From design file to live website

# [SITE NAME] — Build log

> **Template.** Save as `handoff/BUILD-LOG.md`. Claude keeps it current. Newest work goes under its own dated heading;
> "Still to do" and "Custom code used" are updated in place, and their numbers are kept so earlier references match.

## Setup ([DATE])
- WordPress [version], Elementor [version] + Pro [version] ([license plan]), Hello Elementor, [WooCommerce], [plugins].
- Local site URL: `https://[site].local` (HTTPS on). PHP [version].
- Visibility: [Drafts until approval / published behind Coming soon].

## Globals ([DATE])
- Colors, fonts, sizes and radii loaded from `design-tokens.md`: [list variable names or point to the kit].

## Pages
### [Page name] ([DATE]) [✅ approved by OWNER / 🟡 waiting for review]
- Built from: [containers/widgets]. Matched the reference at 1440px; phone pass at 375px.
- Couldn't match: [anything, and why].

## Decisions from the owner
- [DATE] [Name]: "[their words]" → [what changed].

## Hosting
- Environment: [host] `[env name]` (`https://[address]`), PHP [version].
- Pushes: [DATE] (files + database). Post-push fixes done: [list].
- Reviewer access: [Seamless Login / user / share link].
- Wiped by a database push: [payment keys, licenses, mailer connection, host-only users…].

## Still to do
**Waiting on the owner or others**
1. [item]

**At launch**
2. [item] (see `LAUNCH-PLAYBOOK.md` section [n])

**Known gaps (small)**
3. [item]

## Custom code used
### `[site]-site.php` (must-use plugin): what each piece does, in plain English
1. **[Name].** [What it does, why, which hooks/selectors.]

### Template overrides (`mu-plugins/[site]-templates/`)
- [file]: [why it's overridden; compare after plugin updates].

### Custom CSS (Site Settings → Custom CSS)
- [area]: [selectors].

## Couldn't match
- [item]: [reason].

# [SITE NAME] — Page-by-page build spec

> **Template.** One section per page, in build order. Claude builds exactly what's listed here, in this order, with
> the copy from the reference design. Anything not listed gets asked about, not invented.

## Global: header (Theme Builder → Header)
- Top bar (desktop only): [phone, hours, languages, cart link].
- Logo + tagline: [file, tagline text, which widths show the tagline].
- Menu: [items in order; which are mega menus or dropdowns and what they contain].
- Call to action: [button text → link].
- Phone/tablet: hamburger with tap-to-open accordions; in the bar: [logo, cart, CTA].

## Global: footer (Theme Builder → Footer)
- Columns: [logo + blurb, link lists, contact details, social icons in order].
- Legal row: [links, in order]; on phones: [e.g. 2×2 grid, no separators, 44px tall].

## Pages (build in this order)

### 1. [Page name] — `/[slug]/`
- **Sections, top to bottom:**
  1. [Hero: eyebrow, H1, text, button(s) → links, image].
  2. [Section: heading, cards (how many, what's on each), button → link].
- **Widgets:** [containers/grid, heading, text, button, image, loop grid, accordion, form…].
- **Data:** [which CSV or post type feeds it].
- **Phone:** [carousels, stacking, anything special].
- **SEO:** title "[≤60 chars]", description "[≤155 chars]", share image [file].

### Legal pages
- [Privacy Policy (list every outside service), Terms, Accessibility, Disclaimer] — text in `reference/[file]`.

## Links that must work
- [Every button and menu link with its destination, e.g. "Get a Quote" → `/contact/`.]
- [Old site URLs → new URLs (301 redirects).]

# [SITE NAME] — Design tokens

> **Template.** Load these into Elementor Site Settings (global colors, fonts and variables) before building any
> page. Every color, font and size on the site comes from here.

## Colors
| Name | Hex | Used for |
|---|---|---|
| [brand-primary] | #[......] | [buttons, accents, product line A] |
| [brand-primary-dark] | #[......] | [hover, small text on light backgrounds] |
| [brand-tint] | #[......] | [light backgrounds, badges] |
| [secondary / product line B] | #[......] | [only on product line B] |
| [charcoal / ink] | #[......] | [headings, dark sections] |
| [body] | #[......] | [body text] |
| [muted] | #[......] | [captions, notes] |
| [on-dark] | #[......] | [text on dark backgrounds] |
| [surface] | #[......] | [section backgrounds] |
| [line] | #[......] | [borders] |
| white | #FFFFFF | |

## Fonts
- Display: [family, weights]. Body: [family, weights]. Loaded from [Google Fonts / self-hosted].

## Type scale
| Token | Desktop | Phone | Weight / line height / letter spacing |
|---|---|---|---|
| fs-h1 | [clamp(..)] | | [900 / 1.08 / -1px] |
| fs-h2 | | | |
| fs-h3 | | | |
| fs-body | [15px] | [16px min] | |
| fs-small | | | |
| fs-eyebrow | | | [uppercase, letter spacing] |

## Spacing
[4, 8, 12, 16, 24, 32, 40, 48, 64] px · section padding [64 desktop / 40 phone] · gutters [40 / 24 / 16].

## Radii
[r-sm 6, r-md 10, r-lg 12, r-xl 16, pill 999].

## Layout
Content max width [1400px]; narrow text [760px]; card padding [24px]; grid gap [24px].

## Buttons
| Style | Background | Text | Border | Radius | Padding | Hover |
|---|---|---|---|---|---|---|
| Primary | | | | | | |
| Secondary / outline | | | | | | |

# Launch playbook: Local → host → live

Written for **Local + WP Engine**, but most steps apply to any host. Tick items off and note dates in `BUILD-LOG.md`.
The reasons behind each step are in `LESSONS.md`.

---

## 1. Before the first push

- [ ] **Local uses HTTPS** (Local → site → SSL → Trust, and the site URL starts `https://`). If Local is http, the push
      saves the hosted site's WordPress Address as `http://`, and browsers then block the page styles.
- [ ] **No absolute local addresses in live content.** Search the database for the `.local` domain and fix:
  - Elementor page data and templates (use root-relative `/wp-content/...` links)
  - Elementor's plain-HTML page copies (rebuild them from the page data)
  - redirects
  - plugin "return to shop" links

  Leave revisions and attachment GUIDs alone.
- [ ] **Things that need a full URL are generated, not stored:**
  - the email header logo (filter it to the Media Library URL)
  - share images (turn root-relative into full URLs)
- [ ] **Error check on Local:**
  - every published URL returns 200 with no PHP warnings
  - no JS errors or failed requests on key pages at 1440 and 375px
  - the PHP error log has nothing new
- [ ] **Site root is clean:** no preview/test HTML files or `local-xdebuginfo.php` (move them out).
- [ ] **`mu-plugins/` and `uploads/` are present.** Check there's no push-ignore file excluding them.
- [ ] **Record what the push will wipe on the host:** payment keys, license activations, host-only users, the mailer
      connection, and anything built directly on the host.

## 2. Create the host environment (WP Engine)

- [ ] **Create the environment.** A sandbox (free) is fine for review, but **sandboxes can't use a custom domain**. For
      launch, convert it to a billable site or create a production environment.
- [ ] **Match Local's PHP version** in the environment's Overview → Updates → PHP.
- [ ] **Connect Local:** Local → Connect → WP Engine → log in (Local adds its own key).
- [ ] **Push:** Local → site → **Push** → existing site → environment, with **Files: All files** and **Database ticked**.

## 3. Right after every push (with the database)

- [ ] **Settings → General:** both addresses `https://[host address]`. Then Settings → Permalinks → Save.
- [ ] **Elementor → Tools → Regenerate CSS & Data.** Then **Replace URL** from the old address (and from `http://` to
      `https://`) if anything still points there.
- [ ] **Clear the host cache** (admin bar → WP Engine → Caching → Clear all).
- [ ] **Public visitors see Coming soon.** Logged-in or share-link visitors see the full site, styled.
- [ ] **Licenses** (see section 7): Elementor Pro, plus any premium plugins.
- [ ] **Cloudflare Turnstile:** add the host address to the widget's allowed hostnames, with the same keys. Until
      then, checkout, login and forms fail the check.
- [ ] **Re-enter what the push wiped:** payment keys, mailer connection, host-only users.
- [ ] **Crawl every page:**
  - 200 status, no PHP output
  - no old local addresses
  - no `http://` links to the host
  - headless-browser check for blocked style sheets and JS errors

## 4. Reviewer access (owner/client)

- [ ] **Don't rely on WooCommerce's share link on WP Engine.** The page cache ignores its cookie, so only the first
      page opens. Instead, either:
  - the reviewer logs in through **WP Engine Seamless Login** (portal → environment → **WP Admin**), which creates
    their WordPress admin user automatically and survives database pushes; or
  - create a **Shop Manager** login on the host (wiped by the next database push); or
  - ask WP Engine support to bypass the page cache for the `woo-share` cookie.
- [ ] **Send the reviewer the host address** (not the `.local` one, which only works on your computer), with how to
      log in and a note that logged-out visitors see Coming soon.

## 5. Payment gateway live test *(shops)*

- [ ] **Keys are entered by the owner on the host** (live mode usually needs HTTPS, so not on Local).
- [ ] **After saving the keys, re-check the gateway screen:**
  - the payment page option (Redirect vs Embedded)
  - the enabled methods
  - the method's name and description (activating keys can reset them to plugin defaults)
- [ ] **Payment option order:** e.g. Pay at pickup first, then card. Check it on the live checkout, not just in settings.
- [ ] **Hidden test product** (private, $1, not taxable, one per order). Add it with `/cart/?add-to-cart=[ID]` while
      logged in.
- [ ] **Pay $1, then check:** Order Received page; the order is Processing with the gateway's transaction note.
- [ ] **Void it the same day** in the gateway's portal (before the batch settles). Mark the order **Cancelled** with a
      note. Don't also press WooCommerce's Refund button.
- [ ] **Turn the gateway off again** until launch, if the rules say so. Re-check that the wording and order survived
      the save.

## 6. Email sending

- [ ] **Find the mail provider:** `dig MX [domain]` and `dig TXT [domain]`. An SPF record ending `-all` means the
      site must send through that provider, or a sending service added to DNS.
- [ ] **Recipients** (see `tools/email-recipients-check.php`):
  - store emails (new, cancelled and failed orders, quote requests, quote status, gateway alerts)
  - form notifications
  - the WordPress admin email (often still a Local dev address after a push)
  - customer emails go only to the customer
- [ ] **Connect a mailer** (e.g. FluentSMTP) **on the host only.** Either:
  - **Microsoft 365:** an Entra app with redirect `https://[site]/wp-json/fluent-smtp/outlook_callback` and delegated
    Mail.Send, Mail.Send.Shared and offline_access, authenticated as the sending mailbox (needs that mailbox or an
    admin); or
  - **Google Workspace:** FluentSMTP's Gmail connection, with a Google Cloud OAuth app; or
  - **A sending service** (SMTP2GO, Brevo, Postmark): verify the domain with its DNS records, then an API key.
- [ ] **From address:** a real address on the domain, with **Force From Email**. Set WooCommerce's "From" address too.
- [ ] **Test:** one test email to yourself, then one real store email and one form email to the owner.
- [ ] **If the domain's DNS will move soon,** do this after the move (the records would only be redone).

## 7. Licenses after a domain change

- [ ] **Elementor Pro "Mismatch":** on the new site, **Disconnect**, then **Connect & Activate**. Disconnect only
      affects the site you click it on. Check how many sites the plan covers.
- [ ] **Single-site premium plugins** (e.g. YITH): deactivate on the old site (or in the vendor account), then
      activate on the new one. "Maximum activations reached" means the old activation is still in use.
- [ ] **Note in `BUILD-LOG.md` where each license is active,** and that launch needs one for the live domain.

## 8. Domain move and go-live

**Before**
- [ ] **Save the current DNS.** Run `tools/dns-snapshot.sh [domain]`, **and** export the full zone file from the
      registrar/DNS host (a public lookup can't see every record).
- [ ] **Decide where DNS will live.** Safest: keep DNS where it is and change only `@` and `www`. If DNS moves, copy
      **every email record first** (MX, SPF, DKIM, DMARC, autodiscover, verification TXT), or company email stops.
- [ ] **Final push from Local to the production environment,** then all of section 3.

**Go live**
- [ ] **Add the domain** (`@` and `www`) in the host, update DNS to the host's values, and wait for SSL.
- [ ] **Replace the host address** with `https://[domain]` everywhere (Elementor → Tools → Replace URL), then spot-check
      pages, images and maps.

**Straight after**
- [ ] **Email:** connect the mailer (section 6), and check normal company email still sends and receives.
- [ ] **Turnstile:** add the live hostname.
- [ ] **Licenses** on the live domain (section 7).
- [ ] **Payment gateway:** keys, wording and order checked. **Enable it at launch.** Add it to the Privacy Policy.
- [ ] **WooCommerce Coming soon → Live,** and turn the share link off.
- [ ] **Remove sample content and test products.** Switch tax to the automated service if a stand-in table was used.
- [ ] **Check:**
  - cookie banner pages
  - the sitemap submitted
  - share images
  - redirects from the old site's URLs
- [ ] **Remove temporary access:** SSH keys added for remote work, and temporary reviewer users.
- [ ] **Compare live DNS with the snapshot.** Log the launch in `BUILD-LOG.md`.

---

## Working on the host directly (SSH + WP-CLI)

Use this when a change must be made on the host without a push (e.g. to keep payment keys).

1. Create a dedicated key: `ssh-keygen -t ed25519 -f ~/.ssh/[host]_[site] -N "" -C "claude-code [site]"`.
2. The owner adds the **public** key in WP Engine (Profile → SSH keys, or the environment's "SSH login: Add SSH Key").
3. Connect: `ssh -i ~/.ssh/[host]_[site] -o IdentitiesOnly=yes [env]@[env].ssh.wpengine.net "wp ..."`.
   - Run scripts with `wp eval-file - --user=1` (the user is needed, or Elementor refuses saves).
   - Each command takes about a minute, so bundle the work.
   - Back up a file before replacing it, and compare checksums with Local afterwards.
4. **Run the same script on Local,** so the next push keeps the change.
5. **Purge the cache.** The page cache can serve old pages for up to 10 minutes, so add `?nc=[random]` when testing.
6. **Delete the key** in WP Engine when the remote work is finished.

# Lessons from earlier builds

Each item says what happened, why, and what to do instead. Most cost real time once.

## Hosting and pushes

- **Local on http → the push saves the WordPress Address as `http://`.** The pushed site then loads its Elementor
  style sheets over http on an https page, browsers block them, and every page looks unstyled. **Fix:**
  - turn on HTTPS in Local before the first push; or, after a push
  - set Settings → General to https
  - run Elementor → Regenerate CSS & Data
  - run Replace URL `http://` → `https://`
  - clear the cache
- **A database push replaces everything on the host.** That wipes:
  - payment keys
  - license activations
  - users created on the host
  - the mailer connection
  - pop-ups or settings built directly on the host

  Keep Local as the source of truth, and make host-only changes with a script that also runs on Local.
- **Sandboxes can't take a custom domain** (WP Engine). Plan a conversion to billable/production before launch.
- **The host's page cache holds pages for up to ~10 minutes** (`max-age=600`). After a change, test with a
  cache-busting query (`?nc=123`), or you'll be looking at old pages.
- **WP-CLI over SSH runs without a user.** Elementor refuses to save documents unless you pass `--user=1`.
- **The WordPress admin email and the WooCommerce "From" address come over as Local's dev address**
  (`dev-email@wpengine.local`). Change them after the first push, or alerts go nowhere.

## WooCommerce Coming soon

- **The share link doesn't survive WP Engine's page cache.** The first page (with `?woo-share=`) works; every other
  page is served from cache as Coming soon, because the cache ignores the `woo-share` cookie. Reviewers log in
  instead (Seamless Login or a Shop Manager user), or WP Engine support excludes the cookie from cache.
- **The public Coming soon page loads Elementor's script without its settings,** so it logs one harmless console error
  (`elementorFrontendConfig is not defined`). It goes away at launch.

## Elementor (V4 / atomic)

- **Editing `_elementor_data` directly leaves Elementor's plain-HTML copy (`post_content`) stale.** Search, Rank Math
  share images and feeds then show old content. After direct edits, rebuild it with
  `Plugin::$instance->db->get_plain_text($id)` and save it with `$wpdb` (no revision).
- **Root-relative image links in `post_content` break Rank Math share images** (og:image must be a full URL). Add a
  filter on `rank_math/opengraph/facebook/image` and `…/twitter/image` to make them absolute, or set a share image per
  page.
- **Pages without a featured image share their first picture, often an icon.** Set a social image on Home and key
  pages (Rank Math → Social), using the hero photo.
- **Kit CSS can lose to Elementor's base rules on specificity.** Prefix with `.elementor` / `.e-con`, and write kit CSS
  with a helper script, never through a tool that replaces all the kit settings at once.
- **V4 data formats:**
  - heading text: `{"$$type":"escaped-html","value":"..."}`
  - links: `{"$$type":"link","value":{"destination":{"$$type":"url","value":"..."},"isTargetBlank":{"$$type":"boolean","value":true}}}`
  - form email: `email.value.to` is a string-array; `cc`/`bcc` are strings

  Copy formats from an existing element rather than guessing.
- **Matching a reference "exactly"** usually comes down to line heights (normal vs 1.2–1.65), margins under lists,
  badge line heights and indent widths. Measure both and compare section heights; aim for within 1px.

## Elementor Pro pop-ups

- **There's no "OR" between triggers and rules.** "After 45 s OR on the 3rd page view" needs a small script: open the
  pop-up with `doc.showModal(true)` on the 3rd view, but only if `doc.triggers` exists (Elementor's own rules allow it).
- **"Show up to X times" with Count = On Open counts as soon as the pop-up is eligible on page load,** before it shows,
  so it blocks itself. Use **On Close**, and record the showing yourself on `elementor/popup/show` (key
  `popup-{id}-impressions-count`, lifetime 2628288 s for "Month").
- **A fixed-position pop-up has `offsetParent === null`.** Test visibility with `doc.getModal().isVisible()`.
- **The built-in × is 16px.** Give it a 44px tap area in the pop-up's Custom CSS.

## Payments (card gateways)

- **Live mode needs HTTPS,** so do the key entry and $1 test on the host.
- **Saving or activating keys can reset other gateway settings** (the payment page mode, method names and
  descriptions). Re-check the whole screen after every save.
- **Payment method order lives in `woocommerce_gateway_order`.** Check the real checkout, not just the settings list.
- **Logged-in tests fill checkout with that user's details,** so the confirmation email goes to them. Warn the owner,
  or test with your own details.

## Email

- **Check MX and SPF before choosing a mailer.** `v=spf1 include:spf.protection.outlook.com -all` = Microsoft 365
  only; mail from the web host will fail.
- **Adding the business inbox as a WordPress user doesn't let the site send as it.** That needs the mailbox owner or
  the mail admin (Microsoft/Google), or a sending service verified in DNS.
- **WooCommerce store emails take a comma list in "Recipient".** For a real **Cc**, add it with
  `woocommerce_email_headers`; YITH quote emails use the same filter.
- **V4 Elementor forms have their own To / Cc / Bcc fields.**
- **Changing `admin_email` triggers WordPress's "admin email changed" notice** to the old address.

## Licenses

- **Elementor Pro "Mismatch" after a domain change:** Disconnect, then Connect & Activate on the new site.
  Disconnect only sends the current site's address, so other sites stay connected.
- **Single-site premium licenses** (e.g. YITH) need moving: deactivate on the old site, then activate on the new one.

## Turnstile

- **Every hostname (Local, sandbox, live) must be in the widget's Hostname Management.** Otherwise the widget shows
  "Unable to connect to website" and checkout, login and forms can't be submitted.

## DNS and domain moves

- **A public DNS lookup can't list every record.** Export the zone file from the DNS host as well as running
  `tools/dns-snapshot.sh`.
- **Moving DNS without copying the email records stops company email.** Copy MX, SPF, DKIM, DMARC, autodiscover and
  verification TXT records first.

## Testing habits that paid off

- **Crawl every published URL:** status, PHP output, old local addresses, `http://` links.
- **Headless Chrome checks** at 1440 and 375px: console errors, failed requests, sideways scroll, tap-target sizes.
- **Side-by-side screenshots against the reference,** cropped per section, plus measured section heights.
- **Emails checked by intercepting `pre_wp_mail`,** so nothing is sent.
- **Real-behavior tests for timed things** (pop-ups): fresh browser profile per scenario, with each step's
  expectation written down.

# Responsive Prompt — Phones & Tablets

Reusable prompt for making any site responsive without changing the desktop design. Built from lessons on a live client build. Paste the section below into Claude Code (or any builder).

---

**Make this site fully responsive for phones and tablets without changing the desktop design.**

## Breakpoints
- Desktop: 1280px and up. Keep it exactly as it is now.
- Small laptop: 1025–1279px. Same layout, slightly tighter spacing. Switch the menu to a hamburger if the nav items would wrap or crowd.
- Tablet: 768–1024px.
- Phone: 767px and below.

## Rules
1. **Desktop stays untouched.** Put every change inside a media query for tablet or phone. Don't edit desktop styles.
2. **No horizontal scrolling,** ever. Nothing wider than the screen. Remove fixed pixel widths on containers and use max-width plus percentages, or grid with `minmax(0,1fr)`.
3. **Navigation:** at 1024px and below, the full menu becomes a hamburger. The mobile menu must have the same items, order and dropdown groups as desktop, with dropdowns as tap-to-open sections. Every item must be reachable by tap, never by hover only.
4. **Side-by-side cards** (product rows, galleries, benefit cards, logos):
   - Phone: a carousel showing 1 card plus a small peek of the next, with ‹ › arrow buttons and a "1 of X" counter. Arrows sit below the cards, never covering images or text. Swipe also works.
   - Tablet: 2 cards per view, same arrows.
   - No plain sideways-scroll strips with hidden scrollbars. If items sit side by side on mobile, they get arrows.
5. **Keep stacked (no carousel):** forms, FAQ accordions, long text, spec tables, checkout, cart, footer.
6. **Long sections on phones** (FAQs, resource lists, document lists): collapse into tap-to-open accordions, closed by default, with the item count in the header.
7. **Text:** phone body text at least 16px. Headings scale down with `clamp()` so nothing overflows. Long words and URLs wrap.
8. **Tap targets:** buttons, links, chips and form fields at least 44px tall, with at least 8px between them. Inputs at least 16px font so phones don't zoom in.
9. **Images:** `max-width:100%`, height auto, `object-fit:cover` in fixed-ratio boxes. Never stretched or squashed. Hero images crop sensibly on phones.
10. **Multi-column layouts:** 3–4 columns → 2 on tablet → 1 on phone. Odd counts must not leave one orphaned card with empty space beside it.
11. **Spacing:** reduce section padding on phones (roughly 40px top and bottom, 18–20px sides) so it doesn't feel empty or cramped.
12. **Header and footer** must be responsive too: footer columns stack, contact info stays readable, the logo scales.
13. **Pop-ups and fixed bars:** bottom bar on phones, never blocking the whole screen. Easy-to-tap close button.

## Testing (before saying it's done)
- Check at **375px, 390px, 768px, 1024px, 1280px and 1440px**.
- At each size, confirm: no sideways scroll, nothing overlapping or cut off, every menu item reachable, all carousels have working arrows, all buttons tappable.
- Send screenshots of every page at 375px and 768px, and one at 1440px to prove desktop is unchanged.
- List anything you couldn't fix, and why.

## Process
- Make a backup before changing anything.
- Work page by page or in small batches, and wait for approval between batches.

---

*Adjust the breakpoints or carousel rules if a project's design calls for it. The rest applies to almost any site.*

# WordPress site kit (Elementor + Local + WP Engine)

A reusable starting point for building a client's WordPress site with Claude Code, based on a live
client build (Oct 2026). It holds the instructions, process and checklists. You supply each site's design and content.

## What's in the kit

| File | What it's for |
|---|---|
| `CLAUDE.md` | Instructions Claude reads first: site rules (fill in), quality rules, standing rules, build order, mobile rule. |
| `BUILD-LOG.md` | Template for the running record of what's built, decisions, custom code and what's left. |
| `LAUNCH-PLAYBOOK.md` | Checklists: before the first push, after every push, reviewer access, payment test, email, licenses, domain move, go-live, SSH work. |
| `LESSONS.md` | Gotchas from earlier builds, with the fix for each. |
| `page-spec.md` | Template: header, footer and every page, section by section, with links. |
| `design-tokens.md` | Template: colors, fonts, type scale, spacing, radii and buttons for Elementor globals. |
| `tools/dns-snapshot.sh` | Saves a domain's public DNS (and flags the mail provider and a strict SPF record) before a move. |
| `tools/email-recipients-check.php` | Lists who every store, customer and form email goes to. Read-only by default. |

## Starting a new site

0. **Design the site in Claude Design** and get the owner's approval on every page. Export the approved design as
   HTML for `reference/`.
1. **Create the site in Local** with HTTPS on. Note the PHP version.
2. **Make a `handoff/` folder** in the Local site folder (next to `app/`) and copy this kit into it.
3. **Add the site's inputs** to `handoff/`:
   - `reference/`: the approved design (HTML file, or screenshots/PDFs), with each page labeled by its URL
   - `page-spec.md` and `design-tokens.md`: fill in the templates
   - `data/`: CSVs for products, locations, FAQs and documents, plus an `image-map.csv` (file → new filename + alt text)
   - `images/`: every image the design uses
   - `mobile-guide/` (optional): phone/tablet previews
4. **Fill in `CLAUDE.md`:** the site name, the plugins in use, and the **Site rules** (pricing, contact details, names
   never to use, colors, what's bought vs quoted, shipping, tax, payments, business details, social links, email
   routing). Delete the optional parts that don't apply.
5. **Copy `BUILD-LOG.md`** in as the empty log.
6. **Open Claude Code in the Local site folder** and start with:
   > Read `handoff/CLAUDE.md` and follow it. Start with step 1 of the build order and check with me before moving to
   > the next step.
7. **Before building pages,** connect Claude to Elementor (WP Admin → Elementor → MCP / AI connection) if you use it.

## Things to have ready (they don't block starting)

- **Licenses:** Elementor Pro and any premium plugins. Check how many sites each license covers (Local, staging and
  live may each need one).
- **Payment gateway:** test keys if the gateway has a sandbox; otherwise plan one $1 live test on the host.
- **Hosting account access:** WP Engine. Remember that sandboxes can't take a custom domain.
- **Domain/DNS access:** registrar and DNS host. Find out who manages the business email (Microsoft 365 / Google).
- **Cloudflare account** for Turnstile, the owner's email for notifications, and the business inbox for Cc.

## Using it on non-WooCommerce or non-WP Engine sites

- **No shop:** delete the WooCommerce, quote, shipping, tax and payment parts from `CLAUDE.md`, and sections 5–6 of
  the playbook.
- **Another host:** the playbook's order still holds (push → post-push fixes → reviewer access → email → licenses →
  domain → go-live). Swap in that host's push tool, cache-clearing and SSH steps.

#!/bin/zsh
# Saves a public snapshot of a domain's DNS before a move (website, email and common Microsoft 365 / Google records).
# usage: ./dns-snapshot.sh example.com [output-file]
# A public lookup can't list every record: also export the full zone file from the DNS host.

D="${1:?usage: dns-snapshot.sh example.com [output-file]}"
OUT="${2:-dns-snapshot-$D-$(date +%Y-%m-%d).txt}"

{
  echo "DNS snapshot for $D, taken $(date '+%b %d, %Y %H:%M') (public lookup)."
  echo "Copy every email record to the new DNS host BEFORE switching nameservers, or company email stops working."
  echo
  for q in "NS $D" "A $D" "AAAA $D" "MX $D" "TXT $D" "CNAME www.$D" "A www.$D" "TXT _dmarc.$D" \
           "CNAME autodiscover.$D" "CNAME selector1._domainkey.$D" "CNAME selector2._domainkey.$D" \
           "TXT google._domainkey.$D" "CNAME lyncdiscover.$D" "CNAME sip.$D" "CNAME enterpriseregistration.$D" \
           "CNAME enterpriseenrollment.$D" "SRV _sip._tls.$D" "SRV _sipfederationtls._tcp.$D" "CAA $D"; do
    set -- ${=q}
    r=$(dig +short "$1" "$2" | tr '\n' ' ')
    printf '%-6s %-44s %s\n' "$1" "$2" "${r:-(none)}"
  done
  echo
  ns=$(dig +short NS "$D" | head -1)
  mx=$(dig +short MX "$D" | head -1)
  echo "DNS host: ${ns:-unknown} | Mail: ${mx:-none}"
  case "$mx" in
    *outlook.com*) echo "Mail provider looks like Microsoft 365." ;;
    *google.com*|*googlemail.com*) echo "Mail provider looks like Google Workspace." ;;
  esac
  spf=$(dig +short TXT "$D" | grep -i 'v=spf1')
  [[ "$spf" == *"-all"* ]] && echo "SPF ends in -all: the website must send through the listed providers or a service added to SPF/DNS."
} > "$OUT"

cat "$OUT"
echo
echo "Saved to $OUT"

<?php
/**
 * Shows who every site email goes to: WooCommerce/plugin store emails (To and Cc), customer emails, Elementor form
 * notifications (classic and V4 forms) and the WordPress admin email.
 *
 * Safe by default: it only reads settings and headers, and sends nothing.
 *   wp eval-file email-recipients-check.php --user=1
 * Optional, on Local only: TRIGGER=1 also runs the order emails against the newest order, stopping every message at
 * pre_wp_mail so nothing is actually sent.
 *   TRIGGER=1 wp eval-file email-recipients-check.php --user=1
 */

$cc_of = function ( $headers ) {
	$h = is_array( $headers ) ? implode( "\n", $headers ) : (string) $headers;
	preg_match_all( '/^Cc:\s*(.+)$/mi', $h, $m );
	return $m[1] ? implode( ', ', array_map( 'trim', $m[1] ) ) : '(none)';
};

echo 'Site: ', home_url(), "\n";
echo 'WordPress admin email: ', get_option( 'admin_email' ), "\n";

if ( function_exists( 'WC' ) ) {
	echo 'WooCommerce "From": ', get_option( 'woocommerce_email_from_name' ), ' <', get_option( 'woocommerce_email_from_address' ), ">\n";
	echo "\nStore and plugin emails (headers read only):\n";
	foreach ( WC()->mailer()->get_emails() as $cls => $e ) {
		if ( ! $e->is_enabled() ) { continue; }
		if ( $e->is_customer_email() ) {
			printf( "  %-52s To: the customer\n", $e->get_title() );
			continue;
		}
		$headers = @$e->get_headers(); // Some plugin emails expect an object; the Cc line is still read correctly.
		printf( "  %-52s To: %s | Cc: %s\n", $e->get_title() . " [{$e->id}]", $e->get_recipient(), $cc_of( $headers ) );
	}

	if ( getenv( 'TRIGGER' ) ) {
		$caught = array();
		add_filter( 'pre_wp_mail', function ( $return, $atts ) use ( &$caught, $cc_of ) {
			$caught[] = 'To: ' . ( is_array( $atts['to'] ) ? implode( ', ', $atts['to'] ) : $atts['to'] ) . ' | Cc: ' . $cc_of( $atts['headers'] ) . ' | "' . $atts['subject'] . '"';
			return true; // Stop: nothing is sent.
		}, 10, 2 );
		$ids = wc_get_orders( array( 'limit' => 1, 'orderby' => 'date', 'order' => 'DESC', 'return' => 'ids' ) );
		if ( $ids ) {
			echo "\nOrder emails run against order #{$ids[0]} (intercepted, nothing sent):\n";
			$mailer = WC()->mailer()->get_emails();
			foreach ( array( 'WC_Email_New_Order', 'WC_Email_Cancelled_Order', 'WC_Email_Failed_Order', 'WC_Email_Customer_Processing_Order' ) as $cls ) {
				$caught = array();
				$mailer[ $cls ]->trigger( $ids[0] );
				printf( "  %-36s %s\n", $mailer[ $cls ]->get_title(), $caught ? $caught[0] : 'not sent (disabled)' );
			}
		}
	}
}

global $wpdb;
echo "\nElementor form notifications:\n";
$rows = $wpdb->get_results( "SELECT p.ID, p.post_title, pm.meta_value FROM {$wpdb->postmeta} pm JOIN {$wpdb->posts} p ON p.ID = pm.post_id WHERE pm.meta_key = '_elementor_data' AND p.post_type <> 'revision' AND p.post_status <> 'trash' AND ( pm.meta_value LIKE '%\"elType\":\"e-form\"%' OR pm.meta_value LIKE '%\"widgetType\":\"form\"%' )" );
foreach ( $rows as $r ) {
	$walk = function ( $els ) use ( &$walk, $r ) {
		foreach ( $els as $el ) {
			if ( 'e-form' === ( $el['elType'] ?? '' ) && isset( $el['settings']['email']['value'] ) ) {
				$em = $el['settings']['email']['value'];
				$to = isset( $em['to']['value'] ) ? implode( ', ', wp_list_pluck( (array) $em['to']['value'], 'value' ) ) : '(default)';
				printf( "  #%d %-28s V4 form \"%s\": To: %s | Cc: %s | Bcc: %s\n", $r->ID, $r->post_title, $el['settings']['form-name']['value'] ?? '', $to, $em['cc']['value'] ?? '(none)', $em['bcc']['value'] ?? '(none)' );
			} elseif ( 'form' === ( $el['widgetType'] ?? '' ) ) {
				$s = $el['settings'];
				printf( "  #%d %-28s form \"%s\": To: %s | Cc: %s | Bcc: %s\n", $r->ID, $r->post_title, $s['form_name'] ?? '', $s['email_to'] ?? '(admin email)', $s['email_to_cc'] ?? '(none)', $s['email_to_bcc'] ?? '(none)' );
			}
			if ( ! empty( $el['elements'] ) ) { $walk( $el['elements'] ); }
		}
	};
	$walk( json_decode( $r->meta_value, true ) ?: array() );
}
if ( ! $rows ) { echo "  (no Elementor forms found)\n"; }

$mx = function_exists( 'dns_get_record' ) ? @dns_get_record( wp_parse_url( home_url(), PHP_URL_HOST ), DNS_MX ) : array();
if ( $mx ) { echo "\nThis host name's MX: ", implode( ', ', wp_list_pluck( $mx, 'target' ) ), "\n"; }