@cogenta/cli 0.2.2 → 0.4.0

package/dist/commands/serve.js

@@ -1,14 +1,37 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { dirname, join } from 'node:path';
 import process from 'node:process';
 import { pathToFileURL } from 'node:url';
-import { buildContentSchema, createAgentsRouter, createAuditRouter, createAuthRouter, createContentGateway, createContentService, createMediaRouter, createPermissionLayer, createRestRouter, executeGraphQL, resolveActor, } from '@cogenta/api';
+import { createAnalyticsStore, ensureAnalyticsTables, } from '@cogenta/analytics';
+import { buildContentSchema, createAgentsRouter, createAnalyticsRouter, createApiKeysRouter, createAssistantRouter, createAuditRouter, createAuthRouter, createContentGateway, createContentService, createImportRouter, createMarketplaceRouter, createMediaRouter, createMenuRouter, createMfaRecommendationSource, createNoticeDismissalStore, createNoticeRouter, createOpsStatusRouter, createPermissionLayer, createRedirectRouter, createRestRouter, createSearchRouter, createSitePlanRouter, createSuspiciousActivitySource, createTaxonomyRouter, createUsersRouter, errorResponse, executeGraphQL, resolveActor, variantKeyFor, } from '@cogenta/api';
 import { createAuthStore } from '@cogenta/auth';
-import { CogentaError, createDatabaseMediaStore, createDatabaseRegistry, createLogger, createStorageRegistry, isCogentaError, loadConfig, } from '@cogenta/core';
-import { buildSchemaDocument, createContentStore, createRedirectStore, createSchemaTables, withReadOnlyStore, } from '@cogenta/schema';
+import { createCartStore, createCatalogStore, createCommerceAdminRouter, createCommercePermissions, createCouponStore, createCustomerStore, createInvoiceStore, createManualPaymentGateway, createOrderStore, createPaymentStore, createShippingStore, createSubscriptionStore, createTaxStore, ensureCommerceTables, } from '@cogenta/commerce';
+import { CogentaError, createDatabaseMediaStore, createDatabaseQueue, createDatabaseRegistry, createLogger, createStorageRegistry, isCogentaError, loadConfig, } from '@cogenta/core';
+import { importWordPress } from '@cogenta/import';
+import { createMarketplaceCatalog, createMarketplaceInstaller, createPluginGrantStore, ensureMarketplaceTables, ensurePluginTables, } from '@cogenta/plugins';
+import { buildPath, buildSchemaDocument, createContentStore, createMenuStore, createRedirectStore, createSchemaTables, createSearchIndex, createTaxonomyStore, ensureMenuTables, registerScheduledPublishing, withLifecycleEvents, withReadOnlyStore, withScheduledPublishEnqueue, withSearchIndexing, } from '@cogenta/schema';
+import { sendResetMail } from '../reset-mail.js';
 import { serveAdminAsset } from './admin-assets.js';
-import { loadSkinCss, renderRequestedPage } from './theme-render.js';
+import { buildAssistant, withVectorIndexing } from './assistant.js';
+import { createContentWebhookEmitter } from './content-webhooks.js';
+import { applySecurity } from './http-security.js';
+import { selectMediaImageProcessor } from './media-images.js';
+import { renderSearchPage } from './search-page.js';
+import { createSecurityAlertWatch } from './security-alerts.js';
+import { buildSitemapFiles, collectRoutedResources, renderRobots, seoSiteFor } from './seo.js';
+import { createSitePlanning } from './site-plan.js';
+import { cssEtag, loadThemeCss } from './theme-css.js';
+import { DEFAULT_IMAGE_ENDPOINT, joinStyles, loadSkinCss, renderDraftPage, renderRequestedPage, STYLESHEET_PATH, } from './theme-render.js';
+/** `/sitemap.xml` and the `/sitemap-N.xml` chunks a large site splits into. */
+const SITEMAP_PATH = /^\/sitemap(?:-\d+)?\.xml$/u;
+/** The only `Content-Type` values `/_image` will ever put on the wire. */
+const SERVABLE_IMAGE_TYPES = new Set([
+    'image/avif',
+    'image/webp',
+    'image/jpeg',
+    'image/png',
+]);
 const SCHEMA_FILE_CANDIDATES = [
     'cogenta.schema.ts',
     'cogenta.schema.mts',
@@ -25,6 +48,16 @@ const SCHEMA_FILE_CANDIDATES = [
  * collections has nothing to serve.
  */
 export async function loadCollections(projectRoot) {
+    return (await loadSchemaModule(projectRoot)).collections;
+}
+/**
+ * The same file, read for both halves of the content model.
+ *
+ * Taxonomies arrive as a **named** export beside the default one
+ * (`export const taxonomies = [...]`), so every schema file written before
+ * `schema@2.0` keeps loading unchanged and simply declares none.
+ */
+export async function loadSchemaModule(projectRoot) {
     for (const candidate of SCHEMA_FILE_CANDIDATES) {
         const path = join(projectRoot, candidate);
         let module;
@@ -49,7 +82,18 @@ export async function loadCollections(projectRoot) {
                 hint: 'Export the array defineCollection() built, the same one passed to createSchemaTables in tests.',
             });
         }
-        return collections;
+        const taxonomies = module.taxonomies;
+        if (taxonomies !== undefined && !Array.isArray(taxonomies)) {
+            throw new CogentaError({
+                code: 'SCHEMA_INVALID',
+                message: `${path} exports "taxonomies", but not as an array.`,
+                hint: 'Export the array defineTaxonomy() built: export const taxonomies = [category].',
+            });
+        }
+        return {
+            collections: collections,
+            taxonomies: (taxonomies ?? []),
+        };
     }
     throw new CogentaError({
         code: 'SCHEMA_INVALID',
@@ -57,6 +101,29 @@ export async function loadCollections(projectRoot) {
         hint: 'Create cogenta.schema.ts, default-exporting the array of collections defineCollection() built.',
     });
 }
+/**
+ * The schema file this project actually loads, or `undefined` when it has
+ * none.
+ *
+ * Anything that *writes* the schema back has to target this, not a guessed
+ * name: `loadCollections` prefers `cogenta.schema.ts` (the form ADR-0010
+ * calls for — TypeScript in git), so a writer that assumed `.mjs` would
+ * create tables and then write a file nothing reads, leaving an operator
+ * with orphan tables and no collections after the restart it was told to do.
+ */
+export async function findSchemaFile(projectRoot) {
+    for (const candidate of SCHEMA_FILE_CANDIDATES) {
+        const path = join(projectRoot, candidate);
+        try {
+            await stat(path);
+            return path;
+        }
+        catch {
+            // Try the next candidate — same order `loadCollections` uses.
+        }
+    }
+    return undefined;
+}
 /**
  * True only when the candidate file itself does not exist — never for a
  * missing import *inside* it, which must surface as a real error rather than
@@ -75,33 +142,111 @@ function isModuleNotFound(error, path) {
     // `.ts`) surfaced as a hard SCHEMA_INVALID instead of trying the next one.
     return error.message.includes(pathToFileURL(path).href) || error.message.includes(path);
 }
+/**
+ * What `/api/assistant` answers with when this process built no assistant at
+ * all — a caller that did not ask for one, in a test or an embedding. Exactly
+ * what `createAssistToolset` returns with no provider, restated here so
+ * `assembleSite` need not construct one to say "off".
+ */
+const EMPTY_TOOLSET = Object.freeze({
+    available: false,
+    reason: 'No AI provider is configured for this site, so the writing assistant is switched off. Everything else in the CMS works exactly the same.',
+    tools: Object.freeze([]),
+    capabilities: Object.freeze([]),
+});
 /** `relyingPartyId` is the bare host: WebAuthn ties a passkey to a domain, not a URL. */
 function webauthnConfigFor(site) {
     const host = new URL(site.url).hostname;
     return { relyingPartyName: site.name, relyingPartyId: host, origin: site.url };
 }
-async function assembleSite(db, collections, signingKey, site, storage, health, 
-/** Optional: no caller constructs an agent registry today, and `/api/agents` simply is not mounted when this is absent — see `agentsRouter` on `Site`. */
-agents, 
-/**
- * "Commencer par une démo en lecture seule" (L9 tâche 12, playground). Every
- * write REST or GraphQL could attempt refuses with `CONTENT_READ_ONLY`
- * instead of landing — wrapped once here, at the one place both transports'
- * stores are actually constructed, so neither can bypass it.
- */
-readOnly = false, 
-/** `null` when `theme.tokens.json` is absent or invalid — see `loadSkinCss`. */
-skinCss = null) {
-    await createSchemaTables(db, collections);
+async function assembleSite(options) {
+    const { db, collections, site, storage, logger } = options;
+    const readOnly = options.readOnly ?? false;
+    const styles = options.styles ?? null;
+    const taxonomies = options.taxonomies ?? [];
+    // Taxonomies first: a `f.taxonomy()` field carries a real foreign key into
+    // the terms table, which therefore has to exist before the collection does.
+    await createSchemaTables(db, collections, taxonomies);
+    // Full-text search, connected for the first time (L10 task 3). The index is
+    // derived data and creates its own physical table, so a fresh install can
+    // index its first entry without a migration having run.
+    //
+    // Accepted from the caller when there is one: `runServe` builds it before the
+    // assistant so the semantic half can be fused with *this* index rather than
+    // with a second one over the same table.
+    const searchIndex = options.searchIndex ?? (await createSearchIndex({ db }));
+    // Scheduled publication (L1's `schedulePublication`/`registerScheduledPublishing`,
+    // written and tested from the start but never wired to anything — the admin
+    // showed "Scheduled" as a read-only badge). The `database` queue driver is
+    // the R1-honest choice: no Redis, no external worker, just a table in the
+    // site's own database, drained by `runServe`'s own `setInterval` tick — see
+    // the comment there for the lateness this trades for not requiring a
+    // persistent process.
+    const scheduledPublishQueue = createDatabaseQueue({ db, logger });
     const stores = new Map();
     const storeFor = (collection) => {
         const existing = stores.get(collection.name);
         if (existing !== undefined)
             return existing;
-        const created = createContentStore({ db, collection });
-        const stored = readOnly ? withReadOnlyStore(created) : created;
-        stores.set(collection.name, stored);
-        return stored;
+        // `siblings` is what lets `delete()` enforce `restrict` in application
+        // code (ADR-0022): trashing is an UPDATE, so the foreign key has nothing
+        // left to refuse at that moment.
+        const created = createContentStore({ db, collection, siblings: collections });
+        const guarded = readOnly ? withReadOnlyStore(created) : created;
+        // Queues the real publish job for a save that lands as `status:
+        // 'scheduled'`. Placed right after the read-only guard so a write that
+        // guard refused never reaches the queue either.
+        const schedulable = withScheduledPublishEnqueue(guarded, {
+            collection,
+            queue: scheduledPublishQueue,
+            onError: (error) => logger.error('scheduled publish enqueue failed', {
+                collection: collection.name,
+                error: String(error),
+            }),
+        });
+        // Outermost, so a read-only refusal happens *before* anything is indexed:
+        // a write that never landed must not change the index either.
+        const indexed = withSearchIndexing(schedulable, {
+            collection,
+            index: searchIndex,
+            onError: (error) => logger.error('search index write failed', {
+                collection: collection.name,
+                error: String(error),
+            }),
+        });
+        // The semantic half, wrapped the same way and for the same reason (L18
+        // task 5): REST and GraphQL are handed the same store instances, so one
+        // wrap covers both and neither can write content the index never hears
+        // about. Absent entirely when no embedder is available.
+        const stored = options.assistant?.vectors === undefined
+            ? indexed
+            : withVectorIndexing(indexed, {
+                collection,
+                siteId: site.url,
+                store: options.assistant.vectors.store,
+                embeddings: options.assistant.vectors.embeddings,
+                onError: (error) => logger.error('vector index write failed', {
+                    collection: collection.name,
+                    error: String(error),
+                }),
+            });
+        // Outermost of all: an event must describe a write that really landed, so
+        // it fires after the read-only guard has had its chance to refuse and
+        // after the index has been brought back in step. A receiver that rebuilt a
+        // page from an event the store then rejected would serve a page that never
+        // existed.
+        const observed = options.onContentEvent == null
+            ? stored
+            : withLifecycleEvents(stored, {
+                collection,
+                emit: options.onContentEvent,
+                onError: (error) => logger.error('content webhook emit failed', {
+                    collection: collection.name,
+                    error: String(error),
+                }),
+            });
+        stores.set(collection.name, observed);
+        return observed;
     };
     // The gateway (below) reads `stores` directly rather than through
     // `storeFor` — REST's own lazy population left it empty for any
@@ -111,6 +256,19 @@ skinCss = null) {
     // same, already-complete map.
     for (const collection of collections)
         storeFor(collection);
+    // The publish half of scheduling: re-reads the entry before acting, so an
+    // entry edited back to `draft` — or already published by hand — before its
+    // hour comes is left alone rather than redone by a job still sitting in
+    // the queue (see `withScheduledPublishEnqueue`, which enqueues again on
+    // every save rather than tracking a previous job id).
+    registerScheduledPublishing(scheduledPublishQueue, async (publication) => {
+        const target = stores.get(publication.collection);
+        if (target === undefined)
+            return;
+        const entry = await target.read(publication.entryId, { state: 'working' });
+        if (entry?.status === 'scheduled')
+            await target.publish(publication.entryId);
+    }, { logger });
     const redirects = createRedirectStore({ db });
     await redirects.ensureTable();
     const permissions = createPermissionLayer({ collections });
@@ -122,41 +280,283 @@ skinCss = null) {
     });
     const auth = await createAuthStore({
         db,
-        signingKey,
+        signingKey: options.signingKey,
         collections,
         issuer: site.name,
         webauthn: webauthnConfigFor(site),
     });
+    // One store per taxonomy, made once: a term store holds no state beyond its
+    // table, but re-deriving it per request would re-resolve every identifier.
+    const taxonomyStores = new Map();
+    const taxonomyStoreFor = (taxonomy) => {
+        const existing = taxonomyStores.get(taxonomy.name);
+        if (existing !== undefined)
+            return existing;
+        const created = createTaxonomyStore({ db, taxonomy });
+        taxonomyStores.set(taxonomy.name, created);
+        return created;
+    };
     const mediaStore = createDatabaseMediaStore({ db });
+    const noticeDismissals = createNoticeDismissalStore(db);
+    await noticeDismissals.ensureTable();
+    // L17: a local/embedded catalog, not a distant service — L13's API keys,
+    // which the lot names as that dependency, were never built. Empty until a
+    // site configures one; a marketplace router that always answers is what
+    // lets the admin screen render instead of guessing whether one exists.
+    await ensurePluginTables(db);
+    await ensureMarketplaceTables(db);
+    const marketplaceGrants = createPluginGrantStore(db);
+    const marketplaceCatalog = createMarketplaceCatalog(options.marketplace?.catalog ?? []);
+    const marketplaceInstaller = createMarketplaceInstaller(db, {
+        grantStore: marketplaceGrants,
+        ...(options.marketplace?.trustedPublicKeys === undefined
+            ? {}
+            : { trustedPublicKeys: options.marketplace.trustedPublicKeys }),
+    });
+    // Menus (navigation). Not schema-declared, so one fixed pair of tables
+    // rather than one per taxonomy — see `menu-tables.ts`.
+    await ensureMenuTables(db);
+    const menuStore = createMenuStore({ db });
+    const gateway = createContentGateway({ collections, stores, permissions });
+    // Resolves an `entry`-kind menu item to a display label and public route,
+    // through the same permission-checked gateway everything else reads
+    // through. `ANONYMOUS`: a menu is public navigation, so an item is only
+    // ever resolved to what an anonymous visitor could also reach — an
+    // unpublished target resolves to `null` rather than leaking a draft's
+    // title into a public nav response.
+    const resolveMenuEntry = async (collectionName, entryId) => {
+        const collection = collections.find((candidate) => candidate.name === collectionName);
+        if (collection === undefined)
+            return null;
+        const entry = await gateway.read(collectionName, entryId, {
+            actor: { id: null, roles: ['public'] },
+        });
+        if (entry === null)
+            return null;
+        const stringValues = Object.fromEntries(Object.entries(entry.values).filter((pair) => typeof pair[1] === 'string'));
+        const label = typeof entry.values['title'] === 'string'
+            ? entry.values['title']
+            : typeof entry.values['name'] === 'string'
+                ? entry.values['name']
+                : entryId;
+        let route = null;
+        if (collection.routing !== undefined) {
+            try {
+                route = buildPath(collection, stringValues, entry.locale ?? undefined);
+            }
+            catch {
+                // A route field is missing on this entry (e.g. an empty slug on a
+                // draft). The item still resolves — with a label, no link — rather
+                // than failing the whole menu response over one broken reference.
+                route = null;
+            }
+        }
+        return { label, route };
+    };
+    // Contract E (ADR-0024): a whole separate domain, wired the same way the
+    // taxonomy tables are — created idempotently, once, here, so a site that
+    // never sells anything pays nothing beyond a handful of `create table if
+    // not exists` statements it never queries.
+    await ensureCommerceTables(db);
+    const commerceCatalog = createCatalogStore(db);
+    const commerceCustomers = createCustomerStore(db);
+    const commerceTax = createTaxStore(db);
+    const commerceShipping = createShippingStore(db);
+    const commerceCoupons = createCouponStore(db);
+    const commerceCarts = createCartStore(db, {
+        catalog: commerceCatalog,
+        tax: commerceTax,
+        shipping: commerceShipping,
+        coupons: commerceCoupons,
+    });
+    const commerceOrders = createOrderStore(db, {
+        catalog: commerceCatalog,
+        carts: commerceCarts,
+        customers: commerceCustomers,
+        coupons: commerceCoupons,
+    });
+    // The manual/bank-transfer driver: the one payment gateway that needs no
+    // provider keys, so a shop is sellable before anyone configures Stripe
+    // (mirrors R1 — a real degraded implementation, not a stub).
+    const commercePayments = createPaymentStore(db, {
+        gateway: createManualPaymentGateway(),
+        orders: commerceOrders,
+    });
+    const commercePermissions = createCommercePermissions();
+    const commerceSubscriptions = createSubscriptionStore(db, {
+        catalog: commerceCatalog,
+        customers: commerceCustomers,
+        orders: commerceOrders,
+        payments: commercePayments,
+    });
+    // Absent until the site fills in `billing` (contract E, ADR-0024): an
+    // invoice with a made-up seller address is worse than no invoicing at all,
+    // so the route stays unreachable rather than issuing one anyway.
+    const billing = options.billing;
+    const commerceInvoices = billing === undefined
+        ? undefined
+        : createInvoiceStore(db, {
+            orders: commerceOrders,
+            seller: {
+                address: [billing.legalName, ...billing.address],
+                ...(() => {
+                    const footer = [billing.taxId, billing.footer]
+                        .filter((part) => part !== undefined)
+                        .join(' — ');
+                    return footer === '' ? {} : { footer };
+                })(),
+            },
+        });
+    await ensureAnalyticsTables(db);
+    const analyticsStore = createAnalyticsStore(db);
+    const siteHost = new URL(site.url).hostname;
     return {
         db,
         auth,
         restRouter: createRestRouter({ service, siteUrl: site.url }),
-        authRouter: createAuthRouter({ auth }),
-        mediaRouter: createMediaRouter({ store: mediaStore, storage }),
+        authRouter: createAuthRouter({
+            auth,
+            ...(options.onForgotPassword == null ? {} : { onForgotPassword: options.onForgotPassword }),
+        }),
+        analyticsStore,
+        analyticsRouter: createAnalyticsRouter({ store: analyticsStore, siteHost }),
+        mediaRouter: createMediaRouter({
+            store: mediaStore,
+            storage,
+            ...(options.images === undefined || options.images === null
+                ? {}
+                : { images: options.images }),
+        }),
         auditRouter: createAuditRouter({ audit: auth.audit }),
-        ...(agents === undefined ? {} : { agentsRouter: createAgentsRouter(agents) }),
+        taxonomyRouter: createTaxonomyRouter({
+            taxonomies,
+            permissions,
+            storeFor: (taxonomy) => taxonomyStoreFor(taxonomy),
+        }),
+        marketplaceRouter: createMarketplaceRouter({
+            catalog: marketplaceCatalog,
+            installer: marketplaceInstaller,
+        }),
+        menuRouter: createMenuRouter({ store: menuStore, resolveEntry: resolveMenuEntry }),
+        commerceRouter: createCommerceAdminRouter({
+            catalog: commerceCatalog,
+            orders: commerceOrders,
+            customers: commerceCustomers,
+            payments: commercePayments,
+            coupons: commerceCoupons,
+            subscriptions: commerceSubscriptions,
+            ...(commerceInvoices === undefined ? {} : { invoices: commerceInvoices }),
+            permissions: commercePermissions,
+        }),
+        redirectRouter: createRedirectRouter({ store: redirects }),
+        opsStatusRouter: createOpsStatusRouter({
+            security: options.security,
+            webhooks: options.webhooks,
+        }),
+        searchRouter: createSearchRouter({
+            index: searchIndex,
+            collections,
+            permissions,
+            defaultLocale: site.defaultLocale,
+        }),
+        securityAlerts: options.onSecurityEvent == null
+            ? null
+            : createSecurityAlertWatch({
+                rateLimit: auth.rateLimit,
+                send: options.onSecurityEvent,
+                siteUrl: site.url,
+                logger,
+            }),
+        noticeRouter: createNoticeRouter({
+            // One source today, and the seam is the array: a future recommendation
+            // (a plugin update waiting, a certificate about to expire) is one more
+            // entry here and nothing else anywhere.
+            sources: [
+                createMfaRecommendationSource({ collections, credentials: auth.credentials }),
+                // The failed-sign-in table has been written to since L2 and read by
+                // nothing but the limiter's own counter (L14 task 4). One extra source
+                // in this array is the whole wiring — the seam the notice mechanism was
+                // designed around.
+                createSuspiciousActivitySource({ rateLimit: auth.rateLimit }),
+            ],
+            dismissals: noticeDismissals,
+        }),
+        usersRouter: createUsersRouter({ auth }),
+        apiKeysRouter: createApiKeysRouter({ auth }),
+        assistantRouter: createAssistantRouter({
+            toolset: (options.assistant?.toolset ?? EMPTY_TOOLSET),
+            collections,
+            permissions,
+            site,
+            logger,
+        }),
+        ...(options.agents === undefined ? {} : { agentsRouter: createAgentsRouter(options.agents) }),
+        ...(options.sitePlans === undefined
+            ? {}
+            : { sitePlanRouter: createSitePlanRouter(options.sitePlans) }),
+        importRouter: createImportRouter({
+            // `db`/`storage` are the very ones already in scope for the rest of
+            // this function — `@cogenta/import`'s real importer, unchanged, never
+            // reimplemented here (R9: this package gains no dependency on it, only
+            // `@cogenta/cli` does, which already had one for the terminal command).
+            runWordPressImport: (xml) => importWordPress(xml, { db, storage }),
+        }),
         mediaStore,
         storage,
+        images: options.images ?? null,
         graphqlSchema: buildContentSchema({ collections }),
-        gateway: createContentGateway({ collections, stores, permissions }),
-        schemaDocument: buildSchemaDocument(collections, {
-            locales: site.locales,
-            defaultLocale: site.defaultLocale,
-        }),
+        gateway,
+        permissions,
+        schemaDocument: buildSchemaDocument(collections, { locales: site.locales, defaultLocale: site.defaultLocale }, taxonomies),
+        redirects,
         collections,
+        taxonomies,
         site,
-        skinCss,
-        health,
+        styles,
+        security: options.security,
+        health: options.health,
+        tickScheduledPublishing: () => scheduledPublishQueue.tick(),
         dispose: async () => {
+            await scheduledPublishQueue.close();
             await db.close();
         },
     };
 }
+/**
+ * No route on this server takes a JSON body anywhere near this size — the
+ * one exception, `/api/site-plans`, already caps its base64 document
+ * payloads at 60 MiB total inside `site-plan-router.ts`. This is a ceiling
+ * above that, not a route-specific limit: `readBody` runs for every mutating
+ * request, most of them long before any permission check, so an unbounded
+ * read here was a way for an anonymous caller to make the server buffer an
+ * arbitrarily large body before ever being told no.
+ */
+const MAX_REQUEST_BODY_BYTES = 64 * 1024 * 1024;
 async function readBody(req) {
     const chunks = [];
-    for await (const chunk of req)
-        chunks.push(chunk);
+    let total = 0;
+    let tooLarge = false;
+    for await (const chunk of req) {
+        const buf = chunk;
+        total += buf.length;
+        if (total > MAX_REQUEST_BODY_BYTES) {
+            // Bound memory by not buffering any more chunks, but keep draining the
+            // socket rather than destroying it: a client mid-write over the same
+            // TCP connection this response has to go out on can be reset by an
+            // early `req.destroy()`, which loses the 413 response along with it.
+            // Letting the read finish costs bandwidth, never unbounded memory.
+            tooLarge = true;
+            continue;
+        }
+        chunks.push(buf);
+    }
+    if (tooLarge) {
+        throw new CogentaError({
+            code: 'REQUEST_BODY_TOO_LARGE',
+            message: `The request body exceeds the ${MAX_REQUEST_BODY_BYTES}-byte limit.`,
+            hint: 'Send a smaller payload.',
+        });
+    }
     if (chunks.length === 0)
         return undefined;
     const text = Buffer.concat(chunks).toString('utf8');
@@ -191,6 +591,35 @@ function toRestRequest(req, url, body) {
         ...(body === undefined ? {} : { body }),
     };
 }
+/**
+ * `CommerceRequest`'s `query` is single-valued (contract E has no route that
+ * takes a repeated key), unlike `RestRequest`'s — so this is its own small
+ * adapter rather than a cast of `toRestRequest`'s output.
+ */
+function toCommerceRequest(req, url, body) {
+    const query = {};
+    for (const key of url.searchParams.keys()) {
+        query[key] = url.searchParams.get(key) ?? undefined;
+    }
+    return {
+        method: req.method ?? 'GET',
+        path: url.pathname,
+        query,
+        ...(body === undefined ? {} : { body }),
+    };
+}
+/**
+ * The connecting socket's address — never trusted as anything more than an
+ * input to the daily session hash (`@cogenta/analytics`'s `hashSession`).
+ * No `x-forwarded-for` handling: trusting a client-supplied header for
+ * anything security- or privacy-relevant needs a configured trusted-proxy
+ * list this server does not have, and a wrong guess here would only ever
+ * make analytics *less* accurate, never leak anything (the header is never
+ * stored, only hashed).
+ */
+function clientIpOf(req) {
+    return req.socket.remoteAddress ?? 'unknown';
+}
 function responseId(response) {
     const data = response.body?.data;
     return typeof data?.id === 'string' ? data.id : undefined;
@@ -274,6 +703,28 @@ async function recordMediaAudit(site, actor, method, pathname, response, logger)
     })
         .catch((error) => logger.error('audit record failed', { error: String(error) }));
 }
+/**
+ * One entry per successful `POST /api/import/wordpress` — who ran it and how
+ * much it brought in, the same field the terminal command prints as
+ * `formatConversionReport`'s opening line. Never the document itself: a WXR
+ * export can carry a whole site's content, and the audit log is not a backup.
+ */
+async function recordImportAudit(site, actor, method, pathname, response, logger) {
+    if (method !== 'POST' || response.status < 200 || response.status >= 300)
+        return;
+    if (!pathname.startsWith('/api/import/'))
+        return;
+    const report = response.body?.data
+        ?.imported;
+    await site.auth.audit
+        .record({
+        actorId: actor.id,
+        actorRoles: actor.roles,
+        action: 'import.wordpress',
+        ...(report === undefined ? {} : { diff: report }),
+    })
+        .catch((error) => logger.error('audit record failed', { error: String(error) }));
+}
 async function recordAuthAudit(site, actor, method, pathname, response, logger) {
     if (response.status < 200 || response.status >= 300)
         return;
@@ -297,6 +748,80 @@ async function recordAuthAudit(site, actor, method, pathname, response, logger)
         .record({ actorId: userId, actorRoles: roles, action: 'auth.login' })
         .catch((error) => logger.error('audit record failed', { error: String(error) }));
 }
+/**
+ * Account management, in the audit log.
+ *
+ * Who created an account, who changed a role, who disabled someone and who cut
+ * a session short are exactly the events an append-only, hash-chained log
+ * exists for — and they were previously invisible, since the only way to do any
+ * of it was a terminal.
+ *
+ * Recorded here, at the transport boundary, for the same reason the content and
+ * media audits are: the router stays a pure request-in/response-out value, and
+ * only a response that actually succeeded is written down.
+ */
+async function recordUserAudit(site, actor, method, pathname, response, logger) {
+    if (response.status < 200 || response.status >= 300)
+        return;
+    const segments = pathname.split('/').filter((segment) => segment.length > 0);
+    // ['api', 'users', <id?>, <'sessions' | 'password'>?, <sessionId?>]
+    const target = segments[2];
+    const sub = segments[3];
+    const action = method === 'POST' && target === undefined
+        ? 'user.create'
+        : method === 'PATCH' && target !== undefined && sub === undefined
+            ? 'user.update'
+            : method === 'POST' && sub === 'password'
+                ? 'user.password_change'
+                : method === 'DELETE' && sub === 'sessions'
+                    ? 'user.session_revoke'
+                    : null;
+    if (action === null)
+        return;
+    // The subject is named, never anything that could sign anyone in: no
+    // password, no token, not even the new roles' provenance beyond the id.
+    const created = response.body?.data?.user;
+    const subjectId = typeof created?.id === 'string' ? created.id : target === 'me' ? actor.id : (target ?? null);
+    await site.auth.audit
+        .record({
+        actorId: actor.id,
+        actorRoles: actor.roles,
+        action,
+        ...(subjectId === null ? {} : { entryId: subjectId }),
+    })
+        .catch((error) => logger.error('audit record failed', { error: String(error) }));
+}
+/**
+ * Who minted or revoked a machine credential, in the same append-only log as
+ * every other account action (L13 task 8). The raw key itself never reaches
+ * this function — `POST`'s response carries it once, but the audit entry
+ * only ever names the key's id, exactly like `recordUserAudit` never logs a
+ * password.
+ */
+async function recordApiKeyAudit(site, actor, method, pathname, response, logger) {
+    if (response.status < 200 || response.status >= 300)
+        return;
+    const segments = pathname.split('/').filter((segment) => segment.length > 0);
+    // ['api', 'api-keys', <id?>]
+    const target = segments[2];
+    const action = method === 'POST' && target === undefined
+        ? 'apikey.create'
+        : method === 'DELETE' && target !== undefined
+            ? 'apikey.revoke'
+            : null;
+    if (action === null)
+        return;
+    const created = response.body?.data;
+    const subjectId = typeof created?.id === 'string' ? created.id : (target ?? null);
+    await site.auth.audit
+        .record({
+        actorId: actor.id,
+        actorRoles: actor.roles,
+        action,
+        ...(subjectId === null ? {} : { entryId: subjectId }),
+    })
+        .catch((error) => logger.error('audit record failed', { error: String(error) }));
+}
 function writeRestResponse(res, response) {
     res.writeHead(response.status, response.headers);
     res.end(response.body === null || response.body === undefined
@@ -330,6 +855,104 @@ async function serveMediaFile(site, actor, id, req, res) {
     stream.on('error', () => res.destroy());
     stream.pipe(res);
 }
+/**
+ * `GET /_image?id=…&w=…` — the public delivery endpoint for images.
+ *
+ * **Public on purpose, and only for images.** A `<img src>` in a published
+ * page is fetched by a visitor's browser with no session, so an endpoint the
+ * theme can point at cannot be behind the same authentication as
+ * `/api/media/{id}/file`. Restricting it to `kind === 'image'` is what keeps
+ * that from widening to every uploaded PDF and video: those stay behind the
+ * authenticated route, unchanged.
+ *
+ * It serves the rendition the upload already produced, and falls back to the
+ * original when there is none — an asset uploaded before the pipeline
+ * existed, a width outside the ladder, or a host with no image driver. It
+ * never renders on demand: nothing here decodes an image, so a public URL
+ * cannot be turned into CPU by asking for a size nobody stored.
+ */
+async function serveImageVariant(site, url, req, res) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.writeHead(405, { allow: 'GET' }).end();
+        return;
+    }
+    const id = url.searchParams.get('id');
+    if (id === null || id === '') {
+        jsonError(res, 400, 'QUERY_INVALID', 'An image request must name the media it wants.');
+        return;
+    }
+    const asset = await site.mediaStore.get(id);
+    if (asset === null || asset.kind !== 'image') {
+        jsonError(res, 404, 'MEDIA_NOT_FOUND', `No image asset with id "${id}".`);
+        return;
+    }
+    let key = asset.storageKey;
+    // Never the asset's recorded `mimeType` unquestioned. Uploads now record
+    // the sniffed type, but an asset stored before that fix — or by a future
+    // writer that skips the route — could carry `text/html`, and this endpoint
+    // is public, unauthenticated and on the site's own origin. A type that is
+    // not an image serves as an opaque download instead of executing.
+    let contentType = SERVABLE_IMAGE_TYPES.has(asset.mimeType)
+        ? asset.mimeType
+        : 'application/octet-stream';
+    const requested = Number(url.searchParams.get('w'));
+    if (site.images !== null &&
+        Number.isInteger(requested) &&
+        requested > 0 &&
+        asset.width !== null &&
+        asset.height !== null) {
+        const names = site.images.variantNames({ width: asset.width, height: asset.height });
+        const wanted = `${requested}.`;
+        const match = names.find((name) => name.startsWith(wanted));
+        if (match !== undefined) {
+            const variantKey = variantKeyFor(id, match);
+            if (await site.storage.exists(variantKey)) {
+                key = variantKey;
+                if (match.endsWith('.webp'))
+                    contentType = 'image/webp';
+            }
+        }
+    }
+    const stream = await site.storage.get(key);
+    res.writeHead(200, {
+        'content-type': contentType,
+        // Long, because the URL names an immutable rendition of an immutable
+        // upload: replacing an image means a new media id, never new bytes under
+        // the same one.
+        'cache-control': 'public, max-age=31536000, immutable',
+    });
+    stream.on('error', () => res.destroy());
+    stream.pipe(res);
+}
+/**
+ * Loads the media a theme render references, as `@cogenta/render`'s
+ * `MediaAsset`.
+ *
+ * The two shapes are deliberately different types (ADR-0016: the delivery
+ * plane declares its own wire types rather than importing the engine's), so
+ * this is the one place they are mapped. Only images and videos exist in that
+ * shape at all — a PDF has no `srcset` — so anything else is left out and
+ * `ctx.image()` refuses it clearly.
+ */
+async function loadRenderMedia(site, ids) {
+    const found = new Map();
+    for (const id of new Set(ids)) {
+        const asset = await site.mediaStore.get(id);
+        if (asset === null)
+            continue;
+        if (asset.kind !== 'image' && asset.kind !== 'video')
+            continue;
+        found.set(id, {
+            id: asset.id,
+            kind: asset.kind,
+            alt: asset.alt,
+            ...(asset.width === null ? {} : { width: asset.width }),
+            ...(asset.height === null ? {} : { height: asset.height }),
+            focal: asset.focal,
+        });
+    }
+    return found;
+}
 /**
  * Builds the Node request handler from an already-assembled site.
  *
@@ -342,6 +965,11 @@ async function serveMediaFile(site, actor, id, req, res) {
 export function createRequestListener(site, logger) {
     return async (req, res) => {
         const url = new URL(req.url ?? '/', 'http://localhost');
+        // Before anything else, and once: CORS, the security headers and the
+        // cache-control class of this path (L10 task 6). A preflight is answered
+        // here and never reaches a route.
+        if (applySecurity(req, res, url.pathname, site.security))
+            return;
         try {
             const actor = await resolveActor(site.auth, Object.fromEntries(Object.entries(req.headers).map(([key, value]) => [
                 key,
@@ -367,12 +995,46 @@ export function createRequestListener(site, logger) {
                 jsonError(res, 404, 'CONTENT_NOT_FOUND', 'No admin asset matches this path.');
                 return;
             }
+            // The theme's stylesheet: public, cacheable, and the same URL every
+            // page links, so a visitor pays for ~26 kB once instead of on every
+            // page. Inlining it in each document would cost that on every
+            // navigation; a `<link>` with a real ETag costs a conditional request
+            // that answers 304. There is nothing to permission-check — the sheet is
+            // derived from the skin's tokens and contains no content.
+            if (url.pathname === STYLESHEET_PATH) {
+                if (req.method !== 'GET') {
+                    res.writeHead(405, { allow: 'GET' }).end();
+                    return;
+                }
+                if (site.styles === null) {
+                    jsonError(res, 404, 'CONTENT_NOT_FOUND', 'This site has no stylesheet.');
+                    return;
+                }
+                const etag = cssEtag(site.styles);
+                if (req.headers['if-none-match'] === etag) {
+                    res.writeHead(304, { etag }).end();
+                    return;
+                }
+                res.writeHead(200, {
+                    'content-type': 'text/css; charset=utf-8',
+                    etag,
+                    // Revalidate every time: a skin swap must show up on the next
+                    // request, which is the whole promise of contract D's hot swap. The
+                    // ETag makes that revalidation a 304 rather than a re-download.
+                    'cache-control': 'public, max-age=0, must-revalidate',
+                });
+                res.end(site.styles);
+                return;
+            }
             if (url.pathname.startsWith('/api/auth/')) {
                 const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
                 const request = toRestRequest(req, url, body);
                 const response = await site.authRouter.handle(request);
                 writeRestResponse(res, response);
                 await recordAuthAudit(site, actor, req.method ?? 'GET', url.pathname, response, logger);
+                // A refused sign-in is the only clock a brute-force alert can honestly
+                // have here (L14 task 4) — see `security-alerts.ts` for why not a timer.
+                await site.securityAlerts?.observe(response.status);
                 return;
             }
             // Public and read-only: `schema.json` describes collection shapes and
@@ -390,6 +1052,13 @@ export function createRequestListener(site, logger) {
             // Serving the file itself sits outside `mediaRouter`: its `RestResponse`
             // is JSON-only, and a binary body has no shape to fit into that without
             // widening the transport contract every other route relies on.
+            // The public image endpoint (L10 task 5). Before the `/api/*` block on
+            // purpose: it is not an API route, and it is the one media path a
+            // visitor's browser reaches with no session.
+            if (url.pathname === DEFAULT_IMAGE_ENDPOINT) {
+                await serveImageVariant(site, url, req, res);
+                return;
+            }
             const fileMatch = /^\/api\/media\/([^/]+)\/file$/u.exec(url.pathname);
             if (fileMatch !== null) {
                 await serveMediaFile(site, actor, decodeURIComponent(fileMatch[1] ?? ''), req, res);
@@ -421,6 +1090,49 @@ export function createRequestListener(site, logger) {
                 await recordContentAudit(site, actor, req.method ?? 'GET', url.pathname, body, response, logger);
                 return;
             }
+            // Terms live apart from content on purpose: a taxonomy is not a
+            // collection, and a site may legitimately name both the same thing
+            // (ADR-0022). Its router owns its own permission door.
+            if (url.pathname.startsWith('/api/taxonomies')) {
+                const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
+                const request = toRestRequest(req, url, body);
+                writeRestResponse(res, await site.taxonomyRouter.handle(request, context));
+                return;
+            }
+            if (url.pathname.startsWith('/api/marketplace')) {
+                const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
+                const request = toRestRequest(req, url, body);
+                writeRestResponse(res, await site.marketplaceRouter.handle(request, context.actor));
+                return;
+            }
+            // A menu is not schema-declared like a taxonomy, but it gets its own
+            // mount for the same reason: it is not a collection, and its router owns
+            // its own (fixed, not per-site-configurable) permission door.
+            if (url.pathname.startsWith('/api/menus')) {
+                const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
+                const request = toRestRequest(req, url, body);
+                writeRestResponse(res, await site.menuRouter.handle(request, context));
+                return;
+            }
+            // Contract E's own back office, gated by its own permission vocabulary
+            // (`commerce.*`, ADR-0024) — never contract A's five actions, which do
+            // not stretch to "refund" or "issue an invoice".
+            if (url.pathname.startsWith('/api/commerce')) {
+                const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
+                const request = toCommerceRequest(req, url, body);
+                const response = await site.commerceRouter.handle(request, context.actor);
+                // The one route whose body is not JSON: an invoice PDF. Checked by
+                // shape, not by path — the router already decided what to send, this
+                // layer only has to notice how.
+                if (response.body instanceof Uint8Array) {
+                    res.writeHead(response.status, { 'content-type': 'application/pdf' });
+                    res.end(Buffer.from(response.body));
+                    return;
+                }
+                res.writeHead(response.status, { 'content-type': 'application/json; charset=utf-8' });
+                res.end(response.body === null ? undefined : JSON.stringify(response.body));
+                return;
+            }
             if (url.pathname.startsWith('/api/media')) {
                 const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
                 const request = toRestRequest(req, url, body);
@@ -429,11 +1141,107 @@ export function createRequestListener(site, logger) {
                 await recordMediaAudit(site, actor, req.method ?? 'GET', url.pathname, response, logger);
                 return;
             }
+            // The admin screen the redirect table never had: creating and removing
+            // a rule from a browser instead of the database directly (audit
+            // follow-up to L10 task 2). Admin-only, checked by the router itself.
+            if (url.pathname === '/api/redirects') {
+                const body = req.method === 'POST' ? await readBody(req) : undefined;
+                const request = toRestRequest(req, url, body);
+                writeRestResponse(res, await site.redirectRouter.handle(request, context));
+                return;
+            }
+            // Read-only mirrors of `security`/`webhooks` from the config file (audit
+            // follow-up to L10 task 6 / L14 task 1) — see `ops-status-router.ts` for
+            // why editing them here would be the wrong architecture.
+            if (url.pathname === '/api/security-status' || url.pathname === '/api/webhooks-status') {
+                const request = toRestRequest(req, url, undefined);
+                writeRestResponse(res, await site.opsStatusRouter.handle(request, context));
+                return;
+            }
+            // The full-text index, reachable at last (L10 task 3). Its own router
+            // decides which collections this actor may search — never this layer.
+            if (url.pathname === '/api/search') {
+                const request = toRestRequest(req, url, undefined);
+                writeRestResponse(res, await site.searchRouter.handle(request, context));
+                return;
+            }
+            // `/api/analytics/beacon` (public) and `/api/analytics/summary`
+            // (admin-only) — see `@cogenta/analytics` and `analytics-router.ts` for
+            // why both live behind one router with opposite trust models.
+            if (url.pathname.startsWith('/api/analytics')) {
+                const request = toRestRequest(req, url, undefined);
+                writeRestResponse(res, await site.analyticsRouter.handle(request, { actor: context.actor, ip: clientIpOf(req) }));
+                return;
+            }
             if (url.pathname.startsWith('/api/audit')) {
                 const request = toRestRequest(req, url, undefined);
                 writeRestResponse(res, await site.auditRouter.handle(request, context.actor));
                 return;
             }
+            if (url.pathname.startsWith('/api/notices')) {
+                const request = toRestRequest(req, url, undefined);
+                writeRestResponse(res, await site.noticeRouter.handle(request, context.actor));
+                return;
+            }
+            if (url.pathname.startsWith('/api/users')) {
+                const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
+                const request = toRestRequest(req, url, body);
+                const response = await site.usersRouter.handle(request, context.actor);
+                writeRestResponse(res, response);
+                await recordUserAudit(site, actor, req.method ?? 'GET', url.pathname, response, logger);
+                return;
+            }
+            // Machine-to-machine bearer credentials, admin-only (L13 task 8).
+            if (url.pathname.startsWith('/api/api-keys')) {
+                const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
+                const request = toRestRequest(req, url, body);
+                const response = await site.apiKeysRouter.handle(request, context.actor);
+                writeRestResponse(res, response);
+                await recordApiKeyAudit(site, actor, req.method ?? 'GET', url.pathname, response, logger);
+                return;
+            }
+            if (url.pathname.startsWith('/api/site-plans') && site.sitePlanRouter !== undefined) {
+                // `SitePlanRouter` itself refuses every route to a non-admin actor,
+                // but only after `readBody` has already buffered the whole request —
+                // and this route, alone among this server's routes, invites
+                // multi-megabyte bodies by design (uploaded documents). Checking the
+                // role here, before the body is read at all, means an unauthenticated
+                // or non-admin caller is turned away without the server ever reading
+                // what they sent.
+                if (!context.actor.roles.includes('admin')) {
+                    jsonError(res, 403, 'FORBIDDEN', 'Only the admin role may propose or apply a site plan.');
+                    return;
+                }
+                const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
+                const request = toRestRequest(req, url, body);
+                writeRestResponse(res, await site.sitePlanRouter.handle(request, context.actor));
+                return;
+            }
+            // The admin's WordPress importer. Same defensive order as
+            // `/api/site-plans` just above and for the same reason: this route
+            // invites a multi-megabyte upload by design, so the role is checked
+            // before `readBody` buffers anything at all.
+            if (url.pathname.startsWith('/api/import')) {
+                if (!context.actor.roles.includes('admin')) {
+                    jsonError(res, 403, 'FORBIDDEN', 'Only the admin role may import content.');
+                    return;
+                }
+                const body = req.method === 'GET' ? undefined : await readBody(req);
+                const request = toRestRequest(req, url, body);
+                const response = await site.importRouter.handle(request, context.actor);
+                writeRestResponse(res, response);
+                await recordImportAudit(site, actor, req.method ?? 'GET', url.pathname, response, logger);
+                return;
+            }
+            // Always mounted, on every site (L18). On one with no AI provider it is
+            // the route that answers `{available: false}`, which is precisely what
+            // lets the admin panel disappear instead of failing.
+            if (url.pathname.startsWith('/api/assistant')) {
+                const body = req.method === 'GET' ? undefined : await readBody(req);
+                const request = toRestRequest(req, url, body);
+                writeRestResponse(res, await site.assistantRouter.handle(request, context));
+                return;
+            }
             if (url.pathname.startsWith('/api/agents') && site.agentsRouter !== undefined) {
                 const request = toRestRequest(req, url, undefined);
                 writeRestResponse(res, await site.agentsRouter.handle(request, context.actor));
@@ -459,22 +1267,204 @@ export function createRequestListener(site, logger) {
                 res.end(JSON.stringify({ data: health }));
                 return;
             }
+            // The visual page builder's preview (L16). It renders an *unsaved* block
+            // list through the very function that renders the published page, so the
+            // builder can show the real thing in an iframe instead of a React
+            // approximation of the twelve blocks.
+            //
+            // Three gates, in this order, before any of that happens:
+            //  1. an authenticated actor — an anonymous caller has no editing
+            //     session, so it has no business asking for a render of a page state
+            //     that does not exist yet;
+            //  2. `update` on the collection, asked of the same `PermissionLayer`
+            //     every other write path asks (R4: the route verifies, the renderer
+            //     does not);
+            //  3. `renderDraftPage` reads the stored entry through the same
+            //     permission-checked gateway, and every `collectionList` block on
+            //     the page queries through it too — so a draft cannot be used to
+            //     read content this actor could not already read.
+            if (url.pathname === '/api/builder/render') {
+                if (req.method !== 'POST') {
+                    res.writeHead(405, { allow: 'POST' }).end();
+                    return;
+                }
+                if (actor.id === null) {
+                    jsonError(res, 401, 'UNAUTHENTICATED', 'This preview needs a signed-in editor.');
+                    return;
+                }
+                const body = (await readBody(req));
+                const collectionName = typeof body?.collection === 'string' ? body.collection : '';
+                const entryId = typeof body?.entryId === 'string' ? body.entryId : '';
+                const collection = site.collections.find((entry) => entry.name === collectionName);
+                if (collection === undefined || entryId === '') {
+                    jsonError(res, 404, 'CONTENT_NOT_FOUND', 'No such collection or entry.');
+                    return;
+                }
+                // `errorResponse` rather than the outer catch: it is what turns a
+                // `CogentaError` into the status its code deserves (403 for
+                // `FORBIDDEN`), and it is already the mapping every `/api/*` router
+                // uses. The outer catch would answer 500 to a refusal.
+                let html;
+                try {
+                    site.permissions.assert('update', collection, context);
+                    html = await renderDraftPage({
+                        collection: collectionName,
+                        entryId,
+                        blocks: (body?.blocks ?? {}),
+                        ...(typeof body?.values === 'object' && body.values !== null
+                            ? { values: body.values }
+                            : {}),
+                    }, {
+                        collections: site.collections,
+                        gateway: site.gateway,
+                        site: site.site,
+                        styles: site.styles,
+                        loadMedia: (ids) => loadRenderMedia(site, ids),
+                        // Present so the preview's `<body>` stays byte-identical to the
+                        // published page's (the property `theme-render-fidelity`
+                        // proves) — a POST carries no navigation `Referer` to report,
+                        // so this omits `referrer` the same way an ordinary page view
+                        // with no referrer does. The preview does still count as a
+                        // view; there is no distinct "not a real visit" signal to send
+                        // that would not itself become a body difference.
+                        analyticsBeacon: {},
+                        menuRouter: site.menuRouter,
+                    }, context);
+                }
+                catch (error) {
+                    logger.warn('builder preview refused', {
+                        error: isCogentaError(error) ? error.toJSON() : String(error),
+                    });
+                    writeRestResponse(res, errorResponse(error));
+                    return;
+                }
+                if (html === null) {
+                    jsonError(res, 404, 'CONTENT_NOT_FOUND', 'No such collection or entry.');
+                    return;
+                }
+                res.writeHead(200, {
+                    'content-type': 'application/json; charset=utf-8',
+                    // A draft is never cacheable, by anyone, for any length of time.
+                    'cache-control': 'no-store',
+                });
+                res.end(JSON.stringify({ data: { html } }));
+                return;
+            }
+            // Everything below is the public site rather than the API, so the
+            // redirect table gets its turn first: a page renamed last month must
+            // answer its old URL with the 301 the rename recorded, not a 404 (L10
+            // task 2). Before route matching, so a redirect wins even when some
+            // other entry has since taken the old path — that is what `release()`
+            // is for on the write side.
+            if (req.method === 'GET' || req.method === 'HEAD') {
+                const redirect = await site.redirects.resolve(url.pathname);
+                if (redirect !== null) {
+                    res.writeHead(redirect.status, {
+                        location: `${redirect.to}${url.search}`,
+                        'cache-control': redirect.status === 301 ? 'public, max-age=3600' : 'no-store',
+                    });
+                    res.end();
+                    return;
+                }
+            }
+            // `robots.txt` and `sitemap.xml`, from the real content (L10 task 2).
+            // Both are built as `ANONYMOUS` inside `collectRoutedResources`,
+            // whoever asked: a crawler and a signed-in editor must get the same
+            // document, or the sitemap advertises URLs the crawler cannot fetch.
+            if (url.pathname === '/robots.txt') {
+                if (req.method !== 'GET') {
+                    res.writeHead(405, { allow: 'GET' }).end();
+                    return;
+                }
+                res.writeHead(200, {
+                    'content-type': 'text/plain; charset=utf-8',
+                    'cache-control': 'public, max-age=3600',
+                });
+                res.end(renderRobots(seoSiteFor(site.site)));
+                return;
+            }
+            if (SITEMAP_PATH.test(url.pathname)) {
+                if (req.method !== 'GET') {
+                    res.writeHead(405, { allow: 'GET' }).end();
+                    return;
+                }
+                const seoSite = seoSiteFor(site.site);
+                const files = buildSitemapFiles(seoSite, await collectRoutedResources(site.collections, site.gateway));
+                const file = files.find((candidate) => candidate.path === url.pathname);
+                if (file !== undefined) {
+                    res.writeHead(200, {
+                        'content-type': 'application/xml; charset=utf-8',
+                        'cache-control': 'public, max-age=600',
+                    });
+                    res.end(file.contents);
+                    return;
+                }
+                // `/sitemap-9.xml` on a site that only needs one file is a real 404,
+                // not an empty urlset: an empty chunk would tell a crawler the site
+                // has nothing there rather than that the URL is wrong.
+                jsonError(res, 404, 'CONTENT_NOT_FOUND', 'No sitemap file at this path.');
+                return;
+            }
+            // The public search page (L10 task 3): a real form and a real results
+            // list, served through the same permission-checked search router the
+            // API uses. Deliberately a route rather than a contract B block — see
+            // `search-page.ts` for why.
+            if (url.pathname === '/search' && req.method === 'GET') {
+                const html = await renderSearchPage(url.searchParams.get('q') ?? '', {
+                    router: site.searchRouter,
+                    gateway: site.gateway,
+                    collections: site.collections,
+                    site: site.site,
+                    styles: site.styles,
+                }, context);
+                res.writeHead(200, {
+                    'content-type': 'text/html; charset=utf-8',
+                    'cache-control': 'no-store',
+                });
+                res.end(html);
+                return;
+            }
             // Real theme HTML for anything else — see `theme-render.ts`'s own
             // doc comment for what this is and, as importantly, what it isn't
             // (no Astro build, one theme, no image pipeline). GET only: rendering
             // a page has no meaningful response to any other method.
             if (req.method === 'GET') {
-                const html = await renderRequestedPage(url.pathname, {
+                const renderOptions = {
                     collections: site.collections,
                     gateway: site.gateway,
                     site: site.site,
-                    skinCss: site.skinCss,
-                }, context);
+                    styles: site.styles,
+                    loadMedia: (ids) => loadRenderMedia(site, ids),
+                    // Self-hosted analytics (`@cogenta/analytics`): the referrer is read
+                    // from *this* request's own header, server-side — see
+                    // `analyticsBeaconTag` in `theme-render.ts` for why that, rather
+                    // than a client script, is how this page's beacon pixel gets it.
+                    analyticsBeacon: { referrer: req.headers.referer },
+                    menuRouter: site.menuRouter,
+                };
+                const html = await renderRequestedPage(url.pathname, renderOptions, context);
                 if (html !== null) {
                     res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
                     res.end(html);
                     return;
                 }
+                // The site's own 404 page (L14 task 2). It is an ordinary entry at
+                // `site.notFoundPath`, rendered by exactly the same function and
+                // through exactly the same permission-checked gateway as any other
+                // page — a custom 404 that could show content the visitor may not read
+                // would be a hole, not a feature.
+                //
+                // The guard matters: without it, a site whose 404 page is missing (or
+                // whose `notFoundPath` is itself unroutable) would ask for it again
+                // for every unmatched URL forever. One extra lookup, never two.
+                if (url.pathname !== site.site.notFoundPath) {
+                    const notFound = await renderRequestedPage(site.site.notFoundPath, renderOptions, context);
+                    if (notFound !== null) {
+                        res.writeHead(404, { 'content-type': 'text/html; charset=utf-8' });
+                        res.end(notFound);
+                        return;
+                    }
+                }
             }
             res.writeHead(404, { 'content-type': 'application/json; charset=utf-8' });
             res.end(JSON.stringify({
@@ -485,6 +1475,10 @@ export function createRequestListener(site, logger) {
             logger.error('request failed', {
                 error: isCogentaError(error) ? error.toJSON() : String(error),
             });
+            if (isCogentaError(error) && error.code === 'REQUEST_BODY_TOO_LARGE') {
+                jsonError(res, 413, error.code, error.message);
+                return;
+            }
             res.writeHead(500, { 'content-type': 'application/json; charset=utf-8' });
             res.end(JSON.stringify({
                 error: { code: 'INTERNAL', message: 'The request could not be completed.' },
@@ -494,6 +1488,20 @@ export function createRequestListener(site, logger) {
 }
 const DEFAULT_PORT = 4000;
 const DEFAULT_HOST = '127.0.0.1';
+/** How long a shutdown waits for open connections before cutting them. */
+const SHUTDOWN_GRACE_MS = 2_000;
+/**
+ * How often `runServe` drains due scheduled-publication jobs (R1).
+ *
+ * `cogenta serve` has no persistent worker process beyond itself, so this
+ * `setInterval` *is* the cron a hosted deployment with no worker would
+ * otherwise need to configure by hand. The honest trade this makes: a page
+ * scheduled for 09:00 goes live between 09:00 and 09:01, not exactly on the
+ * hour. If the process is stopped when a publication comes due, nothing is
+ * lost — the job is still in the `database` queue's table — it simply runs
+ * on the first tick after the next start, however late that is.
+ */
+const SCHEDULED_PUBLISH_TICK_MS = 60_000;
 /**
  * Runs until `options.signal` aborts. Returns 0 on a clean shutdown, 1 if
  * startup failed — nothing here calls `process.exit` (same convention as
@@ -515,8 +1523,11 @@ export async function runServe(options) {
         return 1;
     }
     let collections;
+    let taxonomies;
     try {
-        collections = await loadCollections(projectRoot);
+        const schema = await loadSchemaModule(projectRoot);
+        collections = schema.collections;
+        taxonomies = schema.taxonomies;
     }
     catch (error) {
         if (isCogentaError(error)) {
@@ -531,8 +1542,73 @@ export async function runServe(options) {
     }
     const selection = await createDatabaseRegistry({ logger }).select(loaded.config.database);
     const storageSelection = await createStorageRegistry({ logger }).select(loaded.config.storage);
-    const skinCss = await loadSkinCss((path) => readFile(path, 'utf8'), join(projectRoot, 'theme.tokens.json'));
-    const site = await assembleSite(selection.instance, collections, loaded.config.auth.signingKey, loaded.config.site, storageSelection.instance, async () => ({ database: await selection.health(), storage: await storageSelection.health() }), undefined, options.readOnly ?? false, skinCss);
+    const styles = joinStyles(await loadSkinCss((path) => readFile(path, 'utf8'), join(projectRoot, 'theme.tokens.json')), await loadThemeCss({ read: (url) => readFile(url, 'utf8') }));
+    const images = await selectMediaImageProcessor(logger);
+    // One signed channel for both outbound events — the content lifecycle (task
+    // 1) and the suspicious-activity alert (task 4). One set of endpoints, one
+    // secret, one signing path.
+    const webhooks = createContentWebhookEmitter({
+        webhooks: loaded.config.webhooks,
+        siteUrl: loaded.config.site.url,
+        logger,
+    });
+    // L18. Never fatal: everything inside degrades to "off" with a log line
+    // rather than stopping the site from serving (R2).
+    const searchIndex = await createSearchIndex({ db: selection.instance });
+    const assistant = await buildAssistant({
+        config: loaded.config,
+        db: selection.instance,
+        logger,
+        // Beside the full-text index, never instead of it: the semantic half is
+        // fused with this one by RRF (L18 task 5).
+        fullText: searchIndex,
+    });
+    const site = await assembleSite({
+        db: selection.instance,
+        assistant,
+        searchIndex,
+        collections,
+        taxonomies,
+        signingKey: loaded.config.auth.signingKey,
+        site: loaded.config.site,
+        storage: storageSelection.instance,
+        logger,
+        health: async () => ({
+            database: await selection.health(),
+            storage: await storageSelection.health(),
+        }),
+        readOnly: options.readOnly ?? false,
+        styles,
+        images: images?.processor ?? null,
+        security: loaded.config.security,
+        webhooks: loaded.config.webhooks,
+        billing: loaded.config.billing,
+        sitePlans: await createSitePlanning({
+            projectRoot,
+            db: selection.instance,
+            collections,
+            config: loaded.config,
+            logger,
+            readOnly: options.readOnly ?? false,
+            // ADR-0010: the schema is writable in development only. `cogenta dev`
+            // says development; `cogenta serve` does not, and a plan can then be
+            // proposed and reviewed but never applied.
+            development: options.development ?? false,
+        }),
+        // The signed outbound webhook channel, connected to the content lifecycle
+        // for the first time (L14 task 1). `null` when the site configured no
+        // endpoint, or configured one without a signing secret.
+        onContentEvent: webhooks.emit,
+        onSecurityEvent: webhooks.send,
+        // Same mail this site's `cogenta users reset-password --email` already
+        // sends (`../reset-mail.js`), just pointed at the admin's reset screen
+        // instead of a terminal command — see that file for why the wording is
+        // written once rather than twice.
+        onForgotPassword: ({ user, token, expiresAt }) => sendResetMail({
+            mailDir: join(projectRoot, '.cogenta', 'mail'),
+            resetUrl: new URL('/admin/reset-password', loaded.config.site.url).toString(),
+        }, loaded.config.site, user.email, token, expiresAt).then(() => undefined),
+    });
     const server = createServer(createRequestListener(site, logger));
     const port = options.port ?? DEFAULT_PORT;
     const host = options.host ?? DEFAULT_HOST;
@@ -546,8 +1622,24 @@ export async function runServe(options) {
     const address = server.address();
     const boundPort = typeof address === 'object' && address !== null ? address.port : port;
     out.ok(`Listening on http://${host}:${boundPort}`);
-    out.detail(`${collections.length} collection(s), db driver: ${selection.driver}, storage driver: ${storageSelection.driver}`);
+    out.detail(`${collections.length} collection(s), db driver: ${selection.driver}, storage driver: ${storageSelection.driver}, image driver: ${images?.driver ?? 'none'}`);
+    out.detail(assistant.summary);
     options.onListening?.({ port: boundPort, host });
+    // Scheduled publication (task 1): a first tick right away catches up on
+    // anything that came due while the process was down, then one every
+    // `SCHEDULED_PUBLISH_TICK_MS` for as long as this server runs. A failed
+    // tick is logged, never fatal — a scheduling hiccup must not take the
+    // whole site down.
+    const runScheduledPublishTick = () => {
+        site.tickScheduledPublishing().catch((error) => {
+            logger.error('scheduled publish tick failed', { error: String(error) });
+        });
+    };
+    runScheduledPublishTick();
+    const scheduledPublishTimer = setInterval(runScheduledPublishTick, options.scheduledPublishTickMs ?? SCHEDULED_PUBLISH_TICK_MS);
+    // Never keeps the process alive on its own: a `signal`-driven shutdown with
+    // no open connections must still be able to exit.
+    scheduledPublishTimer.unref();
     await new Promise((resolve) => {
         if (options.signal === undefined)
             return;
@@ -557,9 +1649,19 @@ export async function runServe(options) {
         }
         options.signal.addEventListener('abort', () => resolve(), { once: true });
     });
+    clearInterval(scheduledPublishTimer);
     await new Promise((resolve, reject) => {
         server.close((error) => (error ? reject(error) : resolve()));
+        // `close()` alone waits for every open connection to end, and a client
+        // that fetched a large response and never read the body holds one open
+        // indefinitely — a media download is exactly that shape. Without the
+        // grace period, one such client turns Ctrl-C into a hang. Found while
+        // writing the image tests, where a deliberately unread image body kept
+        // the whole process alive.
+        const grace = setTimeout(() => server.closeAllConnections(), SHUTDOWN_GRACE_MS);
+        grace.unref();
     });
+    await assistant.dispose();
     await selection.dispose();
     await storageSelection.dispose();
     await site.dispose().catch(() => undefined); // selection.dispose() already closed the same handle