@glw907/cairn-cms 0.40.0 → 0.50.0

package/dist/components/link-completion.js

@@ -1,5 +1,8 @@
-import { syntaxTree } from '@codemirror/language';
 import { formatCairnToken, escapeLinkText } from '../content/links.js';
+// EditPage imports this module statically, so a static @codemirror value import here would pull
+// CodeMirror into a consumer's server bundle. syntaxTree resolves lazily inside the source
+// instead (a CompletionSource may return a Promise), cached after the first completion.
+let langMod = null;
 /** The known concepts in display order; an unlisted concept sorts after these under its own name. */
 const CONCEPT_SECTIONS = {
     pages: { name: 'Pages', rank: 0 },
@@ -30,7 +33,7 @@ export function linkCompletions(targets, query) {
  *  whole `[[query` with the chosen link, and sets filter:false because linkCompletions already
  *  filtered by the query (CodeMirror would otherwise re-filter against the literal `[[query`). */
 export function cairnLinkCompletionSource(targets) {
-    return (context) => {
+    return async (context) => {
         const line = context.state.doc.lineAt(context.pos);
         const before = context.state.sliceDoc(line.from, context.pos);
         const trigger = matchCairnTrigger(before);
@@ -38,7 +41,11 @@ export function cairnLinkCompletionSource(targets) {
             return null;
         // Skip a [[ inside a fenced or inline code node: a cairn link there would be literal text, and
         // the build resolver does not look inside code. The node name carries "Code" for both forms.
-        const node = syntaxTree(context.state).resolveInner(context.pos, -1);
+        langMod ??= await import('@codemirror/language');
+        // The first completion awaits the import above, so the request may already be stale here.
+        if (context.aborted)
+            return null;
+        const node = langMod.syntaxTree(context.state).resolveInner(context.pos, -1);
         for (let n = node; n; n = n.parent) {
             if (/Code/.test(n.name))
                 return null;

package/dist/components/markdown-format.d.ts

@@ -22,11 +22,3 @@ export declare function insertInlineLink(doc: string, from: number, to: number,
  * is left in place.
  */
 export declare function unwrapCairnLink(doc: string, href: string): string;
-/**
- * Rewrite every cairn: link whose href is exactly `oldHref` so its href becomes `newHref`, keeping
- * the display text and any link title byte-for-byte. Rename calls this to repoint a renamed entry's
- * inbound tokens. Parsed with the same remark pipeline as extractCairnLinks, so a token inside a code
- * span is not a link node and is never touched. Each matching node's source span is rewritten from
- * last to first, replacing only the `](oldHref` run so the label and title stay exact.
- */
-export declare function rewriteCairnLink(doc: string, oldHref: string, newHref: string): string;

package/dist/components/markdown-format.js

@@ -157,31 +157,3 @@ export function unwrapCairnLink(doc, href) {
     }
     return out;
 }
-/**
- * Rewrite every cairn: link whose href is exactly `oldHref` so its href becomes `newHref`, keeping
- * the display text and any link title byte-for-byte. Rename calls this to repoint a renamed entry's
- * inbound tokens. Parsed with the same remark pipeline as extractCairnLinks, so a token inside a code
- * span is not a link node and is never touched. Each matching node's source span is rewritten from
- * last to first, replacing only the `](oldHref` run so the label and title stay exact.
- */
-export function rewriteCairnLink(doc, oldHref, newHref) {
-    const tree = unified().use(remarkParse).use(remarkGfm).parse(doc);
-    const spans = [];
-    visit(tree, 'link', (node) => {
-        if (node.url !== oldHref)
-            return;
-        const start = node.position?.start?.offset;
-        const end = node.position?.end?.offset;
-        if (start == null || end == null)
-            return;
-        spans.push({ start, end });
-    });
-    spans.sort((a, b) => b.start - a.start);
-    let out = doc;
-    for (const span of spans) {
-        const src = out.slice(span.start, span.end);
-        const rewritten = src.replace(`](${oldHref}`, `](${newHref}`);
-        out = out.slice(0, span.start) + rewritten + out.slice(span.end);
-    }
-    return out;
-}

package/dist/content/links.d.ts

@@ -18,3 +18,11 @@ export declare function escapeLinkText(text: string): string;
 /** The cairn links a markdown body points at, in first-occurrence order, deduped by concept/id.
  *  Parses the body as mdast, so a token inside a code span or fence is never matched. */
 export declare function extractCairnLinks(body: string): CairnRef[];
+/**
+ * Rewrite every cairn: link whose href is exactly `oldHref` so its href becomes `newHref`, keeping
+ * the display text and any link title byte-for-byte. Rename calls this to repoint a renamed entry's
+ * inbound tokens. Parsed with the same remark pipeline as extractCairnLinks, so a token inside a code
+ * span is not a link node and is never touched. Each matching node's source span is rewritten from
+ * last to first, replacing only the `](oldHref` run so the label and title stay exact.
+ */
+export declare function rewriteCairnLink(doc: string, oldHref: string, newHref: string): string;

package/dist/content/links.js

@@ -50,3 +50,31 @@ export function extractCairnLinks(body) {
     });
     return refs;
 }
+/**
+ * Rewrite every cairn: link whose href is exactly `oldHref` so its href becomes `newHref`, keeping
+ * the display text and any link title byte-for-byte. Rename calls this to repoint a renamed entry's
+ * inbound tokens. Parsed with the same remark pipeline as extractCairnLinks, so a token inside a code
+ * span is not a link node and is never touched. Each matching node's source span is rewritten from
+ * last to first, replacing only the `](oldHref` run so the label and title stay exact.
+ */
+export function rewriteCairnLink(doc, oldHref, newHref) {
+    const tree = unified().use(remarkParse).use(remarkGfm).parse(doc);
+    const spans = [];
+    visit(tree, 'link', (node) => {
+        if (node.url !== oldHref)
+            return;
+        const start = node.position?.start?.offset;
+        const end = node.position?.end?.offset;
+        if (start == null || end == null)
+            return;
+        spans.push({ start, end });
+    });
+    spans.sort((a, b) => b.start - a.start);
+    let out = doc;
+    for (const span of spans) {
+        const src = out.slice(span.start, span.end);
+        const rewritten = src.replace(`](${oldHref}`, `](${newHref}`);
+        out = out.slice(0, span.start) + rewritten + out.slice(span.end);
+    }
+    return out;
+}

package/dist/content/types.d.ts

@@ -154,8 +154,8 @@ export interface CairnAdapter {
     backend: BackendConfig;
     sender: SenderConfig;
     /** The site's one renderer: the editor preview and every public page call it (design decision 4).
-     *  `resolve` rewrites cairn: links to live permalinks; the build passes a site-index resolver, the
-     *  preview a manifest one. */
+     *  `resolve` rewrites cairn: links to live permalinks; the build passes a site-resolver-backed
+     *  one, the preview a manifest one. */
     render(md: string, opts?: {
         stagger?: boolean;
         resolve?: LinkResolve;

package/dist/delivery/data.d.ts

@@ -1,7 +1,7 @@
 export { createContentIndex, fromGlob } from './content-index.js';
 export type { RawFile, ContentSummary, ContentEntry, ContentIndex, ContentProblem } from './content-index.js';
-export { createSiteIndex } from './site-index.js';
-export type { SiteIndex, ConceptIndex } from './site-index.js';
+export { createSiteResolver, buildLinkResolver } from './site-resolver.js';
+export type { SiteResolver, ConceptIndex } from './site-resolver.js';
 export { createSiteIndexes } from './site-indexes.js';
 export type { SiteIndexes, SiteGlobs } from './site-indexes.js';
 export { siteDescriptors } from './site-descriptors.js';
@@ -15,9 +15,7 @@ export { buildSeoMeta } from './seo.js';
 export type { SeoInput, SeoMeta } from './seo.js';
 export { readSeoFields, resolveImageUrl } from './seo-fields.js';
 export type { SeoFields } from './seo-fields.js';
-export { paginate } from './paginate.js';
-export type { Page } from './paginate.js';
 export { rssResponse, jsonFeedResponse, sitemapResponse, robotsResponse } from './responses.js';
 export { jsonLdScript } from './json-ld.js';
 export { permalink } from '../content/permalink.js';
-export { buildSiteManifest, buildLinkResolver } from './manifest.js';
+export { buildSiteManifest } from './manifest.js';

package/dist/delivery/data.js

@@ -2,7 +2,7 @@
 // projections a SvelteKit site or a plain-Node tool reads, with no @sveltejs/kit and no .svelte in
 // the graph. The full ./delivery barrel re-exports this and adds the route loaders.
 export { createContentIndex, fromGlob } from './content-index.js';
-export { createSiteIndex } from './site-index.js';
+export { createSiteResolver, buildLinkResolver } from './site-resolver.js';
 export { createSiteIndexes } from './site-indexes.js';
 export { siteDescriptors } from './site-descriptors.js';
 export { deriveExcerpt, wordCount } from './excerpt.js';
@@ -11,8 +11,7 @@ export { buildSitemap } from './sitemap.js';
 export { buildRobots } from './robots.js';
 export { buildSeoMeta } from './seo.js';
 export { readSeoFields, resolveImageUrl } from './seo-fields.js';
-export { paginate } from './paginate.js';
 export { rssResponse, jsonFeedResponse, sitemapResponse, robotsResponse } from './responses.js';
 export { jsonLdScript } from './json-ld.js';
 export { permalink } from '../content/permalink.js';
-export { buildSiteManifest, buildLinkResolver } from './manifest.js';
+export { buildSiteManifest } from './manifest.js';

package/dist/delivery/feeds.js

@@ -2,13 +2,7 @@
 // channel and a list of items, so they unit-test without a render or a network. The caller
 // (a template +server.ts shim) assembles items from the content index and passes absolute
 // URLs built from PUBLIC_ORIGIN.
-function escapeXml(value) {
-    return value
-        .replace(/&/g, '&')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;');
-}
+import { escapeXml } from './xml.js';
 /** Make a string safe inside a CDATA section by splitting any `]]>` across two sections. */
 function cdataSafe(value) {
     return value.replace(/]]>/g, ']]]]><![CDATA[>');

package/dist/delivery/index.d.ts

@@ -1,3 +1,3 @@
 export * from './data.js';
-export { createPublicRoutes } from '../sveltekit/public-routes.js';
-export type { PublicRoutesDeps, ListData, TagData, TagIndexData, EntryData, } from '../sveltekit/public-routes.js';
+export { createPublicRoutes } from './public-routes.js';
+export type { PublicRoutesDeps, ListData, TagData, TagIndexData, EntryData, } from './public-routes.js';

package/dist/delivery/index.js

@@ -3,4 +3,4 @@
 // lives at ./delivery/head. Importing this pulls @sveltejs/kit through the route loaders, so a
 // plain-Node tool imports from ./delivery/data instead.
 export * from './data.js';
-export { createPublicRoutes } from '../sveltekit/public-routes.js';
+export { createPublicRoutes } from './public-routes.js';

package/dist/delivery/manifest.d.ts

@@ -1,12 +1,7 @@
 import type { Manifest } from '../content/manifest.js';
-import type { LinkResolve } from '../content/links.js';
-import type { SiteIndex } from './site-index.js';
 import type { SiteConfig } from '../nav/site-config.js';
 import type { CairnAdapter } from '../content/types.js';
 import type { SiteGlobs } from './site-indexes.js';
 /** Build the whole-corpus manifest from a site's adapter, config, and per-concept globs. Drafts are
  *  included and flagged, so the admin picker and the guards see the full graph. */
 export declare function buildSiteManifest<A extends CairnAdapter>(adapter: A, config: SiteConfig, globs: SiteGlobs<A>): Manifest;
-/** A resolver backed by the site index, for the build. A miss throws, so a dangling cairn: token
- *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks. */
-export declare function buildLinkResolver(site: SiteIndex): LinkResolve;

package/dist/delivery/manifest.js

@@ -1,8 +1,7 @@
-// cairn-cms: the build-side manifest builder and the build link resolver (content-graph design).
-// buildSiteManifest mirrors createSiteIndexes: it maps the site descriptors over the per-concept
-// globs and projects each file to a manifest row. buildLinkResolver reads the site index, which is
-// fresh from the files at build, and throws on a missing target so a dangling cairn: token fails
-// the build (the backstop). The admin preview uses manifestLinkResolver instead.
+// cairn-cms: the build-side manifest builder (content-graph design). buildSiteManifest mirrors
+// createSiteIndexes: it maps the site descriptors over the per-concept globs and projects each
+// file to a manifest row. The build-time cairn: link resolver lives beside the site resolver in
+// site-resolver.ts; the admin preview uses manifestLinkResolver instead.
 import { siteDescriptors } from './site-descriptors.js';
 import { fromGlob } from './content-index.js';
 import { parseMarkdown } from '../content/frontmatter.js';
@@ -15,7 +14,7 @@ export function buildSiteManifest(adapter, config, globs) {
     for (const descriptor of siteDescriptors(adapter, config)) {
         const record = globRecord[descriptor.id] ?? {};
         for (const file of fromGlob(record)) {
-            // Validate the same way createContentIndex does, so the manifest and the site index agree on
+            // Validate the same way createContentIndex does, so the manifest and the site resolver agree on
             // which entries exist. A validation failure is excluded from both; otherwise the preview would
             // resolve a link the build then rejects as a missing target.
             const { frontmatter, body } = parseMarkdown(file.raw);
@@ -26,13 +25,3 @@ export function buildSiteManifest(adapter, config, globs) {
     }
     return manifest;
 }
-/** A resolver backed by the site index, for the build. A miss throws, so a dangling cairn: token
- *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks. */
-export function buildLinkResolver(site) {
-    return (ref) => {
-        const url = site.concept(ref.concept)?.byId(ref.id)?.permalink;
-        if (!url)
-            throw new Error(`cairn link target not found: cairn:${ref.concept}/${ref.id}`);
-        return url;
-    };
-}

package/dist/{sveltekit → delivery}/public-routes.d.ts

@@ -1,10 +1,10 @@
-import type { ContentSummary, ContentEntry } from '../delivery/content-index.js';
-import type { SiteIndex } from '../delivery/site-index.js';
-import type { SeoMeta } from '../delivery/seo.js';
+import type { ContentSummary, ContentEntry } from './content-index.js';
+import type { SiteResolver } from './site-resolver.js';
+import type { SeoMeta } from './seo.js';
 import type { LinkResolve } from '../content/links.js';
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
-    site: SiteIndex;
+    site: SiteResolver;
     render: (md: string, opts?: {
         stagger?: boolean;
         resolve?: LinkResolve;

package/dist/{sveltekit → delivery}/public-routes.js

@@ -1,12 +1,12 @@
-// cairn-cms: public route loaders (dated-slug design). The factory closes over the site-level
-// index, the runtime render, and the origin. entryLoad and entries are site-wide: one catch-all
+// cairn-cms: public route loaders (dated-slug design). The factory closes over the site
+// resolver, the runtime render, and the origin. entryLoad and entries are site-wide: one catch-all
 // `[...path]` route resolves any concept by request path through `byPermalink`. The archive, tag,
-// and tag-index loaders stay concept-scoped, keyed by concept id. The index is built in site code
-// from globs, so it stays in the prerender graph and out of the runtime Worker.
+// and tag-index loaders stay concept-scoped, keyed by concept id. The resolver is built in site
+// code from globs, so it stays in the prerender graph and out of the runtime Worker.
 import { error } from '@sveltejs/kit';
-import { buildSeoMeta } from '../delivery/seo.js';
-import { readSeoFields, resolveImageUrl } from '../delivery/seo-fields.js';
-import { buildLinkResolver } from '../delivery/manifest.js';
+import { buildSeoMeta } from './seo.js';
+import { readSeoFields, resolveImageUrl } from './seo-fields.js';
+import { buildLinkResolver } from './site-resolver.js';
 /** Build the public loaders for a site's unified index. */
 export function createPublicRoutes(deps) {
     const { site, render, origin, siteName, description, feeds, defaultImage } = deps;

package/dist/delivery/site-indexes.d.ts

@@ -2,7 +2,7 @@ import type { CairnAdapter, ConceptConfig } from '../content/types.js';
 import type { Infer } from '../content/schema.js';
 import type { SiteConfig } from '../nav/site-config.js';
 import type { ContentIndex } from './content-index.js';
-import type { SiteIndex } from './site-index.js';
+import type { SiteResolver } from './site-resolver.js';
 /** A per-concept raw glob record (`{ path: raw }`) keyed by concept id, from `import.meta.glob`. */
 export type SiteGlobs<A extends CairnAdapter> = {
     [K in keyof A['content']]?: Record<string, string>;
@@ -12,13 +12,13 @@ export type SiteGlobs<A extends CairnAdapter> = {
 export type SiteIndexes<A extends CairnAdapter> = {
     [K in keyof A['content']]: ContentIndex<NonNullable<A['content'][K]> extends ConceptConfig<infer S> ? Infer<S> : Record<string, unknown>>;
 } & {
-    readonly site: SiteIndex;
+    readonly site: SiteResolver;
 };
 /**
  * Build typed per-concept indexes and a site resolver from one adapter. Pass the per-concept raw
  * globs as `{ posts: import.meta.glob('...?raw', { eager: true }), ... }`; Vite needs the literal
  * glob at the call site, so the engine cannot glob on the site's behalf. `validate: false` opts out
- * of the build gate, exactly as on `createSiteIndex`.
+ * of the build gate, exactly as on `createSiteResolver`.
  */
 export declare function createSiteIndexes<const A extends CairnAdapter>(adapter: A, config: SiteConfig, globs: SiteGlobs<A>, opts?: {
     validate?: boolean;

package/dist/delivery/site-indexes.js

@@ -1,11 +1,11 @@
 import { siteDescriptors } from './site-descriptors.js';
 import { createContentIndex, fromGlob } from './content-index.js';
-import { createSiteIndex } from './site-index.js';
+import { createSiteResolver } from './site-resolver.js';
 /**
  * Build typed per-concept indexes and a site resolver from one adapter. Pass the per-concept raw
  * globs as `{ posts: import.meta.glob('...?raw', { eager: true }), ... }`; Vite needs the literal
  * glob at the call site, so the engine cannot glob on the site's behalf. `validate: false` opts out
- * of the build gate, exactly as on `createSiteIndex`.
+ * of the build gate, exactly as on `createSiteResolver`.
  */
 export function createSiteIndexes(adapter, config, globs, opts = {}) {
     const descriptors = siteDescriptors(adapter, config);
@@ -25,6 +25,6 @@ export function createSiteIndexes(adapter, config, globs, opts = {}) {
         byConcept[descriptor.id] = index;
         conceptIndexes.push({ descriptor, index });
     }
-    const site = createSiteIndex(conceptIndexes, opts);
+    const site = createSiteResolver(conceptIndexes, opts);
     return { ...byConcept, site };
 }

package/dist/delivery/{site-index.d.ts → site-resolver.d.ts}

@@ -1,12 +1,13 @@
 import type { ConceptDescriptor } from '../content/types.js';
 import type { ContentEntry, ContentIndex, ContentSummary } from './content-index.js';
+import type { LinkResolve } from '../content/links.js';
 /** One concept's descriptor paired with its built index. */
 export interface ConceptIndex {
     descriptor: ConceptDescriptor;
     index: ContentIndex;
 }
 /** The cross-concept query surface a catch-all route and the sitemap read. */
-export interface SiteIndex {
+export interface SiteResolver {
     /** Resolve a request path (with or without a trailing slash) to its entry, or undefined. */
     byPermalink(path: string): ContentEntry | undefined;
     /** Newer/older neighbors within the entry's own concept, for prev/next links. */
@@ -28,6 +29,9 @@ export interface SiteIndex {
  * unless `validate` is `false`, on any non-draft entry whose frontmatter fails its concept's
  * validator, so malformed content fails the build instead of shipping.
  */
-export declare function createSiteIndex(concepts: ConceptIndex[], opts?: {
+export declare function createSiteResolver(concepts: ConceptIndex[], opts?: {
     validate?: boolean;
-}): SiteIndex;
+}): SiteResolver;
+/** A resolver backed by the site resolver, for the build. A miss throws, so a dangling cairn: token
+ *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks. */
+export declare function buildLinkResolver(site: SiteResolver): LinkResolve;

package/dist/delivery/{site-index.js → site-resolver.js}

@@ -21,11 +21,11 @@ function siteProblems(concepts) {
  * unless `validate` is `false`, on any non-draft entry whose frontmatter fails its concept's
  * validator, so malformed content fails the build instead of shipping.
  */
-export function createSiteIndex(concepts, opts = {}) {
+export function createSiteResolver(concepts, opts = {}) {
     if (opts.validate !== false) {
         const problems = siteProblems(concepts);
         if (problems.length > 0) {
-            throw new Error(`site index: ${problems.length} invalid frontmatter field(s):\n  ${problems.join('\n  ')}`);
+            throw new Error(`site resolver: ${problems.length} invalid frontmatter field(s):\n  ${problems.join('\n  ')}`);
         }
     }
     const byPath = new Map();
@@ -35,7 +35,7 @@ export function createSiteIndex(concepts, opts = {}) {
         for (const summary of index.all()) {
             const existing = byPath.get(summary.permalink);
             if (existing) {
-                throw new Error(`site index: "${existing.id}" and "${summary.id}" both resolve to "${summary.permalink}"`);
+                throw new Error(`site resolver: "${existing.id}" and "${summary.id}" both resolve to "${summary.permalink}"`);
             }
             byPath.set(summary.permalink, { index, id: summary.id });
         }
@@ -60,3 +60,13 @@ export function createSiteIndex(concepts, opts = {}) {
         },
     };
 }
+/** A resolver backed by the site resolver, for the build. A miss throws, so a dangling cairn: token
+ *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks. */
+export function buildLinkResolver(site) {
+    return (ref) => {
+        const url = site.concept(ref.concept)?.byId(ref.id)?.permalink;
+        if (!url)
+            throw new Error(`cairn link target not found: cairn:${ref.concept}/${ref.id}`);
+        return url;
+    };
+}

package/dist/delivery/sitemap.js

@@ -1,8 +1,6 @@
 // cairn-cms: sitemap builder (public-delivery design). Pure over a URL list; the caller
 // derives the list from the content index and the routable concepts.
-function escapeXml(value) {
-    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
+import { escapeXml } from './xml.js';
 /** Build a sitemap XML document from a list of URLs. */
 export function buildSitemap(urls) {
     const entries = urls

package/dist/delivery/xml.d.ts

@@ -0,0 +1,2 @@
+/** Escape the XML-significant characters for element text and double-quoted attribute values. */
+export declare function escapeXml(value: string): string;

package/dist/delivery/xml.js

@@ -0,0 +1,11 @@
+// cairn-cms: the one XML text escape the feed and sitemap builders share. The strongest of the
+// two copies it replaced (the old sitemap copy skipped quotes), so both documents stay safe in
+// element text and double-quoted attributes.
+/** Escape the XML-significant characters for element text and double-quoted attribute values. */
+export function escapeXml(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;');
+}

package/dist/diagnostics/conditions.d.ts

@@ -10,11 +10,18 @@ export interface CairnCondition {
     why: string;
     /** The fix, often a command. */
     remediation: string;
-    /** Anchor into the readiness checklist doc, filled in when that doc lands (Pass 3). */
+    /**
+     * The condition's section in the readiness checklist, written as
+     * 'cloudflare-readiness.md#<heading-slug>' so a doc can link it relative to docs/guides/.
+     * The check:readiness gate parses the part after '#' and asserts the heading exists; two
+     * conditions may share a section. Every entry carries one unless the gate's allowlist
+     * excuses it.
+     */
     docsAnchor?: string;
     /** The log vocabulary event this condition correlates with, if any. */
     logEvent?: CairnLogEvent;
 }
+export declare const REGISTRY: Record<string, CairnCondition>;
 /** 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. */

package/dist/diagnostics/conditions.js

@@ -1,10 +1,12 @@
-const REGISTRY = {
+// Exported for the freeze test only; resolve entries through condition() everywhere else.
+export 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.',
+        docsAnchor: 'cloudflare-readiness.md#force-https-at-the-edge',
         logEvent: 'guard.rejected',
     },
     'auth.csrf-token-invalid': {
@@ -13,6 +15,7 @@ const REGISTRY = {
         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.',
+        docsAnchor: 'cloudflare-readiness.md#admin-csrf-token-rejected',
         logEvent: 'guard.rejected',
     },
     'auth.csrf-origin-mismatch': {
@@ -21,6 +24,7 @@ const REGISTRY = {
         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.',
+        docsAnchor: 'cloudflare-readiness.md#non-admin-origin-rejected',
         logEvent: 'guard.rejected',
     },
     'email.sender-not-onboarded': {
@@ -29,6 +33,7 @@ const REGISTRY = {
         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.',
+        docsAnchor: 'cloudflare-readiness.md#onboard-the-sending-domain',
         logEvent: 'auth.link.send_failed',
     },
     'email.send-failed': {
@@ -37,9 +42,71 @@ const REGISTRY = {
         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.',
+        docsAnchor: 'cloudflare-readiness.md#onboard-the-sending-domain',
         logEvent: 'auth.link.send_failed',
     },
+    'config.bindings-missing': {
+        id: 'config.bindings-missing',
+        severity: 'blocker',
+        title: 'Wrangler bindings are missing',
+        why: 'The wrangler config declares no send_email binding named EMAIL or no D1 binding named AUTH_DB, so the magic-link send or the session store has nothing to call and no editor can sign in.',
+        remediation: 'Declare the send_email binding as EMAIL and the d1_databases binding as AUTH_DB in wrangler.jsonc (or wrangler.toml), then re-deploy.',
+        docsAnchor: 'cloudflare-readiness.md#deploy-the-worker-with-its-bindings',
+    },
+    'config.observability-off': {
+        id: 'config.observability-off',
+        severity: 'warning',
+        title: 'Workers Logs has no sink',
+        why: 'observability.enabled is not true in the wrangler config, so the structured log records go nowhere and a runtime failure leaves nothing to read.',
+        remediation: 'Set observability.enabled to true in wrangler.jsonc, then re-deploy.',
+        docsAnchor: 'cloudflare-readiness.md#turn-on-observability',
+    },
+    'config.csrf-disable-missing': {
+        id: 'config.csrf-disable-missing',
+        severity: 'warning',
+        title: 'Framework CSRF check is not handed off',
+        why: "The CSRF authority is not handed to cairn cleanly. Either svelte.config.js does not carry csrf: { checkOrigin: false }, so SvelteKit's own Origin check runs ahead of cairn's guard and rejects an admin form POST that arrives without an Origin header, or the disable is present with no cairn guard wired in src/hooks.server.ts, which leaves the site with no CSRF protection at all.",
+        remediation: "Set csrf: { checkOrigin: false } in svelte.config.js and wire createAuthGuard into src/hooks.server.ts; cairn's guard owns the Origin and double-submit token checks.",
+        docsAnchor: 'cloudflare-readiness.md#hand-cairn-the-csrf-authority',
+    },
+    'config.site-config-invalid': {
+        id: 'config.site-config-invalid',
+        severity: 'blocker',
+        title: 'Site config does not validate',
+        why: 'site.config.yaml fails to parse or fails the URL-policy validation, so the build and the admin cannot resolve the content concepts.',
+        remediation: 'Correct site.config.yaml; the parse or validation error names the failing field or URL-policy rule.',
+        docsAnchor: 'cloudflare-readiness.md#validate-the-site-config',
+    },
+    'edge.hsts-off': {
+        id: 'edge.hsts-off',
+        severity: 'warning',
+        title: 'HSTS is off',
+        why: 'The zone sends no Strict-Transport-Security header with a meaningful max-age, so browsers do not pin https and a later http visit can still hit the admin guard rejection.',
+        remediation: 'Turn on HSTS for the zone under SSL/TLS, Edge Certificates, with a max-age of at least six months.',
+        docsAnchor: 'cloudflare-readiness.md#turn-on-hsts',
+    },
+    'auth.store-unreachable': {
+        id: 'auth.store-unreachable',
+        severity: 'blocker',
+        title: 'Auth store is unreachable',
+        why: 'The AUTH_DB D1 database is missing, lacks the auth schema, or holds no owner row, so no magic-link token can be minted and nobody can sign in.',
+        remediation: 'Create the database, apply the auth schema with `wrangler d1 execute <db> --remote --file ./migrations/0000_auth.sql`, seed the owner row, and check the AUTH_DB binding id in wrangler.jsonc.',
+        docsAnchor: 'cloudflare-readiness.md#provision-the-auth-store',
+    },
+    'github.app-unreachable': {
+        id: 'github.app-unreachable',
+        severity: 'blocker',
+        title: 'GitHub App is unreachable',
+        why: 'The App key fails to parse, the App fails to authenticate, the installation token fails to mint, or the repository refuses a read, so saves and publishes cannot commit.',
+        remediation: 'Check GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, and GITHUB_APP_PRIVATE_KEY_B64 against the App settings, and confirm the App is installed on the repository.',
+        docsAnchor: 'cloudflare-readiness.md#install-the-github-app',
+        logEvent: 'github.unreachable',
+    },
 };
+// The registry is shared identity, never working state; freeze every entry and the map itself.
+for (const entry of Object.values(REGISTRY))
+    Object.freeze(entry);
+Object.freeze(REGISTRY);
 /** Resolve a condition by id. Throws on an unknown id, since ids are compile-time constants. */
 export function condition(id) {
     const found = REGISTRY[id];

package/dist/doctor/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/doctor/bin.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// cairn-doctor: the environment preflight. A thin shell over index.ts (where the unit tests
+// reach the logic): parse the flags, assemble the context with the real fetch and filesystem,
+// run the default registry plus the opt-in live send, print the report. Bad flags go to
+// stderr with exit 2; a failed check exits 1; a clean or all-skip run exits 0. The codes go
+// through process.exitCode, never process.exit, so a piped stdout flushes the whole report
+// before the process ends.
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { liveSendCheck } from './check-send.js';
+import { contextFromEnv, defaultChecks, formatReport, parseArgs, runDoctor } from './index.js';
+async function main() {
+    let args;
+    try {
+        args = parseArgs(process.argv.slice(2));
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 2;
+        return;
+    }
+    const cwd = process.cwd();
+    const ctx = {
+        ...contextFromEnv(process.env, args, cwd),
+        fetch: globalThis.fetch,
+        readFile: async (relPath) => {
+            try {
+                return await readFile(resolve(cwd, relPath), 'utf8');
+            }
+            catch (err) {
+                if (err.code === 'ENOENT')
+                    return null;
+                throw err;
+            }
+        },
+    };
+    const checks = defaultChecks();
+    if (args.sendTest)
+        checks.push(liveSendCheck(args.sendTest));
+    const { results, failed } = await runDoctor(checks, ctx);
+    console.log(formatReport(results));
+    process.exitCode = failed > 0 ? 1 : 0;
+}
+await main();

package/dist/doctor/check-send.d.ts

@@ -0,0 +1,3 @@
+import type { DoctorCheck } from './types.js';
+/** Build the live-send check for one recipient address. */
+export declare function liveSendCheck(to: string): DoctorCheck;