The Build Agent turns a site request into a live subdomain.

// 01 · the stack

What it runs on

Deterministic Node scripts do the mechanical work; Claude does the judgment (design, copy, decisions). GitHub and Cloudflare are reached through org-owned credentials — no personal tokens.

Templates

// 02 · setup

One time, per machine

Clone, run setup, then supply the two secret pieces from the team vault. Everything else travels in the repo.

git clone https://github.com/Enginecy/build-agent && cd build-agent
./setup.sh                 # deps + pinned design DB; creates .env

1. Fill .env

   Copy values from the vault: GitHub App IDs + key path, Cloudflare tokens/account IDs (mo & client), optional NocoDB / Telegram / Discord.

2. Add the App key

   Drop the GitHub App .pem into ./secrets/ and point GITHUB_APP_PRIVATE_KEY_FILE at it (exact filename, incl. .pem).

3. Set your git identity

   Once — this is what puts your name on commits (see §10).

git config --global user.name  "Your Name"
git config --global user.email "<id>+<user>@users.noreply.github.com"

// 03 · mental model

Three repos, one working copy

Keeping these straight removes nearly every point of confusion.

A site's code does not live in this folder. To work on a site you bring it local into work/<slug> (a git-ignored scratch area). That checkout is your working copy — edit it, build it, push it back.

Enginecy/<slug>   ──pull──▶   work/<slug>   ──edit·build·push──▶   Enginecy/<slug>   ──deploy──▶   live
   remote,                  your local                        remote,
   shared truth             working copy                      updated

// 04 · scripts & commands

Your two toolbars

Slash commands (in Claude Code)

Scripts (from repo root — .env auto-loads)

AI imagery & scroll-world

Any site's imagery step generates real photos via Pollinations: enginecy-image-direction writes prompts → brief/media.json → generate-media.mjs → public/img/. The scroll-world template is an immersive "scroll to fly through it" 3D scroll (pre-rendered video scrubbed by scroll); /scroll-world drives build-scroll-world.mjs to generate scene stills + dive/connector videos. Prereqs: POLLINATIONS_API_KEY + ffmpeg.

Two motion modes. --mode kenburns (default) is a deterministic ffmpeg push-in over each still — cheap, but a moving photo. --mode aivideo generates a real Pollinations video per scene, so the camera genuinely flies through the space (true parallax); if a scene's video generation fails (e.g. a Pollinations 402 balance limit) that scene falls back to ken-burns automatically, and cached scenes are reused so you can re-run just the failed one later.

Control panel & site registry

Every deploy is recorded in a NocoDB registry — register.mjs runs at the end of /new-site and /edit-site and upserts by slug (one row per site), auto-filling Type, Account, Lane, Template, Category, Vertical, Domain, Status and DeployedAt from site.config.json. See status across everything two ways:

Both read .env server-side — tokens never reach the browser. One shared UI in shared/dashboard-view.mjs.

// 05 · workflow a

Build a brand-new site

One command — or plain English. The agent parses the details and runs the whole pipeline, asking only for anything required and missing.

/new-site slug=pharmacy-wellness template=bespoke-astro \
          lane=A account=mo subdomain=pharmacy.enginecy.cloud \
          brief='Trust-first pharmacy & wellness landing'

…or just say: "Build a trust-first pharmacy landing at pharmacy.enginecy.cloud."

Under the hood: create-repo → scaffold → the design flow → npm run build (must pass) → the audit gate (site-auditor — blocks on any critical finding) → push → deploy-pages (polled to 200) → register → reports the live URL & repo URL.

// 06 · workflow b

Edit an existing site

The easy way is one command; the manual equivalent is four steps.

/edit-site <slug> <mo|client> <subdomain>

node scripts/pull.mjs <slug>            # get latest into work/<slug>
# …edit work/<slug>…  (optionally: /art-direct <slug>)
cd work/<slug> && npm install && npm run build
# …audit gate: run the site-auditor; fix any critical finding, re-audit…
cd ../.. && node scripts/push.mjs <slug>
node scripts/deploy-pages.mjs <slug> <mo|client> <subdomain>

// 07 · across machines

Collaborating — different people, different machines

The shared truth is the GitHub repo. Git handles multi-machine, sequential collaboration natively; each person's work/<slug> is just their own checkout.

The golden rule: pull before you edit

node scripts/pull.mjs <slug>

push never force-pushes. If your checkout is behind the remote, the push is refused — clearly — instead of clobbering someone's work:

refusing to push: remote is 1 commit(s) ahead of your checkout (stale).
  Pull first:  node scripts/pull.mjs <slug>   then rebuild & re-run.

pull also refuses if you have uncommitted changes (commit or stash first) or if history has diverged (resolve manually). For genuinely concurrent work, use feature branches + PRs — the scripts operate on main.

// 08 · the design flow

What makes each site distinct

Never ship a template's placeholder look. Order: direction → data → copy → execution → imagery → polish → gate. Run just this with /art-direct <slug>.

The audit gate — site-auditor

Contrast bugs kept slipping through — light text on light buttons, dark headings on dark sections — so an automated auditor now runs after every build and before every deploy. /new-site, /edit-site, /deploy and /scroll-world all invoke it as a gate; a CRITICAL finding means do not deploy until it's fixed and re-audited. It's a read-only Claude subagent (.claude/agents/site-auditor.md) that:

• Renders the actual build in a headless browser and reads computed styles — so Tailwind utilities and runtime-injected CSS are covered, which static linters miss.
• Sweeps every text element for AA contrast (lib/contrast-audit.js): normalises every colour through a canvas (handles oklch/oklab/color(srgb)), composites alpha over the real background, flags anything under 4.5:1 (3:1 for large text), and hands text-over-image to a visual screenshot pass.
• Runs accessibility-review (focus, landmarks, alt, touch targets, reduced-motion) and the enginecy-visual-quality prohibitions. For scroll-world it also runs audit-scroll-world.mjs against the engine's runtime UI.

// 09 · lanes & routing

Where a site ships — and to whose account

Lanes — decide by: does it need a server runtime you control?

• No → Lane A (Cloudflare Pages): astro-marketing, astro-content, bespoke-astro, three-experience, scroll-world.
• Yes → Lane B (Dokploy): next-app, webapp-fullstack.

Cloudflare account routing — a hard rule

Pages, R2, and DNS all follow ownership. Pass the right account flag:

deploy-pages picks the token from this flag, creates the project, deploys dist/, attaches the subdomain + proxied CNAME, and polls https://<subdomain> until it returns 200. First-provision SSL can take a few minutes.

Custom domains — not just subdomains

The parameter is named subdomain, but the deploy step attaches whatever hostname you pass — a subdomain, www, or an apex/root domain (handled via CNAME flattening at @). The real requirement isn't "subdomain vs. domain" — it's that the domain's DNS zone lives in the correct Cloudflare account. For *.enginecy.cloud that's already true; a brand-new domain needs one-time onboarding.

Path A — register via Cloudflare Registrar (at-cost): the domain becomes a managed zone in the same account automatically, so deploy-pages then just works. One-time per account, in the dashboard: add a payment method + default registrant contact (Domains → Registrations), and add "Registrar" (read + edit) to that account's API token in .env.

# check availability + at-cost price (free, read-only)
node scripts/add-domain.mjs <mo|client> clientbrand.com

# register into the account (CHARGES it — deliberate two-step)
node scripts/add-domain.mjs <mo|client> clientbrand.com --register --yes [--auto-renew]

# then deploy onto it (apex or any host)
node scripts/deploy-pages.mjs <slug> <mo|client> clientbrand.com

// 10 · attribution

Getting your name on commits

Org access authorizes the push; it does not decide attribution. GitHub attributes a commit by matching the author email to a verified email on an account.

push authors each commit with your own git identity and clears any stale per-repo override. It falls back to the Enginecy Build Agent bot only when no identity is set (e.g. the headless runner). The push itself is authenticated by the App.

For your avatar to appear, both must be true:

1. Your git config --global user.email is an email verified on your GitHub account — the <id>+<user>@users.noreply.github.com address is ideal (private + still links to you).
2. You're a member of the Enginecy org.

// 11 · troubleshooting

When something errors

// 12 · quick reference

Copy-paste

# ── Setup (once per machine) ──
git clone https://github.com/Enginecy/build-agent && cd build-agent
./setup.sh                                    # then fill .env, add secrets/*.pem
git config --global user.email "<id>+<user>@users.noreply.github.com"

# ── New site (in Claude Code) ──
/new-site slug=<slug> template=<template> lane=A account=<mo|client> subdomain=<host> brief='<one line>'

# ── Edit an existing site ──
/edit-site <slug> <mo|client> <subdomain>
#   …or manually:
node scripts/pull.mjs <slug>
# …edit work/<slug> …
cd work/<slug> && npm install && npm run build && cd ../..
node scripts/push.mjs <slug>
node scripts/deploy-pages.mjs <slug> <mo|client> <subdomain>

# ── Design flow only ──
/art-direct <slug>

# ── Register a new domain (Path A · Cloudflare Registrar) ──
node scripts/add-domain.mjs <mo|client> <domain>                 # check price — free
node scripts/add-domain.mjs <mo|client> <domain> --register --yes  # buy it

# ── See status of everything ──
open https://dashboard.enginecy.cloud     # hosted, Access-gated, no install
node scripts/dashboard.mjs                # local panel → localhost:4545