@glw907/cairn-cms 0.59.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';
@@ -142,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
@@ -174,6 +200,43 @@ export interface MediaLibraryData {
   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>;
@@ -183,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. */
@@ -253,6 +400,21 @@ 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. */
@@ -341,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 & MediaBulkFailure
+  SaveFailure & DeleteRefusal & RenameFailure & MediaDeleteRefusal & MediaUpdateFailure & MediaReplaceFailure & MediaAltPropagateFailure & MediaBulkFailure & TidyFailure
 >;
 
 /** The successful upload's response (`uploadAction`). The server-owned `record` rides the editor's
@@ -379,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> {
@@ -705,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;
@@ -768,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. */
@@ -2169,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, mediaBulkDelete, mediaOrphanScan, mediaPurgeOrphans, 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,