@cparkerwebm/webmonterey 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -11,6 +11,61 @@ build. See `/webm:upgrade`.
 
 ---
 
+## 1.3.0 — 2026-09-02
+
+### Changed
+
+- **A staging site is a preview build everywhere.** `environment: "staging"` in webmonterey.json
+  now makes every build a preview — every page noindex with no canonical, no sitemap, `robots.txt`
+  `Disallow: /`, no Google Tag Manager — on every hostname and in every build: a feature branch,
+  `main` on Workers Builds, a laptop. Until now only a non-production branch was a preview, so a
+  site that had not launched was crawlable on its `workers.dev` URL the moment `main` deployed.
+  The branch rule stays: a feature branch of a launched site is still a preview. An unset
+  `environment` is production, as everywhere else, so a site predating the field builds as before.
+  The decision is one pure function, `isPreviewBuild`; the build log says which signal made a
+  build a preview, and `virtual:webm/build` carries it as `reason`.
+
+  **A launched site whose webmonterey.json still says `"staging"` disappears from search after
+  this update:** every page goes noindex and the sitemap is gone. `/webm:launch` sets
+  `"environment": "production"` and `launched` together; `webm doctor` already fails a launched
+  site still declared staging, and its message now names this consequence. Flipping `environment`
+  is what makes a site indexable, so it must not happen before the custom domain is live —
+  `/webm:start` and `/webm:launch` both say so.
+
+- **`/webm:start` creates the Worker.** Step 5 is now one deploy from the laptop — `npm run build
+  && npx wrangler deploy`, guarded by `wrangler deployments list` so a re-run skips it — and step 6
+  connects the repo to the Worker that now exists (Settings → Builds), a smaller dashboard step
+  than importing a repository and typing the Worker name in by hand. The skill used to stop and
+  ask for the Worker to be made in the dashboard; on one site it was not, and the result was a
+  repo, a database and nothing serving. That laptop deploy is the only one a site ever gets: once
+  the repo is connected, a laptop deploy is a version no build produced, which the next push
+  reverts. The adapter's auto-provisioned `<slug>-session` KV namespace is expected and stays out
+  of wrangler.jsonc. The scaffolded README's deploy note says the same.
+
+### Added
+
+- **`webm doctor` checks that the Worker exists.** It asks wrangler for the deployments of the
+  Worker named in wrangler.jsonc and warns when there are none — the silent failure above. It skips
+  with a note when wrangler is not installed or not logged in, so CI and a fresh laptop are not
+  failed for being unable to ask.
+
+- **Hard rule 12 in a site's CLAUDE.md: a session in a client repo never edits the package.** Not
+  in `node_modules`, and not in the package's checkout when it sits on the same machine. The
+  deliverable for an upstream problem is a description of the fix — what, where, expected
+  behaviour, how to verify — as a prompt for a session opened in the package repo; the site takes
+  the fix with `npm update`. Enforced as far as Claude Code's rules reach: `.claude/settings.json`
+  denies `Edit(**/node_modules/**)`, and **`webm sync` now merges the package's deny rules into a
+  site's settings on every install** — adding what is missing, leaving the site's own rules alone,
+  and dropping the two `Write(...)` rules 1.2.0 scaffolded, which Claude Code never consults and
+  warns about at startup. The docs have no rule syntax for "any path outside this project", so
+  that half stays prose.
+
+  **On an existing site:** the settings arrive with the next install. `CLAUDE.md` is the site's
+  own file, so copy rule 12 in from
+  `node_modules/@cparkerwebm/webmonterey/template/site/CLAUDE.md`.
+
+---
+
 ## 1.2.0 — 2026-09-02
 
 ### Added

package/README.md

@@ -20,6 +20,12 @@ the reset, the Cloudflare includes, the consent system, the form pipeline, the r
 It ships **zero visible components**. Every block a visitor sees is built per client, in that
 client's repo. Every default has a documented way to opt out of it.
 
+**The package is edited in this repo, and only here.** A session in a client site that finds a
+package bug does not reach into `node_modules` or into this checkout; its deliverable is a
+description of the fix, run later in a session opened here, and the site takes the result with
+`npm update`. That is rule 12 of the site's `CLAUDE.md`, with an `Edit` deny on `node_modules`
+behind it that `webm sync` keeps in place. The inverse holds: nothing here edits a client site.
+
 ## Creating a client site
 
 ```sh

package/dist/webm.mjs

@@ -196,6 +196,53 @@ var init_mcp = __esm({
   }
 });
 
+// src/cli/settings.ts
+function projectSettings(repo) {
+  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] }
+  };
+}
+function withDenyRules(settings) {
+  const permissions = settings.permissions && typeof settings.permissions === "object" ? { ...settings.permissions } : {};
+  const current = Array.isArray(permissions.deny) ? permissions.deny.filter((r) => 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
+  };
+}
+var DENY_RULES, STALE_RULES, PERMISSIONS_NOTE;
+var init_settings = __esm({
+  "src/cli/settings.ts"() {
+    "use strict";
+    init_mcp();
+    DENY_RULES = [
+      "Read(**/.dev.vars)",
+      "Read(**/.dev.vars.*)",
+      "Read(**/.env)",
+      "Read(**/.env.*)",
+      "Read(**/*.pem)",
+      "Read(**/*.key)",
+      "Read(**/.npmrc)",
+      "Edit(**/.dev.vars)",
+      "Edit(**/.env)",
+      "Edit(**/node_modules/**)"
+    ];
+    STALE_RULES = ["Write(**/.dev.vars)", "Write(**/.env)"];
+    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.";
+  }
+});
+
 // src/cli/scaffold.ts
 function shiftDays(date, days) {
   const shifted = /* @__PURE__ */ new Date(`${date}T00:00:00Z`);
@@ -279,7 +326,7 @@ export default defineConfig({
       worker: n.worker,
       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.",
+      "//environment": "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.",
       stagingEmail: options.stagingEmail ?? "",
@@ -372,31 +419,7 @@ export default defineConfig({
     null,
     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";
+  files[".claude/settings.json"] = JSON.stringify(projectSettings(n.repo), null, 2) + "\n";
   files[".mcp.json"] = JSON.stringify(mcpConfig(), null, 2) + "\n";
   files["src/actions/index.ts"] = `/*
  * Form handlers.
@@ -550,8 +573,11 @@ suffix - \`${n.slug}-portal\`.
 
 ## Deploying
 
-Push to deploy. 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.
+The Worker is created ONCE from a laptop - \`npm run build && npx wrangler deploy\` - and the
+repo is then connected to it in the dashboard (Worker \u2192 Settings \u2192 Builds). /webm:start does
+both. From then on, push to deploy: a \`wrangler deploy\` from a laptop after that creates a
+version no build produced, so history stops describing what is live and the next push
+reverts it.
 `;
   return files;
 }
@@ -560,6 +586,7 @@ var init_scaffold = __esm({
     "use strict";
     init_slug();
     init_mcp();
+    init_settings();
   }
 });
 
@@ -578,7 +605,7 @@ import {
   writeFileSync,
   readdirSync
 } from "node:fs";
-import { basename, join as join2 } from "node:path";
+import { basename, dirname as dirname2, join as join2 } from "node:path";
 function syncDir(source, target) {
   if (!existsSync2(source)) return [];
   mkdirSync(target, { recursive: true });
@@ -604,6 +631,30 @@ function addMissing(source, target) {
   }
   return added.sort();
 }
+function ensureSettings(siteRoot) {
+  const path = join2(siteRoot, ".claude", "settings.json");
+  if (!existsSync2(path)) {
+    mkdirSync(dirname2(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(projectSettings(basename(siteRoot)), null, 2) + "\n");
+    return { added: [...DENY_RULES], removed: [], created: true, skipped: null };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync2(path, "utf8"));
+  } 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) {
   if (!existsSync2(dir)) return [];
   return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory() && existsSync2(join2(dir, e.name, "SKILL.md"))).map((e) => e.name).sort();
@@ -660,7 +711,8 @@ function sync(siteRoot) {
      * which is how code depending on an unpublished package reached main without a word.
      */
     workflows: syncDir(join2(template, "workflows"), join2(siteRoot, ".github/workflows")),
-    migrations: addMissing(join2(template, "migrations"), join2(siteRoot, "migrations"))
+    migrations: addMissing(join2(template, "migrations"), join2(siteRoot, "migrations")),
+    settings: ensureSettings(siteRoot)
   };
 }
 function ensureGitignored(siteRoot) {
@@ -691,6 +743,19 @@ function run(argv2) {
   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}/`);
   }
@@ -707,13 +772,14 @@ var init_sync = __esm({
   "src/cli/sync.ts"() {
     "use strict";
     init_package_root();
+    init_settings();
     NAMESPACE = "webm";
   }
 });
 
 // src/cli/seed.ts
 import { cpSync as cpSync2, existsSync as existsSync3, mkdirSync as mkdirSync2, readdirSync as readdirSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { dirname as dirname2, join as join3, relative } from "node:path";
+import { dirname as dirname3, join as join3, relative } from "node:path";
 function walk(dir) {
   if (!existsSync3(dir)) return [];
   return readdirSync2(dir, { withFileTypes: true }).flatMap((e) => {
@@ -732,7 +798,7 @@ function seed(packageRoot, siteRoot) {
       const rel = relative(source, file);
       const dest = join3(siteRoot, to === "." ? rel : join3(to, rel));
       if (existsSync3(dest)) continue;
-      mkdirSync2(dirname2(dest), { recursive: true });
+      mkdirSync2(dirname3(dest), { recursive: true });
       cpSync2(file, dest);
       written.push(relative(siteRoot, dest));
     }
@@ -800,7 +866,7 @@ __export(new_exports, {
 });
 import { execFileSync } from "node:child_process";
 import { existsSync as existsSync4, mkdirSync as mkdirSync3, readdirSync as readdirSync3, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname3, join as join4, resolve } from "node:path";
+import { dirname as dirname4, join as join4, resolve } from "node:path";
 function parseArgs(argv2) {
   const positional = argv2.filter((a) => !a.startsWith("--"));
   const flag = (name) => {
@@ -863,7 +929,7 @@ function run2(argv2) {
   });
   for (const [path, contents] of Object.entries(files)) {
     const full = join4(root, path);
-    mkdirSync3(dirname3(full), { recursive: true });
+    mkdirSync3(dirname4(full), { recursive: true });
     writeFileSync3(full, contents);
   }
   const seeded = seed(PACKAGE_ROOT, root);
@@ -1982,7 +2048,7 @@ var init_checks = __esm({
       {
         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;
           if (declared !== void 0 && declared !== "production" && declared !== "staging") {
@@ -1992,12 +2058,37 @@ var init_checks = __esm({
           }
           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.`
+              `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 - 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.`
+              `this site has no launch date but is treated as production, so testing a form will 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 \u2192 Settings \u2192 Builds). /webm:start, steps 5 and 6.`
             );
           }
           return pass;
@@ -2079,8 +2170,10 @@ __export(doctor_exports, {
   buildContext: () => buildContext,
   run: () => run5
 });
+import { execFileSync as execFileSync2 } from "node:child_process";
 import { existsSync as existsSync8, readFileSync as readFileSync7, readdirSync as readdirSync6 } from "node:fs";
-import { join as join7, relative as relative3 } from "node:path";
+import { createRequire } from "node:module";
+import { dirname as dirname5, join as join7, relative as relative3, resolve as resolve2 } from "node:path";
 function parseJsonc(source) {
   const stripped = source.replace(/\\"|"(?:\\"|[^"])*"|(\/\/.*|\/\*[\s\S]*?\*\/)/g, (m, comment) => comment ? "" : m).replace(/,(\s*[}\]])/g, "$1");
   return JSON.parse(stripped);
@@ -2140,13 +2233,63 @@ function readMcp(siteRoot) {
     enabled: read(".claude/settings.json", (p) => p.enabledMcpjsonServers ?? null)
   };
 }
+function workerState(siteRoot, name) {
+  const worker = { name: name ?? null, deployments: null, skipped: null };
+  if (!worker.name) return worker;
+  let bin;
+  try {
+    const require2 = createRequire(join7(resolve2(siteRoot), "package.json"));
+    bin = join7(dirname5(require2.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 = execFileSync2(
+      process.execPath,
+      [bin, "deployments", "list", "--name", worker.name, "--json"],
+      {
+        cwd: siteRoot,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 3e4,
+        env: { ...process.env, WRANGLER_SEND_METRICS: "false", NO_COLOR: "1" }
+      }
+    );
+    const start = out.indexOf("[");
+    const parsed = start >= 0 ? JSON.parse(out.slice(start)) : [];
+    return { ...worker, deployments: Array.isArray(parsed) ? parsed.length : 0 };
+  } catch (error) {
+    const e = error;
+    const text = `${e.stdout ?? ""}
+${e.stderr ?? ""}
+${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("\u{1FAB5}"));
+    return { ...worker, skipped: `wrangler could not answer: ${line ?? "no output"}` };
+  }
+}
 function buildContext(siteRoot) {
   const { site } = loadSiteFiles(siteRoot);
   const wranglerPath = ["wrangler.jsonc", "wrangler.json"].map((f) => join7(siteRoot, f)).find(existsSync8);
   const syncPath = join7(siteRoot, ".claude/skills/webm/.webm-sync.json");
+  const wrangler = wranglerPath ? parseJsonc(readFileSync7(wranglerPath, "utf8")) : null;
   return {
     site,
-    wrangler: wranglerPath ? parseJsonc(readFileSync7(wranglerPath, "utf8")) : null,
+    wrangler,
+    worker: workerState(siteRoot, wrangler?.name),
     pages: readTree(siteRoot, "src/pages", [".astro", ".ts"]),
     components: readTree(siteRoot, "src/components", [".astro", ".ts"]),
     today: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
@@ -2227,7 +2370,7 @@ __export(audit_exports, {
   run: () => run6
 });
 import { existsSync as existsSync9, readdirSync as readdirSync7, readFileSync as readFileSync8, statSync as statSync3 } from "node:fs";
-import { join as join8, relative as relative4, resolve as resolve2 } from "node:path";
+import { join as join8, relative as relative4, resolve as resolve3 } from "node:path";
 function attr(tag, name) {
   const m = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i").exec(tag);
   if (!m) return null;
@@ -2376,7 +2519,7 @@ async function probe(urls) {
   return bad.sort((a, b) => a.url.localeCompare(b.url));
 }
 async function run6(argv2) {
-  const dist = resolve2(argv2.find((a) => !a.startsWith("-")) ?? "dist/client");
+  const dist = resolve3(argv2.find((a) => !a.startsWith("-")) ?? "dist/client");
   const noExternal = argv2.includes("--no-external");
   if (!existsSync9(join8(dist, "index.html"))) {
     console.error(`webm audit: no build at ${dist}. Run \`npm run build\` first.`);
@@ -2473,11 +2616,11 @@ var upgrade_exports = {};
 __export(upgrade_exports, {
   run: () => run7
 });
-import { execFileSync as execFileSync2 } from "node:child_process";
+import { execFileSync as execFileSync3 } from "node:child_process";
 import { existsSync as existsSync10, readFileSync as readFileSync9 } from "node:fs";
 import { join as join9 } from "node:path";
 function git(siteRoot, args) {
-  return execFileSync2("git", args, { cwd: siteRoot, encoding: "utf8" }).trim();
+  return execFileSync3("git", args, { cwd: siteRoot, encoding: "utf8" }).trim();
 }
 function installedVersion(siteRoot) {
   const path = join9(siteRoot, "node_modules", PACKAGE, "package.json");
@@ -2507,7 +2650,7 @@ function run7(argv2) {
     git(siteRoot, ["checkout", "-b", branch]);
     console.log(`Branched to ${branch}. Never upgrade on main.`);
   }
-  execFileSync2("npm", ["install", `${PACKAGE}@${target}`], { cwd: siteRoot, stdio: "inherit" });
+  execFileSync3("npm", ["install", `${PACKAGE}@${target}`], { cwd: siteRoot, stdio: "inherit" });
   const to = installedVersion(siteRoot);
   if (!to) {
     console.error("webm upgrade: install did not produce a version. Check the npm output above.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparkerwebm/webmonterey",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "The WebMonterey Astro framework: plumbing, design system, and Claude Code skills for client sites on Cloudflare Workers",
   "license": "MIT",

package/skills/launch/SKILL.md

@@ -211,13 +211,21 @@ In one change:
 "launched": "YYYY-MM-DD"
 ```
 
+**This flip is also what makes the site indexable, so it happens here and not before.** While
+`environment` says `staging`, every build is a preview - every page noindex with no canonical,
+no sitemap, robots.txt disallowing everything, no Google Tag Manager - on every hostname, `main`
+included. Flip it before the custom domain is live and the `workers.dev` copy is what gets
+indexed.
+
 Until `environment` flips, every message the site sends is redirected to `stagingEmail` - correct
 right up to the moment the domain is attached and wrong immediately after: the form keeps saying
 thank you, the client's inbox stays empty, and the first anyone hears of it is a customer asking
-why nobody called back. `webm doctor` fails a launched site still declared staging, which is why
-both fields change together.
+why nobody called back. And a launched site left on `staging` is invisible to search: every page
+noindex, no sitemap, `Disallow: /`. `webm doctor` fails a launched site still declared staging,
+which is why both fields change together.
 
-Anything served from `workers.dev` is still treated as staging whatever this says, so branch
-previews of the live site keep redirecting. That is deliberate.
+Anything served from `workers.dev` is still treated as staging for MAIL whatever this says, and
+any branch other than `main` still builds as a preview, so branch previews of the live site keep
+redirecting and stay out of the index. That is deliberate.
 
 Commit, push, and confirm the deploy. Then run `npx webm doctor` one last time: zero failures.

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,10 @@ 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
 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