Site Builder's Guide

The system in one paragraph

Every Suds site is the same engine wearing a different brand. The Suds Digital Website Builder plugin carries everything — a library whose current count is published in its generated manifest (62 sections today), 7 design archetypes (visual personalities) × 4 hero layouts, the page templates, and the safety rules. Each client gets only a tiny brand theme (their name + colors) that the system generates. You do not need to edit code: choose Claude Code or Codex as the builder, answer decisions in Mission Control, and polish visually in the Section Studio. Both agents consume the same intake, canonical plan, lock, engine, and claim-safety rules; the adapter changes, not the project truth. Data-dependent sections hide themselves instead of inventing facts, and QA remains the final check.

What you need before starting

One-time operator setup — connect Onboarder

1. Sign in to the Suds intake console and open Settings → API keys (API keys).
2. Under Create a new key, use an integration name such as Website Builder — Local, then select Create key.
3. Copy the new sd_live_… value immediately. The intake app shows the raw key only once and stores only its SHA-256 hash.
4. In the intended disposable or client WordPress build target, open Prepare Build, keep the API base URL at https://suds.onboarder.website/api/v1, paste the key, choose wp-content/.claude, and select Save credentials.
5. Select Load projects. The same active integration key can list and fetch available projects; a separate key is not required for every client. Revoke or rotate it from the intake app if it is exposed or no longer needed.

Choose the builder for this session

.claude is the historical name of the shared project-state directory; its name does not mean the project belongs to Claude. Start with one builder and do not initialize both agents at the same time.

The build, step by step

The command names below are the Claude interface. Codex follows the same stages and gates through $suds-build, using the roadmap, task files, protocol lock, and live WordPress state.

From local build to client launch

Building, client review, release publication, and licensing are separate gates. A merge or an approved Studio system revision does not publish a WordPress update. Licensing controls access to signed updates and support; it must never stop an already-installed public site from rendering.

Move the approved build to staging

1. Back up the local files and database, create the staging WordPress install, and set WP_ENVIRONMENT_TYPE=staging.
2. Migrate with the host's normal tool, perform a serialized-data-safe URL replacement, then flush permalinks and caches.
3. If the copied database was ever enrolled, run wp suds release scrub-clone --confirm on staging. This removes copied enrollment metadata without revoking the original site. Never use detach on a clone.
4. Run compatibility and QA again; also test forms/email, mobile and desktop layouts, accessibility, analytics/consent, and the client's critical paths. Share the staging URL and record approval.

Publish the Engine separately, when needed

A new Engine version follows the complete signed-release process: merge the source revision, approve that exact system revision in Studio, prepare and register canary bytes, verify them on a controlled canary site, promote those exact bytes to stable, then publish and close the release run. Never rebuild different bytes under an existing version. Documentation-only corrections such as this guide use the lighter source PR → Studio bundle and matching catalog capture → revision approval path. They do not create a WordPress release, require offline signing, or update the fleet.

Launch and enroll only the final production identity

1. Take fresh staging backups, migrate to the final host/domain, set the final HTTPS home/siteurl, and set WP_ENVIRONMENT_TYPE=production.
2. Verify DNS/TLS, redirects, permalinks, caches, forms/email, analytics/consent, indexing, accessibility, responsive layout, backups, and administrator access. Run wp suds qa --no-color on the final URL.
3. Create a short-lived, single-use enrollment code for this site, enroll it once from production, then verify wp suds release status --format=json and wp suds release check --format=json. Confirm the returned origin is the final production origin and the environment is production.

printf '%s' "$SUDS_ENROLLMENT_CODE" | wp suds release enroll --code=-
wp suds release status --format=json
wp suds release check --format=json

Keep the detailed checklist open during migration and launch: Build locally → client staging → production licensing.

Everyday edits after the build

• Change words/photos: edit the page in WordPress admin — every page shows a "Sections on this page" guide telling you exactly where each piece of content lives. Site-wide facts such as the public phone and service areas live in Theme Settings; branch address, map, hours, and last-wash time live on each Location post.
• Change the layout: Section Builder (?sbs_compose=…) — never edit code.
• Add a service or location: add the post in admin; it appears everywhere automatically (grids, footer, related, schema).
• A section looks wrong: flag it on the Review Board with a note — that's the fix pipeline.
• Something the library can't do: new sections are added to the engine's library (the AI-driven Section Designer pipeline), never hacked into one client's theme. Ask for it; every client benefits.

When something breaks

Where the deeper manuals live