It is for whoever will run the site: an operator (an agency or fractional CMO) setting it up for a client, or the in-house web or marketing person who will manage it. The steps are the same; who owns which account differs, and that is the second section. It stays at step level, with the handful of commands the kit exposes; anything deeper is in the kit's own docs, which ship with every clone.
The Saprel Site Kit is open source: the build method, quality gates, and operating runbooks, which anyone can run standalone. Saprel Web is what the platform adds on top when your analytics data lands: reporting, monitoring, and self-service editing. This guide covers the kit end to end and marks the few steps where Saprel Web is involved.
Before you start
Accounts. A GitHub account with an organization to hold the repository. A Cloudflare account. A Google account with access to the business's Analytics, Search Console, and Ads, or the standing to create them.
Tools. Node 20 or later. Wrangler, Playwright and Lighthouse come with the kit as pinned dependencies (npm ci installs them; a kit release moves every site to the same versions), so nothing is installed globally. Once per machine, with sudo, the system packages Chromium needs: npm exec --no -- playwright install-deps chromium from inside a kit clone. Then once per clone npm run qa:browser, which puts Chromium under that clone's tmp/browsers/; the screenshot script and the Lighthouse gate share it, and no clone can delete another's. The kit moves its Playwright pin only to a version that has been published for at least seven days, never to the release of the week, and a site moves its pin only by taking a kit release: a browser is a large download that runs on every operator's machine, and a week is long enough for a bad release to be pulled or reported. The browser scripts open only localhost and the hosts this repository declares (the canonical link, the worker's routes and its workers.dev host); a command that names any other URL is refused before the browser starts. A coding agent that reads the repository's instructions file before it edits anything; the kit is written for one.
Secrets. The kit does not integrate with or require a specific secrets manager. Kit scripts receive secrets only through environment variables or stdin; they never read a secrets file and never take a secret as a command argument. Each site's secret names are listed in its site configuration (Forms section); the values live only where they are used: the site's secrets are Cloudflare Worker secrets, and anything a scheduled job reads lives in the secret store of wherever that job runs.
For operator commands that need credentials, such as a Cloudflare API token during provisioning, put an environment-variable injector in front of the command:
# 1Password Environments: maintainer-tested
op run --environment <id> -- <command>
# Bitwarden Secrets Manager: compatible, untested
bws run --project-id <id> -- <command>
# Doppler: compatible, untested
doppler run -- <command>
Maintainer-tested means the kit's maintainers run it every day. Compatible means it meets the contract above and the maintainers have not run it.
Whichever you use: the injector's own access token is already in your session, never typed on a command line. Keep one standing environment per client for operator work, and a separate short-lived one for provisioning tokens that you revoke at launch. Never print the environment, and do not rely on output masking: op run masks the values it injected, other injectors may not.
What a scoped API token covers, and what stays in the dashboard. An operator's standing token for a site is scoped to one zone and reads Workers; it is enough for the checks and the day-to-day (the launch check, reading a deployment, the redirect test). It does not create zones, edit DNS, or manage Access, and it does not write Worker secrets. Those are dashboard steps for the account's owner or a person logged in as them: creating the zone and binding the domain (Launch, steps 1 and 2), every DNS record including the mail-authentication records (Launch, step 3a), the Access gate and its policy (Deploy the preview, step 3a; Launch, steps 4 and 7), and the zone's bot settings (Launch, step 6). Worker secrets are set from a kit clone by a logged-in user (Forms). A step in this guide that says "in the dashboard" is one of these; nothing a token does needs a browser.
Inputs. A brand strategy with a visual-identity section (from Saprel Guide, or your own equivalent); the kit ships an outline if you are writing one yourself. Font files, or the family names so you can fetch them. The logo in SVG. A page list: which pages the site needs and what each one is for. A site without a strategy is a site that gets rebuilt.
Who owns what
The rule is short: the business owns the source, the content, its domain and the account its DNS lives in; whoever operates the site works through delegated access and pays for its own tooling; anything a platform holds is the minimum it needs and is revocable by the business. Owning is not managing: the operator still does the work. The test for each row is what happens if the operator disappears tomorrow. In-house, most rows collapse, but the domain and the Google properties belong to the business, not to a person.
| Element | Operator for a client | In-house |
|---|---|---|
| Site repository | Operator's GitHub org, private; the client is added as an outside collaborator on request; transfers to the client at engagement end (a repository transfer is quick and keeps history; re-link the deploy connection afterwards) | The business's own org |
| Cloudflare zone | One Cloudflare account per client, created by the operator from their own Cloudflare login (account menu → Create account, free plan), handed to the client when they want it. Cloudflare has no way to move a zone or a Worker between accounts, but an account itself changes hands in five minutes: invite the client's person as Super Administrator, they accept, the operator steps down. That only works when the account holds nothing but that client, so never put two clients' zones in one account. The client does nothing at signing; DNS still carries their email and domain verification, and the domain stays registered in their name. If the client already runs a Cloudflare account and wants the site in it, the operator works under a scoped API token they mint or scoped member roles (Workers, DNS, Zaraz), never Super Administrator. | The business's own account |
| Domain | Registered in the client's name; the operator edits DNS through the zone and never holds the registrar login | The business's registrar account |
| GA4 property | Client is Administrator; operator is Editor | Business is Administrator; whoever runs the site is Editor |
| Search Console | Client and operator are both Owners (Owner is needed to configure the export) | Business account as Owner |
| Google Ads | Client's account; operator manages through a manager-account link; ad spend is the client's | The business's account |
| Saprel Web subscription | Per site; paid by the client, or by the operator on the client's behalf; the landed data is the client's regardless | Per site; the business pays |
If Saprel lands your analytics data, each source gets one named Saprel service account, added by the property's Administrator and removable in one row. That is the only access the platform holds.
Create the repo from the kit
- Create a new private repository from the kit. Use it as a GitHub template, or clone it at a pinned version and start a fresh history with an "Instantiate site kit" first commit. Pinning matters: the kit moves, and a site should upgrade deliberately, not by accident.
- Name it for the site and open your agent in it from the first step; the session that instantiates is the one that provisions.
- Enable the hooks once per clone:
git config core.hooksPath .githooks
The hooks enforce the commit conventions; the same rules run on pull requests. The docs/ folder stays committed: a gitignored spec layer is a single-machine spec.
Instantiate
Work through the kit's quick start, in this order.
- Brand find-and-replace. Replace the placeholder brand name, domain and the home page's
[Tagline](its<title>,og:title, and the meta/og description, which are sample copy) acrosspublic/anddocs/. Grep afterwards forExample Co,example.comand[; a placeholder that survives will ship. - Design tokens. Re-skin the custom properties at the top of the stylesheet from the visual-identity section of the brand strategy: the colour tokens, the two type families, spacing and radius if the strategy specifies them. Keep the token names; change the values. This is where the look of the site is decided.
- Fonts. Self-hosted only. Subset each weight you use to latin and latin-extended, drop the woff2 files into the fonts folder, uncomment the matching font-face blocks, and preload the two weights that render above the fold. No CDN font link, not even "for now".
- Site configuration. Fill the Global Settings section of the site configuration document: navigation, the CTA table (this is the single source of CTA copy), tracking mode, image conventions, forms, and indexing rules. Then the page list, one spec block per page, each with a status.
- Voice rules. Copy the brand strategy's voice rules into the slot in the agent instructions file, keeping them short and checkable by an agent without judgment calls. Mirror the CTA table there too.
Gate: the repository has no placeholder text, the tokens and fonts are the client's, and the site configuration describes the real site.
Deploy the preview
- Pin the account id in
wrangler.toml, so a multi-account user can never deploy into the wrong account: add one line undercompatibility_date(the id is in the right-hand column of the account's Workers & Pages overview), and set the workernameto match the repository. The kit file carries no slot for it; the line is the site's, and a kit release never touches it (Taking a kit release, below).
account_id = "<the account's 32-character id>"
No local wrangler login is needed for deploys: Cloudflare builds and deploys from the repository.
- Connect Cloudflare's Workers Builds to the repository so every push to the main branch deploys; the first build creates the Worker. In the Cloudflare account: Workers & Pages, Create, Import a repository. The fields:
| Field | Value |
|---|---|
| Git account | The organization that holds the site repository. Cloudflare's GitHub App stays installed on all repositories in that organization. Never switch it to a selection: a selection replaces the previous one and silently disconnects every other site's builds. |
| Repository | The site's repository |
| Production branch | main |
| Build command | Empty. Static assets need none. |
| Deploy command | npm ci && npm run deploy |
| Version command (non-production branches) | npm ci && npm run deploy:preview. The field may appear only after the first branch build; set it then. It mirrors the deploy command: the kit's deploy:preview script writes the build stamp and then uploads a version (wrangler versions upload), so a branch preview carries /build.txt like production. Cloudflare's default for this field skips the stamp. |
| Root directory | /, the default |
| Build watch paths | Defaults |
The deploy command runs the kit's own deploy script, which writes the commit's short SHA to /build.txt and then deploys. The launch check reads that stamp and fails when the live site is not the pushed commit: twice a site took pushes that deployed nothing and nothing outside noticed. The repository pins wrangler in package.json and package-lock.json and turns install scripts off in .npmrc, so the build runs the version the repository names and nothing else. Without a lockfile the build image picks its own package manager; one site's first build ran a different installer with scripts on. Save and deploy.
The site comes up on a workers.dev address: the preview URL, where everything is reviewed before launch. The kit's _headers file carries a staging noindex that stays on until launch day.
- After connecting: enable non-production branch builds under Branch control, so each branch gets its own preview address. Leave the root directory at
/; the Worker and its config live at the repository root and point atpublic/themselves. Leave build watch paths at their defaults; a docs-only push rebuilds an identical site for a minute of free build time, and one less setting per site is worth more than that minute. Then prove the connection: push a small commit and watch the build run and the live site change. A passing launch check does not prove this step; one site ran for a month on hand deploys because it was skipped.
3a. Put the preview behind Cloudflare Access, in this order. Preview URLs are public and Cloudflare adds no noindex of its own, so from the first deploy the whole Worker sits behind an Access gate: every path, /api/* included, answers with a login page until someone signs in. The Zero Trust Free plan needs a card on the client's Cloudflare account before it activates; that is a client row at handover. First rename the Zero Trust team domain to something the client would recognise (it is in every login URL). Then, before creating the gate, add the One-time PIN identity provider under Settings, Authentication. An application created with no login method sends no code to anyone, and nothing says so. Then create one reusable policy named Reviewers: action Allow, include Emails, the reviewers' addresses, login method One-time PIN. Then apply the gate at the Worker: Workers & Pages, the Worker, Settings, Domains & Routes, enable Cloudflare Access on the workers.dev address and on previews, policy Reviewers, session duration 7 days. While the gate is on, nothing in _headers or robots.txt reaches a crawler, because Access answers before the Worker and the assets do; do not try to test the noindex header until the flip. The form's endpoint is behind the gate too, so a form test runs from a signed-in browser or after launch. Prove the gate from the command line:
PRE_FLIP=1 WORKERS_DEV_URL=https://<worker>.<account>.workers.dev npm run qa:launch https://<worker>.<account>.workers.dev
It passes when the workers.dev host answers with the Access redirect.
npm cionce per clone, thennpm run qa:browseronce per clone, thennpm run devserves the site locally; the screenshot script expects it there. Oncewrangler.tomlhas a route, local requests are served under that hostname and the worker's localhost Turnstile skip no longer fires: copy.dev.vars.exampleto.dev.varsand use Cloudflare's test site key in the page while developing. That file holds only Cloudflare's public test keys, never a real secret.
Gate: the workers.dev host answers with the Access redirect, and a signed-in reviewer sees the site.
Tracking
The kit's default is Cloudflare Zaraz, tag management that runs at the edge rather than as a script in the page. No analytics snippet ships in the HTML; the site's JavaScript calls Zaraz when it is present and falls back to a direct Google tag only where a client constraint forces that mode.
- GA4 property. Use the business's existing property or create one, owned by the business as Administrator, one Analytics account per business. Add a web data stream for the domain and note its measurement id.
- Zaraz. In the zone's tag management, add the Google Analytics tool with that measurement id. Set the bot threshold to block automated traffic only, so crawlers still get the page but stay out of the analytics. Skip GA4's own "test installation" button; it looks for a script that is not there by design.
- Consent, by market. Answer one question: are this site's visitors mainly in the EU or UK? If not: Google Analytics through Zaraz with no banner; Zaraz's consent management and Google's consent-mode setting both stay off (consent mode on with no banner to update it sends every hit as denied and hollows out the data). The tool sets two first-party cookies for every visitor, and the privacy page says so. If so: either cookieless analytics in the vendor's anonymous configuration with no banner, or a real consent banner whose choice updates consent mode; Google Analytics with no banner is not an option there, however it is loaded. The settings for the cookieless branch, and the reasoning, are in
docs/decisions/0005. Either way the form sets no cookie. Record which posture the site uses in the search plan's CDN-settings table. - Events. The kit fires four standard events: form submit, outbound click, phone click, download click. Mark the ones that matter as key events in GA4: create each by name under Admin → Key events the day it ships; GA4's events list lags real-time by up to a day, so do not wait for it. Register
form_typeandofferas event-scoped custom dimensions. Never registersubmission_id: it is unique per event, and it belongs in the BigQuery export, where the join to the stored submission happens. Do not invent new event names per site; extend the properties instead.
Gate: a visit from a real browser appears in GA4's real-time view, and a fresh private window shows no banner, no storage keys, and no cookie other than the two first-party cookies Zaraz's Google Analytics tool sets for every visitor (docs/decisions/0004).
Data sources
Analytics exports are forward-only. Every day before the export exists is history nobody will ever have, so this step happens the day the properties exist, not at launch.
- Search Console. Verify the domain as a domain property, by DNS record, with the site's operator as a verified Owner. Owner, not Full, because only an Owner can configure the export. Then switch on the bulk data export to BigQuery. If Saprel lands the data, the destination is Saprel's project and you add Saprel's service account as a Full user; standalone, the destination is a project of your own.
- GA4 to BigQuery. For a site on the Saprel platform, the property's Administrator adds Saprel's analytics service account as Editor, and Saprel creates the daily export link; the operator's job is the Editor rows, nothing more. Standalone, create the link from the property's admin settings to your own project. Daily export either way; the first table lands a day or two later.
- Google Ads, if the business runs it. For a platform site, the account's Admin adds Saprel's service account as Read only on the client's own account, not on any manager account. Standalone, set up the Ads transfer in your own project.
- Existing sites. Search Console serves a sixteen-month trailing window that shrinks daily. Pull the history the same day the export is configured.
Gate: the next day, the Search Console export tables exist, and the GA4 dataset shows its first daily table within two days.
Forms
The kit's worker handles the lead form's POST and the small token request that goes with it, and passes everything else through to the static site. wrangler.toml routes /api/* to the worker first; leave that line in (Troubleshooting says what happens without it). Every integration is opt-in; a missing setting skips that step.
Setting a Worker secret. Every secret below is set the same way, from a kit clone, on a machine where wrangler login holds the Cloudflare user that has the client's account:
CLOUDFLARE_ACCOUNT_ID=<account id> npm exec --no -- wrangler secret put <NAME> --name <worker>
The login is what matters. An operator and a platform are separate Cloudflare users, and wrangler acts as whoever is logged in, so before setting a client's secrets log out and log in as the user that holds that client's account; the account id and --name only stop a same-named Worker in another account from taking the secret. The value goes in at the hidden prompt or over stdin, never as an argument. A client's own machine never writes Worker secrets: its site-ops token is read-only on Workers, and wrangler login is a browser sign-in to a person's Cloudflare user, which does not belong on a shared box. scripts/issue-intake-key.sh runs the same command from the repo root, where the pinned account_id applies.
- Turnstile. Create a Turnstile widget for the domain in Cloudflare, one widget per site. A widget is bound to its hostnames: add the preview host too if the form will be tested before launch. Put the real site key in the form markup (
public/contact.html, where the placeholder widget is commented out next to Cloudflare's test site key) and the real secret on the worker: a mismatch fails every real submission, and Cloudflare's test keys on both sides pass every bot. The launch check refuses a test key on the form's page, which it reads from the site configuration's forms table. Give the worker the secret through stdin, never on the command line:
CLOUDFLARE_ACCOUNT_ID=<account id> npm exec --no -- wrangler secret put TURNSTILE_SECRET --name <worker>
- Lead notification. Set the worker's webhook setting to a Slack or Google Chat incoming webhook, or whichever destination the business reads. A submission posts a compact summary there. The webhook URL is a secret: hidden prompt only, never in a file or a chat. A Google Chat incoming webhook can only be created by a member of that space's Workspace; if the client's space is not yours to configure, post to a space you own until the client creates theirs, then swap the secret and delete the old webhook.
What to send the client, for a Google Chat space (their Workspace admin may need the first two):
> Incoming webhooks must be allowed in your Google Workspace: Admin console, Apps, Google Workspace, Google Chat, Webhooks. A personal Gmail account cannot create one; this needs a Workspace account.
> In the space where you want to see new leads: open the space's name at the top, Apps & integrations, Add webhooks. Name it Web leads, and set the avatar URL to https://saprel.com/saprel-logo-icon.png. Save, then copy the webhook URL and send it to us by direct message only, not in the space and not by email.
The name is fixed on purpose: on a platform site the platform's agent posts its follow-up in the same space, and the webhook's name is how a reader tells the site's own notice from the agent's message. Then set the secret:
CLOUDFLARE_ACCOUNT_ID=<account id> npm exec --no -- wrangler secret put LEAD_WEBHOOK_URL --name <worker>
Prove it with one real browser submission; a test lead never posts to the webhook. Delete the old webhook the same day if one was swapped out.
- CRM handoff. If the business's CRM or marketing platform exposes a form-handler endpoint, set the worker's form-handler setting to it and the fields forward as a form post. The worker redirects to the thank-you page whether or not downstream succeeds, so a failure never loses the lead.
- Lead screen. Set
SITE_DOMAINto the site's domain, a plain var, not a secret: add this block at the end ofwrangler.toml(the kit file has no[vars]section; plain settings are the site's own, and a kit release never touches the file):
# Plain (non-secret) settings the worker reads (site-config, Forms, "This site's
# worker settings"). Secrets never go here.
[vars]
SITE_DOMAIN = "example.com"
Then give the worker a signing secret for its time-to-submit check. Generate it and pipe it straight in, so it never appears on screen:
openssl rand -hex 32 | tr -d '\n' | CLOUDFLARE_ACCOUNT_ID=<account id> npm exec --no -- wrangler secret put FORM_SIGNING_SECRET --name <worker>
A submission that reads as spam (too fast, throwaway address, a sales pitch) is never dropped. On a platform site it is stored and left out of the notification destination; on a standalone site it is posted there marked as possible spam.
- Platform sites (optional; a site on the Saprel platform). Add
INTAKE_URL = "https://api.saprel.ai/api/intake"to the same[vars]block. The intake key is issued here and registered there: runbash scripts/issue-intake-key.shwith the platform operator live at the same moment. It prints the key's hash and waits; the hash is safe to relay in a chat; they register it; you press Enter and the key goes to the worker asINTAKE_KEY. The key itself is never shown. Then, after the site is deployed, set the test token and send one test lead from the same shell, so the token exists nowhere but the worker:
T=$(openssl rand -hex 32)
printf %s "$T" | CLOUDFLARE_ACCOUNT_ID=<account id> npm exec --no -- wrangler secret put TEST_LEAD_TOKEN --name <worker>
sleep 15
printf 'test_token=%s' "$T" | curl -s -X POST https://{site}/api/lead \
--data-binary @- -d 'email=probe@example.com' -d 'name=Test lead' \
-d 'form_type=inquiry' -d 'offer=contact' -d 'consent_version=inquiry-v1'
unset T
Expect JSON with platform: ok. The wait matters after any wrangler secret put: the previous deployment answers until the new one has propagated. Standalone sites skip this step; the form works without it.
- The form carries a honeypot and a one-line consent notice. Keep the notice, and bump the form's
consent_versionwhen its wording changes. The form sets no cookie. Add the form paragraph to the privacy page (the site configuration's Forms section has a draft to adapt): a policy that says contact happens by email is wrong the day the form goes live.
The form refuses submissions if the Turnstile secret is missing anywhere but localhost. A site never runs its form without the gate.
Gate: one real submission from a real browser, not curl: Turnstile passes, the visitor lands on /thank-you, the summary reaches the notification destination within seconds and the CRM if configured, and on a platform site the test lead returned platform: ok. A browser sends a form as a page navigation and command-line tools do not, so only a browser proves the form. /thank-you and /form-error are flat pages, both noindex; a refused submission gets the error page with the refusal's status code.
Build the pages
Homepage first. The homepage is built and approved before anything else. It carries both halves of the strategy: the messaging (hero, calls to action, navigation) and the look and feel (the tokens rendered as a real page). Positioning and visual direction are approved by approving a homepage, not by reading a document; everything after inherits that decision.
Then every other page from its spec. Each page has a spec block in the site configuration: URL, meta, keywords, schema, proof points by id, internal links, status. The agent builds against the spec and does not improvise. Shared navigation and footer live in the homepage file and propagate from there.
The QA scripts, and what each one catches:
npm run qa:driftfails on any nav or footer that is not byte-identical to the homepage's.npm run qa:screenshotrenders desktop and phone views of the pages you name, so a change is looked at, not only diffed, and fails if anything overflows the phone's width. Run it on every page a shared block touches, not only the page you edited.npm run qa:lighthouseruns Lighthouse on every page inpublic/from a local server, median of three runs, and fails under ninety on any of the four categories, accessibility included. Not an average. It needs the per-clone browser (npm run qa:browser).npm run qa:chatchecks the worker's Google Chat body against Google's published message schema; a field Chat does not know fails every notification silently. Only a browser submission to the real webhook proves the whole path.npm run qa:redirectschecks every concrete rule in the redirects file for status and destination.npm run qa:cadencefails on any document underdocs/whose refresh date is older than its class allows.npm run qa:refsfails when a doc names a path, annpm runscript or a numbered section that does not exist; a guide that points at a file that is not there is how a stranger gets stuck. It knows a repository slug, a URL and a section of a named outside document when it sees one. A path that is planned but not yet written is backticked with aplanned:prefix; a handoff or decision record that cites an outside document throughout carries `` in its first lines, and a doc with no numbered headings is never the target of a bare section citation.npm run qa:stale-claimsfails when a sentence a decision retired (listed indocs/stale-claims.json, each with the fact that replaced it) reappears anywhere in the tree.
The launch check runs the last two as well, so a site cannot launch with a guide that names a file that is not there; a section citation the parser cannot read is printed as a warning there, not a blocker.
Also before a page is done: no unresolved proof placeholder, FAQ schema matching the visible text, images with explicit dimensions.
Gate: the client approves the full site on the preview. Nothing flips until they do.
Working pages
Optional, one step. A site whose team wants working documents on the site itself (a tracker, a weekly report, a plan the client reads with you) adds the kit's working-pages template. The pages live at /gtm and /gtm/<name>: never indexed, never linked from the public site, behind the team login once the site is live. A site without working pages skips this section; nothing in the base tree names the path, so there is nothing to delete.
- Copy the pages. From the repo root,
cp -R templates/gtm/public/. public/puts the hub and a tracker in place. The hub file is the shell (no shared nav or footer, a breadcrumb row, an alert, a narrow column); copy it for each further page, keep its head, and link the page from the hub. Files stay flat under the one folder. - Headers and robots. Append the whole of
templates/gtm/_headersto the end ofpublic/_headers, after the sitewide block (a separate block; it stays when the launch-day edit removes the sitewide noindex line). Add the two lines oftemplates/gtm/robots.txttopublic/robots.txtabove the Sitemap line. - Site configuration. Paste the two blocks in
templates/gtm/site-config.mdinto the site configuration: the Indexing row into Global Settings, the page spec as the next numbered block among the page specs. - Fill and check. Put the site's own lines in the hub and the tracker. The drift check already exempts the path (the pages carry no shared blocks), the Lighthouse gate covers them like any other page, and the reference check sees the three template paths above.
- At launch, after the flip: a second Access application, path-scoped to
/gtmand/gtm/*on the custom domain (and on www if it serves), sameReviewerspolicy, session two weeks. Until then the Worker-level gate covers the path with everything else.
Gate: a signed-in reviewer sees the hub on the preview with the noindex, nofollow header on it, and after launch anyone else gets the Access login.
Existing site
When the business already has a site, build the new one in parallel on the preview while the old one keeps serving, and cut over at launch. Search presence is the asset at risk, so four things carry over regardless of design.
- Inventory from the live site. Capture every path, title, description, and existing redirect from the running site, not from memory. The redirect map depends on this list.
- Redirect map. Keep the old slugs wherever the new page list keeps the page. Every retired or moved path gets a permanent redirect in the redirect map document, mirrored to the
_redirectsfile, and tested with the redirect script before launch and again against the live domain after. - Canonical host. Read which of www or the bare domain the old site treats as canonical and keep it. The other host redirects to it.
- Asset snapshot. Download every image, download, and CSS-referenced background from the old host before cutover. Those files disappear with the old subscription.
Old-site defects (a dead email domain, tracking parameters in links, an empty page) are fixes, not questions; list them for the client's ruling. After cutover the old site stays reachable on its host's non-brand address for three to four months, or to the end of its contract, then is snapshotted and switched off.
- Leaving HubSpot (or a similar hosted CMS and sales suite), in this order:
- Export contacts, companies, deals and the blog before anything is deleted; the export is gone with the subscription.
- After cutover, disconnect the domain in HubSpot (Settings, Domains & URLs). A domain left connected keeps trying to renew a certificate for a site it no longer serves and emails the account about failed SSL, every time.
- Uninstall the HubSpot Sales extension from every Gmail account in the business. It injects a tracking pixel (an image served from hs-salescrm-engage.com) into every email sent, including after the site has moved; the business is still tracking its own correspondents without knowing it. Check a sent message's source afterwards for that domain.
- Only then cancel the subscription.
Launch
- Create the zone, records first. Before adding the domain to Cloudflare, capture every DNS record at the registrar: nameservers, A, MX, TXT, CNAME, and the mail-signing selectors. Do not trust the import scan; recreate every mail record explicitly. Registrar-generated SPF macros die with the nameserver change, so write the direct form. Add a site-verification record for the operator's Google account so Search Console ownership does not depend on one person.
- Bind the domain to the worker as a custom domain. It binds fine on a pending zone, but nothing can be proven end to end until the nameservers move.
- Change the nameservers at the registrar. This is the only registrar action in the whole setup, and it is the client's to make. Three waits follow in order: the registry publishes, the zone activates, the certificate issues. The bare domain comes up first and www last; a www error inside that window is the wait, not a redirect bug.
3a. Email authentication, once the zone is live, so the move does not cost the business its mail reputation. Every DNS edit here is a dashboard step on the zone (a scoped token has no DNS), done by the operator; the Workspace steps are the client's admin.
- DKIM. The client's Workspace admin generates a DKIM key (Admin console, Apps, Google Workspace, Gmail, Authenticate email): 2048-bit, selector prefix google. The operator adds the google._domainkey TXT record to the zone with the value shown. Confirm with dig TXT google._domainkey.<domain> that the record resolves, then the client clicks Start authentication. Nothing before the dig; the console reports failure for a record it cannot see yet.
- SPF should already be in the zone from the records-first step (the direct form, no registrar macro).
- DMARC. Add _dmarc TXT with v=DMARC1; p=none; rua=mailto:<a mailbox the client reads>. Let the reports arrive for one to two weeks with no failures from the business's own senders, then move to p=quarantine, and after another clean period to p=reject; the sequence ends at reject, not at none.
- The cache gotcha. Gmail's Show original reports DMARC FAIL on mail delivered before Google's resolver saw the new record, and keeps doing so for that mail. It is a cache, not a fault: send a fresh message after the records have propagated and read that one.
- Noindex off and workers.dev off, one commit, within minutes. Delete the single noindex line from
_headers, keep the rest of the block, and change the existingworkers_dev = trueline near the top ofwrangler.tomltofalse, in place. The key appears once in that file and stays once: adding a secondworkers_devline (one site's merge did) makes wrangler refuse the file. In the same commit, change the cadence class on the first line ofdocs/runbooks/monthly-seo-aeo-review.mdanddocs/content-templates/comparison-template.mdfromlookuptoliving-monthlywith today's date aslast refreshed: the kit ships them as lookup because a pre-launch site has no monthly review to run, and from this commitnpm run qa:cadenceholds the site to one. Commit, deploy. In the Cloudflare dashboard, change the Worker's Access gate from the whole Worker to Previews only, so branch previews stay behind the login and the custom domain is open. The production workers.dev host is the one address the previews-only gate does not cover, which is why it is switched off in the repository rather than left to the gate. Then:
WORKERS_DEV_URL=https://<worker>.<account>.workers.dev npm run qa:launch https://your-domain.com
It asserts that no noindex header remains, robots.txt permits crawling, the sitemap answers, answer-engine crawlers are not blocked, the live build is the pushed commit, the workers.dev host no longer serves the site, Lighthouse is ninety or above on every page, and nothing overflows a phone on the sampled pages. A failing launch check is a blocker: a staging noindex surviving the flip is the most common serious launch bug there is.
- Sitemap and redirects. Submit the sitemap in Search Console. If the site carries migration redirects, run the redirect script against the live domain.
- Zone bot settings. The kit's robots.txt allows answer-engine crawlers on purpose, but a new Cloudflare zone ships with a managed rule that blocks them. Set the zone's AI crawler control to allow, turn off bot fight mode and the labyrinth feature, and confirm in the zone's security events that no allowed crawler is blocked. Edge blocks never reach the worker's logs. Then revoke any temporary API token used for setup.
- Working pages, if the site added them: the path-scoped Access application from the Working pages section, a dashboard click on launch day.
Gate: the launch check passes on the live domain.
After launch
The build plan becomes the ops doc. Same file: retitle it, mark the strategy sections frozen at launch with the date, and record the launch notes once under recent activity. In flight, recent activity, and the parking lot carry the site from here; the session loop does not change, only what the sessions are about. There is deliberately no separate launch document.
Change reports. Every change is a commit with a what-changed-and-why message; the kit's change-report convention turns those into a narrative for a marketing reader. Low-impact changes (copy, posts, templated pages) batch into the periodic report; high-impact ones (shared blocks, headers, redirects, robots, sitemap, tracking, pricing and legal pages) are flagged before they ship and reported the same day. Revert is one commit.
Content production. New content runs the kit's content-production runbook: spec from the template, draft, QA, published with noindex, reviewed at the live URL, then the index flag flipped and the page added to the sitemap. New content is never born indexable.
Monthly review. The monthly search and answer-engine review runbook reads performance, checks comparison pages for drift, and runs the cadence check. Learnings that would help every site go into the kit first, then back into the site.
Taking a kit release
A site moves to a kit release by merging the kit's tag, never its bare main branch, and the merge is one commit named for the tag (Merge site-kit forms-v2.16, say). wrangler.toml is the site's own after instantiation (the worker name, the account pin, workers_dev, the [vars] block) and a kit release never changes it; the build plan is the site's too, so where the merge touches either, the site's copy stays. On every merge after instantiation, with the kit added as a remote named kit:
git fetch kit --tags
git merge --no-commit forms-v2.16
git checkout HEAD -- wrangler.toml
git commit -m "Merge site-kit forms-v2.16"
The checkout keeps the site's wrangler.toml whether the merge touched it cleanly or left a conflict (git checkout --ours wrangler.toml does the same in the conflict case only).
Where the kit changed a page the site has restyled (the thank-you and error pages, the stylesheet), keep the kit's page in the merge and restyle in the next commit. Then npm ci (the release may move the pinned tools), npm run qa:browser if the Playwright pin moved, npm test, npm run qa:drift, npm run qa:refs, npm run qa:stale-claims, and on a live site npm run qa:launch against the domain. Push, and the release is taken when Cloudflare's build check on the push is green and /build.txt shows the merge commit.
Troubleshooting
Eight that account for most of launch week. A longer list follows when the operator guide is published.
- Mail broke after the nameserver change: a registrar SPF macro died with the delegation; write the direct SPF record into the zone.
- Analytics shows nothing: Zaraz is invisible to command-line checks and to GA4's test button; verify from a real browser and the real-time view.
- The site is live but not in search: the staging noindex survived the flip; run the launch check.
- AI crawlers blocked while robots.txt allows them: the zone's managed bot rule; fix it on the zone, not in the repository.
- A redirect does not fire: edit the redirect map first, mirror it to the redirects file, then run the redirect script.
- The form works from curl but a browser gets 405: the static-assets layer answered the form's navigation request before the worker ran;
wrangler.tomlneedsrun_worker_first = ["/api/*"]. The launch check tests for this. - Google Chat shows nothing while Slack works: Chat rejects a webhook body carrying any field it does not know; the kit posts
textonly. Check the worker's log linelead: target=chat outcome=. - A secret you just set is not in effect: wait fifteen seconds; the previous deployment answers until the new one has propagated.
- The launch check says no build stamp is served: the Workers Builds deploy command is still the bare wrangler deploy; set it to
npm ci && npm run deploy(and the version command for branches tonpm ci && npm run deploy:preview). - The screenshot script or the Lighthouse gate says there is no browser:
npm run qa:browserin this clone; if Chromium then fails to start, the machine is missing its system packages (playwright install-deps chromium, once, with sudo). - Nobody receives a login code from the preview: the Access application was created before the One-time PIN identity provider existed; add the provider, then edit the application's login methods.