Small business website spec

This one is long. Copy it, then paste it into your AI.

# Small Business Website Spec

> ⚠️ **This is a planning/specification reference, not a deployable skill for
> no-code platforms.** Base44 and similar builders have no CLI the agent can
> call — building there means dragging pages in a web editor, done by a human.
> A static framework (Astro/Hugo/Eleventy) on Vercel/Netlify/Cloudflare Pages
> *is* agent-workable: the agent can clone the repo, edit, run checks, and push.
> Either way, this skill is the spec: page structure, copy voice, estimator
> widget, SEO checklist, form handling, and the DNS cutover runbook.

## When to Use
- Planning a website rebuild for a small service business
- Choosing between no-code (Base44, Wix Studio, Squarespace) and a static framework (Astro on Vercel)
- Page structure, copy voice, estimator widget, SEO requirements
- DNS migration notes (registrar → new host)
- Wiring contact-form submissions into the agent (email → IMAP polling → CRM → Telegram)
- NOT for automated no-code deployment — no agent-accessible CLI exists there

## Platform Decision: No-Code vs Static Framework

Both paths are valid. Pick by workload, not by hype:

| Factor | No-code (Base44 etc.) | Static framework (Astro/Vercel etc.) |
|---|---|---|
| Who builds it | Human, in a web editor (drag-and-drop) | Human or AI coding agent, in a repo |
| Time to first draft | Hours | Days |
| Monthly cost | ~$50/mo for domain connection + GitHub sync on Builder-tier plans | $0 on Vercel/Netlify free tiers (or an existing plan) |
| SEO | Prerendering exists but is often a black box you can't control | Static HTML — fully crawlable, you own everything |
| Export/exit | Frontend only; backend (auth, DB, entities) stays on the platform SDK — you can't self-host by exporting | It's your repo. Portable by definition. |
| Site types that fit | Interactive apps, member areas, anything needing a real backend | Marketing sites: pages + one estimator widget + one contact form |
| Mutability | A living app on their platform — platform updates can change rendering without you touching anything | An immutable build artifact on CDN edge — it can't break while untouched |
| Agent's role | Paying for the subscription (via stripe-link-cli) and writing the spec — not the build | Full repo work: edit, test, verify, push, deploy |

**How to choose:** if the site needs user accounts, database writes, or complex
app behavior, no-code (or a real framework with a backend) earns its subscription.
If it's a marketing site — pages, photos, an estimator widget, a contact form —
a static build is cheaper, faster to load, better for SEO, and fully agent-workable.

We started on Base44 (for a hackathon "the agent bought the subscription" beat,
which is what `stripe-link-cli` is for), then pivoted to Astro-on-Vercel for the
production site because a static marketing site had zero backend needs. The
pivot itself was cheap **because the spec (this document) was written before
either build** — page inventory, copy voice, estimator logic, and SEO checklist
all carried over unchanged.

## Prerequisites
- Domain at a registrar (GoDaddy or similar) — keep DNS there, repoint records
- Static path: git repo, framework (Astro recommended), hosting account (Vercel/Netlify)
- No-code path: builder account, manual signup + build in the web interface
- Form delivery: an email API (Resend/Postmark/SES) or SMTP — forms should email the owner's inbox
- Payment for no-code subscriptions via the `stripe-link-cli` skill (agent handles the spend, human handles the build)

## Website Architecture

### Pages needed (marketing site for a service business)
1. **Home** — hero image, value proposition, primary CTA ("Get Free Estimate"), estimator above the fold
2. **Service pages** — one per service line (built from a template route; each names the reader's exact situation in the first two sentences)
3. **Service area / location pages** — one per market city (template route, real local copy, not doorway spam)
4. **Realtors & property managers** — the B2B repeat-revenue page, if referrals drive the business
5. **About / Why Us** — owner story, process steps, trust signals, real photos
6. **Gallery** — real job photos, captioned
7. **FAQ** — include a "what makes you different from everyone else?" answer
8. **Contact** — form with estimator pre-fill flow
9. **Reviews** — embedded review widget (or hold back until the widget is wired)
10. **Thank you** — `noindex`, conversion event fires here
11. **Terms** — warranty/terms as a proper page (not a PDF scan)
12. **404**, plus `robots.txt`, `llms.txt` (for AI/agentic search), `sitemap-index.xml`

### Estimator tool integration
The estimator is the conversion hook AND the differentiator. Pricing logic
lives in ONE place (see `estimator-engine` skill; a `rate-card.json` both the
website widget and the agent read is the cleanest split).
- Input: square footage, region tier, property type (residential/commercial/apartment), add-ons
- Output: a **±15% range, never a single number**, never internal line-item math
- Flow: result → one tap → contact form pre-filled with all inputs + quoted range
- Mobile-first: thumb-reachable controls, ≤60 seconds, ≤8 taps
- **The website widget, the agent's chat estimator, and the rate-card file
  must all read from the same rate card.** If a price changes, change the rate
  card first; both consumers pick it up. Canonical source: `estimator-engine`.

### Contact form handler
- Serverless function (or the host's form feature) receives the POST
- Email API (Resend etc.) delivers to the **owner's inbox** — reply-to set to
  the submitter so the owner can hit Reply
- Honeypot spam field (hidden "company" input — if filled, reject silently)
- Validate: required core fields, plus "at least one of phone or email"
- Carrying estimator data into the form? Keep it as structured fields in the
  submission email — the agent's inbox monitor parses them (see below)
- Optional webhook to the agent — but see "Lead intake" before exposing one

### Lead intake (agent integration)
Two ways to get form submissions to the agent:

**A. IMAP polling (recommended default).** The form emails the owner's inbox
with a stable subject prefix (`New website lead: ...`) and a structured
plain-text body. A `no_agent=True` cron script polls the inbox every 3 min,
parses the fields, logs to CRM, and texts the owner's Telegram. Latency ~3 min
— irrelevant for a few leads a week. No public endpoint, nothing to attack.
Full pattern: `grasshopper-voicemail-monitor` skill and its notification-email
reference.

**B. Webhook (faster, more surface).** The form handler POSTs straight to an
agent endpoint. You get instant delivery but you must expose, secure, rate-
limit, and monitor a public URL on the agent box. Only worth it at volume.

Choose A unless leads/minute is a real metric for you. The webhook code can
stay in the form handler, dormant, if you want the option open.

## Content guide

### Copy voice
- **Premium-because-[your real differentiator]** — never "affordable,"
  "budget-friendly," "cheap" (they attract price-shoppers, not your buyers)
- Lead with the outcome (it works, it's guaranteed, it's permanent) — not the chemistry
- Name the reader's exact situation in the first 2 sentences of every service page
- Specificity = trust: real cities, real timeframes, real guarantee terms
- ~7th-grade reading level, short sentences

### Banned-word check
Add a verify-script check for cheap-sounding words: *affordable,
budget-friendly, cheap, competitive pricing, "we work with many budgets,"
best-in-class, world-class, "look no further."* Ban list lives in the repo and
runs in CI — banned words slip back in with every copy edit otherwise.

### Guarantee
If you advertise a guarantee, state its exceptions wherever the guarantee
appears — exceptions buried on a distant page erode trust and invite disputes.

## Common Pitfalls

- **Contact-form cutover risk:** the OLD site's form probably works and goes
  to the owner's inbox. Do NOT repoint DNS until the new form is **verified
  delivering to that same inbox** on a staging domain. Breaking a working
  lead path is worse than keeping the old site live another week.
- **DNS propagation:** 24-48h. Save old DNS values for instant rollback.
- **Email routing:** changing A/CNAME records is fine, but **MX records stay
  pointed at the email host** (e.g. Workspace: `imap.secureserver.net` /
  `smtpout.secureserver.net`). Repointing MX silently breaks the business's email.
- **Mobile-first:** most service-business leads come from phones. Test at
  320px, 375px, 414px widths.
- **301 redirects:** map old (especially WordPress) URLs → new pages before
  cutover, or years of accumulated SEO equity 404s overnight.
- **Banned words:** enforce via the verify script, not vigilance.
- **Terms & conditions:** a scanned-image PDF has no extractable text —
  transcribe it into a real page.
- **Stock photos:** verify licensing before a live launch; "we scraped them
  from our old site" is not a license.
- **Browserless agent box:** no-code checkout and Lighthouse audits need a
  browser. The agent can't drive a web UI without Chromium
  (`npx playwright install --with-deps chromium`); run audits via web tools.
- **Region classification sync:** if you update region tiers in
  `estimator-engine`, update the estimator widget options AND the rate-card
  file. All three must match. Canonical source: `estimator-engine`.
- **No-code export is a one-way door:** the frontend exports; the backend
  doesn't. If you start on no-code, treat it as a prototype — don't wire
  business logic (auth, DB, entities) into it that you'll have to rebuild.
- **Agent pushes to `main`:** for a 1-2 person shop, direct-push with a
  quality gate (tests + verify script) is faster than PR review. Whatever
  you choose, make it a written convention — agents follow conventions,
  they don't infer them.
- **GitHub PATs expire:** if the clone URL embeds a PAT, pushes fail
  mysteriously ~30 days later. Check the token's expiry when setting up,
  and note the `git remote set-url` fix before it bites.

## DNS Configuration (registrar → Vercel example)

```
Type: CNAME
Name: www
Value: cname.vercel-dns.com

Type: A
Name: @
Value: 76.76.21.21 (Vercel default)
```
(No-code hosts give you their own CNAME/A targets — same idea.)

**Do NOT touch MX records** — email stays with the email host.

Cutover order:
1. New contact form verified delivering to the owner's inbox (staging domain)
2. Owner sign-off on content + design
3. THEN repoint DNS
4. Old DNS values saved for instant rollback

## Verification Checklist

### Quality gate (automated — run before every push)
- [ ] Every page renders static HTML with copy in the raw HTML (no client-only content)
- [ ] Unique title (≤60 chars) + meta description (≤155 chars) per indexable page
- [ ] Exactly one H1 + substantial body copy per page
- [ ] Zero banned words (enforced by script)
- [ ] Estimator output matches the agent's chat estimator (same rate card, test N quotes)
- [ ] Guarantee caveats reachable from every page mentioning "guarantee"
- [ ] Structured data (LocalBusiness, Service, FAQPage) + tap-to-call on every page
- [ ] robots.txt, llms.txt, sitemap-index.xml present; /thank-you is noindex
- [ ] Unit tests pass (pricing engine + form validation)

### Pre-cutover (manual)
- [ ] Owner sign-off on the site
- [ ] Form submissions verified delivering to the owner's inbox on the real domain
- [ ] Schema.org validates (Google Rich Results Test)
- [ ] Lighthouse mobile: Performance ≥90, SEO ≥95, Accessibility ≥90
- [ ] Real photos on the site (machines/equipment/jobs, not stock)

### Post-cutover
- [ ] DNS propagated (`dig yourdomain.com`) + HTTPS working
- [ ] 301 redirects from old URLs live
- [ ] Email MX records preserved (don't break email)
- [ ] Search Console + Bing Webmaster verified; sitemap submitted
- [ ] Analytics events firing (estimator_start, estimator_complete, form_submit, call_click)
- [ ] Mobile responsive verified on real devices
- [ ] Lead-intake monitor (if used) picking up form submissions → CRM → Telegram

Fill in anything in [brackets] or {braces} with your own details first.