@glw907/cairn-cms 0.37.0 → 0.38.0

package/CHANGELOG.md

@@ -2,7 +2,36 @@
 
 All notable changes to this project are recorded here, most recent first.
 
-## 0.37.0
+## 0.38.0
+
+The magic-link send is now awaited rather than fire-and-forget, so a delivery failure reaches the
+login response instead of being swallowed. `requestAction` returns a `status` discriminant
+(`sent` | `send_error` | `throttled`) alongside the existing `sent` boolean, and `LoginPage` renders
+a send-error and a throttled state. The `auth.link.send_failed` log record gains a `code` (the
+Cloudflare binding error code) and a `conditionId` (the mapped diagnostic condition).
+
+Consumers may: read `form.status` to render the new states. A site rendering against `form.sent` is
+unaffected, since `sent` is unchanged.
+
+## 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"

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

@@ -8,6 +8,7 @@ the allowlist, so the page never leaks membership (spec §7.1).
   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';
@@ -16,8 +17,9 @@ the allowlist, so the page never leaks membership (spec §7.1).
   interface Props {
     /** The login load's data: the site name, an optional error, and the CSRF token. */
     data: { siteName: string; error: string | null; csrf: string };
-    /** The action result: `sent` is true once a request was accepted. */
-    form: { sent?: boolean } | null;
+    /** The action result. `sent` is true once a request was accepted; `status` discriminates the
+     * neutral, send-error, and throttled outcomes. */
+    form: { sent?: boolean; status?: 'sent' | 'send_error' | 'throttled' } | null;
   }
 
   let { data, form }: Props = $props();
@@ -37,47 +39,66 @@ 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>
-
-    {#if form?.sent && !dismissed}
-      <div role="status" class="mt-5 flex flex-col items-center text-center">
+    {#if (form?.status === 'sent' || 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="mb-4 flex h-11 w-11 items-center justify-center rounded-xl text-[var(--color-success)]"
-          style="background-color: color-mix(in oklch, var(--color-success) 16%, transparent);"
+          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>
-        <h2 class="text-lg font-semibold">Check your email</h2>
-        <p class="mt-1 text-sm text-[var(--color-muted)]">
+        <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-5 w-full border-t border-[var(--cairn-card-border)] pt-4 text-left">
-          <p class="text-sm text-[var(--color-muted)]">
-            No link after a minute or two? Check your spam folder first. If it still hasn't arrived,
-            double-check the address. It has to match the one your site owner added.
+        <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>
-          <button
-            type="button"
-            class="btn btn-ghost btn-sm mt-3 -ml-2 text-primary"
-            onclick={() => (dismissed = true)}
-          >
-            Use a different email
-          </button>
         </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}
-      <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 data.error}
+      <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 form?.status === 'send_error'}
+        <div role="alert" class="alert alert-warning mb-3 text-sm">
+          We're having trouble sending sign-in links right now. Please contact the site owner.
+        </div>
+      {:else if form?.status === 'throttled'}
+        <div role="status" class="alert mb-3 text-sm">
+          You requested a link recently. Check your inbox, or wait a minute and try again.
+        </div>
+      {/if}
+      <!-- A fresh action result supersedes the GET-time error, so a resubmit into a throttle or a
+           send failure never shows the stale expired-link alert alongside the new state. -->
+      {#if data.error && !form?.status}
         <div role="alert" class="alert alert-error mb-3 text-sm">That link expired. Request a new one below.</div>
       {/if}
       <form method="POST" class="flex flex-col gap-3">

package/dist/components/LoginPage.svelte.d.ts

@@ -6,9 +6,11 @@ interface Props {
         error: string | null;
         csrf: string;
     };
-    /** The action result: `sent` is true once a request was accepted. */
+    /** The action result. `sent` is true once a request was accepted; `status` discriminates the
+     * neutral, send-error, and throttled outcomes. */
     form: {
         sent?: boolean;
+        status?: 'sent' | 'send_error' | 'throttled';
     } | null;
 }
 /**

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;
@@ -3357,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);
   }
@@ -3398,8 +3404,8 @@
     margin-bottom: calc(var(--spacing) * 6);
   }
 
-  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .-ml-2 {
-    margin-left: calc(var(--spacing) * -2);
+  :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 {
@@ -3806,10 +3812,6 @@
     height: calc(var(--spacing) * 8);
   }
 
-  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .h-11 {
-    height: calc(var(--spacing) * 11);
-  }
-
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .h-12 {
     height: calc(var(--spacing) * 12);
   }
@@ -3884,10 +3886,6 @@
     width: calc(var(--spacing) * 9);
   }
 
-  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .w-11 {
-    width: calc(var(--spacing) * 11);
-  }
-
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .w-12 {
     width: calc(var(--spacing) * 12);
   }
@@ -4038,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;
   }
@@ -4170,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);
@@ -4212,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);
@@ -4329,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);
   }
@@ -4444,10 +4459,6 @@
     padding-top: calc(var(--spacing) * 3);
   }
 
-  :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .pt-4 {
-    padding-top: calc(var(--spacing) * 4);
-  }
-
   :where([data-theme='cairn-admin'], [data-theme='cairn-admin-dark']) .pr-3 {
     padding-right: calc(var(--spacing) * 3);
   }
@@ -4521,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);
@@ -5364,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,53 @@
+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',
+    },
+    'email.sender-not-onboarded': {
+        id: 'email.sender-not-onboarded',
+        severity: 'blocker',
+        title: 'Email sending domain is not onboarded',
+        why: 'The from-address domain has no enabled Cloudflare sending subdomain, so env.EMAIL.send has no aligned sender and the magic-link send throws E_SENDER_NOT_VERIFIED. No editor can sign in.',
+        remediation: 'Onboard the sending domain with `wrangler email sending enable <domain>`, then re-deploy. The domain must match branding.from.',
+        logEvent: 'auth.link.send_failed',
+    },
+    'email.send-failed': {
+        id: 'email.send-failed',
+        severity: 'blocker',
+        title: 'Magic-link email send failed',
+        why: 'The magic-link send threw for a reason other than a missing sender onboarding (a delivery error, a binding misconfiguration, or a custom sender failure), so the editor never received a link.',
+        remediation: 'Read the auth.link.send_failed log record (the code and error fields) in Workers Logs, and check the EMAIL binding and the sender configuration.',
+        logEvent: 'auth.link.send_failed',
+    },
+};
+/** 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/email.d.ts

@@ -1,4 +1,5 @@
 import type { AuthEnv } from './auth/types.js';
+import { CairnError } from './diagnostics/index.js';
 export type { AuthEnv };
 /** The message a built magic-link email carries. */
 export interface MagicLinkMessage {
@@ -14,7 +15,9 @@ export interface AuthBranding {
     from: string;
     replyTo?: string;
 }
-/** The injected send. Production uses `cloudflareSend`; tests pass a sink. */
+/** The injected send. Production uses `cloudflareSend`; tests pass a sink. A thrown error's
+ *  text reaches the structured log (scrubbed and truncated), so a custom sender must not embed
+ *  the message body or the magic link in what it throws. */
 export type SendMagicLink = (env: AuthEnv, message: MagicLinkMessage) => Promise<void>;
 /** Build the confirmation email. The link is the only action; the copy stays plain. */
 export declare function buildMagicLinkMessage(input: {
@@ -24,3 +27,19 @@ export declare function buildMagicLinkMessage(input: {
 }): MagicLinkMessage;
 /** The production send: Cloudflare Email Sending through the EMAIL binding. */
 export declare const cloudflareSend: SendMagicLink;
+/**
+ * Read the E_* code a Cloudflare Email Sending binding error carries (E_SENDER_NOT_VERIFIED,
+ * E_DELIVERY_FAILED, and the rest of the set). The structured `code` property is the documented
+ * shape, but it is unproven against the live binding, so a code embedded in the message is read as
+ * a fallback. A custom injected sender that throws a plain Error has neither, so this returns
+ * undefined and the record still logs cleanly.
+ */
+export declare function errorCode(err: unknown): string | undefined;
+/**
+ * Map a magic-link send failure to its registered diagnostic condition, carrying the original error
+ * as the cause. The not-verified code is the onboarding gap (the ecxc fault); the live binding has
+ * also been observed throwing the bare "not a verified address" string with no code, so that
+ * message maps to the same condition. Everything else is the generic send failure. The caller logs
+ * the conditionId and code, and returns a send_error status.
+ */
+export declare function emailSendFailure(err: unknown): CairnError;

package/dist/email.js

@@ -1,3 +1,4 @@
+import { CairnError } from './diagnostics/index.js';
 /** Escape the five HTML-significant characters. */
 function escapeHtml(value) {
     return value
@@ -23,3 +24,27 @@ export const cloudflareSend = async (env, message) => {
         throw new Error('EMAIL binding is not configured');
     await env.EMAIL.send(message);
 };
+/**
+ * Read the E_* code a Cloudflare Email Sending binding error carries (E_SENDER_NOT_VERIFIED,
+ * E_DELIVERY_FAILED, and the rest of the set). The structured `code` property is the documented
+ * shape, but it is unproven against the live binding, so a code embedded in the message is read as
+ * a fallback. A custom injected sender that throws a plain Error has neither, so this returns
+ * undefined and the record still logs cleanly.
+ */
+export function errorCode(err) {
+    if (typeof err === 'object' && err !== null && 'code' in err && typeof err.code === 'string') {
+        return err.code;
+    }
+    return String(err).match(/\bE_[A-Z][A-Z_]*\b/)?.[0];
+}
+/**
+ * Map a magic-link send failure to its registered diagnostic condition, carrying the original error
+ * as the cause. The not-verified code is the onboarding gap (the ecxc fault); the live binding has
+ * also been observed throwing the bare "not a verified address" string with no code, so that
+ * message maps to the same condition. Everything else is the generic send failure. The caller logs
+ * the conditionId and code, and returns a send_error status.
+ */
+export function emailSendFailure(err) {
+    const onboarding = errorCode(err) === 'E_SENDER_NOT_VERIFIED' || String(err).includes('not a verified address');
+    return new CairnError(onboarding ? 'email.sender-not-onboarded' : 'email.send-failed', { cause: err });
+}

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