includio-cms 0.20.0 → 0.22.0

package/API.md

@@ -1,8 +1,8 @@
-# includio-cms — Public API v0.20.0
+# includio-cms — Public API v0.22.0
 
 > Auto-generated by `scripts/generate-api-md.ts`. Do not edit by hand.
 
-Entry points: **15** · Stable: **345** · Experimental: **2**
+Entry points: **15** · Stable: **346** · Experimental: **2**
 
 Tags:
 - `@public` — frozen for v1.0; semver-protected.
@@ -13,19 +13,19 @@ Tags:
 
 ### `includio-cms`
 
-- `createEntityAPI(cms: CMS, opts?: EntityAPIOptions): <inferred>` — Creates a high-level Entity API (CRUD + publish/archive) bound to a CMS instance and a user.
+- `createEntityAPI(cms: CMS, opts?: EntityAPIOptions): <inferred>` — Creates a high-level Entity API (CRUD + publish/archive) bound to a CMS
 - `getAuth(): <inferred>` — Returns the underlying `better-auth` instance from the initialized CMS.
-- `getCMS(): CMS` — Returns the singleton CMS instance. Must be called after `includioCMS()` initializes the CMS in `hooks.server.ts`.
-- `interface ResolvedMedia`
-- `resolveMediaWithStyles(mediaIds: string[], styles?: ImageFieldStyle[]): Promise<Record<string, ResolvedMedia>>` — Resolve media files by IDs and generate image styles. Useful for plugins resolving media references (e.g. photo-grid).
+- `getCMS(): CMS` — Returns the singleton CMS instance. Must be called after `includioCMS()`
+- `interface ResolvedMedia` — Resolved media file plus its image styles + blur placeholder. Returned by
+- `resolveMediaWithStyles(mediaIds: string[], styles?: ImageFieldStyle[]): Promise<Record<string, ResolvedMedia>>` — Resolve media files by IDs and generate image styles. Useful for plugins or
 
 ### `includio-cms/core`
 
-- `createEntityAPI(cms: CMS, opts?: EntityAPIOptions): <inferred>` — Creates a high-level Entity API (CRUD + publish/archive) bound to a CMS instance and a user.
+- `createEntityAPI(cms: CMS, opts?: EntityAPIOptions): <inferred>` — Creates a high-level Entity API (CRUD + publish/archive) bound to a CMS
 - `getAuth(): <inferred>` — Returns the underlying `better-auth` instance from the initialized CMS.
-- `getCMS(): CMS` — Returns the singleton CMS instance. Must be called after `includioCMS()` initializes the CMS in `hooks.server.ts`.
-- `interface ResolvedMedia`
-- `resolveMediaWithStyles(mediaIds: string[], styles?: ImageFieldStyle[]): Promise<Record<string, ResolvedMedia>>` — Resolve media files by IDs and generate image styles. Useful for plugins resolving media references (e.g. photo-grid).
+- `getCMS(): CMS` — Returns the singleton CMS instance. Must be called after `includioCMS()`
+- `interface ResolvedMedia` — Resolved media file plus its image styles + blur placeholder. Returned by
+- `resolveMediaWithStyles(mediaIds: string[], styles?: ImageFieldStyle[]): Promise<Record<string, ResolvedMedia>>` — Resolve media files by IDs and generate image styles. Useful for plugins or
 
 ### `includio-cms/types`
 
@@ -239,11 +239,11 @@ Tags:
 ### `includio-cms/sveltekit`
 
 - `const CmsProvider: LegacyComponentType`
-- `defineCollection(config: CollectionInput): CollectionConfig` — Defines a collection (multi-entry content type).
+- `defineCollection(config: CollectionInput): CollectionConfig` — Defines a collection (multi-entry content type, e.g. blog posts, products).
 - `defineConfig(config: CMSConfig): CMSConfig` — Defines the root CMS configuration. Pass to `includioCMS()` in `hooks.server.ts`.
-- `defineForm(config: FormConfig): FormConfig` — Defines a public form (submitted via `/api/forms/[slug]/submit`).
-- `defineObject(config: Omit<ObjectField, 'type'>): ObjectField` — Defines a reusable object field (nested record). Use inside `fields[]`.
-- `defineSingle(config: SingleInput): SingleConfig` — Defines a singleton (single-entry content type, e.g. site settings).
+- `defineForm(config: FormConfig): FormConfig` — Defines a public form (submitted via `POST /api/forms/[slug]/submit`).
+- `defineObject(config: Omit<ObjectField, 'type'>): ObjectField` — Defines a reusable object field (nested record). Use inline inside `fields[]`
+- `defineSingle(config: SingleInput): SingleConfig` — Defines a singleton (single-entry content type, e.g. site settings, homepage).
 - `enableHybridEditing(): <inferred>` — Call in a layout/component script to enable data-hybrid-path rendering for all descendant HybridTarget/Image/Video.
 - `extractBlocks(doc: StructuredContentDoc, type?: string): SCNode[]` — Extract block-level nodes, optionally filtered by type.
 - `extractInlineBlocks(doc: StructuredContentDoc, blockType?: string): SCInlineBlockAttrs[]` — Extract inline block nodes, optionally filtered by blockType.
@@ -267,15 +267,16 @@ Tags:
 
 ### `includio-cms/sveltekit/server`
 
-- `cmsLayoutLoad(event: RequestEvent): <inferred>` — Returns `cmsContext` from `event.locals` for use in a SvelteKit layout `load`. Drop into your `+layout.server.ts`.
-- `countEntries(opts: CountEntriesOptions): Promise<number>` — Count entries matching the same filters as `resolveEntries`, without populating.
+- `cmsLayoutLoad(event: RequestEvent): <inferred>` — Returns `cmsContext` from `event.locals` for use in a SvelteKit layout
+- `countEntries(opts: CountEntriesOptions): Promise<number>` — Count entries matching the same filters as `resolveEntries`, without
 - `type CountEntriesOptions = Omit< ResolveEntriesOptions, 'limit' | 'offset' | 'populate' | 'orderBy' | 'dataOrderBy' >`
 - `const createConsentLog: <inferred>`
 - `const createFormSubmission: <inferred>`
-- `createRestApiHandler(): <inferred>` — REST API handler factory. Returns `{ GET, POST, PUT, DELETE }` `RequestHandler`s authenticated via `x-api-key` header. Mount in `src/routes/admin/api/rest/[...restPath]/+server.ts`.
-- `getPreviewEntry(event: RequestEvent, options: { language: string }): Promise<Entry | null>` — Resolves the preview entry from a `?preview=<versionId>` query param. Requires an authenticated session — throws `Unauthorized` otherwise.
-- `includioCMS(cmsConfig: CMSConfig): Handle[]` — SvelteKit `Handle[]` array that initializes the CMS, generates runtime artifacts, wires auth/admin guards, and exposes `event.locals.cmsContext`. Compose with `sequence()` in `hooks.server.ts`.
-- `parseFormDataForSubmission(formData: FormData, fields: FormField[]): Promise<Record<string, unknown>>` — Parses multipart `FormData` into a typed record of field values, handling file uploads via the configured files adapter.
+- `createRestApiHandler(): <inferred>` — REST API handler factory. Returns `{ GET, POST, PUT, DELETE }`
+- `generateApiKey(): string` — Generate a cryptographically random API key (32 bytes, base64url-encoded).
+- `getPreviewEntry(event: RequestEvent, options: { language: string }): Promise<Entry | null>` — Resolves the preview entry from a `?preview=<versionId>` query param.
+- `includioCMS(cmsConfig: CMSConfig): Handle[]` — SvelteKit `Handle[]` array that initializes the CMS, generates runtime
+- `parseFormDataForSubmission(formData: FormData, fields: FormField[]): Promise<Record<string, unknown>>` — Parses multipart `FormData` into a typed record of field values, handling
 - `type PopulateConfig = { /** Hard cap on relation depth. Default 5. Use `0` to keep all relations as raw IDs. */ maxDept...` — Recursion + per-field opt-out config for relation population.
 - `resolveEntries(opts: ResolveEntriesOptions): Promise<Entry[]>` — Fetch a list of populated Entries from a collection (or singleton with multiple instances).
 - `interface ResolveEntriesOptions`
@@ -386,7 +387,7 @@ Tags:
 ### `includio-cms/files-local`
 
 - `const fullDir: <inferred>`
-- `local(config?: LocalFilesConfig): FilesAdapter` — Local-disk files adapter. Stores uploads under `./static/uploads` (dev) or `/data/uploads` (prod).
+- `local(config?: LocalFilesConfig): FilesAdapter` — Local-disk files adapter. Stores uploads under `./static/uploads` (dev) or
 - `interface LocalFilesConfig`
 
 ### `includio-cms/email-nodemailer`

package/CHANGELOG.md

@@ -3,6 +3,153 @@
 All notable changes to includio-cms are documented here.
 Generated from `src/lib/updates/` — do not edit manually.
 
+## 0.22.0 — 2026-04-30
+
+Faza 9 — DX & config validation pass. `defineConfig()` waliduje config strict Zodem z czytelnymi błędami (path + hint), resolvery / operacje throwują typowane `CmsError` z `code` + `context`, CLI ma `--help` per subcommand i `--version`, README przepisany pod nowych userów (system requirements + 5-min quickstart), `.env.example` rozszerzony o wszystkie `INCLUDIO_*` envy, JSDoc na każdym `@public` symbolu (opis + `@param` + `@returns` + `@example`).
+
+### Added
+- `defineConfig()` (`includio-cms/sveltekit`) — runtime Zod validation z agregacją wszystkich błędów. Invalid config → `ConfigValidationError` (extends `CmsError`) z `issues[]` (path + message + hint), bullet-list message ready-to-paste do PR. `superRefine`: unique slugs (collections/singles/forms), default locale ≤ 1, relation targets w deklarowanych kolekcjach, `apiKeys[].permissions` referuje istniejące collection slugs.
+- `CmsError` + `ConfigValidationError` (`includio-cms` → `core/errors`) — bazowa klasa z `code` (SCREAMING_SNAKE_CASE), `context: Record<string, unknown>`, `cause?`. Stabilne kody: `ENTRY_NOT_FOUND`, `ENTRY_VERSION_NOT_FOUND`, `INVALID_DATA`, `MISSING_REQUIRED_PARAM`, `CONFIG_VALIDATION_FAILED`. `toString()` = `[CODE] message (k=v, k=v)`.
+- `formatZodDataIssues(error)` helper — render Zod errora z entry/form data jako lista `path: message`. Używany w `createEntryVersion`, `updateEntryVersion`, `createFormSubmission`.
+- CLI: `includio --help`, `includio scaffold admin --help`, `includio install-peers --help`, `includio create-user --help` — exit 0 + Usage/Options/Example block. `includio --version` / `-v` z `package.json`. Unknown command → exit 1 + top-level help.
+- `.env.example` rozszerzony — 11 envów z komentarzami i sekcjami (Required / Media & Uploads / Security & Rate Limits). Demo vars usunięte (były tylko dla `src/lib/demo/` skasowanego w Fazie 1).
+- README rebuild: TOC, sekcja **System requirements** (Node 18+, PG 14+, ffmpeg optional), 5-step **Quick start** (install → .env → config → scaffold → create-user → dev), poprawiony link do `DOCS.md`, dodana tabelka adapterów, sekcja CLI z subcommandami.
+- JSDoc bodies (opis + `@param` + `@returns` + `@example`) na każdym `@public` symbolu — `defineConfig`, `defineCollection`, `defineSingle`, `defineForm`, `defineObject`, `getCMS`, `resolveEntry`, `resolveEntries`, `countEntries`, `createFormSubmission`, `parseFormDataForSubmission`, `createConsentLog`, `resolveMediaWithStyles`, `createEntityAPI`, `createRestApiHandler`, `generateApiKey`, `getAuth`, `includioCMS`, `getPreviewEntry`, `cmsLayoutLoad`, factory adapterów (`pg`, `local`, `nodemailerAdapter`, `openAIAdapter`, `claudeAdapter`).
+
+### Fixed
+- `MISSING_REQUIRED_PARAM` zamiast `throw new Error('... is required')` w `resolveEntry` / `resolveEntries` / `countEntries`. Context zawiera `op` + `missing`.
+- `INVALID_DATA` zamiast `throw Error('Invalid data: ' + JSON.stringify(parsedData.error.flatten()))` w `createEntryVersion` / `updateEntryVersion` / `createFormSubmission`. Context zawiera `collection`/`entryId`/`lang` (entries) lub `formSlug` (forms). Body errora to czytelna lista `field.path: message`.
+- `ENTRY_NOT_FOUND` z `{ collection, id }` w `_getDbEntryOrThrow` / `_getRawEntryOrThrow`; `ENTRY_VERSION_NOT_FOUND` z `{ versionId, entryId, lang }` w `_getDbEntryVersionOrThrow`.
+
+### Breaking
+- **Strict config validation w `defineConfig`** — invalid configs które wcześniej "działały" w runtime (np. duplicate slug, brak default locale, relation do nieistniejącej kolekcji, brak metody w adapterze) **teraz throwują `ConfigValidationError` na starcie**. Najczęstsze przypadki + fix:
+  - **Duplicate slug**: dwie kolekcje/singles/forms z tym samym `slug` → unique slug per kategoria.
+  - **Invalid language code**: `code: 'ENGLISH'` → `code: 'en'` (ISO-639-1, opcjonalnie z regionem `'pl-PL'`).
+  - **Multiple default locales**: dwa `{ default: true }` → tylko jeden.
+  - **Missing adapter method**: stub adaptera bez `getEntries` etc. → zaimportuj pełen `pg()` / `local()` lub doimplementuj brakujące metody.
+  - **Invalid relation target**: `{ type: 'relation', collection: 'authors' }` przy braku kolekcji `authors` → dodaj kolekcję lub popraw target.
+- **Resolver / operation error format** — błędy z `resolveEntry` / `resolveEntries` / `countEntries` / `createEntryVersion` / `updateEntryVersion` / `createFormSubmission` rzucają teraz `CmsError` (extends `Error`). `error.message` zachowuje stary opis (przy `toString()` poprzedzony `[CODE]`) — string-matching `error.message === 'Entry not found'` może się rozjechać. **Migracja:**
+  ```ts
+  import { CmsError } from 'includio-cms';
+
+  try { await resolveEntry({ id }); }
+  catch (e) {
+    if (e instanceof CmsError && e.code === 'ENTRY_NOT_FOUND') { ... }
+  }
+  ```
+- **`.env.example` reformatted** — `DEMO_USER_EMAIL`, `DEMO_USER_PASSWORD`, `DEMO_RESET_KEY` usunięte (były tylko dla wewnętrznego demo skasowanego w Fazie 1). Jeśli polegałeś na nich → trzymaj w lokalnym `.env`, nie w `.env.example`.
+
+### Notes
+
+## Czytelność błędów config
+
+Po update — invalid config wyrzuci na starcie:
+
+```
+ConfigValidationError: CMSConfig validation failed (2 issues):
+  - languages[0]: must be a 2-letter ISO code (e.g. 'en' or 'pl-PL')
+  - collections[1].slug: duplicate collection slug 'posts' — Hint: each collection/single/form must have a unique `slug`
+```
+
+Każdy issue ma `path` (JS-notation: `collections[1].slug`, `apiKeys[0].permissions[2]`) i `message`. Tam gdzie da się rozsądnie zgadnąć, dochodzi `Hint:` z fix-suggestion.
+
+## Pattern: branchowanie po error code
+
+Stary kod string-matchujący po `error.message` musi się przepisać:
+
+```ts
+// PRZED
+catch (e) {
+  if ((e as Error).message === 'Entry not found') { /* 404 */ }
+}
+
+// PO
+import { CmsError } from 'includio-cms';
+catch (e) {
+  if (e instanceof CmsError && e.code === 'ENTRY_NOT_FOUND') { /* 404 */ }
+}
+```
+
+Dostępne kody w v0.22.0: `ENTRY_NOT_FOUND`, `ENTRY_VERSION_NOT_FOUND`, `INVALID_DATA`, `MISSING_REQUIRED_PARAM`, `CONFIG_VALIDATION_FAILED`.
+
+## Nowe envy (opt-in)
+
+Skopiuj `node_modules/includio-cms/.env.example` do swojego `.env` — domyślne wartości działają OOTB:
+
+- `INCLUDIO_SHARP_TIMEOUT_MS` (default 30000)
+- `INCLUDIO_RATE_LIMIT_MAX` / `INCLUDIO_RATE_LIMIT_WINDOW_MS` (default 200/60000)
+- `INCLUDIO_FORM_RATE_LIMIT_MAX` / `INCLUDIO_FORM_RATE_LIMIT_WINDOW_MS` (default 5/3600000)
+- `INCLUDIO_CSRF_ALLOWED_ORIGINS` (default: same-origin only)
+
+## CLI helpy
+
+```bash
+includio --help
+includio scaffold admin --help
+includio install-peers --help
+includio create-user --help
+includio --version
+```
+
+Brak SQL migration.
+
+## 0.21.0 — 2026-04-30
+
+Faza 5 część 2 — security finish: form rate-limit DRY refactor, API keys `expiresAt` / `rotatedAt`, sharp timeout 30s, `{@html}` audit close. `KNOWN-RISKS.md` w root jako single source of truth dla zaakceptowanych ryzyk v1.0. Plus: faza 6 setup — vitest coverage (info-only), docker test profile, integration test scaffolding (`tests/`).
+
+### Added
+- `KNOWN-RISKS.md` w root paczki — 5 ryzyk udokumentowanych: CSP `'unsafe-inline'`, API key rotation opt-in, in-memory rate-limit, sharp 30s timeout, ffmpeg/sharp args audit. Każde z mitygacją i triggerem fix.
+- `ApiKeyConfig.expiresAt?: string` (ISO-8601) — opt-in expiry, enforced w `validateApiKey()`. Wygasły klucz → 401 generic (no leak). Brak `expiresAt` = klucz nigdy nie wygasa (backward compat).
+- `ApiKeyConfig.rotatedAt?: string` — info-only audit-trail, nie enforced.
+- `generateApiKey()` (`includio-cms/sveltekit/server`) — crypto-random 32B base64url. Pełna rotacja = update `cms.config.ts` + redeploy (statyczny model, patrz KNOWN-RISKS §2).
+- `withTimeout<T>(promise, ms, label)` + `TimeoutError` (`$lib/server/utils/withTimeout`). Wrap dookoła wszystkich sharp calls (metadata, toBuffer, blur, admin thumbnail, downscale resize). Default 30s, env override `INCLUDIO_SHARP_TIMEOUT_MS`.
+- Form submit rate-limit: refaktor `src/routes/api/forms/[slug]/submit/+server.ts` — używa shared `MemoryRateLimitStore` z `$lib/server/security/rate-limit.js` (DRY z `/admin/api/*` rate-limit). Limity 5/h per IP zachowane. Env: `INCLUDIO_FORM_RATE_LIMIT_MAX`, `INCLUDIO_FORM_RATE_LIMIT_WINDOW_MS`.
+- Faza 6 setup: docker `test` profile (`db_test` na porcie 5434, tmpfs, `fsync=off`), `tests/helpers/{db,api,auth}.ts`, `tests/setup.ts` z TRUNCATE strategy, vitest project `integration` (sequential, `singleFork`), sanity test `tests/integration/db-sanity.spec.ts`.
+- Vitest coverage config (info-only, bez threshold) — `pnpm test:coverage` generuje `coverage/`. Reporter: text/json/html. Devdep: `@vitest/coverage-v8`.
+
+### Fixed
+- `{@html}` w `src/lib/admin/client/users/delete-user-dialog.svelte` (linie 85, 93) zastąpione safe Svelte template `{...}<strong>{...}</strong>{...}`. Defense-in-depth — content był admin-controlled, ale eliminuje wektor regresji XSS gdyby ktoś kiedyś dodał user-supplied input do tych komunikatów.
+
+### Breaking
+- Brak hard breakages. `ApiKeyConfig.expiresAt` / `rotatedAt` są opcjonalne — istniejące configi działają bez zmian.
+- `usersLang.deleteWarningDesc` zmienia sygnaturę z `(name: string) => string` na statyczny obiekt `{ before: string; after: string }`. `usersLang.deleteConfirmType` analogicznie ze stringa na `{ before: string; after: string }`. Wpływ tylko na fork'i admin UI z customowym lang — szybki `pnpm check` zwróci błąd typu, fix = przepisz wartości w lang.
+
+### Notes
+
+## Setup integration tests (opt-in)
+
+```bash
+docker compose --profile test up -d db_test
+pnpm prepack                    # buduje dist/ wymagany przez drizzle-kit push schema
+pnpm db:test:migrate            # drizzle-kit push do test DB
+pnpm test:integration           # uruchamia tests/integration/**
+docker compose --profile test down
+```
+
+## API key expiry (opt-in)
+
+```ts
+// cms.config.ts
+apiKeys: [
+    { key: 'sk-...', name: 'ci', role: 'admin', expiresAt: '2027-01-01T00:00:00Z' }
+]
+```
+
+Generowanie nowego klucza:
+
+```ts
+import { generateApiKey } from 'includio-cms/sveltekit/server';
+console.log(generateApiKey()); // → 43-char base64url, 32B entropii
+```
+
+Pełna rotacja wymaga update'u `cms.config.ts` + redeploy. Pole `rotatedAt` jest info-only (audit trail) — admin ustawia ręcznie przy rotacji.
+
+## Known risks
+
+Lista zaakceptowanych ryzyk v1.0 — `KNOWN-RISKS.md` w root paczki. 5 sekcji: CSP `unsafe-inline`, API key rotation opt-in, in-memory rate-limit (multi-node = wymaga Redis adapter), sharp 30s timeout, ffmpeg/sharp shell audit (SAFE).
+
+Brak SQL migration.
+
 ## 0.20.0 — 2026-04-29
 
 API Surface Lock — exports trim 26→15, JSDoc tagi (`@public`/`@experimental`/`@internal`), autogenerowany `API.md`. Powierzchnia publiczna zamrożona w v1.0 — w 1.x tylko `@experimental` może się zmienić bez breaking semver.

package/DOCS.md

@@ -1,4 +1,4 @@
-# Includio CMS Documentation (v0.20.0)
+# Includio CMS Documentation (v0.22.0)
 
 > This file is auto-generated from the docs site. For the latest version, update the package.
 

package/README.md

@@ -1,57 +1,149 @@
-# Includio CMS
+# includio-cms
 
-A headless CMS built for SvelteKit. Type-safe, extensible, with a modern admin interface.
+[![CI](https://github.com/includio/includio-cms/actions/workflows/ci.yml/badge.svg)](https://github.com/includio/includio-cms/actions/workflows/ci.yml)
+
+A headless CMS built for SvelteKit. Type-safe, extensible, with a modern admin interface and pluggable adapters for database, files, email, and AI.
+
+## Contents
+
+- [Features](#features)
+- [System requirements](#system-requirements)
+- [Quick start (5 minutes)](#quick-start-5-minutes)
+- [Configuration](#configuration)
+- [Adapters](#adapters)
+  - [Writing your own adapter](#writing-your-own-adapter)
+  - [Optional peer dependencies](#optional-peer-dependencies)
+- [CLI](#cli)
+- [Links](#links)
+- [For AI assistants](#for-ai-assistants)
+- [License](#license)
 
 ## Features
 
-- **19 field types** — text, structured content, media, relations, blocks, SEO, and more
+- **20 field types** — text, structured content, media, relations, blocks, SEO, URL, custom plugins, and more
 - **Structured content** — ProseMirror-based rich text with inline blocks, tables, media embeds
 - **Media management** — image styles (Sharp), video transcoding (ffmpeg), focal points, blur placeholders
-- **Per-language versioning** — independent draft/published/scheduled per language
+- **Per-language versioning** — independent draft / published / scheduled per language
 - **Layout DSL** — organize admin editor with sections, columns, cards, accordions
 - **Frontend components** — `<Image>`, `<Video>`, `<StructuredContent>`, `<Media>` for SvelteKit
 - **REST API** — API key auth, CRUD endpoints, schema introspection
 - **Entity API** — server-side programmatic CRUD for scripts, migrations, webhooks
 - **Code generation** — TypeScript types and Zod schemas from your content schema
-- **Pluggable adapters** — swap database, file storage, email, and AI providers
+- **Pluggable adapters** — swap database, file storage, email, AI provider
 - **Plugin system** — lifecycle hooks and custom field types
-- **Video transcoding** — auto-transcode to mp4/webm with background processing
+- **Strict config validation** — invalid configs throw a `ConfigValidationError` listing every issue with a path and a fix hint
+
+## System requirements
+
+- **Node.js** 18+ (20 LTS recommended)
+- **PostgreSQL** 14+ — required by the bundled `db-postgres` adapter; or write your own [`DatabaseAdapter`](#writing-your-own-adapter)
+- **ffmpeg + ffprobe** — optional, only required for video transcoding (set `FFMPEG_PATH` / `FFPROBE_PATH` if not on `PATH`)
+- A SvelteKit project (Kit ≥ 2.48, Svelte ≥ 5.43, Vite ≥ 7)
+
+## Quick start (5 minutes)
 
-## Quick Start
+The five steps below take you from `pnpm add` to a running admin at `/admin`.
+
+**1. Install:**
 
 ```bash
 pnpm add includio-cms
+pnpm dlx includio install-peers
+```
+
+**2. Configure environment:**
+
+```bash
+cp node_modules/includio-cms/.env.example .env
+# edit .env — set DATABASE_URL and BETTER_AUTH_SECRET
 ```
 
-```typescript
+Generate a secret:
+
+```bash
+openssl rand -hex 32
+```
+
+**3. Create `src/lib/cms/cms.config.ts`:**
+
+```ts
 import { defineConfig } from 'includio-cms/sveltekit';
 import { pg } from 'includio-cms/db-postgres';
 import { local } from 'includio-cms/files-local';
 
 export default defineConfig({
   languages: ['en'],
-  db: pg({ databaseUrl: process.env.DATABASE_URL }),
+  db: pg({ databaseUrl: process.env.DATABASE_URL! }),
   files: local(),
-  collections: [/* ... */],
+  auth: { secret: process.env.BETTER_AUTH_SECRET! },
+  collections: []
 });
 ```
 
-See the [full documentation](/docs) for installation, configuration, and usage.
+**4. Scaffold admin routes + create a user:**
 
-## Writing your own adapter
+```bash
+pnpm dlx includio scaffold admin
+pnpm dlx includio create-user
+```
 
-`includio-cms` ships with default adapters (`db-postgres`, `files-local`, `email-nodemailer`, `ai-openai`, `ai-claude`). Each is a factory returning an object that implements a `@public` contract from `includio-cms/types`. Build your own by implementing the same interface — TypeScript will enforce the surface.
+**5. Run the dev server:**
 
-Four adapter contracts:
+```bash
+pnpm dev
+```
 
-- `DatabaseAdapter` — entries, versions, media, tags, form submissions, consent logs.
-- `FilesAdapter` — file upload/download/list, optional private files (e.g. shop receipts).
-- `EmailAdapter` — `sendMail`, default from address/name.
-- `AIAdapter` — currently `generateAltText(fileId)`.
+Open `http://localhost:5173/admin` and sign in with the user you just created.
+
+> Need more? Full reference in [`DOCS.md`](./DOCS.md). API surface in [`API.md`](./API.md).
+
+## Configuration
+
+`defineConfig({ ... })` is your single source of truth. The shape (abridged):
+
+```ts
+defineConfig({
+  languages: ['en', 'pl'],   // first entry is the default locale
+  db, files,                 // required adapters
+  email, ai,                 // optional adapters
+  auth: { secret },          // required for /admin
+  collections: [postsCollection],
+  singles:     [siteSettings],
+  forms:       [contactForm],
+  apiKeys:     [{ key: '...', role: 'admin' }],
+  media:       { /* sharp / video / maintenance options */ },
+  typography:  { fixOrphans: true },
+  shop, cmp                  // optional modules
+});
+```
+
+Invalid configs throw immediately at startup with every issue listed:
+
+```
+ConfigValidationError: CMSConfig validation failed (2 issues):
+  - languages[0]: must be a 2-letter ISO code (e.g. 'en' or 'pl-PL')
+  - collections[1].slug: duplicate collection slug 'posts'
+    — Hint: each collection/single/form must have a unique `slug`
+```
+
+See [`DOCS.md`](./DOCS.md) for every field type and option.
+
+## Adapters
+
+`includio-cms` ships four pluggable contracts. Each has a default implementation; bring your own when you need to.
+
+| Contract           | Default                | Lazy peer dep                |
+|--------------------|------------------------|------------------------------|
+| `DatabaseAdapter`  | `includio-cms/db-postgres` | `postgres`, `drizzle-orm`     |
+| `FilesAdapter`     | `includio-cms/files-local` | —                            |
+| `EmailAdapter`     | `includio-cms/email-nodemailer` | `nodemailer`             |
+| `AIAdapter`        | `includio-cms/ai-openai`, `includio-cms/ai-claude` | `openai`, `@anthropic-ai/sdk` |
 
 Source of truth: [`src/lib/types/adapters/`](src/lib/types/adapters/).
 
-### Minimal custom DB adapter (sketch)
+### Writing your own adapter
+
+Each contract is a TypeScript interface — implement every required method (optionals are marked `?`). TypeScript will enforce the surface.
 
 ```ts
 import type { DatabaseAdapter } from 'includio-cms/types';
@@ -68,7 +160,7 @@ export function myDbAdapter(config: { connection: string }): DatabaseAdapter {
     createEntryVersion: async (data) => { /* ... */ },
     updateEntryVersion: async (data) => { /* ... */ },
     getEntryVersions: async (data) => { /* ... */ },
-    deleteEntryVersion: async (data) => { /* ... */ },
+    deleteEntryVersion: async (data) => { /* ... */ }
     // ...form submissions, media files, image/video styles, tags, consent logs...
   };
 }
@@ -90,25 +182,39 @@ Reference implementation: [`src/lib/db-postgres/index.ts`](src/lib/db-postgres/i
 
 ### Optional peer dependencies
 
-The default email + AI adapters depend on third-party SDKs that **are not installed by default**. If you use them, install the peer:
+The default email + AI adapters depend on third-party SDKs that **are not installed by default**. Install the peer once you use the adapter:
+
+| Adapter            | Required peer       | Install                       |
+|--------------------|---------------------|-------------------------------|
+| `email-nodemailer` | `nodemailer`        | `pnpm add nodemailer`         |
+| `ai-openai`        | `openai`            | `pnpm add openai`             |
+| `ai-claude`        | `@anthropic-ai/sdk` | `pnpm add @anthropic-ai/sdk`  |
+
+Each SDK is loaded lazily on first call. A missing peer throws a clear error at runtime — install it and the adapter wakes up. `pnpm dlx includio install-peers` automates this for the parts of the CMS you have configured.
+
+## CLI
+
+The `includio` binary ships with three subcommands. Run any of them with `--help` for details.
 
-| Adapter                   | Required peer            | Install                                |
-| ------------------------- | ------------------------ | -------------------------------------- |
-| `email-nodemailer`        | `nodemailer`             | `pnpm add nodemailer`                  |
-| `ai-openai`               | `openai`                 | `pnpm add openai`                      |
-| `ai-claude`               | `@anthropic-ai/sdk`      | `pnpm add @anthropic-ai/sdk`           |
+| Command                  | What it does                                              |
+|--------------------------|-----------------------------------------------------------|
+| `includio scaffold admin`| Generates `/admin` and `/api/admin` route files          |
+| `includio install-peers` | Installs missing optional peer SDKs based on your config |
+| `includio create-user`   | Creates an admin/user account interactively              |
 
-Each SDK is loaded lazily on first call. Missing peer throws a clear error at runtime — install it and the adapter wakes up.
+Global flags: `--help, -h` and `--version, -v`.
 
 ## Links
 
-- [Full Documentation](DOCS.md)
-- [Changelog](CHANGELOG.md)
-- [Roadmap](ROADMAP.md)
+- [Full documentation](./DOCS.md)
+- [Public API surface](./API.md)
+- [Changelog](./CHANGELOG.md)
+- [Roadmap](./ROADMAP.md)
+- [Known risks](./KNOWN-RISKS.md)
 
-## For AI Assistants
+## For AI assistants
 
-Full documentation is in [`DOCS.md`](DOCS.md) (shipped with the npm package). When working on a project using includio-cms, read `node_modules/includio-cms/DOCS.md` for the complete API reference, available components, and migration guides.
+Full documentation is in [`DOCS.md`](./DOCS.md) (shipped with the npm package). When working on a project using includio-cms, read `node_modules/includio-cms/DOCS.md` for the complete API reference, available components, and migration guides.
 
 ## License
 

package/ROADMAP.md

@@ -339,6 +339,10 @@
 > 13 faz w ~16 sesjach, droga 0.16 → 1.0.0. Lean scope: stabilizacja, security, testy, docs, audit + polish shopa. Bez nowych feature'ów.
 
 - [x] `[breaking]` `[P0]` API surface lock — exports trim 26→15, JSDoc tagi (@public/@internal/@experimental), `API.md` autogenerated (0.20.0) <!-- files: package.json, scripts/generate-api-md.ts -->
+- [x] `[chore]` `[P1]` Faza 6 — Test foundation: docker postgres + integration project + 43 cases (30 REST + 6 shop checkout + 7 webhook signature/idempotency dla PayU/InPost), coverage report <!-- files: tests/integration/rest/, tests/helpers/{rest,shop}.ts, tests/integration/fixtures/shopConfig.ts, tests/setup.ts -->
+- [x] `[chore]` `[P1]` Faza 7 — E2E foundation: Playwright config (storageState reuse, setup project), `db_test_e2e` na 5435, `e2e/setup/global-setup.ts` (drizzle push), `e2e/admin/auth.setup.ts` (sign-up + admin role + login), 4 specy zielone w ~23s: login, collection-crud (blog-post create→edit→archive→permanent-delete), media-upload, user-mgmt (create→delete); data-testid na critical buttons admin <!-- files: playwright.config.ts, e2e/admin/*, src/lib/admin/client/{collection,entry,users}/, src/lib/admin/components/media/file-upload.svelte -->
+- [x] `[chore]` `[P1]` Faza 8 — CI na PR: `.github/workflows/ci.yml` z jobs lint/typecheck/unit/integration (postgres :5434)/e2e (postgres :5435 + playwright cache)/build, pnpm cache, trace artifacts on fail, README CI badge <!-- files: .github/workflows/ci.yml, README.md -->
+- [x] `[breaking]` `[P0]` Faza 9 — DX & config validation (0.22.0): `defineConfig` Zod strict z field path + hint, `CmsError` + `ConfigValidationError` z code/context, resolver throw sites zmigrowane, CLI `--help` per subcommand + `--version`, `.env.example` rozszerzony o `INCLUDIO_*`, README rebuild (TOC + system req + 5-min quickstart), JSDoc body (opis + @param + @returns + @example) na każdym `@public` <!-- files: src/lib/core/errors.ts, src/lib/types/cms.schema.ts, src/lib/sveltekit/config.ts, src/lib/cli/index.ts, README.md, .env.example, src/lib/updates/0.22.0/ -->
 - [ ] `[fix]` `[P1]` Select field — `defaultValue` propagacja do zod schema (full repro: `ideas/post-v1/select-field-defaultvalue-bug.md`); fix planowany w Fazie 12 (RC)
 
 ## v1.x — Post-v1.0 deferred
@@ -354,10 +358,13 @@
 ## Security hardening
 
 - [ ] `[feature]` `[P1]` `sanitizeHTML` utility — general HTML sanitization outside richtext (text fields, SEO fields)
-- [ ] `[feature]` `[P1]` CSP headers — Content-Security-Policy middleware
-- [ ] `[feature]` `[P1]` CSRF protection — tokens for mutating operations
-- [x] `[feature]` `[P1]` Rate limiting — form submit endpoints (done in 0.13.3; admin/auth endpoints remaining)
-- [x] `[chore]` `[P1]` Security audit — timing attacks, MIME validation, demo endpoint, rate limiting (done in 0.13.3; `{@html}` review remaining)
+- [x] `[feature]` `[P1]` CSP headers — Content-Security-Policy middleware (0.20.0/0.21.0; `unsafe-inline` zaakceptowany — KNOWN-RISKS §1)
+- [x] `[feature]` `[P1]` CSRF protection — origin/referer guard na `/admin/api/*` (0.20.0/0.21.0)
+- [x] `[feature]` `[P1]` Rate limiting — form submit + `/admin/api/*` (form 0.13.3, admin 0.20.0, DRY refactor 0.21.0)
+- [x] `[chore]` `[P1]` Security audit — timing attacks, MIME, demo endpoint, rate limiting, `{@html}` w admin UI, ffmpeg/sharp shell args (0.13.3 + 0.21.0)
+- [x] `[feature]` `[P1]` API key expiry (opt-in `expiresAt`) + `generateApiKey()` helper (0.21.0; pełna rotacja = manual config + redeploy, KNOWN-RISKS §2)
+- [x] `[feature]` `[P1]` Sharp timeout 30s (`withTimeout` + `INCLUDIO_SHARP_TIMEOUT_MS`, 0.21.0)
+- [x] `[chore]` `[P0]` `KNOWN-RISKS.md` — single source of truth dla zaakceptowanych ryzyk v1.0 (0.21.0)
 - [ ] `[chore]` `[P1]` Input sanitization audit — review all fields for XSS
 
 ## Backlog

package/dist/admin/api/rest/handler.d.ts

@@ -1,7 +1,19 @@
 import { type RequestHandler } from '@sveltejs/kit';
 /**
- * REST API handler factory. Returns `{ GET, POST, PUT, DELETE }` `RequestHandler`s authenticated via `x-api-key` header. Mount in `src/routes/admin/api/rest/[...restPath]/+server.ts`.
+ * REST API handler factory. Returns `{ GET, POST, PUT, DELETE }`
+ * `RequestHandler`s authenticated via the `x-api-key` header. Mount in
+ * `src/routes/admin/api/rest/[...restPath]/+server.ts`.
+ *
+ * @returns An object with `GET`, `POST`, `PUT`, `DELETE` SvelteKit
+ *   `RequestHandler`s, ready to re-export from a `+server.ts` route.
  * @public
+ * @example
+ * ```ts
+ * // src/routes/admin/api/rest/[...restPath]/+server.ts
+ * import { createRestApiHandler } from 'includio-cms/admin/remote';
+ *
+ * export const { GET, POST, PUT, DELETE } = createRestApiHandler();
+ * ```
  */
 export declare function createRestApiHandler(): {
     GET: RequestHandler;

package/dist/admin/api/rest/handler.js

@@ -50,8 +50,20 @@ function matchRoute(method, path) {
     return null;
 }
 /**
- * REST API handler factory. Returns `{ GET, POST, PUT, DELETE }` `RequestHandler`s authenticated via `x-api-key` header. Mount in `src/routes/admin/api/rest/[...restPath]/+server.ts`.
+ * REST API handler factory. Returns `{ GET, POST, PUT, DELETE }`
+ * `RequestHandler`s authenticated via the `x-api-key` header. Mount in
+ * `src/routes/admin/api/rest/[...restPath]/+server.ts`.
+ *
+ * @returns An object with `GET`, `POST`, `PUT`, `DELETE` SvelteKit
+ *   `RequestHandler`s, ready to re-export from a `+server.ts` route.
  * @public
+ * @example
+ * ```ts
+ * // src/routes/admin/api/rest/[...restPath]/+server.ts
+ * import { createRestApiHandler } from 'includio-cms/admin/remote';
+ *
+ * export const { GET, POST, PUT, DELETE } = createRestApiHandler();
+ * ```
  */
 export function createRestApiHandler() {
     function handle(method) {

package/dist/admin/api/rest/middleware/apiKey.js

@@ -14,7 +14,15 @@ function safeEqual(a, b) {
 }
 export function validateApiKey(key) {
     const cms = getCMS();
-    return cms.apiKeys.find((k) => safeEqual(k.key, key)) ?? null;
+    const found = cms.apiKeys.find((k) => safeEqual(k.key, key));
+    if (!found)
+        return null;
+    if (found.expiresAt) {
+        const exp = Date.parse(found.expiresAt);
+        if (Number.isFinite(exp) && exp < Date.now())
+            return null;
+    }
+    return found;
 }
 export function setSyntheticUser(event, apiKey) {
     const name = apiKey.name || 'api';

package/dist/admin/api/rest/middleware/generateApiKey.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generate a cryptographically random API key (32 bytes, base64url-encoded).
+ * Use the result for `ApiKeyConfig.key`. Full rotation requires updating
+ * `cms.config.ts` and redeploying — see `KNOWN-RISKS.md` §2.
+ *
+ * @returns A 43-character base64url string (no padding).
+ * @public
+ * @example
+ * ```ts
+ * import { generateApiKey } from 'includio-cms/admin/remote';
+ *
+ * const key = generateApiKey();
+ * console.log(key); // 'A1b2C3...xYz'
+ * ```
+ */
+export declare function generateApiKey(): string;

package/dist/admin/api/rest/middleware/generateApiKey.js

@@ -0,0 +1,19 @@
+import { randomBytes } from 'node:crypto';
+/**
+ * Generate a cryptographically random API key (32 bytes, base64url-encoded).
+ * Use the result for `ApiKeyConfig.key`. Full rotation requires updating
+ * `cms.config.ts` and redeploying — see `KNOWN-RISKS.md` §2.
+ *
+ * @returns A 43-character base64url string (no padding).
+ * @public
+ * @example
+ * ```ts
+ * import { generateApiKey } from 'includio-cms/admin/remote';
+ *
+ * const key = generateApiKey();
+ * console.log(key); // 'A1b2C3...xYz'
+ * ```
+ */
+export function generateApiKey() {
+    return randomBytes(32).toString('base64url');
+}

package/dist/admin/client/collection/collection-entries.svelte

@@ -897,7 +897,7 @@
 		>
 		<AlertDialog.Footer>
 			<AlertDialog.Cancel>{lang[interfaceLanguage.current].cancel}</AlertDialog.Cancel>
-			<AlertDialog.Action onclick={confirmDelete}
+			<AlertDialog.Action onclick={confirmDelete} data-testid="confirm-delete-entry"
 				>{lang[interfaceLanguage.current].delete}</AlertDialog.Action
 			>
 		</AlertDialog.Footer>

package/dist/admin/client/collection/empty-state.svelte

@@ -20,7 +20,7 @@
 	<h3 class="text-lg font-bold text-foreground mb-2">{title}</h3>
 	<p class="text-sm text-muted-foreground max-w-[360px] mb-6">{description}</p>
 	{#if ctaLabel && onCta}
-		<Button variant="default" onclick={onCta}>
+		<Button variant="default" onclick={onCta} data-testid="create-entry-button">
 			<Plus class="size-4 mr-1.5" />
 			{ctaLabel}
 		</Button>