@cloudhal/cli 0.3.7 → 0.3.9

package/README.md

@@ -163,7 +163,7 @@ Locally, `cloudhal studio` reads the project's SQLite (`analytics_events`), roll
 
 **From Git (Workers Builds).** With `WORKERS_CI=1`, which Cloudflare sets in [Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/), `cloudhal deploy` works from a fresh clone. It takes the names from the committed `wrangler.jsonc`, seeds the starter site when the checkout has none, keeps the secrets on the Workers and does not print the setup link. This is what the Deploy to Cloudflare button runs: see [docs/guides/deploy-button.md](../../docs/guides/deploy-button.md).
 
-**Custom domain.** `cloudhal domain set news.example.com --studio studio.example.com` records the hostnames in `cloudhal.json`; the next `cloudhal deploy` routes them to the Workers as [Cloudflare Custom Domains](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/) (the zone must be in the same Cloudflare account — Cloudflare creates the DNS record and certificate) and makes the site's one its primary hostname, so preview links use it (canonical URLs in the starter are not rendered yet). The workers.dev addresses keep working. `cloudhal domain remove` and a deploy undo it.
+**Custom domain.** `cloudhal domain set news.example.com --studio studio.example.com` records the hostnames in `cloudhal.json`; the next `cloudhal deploy` routes them to the Workers as [Cloudflare Custom Domains](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/) (the zone must be in the same Cloudflare account — Cloudflare creates the DNS record and certificate) and makes the site's one its primary hostname on the deployment. `domain set` makes it primary in the local store right away, so `cloudhal dev`, `render` and `build` write it into canonical links, the sitemap and feeds before any deploy. The workers.dev addresses keep working. `cloudhal domain remove` and a deploy undo it. `--redirect www.news.example.com` (repeatable) adds hosts that answer with a 301 to the site's domain, path and query kept: the next deploy routes them to the site Worker as Custom Domains too, so Cloudflare creates their DNS records and certificates. `cloudhal domain remove redirects` drops them.
 
 **Email (RFC-0011).** Add `"mail": { "from": "studio@example.com", "fromName": "Example Studio" }` to `cloudhal.json` and the next `cloudhal deploy` gives the admin Worker a [Cloudflare Email Service](https://developers.cloudflare.com/email-service/) `send_email` binding locked to that address. Invites can then be emailed, and staff can reset a forgotten password from the sign-in screen. Onboard the address's domain in Email Service first. Sending to any recipient needs Workers Paid (3,000 emails a month included); on Free, Email Service delivers only to verified destination addresses of your account. Locally, `cloudhal studio` prints these emails in the terminal instead of sending them.
 

package/dist/assets/starters/blog/README.md

@@ -22,7 +22,9 @@ Everything but `.gitignore`'s list. `cloudhal.json` holds the project's settings
 - `search.json.ts` — the search modal's answers (RFC-0029), where the deployment answers searches (`cloudhal dev`, the Cloudflare Site Worker). `components/SearchDialog.astro` is the modal's markup and words; Cloudhal's `/_cloudhal/search.1.js` wires it, and without it the header form opens `/search`.
 
 ## Styles (`src/styles`)
-`global.css` (imported by `layouts/Base.astro`) loads Tailwind, `fonts.css` and one file per feature from `styles/features/` (`tokens.css` with `@theme`, `prose.css`, `surfaces.css`, `motion.css`, `chrome.css`, `carousel.css` …) in cascade order. The rules are unlayered and later files override earlier ones, so keep the order; add a feature as a new file and import it from `global.css`. `source("..")` on the Tailwind import is relative to `global.css`, so that import stays there.
+`global.css` (imported by `layouts/Base.astro`) loads Tailwind, `fonts.css`, `font-fallbacks.css` and one file per feature from `styles/features/` (`tokens.css` with `@theme`, `prose.css`, `surfaces.css`, `motion.css`, `chrome.css`, `carousel.css` …) in cascade order. The rules are unlayered and later files override earlier ones, so keep the order; add a feature as a new file and import it from `global.css`. `source("..")` on the Tailwind import is relative to `global.css`, so that import stays there.
+
+Fonts are self-hosted under `public/fonts/v1/` and cached for a year (`public/_headers`): files never change under a path, so a new font set goes in `public/fonts/v2/`. Each web font in the pairing stacks (`tokens.css`) is followed by a metric-matched fallback from `font-fallbacks.css` (a system font scaled to the web font's width, ascent and descent), so the swap when the web font arrives does not move the text. That file is generated: after changing a font, run `pnpm fonts:fallbacks` in the monorepo.
 
 ## Theme settings (`src/theme.ts`)
 - `ARCHIVE_PAGE_SIZE` — posts per archive page (20).

package/dist/assets/starters/blog/package.json

@@ -14,18 +14,18 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@cloudhal/astro-renderer": "0.3.7",
-    "@cloudhal/core-ts": "0.3.7",
+    "@cloudhal/astro-renderer": "0.3.9",
+    "@cloudhal/core-ts": "0.3.9",
     "@tailwindcss/vite": "^4.3.3",
     "astro": "7.3.6",
     "better-sqlite3": "13.0.3",
     "tailwindcss": "^4.3.3",
     "@astrojs/cloudflare": "14.3.4",
-    "@cloudhal/cli": "0.3.7"
+    "@cloudhal/cli": "0.3.9"
   },
   "devDependencies": {
     "wrangler": "^4.148.0",
-    "@cloudhal/cloudflare": "0.3.7"
+    "@cloudhal/cloudflare": "0.3.9"
   },
   "trustedDependencies": [
     "better-sqlite3",

package/dist/assets/starters/blog/public/_headers

@@ -0,0 +1,5 @@
+# Font files never change under a path: a new font set gets a new directory (/fonts/v2/…).
+# Cached for a year, the browser uses them on every reload without asking the server, so the
+# text is drawn in its font from the first paint instead of swapping in later.
+/fonts/v1/*
+  Cache-Control: public, max-age=31536000, immutable

package/dist/assets/starters/blog/src/fonts.ts

@@ -4,12 +4,28 @@
  * (Turkish and other accented letters) load on demand through fonts.css's unicode ranges.
  */
 export const PAIRING_PRELOADS: Readonly<Record<string, readonly string[]>> = {
-  editorial: ["/fonts/fraunces-latin-wght-normal.woff2", "/fonts/inter-latin-wght-normal.woff2"],
-  modern: ["/fonts/space-grotesk-latin-wght-normal.woff2", "/fonts/inter-latin-wght-normal.woff2"],
-  humanist: ["/fonts/source-sans-3-latin-wght-normal.woff2"],
+  editorial: [
+    "/fonts/v1/fraunces-latin-wght-normal.woff2",
+    "/fonts/v1/inter-latin-wght-normal.woff2",
+  ],
+  modern: [
+    "/fonts/v1/space-grotesk-latin-wght-normal.woff2",
+    "/fonts/v1/inter-latin-wght-normal.woff2",
+  ],
+  humanist: ["/fonts/v1/source-sans-3-latin-wght-normal.woff2"],
   technical: [
-    "/fonts/jetbrains-mono-latin-wght-normal.woff2",
-    "/fonts/inter-latin-wght-normal.woff2",
+    "/fonts/v1/jetbrains-mono-latin-wght-normal.woff2",
+    "/fonts/v1/inter-latin-wght-normal.woff2",
   ],
-  classic: ["/fonts/source-serif-4-latin-wght-normal.woff2"],
+  classic: ["/fonts/v1/source-serif-4-latin-wght-normal.woff2"],
 };
+
+/**
+ * The same preloads as a `Link` response header. On a Cloudflare zone with Early Hints on, the
+ * edge sends it as a 103 before the page, so the fonts load while the Worker is still rendering.
+ */
+export function fontLinkHeader(hrefs: readonly string[]): string {
+  return hrefs
+    .map((h) => `<${h}>; rel=preload; as=font; type="font/woff2"; crossorigin`)
+    .join(", ");
+}

package/dist/assets/starters/blog/src/pages/[...path].astro

@@ -51,6 +51,7 @@ import {
   relatedEntries,
   termAncestors,
 } from "@cloudhal/astro-renderer/taxonomy";
+import { themeVariables } from "@cloudhal/astro-renderer/theme-settings";
 import type { ContentEntry } from "@cloudhal/core-contracts";
 /**
  * One route for the whole graph (RFC-0002 §7 order): a Page answers at its `path`; an article at
@@ -73,8 +74,10 @@ import NotFound from "../components/NotFound.astro";
 import PostTerms from "../components/PostTerms.astro";
 import RelatedPosts from "../components/RelatedPosts.astro";
 import Search from "../components/Search.astro";
+import { fontLinkHeader, PAIRING_PRELOADS } from "../fonts.ts";
 import { iconSet } from "../icons.ts";
 import Base from "../layouts/Base.astro";
+import { themeSettings } from "../settings.ts";
 import {
   ARCHIVE_PAGE_SIZE,
   blocks,
@@ -354,6 +357,10 @@ const localized = localizeHead(head, site, {
 });
 const meta = fallback || notFound ? { ...localized, robots: "noindex,follow" } : localized;
 Astro.response.headers.set("content-language", shownIn);
+// The pairing's fonts as a Link header too (Early Hints), not only as <link rel=preload> in <head>.
+const pairing = themeVariables(site, themeSettings).attributes["data-ch-type-pairing"];
+const preloads = PAIRING_PRELOADS[pairing ?? ""] ?? [];
+if (preloads.length) Astro.response.headers.set("link", fontLinkHeader(preloads));
 // The reader's notice (RFC-0033 §4): machine output until a person reviews it (or always, when
 // the site asks), a page shown in its original language, each with a link to the original.
 const original = alternates.find((a) => a.original && !a.current);

package/dist/assets/starters/blog/src/styles/features/tokens.css

@@ -55,29 +55,41 @@
   font-family: ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, monospace;
 }
 /*
- * Font pairings (RFC-0023 §2): the families come from fonts.css and load only when used. They win
+ * Font pairings (RFC-0023 §2): the families come from fonts.css and load only when used; each is
+ * followed by its metric-matched fallback (font-fallbacks.css), so the swap does not move the
+ * text. They win
  * over the older typeface setting; `system` keeps it.
  */
 [data-ch-type-pairing="editorial"] {
-  --ch-font-display: "Fraunces Variable", ui-serif, Georgia, serif;
-  --ch-font-text: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
+  --ch-font-display: "Fraunces Variable", "Fraunces Variable Fallback", ui-serif, Georgia, serif;
+  --ch-font-text: "Inter Variable", "Inter Variable Fallback", ui-sans-serif, system-ui, sans-serif;
 }
 [data-ch-type-pairing="modern"] {
-  --ch-font-display: "Space Grotesk Variable", ui-sans-serif, system-ui, sans-serif;
-  --ch-font-text: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
+  --ch-font-display:
+    "Space Grotesk Variable", "Space Grotesk Variable Fallback", ui-sans-serif, system-ui,
+    sans-serif;
+  --ch-font-text: "Inter Variable", "Inter Variable Fallback", ui-sans-serif, system-ui, sans-serif;
 }
 [data-ch-type-pairing="humanist"] {
-  --ch-font-display: "Source Sans 3 Variable", ui-sans-serif, system-ui, sans-serif;
-  --ch-font-text: "Source Sans 3 Variable", ui-sans-serif, system-ui, sans-serif;
+  --ch-font-display:
+    "Source Sans 3 Variable", "Source Sans 3 Variable Fallback", ui-sans-serif, system-ui,
+    sans-serif;
+  --ch-font-text:
+    "Source Sans 3 Variable", "Source Sans 3 Variable Fallback", ui-sans-serif, system-ui,
+    sans-serif;
 }
 [data-ch-type-pairing="technical"] {
-  --ch-font-display: "JetBrains Mono Variable", ui-monospace, monospace;
-  --ch-font-text: "Inter Variable", ui-sans-serif, system-ui, sans-serif;
-  --ch-font-code: "JetBrains Mono Variable", ui-monospace, monospace;
+  --ch-font-display:
+    "JetBrains Mono Variable", "JetBrains Mono Variable Fallback", ui-monospace, monospace;
+  --ch-font-text: "Inter Variable", "Inter Variable Fallback", ui-sans-serif, system-ui, sans-serif;
+  --ch-font-code:
+    "JetBrains Mono Variable", "JetBrains Mono Variable Fallback", ui-monospace, monospace;
 }
 [data-ch-type-pairing="classic"] {
-  --ch-font-display: "Source Serif 4 Variable", ui-serif, Georgia, serif;
-  --ch-font-text: "Source Serif 4 Variable", ui-serif, Georgia, serif;
+  --ch-font-display:
+    "Source Serif 4 Variable", "Source Serif 4 Variable Fallback", ui-serif, Georgia, serif;
+  --ch-font-text:
+    "Source Serif 4 Variable", "Source Serif 4 Variable Fallback", ui-serif, Georgia, serif;
 }
 [data-ch-type-pairing]:not([data-ch-type-pairing="system"]) .ch-body {
   font-family: var(--ch-font-text);

package/dist/assets/starters/blog/src/styles/font-fallbacks.css

@@ -0,0 +1,53 @@
+/*
+ * Generated by scripts/font-fallbacks.ts: do not edit. Metric-matched fallback faces for the
+ * pairings' web fonts (tokens.css lists each right after its web font), so the swap to the web
+ * font does not move the text.
+ */
+@font-face {
+  font-family: "Fraunces Variable Fallback";
+  src: local("Times New Roman"), local("TimesNewRomanPSMT");
+  size-adjust: 113.62%;
+  ascent-override: 86.08%;
+  descent-override: 22.44%;
+  line-gap-override: 0.00%;
+}
+@font-face {
+  font-family: "Inter Variable Fallback";
+  src: local("Arial"), local("ArialMT");
+  size-adjust: 107.12%;
+  ascent-override: 90.44%;
+  descent-override: 22.52%;
+  line-gap-override: 0.00%;
+}
+@font-face {
+  font-family: "Space Grotesk Variable Fallback";
+  src: local("Arial"), local("ArialMT");
+  size-adjust: 109.47%;
+  ascent-override: 89.89%;
+  descent-override: 26.67%;
+  line-gap-override: 0.00%;
+}
+@font-face {
+  font-family: "Source Sans 3 Variable Fallback";
+  src: local("Arial"), local("ArialMT");
+  size-adjust: 92.42%;
+  ascent-override: 110.80%;
+  descent-override: 43.28%;
+  line-gap-override: 0.00%;
+}
+@font-face {
+  font-family: "Source Serif 4 Variable Fallback";
+  src: local("Times New Roman"), local("TimesNewRomanPSMT");
+  size-adjust: 117.91%;
+  ascent-override: 87.87%;
+  descent-override: 28.41%;
+  line-gap-override: 0.00%;
+}
+@font-face {
+  font-family: "JetBrains Mono Variable Fallback";
+  src: local("Courier New"), local("CourierNewPSMT");
+  size-adjust: 99.98%;
+  ascent-override: 102.02%;
+  descent-override: 30.00%;
+  line-gap-override: 0.00%;
+}

package/dist/assets/starters/blog/src/styles/fonts.css

@@ -8,7 +8,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 900;
-  src: url(/fonts/fraunces-latin-ext-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/fraunces-latin-ext-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
@@ -17,7 +17,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 900;
-  src: url(/fonts/fraunces-latin-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/fraunces-latin-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
@@ -26,7 +26,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 900;
-  src: url(/fonts/inter-latin-ext-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/inter-latin-ext-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
@@ -35,7 +35,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 900;
-  src: url(/fonts/inter-latin-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/inter-latin-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
@@ -44,7 +44,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 800;
-  src: url(/fonts/jetbrains-mono-latin-ext-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/jetbrains-mono-latin-ext-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
@@ -53,7 +53,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 100 800;
-  src: url(/fonts/jetbrains-mono-latin-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/jetbrains-mono-latin-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
@@ -62,7 +62,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 200 900;
-  src: url(/fonts/source-sans-3-latin-ext-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/source-sans-3-latin-ext-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
@@ -71,7 +71,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 200 900;
-  src: url(/fonts/source-sans-3-latin-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/source-sans-3-latin-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
@@ -80,7 +80,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 200 900;
-  src: url(/fonts/source-serif-4-latin-ext-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/source-serif-4-latin-ext-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
@@ -89,7 +89,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 200 900;
-  src: url(/fonts/source-serif-4-latin-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/source-serif-4-latin-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }
@@ -98,7 +98,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 300 700;
-  src: url(/fonts/space-grotesk-latin-ext-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/space-grotesk-latin-ext-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
 }
@@ -107,7 +107,7 @@
   font-style: normal;
   font-display: swap;
   font-weight: 300 700;
-  src: url(/fonts/space-grotesk-latin-wght-normal.woff2) format("woff2-variations");
+  src: url(/fonts/v1/space-grotesk-latin-wght-normal.woff2) format("woff2-variations");
   unicode-range:
     U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
 }

package/dist/assets/starters/blog/src/styles/global.css

@@ -1,6 +1,7 @@
 /* Scan `src/` only: automatic detection may walk up the file system (docs/design/starter-references.md §6). */
 @import "tailwindcss" source("..");
 @import "./fonts.css";
+@import "./font-fallbacks.css";
 
 /*
  * One file per feature (docs/engineering/code-structure.md §8), in cascade order. Unlayered on

package/dist/src/cli/commands-local.js

@@ -45,6 +45,10 @@ const snapshotCommand             = async (_rest, values, { projectDir }) => {
     ...(values.label ? { label: values.label } : {}),
     ...(values.publish ? { publish: true } : {}),
   });
+  if (snap.unchanged) {
+    console.log(`nothing changed since ${snap.id} (live); no new snapshot`);
+    return 0;
+  }
   console.log(
     `${snap.id}  nodes=${snap.nodes.length}  +${snap.summary.added} ~${snap.summary.changed} -${snap.summary.removed}${values.publish ? "  (published)" : ""}`,
   );

package/dist/src/cli/commands-remote.js

@@ -60,23 +60,27 @@ const deployCommand             = async (_rest, values, { projectDir }) => {
 function changeDomain(rest          , values           , projectDir        ) {
   const [action, arg] = rest;
   if (action === "set") {
-    if (!arg && !values.studio)
-      throw new Error("usage: cloudhal domain set <hostname> [--studio <hostname>]");
+    const redirects = (values.redirect ?? []).flatMap((v) => v.split(","));
+    if (!arg && !values.studio && redirects.length === 0)
+      throw new Error(
+        "usage: cloudhal domain set <hostname> [--studio <hostname>] [--redirect <hostname>]…",
+      );
     return domain({
       projectDir,
       set: {
         ...(arg ? { site: arg } : {}),
         ...(values.studio ? { studio: values.studio } : {}),
+        ...(redirects.length > 0 ? { redirects } : {}),
       },
     });
   }
   if (action === "remove") {
     const which = arg ?? "all";
-    if (!["site", "studio", "all"].includes(which))
-      throw new Error("usage: cloudhal domain remove [site|studio|all]");
+    if (!["site", "studio", "redirects", "all"].includes(which))
+      throw new Error("usage: cloudhal domain remove [site|studio|redirects|all]");
     return domain({
       projectDir,
-      remove: which === "all" ? ["site", "studio"] : [which                ],
+      remove: which === "all" ? ["site", "studio", "redirects"] : [which                ],
     });
   }
   if (action === undefined) return domain({ projectDir });
@@ -87,7 +91,7 @@ const domainCommand             = async (rest, values, { projectDir }) => {
   const result = await changeDomain(rest, values, projectDir);
   console.log(
     result
-      ? `site:   ${result.site ? `https://${result.site}` : "(workers.dev)"}\nstudio: ${result.studio ? `https://${result.studio}` : "(workers.dev)"}`
+      ? `site:   ${result.site ? `https://${result.site}` : "(workers.dev)"}\nstudio: ${result.studio ? `https://${result.studio}` : "(workers.dev)"}${result.redirects ? `\n301:    ${result.redirects.join(", ")} → https://${result.site}` : ""}`
       : "no custom domains; the Workers answer on workers.dev",
   );
   if (rest[0])

package/dist/src/cli/help.d.ts

@@ -1,2 +1,2 @@
 /** `cloudhal --help`; every command it names has an entry in `COMMANDS` (cli.ts). */
-export declare const HELP = "cloudhal \u2014 agent-native sites\n\nUsage:\n  cloudhal init <dir> [--name <name>] [--starter blog]   create a site project with a seeded local store\n  cloudhal dev [--port <n>] [--host]                      live preview (drafts visible)\n  cloudhal snapshot [--label <text>] [--publish]          freeze the current graph (optionally publish)\n  cloudhal build [--snapshot <id>]                        static HTML from the published/latest snapshot\n  cloudhal studio [--port <n>] [--no-auth]                API + Studio UI for this project (default :8787)\n  cloudhal mcp [--mode plan|manual|edits|auto|bypass] [--scopes a,b] [--skills <dir>] [--preview-url <url>]\n                                                          MCP server over stdio for this project\n  cloudhal deploy [--name <base>] [--dry-run] [--jurisdiction eu] [--scheduler cron|alarm] [--plan free|paid]\n                  [--force-downgrade] [--no-build-studio]\n                                                          site + admin Workers on Cloudflare (uses wrangler login);\n                                                          --jurisdiction eu keeps a newly created D1 database\n                                                          in the EU (cannot be changed later); --scheduler picks\n                                                          the minute cron trigger or the Durable Object alarm;\n                                                          --plan sizes scheduler ticks for the account's Workers\n                                                          plan (default free; remembered);\n                                                          --force-downgrade deploys older schedules code over\n                                                          open releases and time gates; from the monorepo a\n                                                          stale apps/studio/dist is rebuilt first\n                                                          (--no-build-studio: fail instead)\n  cloudhal domain [set <hostname>] [--studio <hostname>] | remove [site|studio|all]\n                                                          custom domains for the next deploy\n  cloudhal push [--replace] [--cancel-schedules] [--admin-url <url>]\n                                                          local site \u2192 deployment (refused while releases are\n                                                          open unless --cancel-schedules cancels them)\n  cloudhal pull [--replace] [--admin-url <url>]           deployment \u2192 local site\n  cloudhal owner transfer --to <email> [--admin-url <url>]\n                                                          make a member the deployment's Owner\n                                                          (lockout recovery; uses the deployment token)\n  cloudhal site list | create --name <name> --slug <slug> [--locale <tag>] [--project <id>] [--theme <name>] [--from <siteId>]\n                     | delete <siteId> --confirm <slug>  [--remote] [--admin-url <url>]\n                                                          the installation's sites (RFC-0034): one Studio,\n                                                          many isolated sites; nothing is published\n  cloudhal migrate tags-to-terms [--dry-run] [--revert <id>]\n                                                          move entry tags into tag terms (RFC-0002);\n                                                          resumable; --revert <id> undoes a run\n  cloudhal media import-urls [--dry-run] [--include-markdown] [--allow-host <host>]\u2026 | --revert <id>\n                                                          copy linked images into the media library\n                                                          (RFC-0004); revertible\n  cloudhal media verify [<assetId>]                       recompute media checksums\n  cloudhal media gc [--dry-run]                           delete unreferenced media bytes (> 24 h old)\n  cloudhal media placeholders [--remote] [--all] [--dry-run]\n                                                          draw missing image placeholders in local Chrome\n  cloudhal analytics status [--remote]                    site analytics: settings, daily totals, budget\n  cloudhal analytics rollup [--days <n>] [--remote] [--redo]\n                                                          compute daily totals (--remote backfills the\n                                                          deployment from WAE, up to 92 days)\n  cloudhal analytics seed [--days <n>] [--views <n>]      demo traffic in the local SQLite only\n  cloudhal analytics export [--from <date> --to <date>] [--remote] [--out <file>]\n                                                          daily totals as CSV (default: 30 days)\n  cloudhal comments status [--remote]                     reader comments: counts, pending, daily cap, purges\n  cloudhal comments export [--remote] [--with-personal-data --out <file>]\n                                                          comments as JSON lines (stdout or --out)\n  cloudhal comments import --in <file> [--remote]         JSON lines back in; idempotent, safe to rerun\n  cloudhal schedules status [--remote]                    the scheduler's health, open releases, gated pages\n  cloudhal schedules list [--remote] [--limit <n>]        the site's releases\n  cloudhal schedules run-due [--remote]                   one scheduler tick now (self-hosting: run it from\n                                                          the system's cron every minute)\n  cloudhal ai build-eval [--remote] [--models a,b] [--briefs landing,faq] [--out <file>]\n                        [--design] [--look] [--judge <model>|none]\n                                                          compare models on Build chat's turn, in memory\n                                                          (real model calls; RFC-0020 open question 7);\n                                                          --design renders each result: failed checks and\n                                                          a vision model's score (RFC-0021 21c); --look lets\n                                                          the model see its render first, as Build chat does\n  cloudhal ai judge-check [--remote] [--judge <model>]   score the reference pages (empty \u2192 strong) with the\n                                                          design judge; fails when it does not rank them\n  cloudhal render <path|url> [--width 1440,390] [--scheme dark] [--motion static|reduce|full]\n                        [--frames <n>] [--base <url>] [--out <dir>]\n                                                          screenshots and render_page's checks for a page\n                                                          (of cloudhal dev by default; RFC-0024)\n  cloudhal motion audit [--path <p>]                      the motion each page asks for, against its budgets\n  cloudhal tokens export [--format dtcg] [--out <file>]   the site's design tokens as a W3C Design Tokens file\n                                                          (Figma, Style Dictionary; RFC-0023)\n  cloudhal chrome get [--file <f>] | set --file <f>       the site's header, footer and brand as JSON\n                                                          (RFC-0025)\n  cloudhal search reindex [--remote]                      rebuild the search index from the live snapshot\n                                                          (publishing keeps it current; for restored backups)\n  cloudhal --help\n";
+export declare const HELP = "cloudhal \u2014 agent-native sites\n\nUsage:\n  cloudhal init <dir> [--name <name>] [--starter blog]   create a site project with a seeded local store\n  cloudhal dev [--port <n>] [--host]                      live preview (drafts visible)\n  cloudhal snapshot [--label <text>] [--publish]          freeze the current graph (optionally publish)\n  cloudhal build [--snapshot <id>]                        static HTML from the published/latest snapshot\n  cloudhal studio [--port <n>] [--no-auth]                API + Studio UI for this project (default :8787)\n  cloudhal mcp [--mode plan|manual|edits|auto|bypass] [--scopes a,b] [--skills <dir>] [--preview-url <url>]\n                                                          MCP server over stdio for this project\n  cloudhal deploy [--name <base>] [--dry-run] [--jurisdiction eu] [--scheduler cron|alarm] [--plan free|paid]\n                  [--force-downgrade] [--no-build-studio]\n                                                          site + admin Workers on Cloudflare (uses wrangler login);\n                                                          --jurisdiction eu keeps a newly created D1 database\n                                                          in the EU (cannot be changed later); --scheduler picks\n                                                          the minute cron trigger or the Durable Object alarm;\n                                                          --plan sizes scheduler ticks for the account's Workers\n                                                          plan (default free; remembered);\n                                                          --force-downgrade deploys older schedules code over\n                                                          open releases and time gates; from the monorepo a\n                                                          stale apps/studio/dist is rebuilt first\n                                                          (--no-build-studio: fail instead)\n  cloudhal domain [set <hostname>] [--studio <hostname>] [--redirect <hostname>]\u2026 | remove [site|studio|redirects|all]\n                                                          custom domains for the next deploy\n  cloudhal push [--replace] [--cancel-schedules] [--admin-url <url>]\n                                                          local site \u2192 deployment (refused while releases are\n                                                          open unless --cancel-schedules cancels them)\n  cloudhal pull [--replace] [--admin-url <url>]           deployment \u2192 local site\n  cloudhal owner transfer --to <email> [--admin-url <url>]\n                                                          make a member the deployment's Owner\n                                                          (lockout recovery; uses the deployment token)\n  cloudhal site list | create --name <name> --slug <slug> [--locale <tag>] [--project <id>] [--theme <name>] [--from <siteId>]\n                     | delete <siteId> --confirm <slug>  [--remote] [--admin-url <url>]\n                                                          the installation's sites (RFC-0034): one Studio,\n                                                          many isolated sites; nothing is published\n  cloudhal migrate tags-to-terms [--dry-run] [--revert <id>]\n                                                          move entry tags into tag terms (RFC-0002);\n                                                          resumable; --revert <id> undoes a run\n  cloudhal media import-urls [--dry-run] [--include-markdown] [--allow-host <host>]\u2026 | --revert <id>\n                                                          copy linked images into the media library\n                                                          (RFC-0004); revertible\n  cloudhal media verify [<assetId>]                       recompute media checksums\n  cloudhal media gc [--dry-run]                           delete unreferenced media bytes (> 24 h old)\n  cloudhal media placeholders [--remote] [--all] [--dry-run]\n                                                          draw missing image placeholders in local Chrome\n  cloudhal analytics status [--remote]                    site analytics: settings, daily totals, budget\n  cloudhal analytics rollup [--days <n>] [--remote] [--redo]\n                                                          compute daily totals (--remote backfills the\n                                                          deployment from WAE, up to 92 days)\n  cloudhal analytics seed [--days <n>] [--views <n>]      demo traffic in the local SQLite only\n  cloudhal analytics export [--from <date> --to <date>] [--remote] [--out <file>]\n                                                          daily totals as CSV (default: 30 days)\n  cloudhal comments status [--remote]                     reader comments: counts, pending, daily cap, purges\n  cloudhal comments export [--remote] [--with-personal-data --out <file>]\n                                                          comments as JSON lines (stdout or --out)\n  cloudhal comments import --in <file> [--remote]         JSON lines back in; idempotent, safe to rerun\n  cloudhal schedules status [--remote]                    the scheduler's health, open releases, gated pages\n  cloudhal schedules list [--remote] [--limit <n>]        the site's releases\n  cloudhal schedules run-due [--remote]                   one scheduler tick now (self-hosting: run it from\n                                                          the system's cron every minute)\n  cloudhal ai build-eval [--remote] [--models a,b] [--briefs landing,faq] [--out <file>]\n                        [--design] [--look] [--judge <model>|none]\n                                                          compare models on Build chat's turn, in memory\n                                                          (real model calls; RFC-0020 open question 7);\n                                                          --design renders each result: failed checks and\n                                                          a vision model's score (RFC-0021 21c); --look lets\n                                                          the model see its render first, as Build chat does\n  cloudhal ai judge-check [--remote] [--judge <model>]   score the reference pages (empty \u2192 strong) with the\n                                                          design judge; fails when it does not rank them\n  cloudhal render <path|url> [--width 1440,390] [--scheme dark] [--motion static|reduce|full]\n                        [--frames <n>] [--base <url>] [--out <dir>]\n                                                          screenshots and render_page's checks for a page\n                                                          (of cloudhal dev by default; RFC-0024)\n  cloudhal motion audit [--path <p>]                      the motion each page asks for, against its budgets\n  cloudhal tokens export [--format dtcg] [--out <file>]   the site's design tokens as a W3C Design Tokens file\n                                                          (Figma, Style Dictionary; RFC-0023)\n  cloudhal chrome get [--file <f>] | set --file <f>       the site's header, footer and brand as JSON\n                                                          (RFC-0025)\n  cloudhal search reindex [--remote]                      rebuild the search index from the live snapshot\n                                                          (publishing keeps it current; for restored backups)\n  cloudhal --help\n";

package/dist/src/cli/help.js

@@ -21,7 +21,7 @@ Usage:
                                                           open releases and time gates; from the monorepo a
                                                           stale apps/studio/dist is rebuilt first
                                                           (--no-build-studio: fail instead)
-  cloudhal domain [set <hostname>] [--studio <hostname>] | remove [site|studio|all]
+  cloudhal domain [set <hostname>] [--studio <hostname>] [--redirect <hostname>]… | remove [site|studio|redirects|all]
                                                           custom domains for the next deploy
   cloudhal push [--replace] [--cancel-schedules] [--admin-url <url>]
                                                           local site → deployment (refused while releases are

package/dist/src/cli.d.ts

@@ -53,6 +53,10 @@ export declare const OPTIONS: {
     readonly studio: {
         readonly type: "string";
     };
+    readonly redirect: {
+        readonly type: "string";
+        readonly multiple: true;
+    };
     readonly revert: {
         readonly type: "string";
     };

package/dist/src/cli.js

@@ -26,6 +26,7 @@ export const OPTIONS = {
   replace: { type: "boolean" },
   "admin-url": { type: "string" },
   studio: { type: "string" },
+  redirect: { type: "string", multiple: true },
   revert: { type: "string" },
   to: { type: "string" },
   "include-markdown": { type: "boolean" },

package/dist/src/cloudflare/config.d.ts

@@ -102,6 +102,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
     domain?: string;
     /** RFC-0034 §5: every other site's hostnames, one Custom Domain route each. */
     domains?: readonly string[];
+    /** Hosts that answer with a 301 to `domain` (#49), each routed as a Custom Domain too. */
+    redirects?: readonly string[];
     analytics?: AnalyticsDeployment;
     comments?: CommentsDeployment;
     /** Extra hostnames the site answers on (custom domains): analytics and comments check them. */
@@ -150,6 +152,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -157,6 +161,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER: string;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT: string;
@@ -164,6 +170,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -171,6 +179,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     };
     cache: {
         enabled: boolean;
@@ -223,6 +233,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -230,6 +242,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER: string;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT: string;
@@ -237,6 +251,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -244,6 +260,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     };
     cache: {
         enabled: boolean;
@@ -296,6 +314,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -303,6 +323,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER: string;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT: string;
@@ -310,6 +332,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -317,6 +341,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     };
     cache: {
         enabled: boolean;
@@ -366,6 +392,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -373,6 +401,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER: string;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT: string;
@@ -380,6 +410,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -387,6 +419,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     };
     cache: {
         enabled: boolean;

package/dist/src/cloudflare/config.js

@@ -180,6 +180,8 @@ export function siteWorkerConfig(
                     
                                                                                    
                                 
+                                                                                              
+                                  
                                     
                                   
                                                                                                    
@@ -191,6 +193,7 @@ export function siteWorkerConfig(
   const a = n.analytics;
   const c = n.comments?.available ? n.comments : undefined;
   const hosts = [...new Set([...(n.siteHosts ?? []), ...(a?.siteHosts ?? [])])];
+  const redirects = n.domain ? (n.redirects ?? []) : [];
   const ratelimits = [
     // Optional cross-isolate beacon limit (RFC-0006 §5.5): one key per client (an HMAC, never the IP).
     ...(a?.rateLimit
@@ -237,8 +240,11 @@ export function siteWorkerConfig(
         : {}),
       // RFC-0006 §5.2 / RFC-0007 §6.2 step 2: the same-origin checks accept these hosts too.
       ...((a || c) && hosts.length > 0 ? { CLOUDHAL_SITE_HOSTS: hosts.join(",") } : {}),
+      ...(n.domain && redirects.length > 0
+        ? { CLOUDHAL_REDIRECT_HOSTS: redirects.join(","), CLOUDHAL_REDIRECT_TO: n.domain }
+        : {}),
     },
-    ...customDomain(n.domain, n.domains),
+    ...customDomain(n.domain, [...(n.domains ?? []), ...redirects]),
     // Workers Cache: published pages are cached until a publish purges `cloudhal-site-<id>`.
     cache: { enabled: true },
     observability: observabilitySettings(n.observability),

package/dist/src/commands/deploy/prepare.js

@@ -292,6 +292,7 @@ export async function buildSite(
       ...(served.siteIds ? { siteIds: served.siteIds } : {}),
       ...(served.hosts.length > 0 ? { domains: served.hosts } : {}),
       ...(cfg.domains?.site ? { domain: cfg.domains.site, siteHosts: [cfg.domains.site] } : {}),
+      ...(cfg.domains?.redirects ? { redirects: cfg.domains.redirects } : {}),
       ...(input.analytics ? { analytics: input.analytics } : {}),
       comments: input.comments,
       observability: input.observability,

package/dist/src/commands/domain.d.ts

@@ -1,11 +1,15 @@
 import { type ProjectConfig } from "../config.js";
-export type DomainTarget = "site" | "studio";
+export type DomainTarget = "site" | "studio" | "redirects";
 export interface DomainOptions {
     readonly projectDir: string;
-    /** Hostnames to set (others stay as they are). */
+    /**
+     * Hostnames to set (others stay as they are). `redirects` replaces the list of hosts that
+     * answer with a 301 to the site's domain (#49).
+     */
     readonly set?: {
         readonly site?: string;
         readonly studio?: string;
+        readonly redirects?: readonly string[];
     };
     /** Domains to forget. */
     readonly remove?: readonly DomainTarget[];

package/dist/src/commands/domain.js

@@ -2,16 +2,28 @@
  * `cloudhal domain` — the custom domains `cloudhal deploy` routes to this project's Workers
  * (Cloudflare Custom Domains: the zone must be in the same Cloudflare account; wrangler creates
  * the DNS record and certificate). Kept in cloudhal.json so the setting travels with the project.
+ * The site's own hostname also becomes its primary domain in the local store, so `cloudhal build`
+ * writes it into canonical links, the sitemap and feeds before any deploy (#48); `deploy` does the
+ * same on the deployment.
  */
-import { isHostname, normalizeHostname } from "@cloudhal/core-ts";
+import path from "node:path";
+import { isHostname, normalizeHostname, withPrimaryDomain } from "@cloudhal/core-ts";
+import { openLocalStore } from "@cloudhal/core-ts/local";
 import {                     readProjectConfig, writeProjectConfig } from "../config.js";
 
-                                             
+                                                           
 
                                 
                               
-                                                    
-                                                                      
+     
+                                                                                            
+                                                  
+     
+                  
+                           
+                             
+                                           
+    
                            
                                             
  
@@ -27,18 +39,47 @@ export function checkHostname(input        )         {
 
 export async function domain(options               )                                    {
   const cfg = await readProjectConfig(options.projectDir);
-  const next                                     = { ...cfg.domains };
+  const next                                                                    = {
+    ...cfg.domains,
+  };
   for (const target of options.remove ?? []) delete next[target];
+  // redirects go to the site's domain: without it they have nowhere to go
+  if (options.remove?.includes("site")) delete next.redirects;
   if (options.set?.site) next.site = checkHostname(options.set.site);
   if (options.set?.studio) next.studio = checkHostname(options.set.studio);
+  if (options.set?.redirects)
+    next.redirects = [...new Set(options.set.redirects.map(checkHostname))];
   if (next.site && next.site === next.studio)
     throw new Error("the site and Studio need different hostnames");
+  checkRedirects(next);
+  if (!next.redirects?.length) delete next.redirects;
+  const any = next.site || next.studio || next.redirects;
   if (options.set || options.remove) {
     const { domains: _old, ...rest } = cfg;
-    await writeProjectConfig(options.projectDir, {
-      ...rest,
-      ...(next.site || next.studio ? { domains: next } : {}),
-    });
+    await writeProjectConfig(options.projectDir, { ...rest, ...(any ? { domains: next } : {}) });
+  }
+  if (next.site && options.set?.site) await makePrimary(options.projectDir, cfg, next.site);
+  return any ? next : undefined;
+}
+
+/** Redirect hosts need a site domain to go to, and are neither it nor Studio's. */
+function checkRedirects(d                                                                   ) {
+  if (!d.redirects?.length) return;
+  if (!d.site)
+    throw new Error("redirects need the site's own domain: cloudhal domain set <hostname>");
+  for (const host of d.redirects)
+    if (host === d.site || host === d.studio)
+      throw new Error(`${host} is already the site's or Studio's domain; it cannot redirect`);
+}
+
+/** `hostname` becomes the local site's primary domain (other domains stay, as secondary). */
+async function makePrimary(projectDir        , cfg               , hostname        ) {
+  const local = await openLocalStore(path.join(projectDir, cfg.dataDir));
+  try {
+    const site = await local.store.getSite(cfg.siteId);
+    if (site && site.domains.find((d) => d.primary)?.hostname !== hostname)
+      await local.store.updateSite({ ...site, domains: withPrimaryDomain(site.domains, hostname) });
+  } finally {
+    await local.close();
   }
-  return next.site || next.studio ? next : undefined;
 }

package/dist/src/commands/snapshot.d.ts

@@ -4,7 +4,15 @@ export interface SnapshotOptions {
     readonly label?: string;
     readonly publish?: boolean;
 }
-/** Creates a snapshot of the live site (and optionally publishes it). */
-export declare function snapshot(options: SnapshotOptions): Promise<Snapshot>;
+/** A snapshot, or (`unchanged`) the live one when publishing would change nothing. */
+export type SnapshotResult = Snapshot & {
+    readonly unchanged?: true;
+};
+/**
+ * Creates a snapshot of the live site (and optionally publishes it). Publishing a site whose
+ * graph matches its live snapshot makes no new one (#51): re-running a setup script does not pad
+ * the history with empty snapshots.
+ */
+export declare function snapshot(options: SnapshotOptions): Promise<SnapshotResult>;
 /** The snapshot `cloudhal build` renders: the published one, else the latest, else a fresh one. */
 export declare function resolveBuildSnapshot(projectDir: string): Promise<Snapshot>;

package/dist/src/commands/snapshot.js

@@ -1,6 +1,6 @@
 import path from "node:path";
                                                          
-import { openLocalStore } from "@cloudhal/core-ts/local";
+import {                  openLocalStore } from "@cloudhal/core-ts/local";
 import { readProjectConfig } from "../config.js";
 
                                   
@@ -9,11 +9,22 @@ import { readProjectConfig } from "../config.js";
                              
  
 
-/** Creates a snapshot of the live site (and optionally publishes it). */
-export async function snapshot(options                 )                    {
+/** A snapshot, or (`unchanged`) the live one when publishing would change nothing. */
+                                                                      
+
+/**
+ * Creates a snapshot of the live site (and optionally publishes it). Publishing a site whose
+ * graph matches its live snapshot makes no new one (#51): re-running a setup script does not pad
+ * the history with empty snapshots.
+ */
+export async function snapshot(options                 )                          {
   const cfg = await readProjectConfig(options.projectDir);
   const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
   try {
+    if (options.publish) {
+      const live = await unchangedLive(local.store, cfg.siteId);
+      if (live) return { ...live, unchanged: true };
+    }
     const snap = await local.store.createSnapshot(cfg.siteId, {
       actor: { kind: "human", id: "user_localcli0001", name: "cloudhal CLI" },
       reason: options.publish ? "publish" : "manual",
@@ -30,6 +41,18 @@ export async function snapshot(options                 )                    {
   }
 }
 
+/** The live snapshot when the site has one and nothing is pending against it. */
+async function unchangedLive(
+  store                     ,
+  siteId        ,
+)                                {
+  const site = await store.getSite(siteId);
+  if (!site?.publishedSnapshotId) return undefined;
+  const d = await store.pendingChanges(siteId);
+  if (d.added.length || d.removed.length || d.changed.length) return undefined;
+  return (await store.getSnapshot(site.publishedSnapshotId)) ?? undefined;
+}
+
 /** The snapshot `cloudhal build` renders: the published one, else the latest, else a fresh one. */
 export async function resolveBuildSnapshot(projectDir        )                    {
   const cfg = await readProjectConfig(projectDir);

package/dist/src/config.d.ts

@@ -104,11 +104,13 @@ export interface ProjectConfig {
     readonly dataDir: string;
     /**
      * Custom domains `cloudhal deploy` routes to the Workers (Cloudflare Custom Domains; the zone
-     * must be in the same account). The workers.dev addresses keep working.
+     * must be in the same account). The workers.dev addresses keep working. `redirects` answer with
+     * a 301 to `site` (#49), e.g. `www.example.com`.
      */
     readonly domains?: {
         readonly site?: string;
         readonly studio?: string;
+        readonly redirects?: readonly string[];
     };
     /** Site analytics (RFC-0006); absent = off. */
     readonly analytics?: AnalyticsConfig;

package/dist/src/config.js

@@ -117,9 +117,14 @@ const MAIL_ADDRESS = /^[^\s@<>"]+@[^\s@<>"]+\.[^\s@<>"]+$/;
                            
      
                                                                                                 
-                                                                          
+                                                                                                  
+                                                   
      
-                                                                          
+                      
+                           
+                             
+                                           
+    
                                                  
                                        
                                                                       
@@ -167,6 +172,21 @@ const OWN_KEYS = new Set([
 
 const VITALS = [0, 1, 2, 5, 10, 20];
 
+/** `domains`, leniently: values of the wrong type are left out. */
+function parseDomains(input         )                           {
+  if (!input || typeof input !== "object") return undefined;
+  const d = input                           ;
+  const redirects = Array.isArray(d.redirects)
+    ? d.redirects.filter((h)              => typeof h === "string" && h !== "")
+    : [];
+  const out = {
+    ...(typeof d.site === "string" && d.site ? { site: d.site } : {}),
+    ...(typeof d.studio === "string" && d.studio ? { studio: d.studio } : {}),
+    ...(redirects.length > 0 ? { redirects } : {}),
+  };
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 /** Leniently parsed, like `domains`: values of the wrong type are left out. */
 export function parseAnalyticsConfig(input         )                              {
   if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
@@ -297,7 +317,7 @@ export async function readProjectConfig(projectDir        )
   }
   const cfg = JSON.parse(raw)                          ;
   if (typeof cfg.siteId !== "string") throw new Error(`${CONFIG_FILE}: missing siteId`);
-  const domains = cfg.domains && typeof cfg.domains === "object" ? cfg.domains : undefined;
+  const domains = parseDomains(cfg.domains);
   const analytics = parseAnalyticsConfig(cfg.analytics);
   const comments = parseCommentsConfig(cfg.comments);
   const schedules = parseSchedulesConfig(cfg.schedules);
@@ -314,14 +334,7 @@ export async function readProjectConfig(projectDir        )
       ? { installation: cfg.installation }
       : {}),
     dataDir: cfg.dataDir ?? ".cloudhal",
-    ...(domains && (domains.site || domains.studio)
-      ? {
-          domains: {
-            ...(typeof domains.site === "string" ? { site: domains.site } : {}),
-            ...(typeof domains.studio === "string" ? { studio: domains.studio } : {}),
-          },
-        }
-      : {}),
+    ...(domains ? { domains } : {}),
     ...(analytics ? { analytics } : {}),
     ...(comments ? { comments } : {}),
     ...(schedules ? { schedules } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudhal/cli",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "cloudhal — create, run and build Cloudhal sites locally",
   "license": "Apache-2.0",
   "homepage": "https://cloudhal.dev",
@@ -27,16 +27,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@cloudhal/agent-runtime": "0.3.7",
-    "@cloudhal/analytics": "0.3.7",
-    "@cloudhal/api": "0.3.7",
-    "@cloudhal/cloudflare": "0.3.7",
-    "@cloudhal/comments": "0.3.7",
-    "@cloudhal/core-contracts": "0.3.7",
-    "@cloudhal/core-ts": "0.3.7",
-    "@cloudhal/mcp-server": "0.3.7",
-    "@cloudhal/schedules": "0.3.7",
-    "@cloudhal/storage": "0.3.7",
+    "@cloudhal/agent-runtime": "0.3.9",
+    "@cloudhal/analytics": "0.3.9",
+    "@cloudhal/api": "0.3.9",
+    "@cloudhal/cloudflare": "0.3.9",
+    "@cloudhal/comments": "0.3.9",
+    "@cloudhal/core-contracts": "0.3.9",
+    "@cloudhal/core-ts": "0.3.9",
+    "@cloudhal/mcp-server": "0.3.9",
+    "@cloudhal/schedules": "0.3.9",
+    "@cloudhal/storage": "0.3.9",
     "@hono/node-server": "^2.1.4",
     "better-sqlite3": "13.0.3"
   },