Suds Site Build Operator Manual

Suds Site Build System

Suds Site Build Operator Manual

This is the detailed operator guide for running a new laundromat website job. Prepare Build installs supported Claude Code and Codex adapters over the same project protocol; this manual shows the Claude /suds:* interface in depth and identifies the equivalent Codex route.

Essentials

Primary command/suds

Input fileSD-*-client.json

Theme importerwp suds import-intake

Operator dashboardMission Control

Saved answersoperator-decisions.json

Website outputBCB child theme

Build rulesBCB-CONSTRUCTION-CONTRACT.md

Start Here

The system turns one onboarder JSON export into a planned, branded, built Suds laundromat website. Choose Claude Code or Codex for the session, open Mission Control, then repeat build and polish passes until the launch checklist is clean.

You prepare

A working Local WP site with the Suds Digital Website Builder engine plugin active. Run Prepare Build (or wp suds prepare-build <uuid>) to install both .claude/ and .codex/skills/suds-build and fetch the shared client intake.

Your chosen agent prepares

Client docs, page map, build plan, site standards, specs, tasks, plus the live Mission Control dashboard.

Your chosen agent builds

The client child theme, pages, sections, copy, media wiring, SEO/schema, and QA fixes.

Use Mission Control as your dashboard: after setup, run /suds:mission-control to see brand direction, page strategy, copy, assets, blockers, roadmap status, and the next recommended action.

Choose one builder: in Claude Code, open the site's wp-content workspace and run /suds:init. In Codex, open the same workspace, invoke $suds-build, and ask it to initialize and build from the newest prepared intake. The .claude name is legacy shared-state naming; both agents use it. Do not initialize both agents concurrently.

What You Need

Do this before running any /suds command.

Required

Local WP site starts successfully.

Frontend and /wp-admin both load.

The engine's Prepare Build screen (or wp suds prepare-build <uuid>) has installed .claude/, .codex/skills/suds-build, and the intake; manual fallback uses wp suds install-framework --location=wp_content.

BCB parent theme, canonical thin starter, and Suds Engine plugin are present.

The Engine plugin includes BCB-CONSTRUCTION-CONTRACT.md and AGENTS.md.

Blueprint plugins are already installed and active.

The workspace contains .claude/, themes/, and plugins/, or can access them directly.

Do Not Build These

The system assumes these are handled outside the creative build workflow:

Set Up The Job

Each client job starts with exactly one fresh intake file in .claude/intake/.

Open the correct workspace in your chosen agent

Start Claude Code or Codex in the Local site workspace. When Prepare Build uses its normal location, open wp-content: it contains the shared .claude/ project state and the installed .codex/ skill.

Clear old intakes

Move old SD-*-client.json files out of .claude/intake/. Leaving multiple client exports in the folder can cause the wrong job to initialize.

Add the new intake

Copy the client export into .claude/intake/. Accepted names are SD-<id>-client.json and sd-<id>-client.json.

cp ~/Downloads/SD-####-client.json .claude/intake/

Run init soon after export

Onboarder image links can expire. /suds:init downloads the signed-url images into .claude/intake/assets/SD-<id>/ so the build does not lose client media mid-project.

/suds:init

Switch Agents Safely

An in-progress project can move between Claude and Codex without changing its canonical facts or restarting the workflow.

wp suds handoff-agent --to=codex

wp suds handoff-agent --to=claude

Run the appropriate command from the Local shell at the WordPress root, then continue the active roadmap/task in the target agent. The gate verifies both locks and preserves the immutable intake and canonical build plan. A factual mismatch stops. If it reports REVIEW_DIFFERENCES, inspect the comparison before rerunning with --accept-review-differences. Never rerun init solely to switch agents.

Run An Autonomous Build

For a full Claude build, give Claude Code one high-level objective and let it run the pipeline end-to-end. Codex uses the equivalent $suds-build objective over the same stages. Keep the /suds:* commands as the step-by-step Claude workflow inside that objective.

Use it when

You want Claude Code to keep moving through setup, Mission Control review, specs, execution, polish, and launch checks.

The definition of done is clear: no launch-blocking gates, no unresolved required decisions, and tasks complete.

You can pause or steer the thread when client facts, credentials, or approvals are needed.

Do not use it for

Do not let the autonomous prompt replace the workflow. It should run the /suds:* commands, open Mission Control, and use operator-decisions.json as the human answer source.

Build this Suds client site from the pinned intake in .claude/intake using the shared Engine plugin and a generated thin brand theme. Follow CLAUDE.md and the /suds: commands. Run init, Mission Control review, bootstrap, wp suds import-intake, /suds:copy, next/execute cycles, and launch-readiness improvements. Continue until Mission Control shows no launch-blocking gates, required operator decisions are answered or marked needs_client, generated tasks are complete, and the site passes responsive, copy, media, SEO/schema, placeholder, compatibility, and claim-safety QA. Stop only for missing client facts, credentials, or approvals outside the blueprint boundary.

Best pattern: the autonomous prompt keeps the long-running objective alive; /suds:mission-control remains the operator dashboard and decision entry point.

Run The Build

Use this sequence for a normal client site. Repeat /suds:next, /suds:execute, and /suds:mission-control until the roadmap and launch gates are complete.

1InitIngest intake and assets.

2ReviewOpen Mission Control.

3BootstrapGenerate the thin brand theme (engine plugin).

4ImportIntake → pages, settings & posts.

5CopyTailor section copy.

6PlanCreate next spec.

7ExecuteBuild one task.

8ImprovePolish and QA.

Initialize the project

Creates the project docs, localizes assets, researches the existing website when a URL is provided, and compiles the page map and build plan.

/suds:init

Pre-flight the intake. Before bootstrapping, run wp suds eval-intake to see exactly how this client maps: the selected design archetype (with scores and the runner-up you can override), the derived signals, the resolved section stack for every page, and a gap / claim-safety punch-list (missing logo / photos / map / hours, pickup offered without a booking URL, plus the reviews and pricing that always need an operator pass). It's a pure read — it never touches the site — so it's the deterministic "catch intake problems before building" check that pairs with the Mission Control review. Think of it as the structural twin of the /suds:init report: /suds:init already covers this for a single client (and catches qualitative issues a deterministic check can't — e.g. when the logo / signage / map all read a different brand than the intake's business name), so running eval-intake here is optional confirmation; its real edge is batch-vetting many intakes (--all --dir=<path>) and as the agent's deterministic check. It's a wp suds command, so it's available once the Suds Digital Website Builder engine plugin is active. Substitute your real intake id for ####.

wp suds eval-intake .claude/intake/SD-####-client.json

Open Mission Control

Open the live dashboard to catch intake problems before building — missing phone, wrong address, weak images, unclear services, or decisions needed — and to track the build as it runs. Leave it open; it refreshes itself.

/suds:mission-control

Bootstrap the child theme

Generates the client's thin brand theme from the canonical Engine tool, activates it before the Engine, derives brand colors and typography, and writes the per-client manifest and theme standards. The theme is a small wrapper; reusable sections, templates, CSS, schema, composition, and wp suds stay in the shared Engine plugin. You pick a design archetype (1 of 7 skins — Express/Warm/Value/Commercial/Premium/Eco/Basecamp; confirm or override) and one of 4 hero layouts. Those choices set shape, type, density, motion, section order, and hero defaults as tokens, so the same Engine components re-skin per client. Bootstrap also seeds brand colors into Theme Settings from the site logo (wp suds apply-palette) so they remain concrete and editable.

/suds:bootstrap

Import the intake into WordPress

Run the Suds Build System 2.0 importer to turn the one intake file into a navigable, populated site. It scaffolds the site shell — the standard pages (Home/About/Pricing/FAQ/Contact) with their templates, the static front page, and the primary nav menu (Services and Locations link to their archives) — then fills empty global Theme Settings (Main business contact, archetype, CTAs, service-area towns, social), the home page content, and the Service and Location posts, flagging a Primary location only when one does not already exist. Intake is the starter seed, not the long-term source of truth: existing WordPress edits win on normal re-runs; pass --refresh-intake only when you intentionally want intake to reassert values. Pricing can be client-confirmed or seeded as market defaults marked for review when the intake says pricing should display. On Local, prefix WP-CLI with the site's MySQL socket (see the project manifest). Need just the shell? Run wp suds scaffold or wp suds import-intake <file> --posts-only.

wp suds import-intake .claude/intake/SD-####-client.json

Images are a separate step. wp suds import-assets <file> sideloads the intake assets[] (a local path, an --assets dir, or a remote download_url) into the media library and assigns each to its slot — logo→site logo, storefront→hero, interior→why, vehicle→service-area, service→service featured image. Real photos always beat placeholders, and it's idempotent.

Logo-only or sparse-photo client? Keep the raw intake immutable. Copy it to .claude/product/derived-intake.json, then run the /suds-placeholder-kit skill on that derived working file before import-assets. It derives a palette from the logo and generates claim-safe, clearly-temporary brand placeholders (watermarked, flagged is_placeholder) sized to every empty slot, and appends them to the derived file's assets[] — so the first-pass draft looks finished for client review without fabricating photos of the business. Swap in real photos as the client sends them and re-run import-assets (real always wins). Requires pip install Pillow numpy.

/suds-placeholder-kit → .claude/product/derived-intake.json (logo-only/sparse; optional)

wp suds import-assets .claude/intake/SD-####-client.json

Tailor the copy

Act as the expert copywriter: /suds:copy reads the intake and writes claim-safe, on-brand, client-tailored copy into the site's empty copy fields — turning generic defaults like "Ways to get it clean" into copy that reads like the actual client. It's set-once (anything an operator already edited, and any prior value, is kept), safe to re-run, and only writes copy grounded in stated facts and for services the client actually offers. Use --force to regenerate.

/suds:copy

Review brand & decisions in Mission Control

After bootstrap, the Brand and Assets views fill in. Answer any open decisions in Mission Control before building pages — saved answers become approved constraints.

/suds:mission-control

Create the next spec

Generates the next build spec and task list from the roadmap, build plan, and page map.

/suds:next

Execute one task

Run the task ID Claude Code created. Build tasks should stay scoped: one page, one section, one system area, or one clear QA target at a time.

/suds:execute SC-1003

Polish or fix a specific issue

Use /suds:improve for targeted work after pages render or after review finds a clear problem.

/suds:improve launch-readiness "resolve open launch gates"

Mission Control (Live Dashboard)

Mission Control is a live operator dashboard over the whole build. Mission Control is the always-on ops view: current phase, progress, tasks, blockers, decisions, and docs — refreshed automatically as the agent works.

/suds:mission-control

That refreshes the rollup and opens http://localhost:8976/ (or run python3 .claude/tools/mission_control_server.py --port 8976 directly). It is loopback-only.

What it shows

Current phase, overall % complete, and Init/Bootstrap/Spec stage status.

Tasks by status, the roadmap, the page plan, and blockers (needs-client decisions + open launch gates).

A docs reader for overview, page map, roadmap, standards, and the changelog.

What you can do

Answer Decisions Needed inline (saved to .claude/product/operator-decisions.json). Use the copy buttons to hand the recommended next command, a task's /suds:execute, a decision-as-constraint, or a full status briefing to Claude Code Desktop. It always reflects the real files, so it can't fall behind.

Where Content Lives

With the shared Engine and generated thin brand theme, every piece of content has one home, so nothing is duplicated. The importer fills the facts and /suds:copy fills tailored copy; this is where an operator edits or tops up anything by hand in wp-admin. Every field follows the same rule: what you type wins; leave it blank and the Engine either uses a claim-safe default or self-gates the section.

To edit…	Go to…
Archetype, hero layout, brand colors, fonts, band texture	Theme Settings → Design — colors are seeded from the logo; anything you type here wins, and clearing a color restores the logo-derived value. Band texture lets you keep the skin's pattern on the dark brand band, switch it to another pattern, adjust its strength, or turn it off.
Phone, email, hours summary, social links, service-area towns	Theme Settings → Main business — the brand-level contact (one per business).
Primary CTA + scheduling link, announcement bar, closing CTA copy	Theme Settings → Calls to Action
Footer tagline	Theme Settings → Footer
Home hero + every home-section copy block (services, how-it-works, why-us, service area, reviews)	Pages → Home → the per-section "Section: …" field groups — page-scoped, not in Theme Settings. Each page editor also shows a "Sections on this page" panel naming every section it renders and where that section's content lives.
Street address, hours, map, amenities, photo gallery for a shop	Locations (one post per shop). Flag one as the Primary location — its address, hours, and directions drive the top bar, footer, and local-business schema. With 2+ published Locations, "Our locations" sections appear automatically on the Contact and location pages, and each location page carries its own local-business schema.
Interior photos (home "why us" photo + About-page gallery)	Pages → Home → the "Why us" section's Interior gallery — one shared set: it powers the home panel's photo/slider AND, with 3+ photos, a photo gallery section on the About page.
Services and FAQs	Services and FAQs (one post each) — they feed the home grids, archives, and schema.
Reusable section copy — the heading/wording of the shared blocks (pricing, promise, commercial, pickup, wash & fold, amenities, hours, FAQ, map, values, locations, gallery)	Theme Settings → Copy — overrides for every shared section head; `/suds:copy` fills these, blank = claim-safe default.

The pages assemble themselves. Each page is built from a section library, and the chosen archetype picks which variant of each section to use — so two clients on different archetypes get visibly different, complete pages from the same parts. Sections that have no data (e.g. a pickup block on a self-service shop) simply hide, and richer data unlocks more: 2+ Locations add "Our locations" sections, 3+ interior photos add an About-page gallery. You don't place sections by hand; you fill the fields and pick the archetype. To see exactly what each page renders right now — and where every section's content is edited — open Appearance → Design System → Pages.

Location galleries: each Location has a photo Gallery with a 2–6 column control; the front-end opens them in a lightbox automatically. Add or reorder photos right on the Location post.

Polish Pages

Once pages render locally, use visual review and BCB Edit Capture to create focused prompts. Keep each polish pass narrow.

Open the local page

Review desktop and mobile sizes while logged into WordPress.

Capture the issue

Use BCB Edit Capture from the admin bar. Select the section, describe the problem, and copy the generated SDD prompt.

Paste the prompt into Claude Code

Most visual polish should use /suds:improve.

/suds:improve responsive "fix mobile spacing on the services grid"

Refresh and verify

Reload the page, check the exact issue, and repeat with the next narrow issue or patch list.

Launch Check

Before handoff or launch, verify the site behaves like a finished laundromat website, not just a generated draft.

Run the readiness gate first

/suds:qa answers "is this ready to share with the client?" It runs the deterministic wp suds qa checker (structure, content, design, rendering, claim-safety), interprets each finding, applies the safe fixes with --fix (scaffold / import-intake / apply-palette / a /suds:copy pass), and returns a verdict — READY, SHAREABLE with notes, or NOT READY — plus a punch-list of anything an operator still has to do (photos, logo, missing facts). FAILs block; WARN-only is shareable for feedback. Then walk the human checklist below.

/suds:qa --fix

Content and trust

No placeholder copy, lorem ipsum, fake prices, or unconfirmed claims.

Phone, address, maps, hours, and contact CTAs are correct.

Service pages match confirmed services only.

Images have meaningful alt text and are not broken.

Build quality

Header, navigation, hero, and footer work on desktop and mobile.

Forms use real form IDs and submit correctly in the local/staging environment.

SEO title, description, schema, and location data are present.

Mission Control shows no unresolved launch-blocking gates.

/suds:mission-control

Last-mile reminder: SMTP credentials, DNS cutover, hosting migration, and license/account tasks are operator or admin responsibilities outside the creative build workflow.

Design-system reference (archetype theme): the Suds Build System 2.0 theme ships a living reference of every section, variant, and design token — browse Appearance → Design System in wp-admin: Brand tokens (swatches + export), Pages (what each page renders right now, in order, with edit-content and live-preview links per section — the fastest answer to "where do I change this?"), and the Section library (every section with one-click live previews). Also: docs/manual.html in the theme, the visual section catalog + coverage matrix in docs/catalog.html, per-section previews at ?sbs_preview=<id>, and token export with wp suds tokens (JSON / CSS / ACF). See .claude/reference/design-manifest.md. Section Review Board (polish loop with the agent): open ?sbs_review=board on the sandbox — a sections × archetypes coverage matrix; click any cell to preview with review chips (flag a section with a note, mark approve), ?sbs_review=matrix&sec=<id> shows one section across every skin. Your flags become the agent's punch list (wp suds review next); the agent marks fixes ready for your re-check.

The Section Studio (compose + create): two newer browser tools complete the polish loop — full runbook in the theme at docs/workbench-runbook.md. Section Builder (?sbs_compose=<page>): arrange any page beside a live render — reorder / add / remove sections, set each section's layout knobs (columns, density, tone…), pick the home hero layout; every save passes the same claim-safety validation as wp suds compose, with one-click Undo/Reset. Sections that would assert something untrue on this site are greyed out with the reason. Section Designer (?sbs_design=new): spec a brand-new section (purpose, placement, fields, knobs, authoring brief) — it files a work order for the agent, who scaffolds, authors, lints (wp suds section lint), and brings it to the Review Board; you approve it in all 7 skins before it publishes (wp suds section publish --check). Drafts are badged everywhere and never ship to client sites.

Troubleshooting

Most problems come from the wrong workspace, stale intake files, expired assets, or trying to make the workflow handle non-build setup.

Problem	Likely cause	What to do
Claude Code cannot find `.claude/`	The session opened in the wrong folder.	Open the folder that contains `.claude/` and the WordPress files, or move the framework into the selected workspace.
`/suds:init` picks the wrong client	Multiple intake JSON files are present.	Keep only one `SD-*-client.json` in `.claude/intake/`, then rerun `/suds:init`.
Images are missing	Signed onboarder URLs expired before init localized them.	Export a fresh client JSON, replace the old file, and run `/suds:init` quickly.
Mission Control looks empty or behind	The build hasn't reached that stage yet, or the page is cached.	Run the relevant `/suds:*` command; the dashboard re-derives from files every few seconds — reload if needed.
Mission Control says "pre-init" but the site is already built	An inherited / mid-build site that was never onboarded into the framework (no `product/` docs).	Do not run `/suds:init` (it would generate a fictional from-scratch plan). Run `/suds:backfill` to reconcile the artifacts from the live site, then finish remaining work with `/suds:improve`.
An older build is missing the Google rating badge, reviews, or pricing	The site was built before the questionnaire captured public contact / reviews / pricing, so those surfaces sit gated off.	Run `/suds:enrich` — it backfills exactly those surfaces from a re-issued intake, market-default pricing marked for review, or values you confirm, set-once (it never overwrites edits). Surfaces with no real source are reported as open decisions.
Decision answers will not save	The Mission Control server isn't running, or the page was opened as a file.	Run `/suds:mission-control` (or the launcher) and use the `localhost` URL it opens.
`/suds:next` cannot create work	Required product docs or roadmap files are missing.	Run `/suds:init` again, then retry `/suds:next`.
A generated task tries to install plugins or configure DNS	The task crossed the blueprint boundary.	Reject that scope and rerun the request as creative build work: copy, layout, theme, media, SEO/schema, or launch QA.
WP-CLI has database errors in Local	Local may require its MySQL socket path.	Use the socket noted in the project manifest, usually with `php -d mysqli.default_socket=<site-sock> wp ...`.
Page polish is unclear	The issue is too broad for one pass.	Use BCB Edit Capture and ask for one section, one page, or one ordered patch list at a time.

Suds Site Build Operator Manual. Primary command: /suds. Active workflow root: .claude/.