Site Builder

The Site Builder is the theme’s onboarding wizard. The form half runs anywhere the theme renders, GitHub Pages included. The Claude half connects through the local dev proxy and turns the wizard into an assisted build: Claude sees every answer, proposes and applies values, checks the machine, reads the theme’s source, writes the project, and runs Docker.

What you’ll do

Use this reference to understand how the wizard is structured, configure or extend a step, and see exactly what actions the Claude session is permitted to take.

Prerequisites

• The theme served locally (docker compose up) so /setup/ renders. In production the page shows a notice unless show_setup_wizard: true is set.
• For the AI layer: Node.js 20.6+, a Claude Code OAuth token in .env, and the dev proxy running.

Where it renders

The nine steps

Steps, prerequisites, catalogs and the framework brief all come from one data file, _data/site_builder.yml, so the form, the generators, and the AI prompt cannot drift apart.

Generated files

The preview panel shows every file live and regenerates on each keystroke. Any file can be overridden by hand or by Claude; overridden files carry a dot on their tab.

Download file saves the active file. Download bundle saves zer0-site-bundle.sh, a self-extracting bash script that recreates the whole tree in a folder you name.

The site plan (schema-driven output)

Beyond the form fields, the agent produces a site plan: a structured description of the landing page, the navigation shape, theme overrides and example pages. The plan is validated against plan_schema in _data/site_builder.yml (a JSON-Schema subset: type, properties, required, additionalProperties, enum, enumFrom a catalog, items, maxItems, maxLength, pattern) before anything changes, and the generators turn it into files. Every option the agent can pick comes from a catalog in the same data file, so adding a palette, a font pairing, a landing template or a section type is a data change.

Template defaults fill in whatever the plan leaves out, so a plan with only landing.template: showcase still yields a complete landing page whose copy is derived from the brief and collections. The Structure step exposes the same choices as controls (navigation style, sidebar, landing template, a page planner) and the Appearance step exposes palette cards, a font pairing with live preview, and corner radius; Preview on this page applies the generated overrides to the wizard itself. Claude submits plans with set_site_plan; the browser shows a confirmation card listing what changes and rejects anything the schema does not allow, returning the errors to the model.

Configuration

site_builder:
  enabled: true
  endpoint: '/api/wizard'      # dev proxy base; _config_dev.yml sets http://localhost:8787/api/wizard
  chat_endpoint: ''            # '' reuses ai_chat.endpoint
  model: 'claude-opus-4-8'     # default; the proxy's CHAT_MODEL overrides it server-side
  max_tokens: 4096
  default_port: 4000

The Claude session

Every turn sends a system prompt built from four parts: the framework brief from the data file, the field schema the wizard exposes, the current step’s guidance, and a summary of every answer, check result and generated file. Because the form is the single source of truth and the script only talks to it through window.Zer0SetupWizard, anything you type and anything Claude applies is visible to both immediately.

Tools available to the model:

The visible transcript is kept in sessionStorage as plain text turns only, so a restored conversation can never orphan a tool result.

Dev-proxy routes

The routes live only in templates/deploy/chat-proxy/dev-proxy.mjs and are bounded by wizard-store.mjs. The Cloudflare Worker never has them.

Environment: WIZARD_TARGET_ROOT and WIZARD_DISABLE_COMPOSE=1.

Validate a build end to end

Because the agent’s answers are not deterministic, the wizard ships a scenario runner rather than a fixed transcript. It samples a realistic brief, author, tone, skin, color mode and integrations for a site type, drives the whole wizard in a real browser with video recording on, accepts Claude’s confirmation cards, writes the project, starts it with Docker, and asserts structural facts about the result: the expected files exist, the site answers on every route for that type, and it carries the chosen title and skin.

# theme on :4000, dev proxy on :8787
node test/visual/site-builder-walkthrough.mjs                       # one random scenario
SCENARIO=cookbook SEED=42 node test/visual/site-builder-walkthrough.mjs
SCENARIO=all COUNT=6 SITE_PORT=4100 node test/visual/site-builder-walkthrough.mjs

Scenarios live in test/visual/site-builder-scenarios.mjs (blog, docs, cookbook, portfolio, garden, mixed). Each run prints its seed and writes report.md, report.json, screenshots and video-desktop.webm under test/visual-results/site-builder-walkthrough/<timestamp>/. When the assistant is unavailable the runner records those checks as failed, fills deterministic stand-ins, and still exercises the build. Generated sites use SITE_PORT + 10·i with LiveReload on the next port, so they run beside the theme’s own dev server.

Verify

1. Start the theme and the proxy, open /setup/, and confirm the badge reads connected.
2. Press Run checks on the Prerequisites step and confirm each row changes state.
3. Type a brief, press Draft with Claude, and confirm a card asks before fields change.
4. On Build, press Check, Write project, then docker compose up; the terminal streams the build and Open site loads the new site.

Troubleshooting

Related

• Site Builder quickstart is the walkthrough for first-time users.
• AI Chat Assistant documents the shared proxy and its auth modes.
• Machine Setup is the manual reference for the Prerequisites step.