create-questpie 2.0.3 → 2.0.4

package/skills/questpie/references/workflows.md

@@ -0,0 +1,155 @@
+---
+name: questpie-core/workflows
+description:
+  QUESTPIE durable workflows long-running business processes replay steps sleep waitForEvent invoke compensation cron admin UI workflow service
+  - questpie-core
+---
+
+# Durable Workflows
+
+Use `@questpie/workflows` when business logic spans multiple steps, waits on time or external events, needs retry-safe side effects, or should survive process restarts.
+
+## Install And Register
+
+```bash
+bun add @questpie/workflows
+```
+
+```ts title="modules.ts"
+import { workflowsModule } from "@questpie/workflows/modules/workflows";
+export default [workflowsModule] as const;
+```
+
+`workflowsModule` carries its codegen plugin. Do not also add `workflowsPlugin()` to `questpie.config.ts` unless you are doing a custom module setup that deliberately omits `workflowsModule`.
+
+Runtime options (route access rule — default admin-only — and execution-lease settings) go in plugin-discovered `config/workflows.ts` using the `workflowsConfig()` factory from `@questpie/workflows/server`.
+
+For admin UI pages/widgets, register the client module:
+
+```ts title="questpie/admin/modules.ts"
+import adminClientModule from "@questpie/admin/client-module";
+import { workflowsClientModule } from "@questpie/workflows/client/modules/workflows";
+export default {
+	name: "app-admin" as const,
+	views: { ...adminClientModule.views, ...workflowsClientModule.views },
+	components: {
+		...adminClientModule.components,
+		...workflowsClientModule.components,
+	},
+	fields: { ...adminClientModule.fields, ...workflowsClientModule.fields },
+	pages: { ...adminClientModule.pages, ...workflowsClientModule.pages },
+	widgets: { ...adminClientModule.widgets, ...workflowsClientModule.widgets },
+	blocks: { ...adminClientModule.blocks, ...workflowsClientModule.blocks },
+};
+```
+
+## Define A Workflow
+
+Put workflow definitions in `workflows/*.ts`:
+
+```ts title="workflows/production-order.ts"
+import { workflow } from "@questpie/workflows";
+import { z } from "zod";
+
+export default workflow({
+	name: "production-order",
+	schema: z.object({
+		orderId: z.string(),
+	}),
+	timeout: "7d",
+	handler: async ({ input, step, ctx, log }) => {
+		const order = await step.run("load-order", async () => {
+			return ctx.collections.productionOrders.findOne({
+				where: { id: input.orderId },
+				with: { toy: true },
+			});
+		});
+		if (!order) throw new Error("Production order not found");
+
+		await step.run("reserve-materials", async () => {
+			await ctx.queue.recalculateMaterialPlan.publish({
+				orderId: input.orderId,
+			});
+		});
+
+		await step.waitForEvent("materials-ready", {
+			event: "materials.available",
+			match: { orderId: input.orderId },
+			timeout: "2d",
+		});
+
+		await step.run("notify-scheduled", async () => {
+			await ctx.email.sendTemplate({
+				template: "productionScheduled",
+				input: { orderId: input.orderId },
+				to: order.ownerEmail,
+			});
+		});
+
+		log.info("Production order workflow completed");
+		return { status: "scheduled" };
+	},
+});
+```
+
+Run codegen after adding workflow files:
+
+```bash
+bun questpie generate
+```
+
+## Trigger And Signal
+
+Use injected `workflows` from route, job, hook, or service context:
+
+```ts title="routes/start-production.ts"
+import { route } from "questpie/services";
+import { z } from "zod";
+
+export default route()
+	.post()
+	.schema(z.object({ orderId: z.string() }))
+	.handler(async ({ input, workflows }) => {
+		const result = await workflows.trigger("production-order", {
+			orderId: input.orderId,
+		});
+		return { instanceId: result.instanceId };
+	});
+```
+
+Signal waiting workflows:
+
+```ts
+await workflows.sendEvent(
+	"materials.available",
+	{ receivedAt: new Date().toISOString() },
+	{ orderId },
+);
+```
+
+## Cron Workflows
+
+Use workflow-level `cron` for recurring long-running processes:
+
+```ts
+export default workflow({
+	name: "nightly-material-plan",
+	schema: z.object({}),
+	cron: { schedule: "0 2 * * *", overlap: "skip" },
+	handler: async ({ step, ctx }) => {
+		await step.run("recalculate", async () => {
+			await ctx.queue.recalculateMaterialPlan.publish({});
+		});
+	},
+});
+```
+
+On Node/Bun workers, `app.queue.listen()` runs workflow jobs and maintenance. On Cloudflare Workers, use `cloudflareQueuesAdapter`, export `createCloudflareWorkerHandlers(app)`, and configure a Cron Trigger for workflow maintenance.
+
+## Rules
+
+- Keep external side effects inside `step.run()` so replay does not repeat them.
+- Use stable step names. Renaming a step changes replay identity.
+- Use idempotency keys when calling external APIs.
+- Use `step.waitForEvent()` for durable waits instead of polling loops.
+- Keep workflow definitions in `workflows/`; do not define them inside route/job files.

package/skills/questpie-admin/AGENTS.md

@@ -20,7 +20,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
 
@@ -33,8 +34,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 },
@@ -47,7 +47,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;
 ```
@@ -57,6 +58,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"
@@ -129,44 +150,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
 
@@ -184,8 +192,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: [
@@ -1503,6 +1510,6 @@ 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/SKILL.md

@@ -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: [

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/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/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;