@the-smithy/create-hearth-site 0.24.1 → 0.26.0

package/README.md

@@ -39,7 +39,8 @@ cd acme-website
 ```
 
 Add an API key to `.env.local` (Hearth → the site → API & webhooks → API keys), and run `pnpm dev`. The
-new site's README walks through the first run, previews, deploying and troubleshooting.
+new site's README walks through the first run, previews and troubleshooting. Its `HOSTING.md` covers deploying to
+Netlify or Vercel, and its `AGENTS.md` holds the instructions for coding agents.
 
 ## Documentation
 

package/bin/create-hearth-site.js

@@ -19,7 +19,7 @@ const self = JSON.parse(await readFile(path.join(here, "..", "package.json"), "u
 
 /** Files that exist in the template folder during development but never belong in a new site. */
 // The template's lockfile is the Hearth workspace's (the SDK as a workspace link); a new site makes its own.
-const SKIP = new Set(["node_modules", ".next", ".netlify", ".env.local", "next-env.d.ts", "tsconfig.tsbuildinfo", "pnpm-lock.yaml"]);
+const SKIP = new Set(["node_modules", ".next", ".netlify", ".vercel", ".env.local", "next-env.d.ts", "tsconfig.tsbuildinfo", "pnpm-lock.yaml"]);
 /** Dotfiles npm won't publish (or that would confuse the monorepo) are stored with a leading underscore. */
 const RENAMES = { _gitignore: ".gitignore", "_pnpm-workspace.yaml": "pnpm-workspace.yaml" };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/create-hearth-site",
-  "version": "0.24.1",
+  "version": "0.26.0",
   "description": "Start a new client website powered by Hearth: pnpm create @the-smithy/hearth-site",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -21,6 +21,7 @@
     "!template/node_modules",
     "!template/.next",
     "!template/.netlify",
+    "!template/.vercel",
     "!template/.env.local",
     "!template/next-env.d.ts",
     "!template/tsconfig.tsbuildinfo",
@@ -29,9 +30,9 @@
   ],
   "devDependencies": {
     "vitest": "^5.0.3",
-    "@the-smithy/hearth-schema": "^0.24.1"
+    "@the-smithy/hearth-schema": "^0.26.0"
   },
   "scripts": {
-    "test": "node --test \"test/**/*.test.js\" && vitest run test/blocks.test.ts"
+    "test": "node --test \"test/**/*.test.js\" && vitest run test/blocks.test.ts test/overrides.test.ts"
   }
 }

package/template/AGENTS.md

@@ -1,13 +1,195 @@
 # Notes for coding agents
 
-Read `CLAUDE.md` in this folder: it holds this project's instructions for every AI coding assistant, then `SITE.md`
-for notes about this site.
+This is a client website whose content comes from Hearth, The Smithy's headless CMS. This file is Hearth's and is
+replaced by `pnpm hearth:update`: notes about this particular site go in `SITE.md`, which you should read too.
+`CLAUDE.md` and `GEMINI.md` only point here, for the assistants that look for those names.
 
-In short: Hearth's code (`src/hearth/`, and the files `src/hearth/manifest.json` lists) is shared by every site and
-replaced by `pnpm hearth:update`, so never edit it. A site is styled in `src/theme/`: tokens in `theme.css`, and the
-Tailwind classes of each element's slot in `index.ts` (every slot and its default is in
-`src/hearth/theme/defaults.ts`).
+## How this site is built: Hearth's code, the site's styling
 
-In a new checkout, run `pnpm hearth:check`, then `pnpm hearth:docs`. The latter also installs the skills Hearth
-offers this site in `.claude/skills/`. Read the `SKILL.md` of any that fits your task and follow it (see "Skills" in
-`CLAUDE.md`).
+Everything that works with Hearth is already here, and it's the same in every site Hearth runs: every block type,
+the event, fundraiser and donation pages, forms (contact, volunteer sign-up, registration, donations), the
+header and phone menu, the footer, previews, SEO, analytics, redirects and the sitemap. **A site is built by styling
+it, not by writing code.** It has two parts:
+
+| Folder         | Whose      | What's in it                                                                                   |
+| -------------- | ---------- | ---------------------------------------------------------------------------------------------- |
+| `src/hearth/`  | Hearth's   | All the components and pages, and the theme's slots and defaults. **Never edit it.**            |
+| `src/theme/`   | The site's | Its look: tokens, slot classes, fonts, wording, custom blocks. **All design work goes here.**   |
+
+`src/app/` holds one-line route files that point at `src/hearth/pages/`; they're Hearth's too (see
+`src/hearth/manifest.json` for every file Hearth manages). Pages the site needs that Hearth doesn't serve can be
+added in `src/app/` as the site's own.
+
+`pnpm hearth:update` brings in a new release of Hearth's code: it replaces the managed files and leaves `src/theme`
+and the site's own files alone. That's how every site gets new blocks and fixes at once, so an edit to a managed file
+is lost at the next update, and stops the update (it refuses to overwrite uncommitted changes there).
+
+## Styling a site
+
+Work in this order, and stop at the first step that gets the result:
+
+1. **Tokens** in `src/theme/theme.css`: colors, fonts, content width. Every slot uses these names (`bg-accent`,
+   `text-highlight`, `bg-muted`, `border-field`…), so most of a brand is set here. Hearth's tones (default, muted,
+   inverse, accent) map onto them.
+2. **Fonts** in `src/theme/fonts.ts` (next/font), used from the tokens.
+3. **Slots** in `src/theme/index.ts`. Every element Hearth's code draws takes its Tailwind classes from one slot.
+   `src/hearth/theme/defaults.ts` lists every part (`hero`, `cardGrid`, `header`, `form`, `event`…), every slot
+   and its default classes: read it before styling. Set only the slots the design changes:
+
+   ```ts
+   export const theme = defineTheme({
+     hero: { title: "font-display text-7xl uppercase", inner: (base) => `${base} text-center` },
+     button: { primary: "inline-block bg-accent px-6 py-3 font-mono uppercase text-accent-ink hover:bg-ink" },
+     stats: { tone: "accent" },
+   });
+   ```
+
+   - A string **replaces** the slot's default; a function **extends** it (`(base) => …`). Replace when you change a
+     property the default already sets (a radius, a size), since two classes for the same property don't reliably
+     resolve in the order written.
+   - Each slot styles one element, so slots never fight. States are attributes on the element, so they're plain
+     Tailwind variants in the slot: `on-dark:` (on an inverse or accent ground), `data-[size=full]:`,
+     `data-highlight:`, `aria-invalid:`, `aria-[current=page]:`, `has-checked:`, `in-data-[…]:` and others; the top
+     of `defaults.ts` lists them and each slot's comment says which apply.
+   - Slots named `tone` pick a block's ground (default, muted, inverse or accent). `text` holds the words the code
+     shows ("Get directions", "Register"…), with `{name}` for what the code fills in. `map.style` is the map's MapLibre
+     style; `emberForm` shapes Ember forms. A few slots in `page` are settings: `themeColor` (the browser's color around
+     the page), `externalLinks` ("new-tab"), `navMatch` ("exact" for menu links) and `dateStyle` ("long" for event dates).
+   - Icons and marks drawn with CSS (`before:content-['✓']`, the FAQ's `+`, link arrows) live in slots too. A card's
+     Icon in Hearth arrives as `data-icon="graduation-cap"`, for the site's CSS to draw.
+4. **Site CSS** under the tokens in `theme.css`: keyframes, background patterns, `@utility` classes your slots use,
+   and rules for Hearth's rich text (`.prose`), a block (`[data-block="hero"]`), a page the code serves
+   (`[data-page="events"]`, so the same blocks elsewhere stay as they are) or one card (`[data-card="our-history"]`, from
+   its title).
+5. **A page in Hearth** for words the code draws on its own pages: see "Pages at the code's addresses" below.
+6. **Overrides**, last: `src/theme/overrides.tsx` (see "Overrides" below). An override is the site's own code: updates
+   don't reach it, so it falls behind Hearth. Use one only when everything above can't get there, build it from
+   `src/hearth/ui.tsx` and the theme, and say why in `SITE.md`.
+
+Never copy a component out of `src/hearth/` to restyle it. If a design needs a slot or an option Hearth doesn't have,
+say so: it belongs in Hearth's template for every site (tell the developer to raise it with The Smithy), and an
+override can bridge the gap meanwhile.
+
+### Pages at the code's addresses
+
+`/events`, `/fundraisers`, `/donate`, `/donate/thank-you`, `/registered` and the 404 are served by Hearth's code, with
+default words. A published page in Hearth at that address (`events`, `donate/thank-you`, `not-found` for the 404…)
+replaces those words: its blocks, its SEO and its structured data. **So a page's text never needs its own route or an
+override: make the page in Hearth.** `/events` and the fundraiser and donation addresses still need the site's Events
+or Giving feature. The site's `reserved_slugs` in Hearth mustn't list these, since that refuses the page.
+
+The thank-you pages and the 404 are never indexable and never in the sitemap or llms.txt. The 404 always answers 404,
+never serves at `/not-found`, and redirects run before it.
+
+### Overrides
+
+Everything is optional. A site's file only exports what it uses, and an update never replaces it. They can import
+Hearth's components, `Blocks` too. The types are in `src/hearth/overrides.ts`. They're used everywhere the template draws
+these things:
+
+| Export | Replaces | Given |
+| --- | --- | --- |
+| `blocks` | A whole block's component, by type | `{ block }`. An anchor from Hearth keeps working around it |
+| `Logo` | The logo in the header, and in the footer once the `footer.logo` slot has classes | `{ site, place }` |
+| `Footer` | The footer | `{ site }` |
+| `EventPage` | An event's page, at `/events/…` and in collections, so a site needs no route of its own | `{ event }` |
+| `FundraiserPage` | A fundraiser's page | `{ fundraiser }` |
+| `EventCard`, `FundraiserCard` | The cards in lists; each draws an `<li>`, and may be async | `{ event }` or `{ fundraiser }`, and `heading`: `"h2"` or `"h3"`, for its title |
+| `DonateForm` | The donation form | The amounts, `fundraiser`, `fundraisers` (active ones to choose from) and `submitLabel` |
+
+`EventPage` and `FundraiserPage` have their structured data drawn around them. To build on Hearth's: `EventContent`,
+`EventRegisterSection` and `EventVolunteerSection` from `components/EventView.tsx`, `FundraiserContent` from
+`components/FundraiserView.tsx`. A site's own routes are for pages Hearth has no address for, not for an event's or
+a fundraiser's page.
+
+`own` in the manifest (managed files `pnpm hearth:update` leaves alone) is for a site inside an app, with its own root
+layout, not for keeping a page: it stops that file getting fixes. Such a site imports `src/hearth/hearth.css` alone in
+its own CSS, and `src/hearth/base.css` if it wants Hearth's rich text and focus rings.
+
+**Custom blocks** (Settings → Custom blocks in Hearth) are the one place a site writes components: in
+`src/theme/custom-blocks.tsx`, built from `src/hearth/ui.tsx` so they take the theme.
+
+## Staying on the template and up to date
+
+Every site Hearth runs has the same code, so a fix or a new block reaches them all at once. That only holds while
+each site stays on the template and on current releases:
+
+- **Check for new releases from The Smithy at the start of every piece of work.** `pnpm hearth:check` lists every
+  `@the-smithy/*` package and Hearth's code in this site with a newer release on npm, even with no API key. Tell the
+  developer what it found.
+- **Update before you build on old code.** `pnpm hearth:update` brings Hearth's code and SDK to the latest release;
+  `pnpm add @the-smithy/<name>@latest` does any other Smithy package, such as the Ember SDK. Read the package's
+  `CHANGELOG.md`, run the checks below, look at the site, and commit the update on its own, with
+  `pnpm-workspace.yaml` if pnpm added the new versions to it.
+- **Don't drift.** A design change goes in `src/theme/`. Don't copy a component out of `src/hearth/`, replace a route
+  file, or write a site's own data layer, SEO or forms. A bug or a gap in Hearth's code gets fixed in Hearth's
+  template and reaches the site by an update; say so to the developer, and if it can't wait, bridge it with an override
+  and note it in `SITE.md`.
+- **After an update, look through `SITE.md`'s overrides** and compare each with the component it replaced in
+  `src/hearth/blocks`, since updates don't reach them. Delete any that the theme can now do.
+
+## First steps in a new checkout
+
+Do these before writing code, and tell the developer what you found:
+
+1. **Check the setup:** `pnpm hearth:check`. It reports any newer releases from The Smithy (see above), reads
+   `.env.local`, connects to Hearth, lists the published pages and the block types they use, and flags types with no
+   component. It never prints the API key; you shouldn't either, so don't open `.env.local` to read the key or echo
+   it. If it fails, its message says what to fix (missing key, wrong `HEARTH_SITE`, revoked key). Ask the developer to
+   fix `.env.local`; don't guess values.
+2. **Get the full reference:** `pnpm hearth:docs` saves Hearth's API guide (every block and its fields, events,
+   forms, previews, SEO) to `hearth-api.md`. Read the parts you need from it, and from
+   `node_modules/@the-smithy/hearth/llms.md` for the SDK. It also installs any skills Hearth offers this site (see
+   "Skills" below), so run it again when they're missing. These aren't committed, so some assistants' search skips
+   them: open them by their exact path, or from the terminal if your tool won't.
+3. **"Nothing is published"** means every page is a 404 until editors publish in Hearth. That's not a code
+   problem: say so, and don't add placeholder content to work around it.
+4. **Then style the site** as above, checking with `pnpm dev` against the published pages, on a phone width too.
+
+## Skills
+
+`pnpm hearth:docs` installs the skills Hearth offers this site (which ones depends on the site) in `.agents/skills/`
+and, as the same copies, in `.claude/skills/`, since Claude Code only reads that one. Each `SKILL.md` says what it's
+for and when to use it. If your assistant doesn't load them by itself, read the ones that fit the task and follow them.
+Use them for that work, design work in particular, rather than starting from scratch. They aren't committed (a
+`.gitignore` in each folder lists them), so a fresh checkout gets them by running `pnpm hearth:docs`; never edit them,
+because the next run replaces them.
+
+## Hosting
+
+The site runs on Netlify or Vercel with no code changes: `HOSTING.md` has the steps and the settings for each. Don't
+add code for one host, or an image optimizer; if a host seems to need one, say so to the developer.
+
+## Rules
+
+- **Content comes from Hearth.** Don't hard-code page text, menus, contact details or SEO tags. They're edited
+  in Hearth and arrive through `src/hearth/client.ts`. The site's code owns design only.
+- **The API key is secret.** Only import `@/hearth/client` from server components, route handlers and server
+  actions. Never from a `"use client"` file.
+- **Use `hearthNext.*` for reads.** It caches and tags requests so the publish webhook can refresh them.
+  Calling `hearth.*` directly skips the cache.
+- **Keep every option working.** Blocks have tones, image positions, sizes and optional fields; check a restyle
+  with each, on light and dark grounds, and check text contrast on every ground (form field borders need 3:1).
+- **No bundled content.** Every page comes from Hearth; an address with no published page is a 404. Don't add
+  fallback or sample content to the code.
+- **Previews, analytics and forms come from Hearth's code.** Don't build a preview banner, add Google Analytics or
+  other trackers (Hearth's analytics is cookieless; marketing tags need a consent banner and are a separate, opt-in
+  feature), or post forms anywhere else. Use `track("name")` from `@the-smithy/hearth/analytics` in the site's own
+  code for meaningful actions.
+
+## Checks
+
+`pnpm typecheck` and `pnpm build`. The build needs the `.env.local` keys, because it reads content from Hearth.
+`pnpm hearth:check` shows any block type the published content uses without a component (run `pnpm hearth:update`).
+After `pnpm hearth:update`: `pnpm install`, then the checks; a type error in `src/theme/index.ts` means a slot was
+renamed or removed (see `defaults.ts`).
+
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->

package/template/CLAUDE.md

@@ -1,125 +1,3 @@
-# Notes for Claude
+The instructions for coding agents in this project are in `AGENTS.md`:
 
-This is a client website whose content comes from Hearth, The Smithy's headless CMS. This file is Hearth's and is
-replaced by `pnpm hearth:update`: notes about this particular site go in `SITE.md`, which you should read too.
-
-## How this site is built: Hearth's code, the site's styling
-
-Everything that works with Hearth is already here, and it's the same in every site Hearth runs: every block type,
-the event, fundraiser and donation pages, forms (contact, volunteer sign-up, registration, donations), the
-header and phone menu, the footer, previews, SEO, analytics, redirects and the sitemap. **A site is built by styling
-it, not by writing code.** It has two parts:
-
-| Folder         | Whose      | What's in it                                                                                   |
-| -------------- | ---------- | ---------------------------------------------------------------------------------------------- |
-| `src/hearth/`  | Hearth's   | All the components and pages, and the theme's slots and defaults. **Never edit it.**            |
-| `src/theme/`   | The site's | Its look: tokens, slot classes, fonts, wording, custom blocks. **All design work goes here.**   |
-
-`src/app/` holds one-line route files that point at `src/hearth/pages/`; they're Hearth's too (see
-`src/hearth/manifest.json` for every file Hearth manages). Pages the site needs that Hearth doesn't serve can be
-added in `src/app/` as the site's own.
-
-`pnpm hearth:update` brings in a new release of Hearth's code: it replaces the managed files and leaves `src/theme`
-and the site's own files alone. That's how every site gets new blocks and fixes at once, so an edit to a managed file
-is lost at the next update, and stops the update (it refuses to overwrite uncommitted changes there).
-
-## Styling a site
-
-Work in this order, and stop at the first step that gets the result:
-
-1. **Tokens** in `src/theme/theme.css`: colors, fonts, content width. Every slot uses these names (`bg-accent`,
-   `text-highlight`, `bg-muted`, `border-field`…), so most of a brand is set here. Hearth's tones (default, muted,
-   inverse, accent) map onto them.
-2. **Fonts** in `src/theme/fonts.ts` (next/font), used from the tokens.
-3. **Slots** in `src/theme/index.ts`. Every element Hearth's code draws takes its Tailwind classes from one slot.
-   `src/hearth/theme/defaults.ts` lists every part (`hero`, `cardGrid`, `header`, `form`, `event`…), every slot
-   and its default classes: read it before styling. Set only the slots the design changes:
-
-   ```ts
-   export const theme = defineTheme({
-     hero: { title: "font-display text-7xl uppercase", inner: (base) => `${base} text-center` },
-     button: { primary: "inline-block bg-accent px-6 py-3 font-mono uppercase text-accent-ink hover:bg-ink" },
-     stats: { tone: "accent" },
-   });
-   ```
-
-   - A string **replaces** the slot's default; a function **extends** it (`(base) => …`). Replace when you change a
-     property the default already sets (a radius, a size), since two classes for the same property don't reliably
-     resolve in the order written.
-   - Each slot styles one element, so slots never fight. States are attributes on the element, so they're plain
-     Tailwind variants in the slot: `on-dark:` (on an inverse or accent ground), `data-[size=full]:`,
-     `data-highlight:`, `aria-invalid:`, `aria-[current=page]:`, `has-checked:`, `in-data-[…]:` and others; the top
-     of `defaults.ts` lists them and each slot's comment says which apply.
-   - Slots named `tone` pick a block's ground (default, muted, inverse or accent). `text` holds the words the code
-     shows ("Get directions", "Register"…). `map.style` is the map's MapLibre style; `emberForm` shapes Ember forms.
-   - Icons and marks drawn with CSS (`before:content-['✓']`, the FAQ's `+`, link arrows) live in slots too.
-4. **Site CSS** under the tokens in `theme.css`: keyframes, background patterns, `@utility` classes your slots use,
-   and rules for Hearth's rich text (`.prose`) or a block (`[data-block="hero"]`).
-5. **Overrides**, last: `src/theme/overrides.tsx` can replace a whole block's component or draw the header's logo.
-   An override is the site's own code: updates don't reach it, so it falls behind Hearth. Use one only when slots,
-   tokens and CSS can't get there, build it from `src/hearth/ui.tsx` and the theme, and say why in `SITE.md`.
-
-Never copy a component out of `src/hearth/` to restyle it. If a design needs a slot or an option Hearth doesn't have,
-say so: it belongs in Hearth's template for every site (tell the developer to raise it with The Smithy), and an
-override can bridge the gap meanwhile.
-
-**Custom blocks** (Settings → Custom blocks in Hearth) are the one place a site writes components: in
-`src/theme/custom-blocks.tsx`, built from `src/hearth/ui.tsx` so they take the theme.
-
-## First steps in a new checkout
-
-Do these before writing code, and tell the developer what you found:
-
-1. **Check the setup:** `pnpm hearth:check`. It reads `.env.local`, connects to Hearth, lists the published
-   pages and the block types they use, and flags types with no component. It never prints the API key; you
-   shouldn't either, so don't open `.env.local` to read the key or echo it. If it fails, its message says what to
-   fix (missing key, wrong `HEARTH_SITE`, revoked key). Ask the developer to fix `.env.local`; don't guess values.
-2. **Get the full reference:** `pnpm hearth:docs` saves Hearth's API guide (every block and its fields, events,
-   forms, previews, SEO) to `hearth-api.md`. Read the parts you need from it, and from
-   `node_modules/@the-smithy/hearth/llms.md` for the SDK. It also installs any skills Hearth offers this site in
-   `.claude/skills/` (see "Skills" below), so run it again when they're missing.
-3. **"Nothing is published"** means every page is a 404 until editors publish in Hearth. That's not a code
-   problem: say so, and don't add placeholder content to work around it.
-4. **Then style the site** as above, checking with `pnpm dev` against the published pages, on a phone width too.
-
-## Skills
-
-`pnpm hearth:docs` installs the skills Hearth offers this site in `.claude/skills/` (which ones depends on the
-site). Each `SKILL.md` says what it's for and when to use it. Claude Code loads them by itself; other assistants
-should read the ones that fit the task and follow them. Use them for that work, design work in particular, rather
-than starting from scratch. They aren't committed (`.claude/skills/.gitignore` lists them), so a fresh checkout gets
-them by running `pnpm hearth:docs`; never edit them, because the next run replaces them.
-
-## Rules
-
-- **Content comes from Hearth.** Don't hard-code page text, menus, contact details or SEO tags. They're edited
-  in Hearth and arrive through `src/hearth/client.ts`. The site's code owns design only.
-- **The API key is secret.** Only import `@/hearth/client` from server components, route handlers and server
-  actions. Never from a `"use client"` file.
-- **Use `hearthNext.*` for reads.** It caches and tags requests so the publish webhook can refresh them.
-  Calling `hearth.*` directly skips the cache.
-- **Keep every option working.** Blocks have tones, image positions, sizes and optional fields; check a restyle
-  with each, on light and dark grounds, and check text contrast on every ground (form field borders need 3:1).
-- **No bundled content.** Every page comes from Hearth; an address with no published page is a 404. Don't add
-  fallback or sample content to the code.
-- **Previews, analytics and forms come from Hearth's code.** Don't build a preview banner, add Google Analytics or
-  other trackers (Hearth's analytics is cookieless; marketing tags need a consent banner and are a separate, opt-in
-  feature), or post forms anywhere else. Use `track("name")` from `@the-smithy/hearth/analytics` in the site's own
-  code for meaningful actions.
-
-## Checks
-
-`pnpm typecheck` and `pnpm build`. The build needs the `.env.local` keys, because it reads content from Hearth.
-`pnpm hearth:check` shows any block type the published content uses without a component (run `pnpm hearth:update`).
-After `pnpm hearth:update`: `pnpm install`, then the checks; a type error in `src/theme/index.ts` means a slot was
-renamed or removed (see `defaults.ts`).
-
-<!-- BEGIN:nextjs-agent-rules -->
-
-# This is NOT the Next.js you know
-
-This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
-
-This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
-
-<!-- END:nextjs-agent-rules -->
+@AGENTS.md

package/template/GEMINI.md

@@ -0,0 +1,3 @@
+The instructions for coding agents in this project are in `AGENTS.md`:
+
+@./AGENTS.md

package/template/HOSTING.md

@@ -0,0 +1,88 @@
+# Hosting a Hearth site
+
+This site runs on Netlify or Vercel with no code changes. Its pages, webhook, previews and SEO use standard Next.js
+features, and images come straight from Hearth's CDN, so neither host's image optimization is used or billed. The
+sites The Smithy runs are on Netlify.
+
+This file is Hearth's and is replaced by `pnpm hearth:update`. Notes about this site's hosting go in `SITE.md`.
+
+## Setting up, on either host
+
+Do these in order: the webhook's signing secret only exists once the webhook address is saved.
+
+1. **Create a project from this repo,** with `pnpm-lock.yaml` committed. The host-specific settings are below.
+2. **Add the environment variables** before the first deploy, because the build reads content from Hearth and fails
+   without them. Never put them in `netlify.toml` or anything else in git.
+
+   | Variable | Value | Where it's needed |
+   | --- | --- | --- |
+   | `HEARTH_SITE` | The site's address in Hearth, e.g. `acme` | Production and previews |
+   | `HEARTH_API_KEY` | A key made for this host (API & webhooks → API keys), so you can revoke it alone. Mark it secret | Production and previews |
+   | `HEARTH_WEBHOOK_SECRET` | Added in step 5 | Production |
+
+3. **Deploy,** then connect your domain and choose its primary address (see "Domains").
+4. **Set the web address in Hearth** to that primary address, under **Settings → Your site → Web address**. Search
+   engines are kept out until it's set.
+5. **Connect the publish webhook.** In **API & webhooks → Webhook and preview**, set **Revalidation webhook** to
+   `https://<primary domain>/api/revalidate` and save. A **Signing secret** appears: add it as
+   `HEARTH_WEBHOOK_SECRET`, then **deploy again**. Both hosts apply a changed variable only to new deploys.
+6. **Clear the Preview address** if you set it to localhost. Empty means the live site's `/api/preview`.
+7. **Check it:** publish a small change in Hearth. It should show on the live site within a few seconds.
+
+Without the webhook, published changes still appear, but can take up to an hour.
+
+## Netlify
+
+The template's `netlify.toml` sets the build command and Node 22, and Netlify's
+[Next.js adapter](https://docs.netlify.com/build/frameworks/framework-setup-guides/nextjs/overview/) needs no other
+configuration.
+
+| Setting | Use | Why |
+| --- | --- | --- |
+| Adapter version | Don't pin it | Netlify then updates it on each build, and tests it with every Next.js release |
+| Function region | Leave on the default, Ohio (`cmh`) | It's the same AWS region as Hearth. Older sites may differ: see Cloud compute → Functions → Region (Pro and up) |
+| `NETLIFY_NEXT_SKEW_PROTECTION` | `true` | Forms use server actions. This keeps a page opened before a deploy able to submit after it |
+| Variable scopes (Pro and up) | Include Builds and Functions | The build and the running site both read Hearth |
+
+## Vercel
+
+Vercel detects Next.js and pnpm by itself, so there's no config file, and `netlify.toml` is ignored. If the site
+isn't at the top of its repo, set the project's Root Directory.
+
+| Setting | Use | Why |
+| --- | --- | --- |
+| Plan | Pro for commercial work | [Hobby is non-commercial only](https://vercel.com/docs/limits/fair-use-guidelines). Taking payment from visitors, tickets for example, counts; asking for donations doesn't. Treat a site you're paid to build as commercial |
+| `ENABLE_EXPERIMENTAL_COREPACK` | `1` | Builds with the exact pnpm version in `package.json` rather than one [picked from the lockfile](https://vercel.com/docs/package-managers) |
+| Node version | Set `"engines": { "node": "22.x" }` in `package.json` to match Netlify | [`engines` overrides the project setting](https://vercel.com/docs/functions/runtimes/node-js/node-js-versions), and the template's `>=20` names no version. Your own machine then needs Node 22 too |
+| Function region | Leave on the default, Washington, D.C. (`iad1`) | It's in the US East, near Hearth. Pages are served from the CDN, and a region further away still fetches from Hearth in the US |
+| Skew Protection | Leave on | Forms use server actions. It's [on by default](https://vercel.com/docs/skew-protection) for new projects, on Pro and up |
+| Enable access to System Environment Variables | Leave on | The site reads `VERCEL_ENV` to keep preview deployments out of search engines, and Skew Protection needs it |
+| `HEARTH_API_KEY` type | Secret | [Write-only after saving](https://vercel.com/docs/environment-variables/sensitive-environment-variables) |
+| Deployment Protection | Standard | [Protects everything except production domains](https://vercel.com/docs/deployment-protection), so the webhook and Hearth's preview must use the production domain, never a `*.vercel.app` deployment address |
+
+**Redeploying doesn't refresh content on Vercel.** The
+[Data Cache](https://vercel.com/docs/caching/runtime-cache/data-cache) that holds Hearth's responses keeps them across
+deployments, and production and previews each have their own. The webhook clears production's when something
+publishes; previews catch up within the hour. To clear it by hand, use CDN → Caches → Purge cache → All content →
+Runtime and Data Cache, but on Hobby and Pro that clears every project in the team.
+
+## Domains
+
+Add both the bare domain and `www` to the project, with the one Hearth uses as primary, so the other redirects to it.
+Hearth's web address, the webhook and the primary domain must all be the same address. Netlify and Vercel both
+recommend `www` as primary, Netlify especially when DNS is hosted elsewhere.
+
+- **Netlify:** add both under Domain management and set the primary there.
+- **Vercel:** under Settings → Domains, choose Edit on the one to redirect, then **Redirect to**.
+
+## When something's wrong
+
+| What you see | Why, and what to do |
+| --- | --- |
+| The build fails with ``Hearth: `apiKey` is required`` | The variables are missing for that deploy's environment, previews included |
+| Published changes don't show | The webhook isn't set, or `HEARTH_WEBHOOK_SECRET` doesn't match Hearth's signing secret. Deploy again after changing it |
+| The webhook gets a 401 and it isn't the secret | On Vercel, it points at a protected deployment address rather than the production domain |
+| Published changes show on production but not a preview | Expected: the webhook only reaches production |
+| A page stays stale on Netlify | Run `curl -D - -o /dev/null -H "x-nf-debug-logging: 1" <url>`. `Debug-Netlify-Cache-Tag` should list `hearth`. If it doesn't, the site's SDK is older than 0.24.1: run `pnpm hearth:update` |
+| "Preview on the website" opens the wrong place or a login | Check **Preview address** in API & webhooks. On Vercel it must be the production domain |
+| A form fails in a page opened before a deploy, and works after a reload | Skew protection is off: see the host's table above |

package/template/README.md

@@ -41,17 +41,17 @@ without touching your styling. See "Styling the site" below.
 
 ## Working with an AI coding assistant
 
-The project comes with instructions for coding agents (`CLAUDE.md`, which Claude Code reads on its own, and
-`AGENTS.md` for other assistants). Once your API key is in `.env.local`:
+The project comes with instructions for coding agents in `AGENTS.md`, which Codex, Cursor, Copilot and others read on
+their own. `CLAUDE.md` and `GEMINI.md` point Claude Code and Gemini CLI to it. Once your API key is in `.env.local`:
 
 1. **Check the connection yourself, or have the agent do it:** `pnpm hearth:check` confirms the key works and
    lists the published pages and the block types they use. It never prints the key.
 2. **Give the agent the full reference:** `pnpm hearth:docs` saves Hearth's API guide to `hearth-api.md` (not
-   committed), and installs any coding-assistant skills Hearth offers your site in `.claude/skills/`. The agent's
-   instructions already point it at both.
+   committed), and installs any coding-assistant skills Hearth offers your site in `.agents/skills/` and
+   `.claude/skills/`. The agent's instructions already point it at both.
 3. **Then tell it what to build.** Prompts that work well:
 
-   - *"Run the first steps in CLAUDE.md and tell me what's published and which blocks the site uses."*
+   - *"Run the first steps in AGENTS.md and tell me what's published and which blocks the site uses."*
    - *"Restyle the site to match the brand: colors `#1F3A5F` and `#C8A15A`, font Lora for headings. Start with
      the tokens in `src/theme/theme.css`, then the hero, card grid and media-text slots in `src/theme/index.ts`."*
    - *"Match the current website at https://example.org: compare each published page with the same page there
@@ -76,12 +76,15 @@ Keep the API key out of chat: the agent never needs to see it, only `.env.local`
   and the page's language all come from Hearth (`siteMetadata`, `generatePageMetadata`, `sitemapWith`, `robots`,
   `llmsTxtHandler`, `redirectOrNotFound`). Preview deploys
   and sites hidden in Hearth are kept out of search engines. What's still yours:
-  - Pages your own code serves (like `/events`) need their own `generateMetadata` and a place in `src/app/sitemap.ts`.
+  - `/events`, `/fundraisers`, `/donate`, `/donate/thank-you`, `/registered` and the 404 are served by Hearth's code. A page
+    in Hearth at that address (`not-found` for the 404) replaces their words, SEO and all, so make one there rather than
+    a page in code.
+  - Other pages your own code serves need their own `generateMetadata` and a place in `src/app/sitemap.ts`.
   - Use `<Img priority>` for the image at the top of a page, and keep one `<h1>` per page (the Hero block renders it).
   - Give `<Img>` the `crop` of an image that fills a frame (`crop={4 / 3}` for `aspect-[4/3] object-cover`) so it keeps
     the focal point set in Hearth's media library in view.
-  - Add both the bare domain and `www` to the site in Netlify, with the one Hearth uses as primary: Netlify then
-    redirects the other to it.
+  - Add both the bare domain and `www` to the site at your host, with the one Hearth uses as primary, so the other
+    redirects to it (see `HOSTING.md`).
 
 ### Styling the site
 
@@ -92,7 +95,7 @@ Keep the API key out of chat: the agent never needs to see it, only `.env.local`
 | `src/hearth/theme/defaults.ts` | Every slot and its default classes: read it to find the slot to change |
 | `src/theme/fonts.ts` | Web fonts (next/font) |
 | `src/theme/custom-blocks.tsx` | Components for the site's own block types (Settings → Custom blocks in Hearth) |
-| `src/theme/overrides.tsx` | Last resort: replace a whole block's component, or draw the logo |
+| `src/theme/overrides.tsx` | Last resort: replace a whole block's component, the logo, the footer, the event or fundraiser page, their cards or the donation form (see `AGENTS.md`) |
 | `SITE.md` | Notes about this site's design, for the next person or coding agent |
 
 A slot holds the classes of one element, e.g. `hero.title` or `cardGrid.card`. Set a string to replace the default,
@@ -107,7 +110,10 @@ export const theme = defineTheme({
 ```
 
 States are Tailwind variants inside the slot: `on-dark:` for blocks on an inverse or accent ground,
-`data-[size=full]:`, `aria-invalid:` and so on (listed at the top of `defaults.ts`).
+`data-[size=full]:`, `aria-invalid:` and so on (listed at the top of `defaults.ts`). Words the code shows are slots under
+`text`, and `page` holds some settings: `themeColor`, `externalLinks`, `navMatch` and `dateStyle`.
+
+Editors can name any block in Hearth ("Link to this block"), so a link such as `/#upcoming` jumps to it.
 
 ### Where things live
 
@@ -137,24 +143,11 @@ import { GlobalBlock } from "@/hearth/blocks/global";
 `hearthNext.getGlobalBlocks()` lists every global block (key, name, type, pop-up, the pages and menu items it's on,
 the resolved block); `hearthNext.getGlobalBlock(keyOrId)` gets one.
 
-## Deploying to Netlify
-
-Do these in order: the webhook's signing secret only exists once the webhook URL is saved.
-
-1. **Create the Netlify site** from this repo. `netlify.toml` already sets the build command.
-2. **Add environment variables** in Netlify: `HEARTH_SITE`, and `HEARTH_API_KEY` as a secret. Use a separate key
-   named "Netlify", so you can revoke one without breaking the other. Set them **before the first deploy**: the
-   build reads content from Hearth and fails without them. Nothing else is needed; the packages are public on npm.
-3. **Deploy**, and note the site's domain.
-4. **Set the web address in Hearth.** The site's admin sets it under **Settings → Your site → Web address**.
-   Until then, search engines are kept out.
-5. **Connect the publish webhook.** In **API & webhooks → Webhook and preview**, set **Revalidation
-   webhook** to `https://<domain>/api/revalidate` and save. A **Signing secret** appears: add it in Netlify as
-   `HEARTH_WEBHOOK_SECRET`, then **redeploy**, since Netlify only applies new variables on the next deploy.
-6. **Clear the Preview address** if you set it to localhost. Empty means the live site's `/api/preview`.
-7. **Check it:** publish a small change in Hearth. It should show on the live site within a few seconds.
+## Deploying
 
-Without the webhook, published changes still appear, but can take up to an hour.
+The site runs on Netlify or Vercel with no code changes. **`HOSTING.md` has the steps and the best settings for each.**
+Set `HEARTH_SITE` and `HEARTH_API_KEY` before the first deploy, because the build reads content from Hearth. The
+packages are public on npm, so nothing else is needed to install them.
 
 ## When something's wrong
 
@@ -162,7 +155,7 @@ Without the webhook, published changes still appear, but can take up to an hour.
 | --- | --- |
 | "Page not found" on every page | Nothing is published yet, or `HEARTH_SITE` is wrong. Publish the homepage in Hearth; check the address against Hearth's address bar |
 | Not sure what's wrong | Run `pnpm hearth:check`: it checks `.env.local` and the connection and says what to fix |
-| ``Hearth: `apiKey` is required`` (dev or build) | `HEARTH_API_KEY` is missing from `.env.local`, or from Netlify's variables |
+| ``Hearth: `apiKey` is required`` (dev or build) | `HEARTH_API_KEY` is missing from `.env.local`, or from your host's variables |
 | An `unauthorized` (401) error from Hearth | The key is mistyped, revoked, or belongs to another site. Create a new one for this site |
 | Published changes don't show locally | Hard refresh (Ctrl+Shift+R). The webhook can't reach your computer |
 | Published changes don't show live | The webhook isn't set, or `HEARTH_WEBHOOK_SECRET` doesn't match Hearth's signing secret (redeploy after changing it) |
@@ -175,7 +168,15 @@ with a Markdown version to give an AI coding assistant. The SDK also ships `node
 
 ## Updating
 
+**Check for new releases whenever you start work on the site:** `pnpm hearth:check` lists anything from The Smithy
+with a newer release, and works without an API key.
+
 `pnpm hearth:update` updates Hearth's code in the site (`src/hearth/` and the other files `src/hearth/manifest.json`
 lists) to the latest release, with the packages it needs. Your `src/theme/` and your own files aren't touched. Then
 `pnpm install`, `pnpm typecheck`, `pnpm build`, and a look at the site. New blocks arrive styled by the defaults and
-your tokens; give them slots in the theme if the design needs it.
+your tokens; give them slots in the theme if the design needs it. Update other Smithy packages, such as the Ember SDK,
+with `pnpm add @the-smithy/<name>@latest`.
+
+Keep the site on the template: design goes in `src/theme/`, and bugs or gaps in `src/hearth/` get fixed in Hearth's
+template rather than here. If a site has to bridge a gap, its override goes in `src/theme/overrides.tsx` with a note
+in `SITE.md`.

package/template/SITE.md

@@ -1,7 +1,7 @@
 # This site
 
 Notes for whoever works on this site next, people and coding agents alike: the design's intent, decisions, and
-anything unusual. Hearth's own instructions are in `CLAUDE.md` (replaced by `pnpm hearth:update`); this file is the
+anything unusual. Hearth's own instructions are in `AGENTS.md` (replaced by `pnpm hearth:update`); this file is the
 site's and stays as it is.
 
 ## Design

package/template/_gitignore

@@ -2,11 +2,12 @@ node_modules/
 /.next/
 /out/
 .netlify
+.vercel
 .DS_Store
 *.tsbuildinfo
 next-env.d.ts
 
-# Keys live here locally and in Netlify's environment variables, never in git.
+# Keys live here locally and in your host's environment variables, never in git.
 .env*
 !.env.example