@cparkerwebm/webmonterey 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -11,6 +11,69 @@ build. See `/webm:upgrade`.
 
 ---
 
+## 1.5.0 — 2026-09-06
+
+### Added
+
+- **The `/webmaster` page names the client.** Every string in `copy.webmaster` may carry
+  `{client}`, filled from `client` in `webmonterey.json` when the page renders, and the default
+  copy now does: the meta description, the first paragraph ("This Acme Co custom website was
+  designed, built and managed by WebMonterey…") and the contact line ("If you have a question
+  about the Acme Co website…"). Until now every site in the fleet carried the same paragraph
+  word for word, which is duplicate content across a hundred domains; a page that says whose
+  site it is is not. A site overriding `copy.webmaster` keeps its own words and may use
+  `{client}` in them. A site with no client name yet gets the sentence without the name.
+
+- **A "Visit WebMonterey" button on `/webmaster`.** Outline style, in the site's link colour,
+  radius and border width, below the paragraphs, to the same attributed agency URL the first
+  paragraph links to. The label is `copy.webmaster.cta`. For a site that lays the page out
+  itself, `WebmasterPageProps` gains `cta: { label, href }`, and `AGENCY_LINK_ATTRS` is
+  exported beside it so the button carries the same `target` and `rel` as the intro link
+  without either being typed twice. **A site that already exports `webmasterPage` does not
+  show the button until its component renders `cta`** - `/webm:webmaster` has the updated
+  reference component, one line to add.
+
+- **`webm clean`.** Removes `node_modules/.vite`, `.astro` and `dist` - the three
+  directories a stale dev server is made of - and nothing else. `--dry-run` lists them. The
+  reset that used to be "delete some caches and restart" is one command a session in a client
+  repo can run without knowing what Vite is. `/webm:traps` names it.
+
+- **The Vite pre-bundle is rebuilt on every `astro dev` start.** `optimizeDeps.force` in dev
+  only. A cache in `node_modules/.vite` that outlived a package update, a branch switch or an
+  `astro check` was the dev server 500ing on every request until someone cleared it; a few
+  seconds at startup buys not having that session. A cache that changes underneath a running
+  server is still `webm clean`.
+
+### Changed
+
+- **The `/webmaster` copy, again.** "WebMonterey handles web hosting, security, strategy and
+  ongoing care of our site." - _web hosting_, _our site_, and the clause about focusing on what
+  we do is gone. The contact line reads "about the {client} website" rather than "about this
+  website". A site overriding `copy.webmaster` is unaffected.
+
+- **`@astrojs/cloudflare` floor is `^14.3.0`.** It fixes a cold `astro dev` crash by
+  pre-bundling two of its own entrypoints, and a custom Worker entrypoint - which
+  `defineWorker` builds - now falls back to static assets when no route matches. The package's
+  own handler import is unchanged and the scheduled-handler scenario in the e2e still passes.
+  The package is tested on Astro 7.3.1; the peer range is still `^7.0.0` and 7.3 asks nothing
+  of a site. TypeScript stays on 6: TypeScript 7.0 is out, but `@astrojs/check` declares
+  TypeScript 5 or 6, and Astro's language tooling needs 6 until 7.1 ships a stable API.
+
+### Fixed
+
+- **Astro no longer warns that `/404` is defined twice.** A site with its own
+  `src/pages/404.astro` got two `[router]` warnings on every build - "A static route cannot be
+  defined more than once … will result in a hard error in following versions of Astro" - because
+  the package injected its 404 regardless and relied on the site's file winning. It now looks for
+  the site's own 404 first, in every form Astro treats as a route (`.astro`, `.md`, `.mdx`,
+  `.html`, `.ts`, `.js`), and injects its page only when there is none. A site with no 404 of
+  its own sees no change.
+
+Take it with `npx webm upgrade`. There is no codemod; the one thing to do by hand is the
+`cta` line in a site that exports `webmasterPage`.
+
+---
+
 ## 1.4.0 — 2026-09-04
 
 ### Added

package/README.md

@@ -25,8 +25,8 @@ block router, `header`, `footer` and `panels` for the chrome, `pageHeader` in pl
 router's plain `<h1>`, `structuredData` for the site's JSON-LD, and `webmasterPage` for the body
 of the `/webmaster` page. That last one is the seam for a site whose document pages have a richer
 layout than a heading and a stack of paragraphs: the component receives the merged copy
-(`{ title, description, intro, body }`; `intro` and `body` are HTML, the agency link already in
-`intro`) and lays it out; the route, the words, the `<head>`, the share image and the agency graph
+(`{ title, description, intro, body, cta }`; `intro` and `body` are HTML, the agency link already
+in `intro`, the client's name already in the words, `cta` the outbound button) and lays it out; the route, the words, the `<head>`, the share image and the agency graph
 stay the package's. It carries no copy of its own - the words are overridden through
 `copy.webmaster` in `webmonterey.json`, not in the component.
 

package/dist/webm.mjs

@@ -68,8 +68,8 @@ function normalizeDomain(input) {
   return cleaned;
 }
 function slugFor(domain) {
-  const clean = normalizeDomain(domain);
-  const parts = clean.split(".");
+  const clean2 = normalizeDomain(domain);
+  const parts = clean2.split(".");
   const lastTwo = parts.slice(-2).join(".");
   const drop = TWO_PART_SUFFIXES.has(lastTwo) ? 2 : 1;
   const kept = parts.slice(0, Math.max(1, parts.length - drop));
@@ -2695,11 +2695,53 @@ var init_upgrade = __esm({
   }
 });
 
+// src/cli/clean.ts
+var clean_exports = {};
+__export(clean_exports, {
+  CLEAN_TARGETS: () => CLEAN_TARGETS,
+  clean: () => clean,
+  cleanTargets: () => cleanTargets,
+  run: () => run8
+});
+import { existsSync as existsSync11, rmSync as rmSync2 } from "node:fs";
+import { join as join10, resolve as resolve4 } from "node:path";
+function cleanTargets(root) {
+  return CLEAN_TARGETS.filter((t) => existsSync11(join10(root, t)));
+}
+function clean(root) {
+  const present = cleanTargets(root);
+  for (const t of present) rmSync2(join10(root, t), { recursive: true, force: true });
+  return present;
+}
+async function run8(argv2) {
+  const dryRun = argv2.includes("--dry-run");
+  const root = resolve4(process.cwd());
+  if (!existsSync11(join10(root, "astro.config.mjs"))) {
+    console.error("webm clean: no astro.config.mjs here - run it from the site root.");
+    return 1;
+  }
+  const targets = dryRun ? cleanTargets(root) : clean(root);
+  if (targets.length === 0) {
+    console.log("Nothing to clean.");
+    return 0;
+  }
+  for (const t of targets) console.log(`${dryRun ? "would remove" : "removed"}  ${t}/`);
+  if (!dryRun) console.log("\nNext `npm run dev` or `npm run build` regenerates all of it.");
+  return 0;
+}
+var CLEAN_TARGETS;
+var init_clean = __esm({
+  "src/cli/clean.ts"() {
+    "use strict";
+    CLEAN_TARGETS = ["node_modules/.vite", ".astro", "dist"];
+  }
+});
+
 // bin/webm.mjs
 init_package_root();
 import { readFileSync as readFileSync10 } from "node:fs";
-import { join as join10 } from "node:path";
-var pkg = JSON.parse(readFileSync10(join10(PACKAGE_ROOT, "package.json"), "utf8"));
+import { join as join11 } from "node:path";
+var pkg = JSON.parse(readFileSync10(join11(PACKAGE_ROOT, "package.json"), "utf8"));
 var COMMANDS = {
   new: {
     blurb: "Scaffold a new client site from a domain",
@@ -2728,6 +2770,10 @@ var COMMANDS = {
   upgrade: {
     blurb: "Move this site to a newer framework version",
     load: () => Promise.resolve().then(() => (init_upgrade(), upgrade_exports))
+  },
+  clean: {
+    blurb: "Remove node_modules/.vite, .astro and dist - the reset for a stale dev server",
+    load: () => Promise.resolve().then(() => (init_clean(), clean_exports))
   }
 };
 function usage() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparkerwebm/webmonterey",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "description": "The WebMonterey Astro framework: plumbing, design system, and Claude Code skills for client sites on Cloudflare Workers",
   "license": "MIT",
@@ -22,14 +22,14 @@
   },
   "//dependencies": "The integration wires these itself, so a client site installs only astro and this package.",
   "dependencies": {
-    "@astrojs/cloudflare": "^14.1.7",
+    "@astrojs/cloudflare": "^14.3.0",
     "@astrojs/sitemap": "^3.7.3"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",
-    "@cloudflare/workers-types": "^5.20260826.1",
+    "@cloudflare/workers-types": "^5.20260906.1",
     "@types/node": "^26.1.2",
-    "astro": "^7.1.6",
+    "astro": "^7.3.1",
     "esbuild": "^0.28.2",
     "prettier": "^3.9.6",
     "prettier-plugin-astro": "^0.14.1",

package/skills/traps/SKILL.md

@@ -165,6 +165,13 @@ either direction, and nothing warns you. Code moves on push; schema moves via
 **Astro's dev server daemonizes.** It detaches and the launching command exits, which reads as a
 crash. Manage it with `astro dev status` / `logs` / `stop`.
 
+**A dev server that 500s on every request, or serves last week's code, has a stale cache, not a
+bug in the site.** Vite's pre-bundle in `node_modules/.vite` and Astro's cache in `.astro` both
+outlive what they were built from. `astro dev stop && npx webm clean && npm run dev` is the
+reset; it removes those two and `dist`, all regenerated by the next start. The package already
+rebuilds the pre-bundle on every dev start, so the remaining case is a cache that changed
+underneath a running server.
+
 ---
 
 ## TypeScript and APIs

package/skills/webmaster/SKILL.md

@@ -23,12 +23,18 @@ interface WebmasterPageProps {
   description: string; // text - also the meta description
   intro: string; // HTML - the first paragraph, agency link already in it
   body: string[]; // HTML - one entry per remaining paragraph
+  cta: { label: string; href: string }; // the outbound button: text, and the attributed URL
 }
 ```
 
 `intro` and `body` are already HTML: the agency link with its UTM parameters, and the copy's own
 inline formatting (`**bold**`, `_italic_`, `[text](/url)`) rendered and escaped. Render them with
-`set:html`. `title` and `description` are text.
+`set:html`. `title` and `description` are text. The client's name is already filled in wherever
+the copy says `{client}`.
+
+`cta` is the "Visit WebMonterey" button. Render it as a link in the site's outline button style,
+with `AGENCY_LINK_ATTRS` (from the same import) spread on: it leaves the site, and those are the
+attributes the intro link carries.
 
 **The component carries no copy of its own.** Not a heading, not a caption, not a sentence. The
 words are the same on every site; when a client wants them changed, that is `copy.webmaster` in
@@ -52,11 +58,14 @@ site; replace the element names and classes with the document block's own.
  * The /webmaster page body. The package hands in the copy; this lays it out like the site's
  * other document pages. See /webm:webmaster.
  */
-import type { WebmasterPageProps } from '@cparkerwebm/webmonterey/webmonterey/webmaster';
+import {
+  AGENCY_LINK_ATTRS,
+  type WebmasterPageProps,
+} from '@cparkerwebm/webmonterey/webmonterey/webmaster';
 
 type Props = WebmasterPageProps;
 
-const { title, intro, body } = Astro.props;
+const { title, intro, body, cta } = Astro.props;
 ---
 
 <section class="webm-section" data-space="lg">
@@ -68,24 +77,32 @@ const { title, intro, body } = Astro.props;
       <div class="doc__panel">
         <p set:html={intro} />
         {body.map((paragraph) => <p set:html={paragraph} />)}
+        <p>
+          <a class="button button--outline" href={cta.href} {...AGENCY_LINK_ATTRS}>{cta.label}</a>
+        </p>
       </div>
     </article>
   </div>
 </section>
 ```
 
+`button button--outline` stands for whatever this site's outline button class is - the one its
+own blocks use.
+
 If the document block is itself a component that takes `title` and a slot or `html` prop, render
 it directly rather than copying its markup:
 
 ```astro
 ---
+import { AGENCY_LINK_ATTRS } from '@cparkerwebm/webmonterey/webmonterey/webmaster';
 import Doc from '../content/content-000001/content-000001.astro';
-const { title, intro, body } = Astro.props;
+const { title, intro, body, cta } = Astro.props;
 ---
 
 <Doc title={title}>
   <p set:html={intro} />
   {body.map((paragraph) => <p set:html={paragraph} />)}
+  <p><a class="button button--outline" href={cta.href} {...AGENCY_LINK_ATTRS}>{cta.label}</a></p>
 </Doc>
 ```
 
@@ -109,8 +126,10 @@ Then read `dist/client/webmaster/index.html`:
 
 - the body is the new markup, and there is no `webm-stack` div left from the built-in layout
 - the `<h1>` is the package's title (`Our Webmaster` unless `copy.webmaster.title` is set)
-- the first paragraph has one `<a href="https://webmonterey.com/?utm_source=client…"
-target="_blank" rel="noopener">` and nothing else links off-site
+- the first paragraph names this client and has one
+  `<a href="https://webmonterey.com/?utm_source=client…" target="_blank" rel="noopener">`; the
+  "Visit WebMonterey" button is the only other off-site link, to the same URL with the same
+  attributes
 - `<title>`, `meta name="description"`, `og:image` (`/webmaster/og.png`) and the
   `application/ld+json` block are present and unchanged from before the export
 

package/src/cli/clean.test.ts

@@ -0,0 +1,48 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CLEAN_TARGETS, clean, cleanTargets } from './clean.ts';
+
+const site = (dirs: string[]) => {
+  const root = mkdtempSync(join(tmpdir(), 'webm-clean-'));
+  for (const d of dirs) {
+    mkdirSync(join(root, d), { recursive: true });
+    writeFileSync(join(root, d, 'x'), '');
+  }
+  return root;
+};
+
+test('clean removes only the generated directories and reports them in order', () => {
+  const root = site(['dist', '.astro', 'node_modules/.vite', 'node_modules/astro', 'src/pages']);
+  try {
+    assert.deepEqual(clean(root), [...CLEAN_TARGETS]);
+    for (const t of CLEAN_TARGETS) assert.equal(existsSync(join(root, t)), false, t);
+    assert.equal(existsSync(join(root, 'node_modules/astro/x')), true, 'installed packages stay');
+    assert.equal(existsSync(join(root, 'src/pages/x')), true, 'source stays');
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('clean is idempotent: the second run finds nothing', () => {
+  const root = site(['dist', '.astro']);
+  try {
+    assert.deepEqual(clean(root), ['.astro', 'dist']);
+    assert.deepEqual(clean(root), []);
+    assert.deepEqual(cleanTargets(root), []);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('cleanTargets reports without removing', () => {
+  const root = site(['dist']);
+  try {
+    assert.deepEqual(cleanTargets(root), ['dist']);
+    assert.equal(existsSync(join(root, 'dist/x')), true);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/cli/clean.ts

@@ -0,0 +1,62 @@
+/*
+ * `webm clean` - throw away everything a build or a dev server can regenerate.
+ *
+ * WHY A COMMAND. A dev session that has gone stale - Vite serving a pre-bundle whose hash no
+ * longer matches, a content-layer cache that predates a schema edit, a dist/ from a branch that
+ * is no longer checked out - is fixed by deleting three directories, and knowing which three is
+ * the whole trick. Written down in a skill it is prose; here it is one word, and a session in a
+ * client repo can run it without knowing what Vite is.
+ *
+ * Nothing here is the site's. Every path is generated, gitignored, and rebuilt by the next
+ * `astro dev` or `astro build`. The three are:
+ *
+ *   node_modules/.vite   Vite's dependency pre-bundle. Astro dev reads it on every request and
+ *                        500s on all of them once it is stale - see optimizeDeps in the
+ *                        integration for the mechanism.
+ *   .astro               Astro's own cache: content-layer data, generated types, the dev server's
+ *                        lock and state files. `astro dev --force` clears part of this; removing
+ *                        the directory clears all of it.
+ *   dist                 The last build. Kept out of the way so `webm compare` and `astro
+ *                        preview` cannot answer from an older branch's output.
+ *
+ * `--dry-run` lists what would go and touches nothing.
+ */
+import { existsSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+/** What a clean removes, relative to the site root. Order is the order they are reported. */
+export const CLEAN_TARGETS = ['node_modules/.vite', '.astro', 'dist'] as const;
+
+/** The targets that exist under `root` right now, as relative paths. */
+export function cleanTargets(root: string): string[] {
+  return CLEAN_TARGETS.filter((t) => existsSync(join(root, t)));
+}
+
+/**
+ * Remove every target that exists and return what was removed. Idempotent: a second run finds
+ * nothing and removes nothing, which is what a repeatable reset should do.
+ */
+export function clean(root: string): string[] {
+  const present = cleanTargets(root);
+  for (const t of present) rmSync(join(root, t), { recursive: true, force: true });
+  return present;
+}
+
+export async function run(argv: string[]): Promise<number> {
+  const dryRun = argv.includes('--dry-run');
+  const root = resolve(process.cwd());
+
+  if (!existsSync(join(root, 'astro.config.mjs'))) {
+    console.error('webm clean: no astro.config.mjs here - run it from the site root.');
+    return 1;
+  }
+
+  const targets = dryRun ? cleanTargets(root) : clean(root);
+  if (targets.length === 0) {
+    console.log('Nothing to clean.');
+    return 0;
+  }
+  for (const t of targets) console.log(`${dryRun ? 'would remove' : 'removed'}  ${t}/`);
+  if (!dryRun) console.log('\nNext `npm run dev` or `npm run build` regenerates all of it.');
+  return 0;
+}

package/src/includes/webmonterey/copy-defaults.ts

@@ -71,11 +71,18 @@ export interface Copy {
    * The /webmaster page. `intro` wraps the agency link: `before` <a>WebMonterey</a> `after`.
    * `intro` and `body` take the inline prose subset - `**bold**`, `_italic_`, `[text](/url)`.
    */
+  /*
+   * Every string here may carry `{client}`, filled with the site's client name at render. It is
+   * what makes the page different on every site: the same paragraph on a hundred sites is
+   * duplicate content, and a page that names the client is not.
+   */
   webmaster: {
     title: string;
     description: string;
     intro: { before: string; after: string };
     body: string[];
+    /** The label of the outbound button to the agency. */
+    cta: string;
   };
 }
 
@@ -138,16 +145,17 @@ export const DEFAULT_COPY: Copy = {
   webmaster: {
     title: 'Our Webmaster',
     description:
-      'This custom website was designed, built and managed by WebMonterey, a webmaster service in Monterey, California.',
+      'This {client} custom website was designed, built and managed by WebMonterey, a webmaster service in Monterey, California.',
     intro: {
-      before: 'This custom website was designed, built and managed by',
+      before: 'This {client} custom website was designed, built and managed by',
       after:
-        ', a webmaster service in Monterey, California. WebMonterey handles the hosting, security, strategy and ongoing care of the site so that we can focus on what we do.',
+        ', a webmaster service in Monterey, California. WebMonterey handles web hosting, security, strategy and ongoing care of our site.',
     },
     /* Bold on purpose: the contact instruction is the paragraph a visitor with a problem needs. */
     body: [
-      "**If you have a question about this website, notice something that isn't working, or have trouble using a page, please let WebMonterey know and they will take care of it.**",
+      "**If you have a question about the {client} website, notice something that isn't working, or have trouble using a page, please let WebMonterey know and they will take care of it.**",
     ],
+    cta: 'Visit WebMonterey',
   },
 };
 

package/src/includes/webmonterey/webmaster/webmaster.test.ts

@@ -10,7 +10,10 @@ import {
   introHtml,
   webmasterPageProps,
   WEBMASTER_PATH,
+  AGENCY_LINK_ATTRS,
+  personalize,
 } from './webmaster.ts';
+import { DEFAULT_COPY } from '../copy-defaults.ts';
 
 /*
  * Webmaster.astro read as SOURCE, because it cannot be imported here: an .astro file only
@@ -99,16 +102,16 @@ test('introHtml escapes the copy and the href', () => {
   assert.ok(html.endsWith('"q"'));
 });
 
+const TEXT = {
+  title: 'T',
+  description: 'D',
+  intro: { before: 'Built by', after: ', **really**.' },
+  body: ["**If it isn't working, say so.**", 'See [the policy](/privacy).'],
+  cta: 'Visit',
+};
+
 test('the copy carries the inline prose subset, in the intro and the body', () => {
-  const props = webmasterPageProps(
-    {
-      title: 'T',
-      description: 'D',
-      intro: { before: 'Built by', after: ', **really**.' },
-      body: ["**If it isn't working, say so.**", 'See [the policy](/privacy).'],
-    },
-    'https://x.test/',
-  );
+  const props = webmasterPageProps(TEXT, 'https://x.test/');
   assert.equal(props.title, 'T');
   assert.equal(props.description, 'D');
   assert.ok(props.intro.endsWith('</a>, <strong>really</strong>.'));
@@ -118,15 +121,68 @@ test('the copy carries the inline prose subset, in the intro and the body', () =
   ]);
 });
 
+test('the cta is the copy label and the same attributed href the intro links to', () => {
+  const props = webmasterPageProps(TEXT, 'https://x.test/?utm_source=client');
+  assert.deepEqual(props.cta, { label: 'Visit', href: 'https://x.test/?utm_source=client' });
+  assert.match(props.intro, /href="https:\/\/x\.test\/\?utm_source=client"/);
+});
+
+/* ── the client's name, so no two sites carry the same paragraph ────────────────────────── */
+
+test('personalize fills {client} and leaves other braces alone', () => {
+  assert.equal(personalize('This {client} site, {other}.', 'Acme'), 'This Acme site, {other}.');
+});
+
+test('personalize drops the placeholder and its space on an unconfigured site', () => {
+  assert.equal(personalize('This {client} custom website', ''), 'This custom website');
+  assert.equal(personalize('about the {client} website', ''), 'about the website');
+  assert.equal(personalize('{client} is here', ''), 'is here');
+});
+
+test('the client name reaches every prop, and is escaped like text', () => {
+  const props = webmasterPageProps(
+    {
+      title: '{client} webmaster',
+      description: 'About {client}',
+      intro: { before: 'The {client} site, by', after: ', for {client}.' },
+      body: ['Ask {client}.'],
+      cta: 'Visit, {client}',
+    },
+    'https://x.test/',
+    'Smith & Sons',
+  );
+  assert.equal(props.title, 'Smith & Sons webmaster');
+  assert.equal(props.description, 'About Smith & Sons');
+  assert.ok(props.intro.startsWith('The Smith &amp; Sons site, by <a '), props.intro);
+  assert.ok(props.intro.endsWith('</a>, for Smith &amp; Sons.'), props.intro);
+  assert.deepEqual(props.body, ['Ask Smith &amp; Sons.']);
+  assert.equal(props.cta.label, 'Visit, Smith & Sons');
+});
+
+test('the default copy names the client in the description, the intro and the contact line', () => {
+  const props = webmasterPageProps(DEFAULT_COPY.webmaster, 'https://x.test/', 'Acme Co');
+  assert.match(props.description, /^This Acme Co custom website/);
+  assert.match(props.intro, /^This Acme Co custom website was designed, built and managed by <a /);
+  assert.match(props.body[0]!, /about the Acme Co website/);
+  assert.equal(props.cta.label, 'Visit WebMonterey');
+});
+
 test('the built-in page renders the same intro string a site layout receives', () => {
   /*
    * One source for the agency link. The page used to build its own <a> in the template, which
-   * is how a second copy of the attributes would drift; now both layouts render introHtml.
+   * is how a second copy of the attributes would drift; now both layouts render introHtml. The
+   * one <a> the template does write is the button, and its attributes are the spread constant,
+   * never typed out.
    */
   const page = readFileSync(new URL('../../../pages/webmaster.astro', import.meta.url), 'utf8');
-  const template = page.slice(page.lastIndexOf('---'));
+  const template = page.slice(page.indexOf('---', 3));
   assert.match(template, /<p set:html=\{props\.intro\} \/>/);
-  assert.doesNotMatch(template, /<a\s/, 'the page must not assemble the agency link itself');
+  const anchors = template.match(/<a\s[^>]*>/g) ?? [];
+  assert.equal(anchors.length, 1, 'the template writes exactly one link: the button');
+  assert.match(anchors[0]!, /href=\{props\.cta\.href\}/);
+  assert.match(anchors[0]!, /\{\.\.\.AGENCY_LINK_ATTRS\}/);
+  assert.doesNotMatch(anchors[0]!, /target=|rel=/, 'attributes come from the constant only');
+  assert.deepEqual(AGENCY_LINK_ATTRS, { target: '_blank', rel: 'noopener' });
   const html = introHtml({ before: '', after: '' }, 'https://x.test/');
   assert.match(html, /target="_blank"/);
   assert.match(html, /rel="noopener"/);

package/src/includes/webmonterey/webmaster/webmaster.ts

@@ -26,6 +26,7 @@
  */
 
 import { escapeHtml, renderInline } from '../prose/inline.ts';
+import { fill } from '../copy-defaults.ts';
 
 /** The credit wording. Rendered verbatim on the site and in email. */
 export const CREDIT_TEXT = 'Powered by WebMonterey';
@@ -108,6 +109,33 @@ export interface WebmasterPageProps {
   intro: string;
   /** The remaining paragraphs' inner HTML, one entry per `<p>`. */
   body: string[];
+  /**
+   * The outbound button: `copy.webmaster.cta` as text, and the same attributed agency URL the
+   * intro links to. Render it as a link with `AGENCY_LINK_ATTRS` spread on - it leaves the site.
+   */
+  cta: { label: string; href: string };
+}
+
+/**
+ * The attributes every link to the agency carries: a new tab because it leaves the site,
+ * `noopener` without `noreferrer` because the referrer IS the attribution. One constant, spread
+ * by the built-in page and by introHtml, so the intro link and the button cannot disagree.
+ */
+export const AGENCY_LINK_ATTRS = { target: '_blank', rel: 'noopener' } as const;
+
+/**
+ * `{client}` in a copy string becomes the client's name; everything else is left alone.
+ *
+ * WHY THE PAGE NAMES THE CLIENT. The same paragraph on every site the agency builds is duplicate
+ * content across the fleet. A paragraph that says whose website this is is not, and it reads as
+ * written for the client rather than pasted. `client` is '' on a site that has not set one yet
+ * - the CHANGEME placeholder never reaches a page - and then the placeholder simply drops out
+ * and the doubled space with it: "This custom website" rather than "This  custom website".
+ *
+ * Runs BEFORE the inline renderer, so a name with an ampersand is escaped like any other text.
+ */
+export function personalize(text: string, client: string): string {
+  return fill(text, { client }).replace(/ {2,}/g, ' ').trim();
 }
 
 /**
@@ -122,24 +150,34 @@ export interface WebmasterPageProps {
  * and an element on separate lines, and "managed byWebMonterey" shipped.
  */
 export function introHtml(intro: { before: string; after: string }, href: string): string {
-  const link = `<a href="${escapeHtml(href)}" target="_blank" rel="noopener">${escapeHtml(AGENCY.name)}</a>`;
+  const attrs = Object.entries(AGENCY_LINK_ATTRS)
+    .map(([k, v]) => `${k}="${v}"`)
+    .join(' ');
+  const link = `<a href="${escapeHtml(href)}" ${attrs}>${escapeHtml(AGENCY.name)}</a>`;
   return `${renderInline(intro.before)} ${link}${renderInline(intro.after)}`;
 }
 
-/** The whole prop set, from the merged copy and the attributed agency link. */
+/**
+ * The whole prop set, from the merged copy, the attributed agency link and the client's name.
+ * `client` is '' when the site has not set one - see personalize.
+ */
 export function webmasterPageProps(
   text: {
     title: string;
     description: string;
     intro: { before: string; after: string };
     body: string[];
+    cta: string;
   },
   href: string,
+  client = '',
 ): WebmasterPageProps {
+  const p = (s: string) => personalize(s, client);
   return {
-    title: text.title,
-    description: text.description,
-    intro: introHtml(text.intro, href),
-    body: text.body.map(renderInline),
+    title: p(text.title),
+    description: p(text.description),
+    intro: introHtml({ before: p(text.intro.before), after: p(text.intro.after) }, href),
+    body: text.body.map((paragraph) => renderInline(p(paragraph))),
+    cta: { label: p(text.cta), href },
   };
 }

package/src/integration/config.test.ts

@@ -0,0 +1,50 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { sitePage } from './config.ts';
+
+/*
+ * WHY THIS EXISTS. The integration injects the package's /404 on every site, and Astro warns on
+ * every build of a site that also has src/pages/404.astro: "A static route cannot be defined
+ * more than once … will result in a hard error in following versions". The fix is to not inject
+ * when the site has its own, and this is the file check that decides it.
+ */
+
+const withSrc = (files: string[], fn: (src: string) => void) => {
+  const dir = mkdtempSync(join(tmpdir(), 'webm-cfg-'));
+  try {
+    mkdirSync(join(dir, 'pages'), { recursive: true });
+    for (const f of files) writeFileSync(join(dir, 'pages', f), '');
+    fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+};
+
+test('sitePage is null when src/pages has no file for the route', () => {
+  withSrc(['index.astro', 'contact.astro'], (src) => {
+    assert.equal(sitePage(src, '404'), null);
+  });
+});
+
+test('sitePage finds a 404 in every form Astro treats as a route', () => {
+  for (const ext of ['astro', 'md', 'mdx', 'html', 'ts', 'js']) {
+    withSrc([`404.${ext}`], (src) => {
+      assert.equal(sitePage(src, '404'), join(src, 'pages', `404.${ext}`), ext);
+    });
+  }
+});
+
+test('sitePage ignores files that are not routes', () => {
+  withSrc(['404.css', '404.json', '404.astro.bak'], (src) => {
+    assert.equal(sitePage(src, '404'), null);
+  });
+});
+
+test('sitePage is exact about the stem: 404-old is not 404', () => {
+  withSrc(['404-old.astro', '4040.astro'], (src) => {
+    assert.equal(sitePage(src, '404'), null);
+  });
+});

package/src/integration/config.ts

@@ -94,3 +94,25 @@ export function loadForms(root: string): Record<string, unknown> {
   }
   return out;
 }
+
+/*
+ * THE EXTENSIONS ASTRO TREATS AS A PAGE OR ENDPOINT under src/pages. The docs name .astro and .md
+ * for a custom 404 and .html for plain pages; .mdx arrives with the MDX integration; .ts and .js
+ * are endpoints. Anything else in src/pages is not a route and cannot collide with one.
+ */
+const PAGE_EXTENSIONS = ['astro', 'md', 'mdx', 'html', 'ts', 'js'] as const;
+
+/**
+ * The site's own file for a top-level route, or null when it has none.
+ *
+ * `name` is the route's file stem - `404` for `/404` - and `srcDir` is the site's src directory
+ * as a path, not a URL. Pure, so the integration's "do not inject what the site already has" rule
+ * has a test that runs under `node --test` with a temp directory and nothing else.
+ */
+export function sitePage(srcDir: string, name: string): string | null {
+  for (const ext of PAGE_EXTENSIONS) {
+    const file = join(srcDir, 'pages', `${name}.${ext}`);
+    if (existsSync(file)) return file;
+  }
+  return null;
+}

package/src/integration/index.ts

@@ -30,7 +30,7 @@ import { fileURLToPath } from 'node:url';
 
 import { compileToCss } from '../design/compile.ts';
 import { imageSize } from './image-size.ts';
-import { loadForms, loadSiteFiles, resolveSiteUrl } from './config.ts';
+import { loadForms, loadSiteFiles, resolveSiteUrl, sitePage } from './config.ts';
 import {
   APP_DIR,
   appEnabled,
@@ -251,6 +251,20 @@ export default function webmonterey(options: WebmontereyOptions = {}): AstroInte
              */
             optimizeDeps: {
               exclude: ['@astrojs/cloudflare/handler'],
+              /*
+               * REBUILD THE PRE-BUNDLE ON EVERY DEV START. The cache in node_modules/.vite
+               * outlives the things it was built from - a package update, a branch switch, an
+               * `astro check` that re-optimised under a server that has since stopped - and a
+               * stale one is the dev server 500ing on every request, or serving last week's
+               * copy of a dependency. Forcing costs a few seconds once per start; trusting the
+               * cache costs a session's worth of "restart it and clear the cache". Dev only:
+               * a build does not use the pre-bundle, and this flag is a no-op there anyway.
+               *
+               * Startup only, and that is the limit of it: a re-optimisation triggered while
+               * the server is running still swaps the hash underneath it. `webm clean` is the
+               * reset for that, and the handler exclusion above removes the known trigger.
+               */
+              force: command === 'dev',
             },
             ssr: {
               /*
@@ -468,10 +482,21 @@ export default function webmonterey(options: WebmontereyOptions = {}): AstroInte
          *
          * Astro turns the `/404` route into 404.html, which the Workers asset router serves for
          * any unmatched path. A site that wants its own overrides this the ordinary Astro way, by
-         * having src/pages/404.astro - a file in the site beats an injected route, which is the
-         * child-theme rule holding without anything special here.
+         * having src/pages/404.astro - and then the package MUST NOT inject its own. It used to,
+         * relying on the site's file winning the collision. It did win, but Astro warns on every
+         * build ("A static route cannot be defined more than once … will result in a hard error
+         * in following versions of Astro"), and nothing in the routing docs promises a file beats
+         * an injected route. So the site's file is checked for first, in every form Astro treats
+         * as a route, and the package's page is injected only into the gap. See sitePage.
          */
-        injectRoute({ pattern: '/404', entrypoint: '@cparkerwebm/webmonterey/pages/404.astro' });
+        const own404 = sitePage(config.srcDir.pathname, '404');
+        if (own404) {
+          logger.debug(
+            `the site's own ${own404.slice(root.length)} is the 404; not injecting the package's`,
+          );
+        } else {
+          injectRoute({ pattern: '/404', entrypoint: '@cparkerwebm/webmonterey/pages/404.astro' });
+        }
       },
     },
   };

package/src/integration/virtual.d.ts

@@ -91,8 +91,9 @@ declare module 'virtual:webm/registry' {
    * pages rather than as the package's `<h1>` and stack of paragraphs.
    *
    * Receives `WebmasterPageProps` from `includes/webmonterey/webmaster/webmaster.ts`:
-   * `{ title, description, intro, body }`, the merged `copy.webmaster` - `intro` and `body` as
-   * HTML through the inline prose renderer, the agency link already in `intro`. The component
+   * `{ title, description, intro, body, cta }`, the merged `copy.webmaster` with the client's
+   * name filled in - `intro` and `body` as HTML through the inline prose renderer, the agency
+   * link already in `intro`, `cta` the outbound button's label and href. The component
    * lays the words out and carries no copy of its own. The route, the `<head>`, the share image and the JSON-LD stay the package's.
    * Null means the built-in layout, `pageHeader` seam included.
    */

package/src/pages/webmaster.astro

@@ -26,11 +26,12 @@ import Base from '../layouts/base.astro';
 import { copy } from '../includes/webmonterey/copy.ts';
 import {
   AGENCY,
+  AGENCY_LINK_ATTRS,
   creditUrl,
   webmasterPageProps,
   WEBMASTER_OG_PATH,
 } from '../includes/webmonterey/webmaster/webmaster.ts';
-import { domain, hasDomain } from '../includes/webmonterey/site.ts';
+import { client, domain, hasClient, hasDomain } from '../includes/webmonterey/site.ts';
 import { compact, renderJsonLd } from '../includes/webmonterey/structured-data/nodes.ts';
 import { pageHeader, webmasterPage } from 'virtual:webm/registry';
 import ogImage from 'virtual:webm/webmaster-og';
@@ -41,11 +42,17 @@ const WebmasterPage = webmasterPage;
 const text = copy.webmaster;
 const agencyHref = hasDomain ? creditUrl(domain, 'website') : AGENCY.url;
 /*
- * The words, resolved once for both layouts: the intro with the agency link in it, every
- * paragraph through the inline prose renderer, so `**bold**` in copy.webmaster works here
- * exactly as it does in page JSON.
+ * The words, resolved once for both layouts: the client's name filled into every `{client}`,
+ * the intro with the agency link in it, every paragraph through the inline prose renderer, so
+ * `**bold**` in copy.webmaster works here exactly as it does in page JSON.
+ */
+const props = webmasterPageProps(text, agencyHref, hasClient ? client : '');
+/*
+ * FROM HERE ON, `props`, NEVER `text`. The title and description reach the <title>, the meta
+ * description, the Open Graph tags, the page header and the JSON-LD from props, because that is
+ * where `{client}` has been filled in. The first cut read `text` for those and shipped a meta
+ * description that said "This {client} custom website" - the e2e caught it, the example did not.
  */
-const props = webmasterPageProps(text, agencyHref);
 
 /*
  * The graph needs a real origin for stable @id values, which is the same gate the canonical tag
@@ -60,8 +67,8 @@ if (Astro.site && !build.preview) {
       '@type': 'WebPage',
       '@id': `${url}#webpage`,
       url,
-      name: text.title,
-      description: text.description,
+      name: props.title,
+      description: props.description,
       isPartOf: { '@id': new URL('#website', Astro.site).href },
       about: { '@id': AGENCY.id },
       inLanguage: 'en',
@@ -80,8 +87,8 @@ if (Astro.site && !build.preview) {
 ---
 
 <Base
-  title={text.title}
-  description={text.description}
+  title={props.title}
+  description={props.description}
   shareImage={WEBMASTER_OG_PATH}
   shareImageWidth={ogImage.width}
   shareImageHeight={ogImage.height}
@@ -110,11 +117,11 @@ if (Astro.site && !build.preview) {
            * on the site; the router's plain <h1> otherwise. Same fallback the block router uses.
            */
           PageHeader ? (
-            <PageHeader title={text.title} description={text.description} />
+            <PageHeader title={props.title} description={props.description} />
           ) : (
             <section class="webm-section" data-space="sm">
               <div class="webm-container" data-width="text">
-                <h1>{text.title}</h1>
+                <h1>{props.title}</h1>
               </div>
             </section>
           )
@@ -134,6 +141,16 @@ if (Astro.site && !build.preview) {
               {props.body.map((paragraph) => (
                 <p set:html={paragraph} />
               ))}
+              {/*
+               * The button, to the same attributed URL. Outline rather than filled, so it reads
+               * as an invitation on a page about the site, not a call to action for the agency.
+               * The same attributes as the intro link, from the same constant.
+               */}
+              <p>
+                <a class="webm-webmaster-cta" href={props.cta.href} {...AGENCY_LINK_ATTRS}>
+                  {props.cta.label}
+                </a>
+              </p>
             </div>
           </div>
         </section>
@@ -141,3 +158,29 @@ if (Astro.site && !build.preview) {
     )
   }
 </Base>
+
+{
+  /*
+  GLOBAL, NOT SCOPED, on purpose. A scoped style would stamp a data-astro-cid hash on every
+  element of this page, and examples/minimal asserts the built-in <main> byte for byte so the
+  fallback cannot drift under the seam. The class is package-prefixed and used nowhere else,
+  which is all scoping would buy here. Tokens only: the outline is the link colour, the radius
+  and border width are the site's.
+*/
+}
+<style is:global>
+  @layer webm.components.core {
+    .webm-webmaster-cta {
+      display: inline-block;
+      padding: var(--webm-space-2xs) var(--webm-space-md);
+      border: var(--webm-border-width-2) solid currentColor;
+      border-radius: var(--webm-radius-md);
+      color: var(--webm-link);
+      text-decoration: none;
+    }
+
+    .webm-webmaster-cta:hover {
+      color: var(--webm-link-hover);
+    }
+  }
+</style>

package/template/site/CLAUDE.md

@@ -37,6 +37,7 @@ what it forked from and why, so the next person knows it is deliberate.
 | `npm run preview` | **a real build on real workerd**                           |
 | `npm run check`   | types and content schema                                   |
 | `npx webm doctor` | the things that fail silently                              |
+| `npx webm clean`  | reset a stale dev server: drops `.vite`, `.astro`, `dist`  |
 | `npm run format`  | prettier                                                   |
 
 **Run `npm run preview`, not `dev`, before merging anything** that touches styles,