Reference

One page per package export subpath. The TypeScript types in src/lib are the source of truth, and the export-coverage gate checks every page against them.

Two gates back these pages. check:reference verifies a page documents every export of its subpath. check:reference:signatures goes further for function and const-function exports: it renders each export’s real type through the TypeScript compiler and compares it against the declared ts-block signature on the page, so a signature that drifts from the code fails the build. Copy a declared signature from the real export type rather than hand-writing it. A page that deliberately summarizes a large signature (an actions record shown as Record<string, ...>, say) names itself in the ALLOWLIST at the top of scripts/check-reference-signatures.mjs, keyed ${subpath}#${name} with a reason.

Stability tiers

Every export carries exactly one stability tier, marked either inline on its own section (Stability tier: <tier> API.) or as the Stability column of a Types table row. check:reference enforces this both ways: every enumerated export must carry a tier, and a name that appears in a Types table row, a bare export heading, or a declare signature but is no longer a real export anywhere in the package fails as stale prose (scripts/reference-coverage.mjs).

• Extension API. The frozen contract: the adapter and schema constructors, the composed runtime’s read surface, the single-mount facade, and the components a site mounts directly. Breaking it after the beta freeze is a deliberate major-version event, not an everyday one.

• Scaffold API. Also frozen, but for the copied wiring a scaffolded site owns rather than a seam it imports and calls: the shape a create-cairn-site template writes into a consumer’s own route files, which the same major-version discipline covers.

• Unstable API. Importable today, with no stability promise across minor versions: it may change shape or leave the package in any release with no deprecation window. This covers the advanced per-view components and the piecewise per-route factories (the recomposition seam a site uses only when it mounts routes by hand instead of the single-mount facade), their own config, deps, and result types, and any other export whose shape is not yet committed.

• Core (@glw907/cairn-cms): the engine, the adapter and schema contract, render, and the runtime.

• SvelteKit (/sveltekit): the single-mount createCairnAdmin facade, the auth guard, and the per-route factories.

• The canonical admin mount: the two-file catch-all mount and the composer a site copies.

• Components (/components): the admin Svelte UI.

• The admin toolkit (/admin-toolkit): the field, screen-scaffold, and formatter primitives a site’s own custom /admin/ screen composes.

• Render authoring (/render): the component-authoring toolkit for a component build().

• Islands (/islands): the client runtime that mounts a site’s live components over the static fallbacks.

• Delivery (/delivery): the public read-model route loaders, the response helpers, and CairnHead.

• Delivery data (/delivery/data): the node-safe pure projections.

• Media (/media): the node-safe media surface: the config normalizer, the manifest functions, the naming and transform-URL helpers, the media: codec, and the render resolver.

• Auth store (/auth-store): the server-only editor-provisioning functions backing D1.

• Auth channel (/auth-channel): the server-only factory for a site’s own second-audience login channel, request/confirm/logout over a site-owned D1 binding.

• Auth crypto (/auth-crypto): the server-only token, hash, compare, and cookie-naming primitives for a site’s own second-audience auth flow.

• Cloudflare (/cloudflare): the server-only Turnstile verification and rate-limit wrapper for Cloudflare-native platform primitives.

• Vite (/vite): the cairnManifest() build plugin.

• Ambient types (/ambient): the one-line App.Locals.cairnEditor augmentation for a site’s app.d.ts.

• The cairn-manifest CLI: the manifest regenerate command.

• The cairn-doctor CLI: the setup preflight that checks a site’s local config, Cloudflare account, and GitHub App.

• The cairn-media-seed CLI: seeds local R2 state from a deployed site’s media library, for design iteration against vite dev with no deploy.

• The cairn-audit CLI: the design-language audit, and the norms query that answers a measured norm from the shipped manifest.

• Log events: the structured diagnostic events cairn emits, and their fields.

Two pages here are not export-keyed, since they document an internal contract rather than a package subpath:

• Content authoring syntax: the cairn: internal-link and media: asset token schemes, and the ::include fragment directive, an author types in markdown.
• Admin grammar tokens: the admin’s structural type and spacing vocabulary, the role utilities that reach it from markup, and the palette/grammar boundary a site’s own theming respects.
• Supported toolchain: the SvelteKit, Svelte, TypeScript, Vite, and Node versions the package promises against and the versions its own CI proves.