create-questpie 2.0.4 → 2.1.0

package/skills/questpie-admin/AGENTS.md

@@ -1,1515 +0,0 @@
-# QUESTPIE Admin Panel
-
-The QUESTPIE admin panel is a **projection of your server schema** — not the framework itself. It reads collections, globals, and config via introspection and generates a full admin interface. Your backend works without it.
-
-## 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                      |
-
-## Full Compiled Document
-
-For the complete admin reference with all topics expanded: `AGENTS.md`
-
-## Tech Stack
-
-- **React** + **Tailwind CSS v4** + **shadcn** components
-- **@base-ui/react** primitives (NOT @radix-ui)
-- **@iconify/react** with Phosphor icon set (`ph:icon-name`)
-- **sonner** for toasts — `toast.error()`, `toast.success()`
-- QUESTPIE Neutral Design: flat surfaces, soft neutral geometry,
-  tokenized radius, and restrained floating shadows
-
-## Setup
-
-### 1. Install
-
-```bash
-bun add @questpie/admin
-```
-
-### 2. Runtime Config
-
-```ts title="questpie.config.ts"
-import { runtimeConfig } from "questpie/app";
-export default runtimeConfig({
-	app: { url: process.env.APP_URL || "http://localhost:3000" },
-	db: { url: process.env.DATABASE_URL },
-	secret: process.env.APP_SECRET,
-});
-```
-
-The admin module contributes the codegen plugin automatically. It discovers `config/admin.ts`, `blocks/`, views, components, and admin client modules.
-
-### 3. Modules
-
-```ts title="modules.ts"
-import { adminModule } from "@questpie/admin/modules/admin";
-import { auditModule } from "@questpie/admin/modules/audit";
-
-export default [adminModule, auditModule] as const;
-```
-
-| Module        | Provides                              |
-| ------------- | ------------------------------------- |
-| `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"
-import { adminConfig } from "#questpie/factories";
-
-export default adminConfig({
-	branding: {
-		name: { en: "My App Admin" },
-	},
-	sidebar: {
-		sections: [
-			{ id: "overview", title: { en: "Overview" } },
-			{ id: "content", title: { en: "Content" } },
-		],
-		items: [
-			{
-				sectionId: "overview",
-				type: "link",
-				label: { en: "Dashboard" },
-				href: "/admin",
-				icon: { type: "icon", props: { name: "ph:house" } },
-			},
-			{
-				sectionId: "content",
-				type: "collection",
-				collection: "posts",
-			},
-		],
-	},
-});
-```
-
-### 5. Codegen
-
-```bash
-bunx questpie generate
-```
-
-### 6. Mount the Admin
-
-```ts title="routes/admin/$.tsx"
-import { AdminRouter } from "@questpie/admin/client";
-import { admin } from "@/questpie/admin/admin";
-
-export default function AdminPage() {
-  return <AdminRouter admin={admin} />;
-}
-```
-
-The admin client config is auto-generated by codegen at `admin/.generated/client.ts`. No manual builder setup needed.
-
-## Branding
-
-```ts title="config/admin.ts"
-import { adminConfig } from "#questpie/factories";
-
-export default adminConfig({
-	branding: {
-		name: { en: "Barbershop Control", sk: "Riadenie barbershopu" },
-	},
-});
-```
-
-| Option | Type             | Description                      |
-| ------ | ---------------- | -------------------------------- |
-| `name` | `string \| i18n` | App name shown in sidebar header |
-| `logo` | `string`         | Logo URL or path                 |
-
-## Theming (CSS Variables)
-
-The admin uses CSS variables for all theming. Override them in your own CSS file.
-
-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"` — UI, prose, headings, labels, navigation        |
-| `--font-mono` | `"JetBrains Mono Variable"` — code, file paths, commands, IDs       |
-
-### Sidebar Variables
-
-Separate tokens for independent sidebar theming: `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-accent`, `--sidebar-border`, `--sidebar-ring`.
-
-### Custom Theme
-
-1. Copy the admin CSS file
-2. Change variable values
-3. Import your copy instead
-4. Zero component changes needed
-
-## Content Localization
-
-When collections have `.localized()` fields, the admin shows a locale switcher:
-
-```ts title="config/app.ts"
-import { appConfig } from "questpie/app";
-export default appConfig({
-	locale: {
-		locales: [
-			{ code: "en", label: { en: "English" }, flagCountryCode: "gb" },
-			{ code: "sk", label: { en: "Slovak" } },
-		],
-		defaultLocale: "en",
-	},
-});
-```
-
-The admin tracks content locale separately from UI locale. Only localized field values change when switching.
-
-## Media & Uploads
-
-```ts
-avatar: f.upload({
-  to: "assets",
-  mimeTypes: ["image/*"],
-  maxSize: 5_000_000,
-}),
-```
-
-The admin renders drag-and-drop upload, image preview, file info, and remove button.
-
-## Live Preview
-
-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.
-
-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
-
-Add `.preview()` to a collection to enable split-screen editing:
-
-```ts title="collections/pages.ts"
-export const pages = collection("pages")
-	.fields(({ f }) => ({
-		title: f.text().required().localized(),
-		slug: f.text().required(),
-		content: f.blocks().localized(),
-	}))
-	.preview({
-		enabled: true,
-		position: "right",
-		defaultWidth: 50,
-		url: ({ record }) => {
-			const slug = record.slug as string;
-			return slug === "home" ? "/?preview=true" : `/${slug}?preview=true`;
-		},
-	});
-```
-
-Preview opens the existing split-screen editor. Patches and refresh/resync messages update the iframe mirror; save/autosave still writes through the form.
-
-### Prepare a Frontend Page
-
-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({ page }) {
-	const router = useRouter();
-	const preview = useCollectionPreview({
-		initialData: page,
-		onRefresh: () => router.invalidate(),
-	});
-
-	return (
-		<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>
-	);
-}
-```
-
-### Key Principles
-
-- 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`
-- `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
-
-Enable `auditModule` for activity timeline. Enable versioning on collections for snapshot restore:
-
-```ts
-export const pages = collection("pages")
-  .fields(({ f }) => ({ ... }))
-  .options({ versioning: true });
-```
-
-## Scope (Multi-Tenancy)
-
-The admin provides scope primitives for multi-tenant applications. Import from `@questpie/admin/client`.
-
-### ScopeProvider
-
-Wraps the admin to enable scope selection. Manages scope ID in React state and persists to localStorage.
-
-```tsx
-import { ScopeProvider } from "@questpie/admin/client";
-
-<ScopeProvider
-	headerName="x-selected-workspace" // HTTP header for scope ID
-	storageKey="admin-workspace" // localStorage key
-	defaultScope={null} // default value
->
-	<AdminLayout>...</AdminLayout>
-</ScopeProvider>;
-```
-
-### ScopePicker
-
-Dropdown for selecting the current scope. Place in sidebar via `slots.afterBrand`:
-
-```tsx
-import { ScopePicker } from "@questpie/admin/client";
-
-<AdminLayout
-	admin={admin}
-	basePath="/admin"
-	slots={{
-		afterBrand: (
-			<div className="px-3 py-2 border-b">
-				<ScopePicker
-					collection="workspaces"
-					labelField="name"
-					allowClear
-					compact
-				/>
-			</div>
-		),
-	}}
-/>;
-```
-
-Three data sources: `collection` (queries a collection), `options` (static array), `loadOptions` (async function).
-
-### useScopedFetch / createScopedFetch
-
-Inject scope header into all API calls:
-
-```tsx
-import { useScopedFetch, createScopedFetch } from "@questpie/admin/client";
-
-// React hook
-const scopedFetch = useScopedFetch();
-const client = useMemo(
-	() => createClient({ baseURL: "/api", fetch: scopedFetch }),
-	[scopedFetch],
-);
-
-// Non-React
-const scopedFetch = createScopedFetch("x-selected-workspace", () =>
-	getScopeId(),
-);
-```
-
-### useScope / useScopeSafe
-
-Access current scope state in any component:
-
-```tsx
-import { useScope, useScopeSafe } from "@questpie/admin/client";
-
-const { scopeId, setScope, clearScope, headerName } = useScope(); // throws outside ScopeProvider
-const scope = useScopeSafe(); // returns null outside ScopeProvider
-```
-
-For the full server-side setup (context resolver, type augmentation, access rules), see the `questpie` skill's `references/multi-tenancy.md`.
-
-## Common Mistakes
-
-1. **CRITICAL: Using `asChild` prop** — QUESTPIE admin uses `@base-ui/react`, which uses the `render` prop. `asChild` is a Radix pattern and does NOT work here.
-
-   ```tsx
-   // WRONG
-   <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
-   // CORRECT
-   <DialogTrigger render={<Button>Open</Button>} />
-   ```
-
-2. **CRITICAL: Importing from `@radix-ui/*`** — use `@base-ui/react` instead.
-
-3. **HIGH: Using `@phosphor-icons/react`** — use `@iconify/react` with `ph:` prefix.
-
-   ```tsx
-   // WRONG
-   import { CaretDown } from "@phosphor-icons/react";
-   // CORRECT
-   import { Icon } from "@iconify/react";
-   <Icon icon="ph:caret-down" width={16} height={16} />;
-   ```
-
-4. **HIGH: Using lucide-react icons** — use `@iconify/react` with Phosphor icon set.
-
-5. **MEDIUM: Custom `<button>` or `<div>` instead of shadcn components** — use `<Button>`, `<Card>`, etc.
-
-6. **MEDIUM: `console.error` for user errors** — use `toast.error()` from `sonner`.
-
----
-
-# QUESTPIE Admin Views
-
-This skill builds on questpie-admin.
-
-Views control how data appears in the QUESTPIE admin panel. They are configured **server-side** on collections and globals, then rendered by the admin client via registries.
-
-```text
-Server Config                     Admin UI
-.list(({ v }) => v.collectionTable({}))   ->  Table with columns, sort, search
-.form(({ v, f }) => v.collectionForm({})) ->  Form with sections, sidebar, tabs
-sidebar({...})                 ->  Navigation sidebar
-dashboard({...})               ->  Dashboard with widgets
-```
-
-## List Views
-
-Configure table views with `.list()` on a collection.
-
-### Basic Table
-
-```ts
-.list(({ v }) => v.collectionTable({}))
-```
-
-Shows all fields as columns with default rendering.
-
-### Custom Columns and Search
-
-```ts
-.list(({ v, f }) =>
-  v.collectionTable({
-    columns: [f.name, f.email, f.isActive, f.createdAt],
-    searchableFields: [f.name, f.email],
-    defaultSort: { field: f.createdAt, direction: "desc" },
-  }),
-)
-```
-
-| Option             | Type                   | Description                    |
-| ------------------ | ---------------------- | ------------------------------ |
-| `columns`          | `Field[]`              | Fields to show as columns      |
-| `searchableFields` | `Field[]`              | Fields included in text search |
-| `defaultSort`      | `{ field, direction }` | Default sort order             |
-
-## Form Views
-
-Configure edit forms with `.form()`.
-
-### Basic Form
-
-```ts
-.form(({ v, f }) => v.collectionForm({}))
-```
-
-Renders all fields in a single column.
-
-### Sections
-
-Group fields into labeled sections with optional grid layout:
-
-```ts
-.form(({ v, f }) =>
-  v.collectionForm({
-    fields: [
-      {
-        type: "section",
-        label: { en: "Contact Information" },
-        layout: "grid",
-        columns: 2,
-        fields: [f.name, f.email, f.phone],
-      },
-      {
-        type: "section",
-        label: { en: "Profile" },
-        fields: [f.bio],
-      },
-    ],
-  }),
-)
-```
-
-| Option        | Type                | Description                          |
-| ------------- | ------------------- | ------------------------------------ |
-| `type`        | `"section"`         | Required                             |
-| `label`       | `string \| i18n`    | Section heading                      |
-| `description` | `string \| i18n`    | Section description                  |
-| `layout`      | `"grid" \| "stack"` | Field layout                         |
-| `columns`     | `number`            | Grid columns (with `layout: "grid"`) |
-| `fields`      | `Field[]`           | Fields in this section               |
-
-### Form Sidebar
-
-Place fields in a right sidebar panel:
-
-```ts
-.form(({ v, f }) =>
-  v.collectionForm({
-    sidebar: {
-      position: "right",
-      fields: [f.isActive, f.avatar, f.status],
-    },
-    fields: [ /* main content sections */ ],
-  }),
-)
-```
-
-### Computed Fields
-
-Auto-compute values from other fields:
-
-```ts
-{
-  field: f.slug,
-  compute: {
-    handler: ({ data }) => {
-      if (data.name && !data.slug?.trim()) {
-        return slugify(data.name);
-      }
-      return undefined;
-    },
-    deps: ({ data }) => [data.name, data.slug],
-    debounce: 300,
-  },
-}
-```
-
-| Option     | Type             | Description              |
-| ---------- | ---------------- | ------------------------ |
-| `handler`  | `(ctx) => value` | Compute function         |
-| `deps`     | `(ctx) => any[]` | Reactive dependencies    |
-| `debounce` | `number`         | Debounce in milliseconds |
-
-### Conditional Visibility
-
-Show or hide fields based on other field values:
-
-```ts
-{
-  field: f.cancellationReason,
-  hidden: ({ data }) => data.status !== "cancelled",
-}
-```
-
-Read-only fields:
-
-```ts
-{
-  field: f.customerName,
-  readOnly: ({ data }) => !!data.customer,
-}
-```
-
-Section-level visibility:
-
-```ts
-{
-  type: "section",
-  label: { en: "SEO" },
-  hidden: ({ data }) => !data.showSeo,
-  fields: [f.metaTitle, f.metaDescription],
-}
-```
-
-## Dashboard
-
-Configure in `config/admin.ts` under the `dashboard` key:
-
-```ts title="config/admin.ts"
-import { adminConfig } from "#questpie/factories";
-
-export default adminConfig({
-	dashboard: {
-		title: { en: "Dashboard" },
-		description: { en: "Overview of your app" },
-		columns: 4,
-		actions: [
-			{
-				id: "new-post",
-				href: "/admin/collections/posts?create=true",
-				label: { en: "New Post" },
-				icon: { type: "icon", props: { name: "ph:plus" } },
-				variant: "primary",
-			},
-		],
-		sections: [
-			{ id: "today", label: { en: "Today" }, layout: "grid", columns: 4 },
-			{ id: "business", label: { en: "Business" }, layout: "grid", columns: 4 },
-		],
-		items: [
-			/* widget items — see widget types below */
-		],
-	},
-});
-```
-
-### Widget Types
-
-**Stats** — count records with optional filter:
-
-```ts
-{
-  sectionId: "today",
-  id: "pending",
-  type: "stats",
-  collection: "appointments",
-  label: { en: "Pending" },
-  filter: { status: "pending" },
-  span: 1,
-}
-```
-
-**Value** — custom-loaded value with trend:
-
-```ts
-{
-  sectionId: "business",
-  id: "revenue",
-  type: "value",
-  span: 2,
-  refreshInterval: 1000 * 60 * 5,
-  loader: async ({ app }) => ({
-    value: 42000,
-    formatted: "42,000 EUR",
-    label: { en: "Monthly Revenue" },
-    trend: { value: "+12%" },
-  }),
-}
-```
-
-**Progress** — progress bar toward a goal:
-
-```ts
-{
-  sectionId: "business",
-  id: "goal",
-  type: "progress",
-  span: 1,
-  showPercentage: true,
-  label: { en: "Monthly Goal" },
-  loader: async ({ app }) => ({ current: 350, target: 500 }),
-}
-```
-
-**Chart** — chart from field values:
-
-```ts
-{
-  sectionId: "business",
-  id: "by-status",
-  type: "chart",
-  collection: "appointments",
-  field: "status",
-  chartType: "pie",
-  label: { en: "By Status" },
-  span: 1,
-}
-```
-
-**Recent Items** — list recent records:
-
-```ts
-{
-  sectionId: "ops",
-  id: "recent",
-  type: "recentItems",
-  collection: "appointments",
-  label: { en: "Recent" },
-  limit: 6,
-  dateField: "scheduledAt",
-  span: 2,
-}
-```
-
-**Timeline** — activity stream:
-
-```ts
-{
-  sectionId: "ops",
-  id: "activity",
-  type: "timeline",
-  label: { en: "Activity" },
-  maxItems: 8,
-  showTimestamps: true,
-  timestampFormat: "relative",
-  loader: async ({ app }) => {
-    const res = await app.collections.appointments.find({
-      limit: 8,
-      orderBy: { updatedAt: "desc" },
-    });
-    return res.docs.map((apt) => ({
-      id: apt.id,
-      title: apt.displayTitle,
-      description: `Status: ${apt.status}`,
-      timestamp: apt.updatedAt,
-      variant: apt.status === "completed" ? "success" : "warning",
-      href: `/admin/collections/appointments/${apt.id}`,
-    }));
-  },
-  span: 2,
-}
-```
-
-## Sidebar
-
-Configure in `config/admin.ts` under the `sidebar` key:
-
-```ts title="config/admin.ts"
-import { adminConfig } from "#questpie/factories";
-
-export default adminConfig({
-	sidebar: {
-		sections: [
-			{ id: "overview", title: { en: "Overview" } },
-			{ id: "content", title: { en: "Content" } },
-			{ id: "external", title: { en: "External" } },
-		],
-		items: [
-			{
-				sectionId: "overview",
-				type: "link",
-				label: { en: "Dashboard" },
-				href: "/admin",
-				icon: { type: "icon", props: { name: "ph:house" } },
-			},
-			{ sectionId: "overview", type: "global", global: "siteSettings" },
-			{ sectionId: "content", type: "collection", collection: "posts" },
-			{
-				sectionId: "external",
-				type: "link",
-				label: { en: "Open Website" },
-				href: "/",
-				external: true,
-				icon: { type: "icon", props: { name: "ph:arrow-square-out" } },
-			},
-		],
-	},
-});
-```
-
-Items appear in definition order within their section.
-
-Modules contribute sidebar items automatically. `adminModule` adds "Administration" with user management. `auditModule` adds an audit log item.
-
-## Filters & Saved Views
-
-Filters are auto-generated from field definitions:
-
-| Field Type          | Filter Operators                         |
-| ------------------- | ---------------------------------------- |
-| `text`              | Contains, equals, starts with, ends with |
-| `number`            | Equals, greater than, less than, between |
-| `boolean`           | Is true, is false                        |
-| `select`            | Is, is not, in                           |
-| `date` / `datetime` | Before, after, between                   |
-| `relation`          | Is (picker)                              |
-
-Users can save filter + sort + column combinations as named views.
-
-## Bulk Actions
-
-List views support multi-select. Check rows, then use the floating toolbar. Built-in: **Delete** (with confirmation). Soft-delete collections soft-delete instead of permanent removal.
-
-## History & Versions
-
-Click the clock icon in the form toolbar. Two tabs:
-
-| Tab          | Shows                                          | Requires                      |
-| ------------ | ---------------------------------------------- | ----------------------------- |
-| **Activity** | Audit log (create, update, delete, transition) | `auditModule`                 |
-| **Versions** | Full document snapshots with restore           | `.versioning()` on collection |
-
-Enable versioning:
-
-```ts
-export const pages = collection("pages")
-  .fields(({ f }) => ({ ... }))
-  .options({ versioning: true });
-```
-
-Disable audit for a specific collection:
-
-```ts
-export const logs = collection("logs")
-  .admin(() => ({ audit: false }))
-  .fields(({ f }) => ({ ... }));
-```
-
-## Common Mistakes
-
-1. **HIGH: Defining columns that don't match field names** — `columns: [f.name]` requires a `name` field in the collection's `.fields()`. Mismatches cause empty columns.
-
-2. **MEDIUM: Not specifying `searchableFields`** — table search bar won't work unless you explicitly list which fields to search.
-
-3. **MEDIUM: Forgetting sidebar section ordering** — items appear in definition order. If you want "Dashboard" at the top, define it first in the `items` array.
-
-4. **MEDIUM: Missing `sectionId` on sidebar items** — every item must reference an existing section ID.
-
-5. **LOW: Not setting `defaultSort`** — records appear in database insertion order which is usually not what users expect.
-
-## Form Views and Live Preview
-
-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
-
-Add `.preview()` to the collection definition:
-
-```ts
-export const pages = collection("pages")
-	.fields(({ f }) => ({
-		title: f.text().required().localized(),
-		slug: f.text().required(),
-		content: f.blocks().localized(),
-	}))
-	.preview({
-		enabled: true,
-		position: "right",
-		defaultWidth: 50,
-		url: ({ record }) => `/${record.slug}?preview=true`,
-	});
-```
-
-### How It Works
-
-1. The form view detects `.preview()` config and opens a split-screen layout
-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.
-
----
-
-# QUESTPIE Blocks
-
-This skill builds on questpie-admin.
-
-Blocks are reusable content components for page builders. Define them server-side with fields and admin metadata, then render them client-side with React components.
-
-```text
-Server: block("hero")           Client: HeroRenderer
-  .fields({ title, image })  ->    Receives { values, data }
-  .admin({ label, icon })         Returns JSX
-  .prefetch({ with: {...} })
-```
-
-## Defining Blocks
-
-Blocks are defined in `blocks/` using the `block()` factory:
-
-```ts title="blocks/hero.ts"
-import { block } from "#questpie/factories";
-
-export const heroBlock = block("hero")
-	.admin(({ c }) => ({
-		label: { en: "Hero Section", sk: "Hero sekcia" },
-		icon: c.icon("ph:image"),
-		category: "sections",
-	}))
-	.fields(({ f }) => ({
-		title: f.text().localized().required(),
-		subtitle: f.textarea().localized(),
-		backgroundImage: f.upload({ to: "assets" }),
-		overlayOpacity: f.number().default(60),
-		alignment: f
-			.select([
-				{ value: "left", label: "Left" },
-				{ value: "center", label: "Center" },
-				{ value: "right", label: "Right" },
-			])
-			.default("center"),
-		ctaText: f.text().localized(),
-		ctaLink: f.text(),
-	}))
-	.prefetch({ with: { backgroundImage: true } });
-```
-
-### Admin Metadata
-
-```ts
-.admin(({ c }) => ({
-  label: { en: "Hero Section" },      // Display name in block picker
-  icon: c.icon("ph:image"),           // Icon in block picker (Phosphor set)
-  category: "sections",               // Group in block picker
-}))
-```
-
-### Multiple Blocks Per File
-
-Export multiple named blocks from one file:
-
-```ts title="blocks/layout.ts"
-import { block } from "#questpie/factories";
-
-export const twoColumnBlock = block("twoColumn")
-	.admin(({ c }) => ({
-		label: { en: "Two Columns" },
-		icon: c.icon("ph:columns"),
-		category: "layout",
-	}))
-	.fields(({ f }) => ({
-		left: f.blocks(),
-		right: f.blocks(),
-	}));
-
-export const spacerBlock = block("spacer")
-	.admin(({ c }) => ({
-		label: { en: "Spacer" },
-		icon: c.icon("ph:arrows-out-line-vertical"),
-		category: "layout",
-	}))
-	.fields(({ f }) => ({
-		height: f
-			.select([
-				{ value: "sm", label: "Small" },
-				{ value: "md", label: "Medium" },
-				{ value: "lg", label: "Large" },
-				{ value: "xl", label: "Extra Large" },
-			])
-			.default("md"),
-	}));
-```
-
-## Using Blocks in Collections
-
-Add a `blocks` field to any collection:
-
-```ts title="collections/pages.ts"
-import { collection } from "#questpie/factories";
-
-export const pages = collection("pages").fields(({ f }) => ({
-	title: f.text().required().localized(),
-	slug: f.text().required(),
-	content: f.blocks().localized(),
-}));
-```
-
-The admin renders a visual block editor for this field.
-
-## Prefetch
-
-Blocks often reference related data (images, linked records). Use `.prefetch()` to load them alongside block values.
-
-### Declarative Prefetch
-
-```ts
-.prefetch({
-  with: {
-    backgroundImage: true,  // Load the full image record
-  },
-})
-```
-
-### Nested Prefetch
-
-```ts
-.prefetch({
-  with: {
-    featuredBarber: {
-      with: {
-        avatar: true,
-        services: true,
-      },
-    },
-  },
-})
-```
-
-### Functional Prefetch
-
-For complex queries, use a function. The `ctx` parameter provides fully typed `collections` and `globals` via `AppContext` augmentation — no imports needed:
-
-```ts title="blocks/featured.ts"
-import { block } from "#questpie/factories";
-
-export const featuredBlock = block("featured")
-	.fields(({ f }) => ({
-		heading: f.text().required(),
-	}))
-	.prefetch(async ({ values, ctx }) => {
-		return {
-			posts: (await ctx.collections.posts.find({ limit: 5 })).docs,
-		};
-	});
-```
-
-### Using Prefetched Data in Renderers
-
-```tsx
-function HeroRenderer({ values, data }: BlockProps<"hero">) {
-	// values.backgroundImage = "asset-id-123" (just the ID)
-	// data.backgroundImage = { url: "/api/assets/...", filename: "hero.jpg", ... }
-
-	return (
-		<section>
-			{data?.backgroundImage?.url && (
-				<img src={data.backgroundImage.url} alt="" />
-			)}
-			<h1>{values.title}</h1>
-		</section>
-	);
-}
-```
-
-## Block Renderers
-
-React components that receive block data and return JSX.
-
-### Defining a Renderer
-
-```tsx title="admin/blocks/hero.tsx"
-import type { BlockProps } from "../.generated/client";
-
-export function HeroRenderer({ values, data }: BlockProps<"hero">) {
-	return (
-		<section
-			className="relative flex items-center justify-center"
-			style={{ minHeight: "60vh" }}
-		>
-			{data?.backgroundImage?.url && (
-				<img
-					src={data.backgroundImage.url}
-					alt=""
-					className="absolute inset-0 w-full h-full object-cover"
-				/>
-			)}
-			<div className="relative text-center">
-				<h1 className="text-5xl font-bold">{values.title}</h1>
-				{values.subtitle && <p className="text-xl mt-4">{values.subtitle}</p>}
-				{values.ctaText && (
-					<a href={values.ctaLink} className="mt-6 inline-block btn">
-						{values.ctaText}
-					</a>
-				)}
-			</div>
-		</section>
-	);
-}
-```
-
-### BlockProps
-
-| Property   | Type        | Description                                        |
-| ---------- | ----------- | -------------------------------------------------- |
-| `values`   | `object`    | Block field values (title, subtitle, etc.)         |
-| `data`     | `object`    | Prefetched relation data (images, related records) |
-| `children` | `ReactNode` | Nested block content                               |
-
-### Registering Renderers
-
-```tsx title="admin/blocks/index.tsx"
-import { HeroRenderer } from "./hero";
-import { GalleryRenderer } from "./gallery";
-import { CTARenderer } from "./cta";
-
-export const renderers = {
-	hero: HeroRenderer,
-	gallery: GalleryRenderer,
-	cta: CTARenderer,
-};
-```
-
-### Frontend Rendering
-
-Use block renderers on the public frontend:
-
-```tsx title="components/page-renderer.tsx"
-import { renderers } from "@/questpie/admin/blocks";
-
-function PageRenderer({ page }) {
-	return (
-		<div>
-			{page.content?.map((block, i) => {
-				const Renderer = renderers[block.type];
-				if (!Renderer) return null;
-				return <Renderer key={i} values={block.values} data={block.data} />;
-			})}
-		</div>
-	);
-}
-```
-
-## Common Mistakes
-
-1. **HIGH: Not using `ctx.collections.*` in functional prefetch** — use the context-injected collections directly. Do NOT import `app` from `#questpie` inside block files (causes circular dependencies).
-
-   ```ts
-   // WRONG — importing app creates circular dependency
-   import { app } from "#questpie";
-   .prefetch(async ({ values, ctx }) => {
-     const posts = await app.collections.posts.find({});
-   })
-
-   // CORRECT — use ctx.collections directly
-   .prefetch(async ({ values, ctx }) => {
-     const posts = await ctx.collections.posts.find({});
-   })
-   ```
-
-2. **HIGH: Importing from `.generated/` inside block files** — block files are imported BY `.generated/index.ts`, so importing from it back creates circular dependencies. Use the `ctx` parameter instead.
-
-3. **MEDIUM: Block renderer not exported as default or named export** — codegen discovers named exports from block renderer files. Ensure the component is exported.
-
-4. **MEDIUM: Using `{ with: { field: true } }` prefetch for complex queries** — declarative prefetch only loads related records by ID. For filtered/sorted/limited queries, use functional prefetch instead.
-
-5. **MEDIUM: Forgetting `.prefetch()` for upload fields** — without prefetch, `values.backgroundImage` is just an ID string. Add `{ with: { backgroundImage: true } }` to get the full asset record with `url`.
-
-6. **LOW: Missing `category` in `.admin()`** — blocks without a category won't be grouped in the block picker, making it harder to find them.
-
-## Blocks in Live Preview
-
-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`.
-
-### Manual BlockScopeProvider Wrapper
-
-Use `BlockScopeProvider` only when you manually render blocks outside `BlockRenderer`:
-
-```tsx
-import { BlockScopeProvider } from "@questpie/admin/client";
-
-function PageRenderer({ blocks, previewData }) {
-	return blocks.map((block) => {
-		const Renderer = renderers[block.type];
-		return (
-			<BlockScopeProvider key={block.id} blockId={block.id}>
-				<Renderer values={block.values} data={block.data} />
-			</BlockScopeProvider>
-		);
-	});
-}
-```
-
-`PreviewField` components inside the provider resolve paths like `content._values.{blockId}.title`.
-
-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.
-
----
-
-# QUESTPIE Custom UI
-
-This skill builds on questpie-admin.
-
-Extend the QUESTPIE admin with custom field types, custom view types, custom components, and reactive field behaviors.
-
-## Registries
-
-Registries connect server-side schema to client-side rendering. When the admin encounters a field type, it looks up the renderer in the field registry.
-
-```text
-Server: f.text().required()
-  |
-Generated: { type: "text", options: {...} }
-  |
-Admin Client: fieldRegistry.get("text")
-  |
-React: <TextFieldRenderer value={...} onChange={...} />
-```
-
-### Built-in Field Registry
-
-```
-text       -> TextInput
-textarea   -> TextareaInput
-richText   -> RichTextEditor (TipTap)
-number     -> NumberInput
-boolean    -> Checkbox / Switch
-date       -> DatePicker
-datetime   -> DateTimePicker
-select     -> SelectDropdown
-relation   -> RelationPicker
-upload     -> FileUpload
-object     -> NestedForm
-array      -> RepeatableItems
-blocks     -> BlockEditor
-json       -> JSONEditor
-```
-
-### Extending Registries
-
-Place files in the admin directory. Codegen discovers them automatically:
-
-```
-questpie/admin/
-  fields/
-    color.tsx        # Custom color field renderer
-    currency.tsx     # Custom currency field renderer
-  views/
-    kanban.tsx       # Custom kanban list view
-```
-
-These are merged with built-in defaults during codegen and exported in `.generated/client.ts`.
-
-## Custom Fields
-
-### Server-Side Registration
-
-Register custom fields through modules:
-
-```ts
-const myModule = module({
-	name: "custom-fields",
-	fields: {
-		color: colorField,
-		currency: currencyField,
-		phone: phoneField,
-	},
-});
-```
-
-Once registered and codegen runs, the field becomes available on the `f` builder:
-
-```ts
-.fields(({ f }) => ({
-  brandColor: f.color().default("#000000"),
-  price: f.currency({ currency: "USD" }),
-}))
-```
-
-### Admin Field Renderer
-
-Create a React component for the field's edit form:
-
-```tsx title="admin/fields/color.tsx"
-import { Icon } from "@iconify/react";
-
-function ColorFieldRenderer({ value, onChange }) {
-	return (
-		<div className="flex items-center gap-2">
-			<input
-				type="color"
-				value={value || "#000000"}
-				onChange={(e) => onChange(e.target.value)}
-				className="w-10 h-10 border border-border cursor-pointer"
-			/>
-			<span className="font-mono text-sm text-muted-foreground">
-				{value || "#000000"}
-			</span>
-		</div>
-	);
-}
-```
-
-### Cell Renderer
-
-For custom table column rendering, provide a `cell` component alongside the field renderer:
-
-```tsx title="admin/fields/color.tsx"
-// Cell component for list view table
-export function ColorCell({ value }) {
-	return (
-		<div className="flex items-center gap-2">
-			<div
-				className="w-4 h-4 border border-border"
-				style={{ backgroundColor: value || "transparent" }}
-			/>
-			<span className="text-xs font-mono">{value}</span>
-		</div>
-	);
-}
-```
-
-## Custom Views
-
-Create view types beyond built-in table and form — kanban boards, calendars, galleries.
-
-### Server-Side Declaration
-
-```ts
-const myModule = module({
-	name: "custom-views",
-	views: {
-		kanban: kanbanViewDefinition,
-		calendar: calendarViewDefinition,
-	},
-});
-```
-
-### Usage in Collections
-
-```ts
-.list(({ v }) => v.kanban({
-  columns: "status",
-  cardTitle: "title",
-}))
-```
-
-### Client Rendering
-
-```tsx title="admin/views/kanban.tsx"
-function KanbanView({ data, columns, onDrop }) {
-	return (
-		<div className="flex gap-4">
-			{columns.map((col) => (
-				<div key={col.id} className="flex-1">
-					<h3 className="font-mono text-sm font-semibold mb-2">{col.label}</h3>
-					{data
-						.filter((item) => item.status === col.id)
-						.map((item) => (
-							<div
-								key={item.id}
-								className="border border-border bg-card p-3 mb-2"
-							>
-								{item.title}
-							</div>
-						))}
-				</div>
-			))}
-		</div>
-	);
-}
-```
-
-## Reactive Field System
-
-Fields support reactive behaviors configured in the collection's `.form()` view or on the field definition itself.
-
-### Conditional Visibility
-
-```ts
-{
-  field: f.cancellationReason,
-  hidden: ({ data }) => data.status !== "cancelled",
-}
-```
-
-### Read-Only
-
-```ts
-{
-  field: f.customerName,
-  readOnly: ({ data }) => !!data.customer,
-}
-```
-
-### Computed Values
-
-```ts
-{
-  field: f.slug,
-  compute: {
-    handler: ({ data }) => {
-      if (data.name && !data.slug?.trim()) {
-        return slugify(data.name);
-      }
-      return undefined;
-    },
-    deps: ({ data }) => [data.name, data.slug],
-    debounce: 300,
-  },
-}
-```
-
-### Dynamic Options (Server-Side)
-
-For select/relation fields with options that depend on other field values:
-
-```ts
-city: f.relation("cities").admin({
-  options: {
-    handler: async ({ data, search, ctx }) => {
-      const cities = await ctx.db.query.cities.findMany({
-        where: { countryId: data.country },
-      });
-      return {
-        options: cities.map((c) => ({ value: c.id, label: c.name })),
-      };
-    },
-    deps: ({ data }) => [data.country],
-  },
-}),
-```
-
-The `handler` runs **server-side** with full access to `ctx.db`, `ctx.user`, `ctx.req`. It re-executes when any value in `deps` changes.
-
-## UI Component Reference
-
-When building custom admin UI, use these patterns:
-
-### Icons
-
-```tsx
-import { Icon } from "@iconify/react";
-
-// Phosphor icon set with ph: prefix
-<Icon icon="ph:house" width={20} height={20} />
-<Icon icon="ph:caret-down-bold" width={16} height={16} />  // bold weight
-<Icon icon="ph:heart-fill" width={16} height={16} />        // fill weight
-```
-
-### Toasts
-
-```tsx
-import { toast } from "sonner";
-
-toast.success("Record saved");
-toast.error("Failed to save");
-```
-
-### Primitives (base-ui)
-
-```tsx
-// CORRECT — render prop
-<DialogTrigger render={<Button>Open</Button>} />
-
-// WRONG — asChild is Radix, not base-ui
-<DialogTrigger asChild><Button>Open</Button></DialogTrigger>
-```
-
-### Responsive Components
-
-- `ResponsivePopover` — Popover on desktop, Drawer on mobile
-- `ResponsiveDialog` — Dialog on desktop, fullscreen Drawer on mobile
-- Hooks: `useIsMobile()`, `useIsDesktop()`, `useMediaQuery()`
-
-## Common Mistakes
-
-1. **HIGH: Not registering custom field in the field registry** — if codegen doesn't discover the field renderer file, the admin will render nothing for that field type. Place it in `questpie/admin/fields/<name>.tsx`.
-
-2. **HIGH: Missing `cell` component for custom fields** — without a cell component, the list view table shows raw values for your custom field instead of a formatted display.
-
-3. **MEDIUM: Reactive field handlers running client-side** — `options.handler`, `compute.handler`, and other reactive handlers run **SERVER-SIDE** with access to `ctx.db`, `ctx.user`. Do not import client-side modules or use browser APIs in them.
-
-4. **MEDIUM: Using `onChange` wrong in field components** — the field renderer receives `onChange` that expects the **value directly**, not a DOM event.
-
-   ```tsx
-   // WRONG
-   onChange={(e) => onChange(e)}
-   // CORRECT
-   onChange={(e) => onChange(e.target.value)}
-   // Or for non-DOM values:
-   onChange={newValue}
-   ```
-
-5. **MEDIUM: Importing from `@radix-ui/*`** — QUESTPIE admin uses `@base-ui/react`. Never import Radix primitives.
-
-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 follows QUESTPIE Neutral Design.
-
----