15 Site Generation

---
name: "site-generation"
description: "End-to-end AI website generation pipeline. Claude Opus 4.8 emits Bolt-style <boltArtifact> envelopes (multi-file, plan-first) that customize Vite+React+Tailwind templates from pre-researched business data. Pre-research via APIs, media acquisition, brand extraction, visual inspection via GPT Image 2 vision, R2 upload (per-file content-type by extension), D1 status updates. Supports all business types: SaaS, portfolio, non-profit, restaurant, salon, medical, legal, retail, tech."
metadata:
  version: "2.0.0"
  updated: "2026-04-30"
  effort: "xhigh"
  model: "claude-opus-4-8"
  context: "fork"
license: "Rutgers"
compatibility:
  claude-code: ">=2.0.0"
  agentskills: ">=1.0.0"
submodules:
  - bolt-artifact-protocol.md
  - build-breaking-rules.md
  - build-prompts.md
  - domain-features.md
  - homepage-block-library.md
  - local-seo.md
  - media-acquisition.md
  - non-technical-owner-onboarding.md
  - page-set-expansion.md
  - quality-gates.md
  - research-pipeline.md
  - small-business-mode.md
  - source-fidelity-loop.md
  - template-improvements-100.md
  - template-system.md
priority: 3
pack: "website-build"
stage: stable
triggers:
  - "site generation"
  - "bolt artifact"
  - "boltArtifact"
paths:
  - "org:website_build"
---

# 15 — Site Generation

Run the end-to-end AI website generation pipeline: research→media→Bolt artifact emission→R2 upload→D1 status for all business types.

> **Model migration note (pass-78, 2026-06-09)**: `DALL-E` → **GPT Image 2** (2026-04; 2.5 branded 2026-09 — check current API id at integration) + `GPT-4o` → **GPT Image 2 vision**. Per `platform.openai.com/docs/deprecations`. Generation pipeline unchanged.

## Submodules

- **research-pipeline** — API-driven business research, scraping, enrichment
- **media-acquisition** — image/video/logo sourcing across 17 engines (Flux 1.1 Pro Ultra, Ideogram 4.0, Recraft V3, GPT Image 2, Veo 3.1) — Pexels-first / AI-fallback, pHash dedup
- **build-prompts** — master prompt + enhancement phases
- **quality-gates** — Lighthouse CI v0.15+, axe-core / playwright v4.11+ WCAG 2.2 AA, source-parity diff, 3-tier visual regression, console-error gate, Recommendations Loop
- **domain-features** — category-specific for 18+ business types
- **template-system** — Vite + React + Tailwind + shadcn/ui starter
- **local-seo** — citation building, GBP sync, review generation, trust badges, local conversion tracking
- **bolt-artifact-protocol** — `<boltArtifact>` XML envelope spec — ordered file/shell actions, PLAN.md-first, runtime parser + executor, ~$6/site at 80K output tokens
- **blog-import.mjs** — RSS-first crawl + Squarespace JSON fallback → strip CMS residue → GPT Image 2 vision-mini typed-block restructure → pHash dedup → `src/data/blog-posts.ts`
- **validate-assets.mjs** — post-build R2/dist gate — 13 mandatory files + every img/link/script/source ref resolves OR matches allowlist

## Dual-Template Architecture (TWO REPOS — NEVER CONFUSE)

- **Local Business**: `megabytespace/template.projectsites.dev` — Vite + React + Tailwind + shadcn/ui, 15 local components, CSS var brand slots. Use for: restaurant, salon, medical, legal, fitness, contractor, retail, etc.
- **SaaS**: `megabytespace/saas-starter` — Hono + D1 + Clerk + Stripe + Inngest + Resend on CF Workers. Use for: SaaS products, APIs, dev tools, platforms.

### Template selection (from `_form_data.json.category`)

- `restaurant|cafe|salon|spa|medical|dental|legal|fitness|automotive|construction|photography|real_estate|education|financial|retail|pet_services|wedding|church|nonprofit|government` → `template.projectsites.dev`
- `saas|api|platform|devtool|marketplace` → `saas-starter`
- Unknown → local business

### Auto-sync

After ANY change to skills 05-15, evaluate: "Does this improve template?" If yes → push to appropriate template repo same prompt.

## Generation Protocol

Model emits ONE `<boltArtifact>` XML envelope with ordered `<boltAction type="file" filePath="…">` and `<boltAction type="shell">` actions. See `bolt-artifact-protocol.md`.

- First action ALWAYS `PLAN.md` (route tree, design-token diff, media count, file count, validators)
- Runtime parser validates first-action-is-PLAN.md + required-files + `npm…build` shell action; failures re-prompt (max 2 retries)
- Executor modes: `container` (default — `git clone template → npm install → vite build → upload dist/`) | `r2-files` (pre-built static)

## Pipeline

```
Phase 0: Pre-Research + Media Acquisition (ALL BUILD MODES)
  → Google Places, scraping, social verification, brand extraction, media discovery
  → Download ALL images from original; stock via Pexels/Pixabay; AI via GPT Image 2 / Stability AI
  → YouTube/Pexels video embeds
  → Output: _research.json, _scraped_content.json, _assets/
  → HARD GATE: <10 images = build NOT complete

Phase 1: Claude Opus 4.8 Bolt-Artifact Emission (Worker OR Container)
  → Reads all _ context files; emits ONE <boltArtifact> envelope
  → First action ALWAYS PLAN.md
  → Customizes pre-installed Vite+React+Tailwind+shadcn/ui template
  → Builds 1:N-page site MATCHING source sitemap (every URL recreated, max 1000)
  → Clean URL slugs (never copy CMS garbage like -1 suffixes)

Phase 2: Post-Build Verification (Worker)
  → Screenshot via microlink.io → GPT Image 2 vision scoring
  → D1 status update → email notification
```

CRITICAL — In manual/prompt-based builds (no container), Phase 0 runs INLINE as first step. Agent MUST: (1) WebFetch original site pages + extract all image URLs; (2) download images to `public/`; (3) search + download stock photos; (4) generate AI images if API keys available. ALL BEFORE writing any React code. Text-only site = failed build.

## Context Files (written before model runs)

- `_research.json` — business profile + hours + phone + address + reviews + geo
- `_brand.json` — colors + fonts + personality + logo URL + color_source
- `_citations.json` — APA 7th bibliography keyed by refId per `citations.md`
- `_scraped_content.json` — all pages by URL
- `_assets.json` — image manifest w/ metadata
- `_image_profiles.json` — GPT Image 2 vision analysis per image: quality + placement + colors
- `_videos.json` — YouTube/Pexels embed URLs + metadata
- `_places.json` — Google Places enrichment: photos + reviews + rating
- `_form_data.json` — user-submitted from `/create`
- `_domain_features.json` — category-specific feature requirements

## Build Rules (NON-NEGOTIABLE)

### Images

- USE ALL images in `assets/`. Never external URLs (hotlinking blocked).
- Hero: `assets/hero-*`. Gallery: full-width slider w/ ALL images. No image left unused.
- Minimum count: `max(30, original_image_count × 1.4, page_count × 6_home_or_4_sub)` — 4-page rebuild ⇒ 30-50 images; 50-page ⇒ 200+; 500-page ⇒ 2000+
- Per-page floor: home ≥6, every sub-page ≥4. Minimum 5 AI-generated GPT Image 2 originals per site.
- All images through optimization pipeline (skill 12): WebP + AVIF at 320/640/1280/1920w, blur placeholders, dominant color extraction. Use `<ResponsiveImage>`, never raw `<img>` w/ PNG/JPG src.
- Dedupe via 301 not deletion — md5-hashed twins keep canonical, emit `{deleted-url:canonical}` to Worker redirect map.

### Video

- Walker captures `<video>` + `<source>` + `<iframe src*=youtube|vimeo|wistia|loom>` + `data-video-id` + CSS `background-video` + autoplay-loop hero MP4s + animated WebPs + lottie `.json`
- Output `_videos.json` keyed by source URL w/ `{src, poster, duration, dims, transcript?, captions_vtt?, original_route, slot_hint}`
- Template's `<VideoEmbed>` lazy-loads, poster-first, captions if VTT exists, respects `prefers-reduced-motion`
- Augment via Pexels Video API (free) + YouTube Data API search-by-topic for missing background loops
- Video count gate: every original `<video>` and embed accounted for in `_videos.json`; missing = fail

### GPT Image 2 Purpose-Craft (per-slot prompts — never generic)

Every AI-generated image brief MUST include: (1) route + section (`/about hero`); (2) page topic + intent; (3) brand palette tokens by hex from `_brand.json`; (4) composition + aspect ratio; (5) subject specificity (named noun + modifiers + lighting + lens metaphor); (6) negative prompt (no text, no watermarks, no AI artifacts, no extra fingers, no logos).

Build `_image_briefs.json` per site BEFORE generation — one brief per slot, reused across fallback chain (GPT Image 2 → Ideogram → Recraft). Generic "create a hero image" = fail; discarded + brief regenerated.

### Per-Route SEO

SPAs swap meta on `useLocation()` change via `<PageHead />` reading `src/data/page-meta.ts`. Each entry: title 50-60ch keyphrase-first | desc 120-156ch | canonical + og:*+ twitter:* + JSON-LD (Org/Service/BlogPosting/BreadcrumbList/FAQPage). Hard gate: every `<Route path>` has `page-meta.ts` entry or data-derived meta.

### Font-Flash Mitigation

`index.html` `<head>`: `<link rel="preload" as="style">` + animate.css + `html:not(.fonts-loaded) body { opacity: 0 }` + inline `document.fonts.ready.then(reveal)` + `setTimeout(reveal, 1200)` safety net.

### Hero Context Match

Every hero image/video literally depicts page topic — `/mass-schedule` gets stained-glass-window, `/donate` gets volunteers-serving. AI-vision QA scores `image_matches_page_topic` 0-10 per hero; <8 = replace.

### Empty-Config Widgets

Gate every third-party widget on env var: `{import.meta.env.VITE_TURNSTILE_SITEKEY ? <div className="cf-turnstile" data-sitekey={...} /> : null}`. Same for Stripe pk, PostHog snippet, Resend embed. Empty `data-sitekey=""` = console error on every render.

### Post-Deploy Parallel Scan (BOTH scripts required — deploy not verified without both)

- `scripts/scan-assets.mjs` — Playwright concurrency 6, captures console errors/warnings + `requestfailed` + `response.status>=400` per route
- `scripts/check-routes.sh` — curl every route + every blog slug for non-200

### Design

- Dark-first, brand-extracted base color (skill 10 — MANDATORY) | 10+ `@keyframes` animations
- Glassmorphism cards (`bg-white/5 backdrop-blur-md border-white/10`) | gradient text on key headings
- Parallax-style depth on hero | 25+ inline SVG decorative elements
- Every interactive element has hover + active + focus states
- Smooth scroll for ALL same-page nav (`scrollIntoView`, never `#href` jumps)

### Content

- Word count MATCH OR EXCEED original — never ship less content; 5000+ words minimum
- Migrate ALL blog posts, news, events, team bios from scraped content
- About page 2000+ words | every claim factually accurate from research
- Blog → individual routes per post with RSS feed
- Addresses → Google Maps links | phone → `tel:` links | email → `mailto:` links

## See submodules for: research-pipeline, media-acquisition, build-prompts, quality-gates, domain-features, template-system, local-seo, bolt-artifact-protocol, page-set-expansion, source-fidelity-loop, build-breaking-rules.