ADR 0054 — Almanac heritage theme and rich listings

Almanac is the bespoke heritage theme that renders the example site — The Royal Society of Pheasant Patissiers — as a fully realised branded publication. An example site exists to show what Cusp can produce, so it renders through a theme built for its learned-society voice. Almanac is generic enough to reuse: its name carries no site-specific meaning, and every content-type flourish degrades gracefully when the underlying field is absent.

Decision

Almanac is a bundled first-party theme with a 19th-century learned-society aesthetic: parchment and ink, an editorial serif (Newsreader), a ledger monospace (Space Mono) for dates and provenance, hairline and double rules, an engraved seal, and a pheasant-plumage palette. It is the example site's active theme. The design degrades gracefully — rank pills, rosette tallies, accession lines, and ingredient lists render only when the underlying field is present — so Almanac is a credible reusable theme rather than a one-site skin.

The page template dispatches on the collection: recipes get a provenance-and-ingredients treatment (with the attributed pheasant resolved through the reference map), pheasants a register profile with rank and rosettes, dispatches an editorial article with a drop cap and pull quote, events a date block, pages a hero landing, and everything else a prose article. Listings dispatch the same way — a ruled register, an archive card grid, or a periodical lead-and-list.

Rich listings

A listing page needs more than each document's title, slug, permalink, and publish date to render a pheasant's rank and rosettes or a recipe's style on an index. The render path threads per-item data: `listHeadersByCollection` takes an `includeData` option that hydrates each row's per-field data and SEO description, and the `DocumentLink` passed to themes carries them. The option is off by default, so the perf-sensitive header-only path — which never touches the data columns or R2 — is unchanged, and the bundled default theme ignores the extra fields.

Signing

An active theme is trusted only when its signature's key id is in the project key registry, so a bundled theme must be signed. Almanac is signed under the shared first-party key id `cusp-project-2026`. The build script accepts `--source` and `--key-id` arguments so each first-party theme can be built independently, but first-party themes are all maintainer-controlled, so a shared key is acceptable — the per-theme key isolation an earlier revision used for Almanac (`cusp-almanac-2026`) was dropped once that dedicated private key was not retained, and consolidating onto the held key keeps Almanac maintainable.

Consequences

• The example site renders as a fully realised heritage publication, which is what an example is for.
• Every deployment gains Almanac as a switchable bundled theme alongside the three existing first-party themes.
• Any theme can render per-item meta on listing pages; the change is theme-agnostic and opt-in at the query layer.
• The Dynamic Worker Loader is production-only, so themed renders cannot be exercised under local dev. Almanac is iterated through a preview harness that calls the template functions directly (`pnpm tsx scripts/preview-theme.ts`), then verified on a deployed instance.

For the theme package format, signing scheme, and how the render path loads an active theme, see ADR 0028.