@the-smithy/create-hearth-site 0.19.0 → 0.21.0

package/bin/create-hearth-site.js

@@ -91,6 +91,11 @@ async function main() {
   }
   await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 
+  // Record which release Hearth's code in the site came from, for pnpm hearth:update.
+  const manifestPath = path.join(target, "src", "hearth", "manifest.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  await writeFile(manifestPath, JSON.stringify({ ...manifest, version: self.version }, null, 2) + "\n");
+
   const env = (await readFile(path.join(target, ".env.example"), "utf8")).replace(/^HEARTH_SITE=.*$/m, `HEARTH_SITE=${site ?? ""}`);
   await writeFile(path.join(target, ".env.local"), env);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/create-hearth-site",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "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.19.0"
+    "@the-smithy/hearth-schema": "^0.21.0"
   },
   "scripts": {
     "test": "node --test \"test/**/*.test.js\" && vitest run test/blocks.test.ts"

package/template/AGENTS.md

@@ -1,4 +1,13 @@
 # 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`).
+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.
+
+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`).
+
+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`).

package/template/CLAUDE.md

@@ -1,7 +1,70 @@
 # Notes for Claude
 
-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.
+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
 
@@ -13,39 +76,43 @@ Do these before writing code, and tell the developer what you found:
    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.
+   `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 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.
+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/lib/hearth.ts`. The code owns design and layout.
-- **The API key is secret.** Only import `@/lib/hearth` from server components, route handlers and server
+  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.
-- **Blocks are `{ id, type, data }`.** Each block type has one component in `src/components/blocks/`, typed
-  with `BlockOf<"type">`. Keep them working for every option the block offers: tones, image positions,
-  optional fields left empty.
-- **Styling uses the tokens in `src/app/globals.css`** (`bg-accent`, `text-highlight`, …). Tones are semantic.
-  Check text contrast on every ground.
+- **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 come from the SDK.** `<HearthPreview />` in the root layout shows drafts and refreshes as editors
-  work in Hearth. Don't build a preview banner of your own.
-- **Forms** post through `submitHearthForm` in `src/app/actions.ts`. Keep the hidden `_gotcha` field.
-- **Analytics comes from the SDK.** `<HearthAnalytics />` in the root layout counts visits for the site's Traffic
-  page in Hearth: cookieless, so no consent banner. Don't add Google Analytics or other trackers. Marketing tags
-  (ads pixels) need a consent banner and are a separate, opt-in feature. Use `track("name")` from
-  `@the-smithy/hearth/analytics` for meaningful actions (a booking, a sign-up).
+- **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` after changing blocks shows any block type the published content uses without a component.
+`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 -->
 

package/template/README.md

@@ -1,8 +1,13 @@
 # Website powered by Hearth
 
 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.
+[Hearth](https://hearth.thesmithy.io), The Smithy's content management system. **Hearth decides what's on the page;
+this site decides how it looks.** Editors change content in Hearth, and you never hard-code it here.
+
+Everything that works with Hearth (every block, the event and fundraiser pages, forms, previews, SEO) is already
+built, in `src/hearth/`, and shared by every Hearth site. **You build the site by styling it** in `src/theme/`: brand
+tokens, and Tailwind classes for each part of each block. `pnpm hearth:update` brings in new blocks and fixes later
+without touching your styling. See "Styling the site" below.
 
 ## Before you start
 
@@ -42,16 +47,17 @@ The project comes with instructions for coding agents (`CLAUDE.md`, which Claude
 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.
+   committed), and installs any coding-assistant skills Hearth offers your site in `.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."*
    - *"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."*
+     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
-     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."*
+     and restyle the blocks through the theme until they look alike. Content stays in Hearth."*
+   - *"The gallery looks plain. Make it a masonry grid using its slots in the theme, keeping it accessible."*
+   - *"Run `pnpm hearth:update`, then check every published page still looks right."*
 
 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.
@@ -60,36 +66,58 @@ Keep the API key out of chat: the agent never needs to see it, only `.env.local`
 
 - **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.
+- **Making it the client's own.** See "Styling the site" below: tokens first, then slots.
+  - Every block uses semantic tones (`default`, `muted`, `inverse`, `accent`). Map them to the brand in the tokens
+    rather than setting colors block by block.
+  - Headings can mark words with `*asterisks*` to highlight them (the `emphasis` slot, and `hero.emphasis`).
+  - To leave a block type out, ask for it to be turned off for the site in Hearth.
 - **SEO comes from Hearth.** Titles, descriptions, canonical addresses, share images, structured data, the
   sitemap, robots.txt, redirects for old addresses, Search Console verification and the page's language all come
   from Hearth (`siteMetadata`, `generatePageMetadata`, `sitemapWith`, `robots`, `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`.
   - 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.
 
+### Styling the site
+
+| Where | What |
+| --- | --- |
+| `src/theme/theme.css` | Brand tokens (colors, fonts, content width) and the site's own CSS. **Start here** |
+| `src/theme/index.ts` | The Tailwind classes of any part of any block, page, form, header or footer, by slot |
+| `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 |
+| `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,
+or a function to add to it:
+
+```ts
+export const theme = defineTheme({
+  hero: { title: "font-display text-7xl uppercase", inner: (base) => `${base} text-center` },
+  cardGrid: { card: "flex flex-col gap-3 border-2 border-ink p-6" },
+  text: { directions: "Directions" },
+});
+```
+
+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`).
+
 ### Where things live
 
 | Where | What |
 | --- | --- |
-| `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/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/hearth/` | Hearth's code: blocks, pages, forms, header and footer. Shared by every site; **don't edit it** |
+| `src/hearth/client.ts` | The Hearth client. Server-side only, because the API key is secret |
+| `src/hearth/manifest.json` | The files Hearth manages here, and the release they came from |
+| `src/app/` | Route files that point at `src/hearth/pages/`, plus any pages of the site's own |
 | `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 |
 
 ## Deploying to Netlify
@@ -128,6 +156,9 @@ Without the webhook, published changes still appear, but can take up to an hour.
 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
+## Updating
 
-`pnpm up @the-smithy/hearth`. New block types arrive as typed additions: add a component when the site needs one.
+`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.

package/template/SITE.md

@@ -0,0 +1,17 @@
+# 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
+site's and stays as it is.
+
+## Design
+
+- Brand: (colors, fonts, the look in a sentence)
+- Reference: (the design file, the client's old site, design library boards)
+
+## Overrides
+
+Components replaced in `src/theme/overrides.tsx`, and why slots, tokens and CSS couldn't do it. Check each against
+`src/hearth/blocks` after an update.
+
+- None.

package/template/package.json

@@ -9,11 +9,13 @@
     "start": "next start",
     "typecheck": "tsc --noEmit",
     "hearth:check": "node scripts/hearth.mjs check",
-    "hearth:docs": "node scripts/hearth.mjs docs"
+    "hearth:docs": "node scripts/hearth.mjs docs",
+    "hearth:update": "node scripts/hearth.mjs update"
   },
   "dependencies": {
     "@the-smithy/ember": "^0.3.1",
     "@the-smithy/hearth": "workspace:^",
+    "maplibre-gl": "^6.16.0",
     "next": "16.3.8",
     "react": "19.2.8",
     "react-dom": "19.2.8",

package/template/scripts/hearth.mjs

@@ -1,8 +1,13 @@
 // 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";
+//   pnpm hearth:docs    saves Hearth's full API guide to hearth-api.md (not committed) for an AI assistant to read,
+//                       and installs any coding-assistant skills Hearth offers this site in .claude/skills/
+//   pnpm hearth:update  updates Hearth's code in this site (src/hearth and the other files its manifest lists) to the
+//                       latest release, and the packages it needs; src/theme and your own files stay as they are
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { gunzipSync } from "node:zlib";
 
 const command = process.argv[2];
 /** Stops with a message. Thrown rather than process.exit(), which can crash Node on Windows mid-request. */
@@ -11,7 +16,10 @@ const fail = (message) => {
   throw new Stop(message);
 };
 
-function readEnv() {
+/** The SDK, loaded only by the commands that talk to Hearth (so hearth:update works before pnpm install). */
+const sdk = () => import("@the-smithy/hearth");
+
+async 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")
@@ -23,19 +31,23 @@ function readEnv() {
   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 → API & webhooks → 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 API & webhooks.");
-  return { site: env.HEARTH_SITE, apiKey: env.HEARTH_API_KEY, baseUrl: (env.HEARTH_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "") };
+  return { site: env.HEARTH_SITE, apiKey: env.HEARTH_API_KEY, baseUrl: (env.HEARTH_BASE_URL || (await sdk()).DEFAULT_BASE_URL).replace(/\/+$/, "") };
 }
 
-/** Block types the design has a component for (the keys of `blocks` in src/components/blocks/index.tsx). */
+/** Block types the site has a component for (the keys of `blocks` in src/hearth/blocks/index.tsx and src/theme/overrides.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;
+  const keys = (file) => {
+    if (!existsSync(file)) return [];
+    const map = readFileSync(file, "utf8").match(/export const blocks[^{]*\{([\s\S]*?)\n?\};/);
+    return map ? [...map[1].matchAll(/^\s*([a-zA-Z]+):/gm)].map((m) => m[1]) : [];
+  };
+  const found = [...keys("src/hearth/blocks/index.tsx"), ...keys("src/theme/overrides.tsx")];
+  return found.length ? new Set(found) : null;
 }
 
 async function check() {
-  const env = readEnv();
+  const env = await readEnv();
+  const { createHearthClient, isHearthError } = await sdk();
   const hearth = createHearthClient(env);
   let site;
   try {
@@ -72,7 +84,7 @@ async function check() {
   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" : ""}`);
+    console.log(`  ${type.padEnd(22)} ${String(count).padStart(3)}${missing ? "   ✗ no component: run pnpm hearth:update" : ""}`);
   }
   if (site.features.includes("events")) {
     const events = await hearth.events.list({ when: "upcoming" });
@@ -82,17 +94,185 @@ async function check() {
 }
 
 async function docs() {
-  const env = readEnv();
+  const env = await 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.");
+  await skills(env);
+}
+
+/**
+ * Installs the coding-assistant skills Hearth offers this site into .claude/skills/, replacing the ones it
+ * installed before. Their names are listed in .claude/skills/.gitignore, so they're never committed and the
+ * site's own skills there are left alone.
+ */
+async function skills(env) {
+  const res = await fetch(`${env.baseUrl}/admin/docs/skills.json`, { headers: { Authorization: `Bearer ${env.apiKey}` } });
+  if (!res.ok) return console.log(`  Hearth didn't return the coding-assistant skills (${res.status}); skipped them.`);
+  const { skills: offered = [] } = await res.json();
+  const dir = path.join(".claude", "skills");
+  const listFile = path.join(dir, ".gitignore");
+  const before = existsSync(listFile)
+    ? readFileSync(listFile, "utf8").split(/\r?\n/).map((l) => l.replace(/^\/|\/$/g, "")).filter((l) => l && !l.startsWith("#") && l !== ".gitignore")
+    : [];
+  const safe = (p) => /^[a-z0-9][a-z0-9-]*$/.test(p);
+  const names = offered.map((s) => s.name).filter(safe);
+  for (const name of before) if (safe(name) && !names.includes(name)) rmSync(path.join(dir, name), { recursive: true, force: true });
+  for (const skill of offered.filter((s) => safe(s.name))) {
+    rmSync(path.join(dir, skill.name), { recursive: true, force: true });
+    for (const file of skill.files) {
+      if (!file.path.split("/").every((part) => /^[A-Za-z0-9._-]+$/.test(part) && part !== "..")) continue;
+      const target = path.join(dir, skill.name, ...file.path.split("/"));
+      mkdirSync(path.dirname(target), { recursive: true });
+      writeFileSync(target, file.content);
+    }
+  }
+  if (names.length || before.length) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(listFile, ["# Installed by pnpm hearth:docs from Hearth; refreshed each run.", ".gitignore", ...names.map((n) => `/${n}/`)].join("\n") + "\n");
+  }
+  if (names.length) console.log(`✓ Installed ${names.length === 1 ? "a skill" : `${names.length} skills`} for your coding assistant in .claude/skills/: ${names.join(", ")}.`);
+}
+
+const PACKAGE = "@the-smithy/create-hearth-site";
+const MANIFEST = "src/hearth/manifest.json";
+
+/** The files in an npm package tarball (.tgz), by their path inside it ("package/…"). */
+function untar(tgz) {
+  const tar = gunzipSync(tgz);
+  const files = new Map();
+  let longName = null;
+  for (let at = 0; at + 512 <= tar.length; ) {
+    const header = tar.subarray(at, at + 512);
+    if (header.every((b) => b === 0)) break;
+    const text = (from, len) => header.subarray(from, from + len).toString("utf8").split("\0")[0];
+    const size = parseInt(text(124, 12).trim() || "0", 8);
+    const type = text(156, 1);
+    const body = tar.subarray(at + 512, at + 512 + size);
+    const name = longName ?? [text(345, 155), text(0, 100)].filter(Boolean).join("/");
+    longName = null;
+    if (type === "x") longName = body.toString("utf8").match(/\d+ path=([^\n]*)\n/)?.[1] ?? null;
+    else if (type === "0" || type === "") files.set(name, body);
+    at += 512 + Math.ceil(size / 512) * 512;
+  }
+  return files;
+}
+
+/** Every file at a manifest entry in this site (an entry ending in / is a folder), relative to the site. */
+function localFiles(entry) {
+  if (!existsSync(entry)) return [];
+  if (!entry.endsWith("/")) return [entry];
+  return readdirSync(entry, { recursive: true })
+    .map((f) => path.join(entry, String(f)).split(path.sep).join("/"))
+    .filter((f) => statSync(f).isFile());
+}
+
+const listed = (entries, file) => entries.some((e) => (e.endsWith("/") ? file.startsWith(e) : file === e));
+
+/** Is version range a lower than b? (^1.2.3 against ^1.4.0) */
+const lower = (a, b) => {
+  const v = (r) => (String(r).match(/(\d+)\.(\d+)\.(\d+)/) ?? []).slice(1).map(Number);
+  const [x, y] = [v(a), v(b)];
+  if (x.length < 3 || y.length < 3) return false;
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] < y[i];
+  return false;
+};
+
+/**
+ * Updates the code Hearth manages in this site to the latest release (or --version x.y.z): replaces the managed files
+ * listed in src/hearth/manifest.json, removes managed files the release dropped, adds seeded files that are new to
+ * it (never overwriting the site's), and raises the packages the code needs. src/theme and the site's own files
+ * aren't touched.
+ */
+async function update() {
+  const args = process.argv.slice(3);
+  const force = args.includes("--force");
+  const wanted = args.includes("--version") ? args[args.indexOf("--version") + 1] : "latest";
+  if (!wanted) fail("Give a version after --version, e.g. --version 0.21.0.");
+  if (!existsSync(MANIFEST)) fail(`There's no ${MANIFEST}, so this site predates hearth:update. Move it onto the template's structure first (see CLAUDE.md).`);
+  const old = JSON.parse(readFileSync(MANIFEST, "utf8"));
+
+  // Managed files edited here would be lost: styling belongs in src/theme.
+  const git = spawnSync("git", ["status", "--porcelain", "--", ...old.managed], { encoding: "utf8" });
+  if (git.status === 0 && git.stdout.trim() && !force) {
+    fail(`These managed files have uncommitted changes, which the update would replace:\n${git.stdout.trimEnd()}\nCommit them first (and move any styling into src/theme), or run with --force to replace them.`);
+  }
+
+  // HEARTH_UPDATE_FROM=<a create-hearth-site .tgz> tries a release before it's published.
+  const prefix = "package/template/";
+  let tarball;
+  let version;
+  if (process.env.HEARTH_UPDATE_FROM) {
+    tarball = untar(readFileSync(process.env.HEARTH_UPDATE_FROM));
+    version = JSON.parse(tarball.get("package/package.json").toString("utf8")).version;
+  } else {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE.replace("/", "%2f")}`);
+    if (!res.ok) fail(`npm didn't return ${PACKAGE} (${res.status}).`);
+    const meta = await res.json();
+    version = meta["dist-tags"]?.[wanted] ?? wanted;
+    const release = meta.versions?.[version];
+    if (!release) fail(`${PACKAGE} has no version ${wanted}.`);
+    if (version === old.version && !force) return console.log(`✓ Already on ${version}, the latest. (--force reinstalls it.)`);
+    const download = await fetch(release.dist.tarball);
+    if (!download.ok) fail(`Couldn't download ${PACKAGE}@${version} (${download.status}).`);
+    tarball = untar(Buffer.from(await download.arrayBuffer()));
+  }
+  const files = new Map([...tarball].filter(([name]) => name.startsWith(prefix)).map(([name, body]) => [name.slice(prefix.length), body]));
+  if (!files.has(MANIFEST)) fail(`${PACKAGE}@${version} has no ${MANIFEST}.`);
+  const next = JSON.parse(files.get(MANIFEST).toString("utf8"));
+
+  const changed = [];
+  // Managed files the release no longer has.
+  for (const file of old.managed.flatMap(localFiles)) {
+    if (files.has(file) || file === MANIFEST) continue;
+    rmSync(file);
+    changed.push(`- ${file}`);
+  }
+  for (const [file, body] of files) {
+    if (file === MANIFEST) continue;
+    const managed = listed(next.managed, file);
+    // Seeded files are the site's own: add only ones that are new to this release's list, and never over a file.
+    const newSeed = !managed && listed(next.seeded, file) && !listed(old.seeded ?? [], file) && !existsSync(file);
+    if (!managed && !newSeed) continue;
+    const existed = existsSync(file);
+    if (existed && readFileSync(file).equals(body)) continue;
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, body);
+    changed.push(`${existed ? "~" : "+"} ${file}`);
+  }
+  writeFileSync(MANIFEST, JSON.stringify({ ...next, version }, null, 2) + "\n");
+
+  // The packages the code needs, at least at the release's versions, and its hearth:* scripts. The site's own stay.
+  const pkg = JSON.parse(readFileSync("package.json", "utf8"));
+  const theirs = JSON.parse(files.get("package.json").toString("utf8"));
+  for (const field of ["dependencies", "devDependencies"]) {
+    for (const [name, range] of Object.entries(theirs[field] ?? {})) {
+      const want = String(range).startsWith("workspace:") ? `^${version}` : range;
+      const have = pkg.dependencies?.[name] ?? pkg.devDependencies?.[name];
+      if (have && !lower(have, want)) continue;
+      pkg[field] = { ...pkg[field], [name]: want };
+      changed.push(`~ package.json: ${name} ${have ?? "(new)"} → ${want}`);
+    }
+  }
+  for (const [name, script] of Object.entries(theirs.scripts ?? {})) {
+    if (name.startsWith("hearth:") && pkg.scripts?.[name] !== script) pkg.scripts = { ...pkg.scripts, [name]: script };
+  }
+  writeFileSync("package.json", JSON.stringify(pkg, null, 2) + "\n");
+
+  console.log(`✓ Updated Hearth's code from ${old.version} to ${version}${changed.length ? ":" : " (no files changed)."}`);
+  for (const line of changed) console.log(`  ${line}`);
+  console.log(`\nNext: pnpm install, then pnpm typecheck and pnpm build, and check the site with pnpm dev.`);
+  console.log(`  A type error in src/theme means a slot was renamed or removed: see src/hearth/theme/defaults.ts.`);
+  console.log(`  Components replaced in src/theme/overrides.tsx are the site's own: compare them with src/hearth/blocks.`);
+  console.log(`  What changed: CHANGELOG.md in ${PACKAGE}@${version}.`);
 }
 
 try {
   if (command === "check") await check();
   else if (command === "docs") await docs();
-  else fail("Usage: node scripts/hearth.mjs check | docs");
+  else if (command === "update") await update();
+  else fail("Usage: node scripts/hearth.mjs check | docs | update [--version x.y.z] [--force]");
 } catch (err) {
   if (!(err instanceof Stop)) throw err;
   console.error(`\n✗ ${err.message}\n`);