create-questpie 2.0.2 → 2.0.4

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
 
@@ -29,7 +29,8 @@ For the complete admin reference with all topics expanded: `AGENTS.md`
 - **@base-ui/react** primitives (NOT @radix-ui)
 - **@iconify/react** with Phosphor icon set (`ph:icon-name`)
 - **sonner** for toasts — `toast.error()`, `toast.success()`
-- Brutalist flat design: `--radius: 0px`, no shadows
+- QUESTPIE Neutral Design: flat surfaces, soft neutral geometry,
+  tokenized radius, and restrained floating shadows
 
 ## Setup
 
@@ -42,8 +43,7 @@ bun add @questpie/admin
 ### 2. Runtime Config
 
 ```ts title="questpie.config.ts"
-import { runtimeConfig } from "questpie";
-
+import { runtimeConfig } from "questpie/app";
 export default runtimeConfig({
 	app: { url: process.env.APP_URL || "http://localhost:3000" },
 	db: { url: process.env.DATABASE_URL },
@@ -56,7 +56,8 @@ The admin module contributes the codegen plugin automatically. It discovers `con
 ### 3. Modules
 
 ```ts title="modules.ts"
-import { adminModule, auditModule } from "@questpie/admin/server";
+import { adminModule } from "@questpie/admin/modules/admin";
+import { auditModule } from "@questpie/admin/modules/audit";
 
 export default [adminModule, auditModule] as const;
 ```
@@ -66,6 +67,26 @@ export default [adminModule, auditModule] as const;
 | `adminModule` | User collection, auth pages, admin UI |
 | `auditModule` | Audit log collection, timeline widget |
 
+### Auth/User Contract - Critical
+
+`adminModule` includes the starter auth model and owns the canonical Better Auth `user` collection shape used by admin setup and login guards. That contract includes `user.role` with at least `admin` and `user` values. The built-in setup route checks for `role = "admin"`, and the admin `AuthGuard` expects `session.user.role === "admin"`.
+
+Do not create a replacement `collection("user")` from scratch in an app that uses `adminModule`. If the app needs to customize the user admin UI or add fields, merge the starter user collection and extend it:
+
+```ts title="collections/user.ts"
+import { starterModule } from "questpie/app";
+import { collection } from "#questpie/factories";
+
+export default collection("user")
+	.merge(starterModule.collections.user)
+	.fields(({ f }) => ({
+		// add app-specific user fields here
+		internalNotes: f.textarea(),
+	}));
+```
+
+App-specific authorization tables are fine, but they must not replace or remove the admin user contract unless the app also replaces the built-in admin setup route and auth guard.
+
 ### 4. Admin Config
 
 ```ts title="config/admin.ts"
@@ -138,44 +159,31 @@ export default adminConfig({
 
 The admin uses CSS variables for all theming. Override them in your own CSS file.
 
-### Light Theme (`:root`)
-
-| Variable               | Default   | Purpose                          |
-| ---------------------- | --------- | -------------------------------- |
-| `--background`         | `#FFFFFF` | Page background                  |
-| `--foreground`         | `#0A0A0A` | Primary text                     |
-| `--card`               | `#F8F8F8` | Cards, panels, sidebar           |
-| `--popover`            | `#FFFFFF` | Dropdowns, tooltips, dialogs     |
-| `--muted`              | `#F0F0F0` | Hover states, table headers      |
-| `--muted-foreground`   | `#666666` | Secondary text, placeholders     |
-| `--primary`            | `#B700FF` | Brand accent (CTAs, focus rings) |
-| `--primary-foreground` | `#FFFFFF` | Text on primary backgrounds      |
-| `--destructive`        | `#FF3D57` | Errors, delete actions           |
-| `--success`            | `#00E676` | Positive states                  |
-| `--warning`            | `#FFB300` | Caution states                   |
-| `--info`               | `#40C4FF` | Informational emphasis           |
-| `--border`             | `#E0E0E0` | All structural borders           |
-| `--ring`               | `#B700FF` | Focus ring color                 |
-| `--radius`             | `0px`     | Border radius (0 = brutalist)    |
-
-### Dark Theme (`.dark` class)
-
-Dark mode uses the `.dark` class on the root element. Key overrides:
-
-| Variable       | Dark Value |
-| -------------- | ---------- |
-| `--background` | `#0A0A0A`  |
-| `--foreground` | `#FFFFFF`  |
-| `--card`       | `#111111`  |
-| `--border`     | `#333333`  |
-| `--muted`      | `#1A1A1A`  |
+The full source of truth is `packages/admin/DESIGN.md`. Key defaults:
+
+| Role          | Dark      | Light     |
+| ------------- | --------- | --------- |
+| Background    | `#121212` | `#fafafa` |
+| Foreground    | `#ececec` | `#1c1c1c` |
+| Card          | `#1b1b1b` | `#ffffff` |
+| Surface high  | `#2a2a2a` | `#e8e8e8` |
+| Border        | `#343434` | `#e2e2e2` |
+| Border subtle | `#262626` | `#ebebeb` |
+| Brand primary | `#b700ff` | `#b700ff` |
+
+| Token                    | Default | Use                                         |
+| ------------------------ | ------- | ------------------------------------------- |
+| `--control-radius-inner` | `8px`   | Icon buttons/actions nested inside controls |
+| `--control-radius`       | `12px`  | Inputs, selects, buttons, compact controls  |
+| `--surface-radius`       | `14px`  | Cards, panels, grouped fields, docs blocks  |
+| `--floating-radius`      | `14px`  | Menus, popovers, dialogs, command panels    |
 
 ### Typography
 
 | Variable      | Value                                                               |
 | ------------- | ------------------------------------------------------------------- |
-| `--font-sans` | `"Geist Variable"` — body text, descriptions                        |
-| `--font-mono` | `"JetBrains Mono Variable"` — UI chrome: nav, buttons, tabs, badges |
+| `--font-sans` | `"Geist Variable"` — UI, prose, headings, labels, navigation        |
+| `--font-mono` | `"JetBrains Mono Variable"` — code, file paths, commands, IDs       |
 
 ### Sidebar Variables
 
@@ -193,8 +201,7 @@ Separate tokens for independent sidebar theming: `--sidebar`, `--sidebar-foregro
 When collections have `.localized()` fields, the admin shows a locale switcher:
 
 ```ts title="config/app.ts"
-import { appConfig } from "questpie";
-
+import { appConfig } from "questpie/app";
 export default appConfig({
 	locale: {
 		locales: [
@@ -222,9 +229,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 +255,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 +313,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/custom-ui.md

@@ -302,4 +302,4 @@ toast.error("Failed to save");
 
 6. **MEDIUM: Using `@phosphor-icons/react` or `lucide-react`** — use `@iconify/react` with `ph:` prefix for all icons.
 
-7. **LOW: Not using shadcn components** — prefer `<Button>`, `<Card>`, `<Input>` from the shadcn component library instead of raw HTML elements. The admin has a consistent brutalist design system.
+7. **LOW: Not using shadcn components** — prefer `<Button>`, `<Card>`, `<Input>` from the shadcn component library instead of raw HTML elements. The admin follows QUESTPIE Neutral Design.

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/AGENTS.md

@@ -124,6 +124,12 @@ src/
 - **`questpie.config.ts`** — CLI config (migration directory, app reference).
 - **`src/routes/api/$.ts`** — API catch-all handler. Serves REST + OpenAPI docs at `/api/docs`.
 
+### Admin User Contract
+
+`adminModule` includes the starter auth model and owns the canonical Better Auth `user` collection shape used by admin setup and login guards. That contract includes `user.role` (`admin` or `user`).
+
+Do **not** create a replacement `collection("user")` from scratch. If you need custom user fields or admin layout, merge `starterModule.collections.user` or `adminModule.collections.user` and extend it. Replacing the user collection breaks admin setup/login.
+
 ## How To Write Code
 
 ### Creating a Collection
@@ -160,7 +166,7 @@ export const posts = collection("posts")
 				{ value: "tutorial", label: "Tutorial" },
 			])
 			.label("Category")
-		author: f.relation("users").label("Author"),
+		author: f.relation("user").label("Author"),
 		image: f.upload().label("Cover Image"),
 	}))
 	.title(({ f }) => f.title)
@@ -194,12 +200,12 @@ Then (preferred):
 
 1. Use `bun questpie add collection <name>` to scaffold files
 2. Codegen runs automatically
-3. Run `bun run migrate:create` to generate migration
+3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
 
 Manual workflow (if you create files yourself):
 
 1. Run `bun run questpie:generate` to regenerate `.generated/index.ts`
-2. Run `bun run migrate:create` to generate migration
+2. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
 
 Collections are auto-discovered by codegen — no manual registration needed.
 
@@ -233,12 +239,12 @@ Then (preferred):
 
 1. Use `bun questpie add global <name>` to scaffold files
 2. Codegen runs automatically
-3. Run `bun run migrate:create`
+3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
 
 Manual workflow (if you create files yourself):
 
 1. Run `bun run questpie:generate` to regenerate `.generated/index.ts`
-2. Run `bun run migrate:create`
+2. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
 
 Globals are auto-discovered by codegen — no manual registration needed.
 
@@ -250,7 +256,7 @@ Routes are defined as standalone files in `routes/` and auto-discovered by codeg
 
 ```ts
 // src/questpie/server/routes/get-stats.ts
-import { route } from "questpie";
+import { route } from "questpie/services";
 import { z } from "zod";
 
 export default route()
@@ -384,7 +390,7 @@ If your blocks only use declarative prefetch (`{ with: { field: true } }`), you
 
 Fields support reactive behaviors in `meta.admin`:
 
-- **`hidden`**: Conditionally hide — `({ data }: { data: Record<string, any> }) => !data.isPublished`
+- **`hidden`**: Conditionally hide — `({ data }: { data: Record<string, unknown> }) => !data.isPublished`
 - **`readOnly`**: Make read-only based on conditions
 - **`disabled`**: Disable conditionally
 - **`compute`**: Auto-compute values — `{ handler, deps, debounce }`
@@ -457,7 +463,7 @@ export const {
 
 ```ts
 // src/routes/api/$.ts
-import { createFetchHandler } from "questpie";
+import { createFetchHandler } from "questpie/http";
 import { app } from "#questpie";
 
 const handler = createFetchHandler(app, { basePath: "/api" });
@@ -498,6 +504,7 @@ Optional (with defaults):
 bun dev                     # Start dev server
 bun build                   # Build for production
 bun start                   # Start production server
+bun run db:push             # Push schema to local dev database
 bun run migrate             # Run database migrations
 bun run migrate:create      # Create new migration
 bun run routes:generate     # Regenerate TanStack Router route tree

package/templates/tanstack-start/CLAUDE.md

@@ -15,6 +15,7 @@ This is a [QUESTPIE](https://questpie.com) project scaffolded with `create-quest
 | `bun run questpie:generate`      | Regenerate .generated/index.ts                 |
 | `bun run scaffold:generate`      | Regenerate route tree and QUESTPIE output      |
 | `bun run scaffold:verify`        | Regenerate codegen and type-check              |
+| `bun run db:push`                | Push schema to local dev database              |
 | `bun run migrate:create`         | Generate a migration from schema diff          |
 | `bun run migrate`                | Run pending migrations                         |
 | `bun questpie seed`              | Run pending seeds                              |
@@ -62,6 +63,12 @@ src/questpie/
 - **`questpie.config.ts`** — CLI config (migration directory, app reference).
 - **`src/routes/api/$.ts`** — API catch-all handler. Serves REST + OpenAPI docs at `/api/docs`.
 
+## Admin User Contract
+
+`adminModule` includes the starter auth model and owns the canonical Better Auth `user` collection shape used by admin setup and login guards. That contract includes `user.role` (`admin` or `user`).
+
+Do **not** create a replacement `collection("user")` from scratch. If you need custom user fields or admin layout, merge `starterModule.collections.user` or `adminModule.collections.user` and extend it. Replacing the user collection breaks admin setup/login.
+
 ## Environment Variables
 
 Defined in `src/lib/env.ts` with runtime validation. See `.env.example` for all available variables.
@@ -84,7 +91,7 @@ Preferred workflow:
 
 1. Run `bun questpie add collection my-thing`
 2. The CLI creates the file and auto-runs codegen
-3. Run `bun run migrate:create`
+3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
 
 Manual workflow:
 
@@ -94,7 +101,7 @@ Manual workflow:
    export const myThing = collection("my-thing").fields(({ f }) => ({ ... }));
    ```
 2. Run `bun run questpie:generate` to regenerate `.generated/index.ts`
-3. Run `bun run migrate:create` to generate migration
+3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
 
 Collections are auto-discovered by codegen — no manual registration needed.
 
@@ -104,20 +111,20 @@ Preferred workflow:
 
 1. Run `bun questpie add global my-global`
 2. The CLI creates the file and auto-runs codegen
-3. Run `bun run migrate:create`
+3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
 
 Manual workflow:
 
 1. Create `src/questpie/server/globals/my-global.ts` with a named export
 2. Run `bun run questpie:generate`
-3. Run `bun run migrate:create`
+3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
 
 ### Add a server route (end-to-end type-safe)
 
 1. Create `src/questpie/server/routes/my-function.ts`:
 
    ```ts
-   import { route } from "questpie";
+   import { route } from "questpie/services";
    import { z } from "zod";
 
    export default route()

package/templates/tanstack-start/README.md

@@ -18,8 +18,8 @@ docker compose up -d
 # 2) Regenerate codegen and type-check
 bun run scaffold:verify
 
-# 3) Run migrations
-bun run migrate
+# 3) Create local database tables
+bun run db:push
 
 # 4) Start development server
 bun run dev
@@ -75,6 +75,7 @@ migrations/
 | `bun run routes:generate`        | Regenerate TanStack Router route tree         |
 | `bun run questpie:generate`      | Regenerate `src/questpie/server/.generated/*` |
 | `bun questpie add <type> <name>` | Scaffold entity files (auto-runs codegen)     |
+| `bun run db:push`                | Push schema directly to local dev database    |
 | `bun run migrate`                | Run migrations                                |
 | `bun run migrate:create`         | Create migration                              |
 
@@ -84,14 +85,14 @@ Preferred workflow:
 
 1. Run `bun questpie add collection products`.
 2. The CLI creates the file and runs codegen automatically.
-3. Run `bun run migrate:create`.
+3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
 
 Manual workflow (when you create files by hand):
 
 1. Create a file in `src/questpie/server/collections/`.
 2. Export a collection builder from that file.
 3. Run `bun run questpie:generate`.
-4. Run `bun run migrate:create`.
+4. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
 
 Collections are discovered automatically by codegen. No manual `app.ts` registration is required.
 
@@ -101,13 +102,13 @@ Preferred workflow:
 
 1. Run `bun questpie add global marketing`.
 2. The CLI creates the file and runs codegen automatically.
-3. Run `bun run migrate:create`.
+3. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
 
 Manual workflow (when you create files by hand):
 
 1. Create a file in `src/questpie/server/globals/`.
 2. Export a global builder from that file.
 3. Run `bun run questpie:generate`.
-4. Run `bun run migrate:create`.
+4. Run `bun run db:push` for local development, or `bun run migrate:create` for production migrations.
 
 Globals are discovered automatically by codegen. No manual `app.ts` registration is required.

package/templates/tanstack-start/package.json

@@ -15,6 +15,7 @@
 		"routes:generate": "tsr generate",
 		"questpie:generate": "questpie generate -c src/questpie/server/questpie.config.ts",
 		"scaffold:generate": "bun run routes:generate && bun run questpie:generate",
+		"db:push": "questpie push -c questpie.config.ts",
 		"migrate": "questpie migrate -c questpie.config.ts",
 		"migrate:create": "questpie migrate:create -c questpie.config.ts",
 		"migrate:status": "questpie migrate:status -c questpie.config.ts",

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/questpie/admin/modules.ts

@@ -1 +1,3 @@
-export { default } from "@questpie/admin/client-module";
+import { adminClientModule } from "@questpie/admin/client/modules/admin";
+
+export default [adminClientModule] as const;