@glw907/cairn-cms 0.36.0 → 0.37.1

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project are recorded here, most recent first.
 
+## 0.37.1
+
+Internal groundwork and a docs overhaul; nothing in the public surface or runtime behavior
+changes, and no consumer action is needed.
+
+The diagnostics foundation lands as an internal module: a condition registry
+(`CairnCondition`), a `CairnError` throw primitive, and a shared condition-response renderer
+that the admin guard's three rejection responses (the two CSRF reasons and the HTTPS check) now
+route through. Those responses are unchanged and regression-pinned, and the module exports from
+no package subpath. This is Pass 1 of the diagnostics initiative, the base the upcoming
+`cairn doctor` and readiness checks build on.
+
+Docs are reorganized and rewritten. A new README front door tells the save-flow story, says
+what cairn is not, names the chosen stack, and then opens three doors: the tutorial, the
+showcase, and the docs map. Stray top-level pages joined their Diátaxis arms (the admin route
+contract is `docs/reference/admin-routes.md`, the sanitize floor is
+`docs/explanation/render-safety.md`, key rotation is
+`docs/guides/rotate-the-github-app-key.md`), and every adopter-facing page is rewritten in a
+second-person, example-first voice with its technical content intact.
+
+The magic-link sign-in confirmation is now a branded panel in place of the flat success bar. After an
+editor requests a link, the page shows a mail icon in a soft success tile, a "Check your email"
+heading, and the ten-minute expiry note, all in the admin's Warm Stone styling. Below a divider it
+adds guidance for the link that never arrives: check the spam folder first, then confirm the address
+matches the one the site owner added. This covers the common fat-finger case, where a mistyped address
+gets the same neutral confirmation and no email. A "Use a different email" action returns to the form
+so the address gets corrected without a reload. The confirmation copy stays identical whether or not
+the email is on the allowlist, so the page still never leaks membership.
+
+The change is internal to the `LoginPage` component and needs no action.
+
 ## 0.36.0
 
 cairn now emits structured diagnostic events. The engine had three bare `console.error` calls and no

package/README.md

@@ -1,33 +1,62 @@
 # cairn-cms
 
-An embedded, **magic-link**, GitHub-committing CMS for SvelteKit + Cloudflare sites.
-Non-technical authors log in by email (no GitHub account, no password), edit **raw markdown**
-in a client-only CodeMirror editor with a live preview, and save. Each save commits to `main`
-via a **GitHub App** (committer = `cairn-cms[bot]`, author = the editor) and auto-deploys.
-
-It is **design-agnostic**. Each consumer site supplies an adapter (the content contract through
-`defineAdapter`/`defineFields`, the slug and permalink rules, and its render configuration), so the
-same engine drives sites with completely different markdown pipelines. Two run in production today:
-[ecnordic.ski](https://ecnordic.ski) (a remark-to-rehype directive pipeline) and
-[907.life](https://907.life) (the engine's own `createRenderer`). Content is a fixed set of
-first-class concepts (Posts and Pages), not open-ended collections.
+A CMS that lives inside your SvelteKit site and commits to git. Your editors log in with an
+email link (no GitHub account, no password), write raw markdown in a CodeMirror editor with a
+live preview, and hit Save.
+
+When they hit Save, cairn doesn't write to a database. It commits the markdown straight to
+the repo's `main` branch. The commit goes through a GitHub App, so the editor never touches
+GitHub; they still show up as the commit author, and `cairn-cms[bot]` does the signing. From
+there your normal Cloudflare deploy takes over, the same as if you'd pushed from a terminal.
+Commit is publish. If someone else changed the file mid-edit, cairn refuses the save instead
+of guessing how to merge.
+
+## How it fits your site
+
+cairn is an engine your site imports, not a platform you deploy to. The engine owns the
+machinery that has to be right: the magic-link auth, the commit path, the admin app, the
+render pipeline and its sanitize floor. Your site owns everything a visitor sees: the adapter
+(your content concepts, frontmatter schema, and slug rules through
+`defineAdapter`/`defineFields`), your markdown pipeline, your CSS. Two production sites run
+the same engine today and look nothing alike: [ecnordic.ski](https://ecnordic.ski) renders
+through its own remark directive pipeline, [907.life](https://907.life) through the engine's
+`createRenderer`.
+
+## What cairn is not
+
+- Not a hosted platform. There is no cairn server; the admin ships inside your site's Worker
+  and your repo is the source of truth.
+- Not a database CMS. Content is markdown files in your repo, so it outlives the tool and
+  never needs an export.
+- Not an open-ended collection builder. Content is a fixed set of first-class concepts (Posts
+  and Pages today), each with its own behavior, because the engine should have an opinion
+  about what a Post is.
+
+## The stack is chosen for you
+
+SvelteKit on Cloudflare Workers, D1 for the auth store, GitHub for content. cairn is
+deliberately opinionated: if that stack matches yours, the pieces click together, and if it
+doesn't, cairn is the wrong tool and will not try to meet you halfway.
+
+## Start here
+
+1. **[Build your first cairn site](./docs/tutorial/build-your-first-cairn-site.md)**, the
+   tutorial, takes you from an empty directory to a deployed site with a working `/admin`.
+2. **[`examples/showcase`](./examples/showcase)** is a complete consumer site wired to the
+   engine, and the worked reference for every shape in the docs. When a guide says "mount the
+   route shims," the showcase shows the mounted result.
+3. **[The docs](./docs/README.md)** are organized in four arms: the tutorial, task guides,
+   one reference page per export, and explanation pages for the architecture and design
+   rules.
 
 ## Status
 
-cairn-cms runs two production sites today, [ecnordic.ski](https://ecnordic.ski) and
-[907.life](https://907.life). It is `0.x` and breaks between minor versions. The author is
-still working through the core-feature roadmap, and the project stays closely held until that
-core lands. See the [ROADMAP](./ROADMAP.md) for what is planned and the
-[CHANGELOG](./CHANGELOG.md) for what changed.
-
-Editor auth is self-owned: an atomic single-use magic-link token, a POST-confirm flow, opaque
-D1-backed session rows, and two-tier `owner`/`editor` roles. There is no better-auth, Drizzle,
-or ORM. Pin a caret range and read the CHANGELOG before bumping; every breaking entry carries a
-"Consumers must" line.
-
-A contributor who feels inspired is welcome to open an issue or a discussion to start a
-conversation. There is no formal contribution process yet, so this is not an open call for
-pull requests.
+cairn-cms runs the two production sites above. It is `0.x` and breaks between minor versions,
+so pin a caret range and read the [CHANGELOG](./CHANGELOG.md) before bumping; every breaking
+entry carries a "Consumers must" line. The author is still working through the core-feature
+[ROADMAP](./ROADMAP.md), and the project stays closely held until that core lands. A
+contributor who feels inspired is welcome to open an issue or a discussion; there is no
+formal contribution process yet, so this is not an open call for pull requests.
 
 ## Install
 
@@ -35,35 +64,27 @@ pull requests.
 npm install @glw907/cairn-cms
 ```
 
-Peer dependencies: `svelte@^5` and `@sveltejs/kit@^2`. A consumer site implements a `CairnAdapter`
-and mounts thin `/admin` route shims around the package subpaths:
+Peer dependencies: `svelte@^5` and `@sveltejs/kit@^2`. A consumer site implements a
+`CairnAdapter` and mounts thin `/admin` route shims around the package subpaths:
 
 - `@glw907/cairn-cms`: the core engine and adapter contract.
 - `@glw907/cairn-cms/sveltekit`: the server load and action logic.
 - `@glw907/cairn-cms/components`: the admin Svelte UI.
 - `@glw907/cairn-cms/delivery` and `/delivery/data`: the public read model (indexes, feeds,
-  sitemap, SEO head). The `/delivery/data` barrel is node-safe, with no `@sveltejs/kit` in its graph.
-- `@glw907/cairn-cms/vite`: the `cairnManifest()` Vite plugin, paired with the `cairn-manifest` bin,
-  that builds and verifies the committed content manifest at build time.
-
-Each site binds a Cloudflare D1 database as `AUTH_DB` (the editor allowlist, sessions, and single-use
-magic tokens) and a `[[send_email]]` binding named `EMAIL`. The worked reference for every shape is
-`examples/showcase`.
+  sitemap, SEO head). The `/delivery/data` barrel is node-safe, with no `@sveltejs/kit` in
+  its graph.
+- `@glw907/cairn-cms/vite`: the `cairnManifest()` Vite plugin, paired with the
+  `cairn-manifest` bin, that builds and verifies the committed content manifest at build
+  time.
 
-## Documentation
-
-The [`docs/`](./docs/README.md) tree is organized in four arms: a tutorial that builds a first
-site end to end, how-to guides for each setup task, a reference for every package export, and
-explanation pages for the architecture and design rules. Start at the
-[documentation index](./docs/README.md). The [security policy](./SECURITY.md) covers reporting
-and the security posture.
+Each site binds a Cloudflare D1 database as `AUTH_DB` (the editor allowlist, sessions, and
+single-use magic tokens) and a `[[send_email]]` binding named `EMAIL`. The
+[security policy](./SECURITY.md) covers reporting and the security posture.
 
 ## How it's developed
 
-This is a standalone repo. Consumer sites install the published package from the npm registry by
-version range. The library's own development proves changes against `examples/showcase`, a
-self-contained SvelteKit site that consumes the package through the relative `file:../..` path, so a
-change is exercised end to end before it publishes.
-
-The historical rebuild plan and the early architecture writeups live under `docs/internal/`.
-They are kept for history and are not current.
+This is a standalone repo. Consumer sites install the published package from the npm registry
+by version range. The library's own development proves changes against `examples/showcase`,
+which consumes the package through the relative `file:../..` path, so a change is exercised
+end to end before it publishes. The historical rebuild plan and the early architecture
+writeups live under `docs/internal/history/` and are not current.

package/dist/components/LoginPage.svelte

@@ -7,6 +7,8 @@ the allowlist, so the page never leaks membership (spec §7.1).
 <script lang="ts">
   import './cairn-admin.css';
   import { onMount } from 'svelte';
+  import MailCheckIcon from '@lucide/svelte/icons/mail-check';
+  import InfoIcon from '@lucide/svelte/icons/info';
   import CairnLogo from './CairnLogo.svelte';
   import CsrfField from './CsrfField.svelte';
   import { cairnFaviconHref } from './cairn-favicon.js';
@@ -22,6 +24,9 @@ the allowlist, so the page never leaks membership (spec §7.1).
   let { data, form }: Props = $props();
 
   let rootEl = $state<HTMLElement>();
+  // Lets a mistyped address go back to the form without a reload, even though the server still
+  // reports `sent`. The success copy never reveals whether the email was on the allowlist.
+  let dismissed = $state(false);
   onMount(() => {
     if (rootEl) warnIfChromeWrapped(rootEl);
   });
@@ -33,24 +38,54 @@ the allowlist, so the page never leaks membership (spec §7.1).
   <meta name="robots" content="noindex, nofollow" />
 </svelte:head>
 
+<!-- The brand mark renders in both states; the parent container sets its alignment (left for the
+     form, centered for the confirmation), so one snippet covers both. -->
+{#snippet brand()}
+  <div class="flex items-center gap-2">
+    <CairnLogo class="h-8 w-8 text-primary" />
+    <span class="text-xl font-bold tracking-[-0.01em] font-[family-name:var(--font-display)]">Cairn</span>
+  </div>
+{/snippet}
+
 <!-- data-theme on a bare wrapper: the scoped sheet styles descendants, so the layout classes go one
      level in (a class on the theme element itself would not match). -->
 <div data-theme="cairn-admin" bind:this={rootEl}>
   <div class="flex min-h-screen flex-col items-center justify-center gap-6 bg-base-200 p-4 text-base-content">
   <div class="w-full max-w-sm rounded-box border border-[var(--cairn-card-border)] bg-base-100 p-7 shadow-[var(--cairn-shadow)]">
-    <div class="mb-6 flex items-center gap-2">
-      <CairnLogo class="h-8 w-8 text-primary" />
-      <span class="text-xl font-bold tracking-[-0.01em] font-[family-name:var(--font-display)]">Cairn</span>
-    </div>
-
-    <h1 class="text-lg font-semibold">Sign in to {data.siteName}</h1>
-    <p class="mt-1 mb-5 text-sm text-[var(--color-muted)]">Enter your email. We'll send a one-time sign-in link.</p>
-
-    {#if form?.sent}
-      <div role="status" class="alert alert-success text-sm">
-        Check your email for a sign-in link. It expires in 10 minutes.
+    {#if form?.sent && !dismissed}
+      <!-- The confirmation is a centered moment: brand, then the mail mark, heading, and one line of
+           instruction. The fallback help sits in a gentle inset note below. -->
+      <div role="status" class="flex flex-col items-center text-center">
+        <div class="mb-7">{@render brand()}</div>
+        <div
+          class="flex h-12 w-12 items-center justify-center rounded-xl text-[var(--color-success)]"
+          style="background-color: color-mix(in oklch, var(--color-success) 15%, transparent); box-shadow: inset 0 0 0 1px color-mix(in oklch, var(--color-success) 22%, transparent);"
+        >
+          <MailCheckIcon class="h-6 w-6" />
+        </div>
+        <h1 class="mt-5 text-xl font-semibold tracking-tight">Check your email</h1>
+        <p class="mt-2 text-sm leading-relaxed text-[var(--color-muted)]">
+          We sent a sign-in link to your inbox. Open it within 10 minutes to finish signing in.
+        </p>
+        <div class="mt-6 flex w-full items-start gap-2.5 rounded-[var(--radius-field)] bg-base-content/[0.04] p-3.5 text-left">
+          <InfoIcon class="mt-px h-4 w-4 shrink-0 text-[var(--color-muted)]" />
+          <p class="text-[0.8125rem] leading-relaxed text-[var(--color-subtle)]">
+            No link after a minute or two? Check your spam folder first. If it still hasn't arrived, the
+            address may not match the one your site owner added.
+          </p>
+        </div>
+        <button
+          type="button"
+          class="mt-5 cursor-pointer appearance-none border-none bg-transparent p-0 text-sm font-medium text-primary hover:underline"
+          onclick={() => (dismissed = true)}
+        >
+          Use a different email
+        </button>
       </div>
     {:else}
+      <div class="mb-6 flex justify-center">{@render brand()}</div>
+      <h1 class="text-center text-lg font-semibold">Sign in to {data.siteName}</h1>
+      <p class="mt-1 mb-5 text-center text-sm text-[var(--color-muted)]">Enter your email. We'll send a one-time sign-in link.</p>
       {#if data.error}
         <div role="alert" class="alert alert-error mb-3 text-sm">That link expired. Request a new one below.</div>
       {/if}

package/dist/components/cairn-admin.css

@@ -11,6 +11,7 @@
       --tw-skew-y: initial;
       --tw-space-y-reverse: 0;
       --tw-border-style: solid;
+      --tw-leading: initial;
       --tw-font-weight: initial;
       --tw-tracking: initial;
       --tw-ordinal: initial;
@@ -79,6 +80,7 @@
     --font-weight-bold: 700;
     --tracking-tight: -.025em;
     --tracking-wide: .025em;
+    --leading-relaxed: 1.625;
     --radius-md: .375rem;
     --radius-xl: .75rem;
     --animate-spin: spin 1s linear infinite;
@@ -3337,6 +3339,10 @@
     margin-top: calc(var(--spacing) * 4);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .mt-5 {
+    margin-top: calc(var(--spacing) * 5);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .mt-6 {
     margin-top: calc(var(--spacing) * 6);
   }
@@ -3353,6 +3359,10 @@
     margin-top: auto;
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .mt-px {
+    margin-top: 1px;
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .mr-1 {
     margin-right: calc(var(--spacing) * 1);
   }
@@ -3394,6 +3404,10 @@
     margin-bottom: calc(var(--spacing) * 6);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .mb-7 {
+    margin-bottom: calc(var(--spacing) * 7);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .ml-1 {
     margin-left: calc(var(--spacing) * 1);
   }
@@ -3786,6 +3800,10 @@
     height: calc(var(--spacing) * 5);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .h-6 {
+    height: calc(var(--spacing) * 6);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .h-7 {
     height: calc(var(--spacing) * 7);
   }
@@ -3852,6 +3870,10 @@
     width: calc(var(--spacing) * 5);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .w-6 {
+    width: calc(var(--spacing) * 6);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .w-7 {
     width: calc(var(--spacing) * 7);
   }
@@ -4014,6 +4036,10 @@
     cursor: pointer;
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .appearance-none {
+    appearance: none;
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .flex-col {
     flex-direction: column;
   }
@@ -4146,6 +4172,10 @@
     border-radius: .25rem;
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .rounded-\[var\(--radius-field\)\] {
+    border-radius: var(--radius-field);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .rounded-box {
     border-radius: var(--radius-box);
     border-radius: var(--radius-box);
@@ -4188,6 +4218,11 @@
     border-bottom-width: 1px;
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .border-none {
+    --tw-border-style: none;
+    border-style: none;
+  }
+
   @layer daisyui.l1.l2 {
     :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .badge-ghost {
       border-color: var(--color-base-200);
@@ -4305,6 +4340,10 @@
     padding: calc(var(--spacing) * 3);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .p-3\.5 {
+    padding: calc(var(--spacing) * 3.5);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .p-4 {
     padding: calc(var(--spacing) * 4);
   }
@@ -4432,6 +4471,10 @@
     text-align: center;
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .text-left {
+    text-align: left;
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .text-right {
     text-align: right;
   }
@@ -4489,6 +4532,15 @@
     font-size: .6875rem;
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .text-\[0\.8125rem\] {
+    font-size: .8125rem;
+  }
+
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .leading-relaxed {
+    --tw-leading: var(--leading-relaxed);
+    line-height: var(--leading-relaxed);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .font-bold {
     --tw-font-weight: var(--font-weight-bold);
     font-weight: var(--font-weight-bold);
@@ -4561,6 +4613,10 @@
     color: var(--color-subtle);
   }
 
+  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .text-\[var\(--color-success\)\] {
+    color: var(--color-success);
+  }
+
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .text-base-content {
     color: var(--color-base-content);
   }
@@ -5328,6 +5384,11 @@
   initial-value: solid;
 }
 
+@property --tw-leading {
+  syntax: "*";
+  inherits: false
+}
+
 @property --tw-font-weight {
   syntax: "*";
   inherits: false

package/dist/diagnostics/conditions.d.ts

@@ -0,0 +1,21 @@
+import type { CairnLogEvent } from '../log/index.js';
+export type ConditionSeverity = 'blocker' | 'warning';
+export interface CairnCondition {
+    /** Stable, greppable id, e.g. 'edge.https-not-forced'. */
+    id: string;
+    severity: ConditionSeverity;
+    /** Short human label. */
+    title: string;
+    /** One or two sentences on why the condition bites. */
+    why: string;
+    /** The fix, often a command. */
+    remediation: string;
+    /** Anchor into the readiness checklist doc, filled in when that doc lands (Pass 3). */
+    docsAnchor?: string;
+    /** The log vocabulary event this condition correlates with, if any. */
+    logEvent?: CairnLogEvent;
+}
+/** Resolve a condition by id. Throws on an unknown id, since ids are compile-time constants. */
+export declare function condition(id: string): CairnCondition;
+/** Every registered condition, for the checklist generator and coverage tests. */
+export declare function allConditions(): CairnCondition[];

package/dist/diagnostics/conditions.js

@@ -0,0 +1,37 @@
+const REGISTRY = {
+    'edge.https-not-forced': {
+        id: 'edge.https-not-forced',
+        severity: 'blocker',
+        title: 'Always Use HTTPS is off',
+        why: 'The JS-free admin sign-in posts a form, and the framework CSRF guard rejects a form POST whose origin scheme does not match, so an admin reached over http hits an opaque 403.',
+        remediation: 'Turn on Always Use HTTPS for the zone under SSL/TLS, Edge Certificates, and keep HSTS on.',
+        logEvent: 'guard.rejected',
+    },
+    'auth.csrf-token-invalid': {
+        id: 'auth.csrf-token-invalid',
+        severity: 'blocker',
+        title: 'Admin CSRF token check failed',
+        why: 'An admin form POST carried no valid __Host-cairn_csrf double-submit token, usually a stale tab or blocked cookies.',
+        remediation: 'Open the sign-in page fresh, allow cookies for the site, and request a new link.',
+        logEvent: 'guard.rejected',
+    },
+    'auth.csrf-origin-mismatch': {
+        id: 'auth.csrf-origin-mismatch',
+        severity: 'blocker',
+        title: 'Non-admin form Origin rejected',
+        why: "A non-admin unsafe form POST carried an Origin that did not match the site, so cairn's restored framework Origin check rejected it.",
+        remediation: 'Post the form from the same origin, or check a proxy that strips or rewrites the Origin header.',
+        logEvent: 'guard.rejected',
+    },
+};
+/** Resolve a condition by id. Throws on an unknown id, since ids are compile-time constants. */
+export function condition(id) {
+    const found = REGISTRY[id];
+    if (!found)
+        throw new Error(`unknown cairn condition: ${id}`);
+    return found;
+}
+/** Every registered condition, for the checklist generator and coverage tests. */
+export function allConditions() {
+    return Object.values(REGISTRY);
+}

package/dist/diagnostics/error.d.ts

@@ -0,0 +1,9 @@
+import { type CairnCondition } from './conditions.js';
+export declare class CairnError extends Error {
+    readonly conditionId: string;
+    readonly condition: CairnCondition;
+    constructor(conditionId: string, options?: {
+        cause?: unknown;
+        message?: string;
+    });
+}

package/dist/diagnostics/error.js

@@ -0,0 +1,15 @@
+// CairnError: a thrown failure that names a known condition. A catch site narrows on it, logs from
+// the condition, and renders the condition's message in place of an opaque string. Its first
+// throw-site is Pass 2 (the email send mapping); Pass 1 lands and tests the primitive.
+import { condition } from './conditions.js';
+export class CairnError extends Error {
+    conditionId;
+    condition;
+    constructor(conditionId, options) {
+        const resolved = condition(conditionId);
+        super(options?.message ?? resolved.title, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = 'CairnError';
+        this.conditionId = conditionId;
+        this.condition = resolved;
+    }
+}

package/dist/diagnostics/index.d.ts

@@ -0,0 +1,3 @@
+export { condition, allConditions } from './conditions.js';
+export type { CairnCondition, ConditionSeverity } from './conditions.js';
+export { CairnError } from './error.js';

package/dist/diagnostics/index.js

@@ -0,0 +1,3 @@
+// Internal barrel for the diagnostics model. Not re-exported from any public package subpath.
+export { condition, allConditions } from './conditions.js';
+export { CairnError } from './error.js';

package/dist/github/repo.js

@@ -1,4 +1,3 @@
-// src/lib/github/repo.ts
 // cairn-cms: repo reads and the commit, over the GitHub REST API. Listing a concept
 // directory uses the Git Trees API (the contents API silently truncates at 1,000 entries,
 // spec §7.3); a single-file read uses the contents API. An optional token lifts reads to

package/dist/github/types.js

@@ -1,4 +1,3 @@
-// src/lib/github/types.ts
 // cairn-cms: the GitHub backend's plain data types and its one typed error. The backend
 // reads repo coordinates from the adapter's `BackendConfig` (spec §8); `RepoRef` is the
 // `{ owner, repo, branch }` subset, so `backend` is assignable wherever a `RepoRef` is

package/dist/render/component-grammar.js

@@ -47,7 +47,7 @@ export function serializeComponent(def, values) {
         if (!content)
             continue;
         if (lines.length > 1)
-            lines.push(''); // blank line before this block
+            lines.push('');
         lines.push(`${COLON.repeat(3)}${slot.name}`, content, COLON.repeat(3));
     }
     lines.push(fence);

package/dist/sveltekit/admin-response.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Attach the baseline security headers to an admin response. No full CSP; see the auth-hardening
+ * design. frame-ancestors is the modern clickjacking control and the one CSP directive included.
+ */
+export declare function applySecurityHeaders(headers: Headers): void;
+/** A branded full-document admin page, hardened with the baseline headers and never cached. */
+export declare function brandedAdminPage(status: number, body: string): Response;

package/dist/sveltekit/admin-response.js

@@ -0,0 +1,21 @@
+// Shared response helpers for cairn's admin pages: the baseline security headers and a branded
+// full-document response. Extracted from guard.ts so the guard's resolve path and the condition
+// renderer share one definition.
+/**
+ * Attach the baseline security headers to an admin response. No full CSP; see the auth-hardening
+ * design. frame-ancestors is the modern clickjacking control and the one CSP directive included.
+ */
+export function applySecurityHeaders(headers) {
+    headers.set('X-Content-Type-Options', 'nosniff');
+    headers.set('X-Frame-Options', 'DENY');
+    headers.set('Content-Security-Policy', "frame-ancestors 'none'");
+    headers.set('Referrer-Policy', 'no-referrer');
+    headers.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
+    headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
+}
+/** A branded full-document admin page, hardened with the baseline headers and never cached. */
+export function brandedAdminPage(status, body) {
+    const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+    applySecurityHeaders(headers);
+    return new Response(body, { status, headers });
+}

package/dist/sveltekit/condition-response.d.ts

@@ -0,0 +1,11 @@
+/** The guard.rejected reasons, each mapped to its registered condition id. */
+export declare const REASON_CONDITION: {
+    readonly https: "edge.https-not-forced";
+    readonly csrf: "auth.csrf-token-invalid";
+    readonly origin: "auth.csrf-origin-mismatch";
+};
+export type GuardReason = keyof typeof REASON_CONDITION;
+/** Render the Response the guard serves for a rejection, by its condition id. */
+export declare function renderConditionResponse(id: string, ctx?: {
+    url?: URL;
+}): Response;

package/dist/sveltekit/condition-response.js

@@ -0,0 +1,34 @@
+// The runtime renderer leg of the diagnostics model: map a condition to the Response the guard
+// serves. Re-homes the three rejection responses guard.ts built inline, keyed by condition id, so
+// the guard's reason, the registered condition, and the served page stay in step.
+import { brandedAdminPage } from './admin-response.js';
+import { httpsRequiredPage } from './https-required-page.js';
+import { csrfRequiredPage } from './csrf-required-page.js';
+import { condition } from '../diagnostics/index.js';
+/** The guard.rejected reasons, each mapped to its registered condition id. */
+export const REASON_CONDITION = {
+    https: 'edge.https-not-forced',
+    csrf: 'auth.csrf-token-invalid',
+    origin: 'auth.csrf-origin-mismatch',
+};
+/** Render the Response the guard serves for a rejection, by its condition id. */
+export function renderConditionResponse(id, ctx = {}) {
+    // Assert the id is registered before rendering, keeping the renderer in 1:1 with the registry.
+    condition(id);
+    switch (id) {
+        case REASON_CONDITION.https: {
+            const httpsUrl = new URL(ctx.url);
+            httpsUrl.protocol = 'https:';
+            return brandedAdminPage(400, httpsRequiredPage(httpsUrl.toString()));
+        }
+        case REASON_CONDITION.csrf:
+            return brandedAdminPage(403, csrfRequiredPage());
+        case REASON_CONDITION.origin:
+            return new Response('Cross-site POST form submissions are forbidden', {
+                status: 403,
+                headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+            });
+        default:
+            throw new Error(`no runtime renderer for condition: ${id}`);
+    }
+}

package/dist/sveltekit/guard.js

@@ -4,9 +4,9 @@
 import { redirect, error } from '@sveltejs/kit';
 import { resolveSession } from '../auth/store.js';
 import { sessionCookieName } from '../auth/crypto.js';
-import { httpsRequiredPage } from './https-required-page.js';
 import { isUnsafeFormRequest, originMatches, validateCsrfToken } from './csrf.js';
-import { csrfRequiredPage } from './csrf-required-page.js';
+import { applySecurityHeaders } from './admin-response.js';
+import { renderConditionResponse } from './condition-response.js';
 import { log } from '../log/index.js';
 /** The login page and the auth endpoints are public; everything else under /admin is gated. */
 function isPublicAdminPath(pathname) {
@@ -28,41 +28,6 @@ function isLocalHost(hostname) {
         hostname === '[::1]' ||
         hostname.endsWith('.localhost'));
 }
-/**
- * Attach the baseline security headers to an admin response. No full CSP; see the auth-hardening
- * design. frame-ancestors is the modern clickjacking control and the one CSP directive included.
- */
-function applySecurityHeaders(headers) {
-    headers.set('X-Content-Type-Options', 'nosniff');
-    headers.set('X-Frame-Options', 'DENY');
-    headers.set('Content-Security-Policy', "frame-ancestors 'none'");
-    headers.set('Referrer-Policy', 'no-referrer');
-    headers.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
-    headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
-}
-/** A branded full-document admin page, hardened with the baseline headers and never cached. */
-function brandedAdminPage(status, body) {
-    const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
-    applySecurityHeaders(headers);
-    return new Response(body, { status, headers });
-}
-/** The hardened 400 help page for a deployed admin request that arrived over http. */
-function httpsRequiredResponse(url) {
-    const httpsUrl = new URL(url);
-    httpsUrl.protocol = 'https:';
-    return brandedAdminPage(400, httpsRequiredPage(httpsUrl.toString()));
-}
-/** A plain 403 for a non-admin cross-origin form POST, matching the framework's wording. */
-function csrfForbidden() {
-    return new Response('Cross-site POST form submissions are forbidden', {
-        status: 403,
-        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-    });
-}
-/** The branded 403 for a failed admin double-submit token check. */
-function csrfRequiredResponse() {
-    return brandedAdminPage(403, csrfRequiredPage());
-}
 /** The SvelteKit `Handle` that guards `/admin/**` and hardens admin responses. */
 export function createAuthGuard() {
     return async function handle({ event, resolve }) {
@@ -72,7 +37,7 @@ export function createAuthGuard() {
         if (!isAdminPath(pathname)) {
             if (isUnsafeFormRequest(event.request) && !originMatches(event)) {
                 log.warn('guard.rejected', { reason: 'origin', path: pathname });
-                return csrfForbidden();
+                return renderConditionResponse('auth.csrf-origin-mismatch');
             }
             return resolve(event);
         }
@@ -82,13 +47,13 @@ export function createAuthGuard() {
         // posts. Local http (wrangler dev) is exempt.
         if (event.url.protocol === 'http:' && !isLocalHost(event.url.hostname)) {
             log.warn('guard.rejected', { reason: 'https', path: pathname });
-            return httpsRequiredResponse(event.url);
+            return renderConditionResponse('edge.https-not-forced', { url: event.url });
         }
         // Rule 1 - admin: every unsafe form POST carries a valid double-submit token, else the branded
         // 403 before resolve() runs. This covers the public login/auth posts too.
         if (isUnsafeFormRequest(event.request) && !(await validateCsrfToken(event))) {
             log.warn('guard.rejected', { reason: 'csrf', path: pathname });
-            return csrfRequiredResponse();
+            return renderConditionResponse('auth.csrf-token-invalid');
         }
         if (!isPublicAdminPath(pathname)) {
             const env = event.platform?.env ?? {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.36.0",
+  "version": "0.37.1",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "sideEffects": [

package/src/lib/components/LoginPage.svelte

@@ -7,6 +7,8 @@ the allowlist, so the page never leaks membership (spec §7.1).
 <script lang="ts">
   import './cairn-admin.css';
   import { onMount } from 'svelte';
+  import MailCheckIcon from '@lucide/svelte/icons/mail-check';
+  import InfoIcon from '@lucide/svelte/icons/info';
   import CairnLogo from './CairnLogo.svelte';
   import CsrfField from './CsrfField.svelte';
   import { cairnFaviconHref } from './cairn-favicon.js';
@@ -22,6 +24,9 @@ the allowlist, so the page never leaks membership (spec §7.1).
   let { data, form }: Props = $props();
 
   let rootEl = $state<HTMLElement>();
+  // Lets a mistyped address go back to the form without a reload, even though the server still
+  // reports `sent`. The success copy never reveals whether the email was on the allowlist.
+  let dismissed = $state(false);
   onMount(() => {
     if (rootEl) warnIfChromeWrapped(rootEl);
   });
@@ -33,24 +38,54 @@ the allowlist, so the page never leaks membership (spec §7.1).
   <meta name="robots" content="noindex, nofollow" />
 </svelte:head>
 
+<!-- The brand mark renders in both states; the parent container sets its alignment (left for the
+     form, centered for the confirmation), so one snippet covers both. -->
+{#snippet brand()}
+  <div class="flex items-center gap-2">
+    <CairnLogo class="h-8 w-8 text-primary" />
+    <span class="text-xl font-bold tracking-[-0.01em] font-[family-name:var(--font-display)]">Cairn</span>
+  </div>
+{/snippet}
+
 <!-- data-theme on a bare wrapper: the scoped sheet styles descendants, so the layout classes go one
      level in (a class on the theme element itself would not match). -->
 <div data-theme="cairn-admin" bind:this={rootEl}>
   <div class="flex min-h-screen flex-col items-center justify-center gap-6 bg-base-200 p-4 text-base-content">
   <div class="w-full max-w-sm rounded-box border border-[var(--cairn-card-border)] bg-base-100 p-7 shadow-[var(--cairn-shadow)]">
-    <div class="mb-6 flex items-center gap-2">
-      <CairnLogo class="h-8 w-8 text-primary" />
-      <span class="text-xl font-bold tracking-[-0.01em] font-[family-name:var(--font-display)]">Cairn</span>
-    </div>
-
-    <h1 class="text-lg font-semibold">Sign in to {data.siteName}</h1>
-    <p class="mt-1 mb-5 text-sm text-[var(--color-muted)]">Enter your email. We'll send a one-time sign-in link.</p>
-
-    {#if form?.sent}
-      <div role="status" class="alert alert-success text-sm">
-        Check your email for a sign-in link. It expires in 10 minutes.
+    {#if form?.sent && !dismissed}
+      <!-- The confirmation is a centered moment: brand, then the mail mark, heading, and one line of
+           instruction. The fallback help sits in a gentle inset note below. -->
+      <div role="status" class="flex flex-col items-center text-center">
+        <div class="mb-7">{@render brand()}</div>
+        <div
+          class="flex h-12 w-12 items-center justify-center rounded-xl text-[var(--color-success)]"
+          style="background-color: color-mix(in oklch, var(--color-success) 15%, transparent); box-shadow: inset 0 0 0 1px color-mix(in oklch, var(--color-success) 22%, transparent);"
+        >
+          <MailCheckIcon class="h-6 w-6" />
+        </div>
+        <h1 class="mt-5 text-xl font-semibold tracking-tight">Check your email</h1>
+        <p class="mt-2 text-sm leading-relaxed text-[var(--color-muted)]">
+          We sent a sign-in link to your inbox. Open it within 10 minutes to finish signing in.
+        </p>
+        <div class="mt-6 flex w-full items-start gap-2.5 rounded-[var(--radius-field)] bg-base-content/[0.04] p-3.5 text-left">
+          <InfoIcon class="mt-px h-4 w-4 shrink-0 text-[var(--color-muted)]" />
+          <p class="text-[0.8125rem] leading-relaxed text-[var(--color-subtle)]">
+            No link after a minute or two? Check your spam folder first. If it still hasn't arrived, the
+            address may not match the one your site owner added.
+          </p>
+        </div>
+        <button
+          type="button"
+          class="mt-5 cursor-pointer appearance-none border-none bg-transparent p-0 text-sm font-medium text-primary hover:underline"
+          onclick={() => (dismissed = true)}
+        >
+          Use a different email
+        </button>
       </div>
     {:else}
+      <div class="mb-6 flex justify-center">{@render brand()}</div>
+      <h1 class="text-center text-lg font-semibold">Sign in to {data.siteName}</h1>
+      <p class="mt-1 mb-5 text-center text-sm text-[var(--color-muted)]">Enter your email. We'll send a one-time sign-in link.</p>
       {#if data.error}
         <div role="alert" class="alert alert-error mb-3 text-sm">That link expired. Request a new one below.</div>
       {/if}

package/src/lib/diagnostics/conditions.ts

@@ -0,0 +1,64 @@
+// The cairn condition registry: one entry per known environment or operational failure mode. It is
+// the shared identity the readiness checklist, the doctor probe, and the runtime renderer all draw
+// from, so the three surfaces agree (the 1:1:1). Internal: exported from no public package subpath,
+// so the shape stays free to grow, the same stance as src/lib/log/. Renaming an id is a breaking
+// change to the observable contract. See
+// docs/superpowers/specs/2026-06-08-cairn-diagnostics-initiative-design.md.
+import type { CairnLogEvent } from '../log/index.js';
+
+export type ConditionSeverity = 'blocker' | 'warning';
+
+export interface CairnCondition {
+	/** Stable, greppable id, e.g. 'edge.https-not-forced'. */
+	id: string;
+	severity: ConditionSeverity;
+	/** Short human label. */
+	title: string;
+	/** One or two sentences on why the condition bites. */
+	why: string;
+	/** The fix, often a command. */
+	remediation: string;
+	/** Anchor into the readiness checklist doc, filled in when that doc lands (Pass 3). */
+	docsAnchor?: string;
+	/** The log vocabulary event this condition correlates with, if any. */
+	logEvent?: CairnLogEvent;
+}
+
+const REGISTRY: Record<string, CairnCondition> = {
+	'edge.https-not-forced': {
+		id: 'edge.https-not-forced',
+		severity: 'blocker',
+		title: 'Always Use HTTPS is off',
+		why: 'The JS-free admin sign-in posts a form, and the framework CSRF guard rejects a form POST whose origin scheme does not match, so an admin reached over http hits an opaque 403.',
+		remediation: 'Turn on Always Use HTTPS for the zone under SSL/TLS, Edge Certificates, and keep HSTS on.',
+		logEvent: 'guard.rejected',
+	},
+	'auth.csrf-token-invalid': {
+		id: 'auth.csrf-token-invalid',
+		severity: 'blocker',
+		title: 'Admin CSRF token check failed',
+		why: 'An admin form POST carried no valid __Host-cairn_csrf double-submit token, usually a stale tab or blocked cookies.',
+		remediation: 'Open the sign-in page fresh, allow cookies for the site, and request a new link.',
+		logEvent: 'guard.rejected',
+	},
+	'auth.csrf-origin-mismatch': {
+		id: 'auth.csrf-origin-mismatch',
+		severity: 'blocker',
+		title: 'Non-admin form Origin rejected',
+		why: "A non-admin unsafe form POST carried an Origin that did not match the site, so cairn's restored framework Origin check rejected it.",
+		remediation: 'Post the form from the same origin, or check a proxy that strips or rewrites the Origin header.',
+		logEvent: 'guard.rejected',
+	},
+};
+
+/** Resolve a condition by id. Throws on an unknown id, since ids are compile-time constants. */
+export function condition(id: string): CairnCondition {
+	const found = REGISTRY[id];
+	if (!found) throw new Error(`unknown cairn condition: ${id}`);
+	return found;
+}
+
+/** Every registered condition, for the checklist generator and coverage tests. */
+export function allConditions(): CairnCondition[] {
+	return Object.values(REGISTRY);
+}

package/src/lib/diagnostics/error.ts

@@ -0,0 +1,20 @@
+// CairnError: a thrown failure that names a known condition. A catch site narrows on it, logs from
+// the condition, and renders the condition's message in place of an opaque string. Its first
+// throw-site is Pass 2 (the email send mapping); Pass 1 lands and tests the primitive.
+import { condition, type CairnCondition } from './conditions.js';
+
+export class CairnError extends Error {
+	readonly conditionId: string;
+	readonly condition: CairnCondition;
+
+	constructor(conditionId: string, options?: { cause?: unknown; message?: string }) {
+		const resolved = condition(conditionId);
+		super(
+			options?.message ?? resolved.title,
+			options?.cause !== undefined ? { cause: options.cause } : undefined
+		);
+		this.name = 'CairnError';
+		this.conditionId = conditionId;
+		this.condition = resolved;
+	}
+}

package/src/lib/diagnostics/index.ts

@@ -0,0 +1,4 @@
+// Internal barrel for the diagnostics model. Not re-exported from any public package subpath.
+export { condition, allConditions } from './conditions.js';
+export type { CairnCondition, ConditionSeverity } from './conditions.js';
+export { CairnError } from './error.js';

package/src/lib/github/credentials.ts

@@ -1,4 +1,3 @@
-// src/lib/github/credentials.ts
 // cairn-cms: the bridge from the adapter's backend config and the Worker's secret to the
 // App signer's input. One tested place owns the join and the missing-secret failure, so the
 // save action (Plan 05) stays thin and a misconfigured Worker fails by name, not with a deep

package/src/lib/github/repo.ts

@@ -1,4 +1,3 @@
-// src/lib/github/repo.ts
 // cairn-cms: repo reads and the commit, over the GitHub REST API. Listing a concept
 // directory uses the Git Trees API (the contents API silently truncates at 1,000 entries,
 // spec §7.3); a single-file read uses the contents API. An optional token lifts reads to

package/src/lib/github/signing.ts

@@ -1,4 +1,3 @@
-// src/lib/github/signing.ts
 // cairn-cms: the GitHub App auth path. Mint an RS256 App JWT signed in-Worker with Web
 // Crypto, exchange it for a short-lived installation access token, and self-test the
 // brittle key conversion. GitHub issues PKCS#1 private keys and Web Crypto's importKey

package/src/lib/github/types.ts

@@ -1,4 +1,3 @@
-// src/lib/github/types.ts
 // cairn-cms: the GitHub backend's plain data types and its one typed error. The backend
 // reads repo coordinates from the adapter's `BackendConfig` (spec §8); `RepoRef` is the
 // `{ owner, repo, branch }` subset, so `backend` is assignable wherever a `RepoRef` is

package/src/lib/render/component-grammar.ts

@@ -54,7 +54,7 @@ export function serializeComponent(def: ComponentDef, values: ComponentValues):
         ? (Array.isArray(raw) ? raw : []).filter((i) => i !== '').map((i) => `- ${i}`).join('\n')
         : ((raw as string | undefined) ?? '');
     if (!content) continue;
-    if (lines.length > 1) lines.push(''); // blank line before this block
+    if (lines.length > 1) lines.push('');
     lines.push(`${COLON.repeat(3)}${slot.name}`, content, COLON.repeat(3));
   }
 

package/src/lib/sveltekit/admin-response.ts

@@ -0,0 +1,23 @@
+// Shared response helpers for cairn's admin pages: the baseline security headers and a branded
+// full-document response. Extracted from guard.ts so the guard's resolve path and the condition
+// renderer share one definition.
+
+/**
+ * Attach the baseline security headers to an admin response. No full CSP; see the auth-hardening
+ * design. frame-ancestors is the modern clickjacking control and the one CSP directive included.
+ */
+export function applySecurityHeaders(headers: Headers): void {
+  headers.set('X-Content-Type-Options', 'nosniff');
+  headers.set('X-Frame-Options', 'DENY');
+  headers.set('Content-Security-Policy', "frame-ancestors 'none'");
+  headers.set('Referrer-Policy', 'no-referrer');
+  headers.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
+  headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
+}
+
+/** A branded full-document admin page, hardened with the baseline headers and never cached. */
+export function brandedAdminPage(status: number, body: string): Response {
+  const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+  applySecurityHeaders(headers);
+  return new Response(body, { status, headers });
+}

package/src/lib/sveltekit/condition-response.ts

@@ -0,0 +1,38 @@
+// The runtime renderer leg of the diagnostics model: map a condition to the Response the guard
+// serves. Re-homes the three rejection responses guard.ts built inline, keyed by condition id, so
+// the guard's reason, the registered condition, and the served page stay in step.
+import { brandedAdminPage } from './admin-response.js';
+import { httpsRequiredPage } from './https-required-page.js';
+import { csrfRequiredPage } from './csrf-required-page.js';
+import { condition } from '../diagnostics/index.js';
+
+/** The guard.rejected reasons, each mapped to its registered condition id. */
+export const REASON_CONDITION = {
+  https: 'edge.https-not-forced',
+  csrf: 'auth.csrf-token-invalid',
+  origin: 'auth.csrf-origin-mismatch',
+} as const;
+
+export type GuardReason = keyof typeof REASON_CONDITION;
+
+/** Render the Response the guard serves for a rejection, by its condition id. */
+export function renderConditionResponse(id: string, ctx: { url?: URL } = {}): Response {
+  // Assert the id is registered before rendering, keeping the renderer in 1:1 with the registry.
+  condition(id);
+  switch (id) {
+    case REASON_CONDITION.https: {
+      const httpsUrl = new URL(ctx.url!);
+      httpsUrl.protocol = 'https:';
+      return brandedAdminPage(400, httpsRequiredPage(httpsUrl.toString()));
+    }
+    case REASON_CONDITION.csrf:
+      return brandedAdminPage(403, csrfRequiredPage());
+    case REASON_CONDITION.origin:
+      return new Response('Cross-site POST form submissions are forbidden', {
+        status: 403,
+        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+      });
+    default:
+      throw new Error(`no runtime renderer for condition: ${id}`);
+  }
+}

package/src/lib/sveltekit/guard.ts

@@ -4,9 +4,9 @@
 import { redirect, error } from '@sveltejs/kit';
 import { resolveSession } from '../auth/store.js';
 import { sessionCookieName } from '../auth/crypto.js';
-import { httpsRequiredPage } from './https-required-page.js';
 import { isUnsafeFormRequest, originMatches, validateCsrfToken } from './csrf.js';
-import { csrfRequiredPage } from './csrf-required-page.js';
+import { applySecurityHeaders } from './admin-response.js';
+import { renderConditionResponse } from './condition-response.js';
 import { log } from '../log/index.js';
 import type { Editor } from '../auth/types.js';
 import type { HandleInput, RequestContext } from './types.js';
@@ -36,46 +36,6 @@ function isLocalHost(hostname: string): boolean {
   );
 }
 
-/**
- * Attach the baseline security headers to an admin response. No full CSP; see the auth-hardening
- * design. frame-ancestors is the modern clickjacking control and the one CSP directive included.
- */
-function applySecurityHeaders(headers: Headers): void {
-  headers.set('X-Content-Type-Options', 'nosniff');
-  headers.set('X-Frame-Options', 'DENY');
-  headers.set('Content-Security-Policy', "frame-ancestors 'none'");
-  headers.set('Referrer-Policy', 'no-referrer');
-  headers.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
-  headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
-}
-
-/** A branded full-document admin page, hardened with the baseline headers and never cached. */
-function brandedAdminPage(status: number, body: string): Response {
-  const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
-  applySecurityHeaders(headers);
-  return new Response(body, { status, headers });
-}
-
-/** The hardened 400 help page for a deployed admin request that arrived over http. */
-function httpsRequiredResponse(url: URL): Response {
-  const httpsUrl = new URL(url);
-  httpsUrl.protocol = 'https:';
-  return brandedAdminPage(400, httpsRequiredPage(httpsUrl.toString()));
-}
-
-/** A plain 403 for a non-admin cross-origin form POST, matching the framework's wording. */
-function csrfForbidden(): Response {
-  return new Response('Cross-site POST form submissions are forbidden', {
-    status: 403,
-    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-  });
-}
-
-/** The branded 403 for a failed admin double-submit token check. */
-function csrfRequiredResponse(): Response {
-  return brandedAdminPage(403, csrfRequiredPage());
-}
-
 /** The SvelteKit `Handle` that guards `/admin/**` and hardens admin responses. */
 export function createAuthGuard() {
   return async function handle({ event, resolve }: HandleInput): Promise<Response> {
@@ -86,7 +46,7 @@ export function createAuthGuard() {
     if (!isAdminPath(pathname)) {
       if (isUnsafeFormRequest(event.request) && !originMatches(event)) {
         log.warn('guard.rejected', { reason: 'origin', path: pathname });
-        return csrfForbidden();
+        return renderConditionResponse('auth.csrf-origin-mismatch');
       }
       return resolve(event);
     }
@@ -97,14 +57,14 @@ export function createAuthGuard() {
     // posts. Local http (wrangler dev) is exempt.
     if (event.url.protocol === 'http:' && !isLocalHost(event.url.hostname)) {
       log.warn('guard.rejected', { reason: 'https', path: pathname });
-      return httpsRequiredResponse(event.url);
+      return renderConditionResponse('edge.https-not-forced', { url: event.url });
     }
 
     // Rule 1 - admin: every unsafe form POST carries a valid double-submit token, else the branded
     // 403 before resolve() runs. This covers the public login/auth posts too.
     if (isUnsafeFormRequest(event.request) && !(await validateCsrfToken(event))) {
       log.warn('guard.rejected', { reason: 'csrf', path: pathname });
-      return csrfRequiredResponse();
+      return renderConditionResponse('auth.csrf-token-invalid');
     }
 
     if (!isPublicAdminPath(pathname)) {