@glw907/cairn-cms 0.58.0 → 0.60.0

package/src/lib/sveltekit/content-routes.ts

@@ -10,13 +10,23 @@ import { deriveExcerpt } from '../content/excerpt.js';
 import { asString } from '../content/identity.js';
 import { isValidId, slugify, filenameFromId, composeDatedId, slugFromId, renameId } from '../content/ids.js';
 import { appCredentials, type GithubKeyEnv } from '../github/credentials.js';
-import { listMarkdown, readRaw, commitFiles, type FileChange } from '../github/repo.js';
+import { listMarkdown, readRaw, commitFile, commitFiles, type FileChange } from '../github/repo.js';
 import { branchHeadSha, createBranch, deleteBranch, listBranches } from '../github/branches.js';
 import { PENDING_PREFIX, pendingBranch, parsePendingBranch } from '../content/pending.js';
 import { cachedInstallationToken } from '../github/signing.js';
 import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest, upsertEntry, removeEntry, inboundLinks, type Manifest, type LinkTarget, type InboundLink } from '../content/manifest.js';
 import { isConflict } from '../github/types.js';
 import { log } from '../log/index.js';
+import { dictionaryFileForDialect, DEFAULT_TIDY_MODEL, resolveTidyConventions, parseSiteConfig, setTidy, validateTidyConventions, TidyConventionsError } from '../nav/site-config.js';
+import type { TidyConventions } from '../nav/site-config.js';
+import { buildTidyPrompt } from './tidy-prompt.js';
+// Server-only: the Anthropic SDK ships the API-key path and never reaches a browser bundle. It is
+// imported only here (a Worker module no component imports statically), and the server-only-deps test
+// guards that boundary. The default export is the Anthropic client class; the structural TidyClient
+// type below keeps the action's surface small and the test seam injectable, so the SDK's deep types
+// never leak into a public signature.
+import Anthropic from '@anthropic-ai/sdk';
+import { parseDictionary, mergeDictionaryWords, serializeDictionary, isValidDictionaryWord } from '../content/site-dictionary.js';
 import { issueCsrfToken, validateCsrfHeader } from './csrf.js';
 import { requireSession } from './guard.js';
 import { sniffMediaType, isDeniedUpload, extForMediaType } from '../media/sniff.js';
@@ -29,10 +39,14 @@ import { mediaLibraryEntry } from '../media/library-entry.js';
 import type { MediaLibrary, MediaLibraryEntry } from '../media/library-entry.js';
 import { buildUsageIndex } from '../media/usage.js';
 import type { UsageEntry } from '../media/usage.js';
+import { runReconcile, MEDIA_KEY_RE, type ReconcileBucket } from '../media/reconcile.js';
+import { buildOrphanScan, type OrphanScan } from '../media/orphan-scan.js';
 import { repointMediaRef, fillAltForHash } from '../content/media-rewrite.js';
 import type { RepointPlacement, AltPlacement } from '../content/media-rewrite.js';
 import { planMediaRewrite } from '../media/rewrite-plan.js';
 import type { BranchRef } from '../media/rewrite-plan.js';
+import { planBulkDelete } from '../media/bulk-delete-plan.js';
+import type { BulkDeleteSkip } from '../media/bulk-delete-plan.js';
 import type { CookieJar, EventBase } from './types.js';
 import type { CairnRuntime, ConceptDescriptor, FrontmatterField, PreviewConfig, ResolvedPreview } from '../content/types.js';
 import type { Editor, Role } from '../auth/types.js';
@@ -138,6 +152,22 @@ export interface EditData {
    *  when one exists, applied over the top-level values); null when the site sets none, which
    *  leaves the frame rendering unstyled markup behind a hint. */
   preview: ResolvedPreview | null;
+  /** The spellcheck dictionary file for the site's configured dialect (default US English), resolved
+   *  once at compose. The editor resolves it to a real asset URL on the main thread and hands that URL
+   *  to the spellcheck Worker's `init`, the same way `mediaLibrary` is threaded in. Just the filename,
+   *  e.g. "dictionary-en-us.txt". */
+  spellcheckDictionary: string;
+  /** The committed personal-dictionary words for the site (spec 1.6): the durable, shared, reviewable
+   *  layer the editor seeds the spellcheck Worker's personal set from, the way `mediaLibrary` is handed
+   *  in. Read from the git-committed `dictionary.txt` at editor load; empty when the file is absent or
+   *  unreadable (the editor degrades to dialect-only). The dialect dictionary and the session ignore
+   *  list are the other two layers; only this one is committed. */
+  siteDictionary: string[];
+  /** The editor-tier tidy facts the review surface needs (spec 2.5): whether tidy is enabled, the model
+   *  that runs (for the head pill), and the RESOLVED conventions (the only data source for a
+   *  normalization's because-line and the local category inference). The API key never appears here, it
+   *  is a Worker secret. `enabled` false hides the Tidy control. */
+  tidy: { enabled: boolean; model: string; conventions: TidyConventions };
 }
 
 /** One asset's where-used overlay, kept separate from MediaLibraryEntry so the picker's shared
@@ -161,14 +191,52 @@ export interface MediaLibraryData {
    *  redirected commit conflict never overwrite each other. */
   error: string | null;
   /** The success flash a redirected action carries: `deleted` from `?deleted=1`, `updated` from
-   *  `?updated=1`, `replaced` from `?replaced=1`, `altPropagated` from `?altPropagated=1`, null
-   *  otherwise. The component renders a polite success strip for each. */
-  flash: 'deleted' | 'updated' | 'replaced' | 'altPropagated' | null;
+   *  `?updated=1`, `replaced` from `?replaced=1`, `altPropagated` from `?altPropagated=1`,
+   *  `bulkDeleted` from `?bulkDeleted=1`, `orphansPurged` from `?orphansPurged=1`, null otherwise.
+   *  The component renders a polite success strip for each. */
+  flash: 'deleted' | 'updated' | 'replaced' | 'altPropagated' | 'bulkDeleted' | 'orphansPurged' | null;
   /** A redirected action's conflict error read from `?error=` (a commit-conflict bounce). Kept in
    *  its own slot rather than the degraded-load `error` above, so the two never collide. */
   flashError: string | null;
 }
 
+/** The two-tier tidy settings load (spec 2.8, Task 15). The developer tier is read-only: `enabled`,
+ *  `keyConfigured`, and `model`/`modelLabel` are deploy-time facts the editor sees but cannot change.
+ *  The editor tier is the resolved `conventions` block, written back through the save. The visibility
+ *  gate is truthful: `enabled` is true only when `tidy.enabled` is set AND the API key is present, so
+ *  the screen renders the convention list only then and the honest gate note otherwise. The key is a
+ *  Worker secret, so `keyConfigured` is the presence of `ANTHROPIC_API_KEY` in the load's env, never
+ *  the key itself; nothing here returns or logs the secret. */
+export interface SettingsData {
+  /** The truthful gate: tidy is enabled AND the API key is present. The screen renders the editor
+   *  tier only when this is true, and the honest gate note (a labelled region, no disabled controls)
+   *  otherwise. */
+  enabled: boolean;
+  /** Whether `tidy.enabled` is set in the site config, independent of the key. The gate note's
+   *  checklist reads this to show which deploy-time step is still open. */
+  tidyEnabled: boolean;
+  /** Whether the API key secret is present in the Worker env. A presence flag, never the key. */
+  keyConfigured: boolean;
+  /** The model id (a developer-tier fact, read-only on the screen). */
+  model: string;
+  /** A plain-language label for the model id ("Claude Sonnet"), so the read-only fact is not a bare
+   *  jargon token. Falls back to the raw id for an unknown model. */
+  modelLabel: string;
+  /** The resolved editor-tier conventions: every field concrete, the screen's initial control state.
+   *  Present only when the gate is open; the gate state needs no conventions. */
+  conventions: TidyConventions;
+  /** The success flash a redirected save carries (`?saved=1`). */
+  saved: boolean;
+  /** A redirected save's validation or conflict error read from `?error=`. */
+  error: string | null;
+}
+
+/** A refused settings save: a conflict bounce or a malformed conventions payload. Just the one-line
+ *  summary; the save commits nothing on a refusal. */
+export interface SettingsSaveFailure {
+  error: string;
+}
+
 /** The structural event the content routes read; a real SvelteKit RequestEvent satisfies it. */
 export interface ContentEvent extends EventBase<GithubKeyEnv> {
   params: Record<string, string>;
@@ -178,12 +246,96 @@ export interface ContentEvent extends EventBase<GithubKeyEnv> {
 }
 
 /** Injectable dependencies; tests stub the token mint to avoid signing a real key. */
+/** The minimal Anthropic client surface the tidy action uses, typed structurally so the SDK's deep
+ *  generics never reach a public signature and so the integration test can inject a fake whose
+ *  `messages.create` it stubs. The real factory builds `new Anthropic({ apiKey })`, which satisfies
+ *  this shape. The success path reads only the text blocks, the model, the stop reason, and the usage
+ *  counts. */
+export interface TidyClient {
+  messages: {
+    create(
+      body: {
+        model: string;
+        max_tokens: number;
+        system: string;
+        messages: { role: 'user'; content: string }[];
+      },
+      // The SDK signature is create(body, options). The abort signal belongs in the second argument
+      // (RequestOptions), not the body, so the request actually cancels when the deadline fires.
+      options?: { signal?: AbortSignal },
+    ): Promise<{
+      content: { type: string; text?: string }[];
+      model: string;
+      stop_reason: string | null;
+      usage: { input_tokens: number; output_tokens: number };
+    }>;
+  };
+}
+
 export interface ContentRoutesDeps {
   /** Mint a GitHub App installation token from the Worker env. Defaults to the real signer.
    *  A bare string works too; the routes await whatever comes back. */
   mintToken?: (env: GithubKeyEnv) => string | Promise<string>;
+  /** Build the Anthropic client for the tidy action from the resolved API key. Defaults to the real
+   *  SDK client. Injected in tests so `messages.create` is stubbed and no network call (or real key)
+   *  is ever needed. The factory runs only after the key is read from the env, so a disabled or
+   *  unconfigured site never constructs a client. */
+  anthropic?: (opts: { apiKey: string }) => TidyClient;
+  /** The tidy action's own request deadline in milliseconds, set shorter than the platform limit so a
+   *  slow model call becomes a clean retryable fail(502) rather than a platform timeout. Defaults to
+   *  {@link DEFAULT_TIDY_TIMEOUT_MS}. Overridable in tests to assert the deadline path without waiting. */
+  tidyTimeoutMs?: number;
 }
 
+/** The successful tidy outcome (spec 2.1): the corrected markdown, the model that produced it, and the
+ *  token usage. The diff is computed on the client (Task 12), so the server returns the plain text and
+ *  commits nothing. Admin-internal: consumed by the editor's review surface, not on the package's
+ *  sveltekit subpath, so it carries no reference page. */
+export interface TidyResult {
+  corrected: string;
+  model: string;
+  usage: { input_tokens: number; output_tokens: number };
+}
+
+/** A refused tidy: `fail(403)` on a failed CSRF check, `fail(503)` when tidy is disabled or the API
+ *  key is missing, `fail(413)` for an over-long body, `fail(502)` for a deadline overrun, abort, or
+ *  model error (all retryable), `fail(422)` for a model refusal, `fail(400)` for a malformed body. Just
+ *  the one-line summary; the action commits nothing, so a refusal can never corrupt the entry. */
+export interface TidyFailure {
+  error: string;
+}
+
+/** The Worker-side request deadline for the tidy model call: 30 seconds. A tidy call to Sonnet on a
+ *  full entry can run many seconds, so the action bounds it with an AbortSignal and maps the overrun to
+ *  a retryable fail(502). This sits well under Cloudflare's per-request wall-clock ceiling (a Worker
+ *  invocation can run far longer, but a single subrequest left open near that ceiling would surface as a
+ *  platform timeout the action could not shape into a clean retry). 30s comfortably covers a proofread
+ *  of the bounded input (see MAX_TIDY_CHARS) while leaving headroom under the platform limit. */
+const DEFAULT_TIDY_TIMEOUT_MS = 30_000;
+
+/** The fallback site-config path when no nav menu names one: the convention every scaffolded site
+ *  uses. The settings save edits the same committed YAML the nav editor does, so it resolves the path
+ *  from the configured nav menu first and falls back to this default. */
+const DEFAULT_SITE_CONFIG_PATH = 'src/lib/site.config.yaml';
+
+/** Plain-language labels for the known tidy models, so the read-only model fact reads as a name rather
+ *  than a bare id. An unknown id falls back to itself. */
+const TIDY_MODEL_LABELS: Record<string, string> = {
+  'claude-sonnet-4-6': 'Claude Sonnet',
+  'claude-haiku-4-5': 'Claude Haiku',
+};
+
+/** The display label for a tidy model id, falling back to the raw id for an unknown model. */
+function tidyModelLabel(model: string): string {
+  return TIDY_MODEL_LABELS[model] ?? model;
+}
+
+/** The input cap for a single tidy request: 24000 characters (~6k input tokens). A proofread runs at
+ *  roughly input length, so this stays comfortably inside the 30s deadline; a longer entry refuses with
+ *  fail(413) and the author tidies a selection instead. The cap is enforced BEFORE the model call, so an
+ *  over-long body never spends a token or risks the deadline. */
+const MAX_TIDY_CHARS = 24_000;
+
 /** A blocked save or publish: `fail(400)` when the body links to a target absent from main. */
 export interface SaveFailure {
   /** The one-line human summary every content action failure carries. */
@@ -248,6 +400,45 @@ export interface MediaAltPropagateFailure {
   error: string;
 }
 
+/** The personal-dictionary add outcome (spec 1.6): the merged, canonical sorted word list after the
+ *  add landed. The client reconciles its pending-additions set against this (a word now in the list is
+ *  committed and dropped from pending). Admin-internal: exported for the editor host's reconcile, not
+ *  on the package's sveltekit subpath, so it carries no reference page. */
+export interface DictionaryAddResult {
+  words: string[];
+}
+
+/** A refused personal-dictionary add: `fail(403)` on a failed CSRF check, `fail(400)` on a body that
+ *  carries no valid word. The client keeps its pending additions for the session and re-attempts on
+ *  the next save, so the word is never silently dropped. Just the one-line summary. */
+export interface DictionaryAddFailure {
+  error: string;
+}
+
+/** A refused media bulk delete or orphan purge: `fail(503)` for the fail-closed strict-usage refusal
+ *  (the whole batch refuses) or media-off / a missing bucket binding. The per-item outcomes ride the
+ *  returned summary, not a fail. */
+export interface MediaBulkFailure {
+  error: string;
+}
+
+/** The bulk-delete outcome the component renders: the deleted hashes, the skipped rows from the
+ *  partition (with their reason and where-used), and any per-object R2 delete failure. Admin-internal,
+ *  not on the package subpath, so no reference page. */
+export interface MediaBulkDeleteResult {
+  deleted: string[];
+  skipped: BulkDeleteSkip[];
+  failed: { hash: string; error: string }[];
+}
+
+/** The orphan-purge outcome: the purged R2 keys, the keys skipped because their hash was claimed by a
+ *  manifest row since the scan, and any per-object delete failure. Admin-internal, no reference page. */
+export interface MediaOrphanPurgeResult {
+  purged: string[];
+  skippedClaimed: string[];
+  failed: { key: string; error: string }[];
+}
+
 /** One entry the replace preview will rewrite, enriched with its display title and permalink from the
  *  content manifest (the planner's PlannedEntry carries neither). The screen lists these as the
  *  confirm dialog's where-touched preview, and the apply re-derives its own plan rather than trusting
@@ -312,7 +503,7 @@ export interface MediaAltPreviewPlan {
  *  `form` prop carries a `?/mediaDelete`, `?/mediaUpdate`, `?/mediaReplace`, or `?/mediaAltPropagate`
  *  refusal without a second type. */
 export type ContentFormFailure = Partial<
-  SaveFailure & DeleteRefusal & RenameFailure & MediaDeleteRefusal & MediaUpdateFailure & MediaReplaceFailure & MediaAltPropagateFailure
+  SaveFailure & DeleteRefusal & RenameFailure & MediaDeleteRefusal & MediaUpdateFailure & MediaReplaceFailure & MediaAltPropagateFailure & MediaBulkFailure & TidyFailure
 >;
 
 /** The successful upload's response (`uploadAction`). The server-owned `record` rides the editor's
@@ -350,6 +541,13 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
   const mintToken =
     deps.mintToken ?? ((env: GithubKeyEnv) => cachedInstallationToken(appCredentials(runtime.backend, env)));
 
+  // The default Anthropic factory builds the real SDK client from the resolved key. Tests inject a fake
+  // (deps.anthropic) so messages.create is stubbed and no network call or real key is ever needed. The
+  // SDK client satisfies TidyClient structurally; the cast names that to the compiler.
+  const anthropicClient =
+    deps.anthropic ?? ((opts: { apiKey: string }) => new Anthropic({ apiKey: opts.apiKey }) as unknown as TidyClient);
+  const tidyTimeoutMs = deps.tidyTimeoutMs ?? DEFAULT_TIDY_TIMEOUT_MS;
+
   /** Main's manifest, parsed. A missing file starts empty (a fresh repo before the first commit).
    *  Always read from main: pending branches carry no manifest copy. */
   async function readManifest(token: string): Promise<Manifest> {
@@ -546,6 +744,8 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     else if (event.url.searchParams.get('updated') === '1') flash = 'updated';
     else if (event.url.searchParams.get('replaced') === '1') flash = 'replaced';
     else if (event.url.searchParams.get('altPropagated') === '1') flash = 'altPropagated';
+    else if (event.url.searchParams.get('bulkDeleted') === '1') flash = 'bulkDeleted';
+    else if (event.url.searchParams.get('orphansPurged') === '1') flash = 'orphansPurged';
     const flashError = event.url.searchParams.get('error');
     let token: string;
     try {
@@ -674,13 +874,17 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     // The media manifest joins the concurrent batch only when media is on, read from the default
     // branch (pending branches carry no copy). A rejected media read degrades to null so the edit
     // never throws on a missing or unreadable media.json; the projection below treats null as empty.
-    const [headSha, mainRaw, manifestRaw, mediaRaw] = await Promise.all([
+    // The committed personal dictionary joins the concurrent batch, read from the default branch. A
+    // rejected read degrades to null so the edit never throws on a missing or unreadable dictionary;
+    // the projection below treats null as an empty word list (the editor falls back to dialect-only).
+    const [headSha, mainRaw, manifestRaw, mediaRaw, dictionaryRaw] = await Promise.all([
       branchHeadSha(runtime.backend, branch, token),
       readRaw(runtime.backend, path, token),
       readRaw(runtime.backend, runtime.manifestPath, token),
       runtime.resolvedAssets.enabled
         ? readRaw(runtime.backend, runtime.mediaManifestPath, token).catch(() => null)
         : Promise.resolve(null),
+      readRaw(runtime.backend, dictionaryFilePath(), token).catch(() => null),
     ]);
     const pending = headSha !== null;
     const raw = pending ? await readRaw({ ...runtime.backend, branch }, path, token) : mainRaw;
@@ -737,9 +941,30 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
       publishedFlash: event.url.searchParams.get('published') === '1',
       discardedFlash: event.url.searchParams.get('discarded') === '1',
       preview: resolvePreview(runtime.preview, concept.id),
+      // composeRuntime always resolves this from the site config's dialect; default a hand-built
+      // runtime that omits it to the US English dictionary so the editor always has a real filename.
+      spellcheckDictionary: runtime.spellcheckDictionary ?? dictionaryFileForDialect(undefined),
+      // The committed personal-dictionary words, normalized to the canonical sorted, deduplicated set
+      // so the editor seeds the Worker's personal layer with a clean list. A missing or unreadable file
+      // is an empty list (the dialect-only fallback).
+      siteDictionary: mergeDictionaryWords(parseDictionary(dictionaryRaw), []),
+      // The editor-tier tidy facts: the master switch, the model (for the head pill), and the resolved
+      // conventions (the because-line and category inference read only these). The API key is never
+      // exposed here. A site with no tidy block reads disabled with the default conventions.
+      tidy: {
+        enabled: runtime.tidy?.enabled ?? false,
+        model: runtime.tidy?.model || DEFAULT_TIDY_MODEL,
+        conventions: resolveTidyConventions(runtime.tidy?.conventions),
+      },
     };
   }
 
+  /** The repo-relative personal-dictionary path, defaulting a hand-built runtime that omits it to the
+   *  same `.cairn/` content root the manifests use. composeRuntime always fills `dictionaryPath`. */
+  function dictionaryFilePath(): string {
+    return runtime.dictionaryPath ?? 'src/content/.cairn/dictionary.txt';
+  }
+
   /** Log a failed commit: a conflict is the expected last-writer-wins outcome, so it warns with a
    *  reason; any other error is unexpected and logs at error with the stringified cause. Publish
    *  failures carry the same shape under their own event name. */
@@ -1493,6 +1718,263 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     throw redirect(303, '/admin/media?deleted=1');
   }
 
+  /** Bulk safe-delete a multi-select of committed media assets. This is mediaDeleteAction extended to
+   *  many items, with the same safety primitives and one rule that defines the batch: the gate is ONE
+   *  shared strict cross-branch usage index built per batch, never N per-item reads (N strict reads
+   *  would blow the workerd connection budget at many open branches). The fail-closed posture is for
+   *  the WHOLE batch: if that single strict index cannot complete, the action refuses everything and
+   *  commits nothing, rather than risk deleting bytes a branch still references.
+   *
+   *  Skip-and-report, never force: the pure planBulkDelete partitions the selection against the strict
+   *  index into deletable (no usage row, a committed manifest row exists), skipped-still-referenced (a
+   *  usage row, carried for the where-used), and skipped-uncommitted (no manifest row). An in-use item
+   *  is skipped and reported, never bulk-force-deleted; forced in-use deletion stays the single-item
+   *  typed-slug path.
+   *
+   *  The order is load-bearing, mirroring single delete: ONE atomic commit removes every deletable row
+   *  FIRST, then the R2 objects are deleted (commit-row-then-delete-R2). A failure after the commit
+   *  leaves bytes with no row (a benign orphan) rather than a row pointing at deleted bytes. Each R2
+   *  delete is best-effort and batch-resilient: a per-object error is reported in `failed` and never
+   *  aborts the rest of the batch. The result is an itemized 207-style summary the component renders
+   *  (deleted / skipped with reasons / failed); there is no success redirect. */
+  async function mediaBulkDelete(event: ContentEvent): Promise<ReturnType<typeof fail> | MediaBulkDeleteResult> {
+    const editor = requireSession(event);
+    const token = await mintToken(event.platform?.env ?? {});
+
+    // Read the selected hashes from the form. Accept the repeated `hash` field, falling back to a JSON
+    // `hashes` array. Each value must match the 16-hex content-hash grammar; a malformed value is
+    // dropped silently rather than surfaced as a skip (it was never a real selection).
+    const form = await event.request.formData();
+    let raw = form.getAll('hash').map(String);
+    if (raw.length === 0) {
+      const json = form.get('hashes');
+      if (typeof json === 'string') {
+        try {
+          const parsed: unknown = JSON.parse(json);
+          if (Array.isArray(parsed)) raw = parsed.map(String);
+        } catch {
+          raw = [];
+        }
+      }
+    }
+    const selected = raw.filter((h) => MEDIA_HASH_RE.test(h));
+
+    // Read the fresh media manifest (the deletable rows come from here, by hash).
+    const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+
+    // Resolve the R2 bucket before any write, so a media-off site or a missing binding refuses before
+    // the commit, exactly like single delete.
+    const resolved = runtime.resolvedAssets;
+    if (!resolved.enabled) {
+      return fail(503, { error: 'Media is not enabled for this site.' } satisfies MediaBulkFailure);
+    }
+    const platformEnv = (event.platform as { env?: Record<string, unknown> } | undefined)?.env ?? {};
+    const rawBucket = platformEnv[resolved.bucketBinding];
+    if (!rawBucket) {
+      return fail(503, { error: 'The media bucket is not bound.' } satisfies MediaBulkFailure);
+    }
+    const store = r2Store(rawBucket as R2Bucket);
+
+    // THE fail-closed gate for the whole batch: one shared strict usage index. STRICT mode rethrows a
+    // branch-read failure, so a transient branch read failing refuses the whole batch rather than
+    // mistaking a still-referenced asset for an orphan. Build exactly one index, never one per item.
+    let index: Awaited<ReturnType<typeof buildUsageIndex>>;
+    try {
+      index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+    } catch {
+      return fail(503, { error: 'Could not verify where these assets are used. Try again.' } satisfies MediaBulkFailure);
+    }
+
+    // The pure partition: membership in the fresh strict index is the gate, never the display count.
+    const plan = planBulkDelete(selected, index, manifest);
+    // An all-skipped or empty batch is a no-op success: nothing committed, nothing deleted.
+    if (plan.deletable.length === 0) {
+      return { deleted: [], skipped: plan.skipped, failed: [] } satisfies MediaBulkDeleteResult;
+    }
+
+    // ONE atomic commit removing EVERY deletable row, folded over removeMediaEntry.
+    let next = manifest;
+    for (const hash of plan.deletable) next = removeMediaEntry(next, hash);
+    const commitFields = { concept: 'media', id: 'bulk', editor: editor.email };
+    try {
+      await commitFiles(
+        runtime.backend,
+        [{ path: runtime.mediaManifestPath, content: serializeMediaManifest(next) }],
+        { message: `Delete ${plan.deletable.length} media assets`, author: { name: editor.displayName, email: editor.email } },
+        token,
+      );
+      log.info('commit.succeeded', commitFields);
+    } catch (err) {
+      commitFailure(commitFields, err, '/admin/media',
+        'The media manifest changed since you opened it. Reload and try again.');
+    }
+
+    // THEN delete each deletable hash's R2 object (the load-bearing order, see the docstring). Best
+    // effort and batch-resilient: a thrown key derivation or a delete error is reported in `failed`
+    // and the loop continues. An absent object is a no-op (the R2 contract).
+    const deleted: string[] = [];
+    const failed: { hash: string; error: string }[] = [];
+    for (const hash of plan.deletable) {
+      try {
+        const row = manifest[hash];
+        await store.delete(r2Key(row.hash, row.ext));
+        deleted.push(hash);
+      } catch (err) {
+        failed.push({ hash, error: err instanceof Error ? err.message : String(err) });
+      }
+    }
+
+    log.info('media.bulk_deleted', { editor: editor.email, deleted: deleted.length, skipped: plan.skipped.length });
+    return { deleted, skipped: plan.skipped, failed } satisfies MediaBulkDeleteResult;
+  }
+
+  /** The on-demand orphan scan: a read-only reconcile of stored R2 bytes against the manifest, joined
+   *  with one strict cross-branch usage index for the broken-reference where-used. It runs only when
+   *  requested, never on the loaded index, because it is heavier than the load path: a full R2 list
+   *  plus a reconcile pass on top of the strict usage build.
+   *
+   *  Detection-time fail-closed: BOTH the reconcile and the strict usage build run inside one
+   *  try/catch, and any throw refuses the whole scan with fail(503) rather than returning a partial
+   *  result. The reconcile must not run on a half-listed bucket: a truncated R2 list would call
+   *  still-stored bytes orphaned. The strict usage build must not run on a half-read branch set: an
+   *  unread branch would make a branch-referenced asset look orphaned. A wrong orphan verdict here
+   *  feeds the irreversible purge, so the scan refuses rather than risk it.
+   *
+   *  The result is the OrphanScan projection: orphanedBytes (stored keys with no manifest row, the
+   *  purge surface) and brokenRefs (manifest rows whose bytes are gone, read-only, shown with their
+   *  where-used so an operator can re-ingest rather than purge a still-referenced record). */
+  async function mediaOrphanScan(event: ContentEvent): Promise<ReturnType<typeof fail> | OrphanScan> {
+    requireSession(event);
+    const token = await mintToken(event.platform?.env ?? {});
+
+    // Resolve the R2 binding. The reconcile lists the raw bucket directly, so keep the raw binding;
+    // the MediaStore seam carries no list. A media-off site or a missing binding refuses the scan.
+    const resolved = runtime.resolvedAssets;
+    if (!resolved.enabled) {
+      return fail(503, { error: 'Media is not enabled for this site.' } satisfies MediaBulkFailure);
+    }
+    const platformEnv = (event.platform as { env?: Record<string, unknown> } | undefined)?.env ?? {};
+    const rawBucket = platformEnv[resolved.bucketBinding];
+    if (!rawBucket) {
+      return fail(503, { error: 'The media bucket is not bound.' } satisfies MediaBulkFailure);
+    }
+
+    // Read the fresh media manifest for the reconcile's manifest side.
+    const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+
+    // THE detection-time fail-closed surface. The reconcile (an R2 list that must complete in full)
+    // and the strict usage build (a branch read that must complete in full) are both unsafe to use
+    // partially, so either throwing refuses the scan. A wrong orphan verdict from a partial read here
+    // would feed the irreversible purge.
+    let reconcile: Awaited<ReturnType<typeof runReconcile>>;
+    let index: Awaited<ReturnType<typeof buildUsageIndex>>;
+    try {
+      reconcile = await runReconcile(rawBucket as unknown as ReconcileBucket, manifest);
+      index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+    } catch {
+      return fail(503, { error: 'Could not check where files are used, so the scan was not run. Try again.' } satisfies MediaBulkFailure);
+    }
+
+    return buildOrphanScan(reconcile, manifest, index);
+  }
+
+  /** Purge orphaned R2 bytes: the one IRREVERSIBLE media action. Raw object bytes live only in R2, not
+   *  in git, so a purged orphan cannot be recovered the way a deleted manifest row can be reverted in
+   *  history. The whole action is built around that fact.
+   *
+   *  The typed-count confirm is the never-bypassable gate, the analogue of single delete's typed-slug
+   *  check. The form's `confirm` must equal the count of selected keys (the approved rev.2 mockup's
+   *  "Type N to purge these files for good"); an empty selection or a mismatched count deletes nothing.
+   *
+   *  Re-derive fresh is the safety crux. The selection came from an earlier scan, so the action does
+   *  NOT trust it: the purge keys are client-posted, so the server cannot assume they came from a fresh
+   *  scan. It reads the current media manifest AND rebuilds ONE strict cross-branch usage index, then
+   *  for each selected key parses the hash from the key grammar. A key that does not match the grammar
+   *  was never a real orphan key and is dropped silently. A key whose hash now has a manifest row OR is
+   *  referenced on any open cairn/* branch survived the scan window (it was claimed by a row, or a
+   *  draft started referencing those bytes), so it is skipped into skippedClaimed and its bytes survive.
+   *  Only a key whose hash is STILL absent from both is purged. This closes the TOCTOU between scan and
+   *  purge that could otherwise irreversibly delete a live draft's bytes.
+   *
+   *  Like the scan and the bulk delete, the strict index build is the fail-closed gate: a branch read
+   *  that throws refuses the whole batch with fail(503) rather than mistaking an unverifiable reference
+   *  for an absent one. The index is built exactly once for the batch, never once per key.
+   *
+   *  There is no commit. An orphan by definition has no manifest row to remove, so the purge deletes
+   *  the R2 object directly. Each delete is best-effort and batch-resilient: a per-object error is
+   *  reported in `failed` and the loop continues; an absent object is a no-op (the R2 contract). */
+  async function mediaPurgeOrphans(event: ContentEvent): Promise<ReturnType<typeof fail> | MediaOrphanPurgeResult> {
+    const editor = requireSession(event);
+    const token = await mintToken(event.platform?.env ?? {});
+
+    // Resolve the R2 binding, the same media-off / missing-binding refusals as the scan. The purge
+    // deletes through the MediaStore seam, so wrap the raw binding.
+    const resolved = runtime.resolvedAssets;
+    if (!resolved.enabled) {
+      return fail(503, { error: 'Media is not enabled for this site.' } satisfies MediaBulkFailure);
+    }
+    const platformEnv = (event.platform as { env?: Record<string, unknown> } | undefined)?.env ?? {};
+    const rawBucket = platformEnv[resolved.bucketBinding];
+    if (!rawBucket) {
+      return fail(503, { error: 'The media bucket is not bound.' } satisfies MediaBulkFailure);
+    }
+    const store = r2Store(rawBucket as R2Bucket);
+
+    // Read the selected R2 keys and the typed confirm.
+    const form = await event.request.formData();
+    const keys = form.getAll('key').map(String);
+    const confirm = String(form.get('confirm') ?? '');
+
+    // The irreversible gate: the confirm must equal the selected count, and the set must be non-empty.
+    // A mismatch or an empty set refuses and deletes NOTHING.
+    if (keys.length === 0 || confirm !== String(keys.length)) {
+      return fail(400, { error: 'Type the number of files to confirm the purge.' } satisfies MediaBulkFailure);
+    }
+
+    // Re-derive fresh against the current manifest, so a key claimed since the scan is never purged.
+    const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+
+    // THE fail-closed gate for the whole batch: one shared strict cross-branch usage index, symmetric
+    // with the scan and the bulk delete. STRICT mode rethrows a branch-read failure, so a transient
+    // branch read refuses the irreversible purge rather than letting a possibly-referenced byte be
+    // treated as a true orphan. Build exactly one index, never one per key.
+    let index: Awaited<ReturnType<typeof buildUsageIndex>>;
+    try {
+      index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+    } catch {
+      return fail(503, { error: 'Could not verify where these files are used. Try again.' } satisfies MediaBulkFailure);
+    }
+
+    const purged: string[] = [];
+    const skippedClaimed: string[] = [];
+    const failed: { key: string; error: string }[] = [];
+    for (const key of keys) {
+      const hash = MEDIA_KEY_RE.exec(key)?.[1];
+      // A key that does not match the grammar was never a real orphan key: drop it silently.
+      if (hash === undefined) continue;
+      // A hash that now has a manifest row was claimed since the scan: its bytes are a live asset now.
+      if (manifest[hash]) {
+        skippedClaimed.push(key);
+        continue;
+      }
+      // A hash referenced on any open cairn/* branch backs an in-progress draft: skip it claimed too.
+      if (index.has(hash)) {
+        skippedClaimed.push(key);
+        continue;
+      }
+      // Still orphaned: delete the object directly. No commit, there is no manifest row.
+      try {
+        await store.delete(key);
+        purged.push(key);
+      } catch (err) {
+        failed.push({ key, error: err instanceof Error ? err.message : String(err) });
+      }
+    }
+
+    log.info('media.orphans_purged', { editor: editor.email, purged: purged.length });
+    return { purged, skippedClaimed, failed } satisfies MediaOrphanPurgeResult;
+  }
+
   /** Edit a committed asset's metadata: its display name, slug, and default alt. A single media.json
    *  row commit, with NO reference rewrite: the resolver and the delivery route key on the hash, so a
    *  rename never breaks an existing `media:` reference. The default alt is the asset's value for the
@@ -1881,7 +2363,313 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     throw redirect(303, '/admin/media?altPropagated=1');
   }
 
-  return { layoutLoad, indexRedirect, listLoad, mediaLibraryLoad, createAction, editLoad, saveAction, publishAction, publishAllAction, discardAction, deleteAction, listDeleteAction, renameAction, uploadAction, mediaDeleteAction, mediaUpdateAction, mediaReplacePreview, mediaReplaceApply, mediaAltPreview, mediaAltApply, mintToken };
+  /** The cap on a personal-dictionary word, matched by isValidDictionaryWord. A word is one line, so
+   *  this bounds an abusive input; the real authority is the per-character validation, which rejects
+   *  whitespace and control bytes so a body can never inject an extra line into the committed file. */
+  const MAX_DICTIONARY_WORD = 64;
+  /** The cap on the words a single add request carries: an editor adds a handful at save time, never
+   *  a flood. Past this the body is treated as abusive and the surplus is dropped. */
+  const MAX_DICTIONARY_BATCH = 100;
+
+  /** Read the committed personal dictionary, merge the validated additions in sorted order, and commit
+   *  the canonical file back. Shared by the first attempt and the post-conflict retry, so both re-read
+   *  the head and re-merge the same additions; the merge is order-independent, so a concurrent editor's
+   *  word that already landed is preserved and the result is the same sorted set regardless of order.
+   *  Returns the merged word list. Throws CommitConflictError (via commitFiles) when the branch moves
+   *  under the commit, which the caller catches to retry once. */
+  async function mergeAndCommitDictionary(token: string, additions: string[], editor: Editor): Promise<string[]> {
+    const path = dictionaryFilePath();
+    // The existing file as its canonical sorted set, so a no-op add is detected against the same
+    // normalization the commit would write (an already-sorted file never re-commits just to reorder).
+    const canonicalExisting = mergeDictionaryWords(parseDictionary(await readRaw(runtime.backend, path, token)), []);
+    const merged = mergeDictionaryWords(canonicalExisting, additions);
+    // Nothing new (every addition was already present): skip the commit so an idempotent add never
+    // pushes an empty commit that would redeploy the site. The merged set is still returned so the
+    // client reconciles its pending additions away.
+    if (merged.length === canonicalExisting.length) return merged;
+    await commitFiles(
+      runtime.backend,
+      [{ path, content: serializeDictionary(merged) }],
+      { message: `Add to dictionary: ${additions.join(', ')}`, author: { name: editor.displayName, email: editor.email } },
+      token,
+    );
+    return merged;
+  }
+
+  /** The repo-relative site-config path the settings save reads and commits. It is the same committed
+   *  YAML the nav editor edits, so it comes from the configured nav menu first and falls back to the
+   *  scaffold default when no menu is configured. */
+  function siteConfigPath(): string {
+    return runtime.navMenu?.configPath ?? DEFAULT_SITE_CONFIG_PATH;
+  }
+
+  /** Read whether the Anthropic API key secret is present in the load's env. A presence flag for the
+   *  truthful visibility gate, never the key itself: the key is a Worker secret, so this only reports
+   *  that a non-empty `ANTHROPIC_API_KEY` exists and the value never leaves the server. */
+  function keyConfigured(event: ContentEvent): boolean {
+    const env = (event.platform?.env ?? {}) as Record<string, unknown>;
+    return typeof env.ANTHROPIC_API_KEY === 'string' && env.ANTHROPIC_API_KEY.length > 0;
+  }
+
+  /** Load the two-tier tidy settings (spec 2.8, Task 15). The developer tier (enabled, key, model) is
+   *  read-only; the editor tier is the resolved conventions block. The visibility gate is truthful: the
+   *  `enabled` flag is true only when `tidy.enabled` is set AND the key is present, so the screen renders
+   *  the convention list only then and the honest gate note otherwise. No secret is returned: only a
+   *  presence flag for the key. The conventions come straight from the runtime config (the same source
+   *  the tidy action's prompt reads), so the screen and the prompt can never diverge. */
+  function settingsLoad(event: ContentEvent): SettingsData {
+    requireSession(event);
+    const tidy = runtime.tidy;
+    const tidyEnabled = tidy?.enabled === true;
+    const keyPresent = keyConfigured(event);
+    const model = tidy?.model || DEFAULT_TIDY_MODEL;
+    return {
+      enabled: tidyEnabled && keyPresent,
+      tidyEnabled,
+      keyConfigured: keyPresent,
+      model,
+      modelLabel: tidyModelLabel(model),
+      conventions: resolveTidyConventions(tidy?.conventions),
+      saved: event.url.searchParams.get('saved') === '1',
+      error: event.url.searchParams.get('error'),
+    };
+  }
+
+  /** Save the editor-tier tidy conventions: validate the posted block, then read-modify-commit it into
+   *  the same committed YAML the nav editor writes, with the session editor as author. The transport is
+   *  the nav save's exactly: a form POST carrying the conventions JSON, the read-modify-commit through
+   *  `commitFile`, and a stale-SHA `isConflict` bounced back as a reload prompt. Only the conventions
+   *  block is written (setTidy leaves `tidy.enabled` and `tidy.model` untouched), so an editor's save can
+   *  never flip the developer-tier deploy facts. The save refuses before any commit when tidy is not
+   *  enabled, so the gate state's absent editor tier can never be saved past. */
+  async function settingsSave(event: ContentEvent): Promise<never> {
+    const editor = requireSession(event);
+    // The editor tier does not exist when tidy is off, so a save in that state is a 404 (no editable
+    // surface to commit), the server half of the truthful gate.
+    if (runtime.tidy?.enabled !== true) throw error(404, 'Tidy is not enabled for this site');
+
+    const form = await event.request.formData();
+    let conventions: TidyConventions;
+    try {
+      conventions = validateTidyConventions(JSON.parse(String(form.get('conventions') ?? '{}')));
+    } catch (err) {
+      const message = err instanceof TidyConventionsError ? err.message : 'Invalid tidy settings';
+      throw redirect(303, `/admin/settings?error=${encodeURIComponent(message)}`);
+    }
+
+    const path = siteConfigPath();
+    const token = await mintToken(event.platform?.env ?? {});
+    const raw = await readRaw(runtime.backend, path, token);
+    if (raw === null) throw error(404, 'Site config not found');
+    // Parse first so a malformed file fails before the write rather than committing onto a broken base.
+    parseSiteConfig(raw);
+
+    const commitFields = { concept: 'settings', id: 'tidy', editor: editor.email };
+    try {
+      await commitFile(
+        runtime.backend,
+        path,
+        setTidy(raw, conventions),
+        { message: 'Update tidy settings', author: { name: editor.displayName, email: editor.email } },
+        token,
+      );
+      log.info('commit.succeeded', commitFields);
+    } catch (err) {
+      if (isConflict(err)) {
+        log.warn('commit.failed', { ...commitFields, reason: 'conflict' });
+        const message = 'The site config changed since you opened it. Reload and reapply your edits.';
+        throw redirect(303, `/admin/settings?error=${encodeURIComponent(message)}`);
+      }
+      log.error('commit.failed', { ...commitFields, error: String(err) });
+      throw err;
+    }
+
+    throw redirect(303, '/admin/settings?saved=1');
+  }
+
+  /** Add a word (or batch) to the git-committed personal dictionary (spec 1.6). The transport mirrors
+   *  the media raw-body actions exactly: a `text/plain` POST, the CSRF token in `X-Cairn-CSRF` validated
+   *  by validateCsrfHeader (CSRF first, then the session), and a small JSON body `{ word }` or
+   *  `{ words }`. It reads the current file from the default branch, inserts the validated words in
+   *  sorted order if absent (idempotent), and commits through the GitHub-App pipeline.
+   *
+   *  The commit is SHA-guarded with commit-and-retry: commitFiles throws CommitConflictError when the
+   *  branch moved under it, which is caught here to re-read the new head, re-merge the same additions
+   *  (the sorted insert is order-independent, so a concurrent editor's word is preserved), and retry
+   *  once. The response is the merged word list, so the client drops the now-committed words from its
+   *  pending set; a refusal rides a `fail` envelope the client reads by `type`/`status`.
+   *
+   *  Input validation is load-bearing here: this commits to the repo from request input, so every word
+   *  is length-bounded and rejected if it carries whitespace or control characters (a word is one
+   *  line), and the batch is capped. A body that yields no valid word refuses with a 400 and commits
+   *  nothing, so the committed file can never gain an injected or empty line. */
+  async function addDictionaryWord(event: ContentEvent): Promise<ReturnType<typeof fail> | DictionaryAddResult> {
+    // CSRF first: a raw-body (JSON) POST, so the header witness is the authority, like the upload and
+    // media actions. A failed check refuses before the session read or any GitHub call.
+    if (!event.cookies || !validateCsrfHeader({ url: event.url, request: event.request, cookies: event.cookies })) {
+      return fail(403, { error: 'csrf' } satisfies DictionaryAddFailure);
+    }
+    const editor = requireSession(event);
+
+    let payload: { word?: unknown; words?: unknown };
+    try {
+      payload = JSON.parse(await event.request.text());
+    } catch {
+      return fail(400, { error: 'Could not read the dictionary request.' } satisfies DictionaryAddFailure);
+    }
+
+    // Collect the candidate words from `word` and/or `words`, keep only the strings, validate each
+    // against the one-line word grammar, dedupe, and cap the batch. A body with no valid word refuses.
+    const raw = [
+      ...(typeof payload.word === 'string' ? [payload.word] : []),
+      ...(Array.isArray(payload.words) ? payload.words.filter((w): w is string => typeof w === 'string') : []),
+    ];
+    const additions = [...new Set(raw.filter((w) => isValidDictionaryWord(w, MAX_DICTIONARY_WORD)))].slice(0, MAX_DICTIONARY_BATCH);
+    if (additions.length === 0) {
+      return fail(400, { error: 'No valid word to add to the dictionary.' } satisfies DictionaryAddFailure);
+    }
+
+    const token = await mintToken(event.platform?.env ?? {});
+    const commitFields = { concept: 'dictionary', id: additions[0]!, editor: editor.email };
+    try {
+      const words = await mergeAndCommitDictionary(token, additions, editor);
+      log.info('dictionary.added', { editor: editor.email, words: additions });
+      return { words };
+    } catch (err) {
+      if (!isConflict(err)) throw err;
+      // The branch moved under the commit. Re-read the new head and re-merge the same additions, then
+      // retry once. The merge is order-independent, so a concurrent editor's word that landed in the
+      // window is preserved and the two adds converge on the same sorted set.
+      try {
+        const words = await mergeAndCommitDictionary(token, additions, editor);
+        log.info('dictionary.added', { editor: editor.email, words: additions, retried: true });
+        return { words };
+      } catch (retryErr) {
+        if (!isConflict(retryErr)) throw retryErr;
+        // A second conflict: give up rather than loop. The client keeps the words in its pending set
+        // for the session and re-attempts on the next save, so the word is never silently dropped.
+        log.warn('dictionary.add_conflict', { editor: editor.email, words: additions });
+        return fail(409, { error: 'The dictionary changed while saving. It will retry on the next save.' } satisfies DictionaryAddFailure);
+      }
+    }
+  }
+
+  /** Tidy: a light LLM copy-edit of the author's markdown (spec 2.1). The first remote model call in
+   *  the library, so this is the highest-blast-radius server action: untrusted content and the Anthropic
+   *  API key. The transport mirrors the media raw-body actions (a `text/plain` POST carrying JSON
+   *  `{ text, scope }`, the CSRF token in `X-Cairn-CSRF`, the response deserialized by the client), with
+   *  abort/timeout/deadline the media calls did not need: a tidy call to Sonnet on a full entry can run
+   *  many seconds.
+   *
+   *  Gate order (every refusal happens before the next step, so a refused request spends nothing):
+   *    1. validateCsrfHeader FIRST (the header witness is the authority for a raw-body POST).
+   *    2. requireSession (an expired session throws the manual-redirect 303 the client reads as status-0).
+   *    3. Read the key and config; refuse fail(503) if tidy is disabled or the key is missing.
+   *    4. Parse and bound the body; refuse fail(400) on malformed JSON, fail(413) on an over-long text.
+   *    5. Only then build the prompt and call the model, bounded by the Worker deadline.
+   *
+   *  The untrusted text rides as the user message, never interpolated into the system prompt; the
+   *  prompt's injection framing (Task 10) treats it as data. The API key never leaves the action: it is
+   *  not returned and not logged, and the log line carries no content. The action commits NOTHING, so a
+   *  failed, aborted, or refused tidy can never corrupt the entry; the diff is computed on the client
+   *  (Task 12), so the server stays a thin model-call boundary. */
+  async function tidyAction(event: ContentEvent): Promise<ReturnType<typeof fail> | TidyResult> {
+    // CSRF first: a raw-body (JSON) POST, so the header witness is the authority. A failed check refuses
+    // before the session read and before any model call.
+    if (!event.cookies || !validateCsrfHeader({ url: event.url, request: event.request, cookies: event.cookies })) {
+      return fail(403, { error: 'csrf' } satisfies TidyFailure);
+    }
+    const editor = requireSession(event);
+
+    // Fail-fast: refuse before any model call if tidy is off or the key is missing. The model is read
+    // from config (a stated fact in this tier); a missing key is the "not enabled" refusal. No secret is
+    // ever returned or logged.
+    const tidy = runtime.tidy;
+    if (!tidy?.enabled) {
+      return fail(503, { error: 'Tidy is not enabled for this site.' } satisfies TidyFailure);
+    }
+    const env = (event.platform?.env ?? {}) as Record<string, unknown>;
+    const apiKey = typeof env.ANTHROPIC_API_KEY === 'string' ? env.ANTHROPIC_API_KEY : '';
+    if (!apiKey) {
+      return fail(503, { error: 'Tidy is not configured: the Anthropic API key is missing.' } satisfies TidyFailure);
+    }
+
+    // Parse and bound the body before the call. A malformed body refuses 400; an over-long text refuses
+    // 413 (tidy a selection instead), so no over-long input ever spends a token or risks the deadline.
+    let payload: { text?: unknown; scope?: unknown };
+    try {
+      payload = JSON.parse(await event.request.text());
+    } catch {
+      return fail(400, { error: 'Could not read the tidy request.' } satisfies TidyFailure);
+    }
+    const text = typeof payload.text === 'string' ? payload.text : '';
+    if (text.length === 0) {
+      return fail(400, { error: 'No text to tidy.' } satisfies TidyFailure);
+    }
+    if (text.length > MAX_TIDY_CHARS) {
+      return fail(413, { error: 'This is too long to tidy at once. Select a passage and tidy that instead.' } satisfies TidyFailure);
+    }
+
+    // Build the system prompt from the resolved conventions (Task 10). The prompt is built from config,
+    // never from the author's text, so the untrusted text cannot reshape the instructions.
+    const system = buildTidyPrompt(resolveTidyConventions(tidy.conventions));
+    const model = tidy.model || DEFAULT_TIDY_MODEL;
+    // max_tokens sized to comfortably exceed the input token count: a proofread runs at roughly input
+    // length, never lowballed. The character cap is ~6k input tokens, so this leaves generous headroom.
+    const maxTokens = 16_000;
+
+    // Bound the model call with the Worker's own deadline (shorter than the platform limit), so a slow
+    // call becomes a retryable fail(502) rather than a platform timeout. The client also drives its own
+    // AbortController (Cancel + a bounded timeout, Task 14); this action accepts an aborted request
+    // cleanly by mapping any abort to the same fail(502).
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), tidyTimeoutMs);
+    let message: Awaited<ReturnType<TidyClient['messages']['create']>>;
+    try {
+      const client = anthropicClient({ apiKey });
+      message = await client.messages.create(
+        {
+          model,
+          max_tokens: maxTokens,
+          system,
+          messages: [{ role: 'user', content: text }],
+        },
+        // The signal rides the request options, so the deadline timer above actually cancels the call.
+        { signal: controller.signal },
+      );
+    } catch (err) {
+      // A deadline overrun, a client abort, or a model error (rate limit, overload, 5xx) all map to the
+      // retryable fail(502). The error string is not surfaced to the client (it may carry internal
+      // detail); the log line carries the editor and the kind, never the key or the content.
+      log.warn('tidy.error', { editor: editor.email, model, aborted: controller.signal.aborted });
+      return fail(502, { error: 'Tidy could not finish. Try again.' } satisfies TidyFailure);
+    } finally {
+      clearTimeout(timer);
+    }
+
+    // A model refusal (the streaming-classifier intervention) is a clean fail(422): the author's text is
+    // untouched, so the editor can leave it as-is.
+    if (message.stop_reason === 'refusal') {
+      log.warn('tidy.refused', { editor: editor.email, model });
+      return fail(422, { error: 'Tidy declined to edit this text.' } satisfies TidyFailure);
+    }
+
+    // Read the output as plain text: concatenate the text blocks (a normal response is one). An empty
+    // result is treated as a model error rather than silently returning an empty document.
+    const corrected = message.content
+      .filter((block) => block.type === 'text' && typeof block.text === 'string')
+      .map((block) => block.text ?? '')
+      .join('');
+    if (corrected.length === 0) {
+      log.warn('tidy.empty', { editor: editor.email, model });
+      return fail(502, { error: 'Tidy returned nothing. Try again.' } satisfies TidyFailure);
+    }
+
+    log.info('tidy.done', { editor: editor.email, model: message.model, usage: message.usage });
+    return { corrected, model: message.model, usage: message.usage };
+  }
+
+  return { layoutLoad, indexRedirect, listLoad, mediaLibraryLoad, settingsLoad, settingsSave, createAction, editLoad, saveAction, publishAction, publishAllAction, discardAction, deleteAction, listDeleteAction, renameAction, uploadAction, mediaDeleteAction, mediaBulkDelete, mediaOrphanScan, mediaPurgeOrphans, mediaUpdateAction, mediaReplacePreview, mediaReplaceApply, mediaAltPreview, mediaAltApply, addDictionaryWord, tidyAction, mintToken };
 }
 
 /** The cap, in characters, on the stored alt text. The human fields are display copy, not content,