@michaelthielemann/kestrel 3.0.0 → 4.0.0

package/README.md

@@ -1,5 +1,7 @@
 # Kestrel
 
+**Please be aware that this project is under rapid development and may not be suitable for long-term projects.**
+
 A slim, **static-site-generator CMS**: a generic collection-driven CRUD core with a schema-driven admin
 editor. You declare collections and fields in TypeScript; Kestrel derives the database, a typed CRUD API,
 and a full admin UI from those definitions, and renders published content to static HTML via
@@ -25,14 +27,9 @@ static host. It is deliberately **not**:
   output); everything else stays behind the admin guard. No per-request rate limiting / live API.
 - **No runtime redirect engine** — redirects are *authored* in the CMS and published as a `redirects.json`
   artifact, but Kestrel never answers a 30x itself; an edge (NGINX / njs / CloudFront) has to read it.
-- **No per-file access control on uploads.** The admin guard protects the media *library* — listing,
-  editing, deleting — but not the bytes. With `media.driver: 'local'` the files are served from the app
-  origin by Nitro's static handler, which runs ahead of every middleware, so anyone who knows a URL can
-  fetch it; the optional IP allow-list does not cover them either (see
-  [configuration.md](./docs/configuration.md#ip-allow-list--optional)). That is the intended model — the
-  editing origin is meant to be non-public, and published media is public by definition. If you deploy
-  Kestrel as a general-purpose CMS whose uploads must stay private, restrict them at the reverse proxy or
-  serve media from a private S3 bucket; the app will not do it for you.
+- **No per-file access control on uploads.** The admin guard protects the media *library*, not the
+  bytes; the editing origin is meant to be non-public and published media is public by definition. See
+  [media.md](./docs/guide/media.md).
 
 ## Features
 
@@ -42,9 +39,10 @@ static host. It is deliberately **not**:
 - **Collection-driven** — declare collections + fields in TypeScript; Kestrel derives the SQLite tables, a
   typed CRUD REST API, and the full admin UI. The schema **migrates itself** (additive in dev; explicit
   `db:migrate` in prod).
-- **Field types** — text, textarea, rich-text, number, boolean, choice (select / buttons / checkboxes),
-  date / time, media, relation (single / many), link (internal / external / email / tel), repeater
-  (nestable), JSON — plus per-field `condition` visibility rules.
+- **Field types** — twelve built in: text (single- or multi-line), slug, richtext, number, boolean,
+  datetime (date / time / range), choice (select / buttons / checkboxes), media, relation (single /
+  many), link (internal / external / email / tel), repeater (nestable), JSON — plus per-field `condition`
+  visibility rules. Register your own with `defineFieldType`.
 - **Page-like collections** — give a collection a `path`, SEO meta, and block or flat content; published
   records render to static HTML and join the sitemap. **Singletons** for settings / navigation.
 - **Block page-builder** — a 3-pane editor (tree · live preview · fields) with nestable block slots; each
@@ -119,48 +117,34 @@ content at `/admin`. You bring your own **public layout** and **block SFCs**
 > the file `nuxi init` writes renders `<NuxtWelcome />` instead of your routes — the admin then appears to
 > be missing rather than blank. Kestrel reports this at build time; `kestrel doctor` catches it earlier.
 
-Full guide: **[consuming-kestrel.md](docs/consuming-kestrel.md)**.
+Full walkthrough: **[getting-started.md](docs/guide/getting-started.md)**.
 
 ## Documentation
 
-Start with the **[architecture guide](docs/architecture.md)** — a per-layer map (what each layer owns,
-where to start reading, the cross-layer seams, the gotchas). Then the per-topic docs:
-
-| Doc | Covers |
-|-----|--------|
-| [architecture.md](docs/architecture.md) | **Start here** — the layer model, boot order, cross-cutting seams, per-layer guide |
-| [field-types.md](docs/field-types.md) | Every built-in field type with its options, the column it becomes, what the server enforces vs. what only configures the widget |
-| [consuming-kestrel.md](docs/consuming-kestrel.md) | Using Kestrel in your own app: defining collections/fields/blocks, auto-discovery, the schema lifecycle |
-| [configuration.md](docs/configuration.md) | The single config source (`kestrel.config.ts`), every `KESTREL_*` env var, the auth/session env split |
-| [block-editing.md](docs/block-editing.md) | The block content model + the 3-pane block editor (tree · preview · fields) |
-| [media-uploads.md](docs/media-uploads.md) | Ingest security, storage drivers (local/S3), responsive-image derivation, EU AI Act disclosure |
-| [multilingual.md](docs/multilingual.md) | Content locales, the editor locale flow, locale-prefixed routing |
-| [static-output.md](docs/static-output.md) | `nuxt generate` + the runtime incremental publisher, the live editor preview, `sitemap.xml` / `robots.txt` / `llms.txt` / `llms-full.txt`, the JSON-LD structured data, CMS-managed redirects, the optional S3 deploy |
-| [reference-integrity.md](docs/reference-integrity.md) | How writes invalidate the static site precisely, dead-reference warnings (a dead link renders `#`, and the editor is warned), and required/unique page slugs |
-| [architecture-decisions.md](docs/architecture-decisions.md) | ADRs (the collection-derived schema engine, reference integrity, the auth/password choice) |
+Two doors, one per audience:
+
+- **[Guide](docs/guide/README.md)** — building a site with the package: collections, fields, blocks,
+  media, publishing, deployment, configuration, extension points.
+- **[Internals](docs/internals/README.md)** — developing Kestrel itself: architecture, layers and
+  packages, the pipeline engine, test rails, releasing, the ADR log.
+
+Most-asked pages: [getting started](docs/guide/getting-started.md) ·
+[field types](docs/guide/field-types.md) · [blocks](docs/guide/blocks.md) ·
+[configuration](docs/guide/configuration.md) · [deploying](docs/guide/deploying.md) ·
+[troubleshooting](docs/guide/troubleshooting.md).
 
 ## Layout
 
-The CMS is split into Nuxt layers under `layers/`:
-
-- **`core`** — the collection/field model, the generic CRUD engine + REST API, def→JSON serialization,
-  the runtime schema-migration engine, config resolution, and the populate registry.
-- **`fields`** — turns a definition into Drizzle tables + Zod schemas (the field-type registry).
-- **`ui`** — the admin design system: schema-driven field widgets, generic primitives, tokens, i18n.
-- **`auth`** — single-user authentication (session cookie, scrypt password, login, CSRF).
-- **`access`** — authorization: a default-deny guard over the entire `/api/` surface + policy/grant registry.
-- **`collections`** — the toggleable built-in `pages` collection + the plugin that registers every
-  discovered collection/block. (Demo content — `posts`/`settings`, the `hero`/`prose` blocks, and a layout —
-  lives in the repo root, dev-only, and is **not** shipped in the package.)
-- **`media`** — uploads, pluggable storage, image derivation, the media library + asset viewer.
-- **`admin`** — the editor SPA: collection list, record editor, the 3-pane block editor.
-- **`public`** — the SSG render path: the catch-all page, `KestrelBlockRenderer`, the JSON-LD head, the literal-key
-  artifacts (sitemap / robots / llms.txt / llms-full.txt / redirects.json), deploy.
-
-`playground/` is a small consuming example. `templates/starter/` is what the scaffolder writes out;
-`scripts/kestrel.mjs` is the engine's CLI and `packages/create-kestrel/` the standalone
-`pnpm create kestrel` front end, which copies the same templates in at pack time rather than keeping
-its own.
+The domain/server code lives in ten `@michaelthielemann/kestrel-*` packages under `packages/` (`contracts`, `core`,
+`fields`, `auth`, `access`, `collections`, `media`, `publishing`, `delivery-live`, `delivery-static`).
+The nine Nuxt layers under `layers/` are thin wiring shells around those packages, except where a surface
+depends on Nuxt's own component resolution and auto-imports: the `ui` and `admin` layers (design system
+and editor SPA) and the `app/` halves of `media` and `public` stay real code in layers. Layers import
+packages by name; packages never import layers.
+
+`playground/` is a small consuming example, `templates/starter/` is what the scaffolder writes,
+`scripts/kestrel.mjs` is the CLI, and `packages/create-kestrel/` the `pnpm create kestrel` front end.
+The full map: [layers-and-packages.md](docs/internals/layers-and-packages.md).
 
 ## Development
 
@@ -185,68 +169,9 @@ node scripts/kestrel.mjs init <dir>   # the consumer scaffolder, from a checkout
 node scripts/kestrel.mjs doctor <dir> # diagnose a consumer project
 ```
 
-In dev, the schema auto-syncs from the collection definitions (additive changes only); production applies
-schema changes explicitly via the `db:migrate` task. See
-[architecture-decisions.md](docs/architecture-decisions.md) for the rationale.
-
-### Publishing the static site
-
-Two ways to produce the static output:
-
-- **One-shot:** `pnpm generate` → `.output/public` (the classic full rebuild).
-- **Runtime publisher (default):** a **production** run (`pnpm build && pnpm preview`, or
-  `node .output/server/index.mjs`) publishes on boot and incrementally re-publishes the affected pages when
-  you press **Publish** in the editor, into `output.dir` (default `.data/published`). Saving is a DB write
-  and leaves the live page alone (unpublishing and deleting still take a page down at once) — see
-  [ADR-0008](docs/architecture-decisions.md), or set `output.publishOnSave: true` for the pre-2.0 behaviour
-  where every save republished. Serve that dir with any static server, e.g. `npx serve .data/published`.
-
-The runtime publisher is **intentionally disabled in `pnpm dev`** (a dev render would write un-hashed Vite
-HTML), so the static files only appear on a production run. In dev you instead get the **live preview**:
-public pages render straight from the running server, and an authenticated admin can open an unpublished
-page at its real URL (the "open in new tab" button in the editor) — with unsaved changes that button
-carries them along in a preview ticket rather than saving them. See
-[static-output.md](docs/static-output.md) for the full picture.
-
-### Simulate a production deploy locally
-
-A real deployment is **two processes**: the private CMS server that *renders* the static files, and a
-public static host that *serves* them. Rehearse that split on one machine:
-
-```bash
-# 1. Auth secrets live in .env (pnpm preview loads it). At minimum:
-#      KESTREL_SESSION_SECRET=<≥32 bytes, e.g. `openssl rand -hex 32`>
-#      KESTREL_ADMIN_PASSWORD_HASH=<from `pnpm hash-password <your-password>`>
-#    Leave KESTREL_SECURE_COOKIES at its default — see the note below.
-
-pnpm build
-pnpm preview                 # built Nitro server, NODE_ENV=production → admin at http://localhost:3000/admin
-                             #   boot-publish writes .data/published; editing in /admin re-publishes affected pages
-
-# in a SECOND terminal — serve the generated site like a CDN would:
-npx serve .data/published    # the public static site, exactly as it ships
-```
-
-`pnpm preview` runs the build under `NODE_ENV=production` and **loads `.env`** (running
-`node .output/server/index.mjs` directly does **not** — export the vars yourself if you go that route).
-Note the split: the **auth** vars below are read per request, so exporting them works either way, but the
-non-auth `KESTREL_*` settings are baked in during `pnpm build` — in front of an already-built server they
-are ignored, and you override them with Nuxt's runtime names instead (`NUXT_KESTREL_DB_PATH`,
-`NUXT_KESTREL_SITE_URL`, …; see [configuration.md](docs/configuration.md)).
-Production mode makes the auth guards strict, so for a working local login:
-
-- `KESTREL_SESSION_SECRET` is **required and ≥32 bytes** (dev uses a random per-process secret); the
-  check runs per-request, not at boot, so a deploy that forgets it still starts and binds the port —
-  every `/api/*` request then answers **500** until the secret is set.
-- `KESTREL_ADMIN_PASSWORD_HASH` must be set, or `POST /api/auth/login` answers **503** (“admin login is
-  not configured”) rather than a wrong-password 401.
-- **Keep `KESTREL_SECURE_COOKIES` at its default (`true`).** `=false` is *refused* in production
-  (`KESTREL_SECURE_COOKIES=false is not allowed in production`); you don't need it — the session cookie is
-  `Secure`/`__Host-`, and browsers accept those over plain `http://localhost`, so login works without HTTPS.
-
-Watch the CMS terminal: boot prints `[kestrel] boot publish: N route(s) written, …`, and each save logs
-the routes it re-rendered. Env reference → [configuration.md](docs/configuration.md); publishing internals
-→ [static-output.md](docs/static-output.md).
+Conventions, test rails and the release flow: [internals/testing.md](docs/internals/testing.md) and
+[internals/releasing.md](docs/internals/releasing.md). Running a built site — production env, the static
+publisher, rehearsing a deploy locally: [deploying.md](docs/guide/deploying.md).
 
 ## Configuration
 
@@ -254,7 +179,7 @@ Non-auth settings live in `kestrel.config.ts` (`satisfies KestrelConfig`); each
 `KESTREL_* env → config → default`, resolved at build/dev start and frozen into `runtimeConfig` (a prebuilt
 server is retuned with the `NUXT_*` runtimeConfig names, not `KESTREL_*`). Auth/session secrets are
 **env-only** and read per request (`KESTREL_SESSION_SECRET`, `KESTREL_ADMIN_PASSWORD_HASH`, …). Full reference:
-[configuration.md](docs/configuration.md).
+[configuration.md](docs/guide/configuration.md).
 
 ## Security
 

package/kestrel.config.ts

@@ -1,4 +1,4 @@
-import type { KestrelConfig } from './layers/core/server/utils/kestrel-config'
+import type { KestrelConfig } from '@michaelthielemann/kestrel-core'
 
 /**
  * Central Kestrel configuration (everything except auth/session, which stays env-only because secrets

package/layers/access/server/middleware/00.ip-allowlist.ts

@@ -5,30 +5,15 @@
 // when `media.driver: 'local'`) — the `00.` prefix only orders files within this layer, while Nitro's own
 // static handler is unconditionally unshifted to the front of the whole handler list. `off` when no list
 // is set → zero cost on PROD/local.
-function loadConfig() {
-  const listRaw = process.env.KESTREL_IP_ALLOWLIST
-  const mode = allowlistMode(process.env.KESTREL_IP_ALLOWLIST_MODE, listRaw)
-  // Named per-token, not just a "0 valid CIDRs" count — a mixed list (one good entry, one IPv6 CIDR this
-  // IPv4-only parser can never match) would otherwise silently under-enforce with no diagnostic at all.
-  const cidrs = parseAllowlist(listRaw, (token) => {
-    console.warn(`[ip-allowlist] dropping unparseable/unsupported allow-list entry "${token}" (IPv4/CIDR only)`)
-  })
-  if (mode !== 'off' && cidrs.length === 0) {
-    console.warn('[ip-allowlist] KESTREL_IP_ALLOWLIST is set but parsed to 0 valid CIDRs — enforce mode will block ALL traffic')
-  }
-  return { mode, cidrs }
-}
-
-// Env is fixed for the process lifetime → parse the (up to a few hundred) CIDRs once, not per request.
-let configured: ReturnType<typeof loadConfig> | undefined
+import { clientIp } from '@michaelthielemann/kestrel-auth'
+import { allowlistConfig, ipAllowed, ipv4ToInt, isRendererContext, isStageGatePassedContext, markStageGatePassed } from '@michaelthielemann/kestrel-access'
 
 // A listener that never shows the gate a usable client address blocks everything, which looks like an
 // outage rather than a misconfiguration unless we say once what to set.
 let warnedUnresolvable = false
 
 export default defineEventHandler((event) => {
-  configured ??= loadConfig()
-  const { mode, cidrs } = configured
+  const { mode, cidrs } = allowlistConfig()
   if (mode === 'off') return
 
   // The runtime publisher renders the public site via a nested in-process $fetch (renderer principal), and

package/layers/access/server/middleware/access-guard.ts

@@ -1,29 +1,31 @@
+import { Forbidden, Unauthorized } from '@michaelthielemann/kestrel-contracts'
+import { toHttpError } from '@michaelthielemann/kestrel-core'
+import { refreshAuthSession } from '@michaelthielemann/kestrel-auth'
+import { claimedByPipelineRoute, resolveEventPrincipal } from '@michaelthielemann/kestrel-access'
+
 export default defineEventHandler((event) => {
   if (!event.path.startsWith('/api/')) return // default-deny applies to the API only
-  const settings = sessionSettings()
-  const decision = evaluateAccess({
-    method: getMethod(event),
-    path: event.path,
-    csrf: {
-      secFetchSite: getRequestHeader(event, 'sec-fetch-site'),
-      origin: getRequestHeader(event, 'origin'),
-      referer: getRequestHeader(event, 'referer'),
-      host: getRequestHeader(event, 'host'),
-    },
-    cookie: getCookie(event, settings.cookieName),
-    secret: settings.secret,
-    nowMs: Date.now(),
-    // The renderer principal is granted to build-time prerender AND to the runtime publisher's render
-    // (an in-process ALS context, not a forgeable header) — both render the public site via /api/route.
-    isPrerender: import.meta.prerender === true || isRendererContext(),
-    // Registry-contributed grants (opt-in layers, e.g. a public proofing back-channel) consulted on top of
-    // the hardcoded policy. Empty by default → guard behaviour unchanged.
-  }, publicReadableResources(), registeredGrants())
-  if (!decision.allow) {
-    throw createError({ statusCode: decision.status, statusMessage: decision.message })
+
+  // Authorization itself belongs to the pipeline the URL names — its `access`/`csrf`/`ipAllowlist`
+  // declarations, evaluated by the engine before step 1. Only the principal is resolved here, because the
+  // gates need it and because the session refresh below is a property of the request, not of the route.
+  event.context.principal = resolveEventPrincipal(event)
+
+  // Default-deny for everything no pipeline claims — an unknown name, a wrong verb, a stray route a
+  // consumer mounted under /api without declaring who may run it. The admin falls through instead, so the
+  // router can still answer accurately (404 for an unknown pipeline, 405 for the wrong verb) without that
+  // answer confirming to an anonymous prober which pipelines exist. For the same reason an anonymous
+  // caller gets the access gate's 401 here, not a 403 — a 401/403 split would itself be the oracle.
+  if (!claimedByPipelineRoute(getMethod(event), event.path) && event.context.principal.role !== 'admin') {
+    // toHttpError is the same single translation every pipeline-thrown KestrelError goes through
+    // (core/server/api/[...path].ts's catch) — this middleware runs before any pipeline, so it calls the
+    // map directly instead of growing a second one.
+    if (event.context.principal.role === 'anonymous') {
+      throw toHttpError(new Unauthorized({ reason: 'Authentication required' }))
+    }
+    throw toHttpError(new Forbidden({ reason: 'Forbidden' }))
   }
-  event.context.principal = decision.principal
-  event.context.readScope = decision.readScope
+
   // Sliding-expiry: any authenticated API activity refreshes the session so it stays alive while in use and
   // auto-expires after `maxAge` of inactivity (idle logout). No-op for anonymous/public requests.
   refreshAuthSession(event)

package/layers/access/server/types.d.ts

@@ -1,8 +1,7 @@
-import type { Principal } from './utils/policy'
+import type { Principal } from '@michaelthielemann/kestrel-access'
 
 declare module 'h3' {
   interface H3EventContext {
     principal?: Principal
-    readScope?: 'published' | 'all'
   }
 }

package/layers/admin/app/components/AdminAccount.vue

@@ -131,7 +131,7 @@ defineExpose({ lang, selectLang, signOut })
   font-weight: var(--weight-medium);
 }
 .rail-account__caret {
-  margin-left: auto; // push the chevron to the right edge of the full-width trigger
+  margin-left: auto;
   flex-shrink: 0;
   color: var(--color-text-muted);
 }

package/layers/admin/app/components/BlockFields.vue

@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import { computed } from 'vue'
-import type { SerializedBlock } from '../../../core/server/utils/serialize-collection'
-import type { LayoutNode } from '../../../core/server/utils/field-layout'
+import type { LayoutNode, SerializedBlock } from '@michaelthielemann/kestrel-core'
 import type { BlockRow } from '../utils/block-tree'
 import { resolveLocalized } from '../../../ui/app/utils/localized'
 

package/layers/admin/app/components/BlockPreview.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed, inject, onMounted, onUnmounted, ref, watch } from 'vue'
-import type { SerializedBlock } from '../../../core/server/utils/serialize-collection'
+import type { SerializedBlock } from '@michaelthielemann/kestrel-core'
 import { previewSrc, parseFrameMessage, type PreviewBlockNode } from '../../../public/app/utils/preview-protocol'
 import { createPreviewSender, acceptsFrameEvent, type PreviewSender } from '../utils/preview-channel'
 import { editorFormContextKey } from '../utils/editor-form-context'
@@ -22,6 +22,16 @@ const { t } = useT()
 const ctx = inject(editorFormContextKey, null)
 const src = computed(() => previewSrc(ctx?.previewUrl.value ?? null, props.locale ?? ''))
 
+// The layout wraps the frame's own document (`<NuxtLayout>`, a parent the postMessage bridge can't reach
+// from inside its slot), so a layout change can't ride the content push — only a fresh navigation
+// re-resolves it. Forcing one needs an actual URL change (a `src` re-assignment to the same string is a
+// no-op), so a change bumps this counter, which `frameSrc` folds into the URL as a harmless query param.
+const layoutReloadKey = ref(0)
+const frameSrc = computed(() => {
+  if (!layoutReloadKey.value) return src.value
+  return `${src.value}${src.value.includes('?') ? '&' : '?'}_r=${layoutReloadKey.value}`
+})
+
 // ---- populate (pipeline: resolve media ids + internal links into reactive caches) ----
 // Block field schemas (non-blocking: byType fills once loaded, then the next send carries the media).
 const { blocks: blockDefs, load } = useBlocks()
@@ -84,9 +94,9 @@ function onFrameLoad() {
   if (!el) return
   try {
     const loc = el.contentWindow?.location
-    if (loc && loc.pathname + loc.search !== src.value) el.src = src.value
+    if (loc && loc.pathname + loc.search !== frameSrc.value) el.src = frameSrc.value
   } catch {
-    el.src = src.value // cross-origin navigation — location unreadable, snap back
+    el.src = frameSrc.value // cross-origin navigation — location unreadable, snap back
   }
 }
 
@@ -101,7 +111,7 @@ function refresh() {
   try {
     el.contentWindow?.location.reload() // same URL → onFrameLoad's snap-back check passes
   } catch {
-    el.src = src.value // cross-origin: location unreadable → renavigate
+    el.src = frameSrc.value // cross-origin: location unreadable → renavigate
   }
 }
 
@@ -121,6 +131,8 @@ watch(populated, () => { if (ready.value) pushContent() })
 watch(() => props.selectedId, (id) => { if (ready.value) sender?.sendSelected(id ?? null) })
 // A src change reloads the iframe (locale switch, first save assigning a URL) → wait for its new ready.
 watch(src, () => { ready.value = false })
+// See `layoutReloadKey` above: a layout change forces a fresh navigation, the only way to re-resolve it.
+watch(() => ctx?.values?.layout, () => { layoutReloadKey.value++; ready.value = false })
 
 // ---- responsive preview: device presets (quick-fill) + automatic scale-to-fit + custom W×H ----
 // The iframe renders at the target resolution's REAL px (so the page fires its true breakpoints); a
@@ -281,7 +293,7 @@ onUnmounted(() => { ro?.disconnect(); ro = null })
 
     <div ref="stage" class="block-preview__stage">
       <div class="block-preview__viewport" :style="viewportStyle">
-        <iframe ref="frame" class="block-preview__frame" :src="src" :style="frameStyle" :title="t('preview.label')" @load="onFrameLoad" />
+        <iframe ref="frame" class="block-preview__frame" :src="frameSrc" :style="frameStyle" :title="t('preview.label')" @load="onFrameLoad" />
       </div>
     </div>
   </section>

package/layers/admin/app/components/BlocksBody.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { SerializedBlock } from '../../../core/server/utils/serialize-collection'
+import type { SerializedBlock } from '@michaelthielemann/kestrel-core'
 import type { BlockTreeCtx } from '../utils/block-tree'
 
 // The page-builder editor body: hierarchy · live preview · contextual fields. All form state comes from

package/layers/admin/app/components/CollectionEditor.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { localePath } from '../../../core/app/utils/locale-path'
+import { localePath } from '@michaelthielemann/kestrel-core/client'
 import { PREVIEW_TOKEN_QUERY, PREVIEW_FALLBACK_PATH } from '../../../public/app/utils/preview-protocol'
 import { resolveCollectionEditor } from '../utils/editor-registry'
 import { editorFormContextKey } from '../utils/editor-form-context'
@@ -23,7 +23,7 @@ const f = useEditForm({ collection: props.collection, id: props.id, locale: prop
 // below, where it originally lived) so `defineExpose` can also run before that same await.
 const {
   formError, saving, submit, dirty, editorType, pageLike, hasStatus,
-  savedStatus, undo, redo, canUndo, canRedo,
+  savedStatus, undo, redo, canUndo, canRedo, quarantined,
 } = f
 
 // Editor → field-widget context. MUST run BEFORE the top-level `await` below — after an await the setup
@@ -91,21 +91,20 @@ const liveStatus = usePublishStatus({
 // Carries "poll the live status on mount" across the create→navigate remount (see usePendingPublishPoll).
 const pendingPoll = usePendingPublishPoll()
 
-// ---- publish + external preview -------------------------------------------------------------------
 // Saving persists to the DB and leaves the live site alone; publishing writes the static file(s). The two
 // are separate buttons because they are separate decisions (ADR-0008) — you can save a page a dozen times
 // while the published version stays exactly as it was.
 const publishing = ref(false)
 const previewOpening = ref(false)
-// `output.publishOnSave` turns the split off again (a save republishes, as before 2.0) — then a Publish
-// button would have nothing to do, so the hosts hide it. Reported by /api/publish-status; unknown (a
+// `output.publishOnSave` turns the split off again (a save republishes) — then a Publish
+// button would have nothing to do, so the hosts hide it. Reported by /api/publishStatus; unknown (a
 // never-saved record, which does not fetch it) reads as the default, i.e. the button stays.
 const publishOnSave = computed(() => liveStatus.data.value.publishOnSave === true)
 const canPublish = computed(() => !publishOnSave.value)
 
 /** Save (a publish publishes what you SEE), promote a draft, then write the output. */
 async function publish() {
-  if (publishing.value || saving.value) return
+  if (publishing.value || saving.value || quarantined.value) return
   publishing.value = true
   try {
     // Pressing Publish IS the publish intent, so a draft is promoted here rather than sending the user to
@@ -159,7 +158,7 @@ async function openPreview() {
   const tab = window.open('', '_blank')
   previewOpening.value = true
   try {
-    const ticket = await $fetch<{ token: string }>('/api/preview', {
+    const ticket = await $fetch<{ token: string }>('/api/createPreview', {
       method: 'POST',
       body: {
         collection: props.collection,
@@ -193,6 +192,7 @@ async function openPreview() {
 defineExpose({
   dirty, saving, undo, redo, canUndo, canRedo, hasStatus, status, savedStatus, previewUrl, pageLike,
   live: liveStatus.data, recordTitle: heading, publish, publishing, canPublish, openPreview, previewOpening,
+  quarantined,
 })
 
 await f.ready
@@ -202,6 +202,7 @@ await f.ready
 const bodyComponent = computed(() => resolveCollectionEditor(editorType.value))
 
 async function onSave() {
+  if (quarantined.value) return
   // Read BEFORE the save: a successful submit rebaselines, after which the saved status is the new one.
   const wasPublished = savedStatus.value === 'published'
   const r = await submit()
@@ -232,7 +233,7 @@ async function onCopyFrom(loc: string) {
   const tid = f.translations.value[loc]
   if (typeof tid !== 'number') return
   try {
-    const row = await $fetch<Record<string, unknown>>(`/api/${props.collection}/${tid}`)
+    const row = await $fetch<Record<string, unknown>>(`/api/${props.collection}/readOne/${tid}`)
     f.applyFrom(row)
   } catch {
     f.formError.value = t('localeBar.copyFailed', { locale: loc.toUpperCase() })
@@ -268,16 +269,27 @@ onUnmounted(() => {
        the submit event and block onSave with a browser bubble — wrongly so on proxy inputs whose text
        doesn't mirror the model (combobox search boxes stay empty although records are selected). -->
   <form :id="formId" class="editor" novalidate @submit.prevent="onSave">
-    <p v-if="formError" class="editor__error" role="alert">{{ formError }}</p>
+    <!-- Quarantined: the row failed its select schema, so its real fields are unknown — no body,
+         no actions, nothing to submit. KestrelUiAlert renders role="alert" for variant="error". -->
+    <KestrelUiAlert v-if="quarantined" variant="error" class="editor__quarantine">
+      <template #title>
+        <KestrelUiIcon name="triangle-alert" :size="16" />
+        {{ t('editor.quarantined.title') }}
+      </template>
+      {{ t('editor.quarantined.desc') }}
+    </KestrelUiAlert>
+    <template v-else>
+      <p v-if="formError" class="editor__error" role="alert">{{ formError }}</p>
 
-    <!-- The editor body is chosen by the collection's `editor` type (fields · blocks · an extension). -->
-    <component :is="bodyComponent" v-if="bodyComponent" />
-    <KestrelEditorUnsupported v-else :editor="editorType" />
+      <!-- The editor body is chosen by the collection's `editor` type (fields · blocks · an extension). -->
+      <component :is="bodyComponent" v-if="bodyComponent" />
+      <KestrelEditorUnsupported v-else :editor="editorType" />
 
-    <div v-if="actions" class="editor__actions">
-      <KestrelUiButton type="submit" variant="primary" icon="check" :loading="saving">{{ t('common.save') }}</KestrelUiButton>
-      <KestrelUiButton type="button" variant="secondary" icon="x" :disabled="saving" @click="emit('cancel')">{{ t('common.cancel') }}</KestrelUiButton>
-    </div>
+      <div v-if="actions" class="editor__actions">
+        <KestrelUiButton type="submit" variant="primary" icon="check" :loading="saving">{{ t('common.save') }}</KestrelUiButton>
+        <KestrelUiButton type="button" variant="secondary" icon="x" :disabled="saving" @click="emit('cancel')">{{ t('common.cancel') }}</KestrelUiButton>
+      </div>
+    </template>
   </form>
 </template>
 
@@ -297,6 +309,13 @@ onUnmounted(() => {
     color: var(--color-danger);
     font-size: var(--text-sm);
   }
+  &__quarantine {
+    .ui-alert__title {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--space-2);
+    }
+  }
   &__actions {
     display: flex;
     gap: var(--space-3);

package/layers/admin/app/components/CollectionList.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
-import type { SerializedCollection } from '../../../core/server/utils/serialize-collection'
+import type { SerializedCollection } from '@michaelthielemann/kestrel-core'
 import { resolveLocalized } from '../../../ui/app/utils/localized'
+import { bulkCustomActions, recordCustomActions } from '../utils/collection-ops'
 
 // `locale` is set only for a translatable collection: it filters the list to that content locale and
 // shows a locale switcher. New records / row links carry it so they open in the same locale.
@@ -33,7 +34,7 @@ const { sort, page, perPage, filter, effectiveQuery, setSort, setPage, clampPage
 const filterDraft = useListFilterDraft({ available, filterableColumns, filter, setFilter })
 const activeFilters = filterDraft.activeFilters
 
-const { rows, total, error, totalPages, fetchRows } = useListRows({
+const { rows, total, quarantinedCount, error, totalPages, fetchRows } = useListRows({
   collection,
   effectiveQuery,
   locale: () => props.locale,
@@ -50,15 +51,23 @@ const { selected, allSelected, headerIndeterminate, toggleRow, toggleAll, clear:
   useListSelection(rows)
 
 // Row action = 1 id, bulk bar = N ids; the server does the batching.
-const { busy: opsBusy, error: opsError, deleteOpen, deleteReport, askDelete, confirmDelete, duplicate: onDuplicate, setStatus } =
+const { busy: opsBusy, error: opsError, deleteOpen, deleteReport, askDelete, confirmDelete, duplicate: onDuplicate, setStatus, runAction } =
   useListBatchActions(collection, fetchRows)
 
+// Schema-driven actions beyond the built-in delete/duplicate/publish: a consumer's `definePipeline` shows
+// up here without any UI code.
+const bulkActions = computed(() => bulkCustomActions(props.schema.actions ?? []))
+const rowActions = computed(() => recordCustomActions(props.schema.actions ?? []))
+
 // Toolbar popovers (filter / columns), including the outside-click and Escape-restores-focus behaviour.
 const { container: toolsRef, open: openPanel, toggle: togglePanel } = useToolbarPanel<'filter' | 'columns'>()
 
 // Polite status announced after every (re)fetch so filter/sort/page changes report their result count
 // to screen readers — WCAG 4.1.3 Status Messages.
 const resultsLabel = computed(() => t(total.value === 1 ? 'list.result' : 'list.results', { total: total.value }))
+// Quarantined rows failed their select schema and would otherwise be silent data loss — a chip in
+// the header surfaces the count whenever it's non-zero.
+const quarantinedLabel = computed(() => t(quarantinedCount.value === 1 ? 'list.quarantinedOne' : 'list.quarantinedCount', { n: quarantinedCount.value }))
 // The ONE permanent live region. A live region only announces MUTATIONS to a node already in the tree, so
 // the selection count is folded in here (mutating this region's text) rather than toggling a second
 // role="status" node into the DOM — inserting an already-populated live node is typically not announced,
@@ -133,6 +142,11 @@ await fetchRows()
         </div>
       </div>
 
+      <span v-if="quarantinedCount > 0" class="list__quarantine-chip">
+        <KestrelUiIcon name="triangle-alert" :size="14" />
+        {{ quarantinedLabel }}
+      </span>
+
       <NuxtLink :to="`/admin/${collection}/new${localeQuery}`" class="list__new">{{ newLabel }}</NuxtLink>
     </div>
 
@@ -141,8 +155,10 @@ await fetchRows()
       :count="selected.size"
       :has-status="!!schema.status"
       :busy="opsBusy"
+      :actions="bulkActions"
       @set-status="(status) => setStatus([...selected], status)"
       @delete="askDelete([...selected])"
+      @run-action="(action) => runAction(action, [...selected])"
       @clear="clearSelection"
     />
 
@@ -173,11 +189,13 @@ await fetchRows()
         :selected="selected"
         :all-selected="allSelected"
         :header-indeterminate="headerIndeterminate"
+        :actions="rowActions"
         @sort="setSort"
         @toggle-row="toggleRow"
         @toggle-all="toggleAll"
         @duplicate="onDuplicate"
         @delete="askDelete"
+        @run-action="(action, id) => runAction(action, [id])"
       />
 
       <KestrelUiEmptyState
@@ -348,6 +366,19 @@ await fetchRows()
     cursor: pointer;
   }
 
+  // Quarantine count chip — icon + text (not color alone, WCAG 1.4.1) so it reads even without color.
+  &__quarantine-chip {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-1);
+    padding: var(--space-1) var(--space-2);
+    border-radius: var(--radius-sm);
+    background: var(--color-danger-soft, var(--color-surface));
+    color: var(--color-danger);
+    font-size: var(--text-sm);
+    font-weight: var(--weight-medium);
+  }
+
   &__new {
     margin-left: auto;
     padding: var(--space-2) var(--space-4);