create-website-build-kit 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-website-build-kit",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Scaffold a production marketing site \u2014 Astro on Cloudflare Workers, with the gates, the migration playbook and the accessibility work already wired.",
   "keywords": [
     "astro",

package/template/CLAUDE.md

@@ -95,6 +95,19 @@ The rules whose failure looks like success — double-counted pageviews, a conve
 two pipes, a trigger on `sent=1` that catches almost nothing — are in `docs/analytics.md`.
 Read it before adding any tag.
 
+⚠ **A CMS DELETES EVERY KEY ITS SCHEMA FORGOT.** It rewrites the whole file from the schema, so
+anything undeclared is absent from what it writes back — the client changes one field, saves, and
+the rest is gone, looking like an ordinary content commit. `npm run check:cms` refuses a
+`.pages.yml` that does not declare every key in the files it edits. **Declare keys the client will
+never touch**, or move them out of a CMS-managed file.
+
+⚠ **UPLOADS GO TO `media/source/`, NEVER `public/img/`.** The direction is the whole bug:
+`optimize-media.mjs` **reads** `media/source/` and **writes** `public/img/`. A CMS media source
+pointed at the output produces files with no variants, no width/height and no manifest entry, so
+`<Img>` throws and the client's own edit turns the build red. `<Img>` accepts a picker path like
+`/img/photos/hero-1200.webp` and normalises it back to the key, so an image field can be a real
+picker instead of asking the client to type a manifest key from memory.
+
 ⚠ **THE HONEYPOT IS CALLED `company`.** `api/contact.ts` discards any submission that fills it in,
 silently and with a 200, so a bot learns nothing. Add a real "Company" field to that form — an
 ordinary client request — and every enquiry from a company that types its name is thrown away, with

package/template/docs/handover.md

@@ -131,6 +131,36 @@ how.
 once — the header, the footer, every button, the notification emails, and what Google reads.
 Ask for them to be changed in that one file rather than page by page, or they will drift.
 
+### Editing it yourself
+
+⚠ *Delete this whole subsection if the site has no content editor.*
+
+You sign in at ⚠ **editor URL** with your ⚠ **GitHub / provider** account. Ask ⚠ **name** to add
+anyone else who needs access.
+
+| Section | What it changes |
+| --- | --- |
+| ⚠ Site settings | ⚠ business name, contact details, the main button |
+| ⚠ Pages | ⚠ the words on Home, About, Contact |
+| ⚠ Services | ⚠ each service, its photograph and description |
+| ⚠ Blog | ⚠ posts |
+
+**A change is live a few minutes after you save.** ⚠ *Confirm the real timing before sending
+this.* To check it worked, open the page in a private window — an ordinary window may show you
+the version you had before.
+
+**Photographs.** Upload them in the ⚠ **Photographs** area, then choose one in the field on the
+page you are editing. Always fill in the short description beside the image: it is what a
+blind visitor hears and what Google reads. Describe what is in the picture, not the file name.
+
+**You cannot break the website from here.** If a change is wrong, the version before it stays
+live until the new one is ready — so a mistake means your change does not appear, not that the
+site goes down. Tell ⚠ **name** what you changed and it can be put back.
+
+**Things to leave alone.** ⚠ *List anything the editor can reach that it should not — otherwise
+delete this line.* If a screen asks for something that looks technical rather than something a
+customer would read, stop and ask.
+
 ---
 
 ## 7. Accessibility

package/template/package-lock.json

@@ -21,7 +21,8 @@
         "sharp": "^0.35.3",
         "turndown": "^7.2.4",
         "typescript": "^6.0.3",
-        "wrangler": "^4.118.0"
+        "wrangler": "^4.118.0",
+        "yaml": "^2.9.0"
       },
       "engines": {
         "node": ">=22.12.0"
@@ -1337,7 +1338,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1360,7 +1360,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1380,7 +1379,6 @@
       "version": "0.35.3",
       "resolved": "https://registry.npmjs.org/@img/sharp-freebsd-wasm32/-/sharp-freebsd-wasm32-0.35.3.tgz",
       "integrity": "sha512-lUxcqWIj2wMQ9BrwNjngcr1gWUr5xgaGThBRqPPalIC2n67Cqj1uPh8NnA/ZhAg8hUbKl+kVHKwgUIwe6ZYPrg==",
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1403,7 +1401,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1420,7 +1417,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1437,7 +1433,6 @@
       "cpu": [
         "arm"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1454,7 +1449,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1471,7 +1465,6 @@
       "cpu": [
         "ppc64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1488,7 +1481,6 @@
       "cpu": [
         "riscv64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1505,7 +1497,6 @@
       "cpu": [
         "s390x"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1522,7 +1513,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1539,7 +1529,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1556,7 +1545,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1573,7 +1561,6 @@
       "cpu": [
         "arm"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1596,7 +1583,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1619,7 +1605,6 @@
       "cpu": [
         "ppc64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1642,7 +1627,6 @@
       "cpu": [
         "riscv64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1665,7 +1649,6 @@
       "cpu": [
         "s390x"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1688,7 +1671,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1711,7 +1693,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1734,7 +1715,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1754,7 +1734,6 @@
       "version": "0.35.3",
       "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.35.3.tgz",
       "integrity": "sha512-cZ0XkcYGpHZkqW6iCkqTcmUC0CD9DhD5d/qeZlZkfRBn6GnHniZXLUo5+9xw8Iv76YE6LQFN9YNBlKREcCG76w==",
-      "dev": true,
       "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
       "optional": true,
       "dependencies": {
@@ -1774,7 +1753,6 @@
       "cpu": [
         "wasm32"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "dependencies": {
@@ -1794,7 +1772,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "Apache-2.0 AND LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1814,7 +1791,6 @@
       "cpu": [
         "ia32"
       ],
-      "dev": true,
       "license": "Apache-2.0 AND LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1834,7 +1810,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "Apache-2.0 AND LGPL-3.0-or-later",
       "optional": true,
       "os": [

package/template/package.json

@@ -36,7 +36,8 @@
     "deploy:production": "npm run build:production && wrangler deploy && node scripts/check-secrets.mjs",
     "check:secrets": "node scripts/check-secrets.mjs",
     "check:copy": "node scripts/check-copy.mjs",
-    "check:form": "node scripts/check-form.mjs"
+    "check:form": "node scripts/check-form.mjs",
+    "check:cms": "node scripts/check-cms.mjs"
   },
   "dependencies": {
     "@astrojs/cloudflare": "^14.1.7",
@@ -51,6 +52,7 @@
     "sharp": "^0.35.3",
     "turndown": "^7.2.4",
     "typescript": "^6.0.3",
-    "wrangler": "^4.118.0"
+    "wrangler": "^4.118.0",
+    "yaml": "^2.9.0"
   }
 }

package/template/scripts/build.mjs

@@ -101,6 +101,12 @@ if (env === 'production') {
    environments — nobody ever meant two controls to share a name. */
 step(process.execPath, ['scripts/check-form.mjs']);
 
+/* Same reasoning, and the same timing: a CMS config that does not declare every
+   key in the file it edits will delete content the first time the client saves.
+   That is a source bug, it is invisible in a build, and it costs nothing to
+   check. A no-op on projects with no `.pages.yml`. */
+step(process.execPath, ['scripts/check-cms.mjs']);
+
 run(['build']);
 
 if (env === 'staging') {

package/template/scripts/check-cms.mjs

@@ -0,0 +1,444 @@
+/**
+ * Refuse a CMS config that will silently destroy content.
+ *
+ *   npm run check:cms
+ *
+ * A no-op when the project has no `.pages.yml` — the kit ships no CMS, and a
+ * check that cannot run says so rather than printing a tick it did not earn.
+ *
+ * ── THE FAILURE THIS EXISTS FOR ────────────────────────────────────────────
+ * ⚠ A CMS REWRITES THE WHOLE FILE FROM ITS SCHEMA. Any key the schema does not
+ *   declare is absent from what it writes back — not merged, not flagged. The
+ *   editor changes one field, hits save, and everything the config forgot is
+ *   gone from the repo. In the diff it reads as an ordinary content commit.
+ *
+ * This is not hypothetical. Audited across five shipped sites, two were losing
+ * data on the client's first save:
+ *
+ *   site.json      analytics.ga4MeasurementId, analytics.gtmId,
+ *                  analytics.googleTagId, analytics.cloudflareToken,
+ *                  businessType, openingHours, socials.google
+ *   home_{en,ru,uz}.json   cta.image.src/alt/isRender,
+ *                          quote.image.src/alt/isRender
+ *
+ * Read the first one again: the moment the client opens Site Settings and saves,
+ * every analytics ID is deleted. Tracking stops, opening hours vanish from the
+ * JSON-LD, and nobody is told. On the multilingual site, all three homepages
+ * lose their CTA and quote images at once.
+ *
+ * 27 keys were at risk across those two projects. Every one was invisible to
+ * `astro check`, to the build, and to a reviewer reading the config — because
+ * the config is *valid*. It just describes less than the file contains.
+ *
+ * ── AND MEDIA POINTED THE WRONG WAY ────────────────────────────────────────
+ * Two of the five declared their upload directory as `public/img`, which is
+ * where `optimize-media.mjs` WRITES. An upload there is servable but has no
+ * variants, no width/height and no manifest entry, so `<Img>` throws and the
+ * client's own edit turns the build red. Uploads belong in the pipeline's
+ * INPUT — `media/source/` — and the direction is the whole bug.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { parse } from 'yaml';
+
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const DIM = '\x1b[2m';
+
+const CONFIG = '.pages.yml';
+
+if (!existsSync(CONFIG)) {
+  console.log(`${DIM}·${RESET} no ${CONFIG} — no CMS to check`);
+  process.exit(0);
+}
+
+let config;
+try {
+  config = parse(readFileSync(CONFIG, 'utf8')) ?? {};
+} catch (err) {
+  console.error(`\n${RED}✗ ${CONFIG} does not parse${RESET}\n\n  ${err.message}\n`);
+  process.exit(1);
+}
+
+const problems = [];
+const warnings = [];
+
+/* PagesCMS nests with `items`, not `content`. Getting this wrong reports every
+   grouped config as having zero entries — which looks like a clean pass. */
+const flatten = (entries) =>
+  (entries ?? []).flatMap((entry) =>
+    entry?.type === 'group' ? flatten(entry.items ?? entry.content ?? []) : [entry],
+  );
+
+/** Every dotted path the schema declares. Arrays reuse the parent prefix. */
+function schemaPaths(fields, prefix = '') {
+  const out = new Set();
+  for (const field of fields ?? []) {
+    if (!field?.name) continue;
+    const path = prefix ? `${prefix}.${field.name}` : field.name;
+    out.add(path);
+    if (Array.isArray(field.fields)) for (const p of schemaPaths(field.fields, path)) out.add(p);
+  }
+  return out;
+}
+
+/** Every dotted path the DATA contains. An array's items sit at its own prefix. */
+function dataPaths(value, prefix = '') {
+  const out = new Set();
+  if (Array.isArray(value)) {
+    for (const item of value) for (const p of dataPaths(item, prefix)) out.add(p);
+  } else if (value && typeof value === 'object') {
+    for (const [key, inner] of Object.entries(value)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      out.add(path);
+      for (const p of dataPaths(inner, path)) out.add(p);
+    }
+  }
+  return out;
+}
+
+/** Frontmatter keys actually used across a collection, as dotted paths. */
+function collectionPaths(dir) {
+  const out = new Set();
+  const walk = (d) =>
+    readdirSync(d).flatMap((e) => {
+      const full = join(d, e);
+      return statSync(full).isDirectory() ? walk(full) : [full];
+    });
+  for (const file of walk(dir).filter((f) => /\.mdx?$/.test(f))) {
+    const raw = readFileSync(file, 'utf8');
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
+    if (!match) continue;
+    try {
+      for (const p of dataPaths(parse(match[1]) ?? {})) out.add(p);
+    } catch {
+      /* A collection item with unparseable frontmatter is the content
+         collection's problem, and astro check reports it properly. */
+    }
+  }
+  return out;
+}
+
+const rel = (p) => relative(process.cwd(), p).split(sep).join('/');
+
+/* ── content entries ─────────────────────────────────────────────────────── */
+
+const entries = flatten(config.content);
+
+if (!entries.length) {
+  warnings.push(`${CONFIG} declares no content entries — the editor sees an empty CMS`);
+}
+
+for (const entry of entries) {
+  const label = entry?.name ?? entry?.label ?? '(unnamed)';
+  const path = entry?.path;
+  if (!path) {
+    problems.push({ label, why: 'has no `path`' });
+    continue;
+  }
+  if (!existsSync(path)) {
+    problems.push({ label, why: `path does not exist: ${path}` });
+    continue;
+  }
+
+  const declared = schemaPaths(entry.fields);
+
+  if (entry.type === 'collection') {
+    const used = collectionPaths(path);
+    const undeclared = [...used].filter((p) => !declared.has(p));
+    if (undeclared.length) {
+      problems.push({ label, why: `frontmatter keys the schema does not declare`, keys: undeclared, path });
+    }
+    continue;
+  }
+
+  if (/\.json$/.test(path)) {
+    let data;
+    try {
+      data = JSON.parse(readFileSync(path, 'utf8'));
+    } catch (err) {
+      problems.push({ label, why: `${path} is not valid JSON — ${err.message}` });
+      continue;
+    }
+    const undeclared = [...dataPaths(data)].filter((p) => !declared.has(p));
+    if (undeclared.length) {
+      problems.push({ label, why: 'keys in the file the schema does not declare', keys: undeclared, path });
+    }
+  }
+}
+
+/* ── media ───────────────────────────────────────────────────────────────── */
+
+/* Declared here, not beside the image checks that read it: the media loop below
+   fills it, and a `const` used above its own declaration is a TDZ
+   ReferenceError that `node --check` cannot see. This file shipped that way for
+   exactly one run. */
+const mediaByName = new Map();
+
+/* Where optimize-media.mjs writes. An upload here is not an input, it is a
+   file dropped into generated output. */
+const GENERATED = ['public/img', 'dist', '.astro'];
+
+const media = config.media ? (Array.isArray(config.media) ? config.media : [config.media]) : [];
+
+for (const source of media) {
+  const input = typeof source === 'string' ? source : source?.input;
+  const name = (typeof source === 'object' && source?.name) || input || '(unnamed)';
+  if (!input) {
+    problems.push({ label: `media ${name}`, why: 'has no `input`' });
+    continue;
+  }
+  if (typeof source === 'object' && source.name) mediaByName.set(source.name, source);
+  const normalised = input.replace(/^\.?\//, '').replace(/\/$/, '');
+  if (GENERATED.some((g) => normalised === g || normalised.startsWith(`${g}/`))) {
+    problems.push({
+      label: `media ${name}`,
+      why: `uploads into ${input}, which is GENERATED output`,
+      direction: true,
+    });
+    continue;
+  }
+  if (!existsSync(input)) {
+    problems.push({ label: `media ${name}`, why: `input directory does not exist: ${input}` });
+    continue;
+  }
+  if (typeof source === 'object' && !source.extensions) {
+    warnings.push(
+      `media "${name}" declares no \`extensions\` — a bad format is accepted in the UI and ` +
+        `fails the build twenty minutes later instead of being refused at the door`,
+    );
+  }
+}
+
+/* ── image fields: is the stored VALUE the shape the field type needs? ───── */
+
+/*
+ * ⚠ THIS IS THE CHECK THE TOLERANT READER MADE NECESSARY.
+ *
+ *   `<Img>` accepts a manifest key OR a picker path, which is what lets an
+ *   image field be a real picker. But a reader that accepts two formats will
+ *   never tell you which one you stored — so converting a field to
+ *   `type: image` without migrating its values leaves a site where:
+ *
+ *     the build is green, astro check is clean, pa11y is clean, and the
+ *     rendered HTML is BYTE-IDENTICAL — and every picker in the CMS is broken.
+ *
+ *   That happened on a real site: eighteen grey squares in the editor and a
+ *   GitHub link 404ing, while every automated check said the site was fine.
+ *   Nothing rendered by the site can see it, because the CMS is not a page.
+ *
+ *   `type: image` is built around the PATH — the picker returns one, the
+ *   thumbnail loads one, the repo link resolves one. So the value has to start
+ *   with that media source's `output`. Convert the field and migrate the data
+ *   in the same change.
+ */
+function imageFields(fields, prefix = '') {
+  const out = [];
+  for (const field of fields ?? []) {
+    if (!field?.name) continue;
+    const path = prefix ? `${prefix}.${field.name}` : field.name;
+    if (field.type === 'image') out.push({ path, media: field.options?.media });
+    if (Array.isArray(field.fields)) out.push(...imageFields(field.fields, path));
+  }
+  return out;
+}
+
+/** Every value stored at a dotted path, walking through arrays. */
+function valuesAt(value, parts) {
+  if (value == null) return [];
+  if (!parts.length) return Array.isArray(value) ? value : [value];
+  if (Array.isArray(value)) return value.flatMap((v) => valuesAt(v, parts));
+  if (typeof value !== 'object') return [];
+  const [head, ...rest] = parts;
+  return valuesAt(value[head], rest);
+}
+
+for (const entry of entries) {
+  const fields = imageFields(entry?.fields);
+  if (!fields.length || !existsSync(entry.path ?? '')) continue;
+
+  const documents = [];
+  if (entry.type === 'collection') {
+    /* Frontmatter only; a body image is markdown, not a field. */
+    const walk = (d) =>
+      readdirSync(d).flatMap((e) => {
+        const full = join(d, e);
+        return statSync(full).isDirectory() ? walk(full) : [full];
+      });
+    for (const file of walk(entry.path).filter((f) => /\.mdx?$/.test(f))) {
+      const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(readFileSync(file, 'utf8'));
+      if (!m) continue;
+      try {
+        documents.push({ where: rel(file), data: parse(m[1]) ?? {} });
+      } catch {
+        /* astro check reports unparseable frontmatter properly. */
+      }
+    }
+  } else if (/\.json$/.test(entry.path)) {
+    try {
+      documents.push({ where: rel(entry.path), data: JSON.parse(readFileSync(entry.path, 'utf8')) });
+    } catch {
+      /* Already reported above. */
+    }
+  }
+
+  for (const { path: fieldPath, media: mediaName } of fields) {
+    const source =
+      (mediaName && mediaByName.get(mediaName)) ?? (media.length === 1 ? media[0] : null);
+    const output = typeof source === 'object' ? source?.output : null;
+    if (!output) continue; // nothing declared to measure against
+    /* `output: /` makes "starts with the output" true of every absolute path, so
+       it only distinguishes a path from a non-path. Still worth reporting — a
+       `type: image` field holding a bare word is a picker showing nothing — but
+       do not pretend the test was stronger than it was. */
+
+    /* ⚠ ONE PROBLEM PER FIELD, NOT PER VALUE. A collection of thirty items with
+       one bad field produced thirty identical lines on a real project — 78 in
+       total for three fields. A gate that floods is a gate that gets switched
+       off, and the fix is always the same edit for the whole field. */
+    const wrong = [];
+    for (const doc of documents) {
+      for (const value of valuesAt(doc.data, fieldPath.split('.'))) {
+        if (typeof value !== 'string' || !value) continue;
+        if (value.startsWith(output)) continue;
+        wrong.push({ value, where: doc.where });
+      }
+    }
+    if (wrong.length) {
+      const samples = [...new Set(wrong.map((w) => w.value))].slice(0, 3);
+      problems.push({
+        label: `${entry.name ?? entry.label} → ${fieldPath}`,
+        why:
+          `is \`type: image\` but ${wrong.length} value(s) are not a path under ${JSON.stringify(output)}` +
+          ` — e.g. ${samples.map((v) => JSON.stringify(v)).join(', ')}`,
+        picker: true,
+        path: wrong[0].where,
+      });
+    }
+  }
+}
+
+/* ── coverage, and secrets ───────────────────────────────────────────────── */
+
+/*
+ * ⚠ WARNINGS, NEVER FAILURES. What belongs in a CMS is a judgement — a single
+ *   -location business has no business needing a Locations collection, and a
+ *   gate that insists otherwise gets switched off. But "the client says whole
+ *   sections are missing" was the actual complaint from five delivered sites,
+ *   and it is checkable: content exists in the repo that no CMS entry points at.
+ *
+ *   Audited across those five, navigation was absent from ALL FIVE, and
+ *   testimonials from four. Nothing reported it, because nothing looked.
+ */
+const covered = new Set(
+  entries.map((e) => (e?.path ?? '').replace(/^\.?\//, '').replace(/\/$/, '')).filter(Boolean),
+);
+
+/*
+ * Generated files — a CMS editing these would be editing build output.
+ *
+ * ⚠ MATCHED BY SHAPE, NOT BY NAME. This began as a two-name list and
+ *   immediately produced a false positive on a real project's
+ *   `media-manifest.json`, which is the denylist problem in miniature: it knows
+ *   only the files already thought of. Anything `*manifest.json` is written by
+ *   a build step, and `lastmod.json` is named because dates are generated too.
+ */
+const isGenerated = (file) => /manifest\.json$/.test(file) || file === 'lastmod.json';
+
+const uncovered = [];
+
+if (existsSync('src/content')) {
+  for (const dir of readdirSync('src/content', { withFileTypes: true })) {
+    if (!dir.isDirectory()) continue;
+    const path = `src/content/${dir.name}`;
+    if (![...covered].some((c) => c === path || c.startsWith(`${path}/`))) uncovered.push(path);
+  }
+}
+
+if (existsSync('src/data')) {
+  for (const file of readdirSync('src/data')) {
+    if (!file.endsWith('.json') || isGenerated(file)) continue;
+    const path = `src/data/${file}`;
+    if (!covered.has(path)) uncovered.push(path);
+  }
+}
+
+if (uncovered.length) {
+  warnings.push(
+    `${uncovered.length} content source(s) exist that no CMS entry points at — the client cannot ` +
+      `edit them, and "whole sections are missing" is how that gets reported:\n` +
+      uncovered.map((u) => `      ${u}`).join('\n') +
+      `\n      Each is either a deliberate developer-controlled file or a gap. Decide which.`,
+  );
+}
+
+/*
+ * ⚠ A SECRET IN A CMS IS A SECRET THE CLIENT CAN READ AND CHANGE. Analytics
+ *   IDs, tokens and keys are technical configuration: their failure mode is
+ *   silent (tracking stops, mail stops) and no editor can diagnose it.
+ */
+const SECRET_SHAPED = /(^|[._-])(api|secret|token|key|password|credential|apikey)([._-]|$)|(ga4|gtm|analytics|measurement)/i;
+
+for (const entry of entries) {
+  const risky = [...schemaPaths(entry?.fields)].filter((f) => SECRET_SHAPED.test(f));
+  if (risky.length) {
+    warnings.push(
+      `"${entry?.name ?? entry?.label}" exposes field(s) that look like technical configuration ` +
+        `rather than content: ${risky.join(', ')}. A client cannot diagnose what breaks when one ` +
+        `is changed, and the failure is silent.`,
+    );
+  }
+}
+
+/* ── report ──────────────────────────────────────────────────────────────── */
+
+for (const w of warnings) console.log(`  ${YELLOW}!${RESET} ${w}`);
+
+if (!problems.length) {
+  console.log(
+    `${GREEN}✓${RESET} ${CONFIG}: ${entries.length} entrie(s), every key declared` +
+      (media.length ? `, ${media.length} media source(s)` : ''),
+  );
+  process.exit(0);
+}
+
+console.error(`\n${RED}✗ ${problems.length} problem(s) in ${CONFIG}${RESET}\n`);
+
+for (const p of problems) {
+  console.error(`    ${p.label}  —  ${p.why}`);
+  if (p.keys) {
+    for (const k of p.keys.slice(0, 12)) console.error(`      ${DIM}${k}${RESET}`);
+    if (p.keys.length > 12) console.error(`      ${DIM}…and ${p.keys.length - 12} more${RESET}`);
+    console.error(
+      `      ${DIM}These exist in ${rel(p.path)} and are NOT in the schema, so the first\n` +
+        `      save from this screen DELETES them. Declare every key — including ones\n` +
+        `      the client will never touch — or move them out of a CMS-managed file.${RESET}`,
+    );
+  }
+  if (p.picker) {
+    console.error(
+      `      ${DIM}The site still renders this: <Img> accepts a manifest key as well as a\n` +
+        `      picker path. The CMS does not — \`type: image\` is built around the path, so\n` +
+        `      the picker shows an empty square and the repo link 404s, while the build,\n` +
+        `      the types and the rendered HTML all stay clean.\n\n` +
+        `      A reader that accepts two formats cannot tell you which one you stored.\n` +
+        `      Convert the field and migrate the values in the same change.${RESET}`,
+    );
+  }
+  if (p.direction) {
+    console.error(
+      `      ${DIM}The direction is the bug. optimize-media.mjs READS media/source/ and\n` +
+        `      WRITES public/img/. An upload into the output has no variants, no\n` +
+        `      width/height and no manifest entry, so <Img> throws and the client's\n` +
+        `      own edit turns the build red.\n\n` +
+        `      input:  media/source/uploads    what the pipeline reads\n` +
+        `      output: /img/uploads            what it writes, once processed${RESET}`,
+    );
+  }
+  console.error('');
+}
+
+process.exit(1);

package/template/scripts/optimize-media.mjs

@@ -16,9 +16,18 @@
 import sharp from 'sharp';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+/*
+ * ⚠ THE PROJECT ROOT IS THE CWD, as it is in every other script here.
+ *
+ *   This resolved from the SCRIPT's own location. In every supported flow the
+ *   two are the same directory — `npm run media` runs with the cwd at the
+ *   package root — so the change is a no-op in use. What it was not was
+ *   testable: the script read its own media/source/ no matter where it was
+ *   pointed, so a fixture could not exercise it at all, and the run that added
+ *   a non-zero exit had nothing proving the exit fires.
+ */
+const ROOT = process.cwd();
 const SRC = path.join(ROOT, 'media/source');
 const OUT = path.join(ROOT, 'public/img');
 const MANIFEST = path.join(ROOT, 'src/data/image-manifest.json');
@@ -56,7 +65,25 @@ const WEBP = { quality: 78, effort: 6 };
 const AVIF = { quality: 55, effort: 4 };
 const FORMATS = ['avif', 'webp'];
 
-const RASTER = /\.(jpe?g|png|webp|tiff?)$/i;
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const DIM = '\x1b[2m';
+
+/*
+ * ⚠ heic/heif ARE HERE ON PURPOSE. libvips in the sharp this kit already ships
+ *   reads them — check with `node -e "console.log(require('sharp').format.heif)"`.
+ *   Leaving them out meant the single likeliest wrong format, a photo straight
+ *   off an iPhone, was discarded by our own regex while the library underneath
+ *   handled it fine. It produced no output, no warning and no manifest entry.
+ */
+const RASTER = /\.(jpe?g|png|webp|tiff?|heic|heif)$/i;
+
+/* Sources are committed forever. Output is capped by the width ladder, so a
+   huge original costs visitors nothing and costs the REPO permanently — say so
+   in those words, or someone "fixes" a page-speed problem that does not exist. */
+const BIG_PIXELS = 24_000_000;
+const BIG_BYTES = 8 * 1024 * 1024;
 
 /*
  * ── DO NOT RESET THIS TO {} ────────────────────────────────────────────────
@@ -362,11 +389,45 @@ const before = await bytes(SRC);
 console.log('optimizing media…');
 await copyBrand(files.filter((f) => f.includes(`${path.sep}brand${path.sep}`)));
 
-for (const file of files.filter((f) => RASTER.test(f))) {
+/*
+ * ⚠ THE RUN MUST NAME EVERYTHING IT DID NOT PRODUCE.
+ *
+ *   This loop used to be `files.filter(RASTER)`. Anything else was dropped with
+ *   no output, no warning and no manifest entry — so a `.heic` in media/source/
+ *   simply was not on the site, and the failure surfaced much later as <Img>
+ *   throwing "no manifest entry for …" against a file plainly sitting in the
+ *   repo. That reads as a bug in the kit rather than a rejected upload.
+ *
+ *   And there was no try/catch, so one corrupt file aborted the run midway —
+ *   after outputs were written and the manifest was partly updated, leaving the
+ *   manifest describing a state on disk that no longer matched it.
+ */
+const skipped = [];
+const failed = [];
+const oversized = [];
+
+for (const file of files) {
   if (file.includes(`${path.sep}brand${path.sep}`)) continue;
-  if (file.includes(`${path.sep}certifications${path.sep}`)) await emitSingle(file);
-  else if (file.includes(`${path.sep}blog${path.sep}`)) await emitResponsive(file, BLOG_WIDTHS);
-  else await emitResponsive(file, PHOTO_WIDTHS);
+  const rel = path.relative(SRC, file);
+
+  if (!RASTER.test(file)) {
+    skipped.push(rel);
+    continue;
+  }
+
+  try {
+    const { size } = await fs.stat(file);
+    const meta = await sharp(file).metadata();
+    if (size > BIG_BYTES || (meta.width ?? 0) * (meta.height ?? 0) > BIG_PIXELS) {
+      oversized.push(`${rel}  ${meta.width}x${meta.height}, ${mb(size)}`);
+    }
+
+    if (file.includes(`${path.sep}certifications${path.sep}`)) await emitSingle(file);
+    else if (file.includes(`${path.sep}blog${path.sep}`)) await emitResponsive(file, BLOG_WIDTHS);
+    else await emitResponsive(file, PHOTO_WIDTHS);
+  } catch (err) {
+    failed.push(`${rel}  ← ${String(err.message).split('\n')[0]}`);
+  }
 }
 
 await emitFavicons();
@@ -378,3 +439,29 @@ await fs.writeFile(MANIFEST, JSON.stringify(manifest, null, 2) + '\n');
 const after = await bytes(OUT);
 console.log(`\nsource ${mb(before)}  →  dist ${mb(after)}  (${Math.round((1 - after / before) * 100)}% smaller)`);
 console.log(`${Object.keys(manifest).length} images in manifest`);
+
+/* A report, not an error. A PDF or a .txt in media/source/ is legitimate — the
+   kit's own comp lives there — so this says what produced no image and lets the
+   reader judge. Only a genuine processing failure exits non-zero. */
+if (skipped.length) {
+  console.log(`\n${YELLOW}!${RESET} ${skipped.length} file(s) produced no image (not a raster format):`);
+  for (const f of skipped) console.log(`    ${DIM}${f}${RESET}`);
+}
+
+if (oversized.length) {
+  console.log(`\n${YELLOW}!${RESET} ${oversized.length} oversized source(s) — the SITE is unaffected:`);
+  for (const f of oversized) console.log(`    ${DIM}${f}${RESET}`);
+  console.log(
+    `    ${DIM}Output is capped by the width ladder, so visitors never download these.\n` +
+      `    The cost is the repository, which carries them forever.${RESET}`,
+  );
+}
+
+if (failed.length) {
+  console.error(`\n${RED}✗ ${failed.length} file(s) failed to process:${RESET}`);
+  for (const f of failed) console.error(`    ${f}`);
+  console.error(
+    `\n  ${DIM}Every other file was still written and the manifest is complete for them.${RESET}\n`,
+  );
+  process.exit(1);
+}

package/template/scripts/recon.mjs

@@ -158,13 +158,17 @@ const notes = [];
  */
 const refusals = new Set();
 
-function refuse(reason, url) {
+function refuse(reason, url, kind) {
   if (!refusals.has(reason)) {
     refusals.add(reason);
     console.log(`  ${YELLOW}refused${RESET} ${reason}`);
+    /* ⚠ ONLY A HOST REFUSAL IS SOMETHING --allow-internal CAN EXCUSE. Offering
+       the flag for a `file:` redirect is a dead hint — the same mistake this
+       script already fixed once in the startup message, still living here. */
     notes.push(
       `Refused to fetch ${url} — ${reason}. This was NOT a network error: the crawl skipped it ` +
-        `deliberately, so the inventory is incomplete. Re-run with --allow-internal if that host is yours.`,
+        `deliberately, so the inventory is incomplete.` +
+        (kind === 'host' ? ' Re-run with --allow-internal if that host is yours.' : ''),
     );
   }
   return null;
@@ -172,7 +176,7 @@ function refuse(reason, url) {
 
 async function req(url, options = {}) {
   const refusal = blockedReason(url, { allowInternal });
-  if (refusal) return refuse(refusal.reason, url);
+  if (refusal) return refuse(refusal.reason, url, refusal.kind);
 
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 20000);
@@ -193,7 +197,7 @@ async function req(url, options = {}) {
     for (let hops = 0; follow && res.status >= 300 && res.status < 400 && res.headers.get('location') && hops < MAX_HOPS; hops++) {
       const next = new URL(res.headers.get('location'), url).toString();
       const hopRefusal = blockedReason(next, { allowInternal });
-      if (hopRefusal) return refuse(`${hopRefusal.reason} — reached by a redirect from ${url}`, next);
+      if (hopRefusal) return refuse(`${hopRefusal.reason} — reached by a redirect from ${url}`, next, hopRefusal.kind);
       url = next;
       res = await fetch(url, { ...options, redirect: 'manual', signal: controller.signal });
     }

package/template/src/components/Img.astro

@@ -9,6 +9,7 @@
  * content migration.
  */
 import manifest from '../data/image-manifest.json';
+import { isPickerPath, toImageKey } from '../lib/image-key';
 
 interface Props {
   /** Manifest key, e.g. "photos/hero-home". */
@@ -36,13 +37,29 @@ const {
   style,
 } = Astro.props;
 
-const entry = (manifest as Record<string, { src: string; srcset: string; width: number; height: number; widths?: number[]; avifSrcset?: string | null }>)[name];
+/* A CMS picker returns `/img/photos/hero-1200.webp`, never `photos/hero`.
+   Normalising here is what lets an image field be a real picker instead of a
+   free-text box asking the client to type a manifest key from memory. */
+const key = toImageKey(name);
+const entry = (manifest as Record<string, { src: string; srcset: string; width: number; height: number; widths?: number[]; avifSrcset?: string | null }>)[key];
 
 if (!entry) {
   // Fail the build, not the page. A missing image is a content bug and should
   // never reach a deploy as a silently broken <img>.
+  //
+  // ⚠ THE THROWN TEXT IS PURE ASCII ON PURPOSE. The Cloudflare adapter puts a
+  //   prerender failure into the `x-astro-prerender-error` HTTP HEADER, and a
+  //   header carrying non-ASCII warns loudly and arrives mangled: an em dash
+  //   came back as `â`. Comments may use the house style; anything inside a
+  //   thrown string may not. See docs/traps.md.
   throw new Error(
-    `Img: no manifest entry for "${name}". Run \`npm run media\` after adding it to media/source/.`,
+    isPickerPath(name)
+      ? `Img: "${name}" was uploaded straight into public/img/, which is where the media pipeline ` +
+        `WRITES, so it has no responsive variants, no width/height and no manifest entry.\n\n` +
+        `Point the CMS media source at media/source/ (what the pipeline READS), re-upload, ` +
+        `then run \`npm run media\`.\n\n` +
+        `The last good deploy is still live; this change just will not appear.`
+      : `Img: no manifest entry for "${name}" (resolved to "${key}"). Run \`npm run media\` after adding it to media/source/.`,
   );
 }
 

package/template/src/lib/image-key.ts

@@ -0,0 +1,47 @@
+/**
+ * Turn a public image PATH back into the manifest KEY it came from.
+ *
+ * ── WHY THIS EXISTS ────────────────────────────────────────────────────────
+ * `<Img>` resolves a manifest key — `photos/hero`. A CMS image picker cannot
+ * return one: it browses files and returns the public path of what it found,
+ * `/img/photos/hero-1200.webp`, because it has no idea a manifest exists.
+ *
+ * Without this, every image field in a CMS-managed site has to be a plain
+ * string with a description asking a non-technical editor to type a key from
+ * memory. That is not an editable field, it is a quiz — and it is why image
+ * editing was the part of the CMS that clients could never actually use.
+ *
+ * The two can meet because `optimize-media.mjs` writes exactly one shape:
+ *
+ *     /img/  +  <key>  -<width>.<ext>
+ *
+ * so the mapping back is exact rather than a guess.
+ *
+ * ── THREE PROPERTIES THAT MAKE IT SAFE ─────────────────────────────────────
+ * 1. **Which variant the editor clicks does not matter.** `-480` and `-1800`
+ *    normalise to the same key and render the identical full srcset.
+ * 2. **A key ending in a digit survives.** The width strip is anchored to the
+ *    extension, so `photos/gift-card-slider-1`, reached via `…-1-480.webp`,
+ *    comes back whole. An unanchored `-\d+` would eat the `-1`.
+ * 3. ⚠ **It must not assume `.webp`.** The kit emits AVIF alongside WebP and
+ *    social cards are `.jpg`, so the extension strip stays generic.
+ */
+
+/** `/img/photos/hero-1200.webp` → `photos/hero`. Anything else is returned as-is. */
+export const toImageKey = (nameOrPath: string): string =>
+  isPickerPath(nameOrPath)
+    ? nameOrPath
+        .replace(/^\/img\//, '')
+        .replace(/-\d+(?=\.[a-z0-9]+$)/i, '')
+        .replace(/\.[a-z0-9]+$/i, '')
+    : nameOrPath;
+
+/**
+ * Did this come from a media picker rather than being a manifest key?
+ *
+ * Used to tell an editor what actually went wrong. `/img/` is where the
+ * pipeline WRITES, so a value pointing there is either a processed variant
+ * (fine — `toImageKey` handles it) or a file uploaded straight into the output
+ * directory, which has no variants and no manifest entry at all.
+ */
+export const isPickerPath = (nameOrPath: string): boolean => nameOrPath.startsWith('/img/');