includio-cms 0.14.0 → 0.14.2

package/DOCS.md

@@ -0,0 +1,4540 @@
+# Includio CMS Documentation (v0.14.2)
+
+> This file is auto-generated from the docs site. For the latest version, update the package.
+
+# Includio CMS
+
+A headless CMS built for SvelteKit. Type-safe, extensible, with a modern admin interface.
+
+> **Beta:** Includio is in active development. Some APIs may change between versions.
+
+## Features
+
+- **Type-safe Configuration** — Define content schemas with full TypeScript support and IDE autocompletion.
+- **Built for SvelteKit** — First-class integration with SvelteKit's architecture, hooks, and routing.
+- **19 Field Types** — Text, structured content, media, relations, blocks, SEO, and more out of the box.
+- **Content Versioning** — Draft, published, and scheduled states for every entry.
+- **Media Management** — Upload, organize with tags, transform images with Sharp, transcode videos with ffmpeg.
+- **Pluggable Adapters** — Swap database, file storage, email, and AI providers independently.
+- **Multi-language** — Per-field localization with any number of languages.
+- **Plugins & Hooks** — Lifecycle hooks for extending CMS behavior (webhooks, logging, etc).
+
+## Quick Start
+
+```bash
+pnpm add includio-cms
+```
+
+```typescript
+import { defineConfig } from 'includio-cms/sveltekit';
+import { pg } from 'includio-cms/db-postgres';
+import { local } from 'includio-cms/files-local';
+import { nodemailerAdapter } from 'includio-cms/email-nodemailer';
+
+export default defineConfig({
+  languages: ['en'],
+  db: pg({ databaseUrl: process.env.DATABASE_URL }),
+  files: local(),
+  email: nodemailerAdapter({
+    defaultFromAddress: 'noreply@example.com',
+    defaultFromName: 'My Site',
+    transportOptions: { host: 'smtp.example.com', port: 587, auth: { user: 'user', pass: 'pass' } }
+  }),
+  collections: [/* ... */],
+  singles: [/* ... */],
+});
+```
+
+See [Getting Started](/docs/getting-started) for full installation instructions.
+
+
+---
+
+# Getting Started
+
+> **Prerequisites:** You need Node.js 18+, a SvelteKit project, and a PostgreSQL database before continuing.
+
+## 1. Install
+
+```bash
+pnpm add includio-cms
+```
+
+## 2. Create CMS Config
+
+Create `src/cms/cms.config.ts`:
+
+```typescript
+import { defineConfig } from 'includio-cms/sveltekit';
+import { pg } from 'includio-cms/db-postgres';
+import { local } from 'includio-cms/files-local';
+import { nodemailerAdapter } from 'includio-cms/email-nodemailer';
+
+export default defineConfig({
+  languages: ['en'],
+  db: pg({
+    databaseUrl: process.env.DATABASE_URL
+  }),
+  files: local(),
+  email: nodemailerAdapter({
+    defaultFromAddress: process.env.SMTP_FROM,
+    defaultFromName: 'My Site',
+    transportOptions: {
+      host: process.env.SMTP_HOST,
+      port: 587,
+      auth: {
+        user: process.env.SMTP_USER,
+        pass: process.env.SMTP_PASS
+      }
+    }
+  }),
+  collections: [],
+  singles: [],
+  forms: [],
+  plugins: []
+});
+```
+
+## 3. Initialize in hooks.server.ts
+
+Add to `src/hooks.server.ts`:
+
+```typescript
+import { includioCMS } from 'includio-cms/sveltekit/server';
+import { sequence } from '@sveltejs/kit/hooks';
+import config from '$cms/cms.config';
+
+export const handle = sequence(...includioCMS(config));
+```
+
+This initializes the CMS, sets up authentication, admin route protection, security headers, and code generation. It runs once on server startup.
+
+> **SvelteKit Alias:** The `$cms` alias maps to `src/cms` — configured via `kit.alias` in `svelte.config.js`.
+
+## 4. Add Layout Load
+
+Create `src/routes/+layout.server.ts` to pass CMS context (e.g. Safari video preference) to the frontend:
+
+```typescript
+import { cmsLayoutLoad } from 'includio-cms/sveltekit/server';
+
+export function load(event) {
+  return cmsLayoutLoad(event);
+}
+```
+
+Then wrap your root layout with `CmsProvider`:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<CmsProvider {data}>
+  {@render children()}
+</CmsProvider>
+```
+
+## 5. Add Admin Routes
+
+The admin panel mounts at `/admin`. Import the admin layout and pages from `includio-cms/admin`.
+
+## 6. Run Migrations
+
+```bash
+pnpm db:push
+```
+
+This creates all required database tables (entries, versions, media, forms, etc).
+
+## 7. Create First User
+
+```bash
+pnpm create:user
+```
+
+Follow the prompts to create an admin user with email and password.
+
+## Next Steps
+
+- [Configuration](/docs/getting-started/configuration) — Full config reference
+- [Collections](/docs/collections) — Define repeatable content types
+- [Singles](/docs/singles) — One-off content like homepage settings
+- [Fields](/docs/fields) — All 19 field types
+- [Frontend Rendering](/docs/frontend) — Components for SvelteKit
+- [Migration Guide](/docs/migration) — Version upgrade guide
+
+
+---
+
+# Configuration
+
+The CMS is configured using `defineConfig` from `includio-cms/sveltekit`.
+
+## CMSConfig Interface
+
+```typescript
+interface CMSConfig {
+  languages: Language[];
+  collections?: CollectionConfig[];
+  singles?: SingleConfig[];
+  forms?: FormConfig[];
+  db: DatabaseAdapter;
+  files: FilesAdapter;
+  email?: EmailAdapter;
+  auth?: AuthConfig;
+  plugins?: PluginConfig[];
+  ai?: AIAdapter;
+  media?: MediaConfig;
+  apiKeys?: ApiKeyConfig[];
+  typography?: TypographyConfig;
+}
+```
+
+## Options
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `languages` | `Language[]` | Yes | Language codes. First is default. |
+| `collections` | `CollectionConfig[]` | No | Repeatable content types |
+| `singles` | `SingleConfig[]` | No | One-off content types |
+| `forms` | `FormConfig[]` | No | Form submission handlers |
+| `db` | `DatabaseAdapter` | Yes | Database adapter instance |
+| `files` | `FilesAdapter` | Yes | File storage adapter instance |
+| `email` | `EmailAdapter` | No | Email sending adapter (for notifications, password reset) |
+| `auth` | `AuthConfig` | No | Authentication configuration |
+| `plugins` | `PluginConfig[]` | No | Lifecycle hook plugins |
+| `ai` | `AIAdapter` | No | AI provider (alt text generation) |
+| `media` | `MediaConfig` | No | Media upload constraints |
+| `apiKeys` | `ApiKeyConfig[]` | No | API keys for REST API access |
+| `typography` | `TypographyConfig` | No | Typography settings |
+
+## Languages
+
+Define supported languages as an array of ISO codes. The first language is the default.
+
+```typescript
+defineConfig({
+  languages: ['en', 'pl', 'de'],
+  // ...
+});
+```
+
+Fields with `localized: true` will store separate values per language.
+
+## Auth
+
+```typescript
+interface AuthConfig {
+  secret: string;   // Session secret
+  baseURL?: string;  // Base URL for auth callbacks
+}
+```
+
+```typescript
+defineConfig({
+  auth: {
+    secret: process.env.AUTH_SECRET
+  },
+  // ...
+});
+```
+
+## API Keys
+
+Enable REST API access with API keys:
+
+```typescript
+interface ApiKeyConfig {
+  key: string;
+  name?: string;
+  role?: 'admin' | 'editor';
+}
+```
+
+```typescript
+defineConfig({
+  apiKeys: [
+    { key: process.env.API_KEY, name: 'Frontend', role: 'editor' }
+  ],
+  // ...
+});
+```
+
+See [API Reference](/docs/api) for REST API endpoints.
+
+## Media Config
+
+```typescript
+interface MediaConfig {
+  maxOriginalWidth?: number;
+  maxOriginalHeight?: number;
+  video?: VideoTranscodeConfig;
+}
+
+interface VideoTranscodeConfig {
+  transcode?: boolean;            // default: true
+  formats?: ('mp4' | 'webm')[];  // default: ['mp4', 'webm']
+  maxResolution?: number;         // default: 1080 (px, longest side)
+  crf?: { mp4?: number; webm?: number }; // default: mp4=23, webm=30
+  concurrency?: number;           // default: 1 (parallel jobs)
+}
+```
+
+Example with video transcoding:
+
+```typescript
+defineConfig({
+  media: {
+    maxOriginalWidth: 4096,
+    video: {
+      transcode: true,
+      formats: ['mp4', 'webm'],
+      maxResolution: 1080,
+      crf: { mp4: 23, webm: 30 }
+    }
+  }
+});
+```
+
+See [Video Transcoding](/docs/video-transcoding) for full details.
+
+## Typography
+
+```typescript
+interface TypographyConfig {
+  fixOrphans?: boolean; // default: true — prevents widow words
+}
+```
+
+## Adapters
+
+### Database
+
+```typescript
+import { pg } from 'includio-cms/db-postgres';
+
+db: pg({
+  databaseUrl: 'postgres://user:pass@localhost:5432/mydb'
+})
+```
+
+See [Database Adapter](/docs/adapters/database) for the full interface.
+
+### File Storage
+
+```typescript
+import { local } from 'includio-cms/files-local';
+
+files: local()
+```
+
+See [Files Adapter](/docs/adapters/files) for the full interface.
+
+### Email
+
+```typescript
+import { nodemailerAdapter } from 'includio-cms/email-nodemailer';
+
+email: nodemailerAdapter({
+  defaultFromAddress: 'noreply@example.com',
+  defaultFromName: 'My Site',
+  transportOptions: {
+    host: 'smtp.example.com',
+    port: 587,
+    auth: { user: 'user', pass: 'pass' }
+  }
+})
+```
+
+See [Email Adapter](/docs/adapters/email) for the full interface.
+
+### AI (Optional)
+
+```typescript
+import { claudeAdapter } from 'includio-cms/ai-claude';
+// or
+import { openAIAdapter } from 'includio-cms/ai-openai';
+
+ai: claudeAdapter({
+  apiKey: process.env.ANTHROPIC_API_KEY
+})
+```
+
+Currently supports automatic alt text generation for uploaded images.
+
+## Helper Functions
+
+| Function | Purpose |
+|----------|---------|
+| `defineConfig` | Type-safe CMS configuration |
+| `defineCollection` | Type-safe collection definition |
+| `defineSingle` | Type-safe single definition |
+| `defineForm` | Type-safe form definition |
+| `defineObject` | Type-safe object field shorthand |
+
+> **Environment Variables:** Use `process.env` for secrets like database URLs, API keys, and SMTP credentials. Never hardcode them in your config file.
+
+
+---
+
+# Layout
+
+Customize how fields are arranged in the admin editor. Layouts apply to both collections and singles via the `layout` property.
+
+## Presets
+
+Quick layout presets for common patterns:
+
+```typescript
+defineCollection({
+  slug: 'posts',
+  layout: 'sidebar-right',
+  // ...
+});
+```
+
+| Preset | Description |
+|--------|-------------|
+| `'sidebar-right'` | Main fields left, metadata sidebar right |
+| `'two-column'` | Balanced two-column layout |
+
+### Preset with Options
+
+```typescript
+// Specify which fields go in the sidebar
+layout: { preset: 'sidebar-right', sidebar: ['seo', 'category', 'publishedAt'] }
+
+// Specify which fields go in the left column
+layout: { preset: 'two-column', left: ['title', 'content'] }
+```
+
+## Custom Layout
+
+For full control, define an array of layout nodes:
+
+```typescript
+defineCollection({
+  slug: 'page',
+  layout: [
+    {
+      type: 'columns',
+      ratio: '2fr 1fr',
+      children: [
+        {
+          type: 'stack',
+          fields: ['title', 'content', 'blocks']
+        },
+        {
+          type: 'stack',
+          children: [
+            {
+              type: 'card',
+              label: 'SEO',
+              fields: ['seo']
+            },
+            {
+              type: 'card',
+              label: 'Settings',
+              fields: ['category', 'publishedAt', 'featured']
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  fields: [/* ... */]
+});
+```
+
+## Node Types
+
+### Section
+
+Labeled grouping with optional icon:
+
+```typescript
+{
+  type: 'section',
+  label: { en: 'Hero', pl: 'Baner' },
+  icon: 'photo',
+  fields: ['heroTitle', 'heroSubtitle', 'heroImage']
+}
+```
+
+### Columns
+
+Grid layout with configurable column ratios:
+
+```typescript
+{
+  type: 'columns',
+  ratio: '2fr 1fr',
+  children: [/* layout nodes */]
+}
+```
+
+Available ratios: `'1fr 1fr'`, `'2fr 1fr'`, `'1fr 2fr'`, `'3fr 1fr'`, `'1fr 3fr'`, `'1fr 1fr 1fr'`
+
+### Card
+
+Bordered card with label, optional auto-grid:
+
+```typescript
+{
+  type: 'card',
+  label: 'Contact Info',
+  autoGrid: true,
+  fields: ['email', 'phone', 'address']
+}
+```
+
+### Accordion
+
+Collapsible section:
+
+```typescript
+{
+  type: 'accordion',
+  label: 'Advanced Settings',
+  defaultOpen: false,
+  fields: ['customCode', 'tracking']
+}
+```
+
+### Stack
+
+Simple vertical stacking (no visual container):
+
+```typescript
+{
+  type: 'stack',
+  fields: ['title', 'content']
+}
+```
+
+## Node Properties
+
+All nodes share:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | `string` | Node type |
+| `label` | `Localized` | Display label (required for section, card, accordion) |
+| `icon` | `string` | Optional icon |
+| `fields` | `string[]` | Field slugs to render in this node |
+| `children` | `LayoutNode[]` | Nested layout nodes |
+
+A node can have `fields`, `children`, or both.
+
+## Dot-Notation for Object Fields
+
+Reference nested object fields using dot-notation:
+
+```typescript
+{
+  type: 'card',
+  label: 'Company',
+  fields: ['companyInfo.name', 'companyInfo.motto', 'companyInfo.contact.email']
+}
+```
+
+This extracts specific fields from object types and places them in the layout, regardless of the object's nesting level.
+
+> **Combining Layouts and Fields:** Fields not referenced in any layout node are rendered at the bottom in their original order. You don't need to include every field in the layout — only the ones you want to position specifically.
+
+
+---
+
+# Collections
+
+Collections are repeatable content types. Each collection can have multiple entries (e.g., blog posts, products, team members).
+
+## Defining a Collection
+
+```typescript
+import { defineCollection } from 'includio-cms/sveltekit';
+
+const posts = defineCollection({
+  slug: 'posts',
+  labels: {
+    singular: { en: 'Post', pl: 'Wpis' },
+    plural: { en: 'Posts', pl: 'Wpisy' }
+  },
+  entryAdminTitle: 'title',
+  fields: [
+    { type: 'text', slug: 'title', required: true },
+    { type: 'slug', slug: 'slug' },
+    { type: 'content', slug: 'content' },
+    { type: 'media', slug: 'cover', accept: 'image/*', styles: [
+      { name: 'thumbnail', width: 400, height: 300, crop: true },
+      { name: 'hero', width: 1200, height: 630, crop: true }
+    ]},
+    { type: 'relation', slug: 'author', collection: 'team', displayField: 'name' },
+    { type: 'select', slug: 'category', options: [
+      { label: 'Tech', value: 'tech' },
+      { label: 'Design', value: 'design' }
+    ]},
+    { type: 'date', slug: 'publishedAt' },
+    { type: 'seo', slug: 'seo' }
+  ]
+});
+```
+
+## Configuration
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `slug` | `string` | Yes | Unique identifier for the collection |
+| `fields` | `Field[]` | Yes | Array of field definitions |
+| `labels` | `{ singular?: Localized; plural?: Localized }` | No | Display labels in admin |
+| `entryAdminTitle` | `string` | No | Field slug used as entry title in admin list |
+| `sidebarIcon` | `IconName` | No | Icon for the admin sidebar |
+| `previewUrl` | `string` | No | URL pattern for previewing entries |
+| `orderable` | `boolean` | No | Enable manual drag-and-drop ordering |
+| `listColumns` | `string[]` | No | Field slugs to display as columns in admin list |
+| `layout` | `Layout` | No | Admin editor [layout](/docs/getting-started/layout) |
+| `slugField` | `string` | No | Dot-path to slug field (default: `'seo.slug'`) |
+| `pathTemplate` | `string` | No | URL path template, e.g. `'blog/{slug}'` |
+
+> **entryAdminTitle:** Set `entryAdminTitle` to a text field slug (like `'title'`) so entries show meaningful names in the admin list instead of IDs.
+
+## Usage in Config
+
+```typescript
+export default defineConfig({
+  collections: [posts, products, team],
+  // ...
+});
+```
+
+## Querying Entries
+
+```typescript
+import { getEntries } from 'includio-cms/admin/remote';
+
+// All published posts
+const posts = await getEntries({
+  slug: 'posts',
+  status: 'published',
+  language: 'en'
+});
+
+// Filter by field values
+const techPosts = await getEntries({
+  slug: 'posts',
+  status: 'published',
+  dataValues: { category: 'tech' }
+});
+
+// Search by field content
+const results = await getEntries({
+  slug: 'posts',
+  dataLike: { title: 'svelte' }
+});
+```
+
+> **Slug Uniqueness:** Collection slugs must be unique across all collections and singles. The slug is used as the database identifier for entries.
+
+
+---
+
+# Singles
+
+Singles are one-off content types. Unlike collections, a single has exactly one entry (e.g., homepage settings, site configuration, about page).
+
+## Defining a Single
+
+```typescript
+import { defineSingle } from 'includio-cms/sveltekit';
+
+const homepage = defineSingle({
+  slug: 'homepage',
+  label: { en: 'Homepage', pl: 'Strona główna' },
+  fields: [
+    { type: 'text', slug: 'heroTitle', required: true, label: 'Hero Title' },
+    { type: 'text', slug: 'heroSubtitle', multiline: true },
+    { type: 'media', slug: 'heroImage', accept: 'image/*', styles: [
+      { name: 'desktop', width: 1920, height: 800, crop: true },
+      { name: 'mobile', width: 768, height: 600, crop: true }
+    ]},
+    { type: 'blocks', slug: 'features', of: [
+      { type: 'object', slug: 'feature', fields: [
+        { type: 'text', slug: 'title', required: true },
+        { type: 'text', slug: 'description', multiline: true },
+        { type: 'media', slug: 'icon', accept: 'image/*' }
+      ]}
+    ]}
+  ]
+});
+```
+
+## Configuration
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `slug` | `string` | Yes | Unique identifier |
+| `fields` | `Field[]` | Yes | Array of field definitions |
+| `label` | `Localized` | No | Display label in admin |
+| `sidebarIcon` | `IconName` | No | Icon for admin sidebar |
+| `previewUrl` | `string` | No | URL for previewing |
+| `layout` | `Layout` | No | Admin editor [layout](/docs/getting-started/layout) |
+| `slugField` | `string` | No | Dot-path to slug field (default: `'seo.slug'`) |
+| `pathTemplate` | `string` | No | URL path template, e.g. `'about'` |
+
+> **Auto-creation:** When you open a single in the admin panel, its entry is automatically created if it doesn't exist yet. No manual creation needed.
+
+## Behavior
+
+- Singles always have exactly one entry
+- They support the same versioning as collections (draft/published/scheduled)
+- The admin shows a single editor view instead of a list
+
+## Usage in Config
+
+```typescript
+export default defineConfig({
+  singles: [homepage, siteSettings, aboutPage, footer],
+  // ...
+});
+```
+
+## Querying
+
+```typescript
+import { getEntry } from 'includio-cms/admin/remote';
+
+const homepage = await getEntry({
+  slug: 'homepage',
+  status: 'published',
+  language: 'en'
+});
+```
+
+
+---
+
+# Fields
+
+Fields define the schema of your content. Includio provides 19 field types (18 built-in + custom) covering common content modeling needs.
+
+## Common Properties
+
+All fields share these base properties:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | `FieldType` | Yes | The field type identifier |
+| `slug` | `string` | Yes | Unique field identifier within the parent |
+| `label` | `Localized` | No | Display label in admin UI |
+| `required` | `boolean` | No | Whether the field must have a value |
+| `description` | `Localized` | No | Help text shown below the field |
+| `defaultValue` | `any` | No | Default value for new entries |
+| `localized` | `boolean` | No | Enable per-language values |
+| `showWhen` | `FieldCondition` | No | Conditionally show/hide this field |
+
+### Conditional Fields (`showWhen`)
+
+Show or hide a field based on the value of a sibling field:
+
+```typescript
+{
+  type: 'text',
+  slug: 'customUrl',
+  label: 'Custom URL',
+  showWhen: { field: 'linkType', equals: 'custom' }
+}
+```
+
+```typescript
+interface FieldCondition {
+  field: string;                    // slug of a sibling field
+  equals?: string | string[];      // show when value matches
+  notEquals?: string | string[];   // show when value does NOT match
+}
+```
+
+> **Localized Fields:** When `localized: true`, the admin shows separate inputs for each configured language. The stored data is keyed by language code.
+
+> **Required Fields:** Fields with `required: true` display a red asterisk (*) next to their label. Validation messages are shown in Polish and summarized in toast notifications.
+
+## Available Types
+
+| Type | Description | Output |
+|------|-------------|--------|
+| [Text](/docs/fields/text) | Single/multiline text | `string` |
+| [Content](/docs/fields/content) | Structured rich text editor | `StructuredContentDoc` |
+| [Number](/docs/fields/number) | Numeric input | `number` |
+| [Boolean](/docs/fields/boolean) | Toggle switch | `boolean` |
+| [Date](/docs/fields/date) | Date picker | `string` (ISO) |
+| [DateTime](/docs/fields/datetime) | Date + time picker | `string` (ISO) |
+| [File](/docs/fields/file) | File upload | `string \| string[]` |
+| [Media](/docs/fields/media-field) | Image/video upload + styles | `MediaFieldData` |
+| [Select](/docs/fields/select) | Dropdown select | `string \| string[]` |
+| [Radio](/docs/fields/radio) | Radio button group | `string` |
+| [Checkboxes](/docs/fields/checkboxes) | Checkbox group | `string[]` |
+| [Relation](/docs/fields/relation) | Reference to entries | `string \| string[]` |
+| [Object](/docs/fields/object) | Nested field group | `ObjectFieldData` |
+| [Array](/docs/fields/array) | Simple typed arrays | `(string \| number \| UrlFieldData)[]` |
+| [Blocks](/docs/fields/blocks) | Repeatable typed objects | `ObjectFieldData[]` |
+| [Slug](/docs/fields/slug) | URL-friendly slug | `string` |
+| [SEO](/docs/fields/seo) | SEO metadata group | `SeoFieldData` |
+| [URL](/docs/fields/url) | URL per locale | `UrlFieldData` |
+
+
+---
+
+# Entries
+
+Entries are the content records stored in your database. Both collections and singles produce entries.
+
+## Entry Types
+
+### Populated Entry (API output)
+
+When fetching entries via `getEntries` / `getEntry`, you receive populated entries with metadata prefixed by `_`:
+
+```typescript
+type Entry = {
+  _id: string;
+  _slug: string;           // Collection/single slug
+  _type: 'collection' | 'singleton';
+  _publishedAt?: Date | null;
+  _url?: string;           // Generated from pathTemplate, e.g. '/blog/my-post'
+} & Record<string, unknown>;  // Your field data
+```
+
+### Database Entry
+
+The raw database structure:
+
+```typescript
+interface DbEntry {
+  id: string;
+  slug: string;           // Collection/single slug
+  type: 'collection' | 'singleton';
+  createdAt: Date;
+  updatedAt: Date;
+  archivedAt: Date | null;
+  sortOrder: number | null;  // For orderable collections
+}
+```
+
+## Versioning
+
+Each entry has per-language versions. Every language can have its own draft, published, and scheduled version independently.
+
+```typescript
+interface DbEntryVersion {
+  id: string;
+  entryId: string;
+  lang: string;            // Language code (e.g. 'en', 'pl')
+  versionNumber: number;
+  data: Record<string, unknown>;
+  createdAt: Date;
+  createdBy: string | null;
+  publishedAt: Date | null;
+  publishedBy: string | null;
+}
+```
+
+### Version Flow
+
+An entry progresses through these states:
+
+1. **Draft** — Work in progress, not visible to public
+2. **Published** — Live content, served to visitors
+3. **Scheduled** — Will be published at a future date/time
+
+Only one version per status per language can exist at a time.
+
+### Operations
+
+| Action | Effect |
+|--------|--------|
+| Save as Draft | Creates/updates draft version for the current language |
+| Publish Now | Creates new version, sets as published immediately |
+| Unpublish | Removes published status from current version |
+| Archive | Soft-deletes entry (can be restored) |
+| Restore | Removes archived status |
+| Delete permanently | Irreversible deletion from database |
+
+> **Archiving:** Archived entries are hidden from the admin list and API queries by default. Only archived entries can be permanently deleted.
+
+## Querying
+
+```typescript
+import { getEntries, getEntry } from 'includio-cms/admin/remote';
+
+// Get published entries for a collection
+const posts = await getEntries({
+  slug: 'posts',
+  status: 'published',
+  language: 'en'
+});
+
+// Get a single entry
+const homepage = await getEntry({
+  slug: 'homepage',
+  status: 'published',
+  language: 'en'
+});
+
+// Filter by exact field values
+const featured = await getEntries({
+  slug: 'posts',
+  dataValues: { featured: true }
+});
+
+// Search by field content (LIKE query)
+const results = await getEntries({
+  slug: 'posts',
+  dataLike: { title: 'svelte' }
+});
+
+// Case-insensitive OR search across fields
+const search = await getEntries({
+  slug: 'posts',
+  dataILikeOr: { title: 'svelte', description: 'svelte' }
+});
+
+// Sort by a data field
+const sorted = await getEntries({
+  slug: 'events',
+  status: 'published',
+  language: 'en',
+  dataOrderBy: { field: 'eventDate', direction: 'asc' }
+});
+
+// Pagination
+const page = await getEntries({
+  slug: 'posts',
+  status: 'published',
+  language: 'en',
+  limit: 10,
+  offset: 20,
+  orderBy: { column: 'createdAt', direction: 'desc' }
+});
+```
+
+## Query Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `slug` | `string` | Collection/single slug |
+| `ids` | `string[]` | Filter by specific entry IDs |
+| `status` | `'draft' \| 'published' \| 'scheduled' \| 'archived'` | Version status |
+| `language` | `string` | Locale for localized fields |
+| `dataValues` | `Record<string, unknown>` | Exact field value matching |
+| `dataLike` | `Record<string, unknown>` | Partial text matching (LIKE) |
+| `dataILikeOr` | `Record<string, unknown>` | Case-insensitive OR search |
+| `orderBy` | `{ column, direction }` | Sort by `'createdAt'`, `'updatedAt'`, or `'sortOrder'` |
+| `dataOrderBy` | `{ field, direction }` | Sort by a JSON data field |
+| `limit` | `number` | Max entries to return |
+| `offset` | `number` | Skip N entries (pagination) |
+
+## Using Entries on Frontend
+
+In a SvelteKit `+page.server.ts` load function:
+
+```typescript
+import { getEntries, getEntry } from 'includio-cms/admin/remote';
+
+export async function load() {
+  const posts = await getEntries({
+    slug: 'posts',
+    status: 'published',
+    language: 'en',
+    limit: 10,
+    orderBy: { column: 'createdAt', direction: 'desc' }
+  });
+
+  return { posts };
+}
+```
+
+Each entry in the result contains your field data plus metadata:
+
+```typescript
+// posts[0] example:
+{
+  _id: "abc-123",
+  _slug: "posts",
+  _type: "collection",
+  _publishedAt: "2026-03-15T10:00:00Z",
+  _url: "/blog/my-first-post",
+  title: "My First Post",
+  content: { type: "doc", content: [...] },  // StructuredContentDoc
+  cover: { data: { ... }, styles: { ... } }, // MediaFieldData
+  category: "tech"
+}
+```
+
+> **pathTemplate:** The `_url` field is auto-generated from the collection's `pathTemplate` (e.g. `'blog/&#123;slug&#125;'`) and the entry's slug field. Configure it in your collection/single definition.
+
+
+---
+
+# Text Field
+
+Single or multiline text input. The most common field type for titles, descriptions, and short content.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'text',
+  slug: 'title',
+  label: 'Title',
+  required: true,
+  placeholder: 'Enter title...'
+}
+```
+
+## With Options
+
+```typescript
+{
+  type: 'text',
+  slug: 'excerpt',
+  label: 'Excerpt',
+  multiline: true,
+  maxLength: 500,
+  description: 'Brief summary for listing pages'
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `placeholder` | `string` | — | Input placeholder text |
+| `minLength` | `number` | — | Minimum character length |
+| `maxLength` | `number` | — | Maximum character length |
+| `pattern` | `string` | — | Regex validation pattern |
+| `multiline` | `boolean` | `false` | Render as textarea |
+| `defaultValue` | `string` | — | Default text value |
+
+## Output
+
+Returns a `string`.
+
+```typescript
+// Single line
+{ title: "My Blog Post" }
+
+// Multiline
+{ excerpt: "A brief description\nspanning multiple lines" }
+```
+
+> **Use Cases:** Use text for titles, subtitles, excerpts, and any short-form content. For longer structured content, use [Content](/docs/fields/content) instead.
+
+
+---
+
+# Content Field
+
+Structured rich text editor powered by [TipTap](https://tiptap.dev/). Outputs a JSON document tree (`StructuredContentDoc`), not HTML.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'content',
+  slug: 'body',
+  label: 'Body',
+  required: true
+}
+```
+
+## With Inline Blocks
+
+Embed custom data blocks inside the rich text flow:
+
+```typescript
+{
+  type: 'content',
+  slug: 'body',
+  label: 'Body',
+  inlineBlocks: [
+    {
+      type: 'object',
+      slug: 'callout',
+      label: 'Callout',
+      fields: [
+        { type: 'select', slug: 'variant', options: [
+          { label: 'Info', value: 'info' },
+          { label: 'Warning', value: 'warning' }
+        ]},
+        { type: 'text', slug: 'text', required: true }
+      ]
+    }
+  ]
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `inlineBlocks` | `ObjectField[]` | — | Custom block types embeddable in the content |
+| `defaultValue` | `StructuredContentDoc` | — | Default document |
+
+## Output
+
+Returns a `StructuredContentDoc` — a JSON tree of nodes:
+
+```typescript
+interface StructuredContentDoc {
+  type: 'doc';
+  content: SCNode[];
+}
+
+interface SCNode {
+  type: string;       // 'paragraph', 'heading', 'figure', etc.
+  attrs?: Record<string, unknown>;
+  content?: SCNode[];
+  marks?: SCMark[];   // 'bold', 'italic', 'link', etc.
+  text?: string;
+}
+```
+
+Example output:
+
+```json
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "heading",
+      "attrs": { "level": 2 },
+      "content": [{ "type": "text", "text": "Hello" }]
+    },
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "text": "This is " },
+        { "type": "text", "text": "bold", "marks": [{ "type": "bold" }] },
+        { "type": "text", "text": " content." }
+      ]
+    }
+  ]
+}
+```
+
+## Node Types
+
+| Type | Description |
+|------|-------------|
+| `paragraph` | Text paragraph |
+| `heading` | Heading (attrs: `level: 2 \| 3`) |
+| `blockquote` | Block quote |
+| `bulletList` | Bullet list |
+| `orderedList` | Numbered list |
+| `listItem` | List item |
+| `codeBlock` | Code block |
+| `horizontalRule` | Horizontal line |
+| `table`, `tableRow`, `tableCell`, `tableHeader` | Table elements |
+| `figure` | Image with caption (attrs: `src`, `alt`, `caption`, `data-media-id`) |
+| `video` | Video embed (attrs: `src`, `poster`, `data-media-id`) |
+| `inlineBlock` | Custom inline block (attrs: `blockType`, `blockData`, `blockId`) |
+| `hardBreak` | Line break |
+
+## Mark Types
+
+| Mark | Description |
+|------|-------------|
+| `bold` | Bold text |
+| `italic` | Italic text |
+| `underline` | Underlined text |
+| `strike` | Strikethrough |
+| `code` | Inline code |
+| `link` | Hyperlink (attrs: `href`, `target`, `title`, `aria-label`) |
+| `highlight` | Highlighted text |
+
+## Rendering on Frontend
+
+Use the built-in `<StructuredContent>` component:
+
+```svelte
+<StructuredContent doc={entry.body} class="prose" />
+```
+
+Override specific node types with snippets:
+
+```svelte
+<StructuredContent doc={entry.body}>
+  {#snippet inlineBlock(blockType, blockData, blockId)}
+    {#if blockType === 'callout'}
+      <aside class="callout">{blockData.text}</aside>
+    {/if}
+  {/snippet}
+</StructuredContent>
+```
+
+For RSS feeds or emails, convert to HTML string:
+
+```typescript
+import { structuredToHtml } from 'includio-cms/sveltekit';
+const html = structuredToHtml(entry.body);
+```
+
+See [Frontend Rendering](/docs/frontend) for all component details and snippet overrides.
+
+> **Media in Content:** Images and videos inserted in the editor are stored as `figure` and `video` nodes with a `data-media-id` attribute. The CMS resolves these to full media data (styles, blur URLs) when entries are fetched via the API.
+
+
+---
+
+# Number Field
+
+Numeric input with optional min, max, and step constraints.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'number',
+  slug: 'price',
+  label: 'Price',
+  required: true
+}
+```
+
+## With Options
+
+```typescript
+{
+  type: 'number',
+  slug: 'quantity',
+  label: 'Quantity',
+  min: 0,
+  max: 1000,
+  step: 1,
+  defaultValue: 1
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `min` | `number` | — | Minimum allowed value |
+| `max` | `number` | — | Maximum allowed value |
+| `step` | `number` | — | Increment step (e.g., 0.01 for currency) |
+| `defaultValue` | `number` | — | Default numeric value |
+
+## Output
+
+Returns a `number`.
+
+```typescript
+{ price: 29.99, quantity: 5 }
+```
+
+> **Decimals:** Set `step: 0.01` for currency values, or `step: 1` for integers only.
+
+
+---
+
+# Boolean Field
+
+Toggle switch for true/false values.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'boolean',
+  slug: 'featured',
+  label: 'Featured',
+  defaultValue: false
+}
+```
+
+## With Options
+
+```typescript
+{
+  type: 'boolean',
+  slug: 'showInNav',
+  label: 'Show in Navigation',
+  description: 'Display this page in the main navigation',
+  defaultValue: true
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `defaultValue` | `boolean` | — | Default toggle state |
+
+## Output
+
+Returns a `boolean`.
+
+```typescript
+{ featured: true, showInNav: false }
+```
+
+> **Common Uses:** Use for feature flags, visibility toggles, or any binary state like "Show in navigation" or "Allow comments".
+
+
+---
+
+# Date Field
+
+Date picker that stores values in ISO format (YYYY-MM-DD).
+
+## Basic Usage
+
+```typescript
+{
+  type: 'date',
+  slug: 'publishedAt',
+  label: 'Published Date'
+}
+```
+
+## With Options
+
+```typescript
+{
+  type: 'date',
+  slug: 'eventDate',
+  label: 'Event Date',
+  required: true,
+  minDate: '2024-01-01',
+  maxDate: '2025-12-31'
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `minDate` | `string` | — | Earliest selectable date (ISO) |
+| `maxDate` | `string` | — | Latest selectable date (ISO) |
+| `defaultValue` | `string` | — | Default date (ISO) |
+
+## Output
+
+Returns an ISO date `string`.
+
+```typescript
+{ publishedAt: "2024-06-15" }
+```
+
+> **Date vs DateTime:** Use Date for day-level precision (publish dates, birthdays). Use [DateTime](/docs/fields/datetime) when you need time-of-day.
+
+
+---
+
+# DateTime Field
+
+Date and time picker that stores values in ISO format.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'datetime',
+  slug: 'scheduledAt',
+  label: 'Scheduled At'
+}
+```
+
+## With Options
+
+```typescript
+{
+  type: 'datetime',
+  slug: 'startsAt',
+  label: 'Start Time',
+  required: true,
+  minDate: '2024-01-01T00:00:00',
+  maxDate: '2025-12-31T23:59:59'
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `minDate` | `string` | — | Earliest selectable date/time (ISO) |
+| `maxDate` | `string` | — | Latest selectable date/time (ISO) |
+| `defaultValue` | `string` | — | Default date/time (ISO) |
+
+## Output
+
+Returns an ISO datetime `string`.
+
+```typescript
+{ scheduledAt: "2024-06-15T14:30:00.000Z" }
+```
+
+> **Scheduling:** Use DateTime for scheduled publishing, event start/end times, or any timestamp that needs time-of-day precision.
+
+
+---
+
+# File Field
+
+File upload with MIME type filtering and size limits.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'file',
+  slug: 'document',
+  label: 'Document',
+  accept: 'application/pdf',
+  maxSizeMB: 10
+}
+```
+
+## With Options (Multiple)
+
+```typescript
+{
+  type: 'file',
+  slug: 'attachments',
+  label: 'Attachments',
+  multiple: true,
+  accept: 'application/pdf,application/zip,text/csv',
+  maxSizeMB: 25
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `accept` | `string` | — | Allowed MIME types (comma-separated) |
+| `maxSizeMB` | `number` | — | Maximum file size in MB |
+| `multiple` | `boolean` | `false` | Allow multiple file uploads |
+| `defaultValue` | `string \| string[]` | — | Default file reference(s) |
+
+## Output
+
+Returns a `string` (media file ID) or `string[]` when `multiple: true`.
+
+```typescript
+// Single
+{ document: "file_abc123" }
+
+// Multiple
+{ attachments: ["file_abc123", "file_def456"] }
+```
+
+> **MIME Types:** Use standard MIME types in `accept`: `application/pdf`, `image/*`, `video/mp4`, etc. Separate multiple types with commas.
+
+
+---
+
+# Media Field
+
+Upload and manage images, videos, and other media. Supports image transforms via Sharp, video accessibility (transcripts, audio descriptions), and blur data URLs.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'media',
+  slug: 'cover',
+  label: 'Cover Image'
+}
+```
+
+## With Image Styles
+
+Generate responsive variants on upload:
+
+```typescript
+{
+  type: 'media',
+  slug: 'hero',
+  label: 'Hero Image',
+  accept: 'image/*',
+  maxSizeMB: 10,
+  styles: [
+    { name: 'thumbnail', width: 200, height: 200, crop: true },
+    { name: 'medium', width: 800, format: 'webp', quality: 80 },
+    { name: 'large', width: 1600, format: 'webp' },
+    { name: 'og', width: 1200, height: 630, crop: true, format: 'jpeg' }
+  ]
+}
+```
+
+## Video Usage
+
+```typescript
+{
+  type: 'media',
+  slug: 'video',
+  label: 'Video',
+  accept: 'video/*',
+  maxSizeMB: 100
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `accept` | `string` | — | MIME filter: `'image/*'`, `'video/*'`, `'image/*,video/*'` |
+| `maxSizeMB` | `number` | — | Max file size in MB |
+| `multiple` | `boolean` | `false` | Allow multiple files |
+| `styles` | `ImageFieldStyle[]` | — | Image transform definitions (images only) |
+
+## ImageFieldStyle
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Style identifier (key in output) |
+| `width` | `number` | Target width in pixels |
+| `height` | `number` | Target height in pixels |
+| `format` | `keyof FormatEnum` | Output format: `webp`, `avif`, `jpeg`, `png` |
+| `crop` | `boolean` | Crop to exact dimensions (vs resize to fit) |
+| `quality` | `number` | Compression quality (1–100) |
+| `media` | `string` | Media query for responsive `<picture>` usage |
+| `srcset` | `number[]` | Widths for srcset generation |
+| `sizes` | `string` | Sizes attribute for responsive images |
+
+## Output
+
+Returns `MediaFieldData` — either `ImageFieldData` or `VideoFieldData` depending on file type.
+
+### Image Output
+
+```typescript
+interface ImageFieldData {
+  data: MediaFile;
+  styles: Record<string, ImageStyle>;
+  blurDataUrl?: string | null;
+}
+
+// Example
+{
+  data: { id: "abc", url: "/uploads/hero.jpg", type: "image", width: 2400, height: 1600, alt: "..." },
+  styles: {
+    thumbnail: { url: "/uploads/hero-thumb.webp", mimeType: "image/webp" },
+    medium: { url: "/uploads/hero-md.webp", mimeType: "image/webp", srcset: "...", sizes: "..." }
+  },
+  blurDataUrl: "data:image/png;base64,..."
+}
+```
+
+### Video Output
+
+```typescript
+interface VideoFieldData {
+  data: MediaFile;
+  styles: Record<string, VideoStyle>;  // Transcoded variants
+  transcript: MediaFile | null;
+  audioDescription: MediaFile | null;
+}
+
+interface VideoStyle {
+  id: string;
+  mediaFileId: string;
+  name: string;
+  url: string;
+  width: number | null;
+  height: number | null;
+  format: string;
+  codec: string | null;
+  fileSize: number | null;
+  mimeType: string;
+  status: 'pending' | 'processing' | 'done' | 'failed';
+  error: string | null;
+}
+
+// Example
+{
+  data: { id: "xyz", url: "/uploads/intro.mp4", type: "video", duration: 120, posterUrl: "/uploads/intro-poster.jpg" },
+  styles: {
+    "mp4-1080": { url: "/uploads/intro-mp4-1080.mp4", format: "mp4", codec: "h264", mimeType: "video/mp4", status: "done", ... },
+    "webm-1080": { url: "/uploads/intro-webm-1080.webm", format: "webm", codec: "vp9", mimeType: "video/webm", status: "done", ... }
+  },
+  transcript: { id: "t1", url: "/uploads/intro-transcript.vtt", ... },
+  audioDescription: null
+}
+```
+
+## MediaFile
+
+The full `MediaFile` interface returned in media field output:
+
+```typescript
+interface MediaFile {
+  id: string;
+  name: string;
+  url: string;
+  type: 'image' | 'video' | 'audio' | 'pdf' | 'other';
+  size: number;
+  width: number | null;
+  height: number | null;
+  alt: string | null;
+  tags: MediaTag[];
+  createdAt: Date;
+  mimeType: string | null;
+  blurDataUrl: string | null;
+  focalX: number | null;
+  focalY: number | null;
+  // Video-specific
+  thumbnailUrl: string | null;
+  duration: number | null;
+  posterUrl: string | null;
+  transcriptFileId: string | null;
+  audioDescriptionFileId: string | null;
+}
+```
+
+> **Performance:** Define styles for all breakpoints you need. Variants are generated on upload, so your frontend serves optimized images without runtime processing. Use `blurDataUrl` for progressive loading placeholders.
+
+## VideoFieldStyle
+
+When defining custom video styles in fields (advanced usage):
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | `string` | Yes | Style identifier |
+| `format` | `'mp4' \| 'webm'` | Yes | Output format |
+| `codec` | `'h264' \| 'vp9'` | No | Video codec |
+| `maxWidth` | `number` | No | Max width in pixels |
+| `maxHeight` | `number` | No | Max height in pixels |
+| `crf` | `number` | No | Compression quality (lower = better) |
+| `audioBitrate` | `string` | No | Audio bitrate (e.g. `'128k'`) |
+
+> **Video Accessibility:** For videos, the admin panel allows attaching transcript and audio description files. These are essential for WCAG compliance and are returned as separate `MediaFile` objects in the API output.
+
+> **Video Transcoding:** Videos are auto-transcoded to mp4/webm in the background. The `&lt;Video&gt;` component renders transcoded sources automatically. See [Video Transcoding](/docs/video-transcoding).
+
+
+---
+
+# Select Field
+
+Dropdown selection from predefined options. Supports single or multiple selection.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'select',
+  slug: 'category',
+  label: 'Category',
+  options: [
+    { label: 'Technology', value: 'tech' },
+    { label: 'Design', value: 'design' },
+    { label: 'Business', value: 'business' }
+  ]
+}
+```
+
+## With Multiple Selection
+
+```typescript
+{
+  type: 'select',
+  slug: 'tags',
+  label: 'Tags',
+  multiple: true,
+  options: [
+    { label: 'Featured', value: 'featured' },
+    { label: 'Popular', value: 'popular' },
+    { label: 'New', value: 'new' }
+  ],
+  defaultValue: ['new']
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `options` | `{ label: Localized; value: string }[]` | — | Available choices (labels support per-language values) |
+| `multiple` | `boolean` | `false` | Allow multiple selections |
+| `defaultValue` | `string \| string[]` | — | Default selection(s) |
+
+## Output
+
+Returns a `string` or `string[]` when `multiple: true`.
+
+```typescript
+// Single
+{ category: "tech" }
+
+// Multiple
+{ tags: ["featured", "new"] }
+```
+
+> **Select vs Radio:** Use Select for 4+ options or when multiple selection is needed. Use [Radio](/docs/fields/radio) for 2-3 mutually exclusive choices where all options should be visible.
+
+
+---
+
+# Radio Field
+
+Radio button group for single selection. All options are visible at once.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'radio',
+  slug: 'layout',
+  label: 'Layout',
+  options: [
+    { label: 'Full Width', value: 'full' },
+    { label: 'Sidebar', value: 'sidebar' },
+    { label: 'Centered', value: 'centered' }
+  ]
+}
+```
+
+## With Default
+
+```typescript
+{
+  type: 'radio',
+  slug: 'priority',
+  label: 'Priority',
+  options: [
+    { label: 'Low', value: 'low' },
+    { label: 'Medium', value: 'medium' },
+    { label: 'High', value: 'high' }
+  ],
+  defaultValue: 'medium'
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `options` | `{ label: Localized; value: string }[]` | — | Available choices (labels support per-language values) |
+| `defaultValue` | `string` | — | Default selected value |
+
+## Output
+
+Returns a `string`.
+
+```typescript
+{ layout: "sidebar", priority: "medium" }
+```
+
+> **Radio vs Select:** Radio shows all options at once — best for 2-3 choices. For longer lists, use [Select](/docs/fields/select) to save space.
+
+
+---
+
+# Checkboxes Field
+
+Checkbox group for multiple selection from predefined options.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'checkboxes',
+  slug: 'features',
+  label: 'Features',
+  options: [
+    { label: 'Responsive', value: 'responsive' },
+    { label: 'Dark Mode', value: 'dark-mode' },
+    { label: 'Animations', value: 'animations' },
+    { label: 'SEO Optimized', value: 'seo' }
+  ]
+}
+```
+
+## With Default
+
+```typescript
+{
+  type: 'checkboxes',
+  slug: 'permissions',
+  label: 'Permissions',
+  options: [
+    { label: 'Read', value: 'read' },
+    { label: 'Write', value: 'write' },
+    { label: 'Delete', value: 'delete' }
+  ],
+  defaultValue: ['read']
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `options` | `{ label: Localized; value: string }[]` | — | Available choices (labels support per-language values) |
+| `defaultValue` | `string \| string[]` | — | Default checked values |
+
+## Output
+
+Returns a `string[]` of selected values.
+
+```typescript
+{ features: ["responsive", "dark-mode", "seo"] }
+```
+
+> **Checkboxes vs Multi-Select:** Checkboxes show all options visually — good for small sets. For many options, use [Select](/docs/fields/select) with `multiple: true`.
+
+
+---
+
+# Relation Field
+
+Reference to entries from another collection. Creates relationships between content types.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'relation',
+  slug: 'author',
+  label: 'Author',
+  collection: 'team',
+  displayField: 'name'
+}
+```
+
+## Multiple Relations
+
+```typescript
+{
+  type: 'relation',
+  slug: 'relatedPosts',
+  label: 'Related Posts',
+  collection: 'posts',
+  multiple: true,
+  displayField: 'title'
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `collection` | `string` | — | Target collection slug (required) |
+| `multiple` | `boolean` | `false` | Allow multiple relations |
+| `displayField` | `string` | — | Field slug shown as label in the picker |
+| `defaultValue` | `string \| string[]` | — | Default entry ID(s) |
+
+## Output
+
+Returns a `string` (entry ID) or `string[]` when `multiple: true`.
+
+```typescript
+// Single
+{ author: "entry_abc123" }
+
+// Multiple
+{ relatedPosts: ["entry_abc123", "entry_def456", "entry_ghi789"] }
+```
+
+> **Display Field:** Always set `displayField` to a text field slug so the admin picker shows readable labels instead of entry IDs.
+
+
+---
+
+# Object Field
+
+Nested group of fields rendered as a collapsible section in the admin.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'object',
+  slug: 'address',
+  label: 'Address',
+  fields: [
+    { type: 'text', slug: 'street', label: 'Street' },
+    { type: 'text', slug: 'city', label: 'City' },
+    { type: 'text', slug: 'zip', label: 'ZIP Code' },
+    { type: 'text', slug: 'country', label: 'Country' }
+  ]
+}
+```
+
+## With defineObject Helper
+
+```typescript
+import { defineObject } from 'includio-cms/sveltekit';
+
+const cta = defineObject({
+  slug: 'cta',
+  label: 'Call to Action',
+  accordionLabelField: 'label',
+  fields: [
+    { type: 'text', slug: 'label', required: true },
+    { type: 'url', slug: 'link' },
+    { type: 'select', slug: 'variant', options: [
+      { label: 'Primary', value: 'primary' },
+      { label: 'Secondary', value: 'secondary' }
+    ]}
+  ]
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `fields` | `Field[]` | — | Nested field definitions (required) |
+| `accordionLabelField` | `string` | — | Field slug for the accordion header label |
+| `defaultValue` | `ObjectFieldData` | — | Default nested values |
+
+## Output
+
+Returns `ObjectFieldData`:
+
+```typescript
+interface ObjectFieldData {
+  slug?: string;   // Object type slug (used in arrays)
+  data: Record<string, unknown>;
+}
+
+// Example
+{
+  address: {
+    data: {
+      street: "123 Main St",
+      city: "Portland",
+      zip: "97201",
+      country: "US"
+    }
+  }
+}
+```
+
+> **Nesting:** Objects can contain any field type, including other objects and arrays. Use them to group related fields logically.
+
+
+---
+
+# Array Field
+
+Simple typed arrays of text, numbers, or URLs. Items can be reordered via drag-and-drop.
+
+> **Looking for repeatable objects?:** For arrays of complex objects (page builders, block-based content), use the [Blocks](/docs/fields/blocks) field instead.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'array',
+  slug: 'tags',
+  label: 'Tags',
+  of: 'text'
+}
+```
+
+## Examples
+
+### Text Array
+
+```typescript
+{
+  type: 'array',
+  slug: 'tags',
+  label: 'Tags',
+  of: 'text',
+  minItems: 1,
+  maxItems: 10
+}
+// Output: ["svelte", "cms", "typescript"]
+```
+
+### Number Array
+
+```typescript
+{
+  type: 'array',
+  slug: 'scores',
+  label: 'Scores',
+  of: 'number',
+  minItems: 3,
+  maxItems: 3
+}
+// Output: [95, 87, 72]
+```
+
+### URL Array
+
+```typescript
+{
+  type: 'array',
+  slug: 'links',
+  label: 'Links',
+  of: 'url'
+}
+// Output: [{ url: { en: "https://..." }, text: { en: "Link" } }, ...]
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `of` | `'text' \| 'number' \| 'url'` | — | Item type (required) |
+| `minItems` | `number` | — | Minimum items required |
+| `maxItems` | `number` | — | Maximum items allowed |
+| `defaultValue` | `(string \| number \| UrlFieldData)[]` | — | Default items |
+
+## Output
+
+Depends on the `of` type:
+
+| `of` | Output Type |
+|------|------------|
+| `'text'` | `string[]` |
+| `'number'` | `number[]` |
+| `'url'` | `UrlFieldData[]` |
+
+
+---
+
+# Blocks Field
+
+Repeatable list of typed objects. Each item is an instance of one of the defined block types. Items can be reordered via drag-and-drop. Ideal for page builders and flexible content sections.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'blocks',
+  slug: 'slides',
+  label: 'Slides',
+  minItems: 1,
+  maxItems: 10,
+  of: [
+    {
+      type: 'object',
+      slug: 'slide',
+      label: 'Slide',
+      accordionLabelField: 'title',
+      fields: [
+        { type: 'text', slug: 'title', required: true },
+        { type: 'content', slug: 'description' },
+        { type: 'media', slug: 'image', accept: 'image/*' }
+      ]
+    }
+  ]
+}
+```
+
+## Multiple Block Types
+
+Create a flexible page builder with multiple block types:
+
+```typescript
+{
+  type: 'blocks',
+  slug: 'content',
+  label: 'Page Content',
+  of: [
+    {
+      type: 'object',
+      slug: 'text-block',
+      label: 'Text Block',
+      fields: [{ type: 'content', slug: 'content' }]
+    },
+    {
+      type: 'object',
+      slug: 'image-block',
+      label: 'Image Block',
+      fields: [
+        { type: 'media', slug: 'image', accept: 'image/*' },
+        { type: 'text', slug: 'caption' }
+      ]
+    },
+    {
+      type: 'object',
+      slug: 'cta-block',
+      label: 'CTA Block',
+      fields: [
+        { type: 'text', slug: 'label', required: true },
+        { type: 'url', slug: 'link' }
+      ]
+    }
+  ]
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `of` | `ObjectField[]` | — | Allowed block types (required) |
+| `minItems` | `number` | — | Minimum items required |
+| `maxItems` | `number` | — | Maximum items allowed |
+| `defaultValue` | `ObjectFieldData[]` | — | Default items |
+| `displayMode` | `'simple' \| 'blocks'` | `'simple'` | Admin UI display mode |
+
+### Display Modes
+
+- **`simple`** — accordion-style list (default). Good for simple repeating groups.
+- **`blocks`** — block picker UI with type selection dialog. Better for page builder with many block types.
+
+## Output
+
+Returns `ObjectFieldData[]`:
+
+```typescript
+[
+  { _id: "abc", _slug: "text-block", content: { type: "doc", content: [...] } },
+  { _id: "def", _slug: "image-block", image: { data: { ... }, styles: { ... } }, caption: "Photo" },
+  { _id: "ghi", _slug: "text-block", content: { type: "doc", content: [...] } }
+]
+```
+
+Each item has `_id` (unique instance ID) and `_slug` (block type slug) plus the block's field data.
+
+## Fixed Length
+
+When `minItems === maxItems`, the field enters **fixed-length mode**: items are pre-populated on mount, and add/duplicate/delete controls are hidden. Only reordering is allowed.
+
+```typescript
+{
+  type: 'blocks',
+  slug: 'features',
+  minItems: 3,
+  maxItems: 3,
+  of: [
+    {
+      type: 'object',
+      slug: 'feature',
+      label: 'Feature',
+      fields: [
+        { type: 'text', slug: 'title', required: true },
+        { type: 'media', slug: 'icon', accept: 'image/*' }
+      ]
+    }
+  ]
+}
+```
+
+For multi-type blocks, use `defaultValue` to control which types are pre-populated:
+
+```typescript
+{
+  type: 'blocks',
+  slug: 'hero',
+  minItems: 2,
+  maxItems: 2,
+  defaultValue: [
+    { _slug: 'heading' },
+    { _slug: 'cta' }
+  ],
+  of: [
+    { type: 'object', slug: 'heading', fields: [...] },
+    { type: 'object', slug: 'cta', fields: [...] }
+  ]
+}
+```
+
+> **Page Builder:** Use blocks with multiple types and `displayMode: 'blocks'` to create a flexible page builder. The `_slug` in each item tells your frontend which component to render.
+
+
+---
+
+# Slug Field
+
+URL-friendly slug with optional pattern support. Automatically transforms input to lowercase with hyphens.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'slug',
+  slug: 'slug',
+  label: 'URL Slug'
+}
+```
+
+## With Pattern
+
+```typescript
+{
+  type: 'slug',
+  slug: 'url',
+  label: 'URL Path',
+  pattern: '/blog/{slug}'
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `pattern` | `string` | — | URL pattern with `{slug}` placeholder |
+| `defaultValue` | `string` | — | Default slug value |
+
+## Output
+
+Returns a `string`. Values are automatically slugified: lowercase, hyphens for spaces, no special characters.
+
+```typescript
+// Input: "My Blog Post!"
+// Output:
+{ slug: "my-blog-post" }
+
+// With pattern '/blog/{slug}':
+{ url: "/blog/my-blog-post" }
+```
+
+> **URL Patterns:** Use `pattern` to generate full URL paths. The `{"{slug}"}` placeholder is replaced with the slugified value.
+
+
+---
+
+# SEO Field
+
+Complete SEO metadata group. Renders a dedicated section in the admin with all common SEO fields.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'seo',
+  slug: 'seo',
+  label: 'SEO'
+}
+```
+
+No additional options needed — the SEO field includes all sub-fields automatically.
+
+## Included Sub-fields
+
+| Sub-field | Type | Description |
+|-----------|------|-------------|
+| `slug` | `string` | URL slug for the page |
+| `title` | `string` | Page title / OG title |
+| `description` | `string` | Meta description |
+| `canonicalUrl` | `string` | Canonical URL override |
+| `ogImage` | `string` | Open Graph image |
+| `keywords` | `string` | Meta keywords |
+| `customCode` | `string` | Custom code injection (`<head>`) |
+
+## Output
+
+Returns `SeoFieldData`:
+
+```typescript
+interface SeoFieldData {
+  slug: string;
+  title: string;
+  description?: string;
+  canonicalUrl?: string;
+  ogImage?: string;
+  keywords?: string;
+  customCode?: string;
+}
+
+// Example
+{
+  seo: {
+    slug: "my-blog-post",
+    title: "My Blog Post | My Site",
+    description: "A great article about...",
+    ogImage: "img_abc123",
+    keywords: "blog, tech, svelte"
+  }
+}
+```
+
+> **One Per Entry:** Add a single SEO field to each collection/single that represents a page. It provides everything needed for `&lt;head&gt;` meta tags.
+
+
+---
+
+# URL Field
+
+URL input with per-locale values. Each configured language gets its own URL input.
+
+## Basic Usage
+
+```typescript
+{
+  type: 'url',
+  slug: 'externalLink',
+  label: 'External Link',
+  placeholder: 'https://example.com'
+}
+```
+
+## With Options
+
+```typescript
+{
+  type: 'url',
+  slug: 'ctaLink',
+  label: 'CTA Link',
+  placeholder: 'https://',
+  description: 'Link target for the call-to-action button'
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `placeholder` | `Localized` | — | Input placeholder text |
+| `text` | `boolean` | — | Show link text input per locale |
+| `newTab` | `boolean` | — | Show "open in new tab" toggle |
+| `rel` | `boolean` | — | Show rel attribute input |
+
+## Output
+
+Returns `UrlFieldData`:
+
+```typescript
+type UrlFieldData = {
+  id?: string;
+  url: Record<string, string>;   // Language → URL mapping
+  text?: Record<string, string>; // Language → link text mapping
+  newTab?: boolean;              // Open in new tab
+  rel?: string;                  // Rel attribute value
+};
+
+// Example (multi-language with text)
+{
+  externalLink: {
+    url: {
+      en: "https://example.com/about",
+      pl: "https://example.com/pl/o-nas"
+    },
+    text: {
+      en: "About us",
+      pl: "O nas"
+    },
+    newTab: true
+  }
+}
+```
+
+> **Per-locale URLs:** URL fields automatically provide separate inputs for each configured language — useful for linking to localized external pages.
+
+
+---
+
+# Media
+
+Includio provides a media library for managing uploaded files, images, and videos.
+
+## Features
+
+- Drag & drop upload with progress indicators
+- Search by filename or alt text
+- Fullscreen lightbox preview with checkered background for transparency
+- Organize with color-coded tags
+- Automatic image style generation (resize, crop, format conversion) via Sharp
+- AI-powered alt text generation (requires AI adapter)
+- Focal point picker for smart cropping
+- Video metadata: poster images, duration, thumbnails
+- Accessibility: transcript and audio description file attachments
+
+## Upload
+
+Drag and drop files anywhere in the media library to upload. Multiple files supported.
+
+- Visual drop zone overlay appears on drag
+- Per-file progress bars during upload
+- Automatic refresh after completion
+
+## Search & Tags
+
+Filter media by typing in the search bar (matches filename and alt text).
+
+Organize media with **tags** — color-coded labels for categorization:
+
+```typescript
+interface MediaTag {
+  id: string;
+  name: string;
+  color: string;
+  createdAt: Date;
+}
+```
+
+Tags can be created, edited, and bulk-assigned to files in the media library.
+
+## Media Files
+
+Uploaded files are stored using the configured `FilesAdapter` and tracked in the database.
+
+```typescript
+type MediaFileType = 'image' | 'video' | 'audio' | 'pdf' | 'other';
+
+interface MediaFile {
+  id: string;
+  name: string;
+  url: string;
+  type: MediaFileType;
+  size: number;
+  width: number | null;
+  height: number | null;
+  alt: string | null;
+  tags: MediaTag[];
+  createdAt: Date;
+  mimeType: string | null;
+  blurDataUrl: string | null;
+  focalX: number | null;
+  focalY: number | null;
+  // Video-specific
+  thumbnailUrl: string | null;
+  duration: number | null;
+  posterUrl: string | null;
+  // Accessibility
+  transcriptFileId: string | null;
+  audioDescriptionFileId: string | null;
+}
+```
+
+## Image Styles
+
+When using the `media` field type with `styles`, the CMS generates transformed image variants using Sharp:
+
+```typescript
+{
+  type: 'media',
+  slug: 'hero',
+  accept: 'image/*',
+  styles: [
+    { name: 'thumb', width: 200, height: 200, crop: true },
+    { name: 'medium', width: 800, format: 'webp', quality: 80 },
+    { name: 'large', width: 1600, format: 'webp' },
+    { name: 'og', width: 1200, height: 630, crop: true, format: 'jpeg' }
+  ]
+}
+```
+
+Generated styles include responsive attributes:
+
+```typescript
+interface ImageStyle {
+  url: string;
+  mimeType: string;
+  media?: string;    // Media query
+  srcset?: string;   // Responsive srcset
+  sizes?: string;    // Sizes attribute
+}
+```
+
+Styles are generated on upload and stored alongside the original. See [Media Field](/docs/fields/media-field) for full style options.
+
+> **Sharp Required:** Image processing requires the `sharp` package. It's included as a dependency of `includio-cms`.
+
+## AI Alt Text
+
+With an AI adapter configured, the admin shows a "Generate alt text" button on image files:
+
+```typescript
+import { claudeAdapter } from 'includio-cms/ai-claude';
+// or
+import { openAIAdapter } from 'includio-cms/ai-openai';
+
+export default defineConfig({
+  ai: claudeAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }),
+  // ...
+});
+```
+
+See [AI Adapter](/docs/adapters/ai) for configuration details.
+
+## Video Transcoding
+
+Includio auto-transcodes uploaded videos to mp4 (h264) and webm (vp9) in the background. Transcoded variants are tracked as `VideoStyle` records:
+
+```typescript
+interface VideoStyle {
+  id: string;
+  mediaFileId: string;
+  name: string;
+  url: string;
+  width: number | null;
+  height: number | null;
+  format: string;
+  codec: string | null;
+  fileSize: number | null;
+  mimeType: string;
+  status: 'pending' | 'processing' | 'done' | 'failed';
+  error: string | null;
+}
+```
+
+The admin maintenance page provides batch transcode, purge, and retranscode with SSE progress.
+
+On the frontend, the `<Video>` component serves transcoded sources automatically with Safari-aware ordering.
+
+See [Video Transcoding](/docs/video-transcoding) for full configuration and usage.
+
+## File Adapter
+
+The file adapter handles physical storage. See [Files Adapter](/docs/adapters/files) for the interface.
+
+
+---
+
+# Video Transcoding
+
+Includio automatically transcodes uploaded videos to optimized mp4 (h264) and webm (vp9) formats in the background. Added in **v0.14.0**.
+
+## Requirements
+
+- **ffmpeg** with `libx264` and `libvpx-vp9` codecs
+- Graceful degradation if ffmpeg is unavailable — videos still upload, just no transcoded variants
+
+Check availability via the System Info endpoint (`GET /admin/api/system-info`).
+
+## Configuration
+
+Enable and configure in your CMS config:
+
+```typescript
+defineConfig({
+  media: {
+    video: {
+      transcode: true,            // default: true
+      formats: ['mp4', 'webm'],   // default: ['mp4', 'webm']
+      maxResolution: 1080,        // default: 1080 (px, longest side)
+      crf: { mp4: 23, webm: 30 },// quality (lower = better, bigger)
+      concurrency: 1              // parallel transcoding jobs
+    }
+  }
+});
+```
+
+```typescript
+interface VideoTranscodeConfig {
+  transcode?: boolean;
+  formats?: ('mp4' | 'webm')[];
+  maxResolution?: number;
+  crf?: { mp4?: number; webm?: number };
+  concurrency?: number;
+}
+```
+
+## How It Works
+
+1. User uploads a video via admin or API
+2. Original file is stored as-is
+3. Background job creates transcoded variants (one per configured format)
+4. Each variant tracked as a `VideoStyle` with status: `pending` → `processing` → `done` / `failed`
+
+### Skip Logic
+
+**For mp4 target format** — skip only when ALL three conditions are met:
+1. Source is already mp4
+2. Resolution ≤1080p (longest side)
+3. Bitrate ≤8Mbps
+
+**For webm target format** — always transcode (no skip possible).
+
+**File size guard**: Files >500MB (`MAX_AUTO_TRANSCODE_SIZE`) are skipped entirely to avoid long processing times. This is a separate check from the format-specific skip logic above.
+
+## VideoStyle
+
+Each transcoded variant produces a `VideoStyle`:
+
+```typescript
+interface VideoStyle {
+  id: string;
+  mediaFileId: string;
+  name: string;           // e.g. 'mp4-1080', 'webm-1080'
+  url: string;
+  width: number | null;
+  height: number | null;
+  format: string;         // 'mp4' | 'webm'
+  codec: string | null;   // 'h264' | 'vp9'
+  fileSize: number | null;
+  mimeType: string;
+  status: 'pending' | 'processing' | 'done' | 'failed';
+  error: string | null;
+}
+```
+
+## Admin UI
+
+The admin maintenance page provides:
+
+- **Batch transcode** — transcode all videos that don't have styles yet (SSE progress)
+- **Purge video styles** — delete all transcoded variants from disk and database
+- **Retranscode** — purge + retranscode all videos
+
+## Frontend Rendering
+
+The `<Video>` component serves transcoded sources automatically:
+
+```svelte
+<Video data={entry.video} controls />
+```
+
+Sources are ordered by `preferMp4` context:
+- Safari: mp4 first (hardware-accelerated)
+- Other browsers: webm first (better compression)
+
+Set preference in your root layout:
+
+```svelte
+<CmsProvider {data}>
+  {@render children()}
+</CmsProvider>
+```
+
+Pass `cmsContext` from your server load:
+
+```typescript
+// +layout.server.ts
+import { cmsLayoutLoad } from 'includio-cms/sveltekit/server';
+
+export function load(event) {
+  return cmsLayoutLoad(event);
+}
+```
+
+See [Frontend Rendering](/docs/frontend) for all component details.
+
+## SQL Migration
+
+```sql
+CREATE TABLE IF NOT EXISTS video_styles (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  media_file_id UUID NOT NULL REFERENCES media_file(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  url TEXT NOT NULL,
+  width INTEGER,
+  height INTEGER,
+  format TEXT NOT NULL,
+  codec TEXT,
+  file_size INTEGER,
+  mime_type TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  error TEXT,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS video_styles_unique_key
+ON video_styles (media_file_id, name);
+```
+
+> **System Info:** Use `GET /admin/api/system-info` to check ffmpeg availability, codec support, and disk usage breakdown.
+
+
+---
+
+# Forms
+
+Collect user submissions through configurable forms with email notifications and file uploads.
+
+## Defining a Form
+
+```typescript
+import { defineForm } from 'includio-cms/sveltekit';
+
+const contact = defineForm({
+  slug: 'contact',
+  label: { en: 'Contact Form' },
+  notificationEmailAddresses: ['admin@example.com'],
+  fields: [
+    { type: 'text', slug: 'name', label: { en: 'Name' }, required: true },
+    { type: 'email', slug: 'email', label: { en: 'Email' }, required: true },
+    { type: 'textarea', slug: 'message', label: { en: 'Message' }, required: true, maxLength: 2000 },
+    { type: 'select', slug: 'topic', label: { en: 'Topic' }, options: [
+      { value: 'general', label: { en: 'General' } },
+      { value: 'support', label: { en: 'Support' } }
+    ]},
+    { type: 'file', slug: 'attachment', label: { en: 'Attachment' }, accept: 'application/pdf', maxSize: 5242880 },
+    { type: 'checkbox', slug: 'consent', label: { en: 'I agree to the privacy policy' }, required: true }
+  ]
+});
+```
+
+## Configuration
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `slug` | `string` | Yes | Unique form identifier |
+| `label` | `Localized` | Yes | Display label in admin |
+| `fields` | `FormField[]` | Yes | Form field definitions |
+| `sidebarIcon` | `IconName` | No | Icon for admin sidebar |
+| `notificationEmailAddresses` | `string[]` | No | Emails notified on submission |
+
+## Form Field Types
+
+| Type | Description | Properties |
+|------|-------------|------------|
+| `text` | Single-line text | `minLength`, `maxLength` |
+| `email` | Email with validation | — |
+| `textarea` | Multi-line text | `minLength`, `maxLength` |
+| `checkbox` | Single checkbox (consent, etc.) | — |
+| `select` | Dropdown select | `options: { value, label? }[]` |
+| `file` | File upload | `accept` (MIME), `maxSize` (bytes) |
+
+### Common Form Field Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `slug` | `string` | Unique identifier |
+| `label` | `Localized` | Display label |
+| `required` | `boolean` | Whether the field is required |
+| `description` | `Localized` | Help text |
+| `errorMessage` | `Localized` | Custom validation error message |
+| `defaultValue` | `any` | Default value |
+| `showInDataTable` | `boolean` | Show column in submissions table |
+
+> **Content Fields vs Form Fields:** Form fields (`text`, `email`, `textarea`, `checkbox`, `select`, `file`) are separate from content fields. They're designed for simple user-facing forms, not complex content modeling.
+
+## Submissions
+
+Submissions are stored in the database and viewable in the admin panel:
+
+```typescript
+interface FormSubmission {
+  id: string;
+  formSlug: string;
+  createdAt: Date;
+  data: Record<string, unknown>;
+  read: boolean;         // Marked as read/unread in admin
+  ip?: string | null;    // Submitter's IP
+  userAgent?: string | null;
+}
+```
+
+## Public Submission Endpoint
+
+Forms can be submitted from your frontend via a public POST endpoint:
+
+```
+POST /api/forms/{slug}/submit
+Content-Type: multipart/form-data
+```
+
+### Submitting from Frontend
+
+```typescript
+async function submitForm(formData: Record<string, unknown>) {
+  const body = new FormData();
+
+  for (const [key, value] of Object.entries(formData)) {
+    if (value instanceof File) {
+      body.append(key, value);
+    } else {
+      body.append(key, String(value));
+    }
+  }
+
+  const res = await fetch('/api/forms/contact/submit', {
+    method: 'POST',
+    body
+  });
+
+  if (!res.ok) {
+    const error = await res.json();
+    throw new Error(error.message);
+  }
+
+  return res.json();
+}
+```
+
+### SvelteKit Form Action
+
+```svelte
+<form method="POST" action="/api/forms/contact/submit" enctype="multipart/form-data">
+  <input name="name" required />
+  <input name="email" type="email" required />
+  <textarea name="message" required></textarea>
+  <input name="attachment" type="file" accept="application/pdf" />
+  <label><input name="consent" type="checkbox" required /> I agree</label>
+  <button type="submit">Send</button>
+</form>
+```
+
+> **Rate Limiting:** Form submissions are rate-limited to 5 per IP per hour to prevent abuse.
+
+## Server-Side Submission
+
+For custom form handling in `+page.server.ts`, use the server-side helpers:
+
+```typescript
+import { createFormSubmission, parseFormDataForSubmission } from 'includio-cms/sveltekit/server';
+
+export const actions = {
+  default: async ({ request, getClientAddress }) => {
+    const { data } = await parseFormDataForSubmission(request, 'contact');
+    const success = await createFormSubmission({
+      slug: 'contact',
+      data,
+      ip: getClientAddress(),
+      userAgent: request.headers.get('user-agent') ?? undefined
+    });
+    return { success };
+  }
+};
+```
+
+| Function | Description |
+|----------|-------------|
+| `parseFormDataForSubmission` | Parse multipart form data for a given form slug. Validates against form config. |
+| `createFormSubmission` | Validate and store submission. Sends notification emails if configured. Returns `boolean`. |
+
+## Private File Uploads
+
+Added in **v0.13.0**. Files uploaded via form submissions are stored in a private directory — they are NOT publicly accessible via URL.
+
+- Private files can only be downloaded through the admin panel
+- Requires `FilesAdapter` with `uploadPrivateFile()` implemented (built-in local adapter supports this)
+- Files are stored separately from public media uploads
+
+This prevents form attachments (e.g. resumes, documents) from being accessible to anyone with the URL.
+
+## Email Notifications
+
+When `notificationEmailAddresses` is set, the CMS sends an email to those addresses on each submission using the configured email adapter.
+
+## Usage in Config
+
+```typescript
+export default defineConfig({
+  forms: [contact, newsletter, feedback],
+  // ...
+});
+```
+
+
+---
+
+# Validation
+
+Includio uses [Zod](https://zod.dev/) for field validation with Polish error messages.
+
+## Required Fields
+
+Fields with `required: true` display a red asterisk (*) next to their label. On submit, missing required fields trigger validation errors.
+
+```typescript
+{
+  type: 'text',
+  slug: 'title',
+  label: 'Tytuł',
+  required: true  // Shows asterisk, validates on save
+}
+```
+
+## Validation Messages
+
+Error messages are displayed in Polish:
+
+| Error | Message |
+|-------|---------|
+| Required field empty | "To pole jest wymagane" |
+| Invalid email | "Nieprawidłowy adres email" |
+| Number out of range | "Wartość musi być między X a Y" |
+| String too short | "Minimum X znaków" |
+| String too long | "Maximum X znaków" |
+
+## Zod Schemas
+
+Each field type has a corresponding Zod schema. You can extend validation:
+
+```typescript
+{
+  type: 'text',
+  slug: 'email',
+  label: 'Email',
+  validation: z.string().email()
+}
+```
+
+> **Automatic Error Handling:** Validation errors are automatically handled by the admin UI — shown in toast notifications on save and inline below each field. No manual error handling needed.
+
+## Custom Validation
+
+Add custom validation rules using the `validate` property:
+
+```typescript
+{
+  type: 'text',
+  slug: 'slug',
+  label: 'Slug',
+  validate: async (value, { entry }) => {
+    const exists = await checkSlugExists(value, entry.id);
+    if (exists) return 'Ten slug już istnieje';
+    return true;
+  }
+}
+```
+
+## Client-Side vs Server-Side
+
+- **Client-side:** Immediate feedback as user types (debounced)
+- **Server-side:** Full validation on form submit before save
+
+Both use the same Zod schemas for consistency.
+
+
+---
+
+# Adapters
+
+Adapters are pluggable backends for core CMS functionality. They abstract away implementation details so you can swap providers without changing your content model.
+
+## Required Adapters
+
+| Adapter | Purpose | Built-in |
+|---------|---------|----------|
+| [Database](/docs/adapters/database) | Store entries, versions, media metadata, forms | `includio-cms/db-postgres` |
+| [Files](/docs/adapters/files) | Store/retrieve uploaded files | `includio-cms/files-local` |
+| [Email](/docs/adapters/email) | Send notification emails | `includio-cms/email-nodemailer` |
+
+## Optional Adapters
+
+| Adapter | Purpose | Built-in |
+|---------|---------|----------|
+| [AI](/docs/adapters/ai) | Image alt text generation | `includio-cms/ai-claude`, `includio-cms/ai-openai` |
+
+## Configuration
+
+```typescript
+import { pg } from 'includio-cms/db-postgres';
+import { local } from 'includio-cms/files-local';
+import { nodemailerAdapter } from 'includio-cms/email-nodemailer';
+import { openAIAdapter } from 'includio-cms/ai-openai';
+
+export default defineConfig({
+  db: pg({ databaseUrl: process.env.DATABASE_URL }),
+  files: local(),
+  email: nodemailerAdapter({
+    defaultFromAddress: process.env.SMTP_FROM,
+    defaultFromName: 'My Site',
+    transportOptions: {
+      host: process.env.SMTP_HOST,
+      port: 587,
+      auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS }
+    }
+  }),
+  ai: openAIAdapter({ apiKey: process.env.OPENAI_API_KEY })  // Optional
+});
+```
+
+## Custom Adapters
+
+Implement custom adapters by conforming to the TypeScript interfaces:
+
+```typescript
+import type { DatabaseAdapter } from 'includio-cms/types';
+
+const myCustomDb: DatabaseAdapter = {
+  createEntry: async (data) => { /* ... */ },
+  getEntries: async (data) => { /* ... */ },
+  // ... implement all required methods
+};
+```
+
+> **Custom Adapters:** You can build adapters for any provider (MySQL, S3, Resend, Claude, etc). Just implement the required interface methods and pass the adapter to `defineConfig`.
+
+
+---
+
+# Database Adapter
+
+The database adapter handles all data persistence: entries, versions, media metadata, form submissions, tags, video styles, and consent logs.
+
+## Interface
+
+```typescript
+interface DatabaseAdapter {
+  // Entries
+  createEntry: (data: DbEntryInsert) => Promise<DbEntry>;
+  getEntries: (data: GetDbEntriesOptions) => Promise<DbEntry[]>;
+  countEntries: (data: Omit<GetDbEntriesOptions, 'limit' | 'offset' | 'orderBy'>) => Promise<number>;
+  updateEntry: (data: { id: string; data: Partial<DbEntry> }) => Promise<DbEntry>;
+  archiveEntry: (data: { id: string; archivedAt?: Date }) => Promise<DbEntry>;
+  deleteEntry: (data: { id: string }) => Promise<void>;
+
+  // Versions
+  createEntryVersion: (data: DbEntryVersionInsert) => Promise<DbEntryVersion>;
+  updateEntryVersion: (data: { id: string; data: Partial<DbEntryVersion> }) => Promise<DbEntryVersion>;
+  getEntryVersions: (data: GetDbEntryVersionsOptions) => Promise<DbEntryVersion[]>;
+  deleteEntryVersion: (data: { id: string }) => Promise<void>;
+
+  // Pagination (optional)
+  getPaginatedEntries?: (data: GetPaginatedEntriesOptions) => Promise<PaginatedEntryRow[]>;
+  countPaginatedEntries?: (data: Omit<GetPaginatedEntriesOptions, 'limit' | 'offset' | 'orderBy'>) => Promise<number>;
+
+  // Forms
+  createFormSubmission: (data: CreateFormSubmissionData) => Promise<void>;
+  getFormSubmissions: (slug: string) => Promise<FormSubmission[]>;
+  getFormSubmission: (id: string) => Promise<FormSubmission | null>;
+  updateFormSubmission: (id: string, data: Partial<FormSubmission>) => Promise<FormSubmission>;
+  deleteFormSubmission: (id: string) => Promise<void>;
+
+  // Consent
+  createConsentLog: (data: ConsentLogData) => Promise<void>;
+
+  // Media Tags
+  getMediaTags: () => Promise<MediaTag[]>;
+  createMediaTag: (data: { name: string; color: string }) => Promise<MediaTag>;
+  updateMediaTag: (data: { id: string; name?: string; color?: string }) => Promise<MediaTag>;
+  deleteMediaTag: (id: string) => Promise<void>;
+  setMediaFileTags: (fileId: string, tagIds: string[]) => Promise<void>;
+  bulkSetMediaFileTags: (fileIds: string[], tagIds: string[]) => Promise<void>;
+  getMediaTagsWithCounts: () => Promise<{ tag: MediaTag; count: number }[]>;
+
+  // Media Files
+  createMediaFile: (data: MediaFile) => Promise<MediaFile>;
+  getMediaFiles: (data: GetMediaFilesOptions) => Promise<MediaFile[]>;
+  countMediaFiles: (data: GetMediaFilesOptions) => Promise<number>;
+  getMediaFile: (data: GetMediaFileOptions) => Promise<MediaFile | null>;
+  updateMediaFile: (data: { id: string; data: Partial<MediaFile> }) => Promise<MediaFile>;
+  deleteMediaFile: (id: string) => Promise<void>;
+  bulkDeleteMediaFiles: (ids: string[]) => Promise<void>;
+
+  // Image Styles
+  createImageStyle: (mediaFileId: string, file: UploadedMediaFile, style: ImageFieldStyle) => Promise<ImageStyle>;
+  getImageStyle: (mediaFileId: string, style: ImageFieldStyle) => Promise<ImageStyle | null>;
+  deleteImageStylesByMediaFileId: (mediaFileId: string) => Promise<{ url: string }[]>;
+  getAllImageStyles: () => Promise<{ id: string; url: string; mediaFileId: string }[]>;
+  deleteAllImageStyles: () => Promise<number>;
+
+  // Video Styles
+  createVideoStyle: (data: CreateVideoStyleData) => Promise<VideoStyle>;
+  getVideoStylesByMediaFileId: (mediaFileId: string) => Promise<VideoStyle[]>;
+  updateVideoStyleStatus: (id: string, status: VideoStyleStatus, data?: Partial<VideoStyleUpdate>) => Promise<VideoStyle>;
+  deleteVideoStylesByMediaFileId: (mediaFileId: string) => Promise<{ url: string }[]>;
+  getAllVideoStyles: () => Promise<{ id: string; url: string; mediaFileId: string; status: VideoStyleStatus }[]>;
+  deleteAllVideoStyles: () => Promise<number>;
+}
+```
+
+## Built-in: PostgreSQL
+
+```typescript
+import { pg } from 'includio-cms/db-postgres';
+
+db: pg({
+  databaseUrl: 'postgres://user:pass@localhost:5432/mydb'
+})
+```
+
+Uses Drizzle ORM under the hood. Run `pnpm db:push` to sync the schema.
+
+## Key Types
+
+### Entry Queries
+
+```typescript
+interface GetDbEntriesOptions {
+  ids?: string[];
+  slug?: string;
+  type?: 'collection' | 'singleton';
+  onlyArchived?: boolean;
+}
+
+interface GetDbEntryVersionsOptions {
+  ids?: string[];
+  entryIds?: string[];
+  lang?: string;
+  status?: 'draft' | 'published' | 'scheduled';
+  dataValues?: Record<string, unknown>;
+  dataLike?: Record<string, unknown>;
+  dataILikeOr?: Record<string, unknown>;
+  dataOrderBy?: { field: string; direction: 'asc' | 'desc' };
+  limit?: number;
+  offset?: number;
+  orderBy?: { column: string; direction: 'asc' | 'desc' };
+}
+```
+
+### Media Queries
+
+```typescript
+interface GetMediaFilesOptions {
+  data: {
+    tagIds?: string[];
+    ids?: string[];
+    mimeTypes?: string[];
+    search?: string;
+    untagged?: boolean;
+    limit?: number;
+    offset?: number;
+  };
+}
+```
+
+### Video Styles
+
+```typescript
+interface CreateVideoStyleData {
+  mediaFileId: string;
+  name: string;
+  url: string;
+  width: number | null;
+  height: number | null;
+  format: string;
+  codec: string | null;
+  fileSize: number | null;
+  mimeType: string;
+  status: VideoStyleStatus; // 'pending' | 'processing' | 'done' | 'failed'
+}
+```
+
+> **Custom Implementation:** To use MySQL, MongoDB, or another database, implement all methods in the `DatabaseAdapter` interface. Each method has clear input/output types. Optional methods (`getPaginatedEntries`, `countPaginatedEntries`) can be omitted.
+
+
+---
+
+# Files Adapter
+
+The files adapter handles physical file storage and retrieval.
+
+## Interface
+
+```typescript
+interface FilesAdapter {
+  downloadFile: (id: string) => Promise<File | null>;
+  uploadFile: (file: File) => Promise<UploadedMediaFile>;
+  renameFile: (url: string, oldName: string, newName: string) => Promise<
+    | { success: true; url: string; name: string }
+    | { success: false; error: 'name-already-exists' }
+  >;
+  deleteFile: (filename: string) => Promise<void>;
+  listFiles: () => Promise<string[]>;
+
+  // Optional — for private form submission files (v0.13.0)
+  uploadPrivateFile?: (file: File) => Promise<{ filename: string; url: string }>;
+  downloadPrivateFile?: (filename: string) => Promise<File | null>;
+  deletePrivateFile?: (filename: string) => Promise<void>;
+}
+```
+
+## Methods
+
+| Method | Required | Description |
+|--------|----------|-------------|
+| `downloadFile` | Yes | Retrieve a file by ID. Returns `null` if not found. |
+| `uploadFile` | Yes | Store a file and return metadata (URL, size, etc). |
+| `renameFile` | Yes | Rename a file. Returns error if name conflicts. |
+| `deleteFile` | Yes | Delete a file by filename. |
+| `listFiles` | Yes | List all stored filenames. Used by media garbage collection. |
+| `uploadPrivateFile` | No | Upload to non-public directory. Used for form file submissions. |
+| `downloadPrivateFile` | No | Download private file by filename. |
+| `deletePrivateFile` | No | Delete private file by filename. |
+
+## Built-in: Local Filesystem
+
+```typescript
+import { local } from 'includio-cms/files-local';
+
+files: local()
+```
+
+Stores files in the project's `static/uploads` directory. Files are accessible at `/uploads/filename.ext`.
+
+Private files are stored in `data/private-uploads/` — not publicly accessible.
+
+> **Production Storage:** The local adapter is ideal for development. For production, implement a custom adapter that stores files in S3, Cloudflare R2, or another object storage service.
+
+## Private File Uploads
+
+Added in **v0.13.0**. Form submissions with file fields upload to a private directory — files are NOT publicly accessible and can only be retrieved through the admin API.
+
+The built-in local adapter implements all three private methods. Custom adapters can optionally implement them to support form file uploads.
+
+## Custom Adapter Example
+
+```typescript
+import type { FilesAdapter } from 'includio-cms/types';
+
+const s3Files: FilesAdapter = {
+  async uploadFile(file) {
+    const key = `uploads/${Date.now()}-${file.name}`;
+    await s3.putObject({ Key: key, Body: file });
+    return { url: `https://cdn.example.com/${key}`, name: file.name, size: file.size };
+  },
+  async downloadFile(id) {
+    const response = await s3.getObject({ Key: id });
+    return new File([response.Body], id);
+  },
+  async renameFile(url, oldName, newName) {
+    // Copy to new key, delete old
+    return { success: true, url: newUrl, name: newName };
+  },
+  async deleteFile(filename) {
+    await s3.deleteObject({ Key: `uploads/${filename}` });
+  },
+  async listFiles() {
+    const result = await s3.listObjects({ Prefix: 'uploads/' });
+    return result.Contents.map(obj => obj.Key.replace('uploads/', ''));
+  }
+};
+```
+
+
+---
+
+# Email Adapter
+
+The email adapter sends notification emails for form submissions and other CMS events.
+
+## Interface
+
+```typescript
+interface EmailAdapter {
+  sendMail: (options: SendMailOptions) => Promise<void>;
+  defaultFromAddress: string;
+  defaultFromName: string;
+}
+
+interface SendMailOptions {
+  to: string | string[];
+  subject: string;
+  html: string;
+}
+```
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `sendMail` | Function | Send an email with HTML body |
+| `defaultFromAddress` | `string` | Default sender email address |
+| `defaultFromName` | `string` | Default sender display name |
+
+## Built-in: Nodemailer
+
+```typescript
+import { nodemailerAdapter } from 'includio-cms/email-nodemailer';
+
+email: nodemailerAdapter({
+  defaultFromAddress: 'noreply@example.com',
+  defaultFromName: 'My Site',
+  transportOptions: {
+    host: 'smtp.example.com',
+    port: 587,
+    auth: {
+      user: process.env.SMTP_USER,
+      pass: process.env.SMTP_PASS
+    }
+  }
+})
+```
+
+> **Transactional Email:** For production, use a transactional email service (SendGrid, Postmark, Resend, etc). Implement the `EmailAdapter` interface with their SDK.
+
+## Custom Adapter Example
+
+```typescript
+import type { EmailAdapter } from 'includio-cms/types';
+
+const resendEmail: EmailAdapter = {
+  defaultFromAddress: 'noreply@example.com',
+  defaultFromName: 'My CMS',
+  async sendMail({ to, subject, html }) {
+    await resend.emails.send({
+      from: 'noreply@example.com',
+      to: Array.isArray(to) ? to : [to],
+      subject,
+      html
+    });
+  }
+};
+```
+
+
+---
+
+# AI Adapter
+
+The AI adapter provides AI-powered features. Currently supports automatic alt text generation for images.
+
+## Interface
+
+```typescript
+interface AIAdapter {
+  generateAltText: (fileId: string) => Promise<string>;
+}
+
+interface AIConfig {
+  apiKey: string;
+}
+```
+
+## Built-in: Claude
+
+```typescript
+import { claudeAdapter } from 'includio-cms/ai-claude';
+
+ai: claudeAdapter({
+  apiKey: process.env.ANTHROPIC_API_KEY
+})
+```
+
+Uses Claude Haiku with vision to analyze uploaded images and generate descriptive alt text. Converts images to PNG before analysis for consistent results.
+
+## Built-in: OpenAI
+
+```typescript
+import { openAIAdapter } from 'includio-cms/ai-openai';
+
+ai: openAIAdapter({
+  apiKey: process.env.OPENAI_API_KEY
+})
+```
+
+Uses GPT-4 Vision to analyze uploaded images and generate descriptive alt text.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Alt text generation | Analyzes image content and generates descriptive text for accessibility |
+
+The adapter is optional. If not configured, AI features are hidden in the admin UI.
+
+> **Optional:** The AI adapter is the only optional adapter. All other adapters (database, files) are required for the CMS to function. Email is also optional.
+
+## Custom Adapter
+
+Implement the `AIAdapter` interface for other providers:
+
+```typescript
+import type { AIAdapter } from 'includio-cms/types';
+
+const customAI: AIAdapter = {
+  async generateAltText(fileId) {
+    // Fetch image, analyze, return alt text string
+    return 'Descriptive alt text';
+  }
+};
+```
+
+
+---
+
+# Authentication
+
+Includio uses [better-auth](https://www.better-auth.com/) for session-based authentication in the admin panel.
+
+## Overview
+
+- Users stored in the database with secure password hashing
+- Sessions use secure HTTP-only cookies
+- Write operations (commands) require authentication
+- Read operations (queries) are public by default
+- Supports email/password and Google OAuth
+
+## Configuration
+
+```typescript
+interface AuthConfig {
+  secret: string;    // Session secret (required)
+  baseURL?: string;  // Base URL for auth callbacks
+}
+```
+
+```typescript
+defineConfig({
+  auth: {
+    secret: process.env.AUTH_SECRET
+  },
+  // ...
+});
+```
+
+## Creating Users
+
+Use the CLI command to create admin users:
+
+```bash
+pnpm create:user
+```
+
+Follow the prompts to enter email and password.
+
+## User Roles
+
+| Role | Permissions |
+|------|-------------|
+| `admin` | Full access: create/edit/delete entries, manage users, settings |
+| `user` | Standard content editing access |
+
+## API Keys
+
+For programmatic REST API access, configure API keys:
+
+```typescript
+interface ApiKeyConfig {
+  key: string;
+  name?: string;            // Descriptive name
+  role?: 'admin' | 'editor';  // Permission level
+}
+```
+
+```typescript
+defineConfig({
+  apiKeys: [
+    { key: process.env.API_KEY, name: 'Frontend app', role: 'editor' }
+  ],
+  // ...
+});
+```
+
+API keys are sent via HTTP header when making REST API requests. See [API Reference](/docs/api).
+
+## Session Flow
+
+1. User enters email/password on the login page
+2. Server validates credentials against the database
+3. Session token is created and stored as HTTP-only cookie
+4. Subsequent requests include the session cookie automatically
+
+## Admin Access
+
+The admin panel at `/admin` requires authentication. Unauthenticated users are redirected to the login page.
+
+## Auth Middleware
+
+Commands (write operations) require authentication:
+
+```typescript
+import { requireAuth } from './middleware/auth.js';
+
+export const createEntry = command(schema, async (input) => {
+  requireAuth(); // Throws 401 if not authenticated
+  // ... create the entry
+});
+```
+
+Queries (read operations) are public, enabling frontend content access:
+
+```typescript
+export const getEntries = query(schema, async (input) => {
+  // No auth required — public content access
+  return await db.getEntries(input);
+});
+```
+
+> **Public Queries:** Read-only queries like `getEntries` and `getEntry` don't require auth. This lets your frontend fetch published content without credentials.
+
+## Password Reset
+
+Users can reset their password via email:
+
+1. User clicks "Forgot password" on the login page
+2. CMS sends a reset link to the registered email
+3. User follows the link and sets a new password
+
+Requires the **email adapter** to be configured. Without it, password reset is unavailable.
+
+## Security
+
+| Feature | Implementation |
+|---------|---------------|
+| Password hashing | Secure one-way hash |
+| Session tokens | `@oslojs/crypto` SHA-256 |
+| Cookie flags | `httpOnly`, `secure`, `sameSite` |
+| Session expiry | Automatic timeout |
+| API key comparison | Timing-safe (v0.13.3) |
+| Security headers | X-Content-Type-Options, X-Frame-Options, Referrer-Policy (v0.13.3) |
+| Upload protection | MIME type blocklist (v0.13.3) |
+
+
+---
+
+# Plugins
+
+Plugins extend CMS behavior through lifecycle hooks that run before or after CRUD operations.
+
+## Defining a Plugin
+
+```typescript
+import type { PluginConfig } from 'includio-cms/types';
+
+const auditLog: PluginConfig = {
+  slug: 'audit-log',
+  hooks: {
+    afterCreate: async (entry) => {
+      console.log('Created entry:', entry.id, entry.slug);
+    },
+    afterUpdate: async (entry) => {
+      console.log('Updated entry:', entry.id);
+    },
+    afterDelete: async (id) => {
+      console.log('Deleted entry:', id);
+    }
+  }
+};
+```
+
+## Hook Lifecycle
+
+Hooks execute in this order:
+
+1. `beforeCreate` / `beforeUpdate` / `beforeDelete` — Before the database operation
+2. **Database operation executes**
+3. `afterCreate` / `afterUpdate` / `afterDelete` — After the operation succeeds
+
+## Available Hooks
+
+| Hook | Arguments | Description |
+|------|-----------|-------------|
+| `beforeCreate` | `data: Record<string, unknown>` | Before entry creation. Receives the entry data. |
+| `afterCreate` | `entry: RawEntry` | After entry creation. Receives the full entry. |
+| `beforeUpdate` | `id: string, data: Record<string, unknown>` | Before entry update. |
+| `afterUpdate` | `entry: RawEntry` | After entry update. |
+| `beforeDelete` | `id: string` | Before entry deletion. |
+| `afterDelete` | `id: string` | After entry deletion. |
+
+## Usage in Config
+
+```typescript
+export default defineConfig({
+  plugins: [auditLog, webhooks, cacheInvalidation],
+  // ...
+});
+```
+
+Multiple plugins are executed in order. All plugins receive the same hook calls.
+
+## Real-world Example: Webhook Plugin
+
+```typescript
+const webhooks: PluginConfig = {
+  slug: 'webhooks',
+  hooks: {
+    afterCreate: async (entry) => {
+      await fetch('https://api.example.com/webhook', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          event: 'entry.created',
+          entry: { id: entry.id, slug: entry.slug, type: entry.type }
+        })
+      });
+    },
+    afterUpdate: async (entry) => {
+      await fetch('https://api.example.com/webhook', {
+        method: 'POST',
+        body: JSON.stringify({ event: 'entry.updated', entry: { id: entry.id } })
+      });
+    },
+    afterDelete: async (id) => {
+      await fetch('https://api.example.com/webhook', {
+        method: 'POST',
+        body: JSON.stringify({ event: 'entry.deleted', id })
+      });
+    }
+  }
+};
+```
+
+> **Use Cases:** Common plugins: webhook triggers, cache invalidation (CDN purge), search index updates, external API sync, Slack notifications, analytics events.
+
+## Plugin Interface
+
+```typescript
+interface PluginConfig {
+  slug: string;
+  fields?: CustomFieldDefinition[];
+  hooks?: {
+    beforeCreate?: (data: Record<string, unknown>) => Promise<void>;
+    afterCreate?: (entry: RawEntry) => Promise<void>;
+    beforeUpdate?: (id: string, data: Record<string, unknown>) => Promise<void>;
+    afterUpdate?: (entry: RawEntry) => Promise<void>;
+    beforeDelete?: (id: string) => Promise<void>;
+    afterDelete?: (id: string) => Promise<void>;
+  };
+}
+```
+
+## Custom Field Types
+
+Plugins can register custom field types that appear alongside built-in fields:
+
+```typescript
+import type { PluginConfig, CustomFieldDefinition } from 'includio-cms/types';
+import { z } from 'zod';
+
+const photoGrid: CustomFieldDefinition = {
+  fieldType: 'photo-grid',
+  // Lazy-loaded Svelte component for the admin editor
+  component: () => import('./PhotoGridEditor.svelte'),
+  // Zod validation schema
+  zodSchema: (field, languages) =>
+    z.array(z.object({ url: z.string(), caption: z.string().optional() })),
+  // TypeScript type string for codegen
+  tsType: '{ url: string; caption?: string }[]',
+  // Transform value when served via API
+  populateResolver: async (value, field) => value
+};
+
+const myPlugin: PluginConfig = {
+  slug: 'photo-grid-plugin',
+  fields: [photoGrid]
+};
+```
+
+### CustomFieldDefinition
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `fieldType` | `string` | Unique type slug (used in `{ type: 'custom', fieldType: '...' }`) |
+| `component` | `() => Promise<{ default: Component }>` | Lazy-loaded Svelte editor component |
+| `zodSchema` | `(field, languages) => ZodType` | Validation schema factory |
+| `tsType` | `string` | TypeScript type for generated types |
+| `populateResolver` | `(value, field) => Promise<unknown>` | Transform value on API output |
+
+### Using a Custom Field
+
+```typescript
+{
+  type: 'custom',
+  slug: 'gallery',
+  fieldType: 'photo-grid',  // Matches CustomFieldDefinition.fieldType
+  label: 'Photo Gallery',
+  config: { maxPhotos: 12 }  // Passed to your component
+}
+```
+
+
+---
+
+# Admin UI
+
+Includio's admin panel uses a layered glass depth system for visual hierarchy. Plugin developers can use these classes for consistent UI.
+
+## Depth System
+
+CSS variables define background colors, borders, and shadows at different depth levels:
+
+```css
+/* Background colors */
+--depth-0-bg  /* Base layer */
+--depth-1-bg  /* First level */
+--depth-2-bg  /* Second level */
+--depth-3-bg  /* Third level (modals, popovers) */
+
+/* Borders */
+--depth-border-1  /* Subtle border */
+--depth-border-2  /* More prominent border */
+
+/* Shadows */
+--depth-shadow-sm  /* Small elevation */
+--depth-shadow-md  /* Medium elevation */
+```
+
+## Glass Classes
+
+Utility classes apply the depth system with glass morphism effects:
+
+```html
+<div class="glass-depth-1">First level panel</div>
+<div class="glass-depth-2">Second level panel</div>
+<div class="glass-depth-3">Modal or popover</div>
+<div class="glass-inset">Inset/recessed area</div>
+```
+
+Each class applies:
+- Background color from depth variable
+- Appropriate border
+- Backdrop blur for glass effect
+- Shadow for elevation
+
+## Dark Mode
+
+The depth system automatically adjusts for dark mode. Variables are redefined in `[data-theme="dark"]` context:
+
+- Backgrounds shift to darker grays
+- Borders become more subtle
+- Glass effect uses different opacity
+
+> **Automatic Switching:** No extra classes needed. The same `glass-depth-*` classes work in both light and dark modes.
+
+## Usage Examples
+
+**Card component:**
+```svelte
+<div class="glass-depth-1 rounded-lg p-4">
+  <h3>Card Title</h3>
+  <p>Card content...</p>
+</div>
+```
+
+**Modal overlay:**
+```svelte
+<div class="glass-depth-3 rounded-xl p-6 shadow-lg">
+  <h2>Modal</h2>
+  <div class="glass-inset rounded p-3">
+    Inset content area
+  </div>
+</div>
+```
+
+**Nested panels:**
+```svelte
+<div class="glass-depth-1 p-4">
+  Outer panel
+  <div class="glass-depth-2 mt-2 p-3">
+    Inner panel
+  </div>
+</div>
+```
+
+## For Plugin Developers
+
+When building admin UI plugins:
+
+1. Use `glass-depth-*` classes instead of raw Tailwind backgrounds
+2. Follow the depth hierarchy (1 → 2 → 3)
+3. Use `glass-inset` for input areas or recessed sections
+4. Test in both light and dark modes
+
+
+---
+
+# Frontend Rendering
+
+Includio provides Svelte components and utilities for rendering CMS content on the frontend. All exports come from `includio-cms/sveltekit`.
+
+```typescript
+import {
+  CmsProvider, Image, Video, Media,
+  StructuredContent, HybridTarget, Preview,
+  setPreferMp4, enableHybridEditing,
+  structuredToHtml, getLink,
+  isImageFieldData, isVideoFieldData,
+  extractBlocks, extractInlineBlocks, extractText, extractMediaRefs
+} from 'includio-cms/sveltekit';
+```
+
+## Components
+
+### CmsProvider
+
+Root wrapper that passes CMS context (e.g. `preferMp4` for video source ordering).
+
+```svelte
+<!-- +layout.svelte -->
+<CmsProvider {data}>
+  {@render children()}
+</CmsProvider>
+```
+
+Pass `cmsContext` from server using `cmsLayoutLoad`:
+
+```typescript
+// +layout.server.ts
+import { cmsLayoutLoad } from 'includio-cms/sveltekit/server';
+
+export function load(event) {
+  return cmsLayoutLoad(event);
+}
+```
+
+### Image
+
+Renders `ImageFieldData` or a raw `MediaFile` with responsive `<picture>`, blur placeholder, and srcset support.
+
+```svelte
+<Image data={entry.cover} alt="Cover image" sizes="(max-width: 768px) 100vw, 50vw" />
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `data` | `ImageFieldData \| MediaFile` | Image data from CMS entry |
+| `pictureClass` | `string` | CSS class on `<picture>` wrapper |
+| `hybridPath` | `string` | Path for hybrid editing |
+| `sizes` | `string` | Responsive sizes attribute |
+| `loading` | `string` | Loading strategy (default: `'lazy'`) |
+
+Features:
+- Renders `<picture>` with `<source>` per image style (srcset, media queries)
+- Blur placeholder via `blurDataUrl` — CSS background fades out on load
+- Falls back to raw `<img>` for plain `MediaFile` objects
+- Spreads additional HTML img attributes
+
+### Video
+
+Renders `VideoFieldData` with transcoded sources, poster, and accessibility tracks.
+
+```svelte
+<Video data={entry.video} controls />
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `data` | `VideoFieldData` | Video data from CMS entry |
+| `hybridPath` | `string` | Path for hybrid editing |
+
+Features:
+- Serves transcoded sources sorted by `preferMp4` context (mp4 first for Safari, webm first otherwise)
+- Original file as final `<source>` fallback
+- `<track kind="captions">` for transcript files
+- `<track kind="descriptions">` for audio description files
+- Poster image from `data.data.posterUrl`
+- Spreads additional HTML video attributes
+
+### Media
+
+Auto-detects image vs video and delegates to `<Image>` or `<Video>`.
+
+```svelte
+<Media data={entry.hero} />
+```
+
+### StructuredContent
+
+Renders `StructuredContentDoc` (content field output) to HTML. Handles all node types: paragraphs, headings, lists, tables, figures, videos, code blocks, inline blocks.
+
+```svelte
+<StructuredContent doc={entry.body} class="prose" />
+```
+
+#### Snippet Overrides
+
+Override rendering for specific node types using Svelte 5 snippets:
+
+```svelte
+<StructuredContent doc={entry.body}>
+  {#snippet inlineBlock(blockType, blockData, blockId)}
+    {#if blockType === 'callout'}
+      <aside class="callout callout-{blockData.variant}">{blockData.text}</aside>
+    {/if}
+  {/snippet}
+
+  {#snippet figure(attrs)}
+    <figure class="my-figure">
+      <img src={attrs.src} alt={attrs.alt} />
+      {#if attrs.caption}<figcaption>{attrs.caption}</figcaption>{/if}
+    </figure>
+  {/snippet}
+
+  {#snippet heading(level, children)}
+    <svelte:element this="h{level}" class="heading-{level}">
+      {@render children()}
+    </svelte:element>
+  {/snippet}
+
+  {#snippet codeBlock(language, text)}
+    <pre class="code-block"><code class="language-{language}">{text}</code></pre>
+  {/snippet}
+</StructuredContent>
+```
+
+| Snippet | Arguments | Description |
+|---------|-----------|-------------|
+| `inlineBlock` | `blockType: string, blockData: Record, blockId: string` | Custom inline blocks |
+| `figure` | `attrs: Record` | Image figures with caption |
+| `video` | `attrs: Record` | Video embeds in content |
+| `heading` | `level: number, children: Snippet` | Heading elements |
+| `paragraph` | `children: Snippet` | Paragraph elements |
+| `codeBlock` | `language: string \| undefined, text: string` | Code blocks |
+
+### HybridTarget
+
+Wraps content for hybrid (in-place) editing. When hybrid editing is enabled, the admin panel can edit content inline on the frontend.
+
+```svelte
+<HybridTarget path="hero.title" tag="h1">
+  {entry.title}
+</HybridTarget>
+```
+
+### Preview
+
+Hybrid editing preview wrapper component.
+
+```svelte
+<Preview />
+```
+
+## Context Functions
+
+### setPreferMp4
+
+Set video source ordering preference. Called automatically by `<CmsProvider>`.
+
+```typescript
+import { setPreferMp4 } from 'includio-cms/sveltekit';
+setPreferMp4(true); // mp4 first (Safari)
+```
+
+### enableHybridEditing
+
+Enable hybrid editing mode for the current page.
+
+```typescript
+import { enableHybridEditing } from 'includio-cms/sveltekit';
+enableHybridEditing();
+```
+
+## Utility Functions
+
+### structuredToHtml
+
+Convert `StructuredContentDoc` to HTML string. Useful for RSS feeds and email.
+
+```typescript
+import { structuredToHtml } from 'includio-cms/sveltekit';
+
+const html = structuredToHtml(entry.body, {
+  inlineBlock: (blockType, blockData) => `<div>${blockData.text}</div>`,
+  baseUrl: 'https://example.com'
+});
+```
+
+### getLink
+
+Extract link URL from a URL field value.
+
+```typescript
+import { getLink } from 'includio-cms/sveltekit';
+
+const href = getLink(entry.link); // string | undefined
+```
+
+### isImageFieldData / isVideoFieldData
+
+Type guards for discriminating `MediaFieldData`:
+
+```typescript
+import { isImageFieldData, isVideoFieldData } from 'includio-cms/sveltekit';
+
+if (isImageFieldData(entry.hero)) {
+  // entry.hero is ImageFieldData
+} else if (isVideoFieldData(entry.hero)) {
+  // entry.hero is VideoFieldData
+}
+```
+
+## Query Helpers
+
+Server-side utilities for extracting data from structured content documents.
+
+```typescript
+import {
+  extractBlocks, extractInlineBlocks,
+  extractText, extractMediaRefs
+} from 'includio-cms/sveltekit';
+```
+
+### extractBlocks
+
+Extract all block nodes (paragraphs, headings, lists, etc.) from a document.
+
+```typescript
+const blocks = extractBlocks(doc);
+```
+
+### extractInlineBlocks
+
+Extract all inline block nodes from a document.
+
+```typescript
+const inlineBlocks = extractInlineBlocks(doc);
+// [{ blockType: 'callout', blockData: { variant: 'info', text: '...' }, blockId: '...' }]
+```
+
+### extractText
+
+Extract plain text from a document (useful for search indexing, excerpts).
+
+```typescript
+const text = extractText(doc);
+// "Hello world. This is the content..."
+```
+
+### extractMediaRefs
+
+Extract all media references (image and video IDs) from a document.
+
+```typescript
+const mediaIds = extractMediaRefs(doc);
+// ['uuid-1', 'uuid-2']
+```
+
+> **Import Path:** All frontend exports come from `includio-cms/sveltekit`. Server-only utilities (like `extractBlocks`) also work from this path but are typically used in `+page.server.ts` load functions.
+
+
+---
+
+# API Reference
+
+Includio provides three ways to access data: remote functions (SvelteKit), REST API (external clients), and the Entity API (server-side programmatic access).
+
+## Remote Functions (SvelteKit)
+
+Type-safe, RPC-style communication for SvelteKit apps.
+
+For `+page.server.ts` load functions, you can also import from `includio-cms/sveltekit/server`:
+
+```typescript
+import { getEntries, getEntry, countEntries } from 'includio-cms/sveltekit/server';
+```
+
+### Queries (Read)
+
+```typescript
+import { getEntries, getEntry, getRawEntries } from 'includio-cms/admin/remote';
+
+// Get published entries
+const posts = await getEntries({
+  slug: 'posts',
+  status: 'published',
+  language: 'en'
+});
+
+// Get single entry by ID
+const post = await getEntry({ id: 'uuid-here' });
+
+// Filter by exact field values
+const featured = await getEntries({
+  slug: 'posts',
+  dataValues: { featured: true, category: 'tech' }
+});
+
+// Search in field content (LIKE query)
+const results = await getEntries({
+  slug: 'posts',
+  dataLike: { title: 'search term' }
+});
+
+// Case-insensitive OR search
+const search = await getEntries({
+  slug: 'posts',
+  dataILikeOr: { title: 'svelte', description: 'svelte' }
+});
+
+// Sort by data field
+const sorted = await getEntries({
+  slug: 'events',
+  status: 'published',
+  dataOrderBy: { field: 'eventDate', direction: 'asc' }
+});
+
+// Pagination
+const page = await getEntries({
+  slug: 'posts',
+  status: 'published',
+  limit: 10,
+  offset: 20,
+  orderBy: { column: 'createdAt', direction: 'desc' }
+});
+```
+
+### Commands (Write)
+
+Commands mutate data and require authentication.
+
+```typescript
+import {
+  createEntry,
+  updateEntryVersionCommand,
+  archiveEntryCommand,
+  unarchiveEntryCommand,
+  deleteEntryCommand
+} from 'includio-cms/admin/remote';
+
+// Create entry
+await createEntry({ slug: 'posts', type: 'collection' });
+
+// Save as draft
+await updateEntryVersionCommand({
+  entryId: 'uuid',
+  data: { title: 'Hello', content: { type: 'doc', content: [] } },
+  type: 'draft'
+});
+
+// Publish immediately
+await updateEntryVersionCommand({
+  entryId: 'uuid',
+  data: { title: 'Hello' },
+  type: 'published-now'
+});
+
+// Unpublish
+await updateEntryVersionCommand({
+  entryId: 'uuid',
+  data: { title: 'Hello' },
+  type: 'cancel-published'
+});
+
+// Archive / Unarchive / Delete
+await archiveEntryCommand('entry-uuid');
+await unarchiveEntryCommand('entry-uuid');
+await deleteEntryCommand('entry-uuid');
+```
+
+### GetEntriesOptions
+
+```typescript
+interface GetEntriesOptions {
+  ids?: string[];
+  slug?: string;
+  dataValues?: Record<string, unknown>;   // Exact match
+  dataLike?: Record<string, unknown>;     // Partial text match (LIKE)
+  dataILikeOr?: Record<string, unknown>;  // Case-insensitive OR search
+  language?: string;
+  status?: 'draft' | 'published' | 'scheduled' | 'archived';
+  orderBy?: { column: 'createdAt' | 'updatedAt' | 'sortOrder'; direction: 'asc' | 'desc' };
+  dataOrderBy?: { field: string; direction: 'asc' | 'desc' };
+  limit?: number;
+  offset?: number;
+}
+```
+
+### Version Types
+
+| Type | Behavior |
+|------|----------|
+| `draft` | Save as draft (not published) |
+| `published-now` | Publish immediately |
+| `cancel-published` | Unpublish current version |
+
+## REST API
+
+For external clients. Requires API key authentication.
+
+### Authentication
+
+Send your API key in the request header:
+
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+Configure API keys in your CMS config:
+
+```typescript
+defineConfig({
+  apiKeys: [
+    { key: process.env.API_KEY, name: 'My App', role: 'editor' }
+  ]
+});
+```
+
+### Endpoints
+
+All REST endpoints are prefixed with your admin API path (e.g. `/admin/api/rest/`).
+
+#### Schema
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/schema` | Full CMS schema |
+| `GET` | `/schema/:slug` | Schema for specific collection/single |
+| `GET` | `/languages` | Available languages |
+
+#### Collections
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/collections/:slug` | List entries (query: `lang`, `status`, `limit`, `offset`) |
+| `GET` | `/collections/:slug/:id` | Get single entry |
+| `POST` | `/collections/:slug` | Create entry |
+| `PUT` | `/collections/:slug/:id` | Update entry draft |
+| `DELETE` | `/collections/:slug/:id` | Delete entry |
+
+#### Singletons
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/singletons/:slug` | Get singleton |
+| `PUT` | `/singletons/:slug` | Update singleton |
+
+#### Entry Lifecycle
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/entries/:id/publish` | Publish (query: `lang`) |
+| `POST` | `/entries/:id/unpublish` | Unpublish |
+| `POST` | `/entries/:id/archive` | Archive |
+| `POST` | `/entries/:id/unarchive` | Unarchive |
+
+#### Media
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/upload` | Upload file |
+| `GET` | `/media/:id` | Get media file metadata |
+
+## Entity API
+
+Server-side programmatic CRUD — for scripts, migrations, seeds, webhooks.
+
+```typescript
+import { createEntityAPI } from 'includio-cms/entity';
+import { getCMS } from 'includio-cms/core';
+
+const cms = getCMS();
+const api = createEntityAPI(cms, { userId: 'system' });
+
+// Create a draft
+const entry = await api.create('posts', {
+  title: 'Hello World',
+  content: { type: 'doc', content: [] }
+});
+
+// Create and publish in one step
+const published = await api.createAndPublish('posts', {
+  title: 'Published Post'
+});
+
+// Update draft
+await api.update(entry.id, { title: 'Updated Title' });
+
+// Publish / unpublish
+await api.publish(entry.id, 'en');
+await api.unpublish(entry.id, 'en');
+
+// Archive / unarchive / delete
+await api.archive(entry.id);
+await api.unarchive(entry.id);
+await api.delete(entry.id);
+
+// List entries
+const entries = await api.list('posts');
+```
+
+### Entity API Methods
+
+| Method | Arguments | Returns | Description |
+|--------|-----------|---------|-------------|
+| `create` | `slug, data?, options?` | `DbEntry` | Create draft entry |
+| `createAndPublish` | `slug, data, options?` | `DbEntry` | Create and publish |
+| `update` | `entryId, data, options?` | `DbEntryVersion` | Update draft |
+| `publish` | `entryId, lang?` | `void` | Publish latest draft |
+| `unpublish` | `entryId, lang?` | `void` | Unpublish all versions |
+| `archive` | `entryId` | `void` | Soft-delete |
+| `unarchive` | `entryId` | `void` | Restore |
+| `delete` | `entryId` | `void` | Permanently delete |
+| `list` | `slug, options?` | `RawEntry[]` | List entries |
+
+Options for `create`/`createAndPublish`: `{ skipValidation?, sortOrder?, lang? }`
+
+> **Delete Restrictions:** Only archived entries can be permanently deleted. Call `archive` first, then `delete`.
+
+
+---
+
+# Migration Guide
+
+Version-by-version upgrade guide. Each section lists what changed, what to do, and new features to adopt.
+
+> **For AI assistants:** When upgrading a site, read the relevant version sections below. Adopt new features (layout DSL, structured content, video transcoding) proactively — even if existing code still works, the new APIs provide better UX and performance.
+
+## General Upgrade Workflow
+
+1. Check breaking changes for all versions between your current and target
+2. Run SQL migrations in order
+3. Update config for new features
+4. Adopt new field types, components, and APIs
+5. Run `pnpm db:push` for schema sync
+6. Test thoroughly
+
+---
+
+## New in 0.14.0 — Video Transcoding
+
+**Added:** Auto-transcode videos to mp4/webm, system info, disk usage.
+
+**What to do:**
+- Run the video_styles SQL migration (see [Video Transcoding](/docs/video-transcoding))
+- Ensure ffmpeg with libx264 + libvpx-vp9 is available in production
+- Config is optional — transcoding enables automatically if ffmpeg available
+
+**Adopt:** Replace manual `<video>` tags with the `<Video>` component:
+
+```svelte
+<!-- Before -->
+<video src={entry.video.data.url} controls />
+
+<!-- After -->
+<Video data={entry.video} controls />
+```
+
+Set up `CmsProvider` + `preferMp4` for Safari-optimized delivery. See [Video Transcoding](/docs/video-transcoding).
+
+**New config option:**
+
+```typescript
+media: {
+  video: {
+    transcode: true,
+    formats: ['mp4', 'webm'],
+    maxResolution: 1080,
+    crf: { mp4: 23, webm: 30 },
+    concurrency: 1
+  }
+}
+```
+
+---
+
+## New in 0.13.0–0.13.4 — Security & Polish
+
+**0.13.0:** Private file uploads for form submissions.
+
+**0.13.2:** Configurable upload size limit via `BODY_SIZE_LIMIT` env var (default 50M, supports K/M/G suffixes).
+
+**0.13.3 — Breaking:** CMS config with empty `languages` array now throws at init. Ensure at least one language.
+
+**0.13.3:** Security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy), timing-safe API key comparison, MIME blocklist.
+
+**0.13.4:** Batch video poster regeneration, filename Unicode normalization (NFC).
+
+---
+
+## New in 0.12.0 — File Field, dataOrderBy, _url
+
+**Added:**
+- `file` field type — direct file upload (not media library)
+- `dataOrderBy` — sort entries by JSON data fields
+- `_url` auto-population from `pathTemplate`
+
+**Adopt:** If you sort entries in frontend queries, use `dataOrderBy`:
+
+```typescript
+const events = await getEntries({
+  slug: 'events',
+  status: 'published',
+  dataOrderBy: { field: 'eventDate', direction: 'asc' }
+});
+```
+
+**Adopt:** Set `pathTemplate` on collections to get auto-populated `_url`:
+
+```typescript
+defineCollection({
+  slug: 'posts',
+  pathTemplate: 'blog/{slug}',
+  // ...
+});
+// entry._url → '/blog/my-post'
+```
+
+---
+
+## New in 0.11.0 — Codegen Overhaul, REST API
+
+**Added:**
+- Flat entry types in codegen, inline block types, `countEntries` helper
+- REST API catch-all handler, file upload endpoint, schema endpoints
+
+**Adopt:** Use generated types for type-safe frontend code. See [Code Generation](/docs/codegen).
+
+---
+
+## New in 0.10.0 — Field Type Consolidation
+
+**Breaking:**
+- Removed `image` field → use `media` with `accept: 'image/*'`
+- Removed `richtext` field → use `content` (structured JSON)
+
+**What to do:**
+
+```typescript
+// Before
+{ type: 'image', slug: 'cover' }
+{ type: 'richtext', slug: 'body' }
+
+// After
+{ type: 'media', slug: 'cover', accept: 'image/*' }
+{ type: 'content', slug: 'body' }
+```
+
+Existing stored data (media UUIDs, ProseMirror docs) remains compatible — only config changes needed.
+
+---
+
+## New in 0.9.0 — Per-Language Entry Versions
+
+**Breaking — major restructure:**
+- Each language gets its own `entry_version` with flat (non-localized) data
+- Publish/unpublish each language independently
+- `entry` table: removed `published_at`, `published_version_id`, `published_by`, `available_locales`
+
+**SQL migration required** (run in order):
+
+```sql
+ALTER TABLE entry_version ADD COLUMN lang TEXT;
+-- Run scripts/migrate-lang-versions.ts to split multi-lang data
+ALTER TABLE entry_version ALTER COLUMN lang SET NOT NULL;
+CREATE INDEX idx_entry_version_publish ON entry_version(entry_id, lang, published_at);
+ALTER TABLE entry DROP COLUMN IF EXISTS published_at;
+ALTER TABLE entry DROP COLUMN IF EXISTS published_version_id;
+ALTER TABLE entry DROP COLUMN IF EXISTS published_by;
+ALTER TABLE entry DROP COLUMN IF EXISTS available_locales;
+```
+
+**API changes:**
+- `unpublishEntry` → `unpublishEntryLang` (requires `lang` parameter)
+- `upsertDraftVersion` and `pruneOldDraftVersions` require `lang`
+- `translateObject` removed — data is single-language per version
+
+---
+
+## New in 0.8.0 — Flat Entry Format
+
+**Breaking:**
+- Object fields: `{ slug, data: {...} }` → `{ _slug, ...fields }` (flat)
+- Blocks fields: `{ _id, slug, data: {...} }` → `{ _id, _slug, ...fields }` (flat)
+- `FlatEntry` type removed — use `Entry`
+- `flattenEntry`/`flattenFields` removed — data is already flat
+
+**What to do:** Run `includio update` to migrate existing entries.
+
+**Adopt:** Update frontend code accessing object/blocks data:
+
+```typescript
+// Before
+const companyName = entry.companyInfo.data.name;
+const blockSlug = entry.blocks[0].slug;
+
+// After
+const companyName = entry.companyInfo.name;
+const blockSlug = entry.blocks[0]._slug;
+```
+
+---
+
+## Adopting the Layout DSL
+
+If you haven't adopted the layout system yet, consider adding it to your collections. It dramatically improves the admin editing experience.
+
+**Before** (flat field list):
+```typescript
+defineCollection({
+  slug: 'page',
+  fields: [/* 15 fields in a long flat list */]
+});
+```
+
+**After** (organized with layout DSL):
+```typescript
+defineCollection({
+  slug: 'page',
+  fields: [/* same fields */],
+  layout: [
+    {
+      type: 'columns',
+      ratio: '2fr 1fr',
+      children: [
+        {
+          type: 'stack',
+          fields: ['title', 'content']
+        },
+        {
+          type: 'stack',
+          children: [
+            { type: 'card', label: { en: 'SEO', pl: 'SEO' }, fields: ['seo'] },
+            { type: 'card', label: { en: 'Settings', pl: 'Ustawienia' }, fields: ['category', 'featured'] }
+          ]
+        }
+      ]
+    }
+  ]
+});
+```
+
+Features:
+- Node types: `section`, `columns`, `card`, `accordion`, `stack`
+- Dot-notation for object fields: `'companyInfo.name'`
+- Preset shortcuts: `'sidebar-right'`, `'two-column'`
+- Fields not in layout render at the bottom automatically
+
+See [Layout](/docs/getting-started/layout) for full documentation.
+
+---
+
+## Adopting StructuredContent Component
+
+If you manually render content field JSON, switch to the built-in component:
+
+```svelte
+<!-- Before: manual recursive rendering -->
+{#if node.type === 'paragraph'}
+  <p>...</p>
+{/if}
+
+<!-- After -->
+<StructuredContent doc={entry.body} class="prose" />
+```
+
+Override specific node types with snippets. See [Frontend Rendering](/docs/frontend).
+
+
+---
+
+# Code Generation
+
+Includio generates TypeScript types and Zod validation schemas from your content schema. Added in **v0.11.0**.
+
+## What Gets Generated
+
+Based on your `collections`, `singles`, and `forms` config, the generator outputs:
+
+- **TypeScript interfaces** per collection/single — with all field types resolved
+- **Flat entry types** — with `_id`, `_slug`, `_type`, `_url`, `_publishedAt` metadata
+- **Inline block types** — from content field `inlineBlocks` definitions
+- **Zod schemas** — for runtime validation matching your field config
+- **`countEntries` helper** — typed query wrapper
+
+## Using Generated Types
+
+```typescript
+import type { PostEntry, TeamMemberEntry } from '$cms/runtime';
+
+// In +page.server.ts
+export async function load() {
+  const posts: PostEntry[] = await getEntries({
+    slug: 'posts',
+    status: 'published'
+  });
+  return { posts };
+}
+```
+
+## Flat vs Nested Types
+
+Entry types are **flat** (since v0.8.0):
+
+```typescript
+// Generated PostEntry
+interface PostEntry {
+  _id: string;
+  _slug: string;
+  _type: 'collection';
+  _url?: string;
+  _publishedAt?: Date | null;
+  _sortOrder?: number;        // if orderable
+  title: string;
+  content: StructuredContentDoc;
+  cover: ImageFieldData;
+  category: string;
+  seo: { title: string; description: string; slug: string };
+}
+```
+
+Object fields are inlined. Blocks use `_slug` discriminator:
+
+```typescript
+// blocks field with multiple block types
+type ContentBlock =
+  | { _id: string; _slug: 'hero'; title: string; image: ImageFieldData }
+  | { _id: string; _slug: 'text'; body: StructuredContentDoc };
+```
+
+## Hyphenated Collection Slugs
+
+Collections with hyphens (e.g. `'blog-post'`) generate PascalCase types: `BlogPostEntry`.
+
+> **Regenerate:** Types are regenerated automatically during development. For production, ensure codegen runs as part of your build step.
+
+
+---