@the-smithy/create-hearth-site 0.12.0 → 0.13.1

package/README.md

@@ -7,26 +7,39 @@ site with every content block rendered, SEO, forms, live preview and the publish
 key, so it shows nothing without a Hearth account. Developer access is by invitation: request it at
 [hearth.thesmithy.io/developers](https://hearth.thesmithy.io/developers).
 
-## Getting started
+## Before you start
 
-```sh
-pnpm create @the-smithy/hearth-site my-site --site <your-site>
-cd my-site
-```
+- Node 20.9 or later, and pnpm (run `corepack enable` once if `pnpm` isn't found).
+- The site's **address** in Hearth: open the site in Hearth and copy the part after `/admin/sites/` in the
+  address bar. For `hearth.thesmithy.io/admin/sites/acme/pages` it's `acme`.
+
+## Create the site
 
-Put a Delivery API key from your site in Hearth (Settings → Developers) in `.env.local`, then:
+From the folder where you keep your projects, run:
 
 ```sh
-pnpm dev
+pnpm create @the-smithy/hearth-site@latest acme-website --site acme
 ```
 
-| Option | |
+Replace `acme-website` with the folder to create and `acme` with your site's address. Each part:
+
+| Part | What it is |
 | --- | --- |
-| `<directory>` | The folder to create |
-| `--site <slug>` | Your site's address in Hearth. You're asked for it if left out |
-| `--skip-install` | Don't run `pnpm install` |
+| `pnpm create @the-smithy/hearth-site@latest` | Runs this package. `pnpm create @the-smithy/hearth-site` is pnpm's short form of `@the-smithy/create-hearth-site`. Keep `@latest`: without it, pnpm skips releases less than a day old and quietly uses an older one |
+| `acme-website` | The folder to create, which also names the project. It must not exist yet, or must be empty |
+| `--site acme` | Your site's address in Hearth (lowercase letters, numbers and dashes). Written to `.env.local` as `HEARTH_SITE` |
+
+Leave out the folder or `--site` and you're asked for them. Add `--skip-install` to skip `pnpm install`.
+
+The command copies the starter into the new folder, writes `.env.local` with the site's address, runs
+`git init` and installs the packages. Then:
+
+```sh
+cd acme-website
+```
 
-The new site's README covers local development and deploying.
+Add an API key to `.env.local` (Hearth → the site → Settings → Developers → API keys), and run `pnpm dev`. The
+new site's README walks through the first run, previews, deploying and troubleshooting.
 
 ## Documentation
 

package/bin/create-hearth-site.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /*
- * pnpm create @the-smithy/hearth-site <directory> [--site <slug>] [--skip-install]
+ * pnpm create @the-smithy/hearth-site@latest <folder> --site <address> [--skip-install]
  *
  * Copies the template next to this file into a new directory, names it, points it at
  * the matching SDK version, and installs. No network calls besides `pnpm install`.
@@ -23,11 +23,15 @@ const SKIP = new Set(["node_modules", ".next", ".netlify", ".env.local", "next-e
 /** 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" };
 
-const usage = `Usage: pnpm create @the-smithy/hearth-site <directory> [--site <slug>] [--skip-install]
+const usage = `Usage: pnpm create @the-smithy/hearth-site@latest <folder> --site <address> [--skip-install]
 
-  <directory>      Folder to create (must be new or empty)
-  --site <slug>    The site's address in Hearth (Site settings), e.g. acme
-  --skip-install   Don't run pnpm install`;
+Example (replace both names with your own; no < > around them):
+  pnpm create @the-smithy/hearth-site@latest acme-website --site acme
+
+  <folder>          The folder to create, which also names the project (must be new or empty)
+  --site <address>  The site's address in Hearth: the part after /admin/sites/ in Hearth's
+                    address bar when you open the site, e.g. acme
+  --skip-install    Don't run pnpm install`;
 
 export function packageName(dir) {
   return (
@@ -52,8 +56,8 @@ async function main() {
   let site = values.site;
   if ((!dir || !site) && process.stdin.isTTY) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
-    dir ||= (await rl.question("Folder for the new site: ")).trim();
-    site ||= (await rl.question("Site address in Hearth (e.g. acme): ")).trim();
+    dir ||= (await rl.question("Folder to create (e.g. acme-website): ")).trim();
+    site ||= (await rl.question("Site address in Hearth, after /admin/sites/ in its address bar (e.g. acme): ")).trim();
     rl.close();
   }
   if (!dir) {
@@ -61,7 +65,7 @@ async function main() {
     process.exit(1);
   }
   if (site && !validSlug(site)) {
-    console.error(`"${site}" isn't a Hearth site address: use lowercase letters, numbers and dashes.`);
+    console.error(`"${site}" isn't a Hearth site address: use lowercase letters, numbers and dashes, as in Hearth's address bar after /admin/sites/ (e.g. acme).`);
     process.exit(1);
   }
 
@@ -107,10 +111,13 @@ Created ${pkg.name} in ${rel}.
 
 Next:
   cd ${rel}
-${installed ? "" : "  pnpm install\n"}  Add the site's API key to .env.local (Hearth → the site → Settings → Developers)
-  pnpm dev
+${installed ? "" : "  pnpm install\n"}  Add an API key to .env.local as HEARTH_API_KEY (Hearth → the site → Settings → Developers → API keys)${
+    site ? "" : "\n  Set HEARTH_SITE in .env.local to the site's address in Hearth (after /admin/sites/ in its address bar)"
+  }
+  pnpm dev, then open http://localhost:3000
 
-README.md covers deploying to Netlify and the publish webhook.`);
+Only published pages show. If every page says "Page not found", publish the homepage (address "home") in Hearth.
+README.md covers the first run, previews, deploying and troubleshooting.`);
 }
 
 // Run when executed (pnpm create runs it through a symlink), not when imported by tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/create-hearth-site",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Start a new client website powered by Hearth: pnpm create @the-smithy/hearth-site",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -29,7 +29,7 @@
   ],
   "devDependencies": {
     "vitest": "^5.0.3",
-    "@the-smithy/hearth-schema": "^0.12.0"
+    "@the-smithy/hearth-schema": "^0.13.1"
   },
   "scripts": {
     "test": "node --test \"test/**/*.test.js\" && vitest run test/blocks.test.ts"

package/template/.env.example

@@ -1,8 +1,8 @@
-# The site's address in Hearth (shown in the admin's site switcher and URLs).
+# The site's address in Hearth: the part after /admin/sites/ in Hearth's address bar, e.g. grand-eastonian.
 HEARTH_SITE=
-# A Delivery API key (Hearth → Settings → Developers). Secret: server-side only.
+# A Delivery API key: Hearth → the site → Settings → Developers → API keys. Secret: server-side only.
 HEARTH_API_KEY=
-# Signing secret for the revalidation webhook (Hearth → Settings → Developers).
+# Only once deployed: the Signing secret shown after saving the Revalidation webhook (Settings → Developers).
 HEARTH_WEBHOOK_SECRET=
 # Optional: point at a different Hearth (e.g. a staging deploy).
 # HEARTH_BASE_URL=https://hearth.thesmithy.io

package/template/AGENTS.md

@@ -0,0 +1,4 @@
+# Notes for coding agents
+
+Read `CLAUDE.md` in this folder: it holds this project's instructions for every AI coding assistant, including
+the first steps to run in a new checkout (`pnpm hearth:check`, then `pnpm hearth:docs`).

package/template/CLAUDE.md

@@ -3,6 +3,22 @@
 This is a client website whose content comes from Hearth, The Smithy's headless CMS. Read
 `node_modules/@the-smithy/hearth/llms.md` for the SDK reference before changing data fetching.
 
+## 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.
+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 build the design** in `src/app/globals.css` (tokens) and `src/components/blocks/` (one component per
+   block type), checking with `pnpm dev` against the published pages.
+
 ## Rules
 
 - **Content comes from Hearth.** Don't hard-code page text, menus, contact details or SEO tags. They're edited
@@ -25,6 +41,7 @@ This is a client website whose content comes from Hearth, The Smithy's headless
 ## Checks
 
 `pnpm typecheck` and `pnpm build`. The build needs the `.env.local` keys, because it reads content from Hearth.
+`pnpm hearth:check` after changing blocks shows any block type the published content uses without a component.
 
 <!-- BEGIN:nextjs-agent-rules -->
 

package/template/README.md

@@ -1,68 +1,127 @@
 # Website powered by Hearth
 
-A Next.js site whose content (pages, menu, footer, events and forms) is managed in
-[Hearth](https://hearth.thesmithy.io). The code decides how things look. Hearth decides what's on the page.
-
-## Setup
-
-1. **Keys.** Copy `.env.example` to `.env.local` (the setup command already did, with `HEARTH_SITE` filled
-   in) and fill it in from the site's Settings → Developers page in Hearth:
-   - `HEARTH_SITE`: the site's address
-   - `HEARTH_API_KEY`: create one under Settings → Developers
-   - `HEARTH_WEBHOOK_SECRET`: from Revalidation webhook (only needed once the site is deployed)
-2. `pnpm install`, then `pnpm dev`.
-3. **Content.** Everything on the site comes from Hearth. Create and publish the homepage there (address
-   `home`), then the other pages. Until a page is published, its address shows "Page not found".
-
-The full documentation (API, SDK, blocks) is in Hearth under **API docs**, with a Markdown version to give an
-AI coding assistant.
-
-## Developing locally
-
-- **Seeing published changes.** Content is cached, and Hearth's publish webhook can't reach your computer. After
-  publishing, do a hard refresh (Ctrl+Shift+R, or Cmd+Shift+R on a Mac): in `pnpm dev` it fetches fresh content.
-- **Previewing drafts.** In Hearth, set Settings → Developers → Preview address to
-  `http://localhost:3000/api/preview`. "Preview on the website" then opens your local site in draft mode, and
-  the page refreshes as you edit. Set it back to the live address once the site is deployed.
-
-## How it fits together
+A Next.js site whose content (pages, menu, footer, events and forms) comes from
+[Hearth](https://hearth.thesmithy.io), The Smithy's content management system. **The code decides how things
+look; Hearth decides what's on the page.** Editors change content in Hearth, and you never hard-code it here.
+
+## Before you start
+
+- **Node 20.9 or later**, and **pnpm**: run `corepack enable` once if `pnpm` isn't found.
+- **A Hearth login with access to the site**, as an Admin or Developer. The Smithy or the site's admin adds you.
+- **The site's address in Hearth.** It's the part after `/admin/sites/` in Hearth's address bar when you open
+  the site, e.g. `grand-eastonian`. The setup command already put it in `.env.local` as `HEARTH_SITE`.
+
+## First run
+
+1. **Create an API key.** In Hearth, open the site, then **Settings → Developers → API keys**, and create a key
+   (name it after where it's used, e.g. "Local"). Copy it straight away: it's only shown once.
+2. **Add it to `.env.local`** in this folder:
+
+   ```ini
+   HEARTH_SITE=grand-eastonian   # already filled in
+   HEARTH_API_KEY=hk_…           # the key you just created
+   HEARTH_WEBHOOK_SECRET=        # leave empty until you deploy
+   ```
+
+   `.env.local` is never committed. Keep the key out of the code and out of chat.
+3. **Check the connection:** `pnpm hearth:check`. It confirms the key works and lists what's published.
+   **Start the site:** `pnpm dev`, then open http://localhost:3000.
+4. **Publish something in Hearth.** The site only shows **published** content, so a site whose pages are all
+   drafts shows "Page not found" everywhere. That's expected, not a bug. Ask the site's editors to publish the
+   homepage (its address is `home`), or publish it yourself if you have edit access, then reload.
+5. **Optional: preview drafts on your machine.** In **Settings → Developers → Webhook and preview**, set
+   **Preview address** to `http://localhost:3000/api/preview`. "Preview on the website" in Hearth's editor then
+   opens your local site with drafts showing, refreshing as you edit. This applies to everyone previewing that
+   site, so clear it when you're done.
+
+## 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`:
+
+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). The agent's instructions already point it there.
+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."*
+   - *"Restyle the site to match the brand: colors `#1F3A5F` and `#C8A15A`, font Lora for headings. Start with
+     the tokens in `globals.css`, then the hero, card grid and media-text blocks."*
+   - *"Match the current website at https://example.org: compare each published page with the same page there
+     and restyle the blocks until they look alike. Content stays in Hearth."*
+   - *"The gallery block looks plain. Make it a masonry grid with a lightbox, keeping it accessible."*
+   - *"Run `pnpm hearth:check` and add a component for every block type it flags."*
+
+Keep the API key out of chat: the agent never needs to see it, only `.env.local` does. If it asks for content
+(page text, menus, contact details), the answer is to add or publish it in Hearth, not to write it into the code.
+
+## While you work
+
+- **Seeing published changes locally.** Content is cached, and Hearth's publish webhook can't reach your
+  computer. After publishing, do a hard refresh (Ctrl+Shift+R, or Cmd+Shift+R on a Mac).
+- **Making it the client's own.** Start with the brand tokens in `src/app/globals.css` (colors, font, content
+  width), then restyle the block components in `src/components/blocks/`.
+  - Every block uses semantic tones (`default`, `muted`, `inverse`, `accent`). Map them to the brand rather than
+    hard-coding colors in a block.
+  - Headings can mark words with `*asterisks*` to highlight them (see `Emphasis` in `src/components/ui.tsx`).
+  - To leave a block type out, delete its line in `src/components/blocks/index.tsx` and ask for it to be turned
+    off for the site in Hearth.
+- **SEO is already handled.** Page titles, descriptions, canonical URLs, share images and structured data all
+  come from Hearth's SEO settings. There's nothing to wire up per page.
+
+### Where things live
 
 | Where | What |
 | --- | --- |
-| `src/lib/hearth.ts` | The Hearth client. Server-side only, because the key is secret |
-| `src/app/[[...slug]]/page.tsx` | Every page in Hearth at its path (`home` is `/`) |
-| `src/app/events/` | Event list and detail pages (sites with the Events feature) |
-| `src/components/blocks/` | One component per Hearth block type. This is where the design lives |
+| `src/lib/hearth.ts` | The Hearth client. Server-side only, because the API key is secret |
+| `src/app/[[...slug]]/page.tsx` | Every page in Hearth at its address (`home` is `/`) |
+| `src/components/blocks/` | One component per Hearth block type. **This is where the design lives** |
 | `src/app/globals.css` | Brand tokens: colors, font, content width |
-| `src/app/api/revalidate/route.ts` | Hearth calls this on publish, so changes go live in seconds |
-| `src/components/RegistrationForm.tsx`, `src/app/registered/` | On-site event registration (sites with Tickets): the form on an event's page and the page paid buyers return to |
-| `src/app/fundraisers/`, `src/app/donate/` | Fundraisers and donations (sites with Giving): lists, a fundraiser's page with its donation form, a general donate page and the thank-you page |
-| `src/app/api/preview/route.ts` | Opens drafts from Hearth's "Preview on the website" button (draft mode); `/api/preview/exit` ends it |
-| `<HearthPreview />` in `src/app/layout.tsx` | The SDK's live preview: while an editor previews, the page refreshes as they edit in Hearth |
-| `src/app/sitemap.ts`, `robots.ts` | Generated from Hearth. Search engines stay out until the domain is set |
+| `src/app/events/` | Event list and detail pages (sites with Events) |
+| `src/app/fundraisers/`, `src/app/donate/` | Fundraisers and donations (sites with Giving) |
+| `src/components/RegistrationForm.tsx`, `src/app/registered/` | On-site event registration (sites with Tickets) |
+| `src/app/api/revalidate/route.ts` | Hearth calls this when something is published, so changes go live in seconds |
+| `src/app/api/preview/route.ts` | Opens drafts from Hearth's "Preview on the website"; `/api/preview/exit` ends it |
+| `<HearthPreview />` in `src/app/layout.tsx` | Refreshes the page while an editor previews and edits in Hearth |
+| `src/app/sitemap.ts`, `robots.ts` | Generated from Hearth. Search engines stay out until the site's web address is set |
 
-Page titles, descriptions, canonical URLs, share images and structured data all come from Hearth's SEO
-settings. Nothing to wire up per page.
+## Deploying to Netlify
 
-## Making it the client's own
+Do these in order: the webhook's signing secret only exists once the webhook URL is saved.
 
-- Start with the tokens in `globals.css`, then restyle the block components.
-- Headings can mark words with `*asterisks*` to highlight them (see `Emphasis` in `components/ui.tsx`).
-- Every block uses semantic tones (`default`, `muted`, `inverse`, `accent`). Map them to the brand rather than
-  hard-coding colors in a block.
-- To leave a block type out, delete its line in `components/blocks/index.tsx`, and turn it off for the site in
-  Hearth.
+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 **Settings → Developers → 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 to Netlify
+Without the webhook, published changes still appear, but can take up to an hour.
+
+## When something's wrong
+
+| What you see | Why, and what to do |
+| --- | --- |
+| "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 |
+| 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) |
+| "Preview on the website" opens the wrong place | Check **Preview address** in Settings → Developers |
 
-1. Create the Netlify site from this repo. `netlify.toml` already sets the build.
-2. Add the environment variables `HEARTH_SITE`, `HEARTH_API_KEY` and `HEARTH_WEBHOOK_SECRET`. The packages
-   come from npm, so the build needs no other credentials.
-3. In Hearth, set the site's domain, then set the webhook URL to `https://<domain>/api/revalidate`.
+## Documentation
 
-Content is cached and refreshed by the webhook on publish, with an hourly refresh as a safety net.
+The full reference (API, SDK, every block and its fields, previews, forms) is in Hearth under **API docs**,
+with a Markdown version to give an AI coding assistant. The SDK also ships `node_modules/@the-smithy/hearth/llms.md`.
 
 ## Updating the SDK
 
-`pnpm up @the-smithy/hearth`. New block types show up as typed additions. Add a component for them when the
-site needs them.
+`pnpm up @the-smithy/hearth`. New block types arrive as typed additions: add a component when the site needs one.

package/template/_gitignore

@@ -9,3 +9,6 @@ next-env.d.ts
 # Keys live here locally and in Netlify's environment variables, never in git.
 .env*
 !.env.example
+
+# Hearth's API guide, downloaded by pnpm hearth:docs for AI assistants.
+hearth-api.md

package/template/package.json

@@ -7,7 +7,9 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "hearth:check": "node scripts/hearth.mjs check",
+    "hearth:docs": "node scripts/hearth.mjs docs"
   },
   "dependencies": {
     "@the-smithy/ember": "^0.3.1",

package/template/scripts/hearth.mjs

@@ -0,0 +1,100 @@
+// Setup helpers for this site, for you or your coding agent. Both read .env.local and never print the API key.
+//   pnpm hearth:check   checks .env.local and the connection to Hearth, then lists what's published
+//   pnpm hearth:docs    saves Hearth's full API guide to hearth-api.md (not committed) for an AI assistant to read
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createHearthClient, DEFAULT_BASE_URL, isHearthError } from "@the-smithy/hearth";
+
+const command = process.argv[2];
+/** Stops with a message. Thrown rather than process.exit(), which can crash Node on Windows mid-request. */
+class Stop extends Error {}
+const fail = (message) => {
+  throw new Stop(message);
+};
+
+function readEnv() {
+  if (!existsSync(".env.local")) fail("There's no .env.local. Copy .env.example to .env.local and fill it in (see README.md → First run).");
+  const env = Object.fromEntries(
+    readFileSync(".env.local", "utf8")
+      .split(/\r?\n/)
+      .map((line) => line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*?)\s*$/))
+      .filter(Boolean)
+      .map(([, key, value]) => [key, value.replace(/^["']|["']$/g, "").replace(/\s+#.*$/, "")]),
+  );
+  if (!env.HEARTH_SITE) fail("HEARTH_SITE is empty in .env.local. It's the site's address: the part after /admin/sites/ in Hearth's address bar.");
+  if (!env.HEARTH_API_KEY) fail("HEARTH_API_KEY is empty in .env.local. Create a key in Hearth → the site → Settings → Developers → API keys.");
+  if (!env.HEARTH_API_KEY.startsWith("hk_")) fail("HEARTH_API_KEY doesn't look like a Hearth key (they start with hk_). Copy it again from Settings → Developers.");
+  return { site: env.HEARTH_SITE, apiKey: env.HEARTH_API_KEY, baseUrl: (env.HEARTH_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "") };
+}
+
+/** Block types the design has a component for (the keys of `blocks` in src/components/blocks/index.tsx). */
+function designedBlocks() {
+  const file = "src/components/blocks/index.tsx";
+  if (!existsSync(file)) return null;
+  const map = readFileSync(file, "utf8").match(/export const blocks[^{]*\{([\s\S]*?)\n\};/);
+  return map ? new Set([...map[1].matchAll(/^\s*([a-zA-Z]+):/gm)].map((m) => m[1])) : null;
+}
+
+async function check() {
+  const env = readEnv();
+  const hearth = createHearthClient(env);
+  let site;
+  try {
+    site = await hearth.site.get();
+  } catch (err) {
+    if (isHearthError(err) && err.code === "unauthorized") {
+      fail(`Hearth didn't accept the API key for "${env.site}". Check that HEARTH_SITE matches the site the key was made in, and that the key wasn't revoked.`);
+    }
+    if (isHearthError(err) && err.code === "not_found") fail(`Hearth has no site "${env.site}". Check HEARTH_SITE against Hearth's address bar.`);
+    fail(`Couldn't reach Hearth at ${env.baseUrl}: ${err instanceof Error ? err.message : err}`);
+  }
+
+  console.log(`✓ Connected to "${site.name}" (${site.slug})${site.domain ? ` · ${site.domain}` : " · no web address set yet"}`);
+  console.log(`  Features: ${site.features.join(", ") || "none"}`);
+
+  const pages = await hearth.pages.list();
+  if (!pages.length) {
+    console.log(`\n! Nothing is published yet, so every page shows "Page not found". That's expected for a new site:`);
+    console.log(`  publish the homepage (address "home") in Hearth, then run this again.`);
+    return;
+  }
+  console.log(`\n✓ ${pages.length} published page${pages.length === 1 ? "" : "s"}:`);
+  for (const p of pages.slice(0, 40)) console.log(`  ${p.path.padEnd(36)} ${p.title}`);
+  if (pages.length > 40) console.log(`  … and ${pages.length - 40} more`);
+  if (!pages.some((p) => p.slug === "home")) console.log(`\n! No published homepage (address "home"), so / shows "Page not found".`);
+
+  // Which block types the published content uses, and whether the design has a component for each.
+  const used = new Map();
+  for (const p of pages.slice(0, 60)) {
+    const page = await hearth.pages.get(p.slug);
+    for (const b of page?.blocks ?? []) used.set(b.type, (used.get(b.type) ?? 0) + 1);
+  }
+  const designed = designedBlocks();
+  console.log(`\nBlock types in published pages (how often):`);
+  for (const [type, count] of [...used].sort((a, b) => b[1] - a[1])) {
+    const missing = designed && !designed.has(type);
+    console.log(`  ${type.padEnd(22)} ${String(count).padStart(3)}${missing ? "   ✗ no component in src/components/blocks/index.tsx" : ""}`);
+  }
+  if (site.features.includes("events")) {
+    const events = await hearth.events.list({ when: "upcoming" });
+    console.log(`\n✓ ${events.length} upcoming event${events.length === 1 ? "" : "s"}`);
+  }
+  console.log(`\nReady. Run pnpm dev and open http://localhost:3000.`);
+}
+
+async function docs() {
+  const env = readEnv();
+  const res = await fetch(`${env.baseUrl}/admin/docs/api.md`, { headers: { Authorization: `Bearer ${env.apiKey}` } });
+  if (!res.ok) fail(`Hearth didn't return the API guide (${res.status}). Check the API key with pnpm hearth:check.`);
+  writeFileSync("hearth-api.md", await res.text());
+  console.log("✓ Saved Hearth's full API guide to hearth-api.md (not committed). Point your coding assistant at it.");
+}
+
+try {
+  if (command === "check") await check();
+  else if (command === "docs") await docs();
+  else fail("Usage: node scripts/hearth.mjs check | docs");
+} catch (err) {
+  if (!(err instanceof Stop)) throw err;
+  console.error(`\n✗ ${err.message}\n`);
+  process.exitCode = 1;
+}

package/template/src/components/blocks/custom.tsx

@@ -0,0 +1,20 @@
+import type { BlockOf } from "@the-smithy/hearth";
+import type { ComponentType } from "react";
+
+/**
+ * This site's own blocks (Settings → Custom blocks in Hearth), one component per block key. Hearth stores what
+ * editors enter under `values`, keyed by each field's name; images come as { src, alt } with absolute URLs, links
+ * as { label, href }, lists as arrays of items. GET /custom-blocks (`hearth.customBlocks.list()`) describes them.
+ *
+ *   "team-member": ({ values }) => <TeamMember name={values.name as string} photo={values.photo as ImageRef} />,
+ */
+const customBlocks: Record<string, ComponentType<{ values: Record<string, unknown> }>> = {};
+
+export function CustomBlock({ block }: { block: BlockOf<"custom"> }) {
+  const Component = customBlocks[block.data.block];
+  if (!Component) {
+    if (process.env.NODE_ENV !== "production") console.warn(`[hearth] No component for custom block "${block.data.block}"; add one in components/blocks/custom.tsx.`);
+    return null;
+  }
+  return <Component values={block.data.values} />;
+}

package/template/src/components/blocks/index.tsx

@@ -4,11 +4,12 @@ import { Section, SectionHeading } from "@/components/ui";
 import { CollectionList } from "./collections";
 import { CallToAction, CardGrid, Faq, Hero, MediaText, Pricing, Projects, Quote, RichText, Stats } from "./content";
 import { EventSpotlight, UpcomingEvents } from "./events";
+import { CustomBlock } from "./custom";
 import { EmberFormBlock } from "./EmberFormBlock";
 import { HearthForm } from "./Form";
 import { Donate, FundraiserGrid, FundraiserSpotlight } from "./giving";
 import { Location, Schedule } from "./info";
-import { Gallery, Logos, People, Video } from "./media";
+import { Embed, Gallery, Logos, People, Video } from "./media";
 
 function FormBlock({ block }: { block: BlockOf<"form"> }) {
   return (
@@ -44,6 +45,7 @@ export const blocks: BlockComponents = {
   quote: Quote,
   gallery: Gallery,
   video: Video,
+  embed: Embed,
   people: People,
   logos: Logos,
   location: Location,
@@ -55,6 +57,7 @@ export const blocks: BlockComponents = {
   fundraiserSpotlight: FundraiserSpotlight,
   fundraiserGrid: FundraiserGrid,
   donate: Donate,
+  custom: CustomBlock,
 };
 
 export function Blocks({ blocks: list }: { blocks: ResolvedBlock[] }) {

package/template/src/components/blocks/media.tsx

@@ -1,4 +1,5 @@
 import { videoEmbedUrl, type BlockOf } from "@the-smithy/hearth";
+import { HearthEmbed } from "@the-smithy/hearth/react";
 import { Img, Section, SectionHeading } from "@/components/ui";
 
 const columns = { "2": "sm:grid-cols-2", "3": "sm:grid-cols-2 lg:grid-cols-3", "4": "sm:grid-cols-2 lg:grid-cols-4" } as const;
@@ -46,6 +47,19 @@ export function Video({ block }: { block: BlockOf<"video"> }) {
   );
 }
 
+/** Embed code from another service, in the SDK's sandboxed frame (it can't reach the rest of the page). */
+export function Embed({ block }: { block: BlockOf<"embed"> }) {
+  const width = { narrow: "max-w-2xl", wide: "max-w-4xl", full: "" }[block.data.width];
+  return (
+    <Section>
+      <figure className={width}>
+        <HearthEmbed block={block} className="rounded-xl" />
+        {block.data.caption ? <figcaption className="mt-3 opacity-75">{block.data.caption}</figcaption> : null}
+      </figure>
+    </Section>
+  );
+}
+
 export function People({ block }: { block: BlockOf<"people"> }) {
   const d = block.data;
   return (