Merge pull request #12 from karero/docs/cloudflare-deploy-conventions

docs(new-website): pages.dev vs workers.dev + DNS-cutover safety

Author: karero

skills/new-website/SKILL.md

@@ -347,6 +347,15 @@ build finishes is it actually live at `<live-domain>` — confirm that separatel
 live at …"). On a **single-stage** site there is no preview: say plainly that the push **is
 going live now**.
 
+**Which URL to quote.** Prefer the **memorable `pages.dev` alias** — the branch alias
+`main.<project>.pages.dev` (or the project alias `<project>.pages.dev`) — over the random
+per-deploy hash URL `<hash>.<project>.pages.dev`. The hash URL is ugly but **immutable**, so
+keep it as a **backup**: when an alias looks **stale** (cache/propagation lag, or it's still
+serving an older build), the hash URL pins the exact fresh deployment and confirms the new
+build is up. Whichever you quote, **open it and confirm it loads** rather than reporting it
+blind — and note it for the project. (A `pages.dev` URL is also the signal you deployed to
+**Pages**, not a Worker — see `references/CLOUDFLARE_FIRST_DEPLOY.md`.)
+
 ## Notes
 
 - Do not rebuild what existing skills cover — GEO depth → `ai-seo`; technical-SEO/

skills/new-website/references/CLOUDFLARE_FIRST_DEPLOY.md

@@ -92,6 +92,14 @@ npx wrangler pages deploy dist --project-name <project>
 #    (Zone>DNS>Edit is only needed if you also script the DNS record itself.)
 ```
 
+> **`pages deploy`, not plain `deploy` — or you get a `workers.dev` URL.** These are static
+> **Pages** sites: every command above is `wrangler pages …` and the deploy must print a
+> **`<project>.pages.dev`** URL. A bare `wrangler deploy` (no `pages`) publishes a **Worker**
+> and hands back a `*.workers.dev` URL instead — a real mistake we've seen on an older kit
+> version. If you see `workers.dev`, stop: you deployed the wrong project type. Confirm it's
+> the accidental Worker (not a pre-existing one with a similar name), then delete it and
+> re-run `wrangler pages deploy`.
+
 Ongoing deploys under (A): re-run `wrangler pages deploy dist --project-name <project>`
 (wrap it in `npm run ship` if you want one command — note the stock `ship.sh` targets the
 git-push model of (B), so adapting it for direct-upload is a follow-up, not assumed here).
@@ -114,3 +122,71 @@ If the owner won't mint a token and won't do the dashboard alone: drive the dash
 your runtime's browser automation (**Claude in Chrome** under Claude Code; the agent's own
 browser tool otherwise — see `search-console-setup`), or read them the clicks one by one.
 Both work; both eat time and patience — which is why **(A) is recommended for true newcomers**.
+
+---
+
+## Going live: moving an existing domain's DNS to Cloudflare — verify twice
+
+When the site replaces a domain that already serves mail and a live site elsewhere (a
+rebuild migrating its DNS to Cloudflare), the cutover is the **single riskiest moment** — a
+wrong or wrongly-proxied record silently breaks email or the site right when it goes live.
+Treat it as a checklist *with* the owner, never a fire-and-forget edit:
+
+1. **Import, then check every record twice.** When Cloudflare scans the existing zone it
+   often misses records. Compare the imported set against the old DNS provider's export
+   **entry by entry, twice** — A/AAAA, CNAME, **all MX**, and every TXT (SPF, DKIM, DMARC,
+   verification tokens). A missing MX or SPF record = broken mail. The scan is least reliable
+   on **CNAME, SRV, and CAA** records even when A/MX/TXT come through, so confirm those by
+   hand:
+   - **Microsoft 365 / Outlook:** verify `autodiscover` (CNAME → `autodiscover.outlook.com`),
+     the DKIM selector CNAMEs (`selector1._domainkey`, `selector2._domainkey`), and the
+     Teams/Skype SRV records (`_sip._tls`, `_sipfederationtls._tcp`). A missing `autodiscover`
+     has been seen on a real migration (Cloudflare may have since improved this — **verify, don't
+     assume**); without it Outlook mailbox auto-setup breaks.
+   - **CAA** records — two failure modes: if existing CAA records are *dropped*, or if they
+     are *restrictive and don't list Cloudflare's CA*, Cloudflare can't issue the TLS cert
+     for the domain (including the Pages custom domain). If any CAA records exist, **confirm
+     they permit Cloudflare's CAs before go-live.**
+   - **Wildcard (`*`)** records and **subdomain NS delegations** — both commonly skipped.
+2. **Get a screenshot and double-check it.** Have the owner screenshot the final Cloudflare
+   DNS table and pass it back so you can review it against the old zone before they flip the
+   nameservers. A second pair of eyes catches the record that was dropped or mistyped.
+3. **Know which records must NOT be proxied (grey cloud, DNS-only).** Cloudflare's orange
+   "proxy" cloud only makes sense for the **HTTP(S) hosts you actually serve through
+   Cloudflare** (usually apex + `www` for this kit; proxy any other host only if it
+   intentionally serves HTTP through Cloudflare). Everything else must stay **DNS-only**, or
+   it breaks:
+   - **MX records and the mail hostnames they point to** — proxying mail destroys delivery.
+   - **SPF / DKIM / DMARC** and other **TXT** records (they aren't HTTP; proxy doesn't apply).
+   - **CNAMEs that aren't your website** — the sneaky trap, because only A/AAAA/CNAME records
+     *can* be proxied and onboarding often defaults the proxy **ON**: `autodiscover` /
+     `autoconfig`, **DKIM selector CNAMEs**, domain-**verification** CNAMEs, and third-party
+     service CNAMEs (email, helpdesk, status pages). A stray orange cloud on any of these
+     breaks the service — leave them DNS-only.
+   - Any record that must resolve to its **real origin IP** (e.g. a service expecting the
+     true address, not Cloudflare's edge).
+   Make sure the owner *understands* this distinction — don't just set it silently.
+4. **Disable DNSSEC at the registrar before touching nameservers.** Check whether DNSSEC is
+   enabled at the old provider/registrar; if it is, **turn it off first** (or follow
+   Cloudflare's DNSSEC migration path). Flipping nameservers while the old DS record is still
+   live leaves a signature chain Cloudflare can't satisfy — resolvers then return
+   `SERVFAIL` and the domain goes dark. Re-enable DNSSEC in Cloudflare afterwards if wanted.
+5. **Only after the passes agree and DNSSEC is handled**, change the nameservers / flip the
+   apex. Then confirm the site loads on the live domain **and** send a test email both
+   directions.
+
+> **Pages: attach the custom domain in the project — a DNS record alone isn't enough.** For a
+> Pages site, just adding a CNAME/record that points at `<project>.pages.dev` does **not**
+> connect the domain; the domain must be added through the Pages **Custom domains** flow
+> (dashboard, or the REST API in §A) or visitors get a **522**. And once it's attached, don't
+> "test" by pointing the record away from Pages and back — Cloudflare can serve errors until
+> it reactivates; use a redirect/origin rule for any temporary routing instead.
+
+> **Make rollback cheap — and don't tear the old setup down yet.** Lower the record TTLs at
+> the old provider ~24h *before* the move. After the flip, **keep the old zone, site, and mail
+> running through the propagation window** — resolvers may serve cached DNS for a while, so you
+> want an instant fall-back. Only retire the old setup once the new domain is confirmed
+> resolving and mail flows both directions.
+
+> Drive these changes *with* the owner, not through blind screen control — same guardrail as
+> the bootstrap token steps above.