includio-cms 0.22.0 → 0.24.0

package/DOCS.md

@@ -1,4 +1,4 @@
-# Includio CMS Documentation (v0.22.0)
+# Includio CMS Documentation (v0.24.0)
 
 > This file is auto-generated from the docs site. For the latest version, update the package.
 
@@ -789,7 +789,7 @@ Entries are the content records stored in your database. Both collections and si
 
 ### Populated Entry (API output)
 
-When fetching entries via `getEntries` / `getEntry`, you receive populated entries with metadata prefixed by `_`:
+When fetching entries via `resolveEntry` / `resolveEntries`, you receive populated entries with metadata prefixed by `_`:
 
 ```typescript
 type Entry = {
@@ -861,87 +861,77 @@ Only one version per status per language can exist at a time.
 ## Querying
 
 ```typescript
-import { getEntries, getEntry } from 'includio-cms/admin/remote';
+import { resolveEntry, resolveEntries, countEntries } 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',
+// Published entries for a collection
+const posts = await resolveEntries({
+  collection: 'posts',
   status: 'published',
-  language: 'en'
-});
-
-// Filter by exact field values
-const featured = await getEntries({
-  slug: 'posts',
-  dataValues: { featured: true }
+  locale: 'en'
 });
 
-// Search by field content (LIKE query)
-const results = await getEntries({
-  slug: 'posts',
-  dataLike: { title: 'svelte' }
-});
+// Single entry by ID
+const post = await resolveEntry({ id: 'uuid', locale: 'en' });
 
-// Case-insensitive OR search across fields
-const search = await getEntries({
-  slug: 'posts',
-  dataILikeOr: { title: 'svelte', description: 'svelte' }
+// Singleton (treated as a one-entry collection)
+const homepage = await resolveEntry({
+  collection: 'homepage',
+  status: 'published',
+  locale: 'en'
 });
 
-// Sort by a data field
-const sorted = await getEntries({
-  slug: 'events',
-  status: 'published',
-  language: 'en',
-  dataOrderBy: { field: 'eventDate', direction: 'asc' }
+// Filter by IDs
+const someOf = await resolveEntries({
+  collection: 'posts',
+  ids: ['id-1', 'id-2', 'id-3']
 });
 
 // Pagination
-const page = await getEntries({
-  slug: 'posts',
+const page = await resolveEntries({
+  collection: 'posts',
   status: 'published',
-  language: 'en',
+  locale: 'en',
   limit: 10,
   offset: 20,
   orderBy: { column: 'createdAt', direction: 'desc' }
 });
+
+// Count without populate (cheap)
+const total = await countEntries({ collection: 'posts', status: 'published' });
+
+// Skip relation populating for one field — return raw IDs
+const slimPosts = await resolveEntries({
+  collection: 'posts',
+  populate: { fields: { author: false } }
+});
 ```
 
 ## 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) |
+| `collection` | `string` | Collection or single slug. Required when `id` not given. |
+| `id` | `string` | Specific entry ID (in `resolveEntry`). |
+| `ids` | `string[]` | Filter by specific entry IDs (in `resolveEntries`). |
+| `status` | `'draft' \| 'published' \| 'scheduled'` | Version status. Default `'published'`. `archived` is **not** a status — use `archive*` operations. |
+| `locale` | `string` | Locale for localized fields. Defaults to `cms.languages[0]`. |
+| `orderBy` | `{ column, direction }` | Sort by `'createdAt'`, `'updatedAt'`, or `'sortOrder'`. |
+| `limit` | `number` | Max entries to return. |
+| `offset` | `number` | Skip N entries (pagination). |
+| `populate` | `{ maxDepth?, fields? }` | Cap recursion depth or opt out of populating specific fields. Default `maxDepth: 5`. |
 
 ## Using Entries on Frontend
 
 In a SvelteKit `+page.server.ts` load function:
 
 ```typescript
-import { getEntries, getEntry } from 'includio-cms/admin/remote';
+import { resolveEntries } from 'includio-cms/sveltekit/server';
 
 export async function load() {
-  const posts = await getEntries({
-    slug: 'posts',
+  const posts = await resolveEntries({
+    collection: 'posts',
     status: 'published',
-    language: 'en',
+    locale: 'en',
     limit: 10,
     orderBy: { column: 'createdAt', direction: 'desc' }
   });
@@ -969,6 +959,104 @@ Each entry in the result contains your field data plus metadata:
 
 > **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.
 
+## Error handling
+
+Resolvers and write operations throw `CmsError` (extends `Error`) with a stable `code` and structured `context`. Match on `code` — never on the message text.
+
+```typescript
+import { resolveEntry, CmsError } from 'includio-cms';
+
+try {
+  const post = await resolveEntry({ collection: 'posts', id: postId, locale: 'en' });
+  if (!post) {
+    // resolveEntry returns null when nothing matches — not an error
+    return error(404, 'Not found');
+  }
+  return { post };
+} catch (e) {
+  if (e instanceof CmsError) {
+    if (e.code === 'MISSING_REQUIRED_PARAM') return error(400, e.message);
+    if (e.code === 'ENTRY_VERSION_NOT_FOUND') return error(404, 'No version for this locale');
+  }
+  throw e;
+}
+```
+
+Stable codes (semver-protected, see [Stability Promise](/docs/stability-promise)):
+
+| Code | Where | Meaning |
+|---|---|---|
+| `ENTRY_NOT_FOUND` | Internal `_getRawEntryOrThrow` (admin REST) | Entry record missing. |
+| `ENTRY_VERSION_NOT_FOUND` | Internal `_getDbEntryVersionOrThrow` | No version row for the requested locale/status. |
+| `INVALID_DATA` | `createEntryVersion`, `updateEntryVersion` | Zod validation against the field schema failed. `error.context.collection` and `error.context.entryId` set. |
+| `MISSING_REQUIRED_PARAM` | `resolveEntry` / `resolveEntries` / `countEntries` | Neither `id` nor `collection` provided, or both omitted in a context that requires them. |
+| `CONFIG_VALIDATION_FAILED` | `defineConfig` (boot) | Config-shape problem — see [Configuration](/docs/getting-started/configuration). |
+
+Errors stringify as `[CODE] message (k=v, k=v)` — useful in logs. Never assert on `error.message` text:
+
+```typescript
+// BAD — fragile, message wording can change in patch releases
+if (e.message === 'Entry not found') { /* ... */ }
+
+// GOOD
+if (e instanceof CmsError && e.code === 'ENTRY_NOT_FOUND') { /* ... */ }
+```
+
+## Transaction patterns
+
+The default Postgres adapter (`includio-cms/db-postgres`) uses short transactions inside individual operations (e.g. create + initial version) but **does not** wrap user-orchestrated multi-call sequences. Two patterns to know:
+
+### Race conditions are versioned, not blocked
+
+If two editors save the same entry at the same time, both writes succeed and produce two new versions. The newer version becomes the current draft. There's no optimistic-lock check — design for "last write wins" semantics.
+
+For sensitive flows (e.g. publishing a price change), gate at the application layer:
+
+```typescript
+const entry = await resolveEntry({ collection: 'products', id, locale: 'en' });
+if (entry?._version !== expectedVersion) {
+  throw new Error('Stale view — reload and retry');
+}
+await updateEntryVersionCommand({ entryId: id, data: newData, type: 'published-now' });
+```
+
+### Custom transactions across multiple operations
+
+If you need create-and-publish or create-N-related-entries to be atomic, run them inside a Drizzle transaction. The Postgres adapter exposes its `db` instance:
+
+```typescript
+import { getCMS } from 'includio-cms/core';
+
+const cms = getCMS();
+const db = cms.db.driver;  // raw drizzle handle when using includio-cms/db-postgres
+
+await db.transaction(async (tx) => {
+  const author = await tx.insert(entries).values({ slug: 'authors' }).returning();
+  await tx.insert(entries).values({
+    slug: 'posts',
+    // ... reference author.id
+  });
+});
+```
+
+Inside the transaction, do **not** call CMS resolvers — they use the un-transacted connection. Either run the whole flow at the SQL layer, or accept that resolvers will read stale state until commit.
+
+### Plugin hooks and partial failure
+
+Plugin lifecycle hooks (`beforeCreate`, `afterUpdate`, etc.) run **outside** the database write — a hook throwing won't roll back the write that already committed. If a hook does network work that must succeed (webhook, downstream sync), enqueue it via your own retry mechanism instead of relying on rollback.
+
+```typescript
+{
+  hooks: {
+    afterCreate: async (entry) => {
+      // Don't throw on network errors — log + enqueue retry
+      try { await fetch(WEBHOOK_URL, { method: 'POST', body: JSON.stringify(entry) }); }
+      catch (e) { await queueRetry({ kind: 'webhook', entryId: entry._id }); }
+    }
+  }
+}
+```
+
 
 ---
 
@@ -1231,6 +1319,65 @@ Returns a `number`.
 
 > **Decimals:** Set `step: 0.01` for currency values, or `step: 1` for integers only.
 
+## Edge cases
+
+The number field is backed by a Zod `z.number()` schema. The defaults reject the silent failure modes you'd expect from a JavaScript number.
+
+| Input | Result |
+|---|---|
+| `NaN` | Rejected by Zod (`expected number, received nan`). |
+| `Infinity`, `-Infinity` | Rejected (Zod requires finite). |
+| `"42"` (string) | Rejected unless coerced upstream — the field hands a number to Zod. |
+| `null` | Allowed only when the field is **not** `required`. |
+| `42.0000001` past `step: 0.01` | Accepted as-is. The admin UI rounds for display; storage keeps the raw value. |
+
+### Floating-point precision
+
+JavaScript numbers are IEEE-754 doubles, so `0.1 + 0.2 === 0.30000000000000004`. If the value is money or an exact unit count, store it with a `step` that matches your precision (e.g. `step: 0.01` for cents) and convert at the boundary:
+
+```typescript
+// Field
+{ type: 'number', slug: 'priceUsd', label: 'Price (USD)', step: 0.01 }
+
+// Frontend rendering (shop)
+const display = (entry.priceUsd ?? 0).toFixed(2); // "29.99"
+
+// Database math — convert to integer cents to avoid drift
+const cents = Math.round(entry.priceUsd * 100);
+```
+
+For high-precision money in the shop module, `numeric(20,6)` is the storage format — see [Shop Overview](/docs/shop).
+
+### `min`/`max` are inclusive
+
+```typescript
+{ type: 'number', slug: 'rating', min: 0, max: 5 }
+```
+
+`0` and `5` are valid. To exclude an endpoint, narrow `step` (`min: 0.01` for "must be > 0") or check in your handler.
+
+### Integer-only values
+
+There's no native "integer" flag — emulate it with `step: 1`. The HTML input enforces step on UI submit; Zod runs the same comparison on the backend:
+
+```typescript
+{ type: 'number', slug: 'pages', min: 1, step: 1 }
+// 5    → ok
+// 5.5  → rejected (`Number must be a multiple of 1`)
+```
+
+### Parsing user input from forms
+
+The form field receives a `number` already, but if you pre-process URLs or query params yourself, guard `parseFloat`:
+
+```typescript
+const raw = url.searchParams.get('count');
+const count = raw ? Number(raw) : null;
+if (count !== null && !Number.isFinite(count)) {
+  // null, NaN, Infinity — handle as invalid
+}
+```
+
 
 ---
 
@@ -1277,6 +1424,56 @@ Returns a `boolean`.
 
 > **Common Uses:** Use for feature flags, visibility toggles, or any binary state like "Show in navigation" or "Allow comments".
 
+## Edge cases
+
+### `null` vs `false`
+
+These mean different things:
+
+- `false` — explicit "off". The user toggled it.
+- `null` — "not set". The field is optional and was never touched.
+
+If you treat them the same, you'll surprise users who expected the default to apply. Always pick one and stick with it:
+
+```typescript
+// Pattern A — required, always boolean
+{ type: 'boolean', slug: 'featured', required: true, defaultValue: false }
+// entry.featured is `boolean`
+
+// Pattern B — optional, may be null
+{ type: 'boolean', slug: 'showInNav', required: false }
+// entry.showInNav is `boolean | null`
+
+// Frontend: always normalize
+const showInNav = entry.showInNav ?? true; // default to "on" if unset
+```
+
+### Don't coerce strings
+
+A common bug: getting `"false"` from a query string and using it directly:
+
+```typescript
+const flag = url.searchParams.get('preview'); // "false" or null
+if (flag) { /* runs even when flag is "false"! */ }
+
+// Correct
+const flag = url.searchParams.get('preview') === 'true';
+```
+
+This isn't specific to the field, but the field stores a real `boolean` — converting back is your responsibility.
+
+### Default value in schema vs runtime
+
+`defaultValue` in the field config controls the **admin form's initial state** for new entries. It does **not** retroactively populate existing entries. If you add `defaultValue: true` to a field that previously had no default, entries created before the change still have whatever they had (often `null`).
+
+For a one-time backfill, run a migration:
+
+```sql
+UPDATE entry_versions
+SET data = jsonb_set(data, '{showInNav}', 'true')
+WHERE data->>'showInNav' IS NULL;
+```
+
 
 ---
 
@@ -1325,6 +1522,57 @@ Returns an ISO date `string`.
 
 > **Date vs DateTime:** Use Date for day-level precision (publish dates, birthdays). Use [DateTime](/docs/fields/datetime) when you need time-of-day.
 
+## Edge cases
+
+### Storage format
+
+Stored as an ISO-8601 calendar date (`YYYY-MM-DD`), no time, no timezone. There's no `Date` instance on disk — just the string. Parse to a `Date` only when you need to compute (`new Date(entry.publishedAt + 'T00:00:00Z')`).
+
+### Timezones — there are none
+
+A `date` field has no timezone. `"2024-06-15"` is the same calendar day everywhere. **Don't convert it through `new Date()` for display** — that introduces a phantom timezone shift:
+
+```typescript
+// BAD — shifts to UTC, may render as "2024-06-14" depending on locale
+new Date(entry.publishedAt).toLocaleDateString();
+
+// GOOD — split, format as-is
+const [year, month, day] = entry.publishedAt.split('-');
+const display = `${day}.${month}.${year}`;
+```
+
+If you absolutely need a timezone, switch to [DateTime](/docs/fields/datetime).
+
+### `null` handling
+
+When `required: false`, the value can be `null`. Always default before formatting:
+
+```typescript
+const date = entry.publishedAt ?? '1970-01-01';
+```
+
+### Invalid strings
+
+The admin UI uses a calendar picker, so it can't emit invalid dates. The REST API and programmatic flows can — pre-validate with `z.string().date()` if you accept user input from outside the admin:
+
+```typescript
+import { z } from 'zod';
+const Schema = z.object({ publishedAt: z.string().date() }); // YYYY-MM-DD
+```
+
+### `minDate` / `maxDate` use the same string format
+
+Compare as strings — ISO `YYYY-MM-DD` sorts lexicographically:
+
+```typescript
+{ type: 'date', slug: 'eventDate', minDate: '2024-01-01', maxDate: '2025-12-31' }
+// '2024-06-15' >= '2024-01-01' → ok
+```
+
+### Edge dates
+
+Years before 1000 or after 9999 break ISO formatting in some pickers. If you need historical or far-future dates, store as a regular text field with your own parser, not `date`.
+
 
 ---
 
@@ -1373,6 +1621,57 @@ Returns an ISO datetime `string`.
 
 > **Scheduling:** Use DateTime for scheduled publishing, event start/end times, or any timestamp that needs time-of-day precision.
 
+## Edge cases
+
+### Always store UTC, render local
+
+The picker writes a UTC ISO timestamp (`2024-06-15T14:30:00.000Z`). Render with `toLocaleString` so users see their own timezone:
+
+```svelte
+<time datetime={entry.scheduledAt}>{local}</time>
+```
+
+### DST transitions
+
+Daylight saving creates ambiguous local times — e.g. in `America/New_York`, the clock skips from 02:00 to 03:00 on the spring switch, so `02:30` doesn't exist that day. Storing UTC dodges this entirely; the issue only appears if you accept _local_ datetimes from a form. If you do, convert at the boundary and warn for known-ambiguous times.
+
+### `null` and invalid strings
+
+```typescript
+// REST or programmatic flow — validate first
+import { z } from 'zod';
+const Schema = z.object({ scheduledAt: z.string().datetime() }); // ISO 8601 full
+```
+
+`null` is allowed when `required: false`. Default before parsing:
+
+```typescript
+const ts = entry.scheduledAt ? new Date(entry.scheduledAt) : null;
+```
+
+### Comparison
+
+Always compare as `Date` objects or ISO strings — both sort correctly:
+
+```typescript
+const past = entry.scheduledAt < new Date().toISOString();
+// or
+const past = new Date(entry.scheduledAt) < new Date();
+```
+
+### Range with `minDate` / `maxDate`
+
+The bounds are full ISO timestamps. Lexicographic comparison still works for ISO strings:
+
+```typescript
+{
+  type: 'datetime',
+  slug: 'startsAt',
+  minDate: '2024-01-01T00:00:00.000Z',
+  maxDate: '2025-12-31T23:59:59.999Z'
+}
+```
+
 
 ---
 
@@ -2974,6 +3273,111 @@ const myCustomDb: DatabaseAdapter = {
 
 > **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`.
 
+## Adapter contracts
+
+Adapter interfaces are part of the public API surface (`@public`). They will not break inside a major version — see [Stability Promise](/docs/stability-promise).
+
+| Interface | Methods | Optional? | Default implementation |
+|---|---:|---|---|
+| `DatabaseAdapter` | 38 | required | `includio-cms/db-postgres` |
+| `FilesAdapter` | 5 + 3 optional | required | `includio-cms/files-local` |
+| `EmailAdapter` | 1 + 2 config props | required | `includio-cms/email-nodemailer` |
+| `AIAdapter` | 1 | optional (only if `ai:` set) | `includio-cms/ai-openai`, `includio-cms/ai-claude` |
+
+Optional methods are marked with `?` in the type definition (`getConsentLogs?`, `uploadPrivateFile?`). Returning `undefined` is fine — the CMS skips features that depend on absent capabilities.
+
+Full method lists live in the source:
+
+- `src/lib/types/adapters/db.ts` — `DatabaseAdapter`
+- `src/lib/types/adapters/files.ts` — `FilesAdapter`
+- `src/lib/types/adapters/email.ts` — `EmailAdapter`
+- `src/lib/types/adapters/ai.ts` — `AIAdapter`
+
+Browse the per-adapter docs ([Database](/docs/adapters/database), [Files](/docs/adapters/files), [Email](/docs/adapters/email), [AI](/docs/adapters/ai)) for method-level expectations and the README's "Writing your own adapter" section for a worked example.
+
+## Peer dependencies — required vs optional
+
+The CMS package declares its peers in `package.json`. Some are required for the CMS to boot at all; others are tied to specific adapters and only need to be installed if you use them.
+
+**Required** (must be installed in your app):
+
+```text
+@sveltejs/kit, @sveltejs/vite-plugin-svelte, better-auth, bits-ui,
+drizzle-orm, formsnap, postgres, runed, sharp, svelte,
+sveltekit-superforms, tailwind-merge, tailwindcss, vite, zod
+```
+
+**Optional** (`peerDependenciesMeta.optional` — install only if you use the matching adapter or feature):
+
+| Package | When to install |
+|---|---|
+| `nodemailer` | `includio-cms/email-nodemailer` |
+| `openai` | `includio-cms/ai-openai` |
+| `@anthropic-ai/sdk` | `includio-cms/ai-claude` |
+| `svelte-tiptap` | rich-text content field |
+| `paneforge` | admin layout split-panes |
+| `svelte-sonner` | admin toasts |
+| `embla-carousel-svelte` | optional carousel UI |
+
+Install only what you need:
+
+```bash
+# Minimum production app (db + local files only)
+pnpm add includio-cms
+
+# With email and OpenAI alt-text
+pnpm add includio-cms nodemailer openai
+```
+
+The CLI `includio install-peers` command walks you through installing required peers based on your `cms.config.ts`.
+
+## Lazy import pattern
+
+Optional SDK peers (`nodemailer`, `openai`, `@anthropic-ai/sdk`) are imported **lazily** inside their adapter factories — never at module top-level. This keeps the bundle clean for users who don't use the adapter, even though the import statement exists in `dist/`.
+
+```typescript
+// Pattern used by includio-cms/email-nodemailer
+export const nodemailerAdapter = (config: NodemailerConfig): EmailAdapter => {
+  let transporterPromise: Promise<Transporter> | null = null;
+
+  const getTransporter = async () => {
+    if (!transporterPromise) {
+      // Imported only on first sendMail call
+      const { createTransport } = await import('nodemailer');
+      transporterPromise = Promise.resolve(createTransport(config.transportOptions));
+    }
+    return transporterPromise;
+  };
+
+  return {
+    defaultFromAddress: config.defaultFromAddress,
+    defaultFromName: config.defaultFromName,
+    sendMail: async ({ to, subject, html }) => {
+      const t = await getTransporter();
+      await t.sendMail({ from: config.defaultFromAddress, to, subject, html });
+    }
+  };
+};
+```
+
+If your custom adapter wraps a heavyweight SDK, follow the same shape: defer the `import('your-sdk')` until the first call that needs it.
+
+## Error contracts
+
+Adapters can throw any `Error` (or subclass). The CMS does **not** wrap unknown errors automatically — they propagate up to your handler. For consistency, surface the same kinds of failures the built-in adapters do:
+
+- **Configuration errors** at construction time (e.g. missing API key) — throw a plain `Error` with a clear message. The CMS will fail fast at `getCMS()`.
+- **Recoverable runtime errors** (rate limit, transient network) — throw a typed error your callers can match on, or return `null` from a read method when "not found" is the natural answer.
+- **Validation errors** are the CMS's job — adapters should accept the data shape they're given and not re-validate.
+
+## Best practices
+
+- **Timeouts.** Wrap third-party calls in a timeout (Sharp's 30 s wrapper in `src/lib/server/utils/withTimeout.ts` is a useful template). A hung adapter pins a SvelteKit worker.
+- **Retry strategy is the caller's job.** Adapters should fail fast and surface the error. Retries belong to whatever orchestrates the call (background job, queue, user-initiated action).
+- **Be honest about partial state.** If `uploadFile` writes to disk but the DB insert fails, the file is leaked. The built-in `files-local` survives this via the maintenance GC pass — design your adapter so a similar reconciliation is possible.
+- **Don't reach into other adapters.** A `FilesAdapter` should not query the DB. The CMS coordinates cross-adapter flows; adapters stay narrow.
+- **Bench locally.** Run a `pnpm test:integration` with your adapter swapped in before production. The integration suite covers ~30 REST scenarios and 6 shop checkout flows that exercise the adapter contract end-to-end.
+
 
 ---
 
@@ -3527,38 +3931,192 @@ Requires the **email adapter** to be configured. Without it, password reset is u
 
 ---
 
-# Plugins
+# Security Model
 
-Plugins extend CMS behavior through lifecycle hooks that run before or after CRUD operations.
+Includio CMS ships with security defaults that work for typical single-tenant deployments. This page describes what's enforced, what's configurable, and where the trade-offs are.
 
-## Defining a Plugin
+> **Accepted risks:** Some defaults trade strictness for compatibility with common dependencies. Each trade-off is documented in `KNOWN-RISKS.md` at the repo root. See "Known accepted risks" at the bottom of this page.
 
-```typescript
-import type { PluginConfig } from 'includio-cms/types';
+## Threat model in scope
 
-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);
-    }
-  }
-};
-```
+| In scope | Out of scope |
+|---|---|
+| CSRF on admin endpoints | Network-level DDoS (use a CDN/WAF) |
+| Brute force on admin login + API keys | Physical/host security of your deploy |
+| XSS via stored content (TipTap, SEO, custom fields) | Compromised admin browser/extensions |
+| Image/video processing crashes (Sharp/ffmpeg) | Compromised database server |
+| Unauthorized API key reuse | Compromised filesystem on the host |
 
-## Hook Lifecycle
+## CSRF Protection
 
-Hooks execute in this order:
+Mutating requests to `/admin/api/*` (POST, PUT, PATCH, DELETE) require a same-origin `Origin` or `Referer` header. The check lives in `src/lib/server/security/csrf.ts` and runs from the SvelteKit `handle` chain.
 
-1. `beforeCreate` / `beforeUpdate` / `beforeDelete` — Before the database operation
-2. **Database operation executes**
-3. `afterCreate` / `afterUpdate` / `afterDelete` — After the operation succeeds
+A request with no `Origin`/`Referer` or with a foreign origin returns `403 Forbidden` and does not reach handlers.
+
+```ts
+// Configure allowed origins (default: same-origin only)
+// .env
+INCLUDIO_CSRF_ALLOWED_ORIGINS=https://staging.example.com,https://admin.example.com
+```
+
+Public endpoints (`/api/forms/*/submit`, shop public API) have their own protections (rate limit, signed cookies for cart) and are not behind CSRF.
+
+## Content Security Policy
+
+A CSP header is set on every admin response. The shape:
+
+```
+default-src 'self';
+script-src 'self' 'unsafe-inline';
+style-src  'self' 'unsafe-inline';
+object-src 'none';
+frame-ancestors 'self';
+base-uri   'self';
+img-src    'self' data: blob:;
+connect-src 'self';
+```
+
+`'unsafe-inline'` on `script-src` and `style-src` is **required** by two admin dependencies (TipTap rich-text editor, Paraglide i18n runtime). The other directives still cover the high-impact vectors:
+
+- `object-src 'none'` blocks Flash/legacy plugins.
+- `frame-ancestors 'self'` blocks clickjacking.
+- `base-uri 'self'` blocks `<base>` injection.
+
+This trade-off is logged as **KNOWN-RISKS §1**. Plan to revisit when TipTap supports nonce-based CSP.
+
+## Rate Limiting
+
+Two rate limit guards ship by default, both backed by the in-process `MemoryRateLimitStore`:
+
+| Surface | Default limit | Env override |
+|---|---|---|
+| `/admin/api/*` | 200 requests / 60 s per IP | `INCLUDIO_RATE_LIMIT_MAX`, `INCLUDIO_RATE_LIMIT_WINDOW_MS` |
+| `POST /api/forms/[slug]/submit` | 5 requests / 1 h per IP | `INCLUDIO_FORM_RATE_LIMIT_MAX`, `INCLUDIO_FORM_RATE_LIMIT_WINDOW_MS` |
+
+```ts
+// Example: lower the form limit for a high-volume newsletter form
+// .env
+INCLUDIO_FORM_RATE_LIMIT_MAX=20
+INCLUDIO_FORM_RATE_LIMIT_WINDOW_MS=3600000
+```
+
+Hitting the limit returns `429 Too Many Requests` with a `Retry-After` header.
+
+> **Multi-node deployments:** The default store is in-process. Behind a load balancer with N nodes, the effective limit is N×. This is **KNOWN-RISKS §3** — fix is a Redis-backed store, planned post-v1.0 as `includio-cms/rate-limit-redis`.
+
+The `RateLimitStore` interface is pluggable — provide a custom store today if you need shared state:
+
+```ts
+import { rateLimitGuard } from 'includio-cms/sveltekit/server';
+import { redisStore } from './my-redis-store.js';
+
+// Wire it into your handle chain
+rateLimitGuard({ store: redisStore });
+```
+
+## API Keys
+
+API keys authenticate REST clients (`/admin/api/*` consumers, third-party integrations). Configure them in `cms.config.ts`:
+
+```ts
+import { defineConfig, generateApiKey } from 'includio-cms/sveltekit';
+
+export default defineConfig({
+  // ...
+  apiKeys: [
+    {
+      key: generateApiKey(),                  // 32 bytes, base64url
+      name: 'mobile-app',
+      role: 'editor',
+      expiresAt: '2027-01-01T00:00:00Z',      // opt-in expiry
+      rotatedAt: '2026-04-30T10:00:00Z'       // audit trail (not enforced)
+    }
+  ]
+});
+```
+
+- `generateApiKey()` returns a 256-bit cryptographic token (43 chars, URL-safe).
+- `expiresAt` is **opt-in**. Without it, the key never expires. Once set, an expired key returns generic `401 Unauthorized` (no leak about whether the key existed).
+- `rotatedAt` is purely audit metadata — not enforced. Update it when you manually rotate.
+- Comparison is timing-safe (`crypto.timingSafeEqual`).
+
+> **Static key model:** Keys live in the config file and load into process memory at boot. Rotation requires updating `cms.config.ts` and redeploying. There's no `POST /admin/api/keys/rotate` endpoint in v1.0 — multi-tenant rotation is **KNOWN-RISKS §2**, deferred post-v1.0.
+
+## Image processing safety
+
+Every Sharp call (`metadata`, `resize`, `toBuffer`) is wrapped in a 30-second timeout. Without it, a malicious upload (zip-bomb image, ultra-high-resolution TIFF) could pin a worker indefinitely.
+
+```ts
+// Configurable via env
+// .env
+INCLUDIO_SHARP_TIMEOUT_MS=60000  # default 30000
+```
+
+A timeout aborts the upload and logs `TimeoutError` to stderr — the original file remains in storage but is not finalized in the DB. See `src/lib/server/utils/withTimeout.ts`.
+
+Subprocess audits for `ffmpeg` and `sharp` (no shell, args passed as arrays, paths normalized) are documented in **KNOWN-RISKS §5**.
+
+## Other defaults
+
+| Default | Source |
+|---|---|
+| HTTP-only, signed session cookies | `better-auth` |
+| `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin` | `src/lib/sveltekit/server/handle.ts` |
+| Filename sanitization (Unicode NFC, no `..`) on uploads | `src/lib/files-local/sanitizeFilename.ts` |
+| MIME blocklist on uploads | `src/lib/core/server/media/mimeBlocklist.ts` |
+| Timing-safe API key comparison | `src/lib/admin/api/rest/middleware/apiKey.ts` |
+
+## Known accepted risks
+
+Five trade-offs are documented in **`KNOWN-RISKS.md`** at the repository root. Each entry follows the format _description → mitigation → when fix_:
+
+1. **CSP `'unsafe-inline'`** — required by TipTap/Paraglide. Fix when nonce-based CSP is supported upstream.
+2. **API key rotation = opt-in** — `expiresAt` optional. Fix when DB-backed rotation lands (post-v1.0).
+3. **Rate limit store is in-process** — single-node only by default. Fix with `includio-cms/rate-limit-redis` (post-v1.0).
+4. **Sharp 30 s timeout** — ultra-large/expensive images error. Fix by raising `INCLUDIO_SHARP_TIMEOUT_MS` or pre-validating dimensions.
+5. **ffmpeg/sharp CLI args** — audit complete, all uses safe. Re-audit if user-controllable transcode params are ever added.
+
+Read the full file before deploying to a multi-tenant or compliance-sensitive environment.
+
+## Reporting a vulnerability
+
+Email `patryk.pilarczyk.00@gmail.com` with subject `[security] AriaCMS …`. Do not file a public GitHub issue for unpatched security bugs.
+
+
+---
+
+# 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
 
@@ -3775,6 +4333,40 @@ When building admin UI plugins:
 3. Use `glass-inset` for input areas or recessed sections
 4. Test in both light and dark modes
 
+## Accessibility
+
+The admin UI targets WCAG 2.1 AA. Built-in defaults:
+
+| Surface | What's enforced |
+|---|---|
+| Color contrast | Plus Jakarta Sans + the brand palette hits ≥ 4.5:1 for body text and ≥ 3:1 for large text and UI graphics. Don't override `--depth-*-bg` or text-color tokens without re-checking. |
+| Keyboard navigation | Every action button is reachable with `Tab`. `Esc` closes modals/popovers, `Enter`/`Space` activates focused controls. Tabbing through `bits-ui` menus restores focus to the trigger. |
+| Focus management | `:focus-visible` outlines on every interactive element. Modals trap focus until dismissed; restoring focus after close is handled by `bits-ui`. |
+| Skip-link | The admin layout includes a "Skip to main content" link as the first focusable element. |
+| Heading hierarchy | One `<h1>` per page (the breadcrumb-driven page title). Sections use `<h2>`/`<h3>` consistently. |
+| ARIA roles | Inline alerts use `role="alert"` + `aria-live="polite"`. Toasters from `svelte-sonner` announce via the same mechanism. Form fields are wired via `aria-describedby` to their hint and error nodes. |
+| Reduced motion | Animations respect `prefers-reduced-motion`. Custom transitions in plugins should follow the same rule. |
+
+### Building accessible custom panels
+
+When you scaffold a custom admin page or plugin panel, preserve the same defaults. The minimal pattern:
+
+```svelte
+<section aria-labelledby="panel-title" class="glass-depth-1 rounded-lg p-4">
+  <h2 id="panel-title">{title}</h2>
+  {@render children()}
+</section>
+```
+
+Things that come up most often when adding custom UI:
+
+- **Buttons, not divs.** Use `<button type="button">` or `<a href>` — never an `onclick` on a `<div>`. Screen readers and keyboards rely on the role.
+- **Label every input.** A `<label for>` paired with the input, or `aria-label` if visually labelless. The form fields shipped with the admin already do this; don't bypass them with raw inputs.
+- **Announce async results.** When a save succeeds, push a toast or update an `aria-live` region. A silent UI is invisible to screen readers.
+- **Don't kill focus rings.** `outline: none` on focus is a WCAG violation unless you replace it with an equivalent indicator. The admin uses `:focus-visible` with a 2px outline at sufficient contrast.
+
+> **Audit before shipping:** WCAG/ATAG compliance is a v1.x roadmap item — current defaults are correct on the surfaces above, but a full audit (axe, manual screen-reader passes) is post-v1.0. If you're targeting public-sector or accessibility-regulated deployments, schedule your own audit.
+
 
 ---
 
@@ -4055,62 +4647,60 @@ 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';
+import { resolveEntry, resolveEntries, countEntries } from 'includio-cms/sveltekit/server';
 ```
 
 ### Queries (Read)
 
 ```typescript
-import { getEntries, getEntry, getRawEntries } from 'includio-cms/admin/remote';
+import { resolveEntry, resolveEntries, countEntries } from 'includio-cms/admin/remote';
 
-// Get published entries
-const posts = await getEntries({
-  slug: 'posts',
+// List published entries (collection name + locale)
+const posts = await resolveEntries({
+  collection: 'posts',
   status: 'published',
-  language: 'en'
+  locale: 'en'
 });
 
 // Get single entry by ID
-const post = await getEntry({ id: 'uuid-here' });
+const post = await resolveEntry({ id: 'uuid-here', locale: 'en' });
 
-// 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' }
-});
+// Get a singleton (treated as a one-entry collection)
+const settings = await resolveEntry({ collection: 'settings', locale: 'en' });
 
-// 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' }
-});
+// Count without populating
+const total = await countEntries({ collection: 'posts', status: 'published' });
 
 // Pagination
-const page = await getEntries({
-  slug: 'posts',
+const page = await resolveEntries({
+  collection: 'posts',
   status: 'published',
   limit: 10,
   offset: 20,
   orderBy: { column: 'createdAt', direction: 'desc' }
 });
+
+// Opt out of populating a relation field — return the raw ID instead
+const postNoAuthor = await resolveEntry({
+  collection: 'posts',
+  id: 'uuid-here',
+  locale: 'en',
+  populate: { fields: { author: false } }
+});
+console.log(postNoAuthor.author); // string ID
+
+// Cap nested relation depth
+const flat = await resolveEntry({
+  collection: 'posts',
+  id: 'uuid-here',
+  locale: 'en',
+  populate: { maxDepth: 1 }
+});
 ```
 
 ### Commands (Write)
 
-Commands mutate data and require authentication.
+Commands mutate data and require admin authentication.
 
 ```typescript
 import {
@@ -4121,7 +4711,7 @@ import {
   deleteEntryCommand
 } from 'includio-cms/admin/remote';
 
-// Create entry
+// Create entry (always starts as draft)
 await createEntry({ slug: 'posts', type: 'collection' });
 
 // Save as draft
@@ -4138,7 +4728,7 @@ await updateEntryVersionCommand({
   type: 'published-now'
 });
 
-// Unpublish
+// Unpublish (status returns to draft)
 await updateEntryVersionCommand({
   entryId: 'uuid',
   data: { title: 'Hello' },
@@ -4151,21 +4741,19 @@ await unarchiveEntryCommand('entry-uuid');
 await deleteEntryCommand('entry-uuid');
 ```
 
-### GetEntriesOptions
+### `ResolveEntriesOptions`
 
 ```typescript
-interface GetEntriesOptions {
+interface ResolveEntriesOptions {
+  collection: string;                 // Collection or single slug
+  locale?: string;                    // Defaults to cms.languages[0]
+  status?: 'draft' | 'published' | 'scheduled';
   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';
+  filter?: Record<string, unknown>;
   orderBy?: { column: 'createdAt' | 'updatedAt' | 'sortOrder'; direction: 'asc' | 'desc' };
-  dataOrderBy?: { field: string; direction: 'asc' | 'desc' };
   limit?: number;
   offset?: number;
+  populate?: { maxDepth?: number; fields?: Record<string, false> };
 }
 ```
 
@@ -4183,7 +4771,7 @@ For external clients. Requires API key authentication.
 
 ### Authentication
 
-Send your API key in the request header:
+Send your API key in the `Authorization` header:
 
 ```
 Authorization: Bearer YOUR_API_KEY
@@ -4192,13 +4780,22 @@ Authorization: Bearer YOUR_API_KEY
 Configure API keys in your CMS config:
 
 ```typescript
+import { defineConfig, generateApiKey } from 'includio-cms/sveltekit';
+
 defineConfig({
   apiKeys: [
-    { key: process.env.API_KEY, name: 'My App', role: 'editor' }
+    {
+      key: process.env.API_KEY ?? generateApiKey(),
+      name: 'My App',
+      role: 'editor',
+      expiresAt: '2027-01-01T00:00:00Z'  // opt-in expiry
+    }
   ]
 });
 ```
 
+See [Security Model — API Keys](/docs/security#api-keys) for rotation guidance.
+
 ### Endpoints
 
 All REST endpoints are prefixed with your admin API path (e.g. `/admin/api/rest/`).
@@ -4241,15 +4838,96 @@ All REST endpoints are prefixed with your admin API path (e.g. `/admin/api/rest/
 
 | Method | Path | Description |
 |--------|------|-------------|
-| `POST` | `/upload` | Upload file |
+| `POST` | `/upload` | Upload file (multipart/form-data) |
 | `GET` | `/media/:id` | Get media file metadata |
 
+### cURL examples
+
+List published entries from the `posts` collection:
+
+```bash
+curl -s -H "Authorization: Bearer $API_KEY" \
+  "https://your-site.com/admin/api/rest/collections/posts?lang=en&status=published&limit=10"
+```
+
+Fetch one entry by ID:
+
+```bash
+curl -s -H "Authorization: Bearer $API_KEY" \
+  "https://your-site.com/admin/api/rest/collections/posts/2c1b9a8e-1234-4567-89ab-cdef01234567"
+```
+
+Create a draft entry:
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"data":{"title":"Hello","slug":"hello"},"lang":"en"}' \
+  "https://your-site.com/admin/api/rest/collections/posts"
+```
+
+Update an existing draft:
+
+```bash
+curl -s -X PUT \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"data":{"title":"Hello, world"},"lang":"en"}' \
+  "https://your-site.com/admin/api/rest/collections/posts/2c1b9a8e-1234-4567-89ab-cdef01234567"
+```
+
+Publish an entry (per locale):
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $API_KEY" \
+  "https://your-site.com/admin/api/rest/entries/2c1b9a8e-1234-4567-89ab-cdef01234567/publish?lang=en"
+```
+
+Upload a media file:
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $API_KEY" \
+  -F "file=@./hero.jpg" \
+  "https://your-site.com/admin/api/rest/upload"
+```
+
+### Error responses
+
+REST errors return a JSON body with a stable `code` (`CmsError.code`) plus a human-readable `message`. Match on `code`, not `message`.
+
+| HTTP | `code` | When |
+|------|--------|------|
+| `400` | `INVALID_DATA` | Body fails Zod validation. `details` lists `field.path: message` per issue. |
+| `400` | `MISSING_REQUIRED_PARAM` | Required query/body param missing (e.g. `collection`). |
+| `401` | `UNAUTHORIZED` | Missing/expired API key, or `Authorization` header malformed. |
+| `403` | `FORBIDDEN` | Key role insufficient for operation, or CSRF check failed. |
+| `404` | `ENTRY_NOT_FOUND` | Resource ID doesn't exist or isn't visible at the requested locale/status. |
+| `404` | `ENTRY_VERSION_NOT_FOUND` | Entry exists but has no version for that locale/status. |
+| `409` | `ENTRY_NOT_RETRIABLE` | Operation conflicts with current state (e.g. publishing an archived entry). |
+| `422` | `CONFIG_VALIDATION_FAILED` | Request implicitly references a misconfigured collection/field. |
+| `429` | `RATE_LIMITED` | Per-IP limit exceeded. `Retry-After` header included. |
+| `500` | `INTERNAL_ERROR` | Unhandled error. Check server logs; the response intentionally omits internals. |
+
+Example error body:
+
+```json
+{
+  "code": "INVALID_DATA",
+  "message": "Invalid data: title.length: must be at least 3 characters",
+  "details": [
+    { "path": "title", "message": "must be at least 3 characters" }
+  ]
+}
+```
+
 ## Entity API
 
 Server-side programmatic CRUD — for scripts, migrations, seeds, webhooks.
 
 ```typescript
-import { createEntityAPI } from 'includio-cms/entity';
+import { createEntityAPI } from 'includio-cms/core';
 import { getCMS } from 'includio-cms/core';
 
 const cms = getCMS();
@@ -4300,6 +4978,8 @@ Options for `create`/`createAndPublish`: `{ skipValidation?, sortOrder?, lang? }
 
 > **Delete Restrictions:** Only archived entries can be permanently deleted. Call `archive` first, then `delete`.
 
+For error handling patterns (`CmsError`, `instanceof`-based branching), see [Entries — Error handling](/docs/entries#error-handling).
+
 
 ---
 
@@ -4499,21 +5179,58 @@ For fully custom designs, use `createOrderState` — a reactive Svelte 5 state o
 
 # Retry payment
 
-When a payment attempt is rejected or left hanging, the customer must be able to try again without going through checkout a second time.
+When a payment attempt is rejected or left hanging, the customer must be able to try again without going through checkout a second time. This page documents the lifecycle, the API, and the failure modes.
 
 ## Lifecycle
 
-1. Customer completes checkout → order created with status `awaitingPayment`, adapter creates a payment session, `paymentProviderRef` stored.
-2. Something goes wrong — customer cancels on gateway, card declined, session expires → webhook flips status to `paymentRejected` (or stays `awaitingPayment` if the gateway never called back).
-3. Customer hits "Zapłać ponownie" on the order view.
-4. `POST /api/shop/orders/[number]/retry-payment?token=...` →
-   - token-gated, status must be `awaitingPayment` or `paymentRejected` (409 otherwise)
-   - adapter's `createPayment()` is called again with the same `OrderRef`
-   - new `paymentProviderRef` replaces the old one
-   - if coming from `paymentRejected`, status rolls back to `awaitingPayment` (logged in status history as `changedBy: 'retry-payment'`)
-   - response contains `redirectUrl` for the new gateway session
+1. **Checkout completes.** Order created with status `awaitingPayment`. The payment adapter's `createPayment()` is called and `paymentProviderRef` is stored on the order.
+2. **Something goes wrong:**
+   - Customer abandons the gateway → status stays `awaitingPayment`.
+   - Customer cancels on the gateway → webhook flips status to `paymentRejected`.
+   - Card declined → webhook flips status to `paymentRejected`.
+   - Gateway session expires before payment → status stays `awaitingPayment` indefinitely (no automatic timeout; let the customer retry or the admin cancel).
+3. **Customer clicks "Zapłać ponownie"** on the token-gated order view.
+4. **Retry endpoint runs:**
+   - `POST /api/shop/orders/[number]/retry-payment?token=...`
+   - Token validated, status must be `awaitingPayment` or `paymentRejected`.
+   - Adapter's `createPayment()` is called again with the same `OrderRef` — the order, items, totals, and order number are reused.
+   - New `paymentProviderRef` replaces the old one.
+   - If the previous status was `paymentRejected`, status rolls back to `awaitingPayment` (logged in `order_status_history` with `changedBy: 'retry-payment'`).
+   - Response contains `redirectUrl` for the new gateway session.
+5. **Webhook eventually settles.** New attempt either succeeds (`paid`) or fails again (`paymentRejected`, retry available).
+
+```
+┌──────────────────┐  customer cancels   ┌──────────────────┐
+│ awaitingPayment  ├────────────────────▶│ paymentRejected  │
+└────────┬─────────┘                     └────────┬─────────┘
+         │                                        │
+         │ retry-payment                          │ retry-payment
+         │ (new providerRef, same order)          │ (rollback to awaitingPayment)
+         ▼                                        ▼
+   ┌──────────────────┐    webhook ok    ┌──────────────────┐
+   │  paid            │◀─────────────────┤ awaitingPayment  │
+   └──────────────────┘                  └──────────────────┘
+```
+
+## Server endpoint
+
+The endpoint is scaffolded by `includio scaffold admin` into your app. Default location: `src/routes/api/shop/orders/[number]/retry-payment/+server.ts`. It calls `retryPayment(orderNumber, token)` from the shop server module:
+
+```ts
+// src/routes/api/shop/orders/[number]/retry-payment/+server.ts
+import { json, error } from '@sveltejs/kit';
+import { retryPayment } from 'includio-cms/shop';
+
+export const POST = async ({ params, url }) => {
+  const token = url.searchParams.get('token');
+  if (!token) throw error(400, 'Missing token');
+
+  const result = await retryPayment(params.number, token);
+  return json(result);
+};
+```
 
-## SDK
+## Headless SDK
 
 ```ts
 import { createShopClient } from 'includio-cms/shop/client';
@@ -4528,23 +5245,53 @@ if (result.requiresPaymentRedirect && result.redirectUrl) {
 
 ## With `createOrderState`
 
-The headless helper handles the redirect for you — it returns the URL, you navigate:
+The headless helper exposes a `retry()` method that returns just the redirect URL. You navigate:
 
-```ts
-const url = await order.retry();
-if (url) window.location.href = url;
+```svelte
+<button onclick={payAgain} disabled={!order.canRetry}>Zapłać ponownie</button>
+```
+
+## Error responses
+
+The endpoint returns standard HTTP statuses with stable codes (`CmsError.code`). Match on `code`, not message text.
+
+| HTTP | Code | When |
+|---|---|---|
+| `400` | `MISSING_REQUIRED_PARAM` | Order has no payment method, or adapter was removed from config. |
+| `401` | `UNAUTHORIZED` | Token missing or doesn't match the order. |
+| `404` | `ENTRY_NOT_FOUND` | Order number doesn't exist. |
+| `409` | `ORDER_NOT_RETRIABLE` | Status is terminal (`paid`, `done`, `cancelled`) — retry is impossible. |
+| `429` | `RATE_LIMITED` | Per-IP retry limit exceeded (default 5 retries / hour per IP). |
+| `502` | `PAYMENT_PROVIDER_ERROR` | Adapter's `createPayment()` threw. Body includes `details.providerMessage` if available. |
+
+Example error body for a terminal-status retry:
+
+```json
+{
+  "code": "ORDER_NOT_RETRIABLE",
+  "message": "Order is already paid; retry is not allowed",
+  "details": { "currentStatus": "paid" }
+}
 ```
 
 ## Constraints
 
-- The same order is reused — numbers, tokens, items, totals stay the same.
-- Terminal statuses (`paid`, `done`, `cancelled`) block retry with **409**.
-- Orders without a payment method or whose adapter was removed from config return **400**.
-- Adapter errors bubble up as **502**.
+- **Same order, same totals.** Retry never recalculates prices, taxes, or shipping. If you need a price update, cancel and let the customer re-checkout.
+- **Token-gated.** The token comes from the order confirmation email. Without it, the endpoint returns 401 even for a logged-in customer — by design (orders are guest-flow first).
+- **Rate-limited per IP.** Default 5 retries per hour. Override with `INCLUDIO_FORM_RATE_LIMIT_*` env vars or a custom `rateLimitGuard` store. See [Security Model — Rate Limiting](/docs/security#rate-limiting).
+- **Idempotent at the gateway.** Each retry produces a new `paymentProviderRef`. Old refs are not cancelled at the gateway — they expire on their own (provider-specific, typically 30 min).
+- **No automatic retries.** The system never retries on the customer's behalf. If a webhook is missed, the customer must click again. Background polling is a v1.x roadmap item.
 
 ## Admin override
 
-If the customer is completely stuck, the admin can manually move the order to `paid` / `cancelled` from the orders detail page — same as before, status-change emails trigger automatically.
+If a customer is stuck (e.g. webhook lost, retry limit hit, gateway down), an admin can manually move the order from the **Orders → detail** page:
+
+- **Mark as paid** — fires the same status-change email + invoice flow as a real success. Use only when payment was confirmed out-of-band.
+- **Cancel** — releases stock reservation, sends cancellation email, status `cancelled` (terminal). Customer cannot retry afterwards.
+
+Status changes from the admin are logged in `order_status_history` with `changedBy: <admin user id>` for audit.
+
+> **Retry vs new order:** Retry reuses the order. If the customer wants to change items, addresses, or shipping method, cancel the order and start checkout again. There's no "edit then retry" flow — by design, to keep the audit trail clean.
 
 
 ---
@@ -4666,6 +5413,118 @@ Tracking number is updated whenever the webhook payload contains a non-null `tra
 `OrderStatus.svelte` (the built-in component) renders a "Śledzenie przesyłki" section automatically when the order has a `trackingNumber`. If you wrote a custom order view, read `order.trackingNumber` and `order.trackingUrl` from the order endpoint response and render them yourself.
 
 
+---
+
+# Stability Promise
+
+What's stable, what may change, and how breaking changes are introduced. Use this as the contract between Includio CMS and your code.
+
+## Semantic Versioning
+
+Includio CMS follows [Semantic Versioning 2.0](https://semver.org/) starting with `1.0.0`:
+
+| Bump | Trigger | Example |
+|---|---|---|
+| **MAJOR** (`1.0.0 → 2.0.0`) | Removed/renamed `@public` symbol, changed function signature, removed config option | Renaming `resolveEntry({ collection })` to `resolveEntry({ table })` |
+| **MINOR** (`1.0.0 → 1.1.0`) | New `@public` symbol, additive option, new optional adapter method | Adding `resolveEntries({ ..., search? })` |
+| **PATCH** (`1.0.0 → 1.0.1`) | Bug fix, internal refactor, doc/typing fix | Fixing a regression in `resolveEntry` cycle detection |
+
+Pre-1.0 releases (`0.x`) made breaking changes in any version — that ends with `1.0.0`.
+
+## API tags — three tiers of stability
+
+Every public symbol carries one of three JSDoc tags. The tag tells you how aggressively you can rely on it.
+
+> **Where to look:** Tags are emitted by `pnpm api:generate` into `API.md` (single source of truth for the public surface). Each entry on `API.md` shows its tag.
+
+### `@public` — semver-protected
+
+Stable. Will not break inside a major version. Removal or signature change requires a MAJOR bump and a migration guide entry.
+
+```ts
+/** @public */
+export function resolveEntry(opts: ResolveEntryOptions): Promise<Entry | null>;
+```
+
+Use freely in production code. Examples: `defineConfig`, `resolveEntry`, `resolveEntries`, `getCMS`, all `define*` helpers, all adapter factories (`pg`, `local`, `nodemailerAdapter`, `openAIAdapter`, `claudeAdapter`).
+
+### `@experimental` — opt-in to change
+
+May change without a MAJOR bump. Ships in a MINOR or PATCH if usage feedback prompts a redesign. Always documented in `CHANGELOG.md` even when it changes.
+
+```ts
+/** @experimental Plugin hooks API — signature may change before 2.0. */
+export interface PluginHooks { /* ... */ }
+```
+
+Use in production at your discretion. Pin the patch version (e.g. `"includio-cms": "1.4.7"` instead of `"^1.4.0"`) if you want to lock against silent changes.
+
+### `@internal` — outside the contract
+
+Not part of the public surface. May change in any release. **Do not import directly** — TypeScript will allow it, but `API.md` does not list these and CHANGELOG does not announce changes.
+
+```ts
+/** @internal */
+export function _populate(/* ... */) { /* ... */ }
+```
+
+Internal symbols use a leading underscore by convention (`_resolveEntry`, `_getRawEntry`).
+
+## Deprecation timeline
+
+When a `@public` symbol needs to go away, the deprecation flow is:
+
+1. **MINOR release** — symbol is annotated `@deprecated` in JSDoc and continues to work. CHANGELOG calls out the deprecation and points to the replacement.
+2. **At least one MINOR cycle later** — the symbol can be removed in the next MAJOR release. Migration guide entry is mandatory.
+
+```ts
+/**
+ * @public
+ * @deprecated Since 1.4.0. Use `resolveEntry({ collection })` instead. Removed in 2.0.0.
+ */
+export function getEntry(opts: GetEntryOptions): Promise<Entry | null>;
+```
+
+> **Pre-1.0 exception:** Some breaking changes between 0.16.0 and 0.22.0 were introduced as **hard removes** (no deprecated wrapper) — consistent with the lean v1.0 policy of "all breaking before v1.0". See the [Migration Guide](/docs/migration) for find-replace patterns.
+
+## What is _not_ part of the contract
+
+These can change in any release without notice:
+
+- File paths under `src/lib/**` (only `package.json` exports map is contractual)
+- Internal helpers with `_` prefix or `@internal` JSDoc
+- Database migrations between minor versions (run `pnpm db:push` after upgrading)
+- The exact wording of error messages — only `CmsError.code` is stable
+- HTML structure of admin UI (admin is a finished surface, not a customizable theme)
+- Implementation details of bundled adapters (`db-postgres`, `files-local`, etc.) — only the `DatabaseAdapter` / `FilesAdapter` interfaces are contractual
+
+## How to consume Includio CMS safely
+
+```json
+{
+  "dependencies": {
+    "includio-cms": "^1.0.0"
+  }
+}
+```
+
+- `^1.0.0` accepts all PATCH and MINOR. Never accepts MAJOR.
+- Pin to exact `1.0.0` if relying on `@experimental` symbols.
+- After `pnpm update`, run `pnpm db:push` and re-run integration tests.
+
+## Reference: public surface
+
+The current public surface is auto-generated and lives in `API.md` at the repo root. Browse it before relying on a symbol — if it's not there, it's not `@public`.
+
+```bash
+pnpm api:generate
+```
+
+Outputs a tree of every exported symbol grouped by entry point (`includio-cms`, `includio-cms/core`, `includio-cms/sveltekit`, `includio-cms/db-postgres`, etc.) with its tag.
+
+See also: [Migration Guide](/docs/migration), [Adapter Contracts](/docs/adapters).
+
+
 ---
 
 # Migration Guide
@@ -4685,6 +5544,170 @@ Version-by-version upgrade guide. Each section lists what changed, what to do, a
 
 ---
 
+## Migrating from 0.x to 1.0 — master cheatsheet
+
+If you're jumping from 0.15.x straight to a v1.0 release, this section is the consolidated set of breaking changes between 0.16.0 and 0.22.0. Sections below the cheatsheet cover the older 0.7–0.15 changes for reference.
+
+### Global find-replace (0.18.0)
+
+The single biggest churn is the entry resolver rename. Run these find-replace passes across your project:
+
+| Find | Replace |
+|---|---|
+| `getEntry({ slug:` | `resolveEntry({ collection:` |
+| `getEntries({ slug:` | `resolveEntries({ collection:` |
+| `language:` (inside resolver options) | `locale:` |
+| `import { getEntry, getEntries } from 'includio-cms` | `import { resolveEntry, resolveEntries, countEntries } from 'includio-cms` |
+| `getEntryOrThrow(opts)` | `const e = await resolveEntry(opts); if (!e) throw new Error('Entry not found');` |
+
+`status: 'archived'` is no longer valid in resolvers — call `archiveEntryCommand(id)` / `unarchiveEntryCommand(id)` instead.
+
+### 0.16.0 — Hard reset
+
+**Breaking.** Removed unused prototypes: `src/lib/inline-edit-proto/*`, `src/lib/demo/seed.ts`, demo routes (`/demo/*`, `/admin/demo/*`), `ROADMAP-EDITOR.md`. None of these were ever in `package.json` exports — if your code didn't import them, no action needed.
+
+### 0.18.0 — Entry resolver consolidation
+
+**Breaking.** Hard-removed from public API: `getEntry`, `getEntries`, `getEntryOrThrow`, `getRawEntry`, `getRawEntries`, `getRawEntryOrThrow`, `getDbEntry`, `getDbEntries`, `populateEntryData`. Replaced by canonical `resolveEntry` / `resolveEntries` / `countEntries`.
+
+What changed in the call shape:
+
+| Old | New |
+|---|---|
+| `getEntry({ slug, id, language, status })` | `resolveEntry({ collection: slug, id, locale: language, status })` |
+| `getEntries({ slug, language, status, ids?, limit?, offset? })` | `resolveEntries({ collection: slug, locale: language, status, ids?, limit?, offset? })` |
+| `populateEntryData(...)` | INTERNAL — admin preview uses internal helpers |
+
+Other behavior changes:
+
+- `status` enum narrowed: removed `'archived'`. Use archive operations instead.
+- `PopulateConfig` is now an explicit option for opt-out (`populate: { fields: { author: false } }`) and depth caps (`populate: { maxDepth: 1 }`). Default is full populate with `maxDepth: 5`.
+- Plugin `populateResolver(value, field)` got a third arg: `populateResolver(value, field, ctx: PopulateCtx)`. `ctx` carries locale, status, depth, visited, populate config, entryId. Add the third arg even if you ignore it.
+
+```typescript
+// Before (0.16)
+import { getEntry, getEntries } from 'includio-cms/server';
+const post = await getEntry({ slug: 'posts', id: postId, language: 'pl' });
+const all  = await getEntries({ slug: 'posts', language: 'pl', limit: 10 });
+
+// After (0.18+)
+import { resolveEntry, resolveEntries } from 'includio-cms/server';
+const post = await resolveEntry({ collection: 'posts', id: postId, locale: 'pl' });
+const all  = await resolveEntries({ collection: 'posts', locale: 'pl', limit: 10 });
+```
+
+### 0.19.0 — Adapter peers go optional
+
+**Breaking.** `@anthropic-ai/sdk`, `nodemailer`, `openai` moved from `dependencies` to `peerDependenciesMeta.optional`. `runed` changed from optional to **required** peer.
+
+What you need to do:
+
+```bash
+# Required for everyone (now hard-required peer)
+pnpm add runed
+
+# Install only if you use the matching adapter
+pnpm add nodemailer            # email-nodemailer
+pnpm add openai                # ai-openai
+pnpm add @anthropic-ai/sdk     # ai-claude
+```
+
+Adapter factories (`pg`, `local`, `nodemailerAdapter`, `openAIAdapter`, `claudeAdapter`) are now `@public` and stable. SDK imports inside the adapters are lazy — installing the SDK is only required when the adapter is actually used at runtime.
+
+### 0.20.0 — API surface lock
+
+**Breaking.** Package exports trimmed from 26 entry points to 16. JSDoc tags (`@public` / `@experimental` / `@internal`) added across the public API. Auto-generated `API.md` is the new single source of truth.
+
+Most-affected import paths (full list of 10 removed/merged paths in [API.md](../API.md)):
+
+| Removed/changed | Replacement |
+|---|---|
+| `includio-cms/admin/*` (wildcard) | `includio-cms/admin/client`, `includio-cms/admin/remote` |
+| `includio-cms/auth` | `includio-cms/core` |
+| `includio-cms/entity` | `includio-cms/core` |
+| `includio-cms/shop/svelte` | `includio-cms/shop/client` |
+| `includio-cms/db-postgres/schema-*` | `includio-cms/db-postgres` |
+| `includio-cms/admin/api/*` | (internal — removed) |
+| `includio-cms/updates` | (internal — removed) |
+
+Run `pnpm check` after upgrading — TypeScript flags every stale import.
+
+### 0.21.0 — Security hardening
+
+**Feature.** No code changes required to consume the new defaults, but you should review them:
+
+- API keys gain optional `expiresAt` (ISO-8601) and audit-only `rotatedAt`. Without `expiresAt`, the key never expires — opt in if you want rotation.
+- Sharp calls (image processing) wrapped in 30-second timeout. Override with `INCLUDIO_SHARP_TIMEOUT_MS`.
+- Form submission rate limit refactored to use shared `MemoryRateLimitStore`. Configure with `INCLUDIO_FORM_RATE_LIMIT_MAX` / `INCLUDIO_FORM_RATE_LIMIT_WINDOW_MS`.
+- New file at repo root: `KNOWN-RISKS.md` — five accepted security trade-offs (CSP `'unsafe-inline'`, opt-in API key rotation, in-memory rate-limit store, Sharp timeout limits, ffmpeg/sharp CLI args). Read it before deploying to compliance-sensitive environments.
+
+See [Security Model](/docs/security) for the full picture.
+
+### 0.22.0 — DX & config validation
+
+**Breaking.** `defineConfig()` now runs strict Zod validation at boot. Configs that previously "worked" with subtle bugs throw `ConfigValidationError` on startup. Resolver and write operations throw typed `CmsError` (with stable `code` + `context`) instead of generic `Error`.
+
+Common config validation failures and fixes:
+
+- **Duplicate slug** — two collections (or singles, or forms) share a slug → make each unique within its category.
+- **Invalid language code** — `'ENGLISH'` → `'en'` (ISO-639-1, optionally with region: `'pl-PL'`).
+- **Multiple default locales** — only one `{ default: true }` allowed.
+- **Missing adapter method** — partial adapter stub → import the full `pg()` / `local()` or implement every required method.
+- **Invalid relation target** — `{ type: 'relation', collection: 'authors' }` while no `authors` collection exists → declare it or fix the target.
+
+Replace string-matching error catches with `code` matching:
+
+```typescript
+// Before
+catch (e) {
+  if ((e as Error).message === 'Entry not found') { /* 404 */ }
+}
+
+// After
+import { CmsError } from 'includio-cms';
+catch (e) {
+  if (e instanceof CmsError && e.code === 'ENTRY_NOT_FOUND') { /* 404 */ }
+}
+```
+
+Stable `CmsError.code` values: `ENTRY_NOT_FOUND`, `ENTRY_VERSION_NOT_FOUND`, `INVALID_DATA`, `MISSING_REQUIRED_PARAM`, `CONFIG_VALIDATION_FAILED`. See [Entries — Error handling](/docs/entries#error-handling).
+
+`.env.example` was reformatted with all `INCLUDIO_*` env vars (sharp timeout, rate limits, CSRF allowed origins). The demo-only `DEMO_USER_*` vars were removed.
+
+### Suggested upgrade path
+
+If you're on 0.15.x and want to land on the v1.0 release in one go:
+
+```bash
+# 1. Upgrade dependencies (pnpm flags missing peers)
+pnpm add includio-cms@latest
+pnpm add runed                       # required peer since 0.19.0
+pnpm add nodemailer openai           # if you use them
+
+# 2. Run TypeScript — fixes most breakage
+pnpm check
+# Fix every error: it's mechanical (find/replace patterns above)
+
+# 3. Sync DB
+pnpm db:push
+
+# 4. Run integration tests
+pnpm test
+
+# 5. Boot the dev server — strict config validation will surface any latent issues
+pnpm dev
+```
+
+If `defineConfig` throws at boot, read the bullet list — every issue has a `path` (e.g. `collections[1].slug`) and a `Hint:` line. Fix top-down; one issue often reveals the next.
+
+---
+
+## Pre-v1.0 deprecations and changes
+
+The sections below cover changes between 0.7 and 0.15. Useful only if you're on a much older release; otherwise skip.
+
+---
+
 ## New in 0.14.0 — Video Transcoding
 
 **Added:** Auto-transcode videos to mp4/webm, system info, disk usage.