@cparkerwebm/webmonterey 1.2.0 → 1.3.0

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,
 });
 
@@ -709,3 +710,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;
 }

package/src/cli/settings.ts

@@ -0,0 +1,106 @@
+/*
+ * The Claude Code project settings a client repo carries, and the one list of what they deny.
+ *
+ * WHY A MODULE, like mcp.ts. Three places have to agree about these rules: the scaffold writes
+ * them into a new site, `webm sync` merges any that are missing into an existing site on every
+ * install, and the tests assert both against this list rather than a literal that falls one
+ * behind. `.claude/settings.json` is otherwise the site's own - a client adds allow rules to it -
+ * so it is MERGED, never replaced: the package's deny rules are added when absent and everything
+ * else in the file is left exactly as found.
+ *
+ * WHAT THE DENY RULES ENFORCE. Two things a session in a client repo must never do, made
+ * mechanical rather than advisory:
+ *
+ *   - read a secret. .env, .dev.vars, keys, the npm config.
+ *   - edit the package. Rule 12 of the site's CLAUDE.md: a session in a client repo never edits
+ *     the package, not in node_modules and not in its checkout. The deliverable for an upstream
+ *     problem is a description of the fix, run later in the package repo.
+ *
+ * THE SYNTAX, verified against code.claude.com/docs/en/permissions rather than recalled:
+ *
+ *   - Read and Edit rules take gitignore patterns. As a DENY rule, `Edit(**\/node_modules/**)`
+ *     matches a node_modules directory at any depth under the working directory.
+ *   - `Edit` rules apply to every built-in tool that edits files - Edit, Write, MultiEdit and
+ *     NotebookEdit. A `Write(...)` rule is accepted, never consulted, and warned about at
+ *     startup, which is why none appears here and why the two that 1.2.0 scaffolded are removed.
+ *   - A `Read` deny also blocks Edit and Write on the same path. The Edit rules for the secret
+ *     files are therefore redundant, and kept: they say what is meant.
+ *   - THERE IS NO PATTERN FOR "ANY PATH OUTSIDE THE PROJECT". A rule names a path - `//absolute`,
+ *     `~/home-relative`, `/project-relative`, or cwd-relative - and nothing expresses the
+ *     complement of one. The package checkout sitting beside a client repo on the same machine
+ *     cannot be denied by rule without hardcoding where it is, and a public package does not
+ *     know. Rule 12 in CLAUDE.md carries that half in prose.
+ */
+
+import { MCP_NAMES } from './mcp.ts';
+
+/** Every rule a site's settings must deny. Order is the order they are written. */
+export const DENY_RULES: readonly string[] = [
+  'Read(**/.dev.vars)',
+  'Read(**/.dev.vars.*)',
+  'Read(**/.env)',
+  'Read(**/.env.*)',
+  'Read(**/*.pem)',
+  'Read(**/*.key)',
+  'Read(**/.npmrc)',
+  'Edit(**/.dev.vars)',
+  'Edit(**/.env)',
+  'Edit(**/node_modules/**)',
+];
+
+/**
+ * Rules an earlier scaffold wrote that Claude Code never consults and warns about at startup.
+ * Removed on sync, by exact string, so a rule the site wrote itself is never touched.
+ */
+export const STALE_RULES: readonly string[] = ['Write(**/.dev.vars)', 'Write(**/.env)'];
+
+const PERMISSIONS_NOTE =
+  'The deny list is package-managed: `webm sync` adds any rule that is missing on every ' +
+  'install and leaves everything else in this file alone. Edit(**/node_modules/**) is rule 12 ' +
+  'of CLAUDE.md made mechanical - a session in this repo never edits the package.';
+
+/** The whole file, for a new site. */
+export function projectSettings(repo: string): Record<string, unknown> {
+  return {
+    '//': `Project settings for ${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': PERMISSIONS_NOTE,
+    permissions: { deny: [...DENY_RULES] },
+  };
+}
+
+/**
+ * An existing settings file with the package's deny rules present and the stale ones gone.
+ *
+ * IDEMPOTENT, and additive everywhere else: a second pass reports nothing and changes nothing,
+ * and a rule the site added itself - an allow list, a deny of its own - survives untouched. The
+ * site's own rules keep their order; the package's are appended in DENY_RULES order.
+ */
+export function withDenyRules(settings: Record<string, unknown>): {
+  settings: Record<string, unknown>;
+  added: string[];
+  removed: string[];
+} {
+  const permissions =
+    settings.permissions && typeof settings.permissions === 'object'
+      ? { ...(settings.permissions as Record<string, unknown>) }
+      : {};
+  const current = Array.isArray(permissions.deny)
+    ? (permissions.deny as unknown[]).filter((r): r is string => typeof r === 'string')
+    : [];
+
+  const removed = current.filter((r) => STALE_RULES.includes(r));
+  const kept = current.filter((r) => !STALE_RULES.includes(r));
+  const added = DENY_RULES.filter((r) => !kept.includes(r));
+  if (!added.length && !removed.length) return { settings, added, removed };
+
+  permissions.deny = [...kept, ...added];
+  return {
+    settings: { ...settings, '//permissions': PERMISSIONS_NOTE, permissions },
+    added,
+    removed,
+  };
+}

package/src/cli/sync.test.ts

@@ -11,6 +11,7 @@ import {
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { sync } from './sync.ts';
+import { DENY_RULES, STALE_RULES } from './settings.ts';
 
 const site = () => mkdtempSync(join(tmpdir(), 'webm-sync-'));
 
@@ -135,3 +136,63 @@ test('the migrations README rides along, so the --remote trap is documented in t
   sync(dir);
   assert.match(readFileSync(join(dir, 'migrations', 'README.md'), 'utf8'), /--remote/);
 });
+
+test('the package deny rules are MERGED into .claude/settings.json, never replacing it', () => {
+  const dir = site();
+  mkdirSync(join(dir, '.claude'), { recursive: true });
+  const path = join(dir, '.claude/settings.json');
+  writeFileSync(
+    path,
+    JSON.stringify({
+      '//': 'theirs',
+      enabledMcpjsonServers: ['astro-docs'],
+      permissions: {
+        allow: ['Bash(npm run *)'],
+        deny: ['Read(**/.env)', 'Write(**/.env)', 'Edit(/secrets/**)'],
+      },
+    }),
+  );
+
+  const first = sync(dir);
+  const written = JSON.parse(readFileSync(path, 'utf8'));
+  assert.ok(first.settings.added.includes('Edit(**/node_modules/**)'), 'rule 12 lands');
+  assert.deepEqual(first.settings.removed, ['Write(**/.env)'], 'the rule Claude Code warns about');
+  assert.equal(written['//'], 'theirs');
+  assert.deepEqual(written.enabledMcpjsonServers, ['astro-docs'], 'not touched by this');
+  assert.deepEqual(
+    written.permissions.allow,
+    ['Bash(npm run *)'],
+    "the site's allow list survives",
+  );
+  assert.ok(written.permissions.deny.includes('Edit(/secrets/**)'), "the site's own deny survives");
+  for (const rule of DENY_RULES) assert.ok(written.permissions.deny.includes(rule), rule);
+  for (const rule of STALE_RULES) assert.ok(!written.permissions.deny.includes(rule), rule);
+  assert.equal(
+    written.permissions.deny.filter((r: string) => r === 'Read(**/.env)').length,
+    1,
+    'a rule already there is not doubled',
+  );
+
+  /* Idempotent: the second pass reports nothing and rewrites nothing. */
+  const before = readFileSync(path, 'utf8');
+  const second = sync(dir);
+  assert.deepEqual(second.settings, { added: [], removed: [], created: false, skipped: null });
+  assert.equal(readFileSync(path, 'utf8'), before);
+});
+
+test('a site with no settings file gets the scaffold defaults', () => {
+  const dir = site();
+  const result = sync(dir);
+  assert.equal(result.settings.created, true);
+  const written = JSON.parse(readFileSync(join(dir, '.claude/settings.json'), 'utf8'));
+  assert.deepEqual(written.permissions.deny, [...DENY_RULES]);
+});
+
+test('a settings file that will not parse is left alone and reported', () => {
+  const dir = site();
+  mkdirSync(join(dir, '.claude'), { recursive: true });
+  writeFileSync(join(dir, '.claude/settings.json'), '{ not json');
+  const result = sync(dir);
+  assert.ok(result.settings.skipped);
+  assert.equal(readFileSync(join(dir, '.claude/settings.json'), 'utf8'), '{ not json');
+});

package/src/cli/sync.ts

@@ -26,6 +26,9 @@
  *                                  a real D1 database must NEVER change - SQLite has already run
  *                                  it and wrangler tracks it by name. Later versions add 0002,
  *                                  they do not rewrite 0001.
+ *   MERGE     .claude/settings.json The package's deny rules are added when absent and the file
+ *                                  is otherwise left as found - a client's allow list is theirs.
+ *                                  See cli/settings.ts for the rules and why they are rules.
  *   SEED      public/, content     Written once by `webm new` and then the client's outright.
  *                                  Not handled here at all - see cli/scaffold.ts.
  *
@@ -46,8 +49,9 @@ import {
   writeFileSync,
   readdirSync,
 } from 'node:fs';
-import { basename, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { PACKAGE_ROOT, packageVersion } from './package-root.ts';
+import { DENY_RULES, projectSettings, withDenyRules } from './settings.ts';
 
 /**
  * The namespace. Rule 5's prefix: the CLI is `webm`, the tokens are --webm-*, the classes are
@@ -68,6 +72,11 @@ interface SyncResult {
   workflows: string[];
   /** Migrations copied because the site did not have them. Never includes an existing file. */
   migrations: string[];
+  /**
+   * What changed in .claude/settings.json: deny rules added, stale ones removed, the file
+   * created when there was none, or why it was left alone.
+   */
+  settings: { added: string[]; removed: string[]; created: boolean; skipped: string | null };
 }
 
 /**
@@ -119,6 +128,46 @@ function addMissing(source: string, target: string): string[] {
   return added.sort();
 }
 
+/**
+ * MERGE. The package's deny rules into the site's settings, and nothing else.
+ *
+ * `.claude/settings.json` is the site's: a client adds allow rules to it, and a full replace would
+ * throw those away on the next install. So the file is read, the rules in cli/settings.ts are
+ * added where absent, the two rules Claude Code warns about at startup are dropped, and the file
+ * is written back only when that changed something - a second pass is a no-op. A file that will
+ * not parse is left exactly as it is and reported: Claude Code cannot read it either, and
+ * rewriting it would hide that.
+ *
+ * Created from the scaffold's defaults when there is none, so a site that predates the file gets
+ * the rules on its next install rather than never.
+ */
+function ensureSettings(siteRoot: string): SyncResult['settings'] {
+  const path = join(siteRoot, '.claude', 'settings.json');
+  if (!existsSync(path)) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(projectSettings(basename(siteRoot)), null, 2) + '\n');
+    return { added: [...DENY_RULES], removed: [], created: true, skipped: null };
+  }
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+  } catch {
+    return {
+      added: [],
+      removed: [],
+      created: false,
+      skipped: '.claude/settings.json is not valid JSON, so it was left alone',
+    };
+  }
+
+  const { settings, added, removed } = withDenyRules(parsed);
+  if (added.length || removed.length) {
+    writeFileSync(path, JSON.stringify(settings, null, 2) + '\n');
+  }
+  return { added, removed, created: false, skipped: null };
+}
+
 function listSkills(dir: string): string[] {
   if (!existsSync(dir)) return [];
   return readdirSync(dir, { withFileTypes: true })
@@ -207,6 +256,7 @@ export function sync(siteRoot: string): SyncResult {
      */
     workflows: syncDir(join(template, 'workflows'), join(siteRoot, '.github/workflows')),
     migrations: addMissing(join(template, 'migrations'), join(siteRoot, 'migrations')),
+    settings: ensureSettings(siteRoot),
   };
 }
 
@@ -245,6 +295,19 @@ export function run(argv: string[]): number {
   for (const m of result.migrations) {
     console.log(`  + migrations/${m}  (apply it: npx wrangler d1 migrations apply <DB> --remote)`);
   }
+  if (result.settings.created) {
+    console.log(`  + .claude/settings.json`);
+  } else if (result.settings.skipped) {
+    console.log(`  ${result.settings.skipped}`);
+  } else if (result.settings.added.length || result.settings.removed.length) {
+    const parts = [
+      result.settings.added.length && `+${result.settings.added.length} deny`,
+      result.settings.removed.length && `-${result.settings.removed.length} stale`,
+    ].filter(Boolean);
+    console.log(
+      `  .claude/settings.json: ${parts.join(', ')} (package-managed rules; yours are kept)`,
+    );
+  }
 
   if (ensureGitignored(siteRoot)) {
     console.log(`  gitignored .claude/skills/${NAMESPACE}/`);