@cparkerwebm/webmonterey 1.2.0 → 1.4.0

package/skills/start/SKILL.md

@@ -97,23 +97,70 @@ like a bot does.
 **Every route with `export const prerender = false` goes in `run_worker_first`, in both slash
 forms.** Miss one and it returns 200 to curl and a 404 page to Chrome. `webm doctor` checks.
 
-## 5. Workers Builds
+## 5. Create the Worker - once, from the laptop
 
-Connect the repo in the Cloudflare dashboard: **Workers & Pages → Create → Import a repository**.
-The Worker name must be the slug exactly as `wrangler.jsonc` has it - Workers Builds fails on a
-mismatch.
+Guarded and re-runnable: skip this step when the Worker already exists.
 
-No build variables are needed. **Push to deploy from then on** - a `wrangler deploy` from a
-laptop creates a version no build produced, so history stops describing what is live, and the
-next push reverts it.
+```sh
+npx wrangler deployments list --name <slug>   # a list: it exists. "does not exist [code: 10007]": create it
+```
+
+The name is `name` in `wrangler.jsonc`. When there is nothing:
+
+```sh
+npm run build            # a real build; `dev` proves nothing here
+npx wrangler deploy
+```
+
+**This is the ONLY laptop deploy a site ever gets.** Before Workers Builds is connected, one
+deploy is exactly how the Worker comes into existence. After it is connected (step 6) a laptop
+deploy is the mistake: a version no build produced, which the next push reverts. This skill used
+to stop here and say to create the Worker in the dashboard by hand, and on one site nobody did -
+the result was a repo, a D1 database and nothing serving. `webm doctor` now warns on that.
+
+The deploy provisions something `wrangler.jsonc` does not name, and that is expected: the Astro
+Cloudflare adapter adds a `SESSION` KV binding, which wrangler auto-provisions as
+`<slug>-session`. Do not add it to the config by hand.
+
+Then verify. Wait a minute first - a brand-new Worker can return `error code: 1042` on valid
+paths for about that long. In a real browser with the console open, load
+`https://<slug>.<account>.workers.dev`: the home page renders, the console is clean. Then check
+one on-demand route with a document-style request, if the site has one yet - a fresh scaffold's
+only Worker route is the form action, which is POST-only:
+
+```sh
+curl -sI -H 'Sec-Fetch-Dest: document' https://<slug>.<account>.workers.dev/<on-demand-route>
+```
+
+The asset router keys off that header and plain curl does not send it, so a route that is 200 to
+`curl` and 404 here is missing from `run_worker_first` (step 4).
+
+## 6. Connect the repo
+
+In the dashboard, on the Worker that now exists: **Settings → Builds → connect `<org>/<slug>`**,
+production branch `main`, no build variables. Connecting a repo to an EXISTING Worker is the
+smaller step - importing a repository and typing the Worker name in by hand is where the name
+mismatch Workers Builds fails on comes from.
+
+**Push to deploy from then on.** The first push supersedes the laptop version. A `wrangler
+deploy` from a laptop after this point creates a version no build produced, so history stops
+describing what is live and the next push reverts it.
+
+Confirm it took:
+
+```sh
+npx wrangler deployments list --name <slug>
+```
+
+The newest deployment's Source is no longer `Upload`.
 
-## 6. Verify the first deploy
+## 7. Verify the first push
 
-Wait a minute after the build reports success - a brand-new Worker can return `error code:
-1042` on valid paths for about that long. Then, in a real browser with the console open, load
-the `workers.dev` URL. The home page renders, the console is clean.
+Wait a minute after the build reports success - the 1042 window again - then load the
+`workers.dev` URL in a real browser with the console open. The home page renders, the console is
+clean.
 
-## 7. Hand over
+## 8. Hand over
 
 Workers Builds comments the preview URL on every PR - that is the client's review link. Preview
 hostnames use the slug, so Chrome's lookalike warning should not appear; if it does, it is a
@@ -121,7 +168,11 @@ URL-shape false positive and **Ignore is safe**.
 
 A preview build is safe to hand out: every page is noindex, there is no sitemap, robots.txt
 disallows everything, analytics does not load, and mail is redirected to `stagingEmail`. The
-client can click anything. The production branch is `main`; anything else previews.
+client can click anything. **Every build of this site is a preview while `environment` is
+`staging`** - `main` and the laptop included - so nothing is indexable before `/webm:launch`
+flips it, and that flip is what makes the site indexable. On a launched site the production
+branch is `main`; anything else previews.
 
-Next: `/webm:new-component` for each block, then `/webm:launch` when the site is
+Next: `/webm:new-component` for each block, `/webm:webmaster` once the site has its document
+block so the package's `/webmaster` page shares its layout, then `/webm:launch` when the site is
 content-complete and approved on a preview.

package/skills/traps/SKILL.md

@@ -329,6 +329,14 @@ divert every enquiry the day a site answers on `www.`.
 nightly sweep — the check that reads a hostname cannot see a cron at all. This is why the switch
 is config rather than something derived from the URL.
 
+**A staging site is a preview build everywhere, and flipping `environment` is what makes it
+indexable.** On `staging` every build — a branch, `main`, a laptop — is noindex on every page with
+no canonical, no sitemap, `Disallow: /` and no Google Tag Manager. So a site that has not launched
+cannot be indexed on its `workers.dev` URL, and a launched site left on `staging` after 1.3.0
+drops out of search with no symptom on the page. `webm doctor` fails the second; `/webm:launch`
+flips the switch only once the custom domain is live. A branch other than `main` previews
+regardless of the switch.
+
 **Check the client's existing DMARC before adding a sending subdomain.** A DMARC record on
 `example.com` applies to its subdomains by default. If the client publishes `p=reject` and DKIM on
 the new subdomain is not right, **every message vanishes** — no bounce, no error, nothing in the

package/skills/webmaster/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: webmaster
+description: Make the package's /webmaster page look like this site's other document pages by exporting a `webmasterPage` layout component from the registry. Use for "the webmaster page looks different", "style /webmaster like /privacy", "webmaster page layout", "webmasterPage".
+---
+
+# The `/webmaster` page
+
+**The package owns the page; this site may own its shape.** `/webmaster` is injected on every
+site: who built it, who to call. The route, the words, the document title, the meta description,
+the share image and the agency JSON-LD are the package's, so the page says the same thing on
+every site. Without help it renders as an `<h1>` (or this site's `pageHeader`) and a stack of
+paragraphs - which looks like a different site the moment the site's own document pages have a
+richer layout.
+
+**Do not add `src/pages/webmaster.astro`.** It collides with the injected route, and the injected
+route wins. The seam is a registry export.
+
+## What the component receives
+
+```ts
+interface WebmasterPageProps {
+  title: string; // text - also the document title
+  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
+}
+```
+
+`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.
+
+**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
+`webmonterey.json` (`title`, `description`, `intro.before`, `intro.after`, `body[]`), never the
+component.
+
+## 1. Find this site's document layout
+
+Look at how the privacy or terms page is rendered - usually one long-form block under
+`src/components/content/`. The webmaster page should reuse **that block's markup and classes**,
+so a change to the document style reaches both.
+
+## 2. Write the component
+
+`src/components/general/webmaster-page.astro`. The reference below is complete and works on any
+site; replace the element names and classes with the document block's own.
+
+```astro
+---
+/*
+ * 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';
+
+type Props = WebmasterPageProps;
+
+const { title, intro, body } = Astro.props;
+---
+
+<section class="webm-section" data-space="lg">
+  <div class="webm-container" data-width="text">
+    <article class="doc">
+      <header class="doc__head">
+        <h1 class="doc__title">{title}</h1>
+      </header>
+      <div class="doc__panel">
+        <p set:html={intro} />
+        {body.map((paragraph) => <p set:html={paragraph} />)}
+      </div>
+    </article>
+  </div>
+</section>
+```
+
+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 Doc from '../content/content-000001/content-000001.astro';
+const { title, intro, body } = Astro.props;
+---
+
+<Doc title={title}>
+  <p set:html={intro} />
+  {body.map((paragraph) => <p set:html={paragraph} />)}
+</Doc>
+```
+
+## 3. Export it
+
+```ts
+// src/components/registry.ts
+export { default as webmasterPage } from './general/webmaster-page.astro';
+```
+
+Not an entry in `blocks` - it is not addressable from page JSON. A named export beside
+`pageHeader` and `structuredData`.
+
+## 4. Verify
+
+```sh
+npm run build
+```
+
+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
+- `<title>`, `meta name="description"`, `og:image` (`/webmaster/og.png`) and the
+  `application/ld+json` block are present and unchanged from before the export
+
+Then push and compare `/webmaster` against `/privacy` on the preview URL: same heading style,
+same panel, the package's words.

package/src/cli/checks.test.ts

@@ -22,6 +22,7 @@ const base = (over: Partial<CheckContext> = {}): CheckContext => ({
   sync: { version: '1.0.0', skills: ['launch'] },
   mcp: { declared: mcpConfig().mcpServers, enabled: [...MCP_NAMES] },
   version: '1.0.0',
+  worker: { name: 'acme', deployments: 1, skipped: null },
   ...over,
 });
 
@@ -434,6 +435,27 @@ test('a registry keyed by name rather than by number is understood', () => {
   assert.equal(runCheck('block-types-registered', ctx).status, 'pass');
 });
 
+test('the chrome exports in a registry are not read as block types', () => {
+  /*
+   * `header`, `footer`, `pageHeader`, `structuredData` and `webmasterPage` sit in the same file
+   * as `blocks`, in either export form. None is a block type, and none may make the check trip
+   * over a registry that is otherwise complete.
+   */
+  const ctx = base({
+    registry: [
+      `import WebmasterPage from './general/webmaster-page.astro';`,
+      `export const blocks = { 'content-000001': C };`,
+      `export const registeredTypes = () => Object.keys(blocks);`,
+      `export { default as pageHeader } from './general/page-header.astro';`,
+      `export const webmasterPage = WebmasterPage;`,
+    ].join('\n'),
+    content: new Map([
+      ['src/content/pages/home.json', JSON.stringify({ blocks: [{ type: 'content-000001' }] })],
+    ]),
+  });
+  assert.equal(runCheck('block-types-registered', ctx).status, 'pass');
+});
+
 test('a site that has not launched only gets a warning about placeholders', () => {
   /*
    * `webm new` seeds every one of these, so a freshly scaffolded site has the full set. The
@@ -709,3 +731,42 @@ test('a server pointed at the wrong url is caught, and both urls are shown', ()
   assert.match(r.detail!, /example\.com/);
   assert.ok(r.detail!.includes(MCP_SERVERS.mdn.url));
 });
+
+/* --- the Worker exists --------------------------------------------------- */
+
+test('a Worker with no deployment warns and says how to create it', () => {
+  /* A repo, a database and nothing serving: the failure /webm:start used to end on. */
+  const r = runCheck(
+    'worker-exists',
+    base({ worker: { name: 'acme', deployments: 0, skipped: null } }),
+  );
+  assert.equal(r.status, 'warn');
+  assert.match(r.detail!, /"acme"/);
+  assert.match(r.detail!, /wrangler deploy/);
+  assert.match(r.detail!, /Settings → Builds/);
+});
+
+test('an unanswerable question skips with the reason, and is not a failure', () => {
+  const r = runCheck(
+    'worker-exists',
+    base({ worker: { name: 'acme', deployments: null, skipped: 'wrangler is not logged in' } }),
+  );
+  assert.equal(r.status, 'pass');
+  assert.match(r.detail!, /skipped: wrangler is not logged in/);
+});
+
+test('a deployed Worker passes', () => {
+  assert.equal(runCheck('worker-exists', base()).status, 'pass');
+});
+
+test('a launched site still declared staging fails, and the message names the search consequence', () => {
+  const r = runCheck(
+    'environment',
+    base({
+      site: { client: 'A', domain: 'a.com', environment: 'staging', launched: '2026-09-01' },
+    }),
+  );
+  assert.equal(r.status, 'fail');
+  assert.match(r.detail!, /noindex/);
+  assert.match(r.detail!, /out of search/);
+});

package/src/cli/checks.ts

@@ -32,6 +32,7 @@ export interface CheckContext {
   site: SiteConfig;
   /** Parsed wrangler.jsonc, or null when absent. */
   wrangler: {
+    name?: string;
     assets?: { run_worker_first?: string[] };
     compatibility_date?: string;
     triggers?: { crons?: string[] };
@@ -73,6 +74,12 @@ export interface CheckContext {
   };
   /** The installed package version. */
   version: string;
+  /**
+   * Whether the Worker named in wrangler.jsonc exists on the account, asked of wrangler by the
+   * doctor. `deployments` is how many it listed - null when the question was not asked, and
+   * `skipped` then says why: wrangler not installed, not logged in, no network.
+   */
+  worker: { name: string | null; deployments: number | null; skipped: string | null };
 }
 
 export interface Check {
@@ -745,7 +752,9 @@ export const CHECKS: Check[] = [
   {
     id: 'environment',
     title: 'The declared environment matches where the site actually is',
-    silentAs: "a launched site whose client email is still being diverted to the agency's inbox",
+    silentAs:
+      "a launched site whose client email is still being diverted to the agency's inbox, and " +
+      'whose every page is noindex',
     run(ctx) {
       const declared = ctx.site.environment;
 
@@ -771,22 +780,51 @@ export const CHECKS: Check[] = [
       if (declared === 'staging' && isConfigured(ctx.site.launched)) {
         return fail(
           `this site launched on ${ctx.site.launched} but is still declared staging, so every ` +
-            `email it sends is being redirected away from its real recipients. Set ` +
-            `"environment": "production" in webmonterey.json.`,
+            `email it sends is being redirected away from its real recipients - and since 1.3.0 ` +
+            `every build of a staging site is a preview: noindex on every page, no canonical, ` +
+            `no sitemap, robots.txt disallowing everything. The live site is dropping out of ` +
+            `search. Set "environment": "production" in webmonterey.json.`,
         );
       }
 
       if (declared !== 'staging' && !isConfigured(ctx.site.launched)) {
         return warn(
           `this site has no launch date but is treated as production, so testing a form will ` +
-            `email the client's real contacts. Set "environment": "staging" in ` +
-            `webmonterey.json until /webm:launch.`,
+            `email the client's real contacts and every page is indexable on its workers.dev ` +
+            `hostname. Set "environment": "staging" in webmonterey.json until /webm:launch.`,
         );
       }
 
       return pass;
     },
   },
+  {
+    /*
+     * THE WORKER EXISTS. /webm:start used to end with a repo, a D1 database and an instruction
+     * to create the Worker in the dashboard by hand - and on one site nobody did. Nothing local
+     * notices: the build is green, every other check here is green, and the site is a
+     * workers.dev hostname that answers nothing. The Worker is the one resource whose absence
+     * has no symptom on disk, so this asks Cloudflare through wrangler - the one thing a laptop
+     * can ask - and steps aside with a note when it cannot.
+     */
+    id: 'worker-exists',
+    title: 'The Worker exists',
+    silentAs: 'a site with a repo, a database and nothing serving',
+    run(ctx) {
+      if (ctx.worker.skipped) return { status: 'pass', detail: `skipped: ${ctx.worker.skipped}` };
+      if (!ctx.worker.name) {
+        return warn('wrangler.jsonc names no Worker, so there is nothing to look for');
+      }
+      if (!ctx.worker.deployments) {
+        return warn(
+          `no deployment of a Worker named "${ctx.worker.name}" on this account. Create it once ` +
+            `from the laptop - npm run build && npx wrangler deploy - then connect the repo to ` +
+            `it in the dashboard (Worker → Settings → Builds). /webm:start, steps 5 and 6.`,
+        );
+      }
+      return pass;
+    },
+  },
   {
     id: 'seeded-files',
     title: 'The files Astro copies verbatim are present',

package/src/cli/doctor.ts

@@ -8,8 +8,10 @@
  *
  * Exit code is 1 on any failure, so it can gate a build or a go-live.
  */
+import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, resolve } from 'node:path';
 import { CHECKS, type CheckContext } from './checks.ts';
 import { loadSiteFiles } from '../integration/config.ts';
 
@@ -108,16 +110,90 @@ function readMcp(siteRoot: string): CheckContext['mcp'] {
   };
 }
 
+/**
+ * Ask wrangler whether the Worker exists - the one check here that leaves the machine.
+ *
+ * `wrangler deployments list --name <name> --json` is a read: it lists what is deployed and
+ * changes nothing. wrangler is resolved from the site upward, the way `npx` would find it,
+ * rather than downloaded - a doctor that installs things is not a doctor. Every way the question
+ * can go unanswered - no wrangler, not logged in, no network - is a SKIP with the reason, never
+ * a failure: the check exists to catch a missing Worker, and a laptop that cannot ask is not
+ * evidence of one.
+ *
+ * The two answers that matter are told apart by wrangler's own words: a missing Worker is
+ * "does not exist [code: 10007]"; a missing login is a request to set CLOUDFLARE_API_TOKEN, an
+ * authentication error, or a rejected token.
+ */
+function workerState(siteRoot: string, name: string | null | undefined): CheckContext['worker'] {
+  const worker = { name: name ?? null, deployments: null, skipped: null };
+  if (!worker.name) return worker;
+
+  /* Absolute, or createRequire refuses it - `webm doctor examples/minimal` passes a relative root. */
+  let bin: string;
+  try {
+    const require = createRequire(join(resolve(siteRoot), 'package.json'));
+    bin = join(dirname(require.resolve('wrangler/package.json')), 'bin/wrangler.js');
+  } catch {
+    return {
+      ...worker,
+      skipped: 'wrangler is not installed here, so the Worker was not looked for',
+    };
+  }
+
+  try {
+    const out = execFileSync(
+      process.execPath,
+      [bin, 'deployments', 'list', '--name', worker.name, '--json'],
+      {
+        cwd: siteRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 30_000,
+        env: { ...process.env, WRANGLER_SEND_METRICS: 'false', NO_COLOR: '1' },
+      },
+    );
+    const start = out.indexOf('[');
+    const parsed: unknown = start >= 0 ? JSON.parse(out.slice(start)) : [];
+    return { ...worker, deployments: Array.isArray(parsed) ? parsed.length : 0 };
+  } catch (error) {
+    const e = error as { stdout?: string; stderr?: string; message?: string };
+    const text = `${e.stdout ?? ''}\n${e.stderr ?? ''}\n${e.message ?? ''}`;
+    if (/code: 10007\]|does not exist on your account/i.test(text)) {
+      return { ...worker, deployments: 0 };
+    }
+    if (
+      /CLOUDFLARE_API_TOKEN|not (logged in|authenticated)|Authentication error|code: (10000|6111|9109)\]/i.test(
+        text,
+      )
+    ) {
+      return {
+        ...worker,
+        skipped:
+          'wrangler is not logged in (npx wrangler login), so whether the Worker exists was not checked',
+      };
+    }
+    const line = text
+      .split('\n')
+      .map((l) => l.replace(/\x1b\[[0-9;]*m/g, '').trim())
+      .find((l) => l && !l.startsWith('🪵'));
+    return { ...worker, skipped: `wrangler could not answer: ${line ?? 'no output'}` };
+  }
+}
+
 export function buildContext(siteRoot: string): CheckContext {
   const { site } = loadSiteFiles(siteRoot);
   const wranglerPath = ['wrangler.jsonc', 'wrangler.json']
     .map((f) => join(siteRoot, f))
     .find(existsSync);
   const syncPath = join(siteRoot, '.claude/skills/webm/.webm-sync.json');
+  const wrangler: CheckContext['wrangler'] = wranglerPath
+    ? parseJsonc(readFileSync(wranglerPath, 'utf8'))
+    : null;
 
   return {
     site,
-    wrangler: wranglerPath ? parseJsonc(readFileSync(wranglerPath, 'utf8')) : null,
+    wrangler,
+    worker: workerState(siteRoot, wrangler?.name),
     pages: readTree(siteRoot, 'src/pages', ['.astro', '.ts']),
     components: readTree(siteRoot, 'src/components', ['.astro', '.ts']),
     today: new Date().toISOString().slice(0, 10),

package/src/cli/scaffold.test.ts

@@ -2,6 +2,7 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { scaffold } from './scaffold.ts';
 import { MCP_NAMES, mcpConfig } from './mcp.ts';
+import { DENY_RULES } from './settings.ts';
 
 const files = (over = {}) =>
   scaffold({
@@ -235,3 +236,11 @@ test('the margin crosses a month and a year boundary correctly', () => {
   assert.equal(at('2026-01-05'), '2025-12-22');
   assert.equal(at('2026-03-05'), '2026-02-19', 'and February');
 });
+
+test('a session in a client repo cannot edit the package: node_modules is denied', () => {
+  const deny: string[] = json(files(), '.claude/settings.json').permissions.deny;
+  assert.deepEqual(deny, [...DENY_RULES], 'the one list in cli/settings.ts');
+  assert.ok(deny.includes('Edit(**/node_modules/**)'));
+  /* Claude Code checks Edit and Read rules only; a Write rule is ignored and warned about. */
+  assert.ok(!deny.some((r) => r.startsWith('Write(')), 'no Write rule');
+});

package/src/cli/scaffold.ts

@@ -10,6 +10,7 @@
  */
 import { resourceNames } from './slug.ts';
 import { MCP_NAMES, mcpConfig } from './mcp.ts';
+import { projectSettings } from './settings.ts';
 
 export interface ScaffoldOptions {
   domain: string;
@@ -151,7 +152,7 @@ export function scaffold(options: ScaffoldOptions): Record<string, string> {
         slug: n.slug,
         launched: null,
         '//environment':
-          "What this deployment is FOR. 'staging' redirects EVERY email the site sends to stagingEmail below, so testing a form on a preview cannot reach the client's real contacts. A new site starts here; /webm:launch flips it to 'production'. Anything served from workers.dev is treated as staging regardless, so a branch preview of a live site is covered too.",
+          "What this deployment is FOR. 'staging' makes every build a PREVIEW - every page noindex with no canonical, no sitemap, robots.txt disallowing everything, no Google Tag Manager - on every hostname, main included, so a site that has not launched cannot be indexed before it exists; and it redirects EVERY email the site sends to stagingEmail below, so testing a form on a preview cannot reach the client's real contacts. A new site starts here; /webm:launch flips it to 'production' once the custom domain is live, and that flip is what makes the site indexable. A branch other than main is a preview regardless, and anything served from workers.dev redirects its mail regardless, so a branch preview of a live site is covered too.",
         environment: 'staging',
         '//stagingEmail':
           'Where staging email goes instead of its real recipients. REQUIRED while environment is staging - a staging site with nowhere to send refuses to send rather than guessing. webm doctor checks.',
@@ -250,33 +251,11 @@ export function scaffold(options: ScaffoldOptions): Record<string, string> {
       2,
     ) + '\n';
 
-  files['.claude/settings.json'] =
-    JSON.stringify(
-      {
-        '//': `Project settings for ${n.repo}.`,
-        '//mcp':
-          'A server declared in .mcp.json is INERT until approved on each machine. Without this line the rules that say consult the Astro and MDN docs before using an API would depend on whoever cloned the repo happening to hit Approve.',
-        includeCoAuthoredBy: false,
-        enabledMcpjsonServers: MCP_NAMES,
-        permissions: {
-          deny: [
-            'Read(**/.dev.vars)',
-            'Read(**/.dev.vars.*)',
-            'Read(**/.env)',
-            'Read(**/.env.*)',
-            'Read(**/*.pem)',
-            'Read(**/*.key)',
-            'Read(**/.npmrc)',
-            'Edit(**/.dev.vars)',
-            'Edit(**/.env)',
-            'Write(**/.dev.vars)',
-            'Write(**/.env)',
-          ],
-        },
-      },
-      null,
-      2,
-    ) + '\n';
+  /*
+   * The deny list comes from cli/settings.ts, the one place it is declared, so a new site and a
+   * `webm sync` on an old one agree about what a session may not touch.
+   */
+  files['.claude/settings.json'] = JSON.stringify(projectSettings(n.repo), null, 2) + '\n';
 
   files['.mcp.json'] = JSON.stringify(mcpConfig(), null, 2) + '\n';
 
@@ -418,8 +397,11 @@ export function scaffold(options: ScaffoldOptions): Record<string, string> {
     `domain Chrome could mistake for a lookalike. A second resource of one kind takes a purpose\n` +
     `suffix - \`${n.slug}-portal\`.\n\n` +
     `## Deploying\n\n` +
-    `Push to deploy. A \`wrangler deploy\` from a laptop creates a version no build produced, so\n` +
-    `history stops describing what is live and the next push reverts it.\n`;
+    `The Worker is created ONCE from a laptop - \`npm run build && npx wrangler deploy\` - and the\n` +
+    `repo is then connected to it in the dashboard (Worker → Settings → Builds). /webm:start does\n` +
+    `both. From then on, push to deploy: a \`wrangler deploy\` from a laptop after that creates a\n` +
+    `version no build produced, so history stops describing what is live and the next push\n` +
+    `reverts it.\n`;
 
   return files;
 }