create-questpie 2.0.2 → 2.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-questpie",
-	"version": "2.0.2",
+	"version": "2.0.3",
 	"description": "Create a new QUESTPIE project",
 	"keywords": [
 		"create",

package/skills/questpie/AGENTS.md

@@ -295,7 +295,7 @@ 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"),
+		status: f.select(["internal", "featured"]).default("internal"),
 		author: f.relation("users"),
 		tags: f.relation("tags").manyToMany({ through: "post_tags" }),
 		cover: f.upload(),
@@ -376,9 +376,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!" } };
 				},
@@ -1238,6 +1238,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
@@ -2012,6 +2014,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 +2034,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!" } };
 			},

package/skills/questpie/SKILL.md

@@ -14,6 +14,7 @@ Server-first TypeScript application framework. Define your data schema once usin
 ## When to Apply
 
 Reference these guidelines when:
+
 - Creating or modifying collections, globals, routes, jobs, services, emails, blocks
 - Working with file conventions or codegen pipeline
 - Configuring adapters (queue, search, storage, realtime, email, KV)
@@ -24,58 +25,120 @@ Reference these guidelines when:
 
 ## Import Paths — Critical
 
-| Factory | Import From | Needs Codegen? |
-|---|---|---|
-| `collection(name)` | `#questpie/factories` | Yes |
-| `global(name)` | `#questpie/factories` | Yes |
-| `block(name)` | `#questpie/factories` | Yes |
-| `adminConfig({...})` | `#questpie/factories` | Yes |
-| `route()` | `"questpie"` | No |
-| `job({...})` | `"questpie"` | No |
-| `service()` | `"questpie"` | No |
-| `email({...})` | `"questpie"` | No |
-| `migration({...})` | `"questpie"` | No |
-| `seed({...})` | `"questpie"` | No |
-| `runtimeConfig({...})` | `"questpie"` | No |
-| `appConfig({...})` | `"questpie"` | No |
-| `authConfig({...})` | `"questpie"` | No |
-| `createClient<AppConfig>()` | `"questpie/client"` | No |
-| `createQuestpieQueryOptions()` | `"@questpie/tanstack-query"` | No |
+| Factory                        | Import From                  | Needs Codegen? |
+| ------------------------------ | ---------------------------- | -------------- |
+| `collection(name)`             | `#questpie/factories`        | Yes            |
+| `global(name)`                 | `#questpie/factories`        | Yes            |
+| `block(name)`                  | `#questpie/factories`        | Yes            |
+| `adminConfig({...})`           | `#questpie/factories`        | Yes            |
+| `route()`                      | `"questpie"`                 | No             |
+| `job({...})`                   | `"questpie"`                 | No             |
+| `service()`                    | `"questpie"`                 | No             |
+| `email({...})`                 | `"questpie"`                 | No             |
+| `migration({...})`             | `"questpie"`                 | No             |
+| `seed({...})`                  | `"questpie"`                 | No             |
+| `runtimeConfig({...})`         | `"questpie"`                 | No             |
+| `appConfig({...})`             | `"questpie"`                 | No             |
+| `authConfig({...})`            | `"questpie"`                 | No             |
+| `createClient<AppConfig>()`    | `"questpie/client"`          | No             |
+| `createQuestpieQueryOptions()` | `"@questpie/tanstack-query"` | No             |
+
+## Module And Plugin Configuration - Critical
+
+Codegen imports `modules.ts` before runtime app creation to extract module-contributed plugins. Any module that contributes a `plugin`, discover patterns, generated factories, categories, views, components, fields, or config factories must be statically discoverable from `modules.ts`.
+
+### DO THIS
+
+Use a static module and a plugin-discovered config file for runtime options:
+
+```ts title="modules.ts"
+import { observabilityModule } from "@questpie/observability/server";
+
+export default [observabilityModule] as const;
+```
+
+```ts title="config/observability.ts"
+import { observabilityConfig } from "@questpie/observability/server";
+
+export default observabilityConfig({
+	serviceName: "barbershop",
+	enabled: process.env.NODE_ENV === "production",
+});
+```
+
+The module reads config at runtime from `app.state.config.observability`:
+
+```ts
+export const observabilityModule = module({
+	name: "questpie-observability",
+	plugin: observabilityPlugin(),
+	services: {
+		observability: service({
+			namespace: null,
+			lifecycle: "singleton",
+			create: ({ app, logger }) =>
+				createObservabilityService(app.state.config?.observability, logger),
+		}),
+	},
+});
+```
+
+### DON'T DO THIS
+
+Do not make runtime options the primary API for codegen-aware modules:
+
+```ts title="modules.ts"
+export default [
+	observabilityModule({
+		serviceName: "barbershop",
+	}),
+] as const;
+```
+
+Do not conditionally hide codegen-aware modules or plugins behind env/runtime checks:
+
+```ts title="modules.ts"
+export default [
+	process.env.OTEL_ENABLED ? observabilityModule : undefined,
+].filter(Boolean);
+```
+
+Factory modules are acceptable only for simple runtime-only modules whose plugin identity and codegen contributions do not change. For reusable packages that ship a `CodegenPlugin`, prefer **static module + `config/*.ts` singleton factory**.
 
 ## Reference Topics
 
 ### Core
 
-| Topic | File | Covers |
-|---|---|---|
-| Quickstart | `references/quickstart.md` | Scaffold, configure, codegen, migrate, serve — zero to running app |
-| Data Modeling | `references/data-modeling.md` | Collections, globals, fields, relations, options, localization |
-| Field Types | `references/field-types.md` | All built-in field types with options and operators |
-| Rules | `references/rules.md` | Access control (row/field level), hooks lifecycle, validation |
-| Business Logic | `references/business-logic.md` | Routes, jobs, services, email templates, context injection |
-| CRUD API | `references/crud-api.md` | Server-side `find`, `create`, `update`, `delete`, globals API |
-| Query Operators | `references/query-operators.md` | `where` clause operators by field type |
+| Topic           | File                            | Covers                                                             |
+| --------------- | ------------------------------- | ------------------------------------------------------------------ |
+| Quickstart      | `references/quickstart.md`      | Scaffold, configure, codegen, migrate, serve — zero to running app |
+| Data Modeling   | `references/data-modeling.md`   | Collections, globals, fields, relations, options, localization     |
+| Field Types     | `references/field-types.md`     | All built-in field types with options and operators                |
+| Rules           | `references/rules.md`           | Access control (row/field level), hooks lifecycle, validation      |
+| Business Logic  | `references/business-logic.md`  | Routes, jobs, services, email templates, context injection         |
+| CRUD API        | `references/crud-api.md`        | Server-side `find`, `create`, `update`, `delete`, globals API      |
+| Query Operators | `references/query-operators.md` | `where` clause operators by field type                             |
 
 ### Infrastructure
 
-| Topic | File | Covers |
-|---|---|---|
-| Production | `references/production.md` | Queue, search, realtime, storage, email, KV adapter setup |
-| Auth | `references/auth.md` | Better Auth integration, session, providers, access patterns |
-| Adapters | `references/infrastructure-adapters.md` | All adapter configs: pg-boss, S3, SMTP, pgNotify, Redis |
+| Topic      | File                                    | Covers                                                       |
+| ---------- | --------------------------------------- | ------------------------------------------------------------ |
+| Production | `references/production.md`              | Queue, search, realtime, storage, email, KV adapter setup    |
+| Auth       | `references/auth.md`                    | Better Auth integration, session, providers, access patterns |
+| Adapters   | `references/infrastructure-adapters.md` | All adapter configs: pg-boss, S3, SMTP, pgNotify, Redis      |
 
 ### Extend
 
-| Topic | File | Covers |
-|---|---|---|
-| Extend | `references/extend.md` | Custom modules, fields, operators, adapters, codegen plugins |
-| Codegen Plugin API | `references/codegen-plugin-api.md` | Plugin architecture, category declarations, templates |
-| Multi-Tenancy | `references/multi-tenancy.md` | Scope isolation, workspace filtering, ScopeProvider |
+| Topic              | File                               | Covers                                                       |
+| ------------------ | ---------------------------------- | ------------------------------------------------------------ |
+| Extend             | `references/extend.md`             | Custom modules, fields, operators, adapters, codegen plugins |
+| Codegen Plugin API | `references/codegen-plugin-api.md` | Plugin architecture, category declarations, templates        |
+| Multi-Tenancy      | `references/multi-tenancy.md`      | Scope isolation, workspace filtering, ScopeProvider          |
 
 ### Client
 
-| Topic | File | Covers |
-|---|---|---|
+| Topic          | File                           | Covers                                                           |
+| -------------- | ------------------------------ | ---------------------------------------------------------------- |
 | TanStack Query | `references/tanstack-query.md` | `q.collections.*`, `q.globals.*`, `q.routes.*`, realtime queries |
 
 ## Key Patterns — Quick Reference
@@ -86,23 +149,23 @@ Reference these guidelines when:
 import { collection } from "#questpie/factories";
 
 export default collection("posts")
-  .fields(({ f }) => ({
-    title: f.text().required(),
-    status: f.select([{ value: "draft", label: "Draft" }]),
-    author: f.relation("users").required(),
-  }))
-  .access({
-    read: true,
-    create: ({ session }) => !!session,
-    update: ({ session, doc }) => doc.authorId === session?.user?.id,
-  })
-  .hooks({
-    beforeChange: async ({ data, operation }) => {
-      if (operation === "create") data.slug = slugify(data.title);
-      return data;
-    },
-  })
-  .options({ versioning: true, timestamps: true });
+	.fields(({ f }) => ({
+		title: f.text().required(),
+		status: f.select([{ value: "draft", label: "Draft" }]),
+		author: f.relation("users").required(),
+	}))
+	.access({
+		read: true,
+		create: ({ session }) => !!session,
+		update: ({ session, doc }) => doc.authorId === session?.user?.id,
+	})
+	.hooks({
+		beforeChange: async ({ data, operation }) => {
+			if (operation === "create") data.slug = slugify(data.title);
+			return data;
+		},
+	})
+	.options({ versioning: true, timestamps: true });
 ```
 
 ### Route
@@ -112,11 +175,11 @@ import { route } from "questpie";
 import z from "zod";
 
 export default route()
-  .post()
-  .schema(z.object({ period: z.enum(["day", "week", "month"]) }))
-  .handler(async ({ input, collections }) => {
-    return collections.posts.find({ where: { status: "published" } });
-  });
+	.post()
+	.schema(z.object({ period: z.enum(["day", "week", "month"]) }))
+	.handler(async ({ input, collections }) => {
+		return collections.posts.find({ where: { status: "published" } });
+	});
 ```
 
 ### Job
@@ -126,13 +189,15 @@ import { job } from "questpie";
 import z from "zod";
 
 export default job({
-  name: "sendReminder",
-  schema: z.object({ userId: z.string() }),
-  retryDelay: 5,  // seconds (not ms!)
-  handler: async ({ payload, email, collections }) => {
-    const user = await collections.users.findOne({ where: { id: payload.userId } });
-    await email.send("reminder", { to: user.email, data: { name: user.name } });
-  },
+	name: "sendReminder",
+	schema: z.object({ userId: z.string() }),
+	retryDelay: 5, // seconds (not ms!)
+	handler: async ({ payload, email, collections }) => {
+		const user = await collections.users.findOne({
+			where: { id: payload.userId },
+		});
+		await email.send("reminder", { to: user.email, data: { name: user.name } });
+	},
 });
 ```
 
@@ -143,14 +208,17 @@ import { createClient } from "questpie/client";
 import type { AppConfig } from "#questpie";
 
 const client = createClient<AppConfig>({
-  baseURL: typeof window !== "undefined" ? window.location.origin : process.env.APP_URL,
-  basePath: "/api",
+	baseURL:
+		typeof window !== "undefined"
+			? window.location.origin
+			: process.env.APP_URL,
+	basePath: "/api",
 });
 
 const { docs } = await client.collections.posts.find({
-  where: { status: "published" },
-  orderBy: { createdAt: "desc" },
-  with: { author: true },
+	where: { status: "published" },
+	orderBy: { createdAt: "desc" },
+	with: { author: true },
 });
 ```
 
@@ -164,17 +232,28 @@ await queue.sendReminder.publish({ userId: "abc" });
 
 ## Common Mistakes
 
-| Severity | Mistake | Fix |
-|---|---|---|
-| CRITICAL | Files in wrong directory | Collections in `collections/`, routes in `routes/`, etc. |
-| CRITICAL | Missing `export default` on convention files | Codegen silently ignores files without default export |
+| Severity | Mistake                                                | Fix                                                                                   |
+| -------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| CRITICAL | Files in wrong directory                               | Collections in `collections/`, routes in `routes/`, etc.                              |
+| CRITICAL | Missing `export default` on convention files           | Codegen silently ignores files without default export                                 |
 | CRITICAL | Importing route/job/service from `#questpie/factories` | Use `"questpie"` — only collection/global/block/adminConfig use `#questpie/factories` |
-| HIGH | Forgetting `questpie generate` after adding files | Re-run codegen on any file add/remove in convention dirs |
-| HIGH | Job handler uses `input` instead of `payload` | Jobs destructure `{ payload }`, routes destructure `{ input }` |
-| HIGH | `queue.send("name", data)` | Use `queue.jobName.publish(data)` |
-| HIGH | `beforeCreate` / `afterCreate` hook names | Use `beforeChange` / `afterChange` with `operation === "create"` guard |
-| MEDIUM | Using npm/yarn instead of Bun | QUESTPIE requires Bun as package manager |
-| MEDIUM | Editing `.generated/` files | Never edit — re-run `questpie generate` |
+| HIGH     | Forgetting `questpie generate` after adding files      | Re-run codegen on any file add/remove in convention dirs                              |
+| HIGH     | Job handler uses `input` instead of `payload`          | Jobs destructure `{ payload }`, routes destructure `{ input }`                        |
+| HIGH     | `queue.send("name", data)`                             | Use `queue.jobName.publish(data)`                                                     |
+| HIGH     | `beforeCreate` / `afterCreate` hook names              | Use `beforeChange` / `afterChange` with `operation === "create"` guard                |
+| HIGH     | Runtime options in codegen-aware modules               | Use static `module({...})` + plugin-discovered `config/*.ts` factory                  |
+| MEDIUM   | Using npm/yarn instead of Bun                          | QUESTPIE requires Bun as package manager                                              |
+| MEDIUM   | Editing `.generated/` files                            | Never edit — re-run `questpie generate`                                               |
+
+## Preview And Workflow Rules
+
+- 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.
+- For publishable pages with workflow enabled, workflow stage is the publication source. Public frontend reads use `stage: "published"`.
+- If public client/HTTP access is enabled, anonymous read access should require `input?.stage === "published"`; editor/preview reads can omit `stage` only when a session is present.
+- Preview/draft-mode reads may load the working stage for authorized editors.
+- Do not add duplicate `isPublished` guidance when workflow already controls publishing.
 
 ## Full Compiled Document
 

package/skills/questpie/references/data-modeling.md

@@ -94,6 +94,10 @@ import { uniqueIndex } from "drizzle-orm/pg-core";
 })
 ```
 
+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.
+
+When workflow is the publication source for pages, public reads use `stage: "published"` and preview/draft-mode reads can load the working stage for authorized editors. Do not add duplicate publication booleans for the same concern.
+
 ### Access Control
 
 ```ts

package/skills/questpie/references/extend.md

@@ -86,6 +86,70 @@ export default runtimeConfig({
 });
 ```
 
+Use direct `runtimeConfig({ plugins })` registration only for standalone codegen plugins or custom setups that do not ship a module. Reusable packages should usually attach the plugin to a static module and let codegen extract it from `modules.ts`.
+
+### Configurable Codegen-Aware Modules
+
+When a package ships a module and a `CodegenPlugin`, keep module identity static and put runtime options in a plugin-discovered config file. Codegen imports `modules.ts` before runtime app creation, so it must be able to see the same module/plugin tree regardless of environment or runtime options.
+
+#### DO THIS
+
+```ts title="modules.ts"
+import { observabilityModule } from "@questpie/observability/server";
+
+export default [observabilityModule] as const;
+```
+
+```ts title="config/observability.ts"
+import { observabilityConfig } from "@questpie/observability/server";
+
+export default observabilityConfig({
+	serviceName: "barbershop",
+	enabled: process.env.NODE_ENV === "production",
+	otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+});
+```
+
+```ts title="@questpie/observability/server.ts"
+export const observabilityModule = module({
+	name: "questpie-observability",
+	plugin: observabilityPlugin(),
+	services: {
+		observability: service({
+			namespace: null,
+			lifecycle: "singleton",
+			create: ({ app, logger }) =>
+				createObservabilityService(app.state.config?.observability, logger),
+		}),
+	},
+});
+```
+
+The plugin contributes `config/observability.ts` as a discover pattern and a typed singleton factory such as `observabilityConfig()`. The service reads the resolved config at runtime from `app.state.config.observability`.
+
+#### DON'T DO THIS
+
+Do not make runtime options the main API for modules that contribute codegen plugins:
+
+```ts title="modules.ts"
+export default [
+	observabilityModule({
+		serviceName: "barbershop",
+		enabled: process.env.NODE_ENV === "production",
+	}),
+] as const;
+```
+
+Do not conditionally include codegen-aware modules or plugins:
+
+```ts title="modules.ts"
+export default [
+	process.env.OTEL_ENABLED ? observabilityModule : undefined,
+].filter(Boolean);
+```
+
+Factory modules are acceptable only for simple runtime-only modules whose plugin identity and generated contributions do not change. If the package contributes discover patterns, generated factories, module categories, views, components, fields, or collection/global extensions, use **static module + `config/*.ts` singleton factory**.
+
 ### Plugin Lifecycle
 
 1. **Discovery** -- codegen scans for files matching category patterns and discover patterns

package/skills/questpie/references/quickstart.md

@@ -494,7 +494,7 @@ bun dev
 
 ## 12. Live Preview (Optional)
 
-Add split-screen live preview to any collection with `.preview()`. The current same-tab flow refreshes the preview iframe after save/autosave and supports field focus over `postMessage`.
+Add split-screen live preview to any collection with `.preview()`. Live Preview uses the existing admin `FormView`, Preview button, `LivePreviewMode`, and iframe. Do not introduce a second default form view or parallel preview API names.
 
 ### Add Preview to a Collection
 
@@ -518,32 +518,47 @@ export default collection("pages")
 
 ### Add Preview Support to the Frontend Page
 
+Frontend checklist:
+
+1. Call `useCollectionPreview({ initialData, onRefresh })`.
+2. Wrap the rendered output in `PreviewProvider`.
+3. Render from `preview.data`, not directly from loader data.
+4. Wrap editable scalar text in `PreviewField`.
+5. Render blocks with `BlockRenderer` when the page uses `f.blocks()`.
+
 ```tsx
 import {
+	BlockRenderer,
 	PreviewField,
 	PreviewProvider,
 	useCollectionPreview,
 } from "@questpie/admin/client";
+import admin from "@/questpie/admin/.generated/client";
 
-function PageView({ initialData }) {
+function PageView({ page }) {
 	const router = useRouter();
 	const preview = useCollectionPreview({
-		initialData,
+		initialData: page,
 		onRefresh: () => router.invalidate(),
 	});
 
 	return (
-		<PreviewProvider
-			isPreviewMode={preview.isPreviewMode}
-			focusedField={preview.focusedField}
-			onFieldClick={preview.handleFieldClick}
-		>
-			<PreviewField field="title" as="h1">
+		<PreviewProvider preview={preview}>
+			<PreviewField field="title" editable="text" as="h1">
 				{preview.data.title}
 			</PreviewField>
+			<BlockRenderer
+				content={preview.data.content}
+				data={preview.data.content?._data}
+				renderers={admin.blocks}
+				selectedBlockId={preview.selectedBlockId}
+				onBlockClick={
+					preview.isPreviewMode ? preview.handleBlockClick : undefined
+				}
+			/>
 		</PreviewProvider>
 	);
 }
 ```
 
-The `"hybrid"` strategy is recommended as the default — it applies field patches instantly via `postMessage` while reconciling derived data (slugs, relations) through the server.
+The form remains authoritative. Save, autosave, Cmd+S, history, workflow, locks, and actions stay in the existing form lifecycle.

package/skills/questpie/references/rules.md

@@ -88,6 +88,49 @@ Access functions receive `AppContext` with these properties:
 | `session`     | Current auth session (null if unauthed) |
 | `db`          | Database instance                       |
 | `collections` | Typed collection API                    |
+| `request`     | Current HTTP `Request` (headers, URL)   |
+
+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 { ApiError } from "questpie";
+import { isAdminRequest } from "@questpie/admin/shared";
+
+type AccessCtx = {
+	request?: Request | null;
+	session?: { user?: unknown | null } | null;
+};
+
+async function canCreatePublicSubmission({ request, session }: AccessCtx) {
+	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
 
@@ -322,6 +365,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-admin/AGENTS.md

@@ -213,9 +213,9 @@ The admin renders drag-and-drop upload, image preview, file info, and remove but
 
 ## Live Preview
 
-Live Preview uses a split-screen iframe. The current implementation refreshes the iframe after save/autosave and uses `postMessage` for field/block focus sync.
+Live Preview is one system: the existing collection `FormView`, Preview button, `LivePreviewMode`, and frontend iframe. Preserve the normal form lifecycle. Do not introduce a separate visual-edit form API, a second default form view, or a parallel preview surface.
 
-Preview V2 patch-based docs are design notes until `useQuestpiePreview`, `PreviewRoot`, and `PreviewBlock` are exported.
+The admin form is authoritative. The iframe mirrors form state through `postMessage`, supports field/block focus, and may request inline scalar edits. Persistence still goes through existing save, autosave, Cmd+S, history, workflow, locks, and actions.
 
 ### Server Config
 
@@ -239,35 +239,57 @@ export const pages = collection("pages")
 	});
 ```
 
-Current preview refreshes the iframe after save/autosave and supports field focus through `postMessage`.
+Preview opens the existing split-screen editor. Patches and refresh/resync messages update the iframe mirror; save/autosave still writes through the form.
 
-### Frontend Integration
+### Prepare a Frontend Page
 
-Use `useCollectionPreview` with `PreviewProvider` and `PreviewField`:
+Use exported APIs only: `useCollectionPreview`, `PreviewProvider`, `PreviewField`, and `BlockRenderer`.
+
+Checklist:
+
+1. Configure `.preview({ url })` on the collection.
+2. Load the same record shape the page normally renders.
+3. For workflow-published pages, public reads use `stage: "published"`; if the public client/HTTP API is exposed, anonymous read access also checks `input?.stage === "published"`. Authorized preview/draft reads can load the working record.
+4. Call `useCollectionPreview({ initialData, onRefresh })` in the page renderer.
+5. Wrap the visual output in `PreviewProvider`.
+6. Render from `preview.data`, not the original loader object.
+7. Wrap editable scalar text with `PreviewField field="..." editable="text" | "textarea"`.
+8. Render block content with `BlockRenderer`; pass `selectedBlockId` and `onBlockClick`.
+9. Keep add/remove/reorder/nesting block operations in the existing block editor.
 
 ```tsx
 import {
+	BlockRenderer,
 	PreviewField,
 	PreviewProvider,
 	useCollectionPreview,
 } from "@questpie/admin/client";
+import admin from "@/questpie/admin/.generated/client";
 
-function PagePreview({ initialData }) {
+function PagePreview({ page }) {
 	const router = useRouter();
 	const preview = useCollectionPreview({
-		initialData,
+		initialData: page,
 		onRefresh: () => router.invalidate(),
 	});
 
 	return (
-		<PreviewProvider
-			isPreviewMode={preview.isPreviewMode}
-			focusedField={preview.focusedField}
-			onFieldClick={preview.handleFieldClick}
-		>
-			<PreviewField field="title" as="h1">
-				{preview.data.title}
-			</PreviewField>
+		<PreviewProvider preview={preview}>
+			<main className={preview.isPreviewMode ? "questpie-preview" : undefined}>
+				<PreviewField field="title" editable="text" as="h1">
+					{preview.data.title}
+				</PreviewField>
+
+				<BlockRenderer
+					content={preview.data.content}
+					data={preview.data.content?._data}
+					renderers={admin.blocks}
+					selectedBlockId={preview.selectedBlockId}
+					onBlockClick={
+						preview.isPreviewMode ? preview.handleBlockClick : undefined
+					}
+				/>
+			</main>
 		</PreviewProvider>
 	);
 }
@@ -275,11 +297,15 @@ function PagePreview({ initialData }) {
 
 ### Key Principles
 
-- Current preview = save/autosave refresh plus field/block focus sync
-- `useCollectionPreview` sends `PREVIEW_READY`, `FIELD_CLICKED`, and `BLOCK_CLICKED`
+- Keep `FormView`, the Preview button, and `LivePreviewMode`
+- Never add a separate visual-edit form API, a second default form view, or parallel preview API names
+- Preserve save/autosave/Cmd+S/history/workflow/locks/actions
+- `useCollectionPreview` handles preview mode, mirrored data, refresh/resync, and focus state
 - `PreviewProvider` supplies preview context to `PreviewField`
-- Each message carries `sessionId`, `seq`, `timestamp`, `protocolVersion`
-- Preview wrappers must prevent accidental navigation in the iframe
+- `PreviewField` annotates scalar fields and can opt into inline editing with `editable`
+- `BlockRenderer` preserves block IDs and block scopes for block annotations
+- Use `BlockScopeProvider` only for custom/manual block rendering outside `BlockRenderer`
+- Validate all iframe messages before updating form state
 
 ## History & Versions
 
@@ -560,7 +586,7 @@ Section-level visibility:
 {
   type: "section",
   label: { en: "SEO" },
-  hidden: ({ data }) => !data.isPublished,
+  hidden: ({ data }) => !data.showSeo,
   fields: [f.metaTitle, f.metaDescription],
 }
 ```
@@ -803,7 +829,7 @@ export const logs = collection("logs")
 
 ## Form Views and Live Preview
 
-Form views connect to the Live Preview V2 system when the collection has `.preview()` configured. The form editor becomes the source of `postMessage` patches — every field change emits a patch through the bus, giving the preview iframe instant updates.
+Form views connect to the existing Live Preview system when the collection has `.preview()` configured. Keep `v.collectionForm()` as the form surface; do not introduce a separate visual-edit form API, a second default form view, or parallel preview API names. The form editor remains the source of patches, refreshes, commits, and resyncs.
 
 ### Enabling Preview on a Collection
 
@@ -827,9 +853,25 @@ export const pages = collection("pages")
 ### How It Works
 
 1. The form view detects `.preview()` config and opens a split-screen layout
-2. Save/autosave sends a `PREVIEW_REFRESH` message to the preview iframe
-3. The preview page handles refreshes through `useCollectionPreview({ initialData, onRefresh })`
-4. `PreviewProvider` and `PreviewField` wire field focus and click-to-focus messages
+2. The preview iframe mirrors form state with snapshot, patch, refresh, commit, and resync messages
+3. Save/autosave/Cmd+S/history/workflow/locks/actions stay in the form lifecycle
+4. The preview page uses `useCollectionPreview({ initialData, onRefresh })`
+5. `PreviewProvider`, `PreviewField`, and `BlockRenderer` wire field and block annotations
+
+### Frontend Preparation Checklist
+
+Use this checklist before expecting visual editing to work:
+
+1. The collection has `.preview({ url })`.
+2. The page loader returns the complete rendered record shape.
+3. Public workflow reads use `stage: "published"`; if public client/HTTP access is enabled, anonymous read access also requires `input?.stage === "published"`. Preview/draft-mode reads load the working record for authorized editors.
+4. The page renderer calls `useCollectionPreview({ initialData, onRefresh })`.
+5. The rendered page is wrapped in `PreviewProvider preview={preview}`.
+6. UI reads from `preview.data`, not directly from loader data.
+7. Scalar text uses `PreviewField field="..." editable="text" | "textarea"` when inline editing is expected.
+8. Blocks render through `BlockRenderer` with `selectedBlockId` and `onBlockClick`.
+9. `BlockScopeProvider` is only needed for custom/manual block rendering outside `BlockRenderer`.
+10. Add/remove/reorder/nesting block operations stay in the existing block editor.
 
 ---
 
@@ -1111,11 +1153,35 @@ function PageRenderer({ page }) {
 
 ## Blocks in Live Preview
 
-When a collection has `.preview()` configured, blocks can participate in preview focus by combining `BlockScopeProvider` with `PreviewField`.
+When a collection has `.preview()` configured, blocks participate in the existing Live Preview system through `BlockRenderer` and `PreviewField`. The form remains authoritative; block annotations only mirror values, focus fields, select blocks, or request inline scalar edits.
+
+### Preferred: BlockRenderer
+
+Use `BlockRenderer` for normal frontend page rendering. It preserves `data-block-id`, routes block selection, and scopes nested `PreviewField` paths automatically.
+
+```tsx
+<BlockRenderer
+	content={preview.data.content}
+	data={preview.data.content?._data}
+	renderers={admin.blocks}
+	selectedBlockId={preview.selectedBlockId}
+	onBlockClick={preview.isPreviewMode ? preview.handleBlockClick : undefined}
+/>
+```
+
+Inside custom block renderers, annotate scalar values with `PreviewField`:
+
+```tsx
+<PreviewField field="title" editable="text" as="h2">
+	{values.title}
+</PreviewField>
+```
+
+This resolves to `content._values.{blockId}.title` when rendered inside `BlockRenderer`.
 
-### BlockScopeProvider Wrapper
+### Manual BlockScopeProvider Wrapper
 
-Use `BlockScopeProvider` in your frontend to scope field paths inside a block:
+Use `BlockScopeProvider` only when you manually render blocks outside `BlockRenderer`:
 
 ```tsx
 import { BlockScopeProvider } from "@questpie/admin/client";
@@ -1134,7 +1200,7 @@ function PageRenderer({ blocks, previewData }) {
 
 `PreviewField` components inside the provider resolve paths like `content._values.{blockId}.title`.
 
-Blocks with declarative prefetch (`{ with: { image: true } }`) resolve relations during reconcile — the preview shows the image URL immediately after the server round-trip completes, not just the asset ID.
+Inline block edits target `_values`, for example `content._values.<blockId>.title`. Tree edits such as add, remove, reorder, and nesting stay in the existing block editor and should trigger refresh or resync when patching is not safe.
 
 ---
 

package/skills/questpie-admin/SKILL.md

@@ -13,11 +13,11 @@ The QUESTPIE admin panel is a **projection of your server schema** — not the f
 
 ## Reference Topics
 
-| Topic | File | Covers |
-|---|---|---|
-| Views | `references/views.md` | List views, form views, dashboard, sidebar, filters, bulk actions, visibility, history |
-| Blocks | `references/blocks.md` | Block definitions, fields, prefetch, renderers, block picker |
-| Custom UI | `references/custom-ui.md` | Custom fields, custom views, registries, reactive fields, widgets |
+| Topic     | File                      | Covers                                                                                 |
+| --------- | ------------------------- | -------------------------------------------------------------------------------------- |
+| Views     | `references/views.md`     | List views, form views, dashboard, sidebar, filters, bulk actions, visibility, history |
+| Blocks    | `references/blocks.md`    | Block definitions, fields, prefetch, renderers, block picker                           |
+| Custom UI | `references/custom-ui.md` | Custom fields, custom views, registries, reactive fields, widgets                      |
 
 ## Full Compiled Document
 
@@ -222,9 +222,9 @@ The admin renders drag-and-drop upload, image preview, file info, and remove but
 
 ## Live Preview
 
-Live Preview uses a split-screen iframe. The current implementation refreshes the iframe after save/autosave and uses `postMessage` for field/block focus sync.
+Live Preview is one system: the existing collection `FormView`, Preview button, `LivePreviewMode`, and frontend iframe. Preserve the normal form lifecycle. Do not introduce a separate visual-edit form API, a second default form view, or a parallel preview surface.
 
-Preview V2 patch-based docs are design notes until `useQuestpiePreview`, `PreviewRoot`, and `PreviewBlock` are exported.
+The admin form is authoritative. The iframe mirrors form state through `postMessage`, supports field/block focus, and may request inline scalar edits. Persistence still goes through existing save, autosave, Cmd+S, history, workflow, locks, and actions.
 
 ### Server Config
 
@@ -248,35 +248,57 @@ export const pages = collection("pages")
 	});
 ```
 
-Current preview refreshes the iframe after save/autosave and supports field focus through `postMessage`.
+Preview opens the existing split-screen editor. Patches and refresh/resync messages update the iframe mirror; save/autosave still writes through the form.
 
-### Frontend Integration
+### Prepare a Frontend Page
 
-Use `useCollectionPreview` with `PreviewProvider` and `PreviewField`:
+Use exported APIs only: `useCollectionPreview`, `PreviewProvider`, `PreviewField`, and `BlockRenderer`.
+
+Checklist:
+
+1. Configure `.preview({ url })` on the collection.
+2. Load the same record shape the page normally renders.
+3. For workflow-published pages, public reads use `stage: "published"`; if the public client/HTTP API is exposed, anonymous read access also checks `input?.stage === "published"`. Authorized preview/draft reads can load the working record.
+4. Call `useCollectionPreview({ initialData, onRefresh })` in the page renderer.
+5. Wrap the visual output in `PreviewProvider`.
+6. Render from `preview.data`, not the original loader object.
+7. Wrap editable scalar text with `PreviewField field="..." editable="text" | "textarea"`.
+8. Render block content with `BlockRenderer`; pass `selectedBlockId` and `onBlockClick`.
+9. Keep add/remove/reorder/nesting block operations in the existing block editor.
 
 ```tsx
 import {
+	BlockRenderer,
 	PreviewField,
 	PreviewProvider,
 	useCollectionPreview,
 } from "@questpie/admin/client";
+import admin from "@/questpie/admin/.generated/client";
 
-function PagePreview({ initialData }) {
+function PagePreview({ page }) {
 	const router = useRouter();
 	const preview = useCollectionPreview({
-		initialData,
+		initialData: page,
 		onRefresh: () => router.invalidate(),
 	});
 
 	return (
-		<PreviewProvider
-			isPreviewMode={preview.isPreviewMode}
-			focusedField={preview.focusedField}
-			onFieldClick={preview.handleFieldClick}
-		>
-			<PreviewField field="title" as="h1">
-				{preview.data.title}
-			</PreviewField>
+		<PreviewProvider preview={preview}>
+			<main className={preview.isPreviewMode ? "questpie-preview" : undefined}>
+				<PreviewField field="title" editable="text" as="h1">
+					{preview.data.title}
+				</PreviewField>
+
+				<BlockRenderer
+					content={preview.data.content}
+					data={preview.data.content?._data}
+					renderers={admin.blocks}
+					selectedBlockId={preview.selectedBlockId}
+					onBlockClick={
+						preview.isPreviewMode ? preview.handleBlockClick : undefined
+					}
+				/>
+			</main>
 		</PreviewProvider>
 	);
 }
@@ -284,11 +306,15 @@ function PagePreview({ initialData }) {
 
 ### Key Principles
 
-- Current preview = save/autosave refresh plus field/block focus sync
-- `useCollectionPreview` sends `PREVIEW_READY`, `FIELD_CLICKED`, and `BLOCK_CLICKED`
+- Keep `FormView`, the Preview button, and `LivePreviewMode`
+- Never add a separate visual-edit form API, a second default form view, or parallel preview API names
+- Preserve save/autosave/Cmd+S/history/workflow/locks/actions
+- `useCollectionPreview` handles preview mode, mirrored data, refresh/resync, and focus state
 - `PreviewProvider` supplies preview context to `PreviewField`
-- Each message carries `sessionId`, `seq`, `timestamp`, `protocolVersion`
-- Preview wrappers must prevent accidental navigation in the iframe
+- `PreviewField` annotates scalar fields and can opt into inline editing with `editable`
+- `BlockRenderer` preserves block IDs and block scopes for block annotations
+- Use `BlockScopeProvider` only for custom/manual block rendering outside `BlockRenderer`
+- Validate all iframe messages before updating form state
 
 ## History & Versions
 

package/skills/questpie-admin/references/blocks.md

@@ -281,11 +281,35 @@ function PageRenderer({ page }) {
 
 ## Blocks in Live Preview
 
-When a collection has `.preview()` configured, blocks can participate in preview focus by combining `BlockScopeProvider` with `PreviewField`.
+When a collection has `.preview()` configured, blocks participate in the existing Live Preview system through `BlockRenderer` and `PreviewField`. The form remains authoritative; block annotations only mirror values, focus fields, select blocks, or request inline scalar edits.
 
-### BlockScopeProvider Wrapper
+### Preferred: BlockRenderer
 
-Use `BlockScopeProvider` in your frontend to scope field paths inside a block:
+Use `BlockRenderer` for normal frontend page rendering. It preserves `data-block-id`, routes block selection, and scopes nested `PreviewField` paths automatically.
+
+```tsx
+<BlockRenderer
+	content={preview.data.content}
+	data={preview.data.content?._data}
+	renderers={admin.blocks}
+	selectedBlockId={preview.selectedBlockId}
+	onBlockClick={preview.isPreviewMode ? preview.handleBlockClick : undefined}
+/>
+```
+
+Inside custom block renderers, annotate scalar values with `PreviewField`:
+
+```tsx
+<PreviewField field="title" editable="text" as="h2">
+	{values.title}
+</PreviewField>
+```
+
+This resolves to `content._values.{blockId}.title` when rendered inside `BlockRenderer`.
+
+### Manual BlockScopeProvider Wrapper
+
+Use `BlockScopeProvider` only when you manually render blocks outside `BlockRenderer`:
 
 ```tsx
 import { BlockScopeProvider } from "@questpie/admin/client";
@@ -304,4 +328,4 @@ function PageRenderer({ blocks, previewData }) {
 
 `PreviewField` components inside the provider resolve paths like `content._values.{blockId}.title`.
 
-Blocks with declarative prefetch (`{ with: { image: true } }`) resolve relations during reconcile — the preview shows the image URL immediately after the server round-trip completes, not just the asset ID.
+Inline block edits target `_values`, for example `content._values.<blockId>.title`. Tree edits such as add, remove, reorder, and nesting stay in the existing block editor and should trigger refresh or resync when patching is not safe.

package/skills/questpie-admin/references/views.md

@@ -161,7 +161,7 @@ Section-level visibility:
 {
   type: "section",
   label: { en: "SEO" },
-  hidden: ({ data }) => !data.isPublished,
+  hidden: ({ data }) => !data.showSeo,
   fields: [f.metaTitle, f.metaDescription],
 }
 ```
@@ -404,7 +404,7 @@ export const logs = collection("logs")
 
 ## Form Views and Live Preview
 
-Form views connect to the Live Preview V2 system when the collection has `.preview()` configured. The form editor becomes the source of `postMessage` patches — every field change emits a patch through the bus, giving the preview iframe instant updates.
+Form views connect to the existing Live Preview system when the collection has `.preview()` configured. Keep `v.collectionForm()` as the form surface; do not introduce a separate visual-edit form API, a second default form view, or parallel preview API names. The form editor remains the source of patches, refreshes, commits, and resyncs.
 
 ### Enabling Preview on a Collection
 
@@ -428,6 +428,22 @@ export const pages = collection("pages")
 ### How It Works
 
 1. The form view detects `.preview()` config and opens a split-screen layout
-2. Save/autosave sends a `PREVIEW_REFRESH` message to the preview iframe
-3. The preview page handles refreshes through `useCollectionPreview({ initialData, onRefresh })`
-4. `PreviewProvider` and `PreviewField` wire field focus and click-to-focus messages
+2. The preview iframe mirrors form state with snapshot, patch, refresh, commit, and resync messages
+3. Save/autosave/Cmd+S/history/workflow/locks/actions stay in the form lifecycle
+4. The preview page uses `useCollectionPreview({ initialData, onRefresh })`
+5. `PreviewProvider`, `PreviewField`, and `BlockRenderer` wire field and block annotations
+
+### Frontend Preparation Checklist
+
+Use this checklist before expecting visual editing to work:
+
+1. The collection has `.preview({ url })`.
+2. The page loader returns the complete rendered record shape.
+3. Public workflow reads use `stage: "published"`; if public client/HTTP access is enabled, anonymous read access also requires `input?.stage === "published"`. Preview/draft-mode reads load the working record for authorized editors.
+4. The page renderer calls `useCollectionPreview({ initialData, onRefresh })`.
+5. The rendered page is wrapped in `PreviewProvider preview={preview}`.
+6. UI reads from `preview.data`, not directly from loader data.
+7. Scalar text uses `PreviewField field="..." editable="text" | "textarea"` when inline editing is expected.
+8. Blocks render through `BlockRenderer` with `selectedBlockId` and `onBlockClick`.
+9. `BlockScopeProvider` is only needed for custom/manual block rendering outside `BlockRenderer`.
+10. Add/remove/reorder/nesting block operations stay in the existing block editor.

package/templates/tanstack-start/src/lib/query-client.ts

@@ -1,9 +1,18 @@
 import { QueryClient } from "@tanstack/react-query";
 
+const ONE_MINUTE = 60 * 1000;
+const FIVE_MINUTES = 5 * ONE_MINUTE;
+
 export const queryClient = new QueryClient({
 	defaultOptions: {
 		queries: {
-			staleTime: 60 * 1000,
+			staleTime: ONE_MINUTE,
+			gcTime: FIVE_MINUTES,
+			refetchOnWindowFocus: false,
+			retry: 1,
+		},
+		mutations: {
+			retry: 0,
 		},
 	},
 });

package/templates/tanstack-start/src/routes/admin/$.tsx

@@ -1,17 +1,28 @@
 import { createFileRoute, useNavigate } from "@tanstack/react-router";
+import { useMemo } from "react";
 
 import { AdminRouter } from "@questpie/admin/client";
 
+function createAdminNavigate(navigate: ReturnType<typeof useNavigate>) {
+	return (path: string) => {
+		void navigate({ to: path });
+	};
+}
+
 function AdminCatchAll() {
 	const navigate = useNavigate();
 	const params = Route.useParams();
 	const splat = params._splat as string;
+	const handleNavigate = useMemo(
+		() => createAdminNavigate(navigate),
+		[navigate],
+	);
 	const segments = splat ? splat.split("/").filter(Boolean) : [];
 
 	return (
 		<AdminRouter
 			segments={segments}
-			navigate={(path) => navigate({ to: path })}
+			navigate={handleNavigate}
 			basePath="/admin"
 		/>
 	);

package/templates/tanstack-start/src/routes/admin/index.tsx

@@ -1,16 +1,23 @@
 import { createFileRoute, useNavigate } from "@tanstack/react-router";
+import { useMemo } from "react";
 
 import { AdminRouter } from "@questpie/admin/client";
 
+function createAdminNavigate(navigate: ReturnType<typeof useNavigate>) {
+	return (path: string) => {
+		void navigate({ to: path });
+	};
+}
+
 function AdminDashboard() {
 	const navigate = useNavigate();
+	const handleNavigate = useMemo(
+		() => createAdminNavigate(navigate),
+		[navigate],
+	);
 
 	return (
-		<AdminRouter
-			segments={[]}
-			navigate={(path) => navigate({ to: path })}
-			basePath="/admin"
-		/>
+		<AdminRouter segments={[]} navigate={handleNavigate} basePath="/admin" />
 	);
 }