Build Bot User Guide
1. Executive Summary
Build Bot turns one good live page into many. You clone a page that already works on the store, Aegis keeps it as a template, and Build Bot fills that template from the Range Planner to make a page for each product. Every page lands in the working copy first, where you can open it, test it and download it. A page reaches a Shopify store only when you publish it.
live page ──clone──▶ template ──build (Range Planner)──▶ working copy ──publish──▶ Shopify
Three rules run through the whole module:
Nothing reaches a store by accident. A build only writes to the working copy. Publishing is a separate step, it asks which store and theme, and the live store always asks you to confirm.
A gap stops the publish, not the build. If the Range Planner card is missing a value the template needs (a price, say), the page is still built so you can see it, but it cannot be published until the Range Planner has the value and the page is rebuilt.
The rules live in Aegis. How a clone has to behave (sliders move, add to cart works, and so on) is written down in Settings → Build Bot, and every clone and build reads it from there. Editing a rule needs no deploy.
Who can use it
The Build Bot tab, the clone_page MCP tool and the builds domain are open
to superadmins and to users with the Build Bot permission
(access_buildbot). Settings → Build Bot is the same.
2. The words used here
| Word | What it means |
|---|---|
| Page type | PDP, LP, FAQ and so on, from Settings → Page Types. Every template and built page belongs to one. |
| Clone | A live page captured as flat HTML that is right at both phone (375px) and desktop (1280px) widths, checked against the live page, with a design pack beside it. |
| Template | A named clone, such as "Floor Cleaner V1". A page type can have several. Product values in it (name, SKU, prices) are slots such as {{ productName }} that a build fills in. |
| Version | Cloning again under an existing template name makes a new version of that template. The newest version is the one builds use. |
| Default template | The template a page type builds from when you don't choose one. Set it in Pages → Clones → Templates. |
| Built page | One page made from a template: page.html (the Shopify cart) and page_ecommerce.html (the Aegis cart). They are listed under Pages → Clones. |
| Working copy | Where built pages are stored: the builds domain, builds.purdyandfigg.dev. For testing and working on, never what customers see. |
| Publish | Putting a built page into a Shopify theme, on staging or live. |
3. Clone a page into a template
Cloning runs on your own computer, in a real browser, driven by Claude through the Aegis MCP. You don't need the Aegis code.
3.1 Before you start
Claude connected to the Aegis MCP (see the Claude MCP Setup guide).
Node.js 20 or later, and Playwright with Chromium and sharp in a folder of their own. Claude checks for these first. If anything is missing it stops and asks you to install it; it never installs anything itself:
npm init -y && npm install playwright sharp && npx playwright install chromium
3.2 Ask Claude to clone
Say something like "clone a page", or give it all at once: "clone LP https://us.purdyandfigg.com/pages/completestarterkit-offer and call it US complete starter kit offer V1". Claude asks, with multiple-choice questions, for anything you leave out:
- The URL of the live page.
- The page type. A product page is usually PDP.
- The template name. Pick an existing name to add a new version of that template, or type a new one to start a new template.
3.3 What happens
A browser window opens. Leave it alone: live sites turn away headless browsers, so it has to be visible. It takes one to three minutes and goes through these steps:
| Step | What it does |
|---|---|
| 0 | Confirms the page type with Aegis. |
| 1 | Captures the page at 375px and 1280px. |
| 2–3 | Finds the sections that differ between the two widths and merges them, so the clone is right at both. |
| 4 | Removes the CSS the page doesn't use. |
| 5 | Checks the copy against the live page: page height, every section's size, a visual score per section, and that sliders, scroll buttons and add to cart work. A clone that fails is not kept. |
| 6 | Makes the template (product values become slots; prices come from what the buy button shows) and writes the design pack. |
| 7 | Stops before uploading: nothing goes to Aegis yet. |
3.4 Look at it, and propose what is wrong
Before anything is uploaded, Claude opens the clone's preview in its own browser view (the template filled with the PIM's photos and copy, as a build will be) and tells you:
- what became a slot, and the value each holds here;
- anything that still belongs to this one product (a name, a price, a SKU left in the text), which every built page would repeat.
Nobody edits a clone. A clone fixed by hand loses the fix the next time
the page is cloned, so the kit records what it wrote and the upload refuses a
template.html or fields.json changed since. If something is wrong or
missing, Claude proposes a clone rule to Aegis (propose_clone_rule): what
to recognise, what the clone should do, how the check proves it. It arrives in
Playbook Rules marked CLONE RULE, with a Slack alert. Approving it adds
the rule to the clone rules (§9); the clone kit is then built to match, and
the page cloned again.
The gallery's photos become PIM slots. The kit marks the product's gallery
itself: desktop slides {{ image1 }}…, mobile ones {{ imageMobile1 }}…,
thumbnails at 120px. A page with no gallery it recognises says so.
The PIM's copy becomes slots too. For a product page, the clone reads the
product's record from the PIM (by SKU) and finds where its copy sits on the
page: the description, scent details, delivery and returns, FAQs, reviews,
subtitle and buy-box lines. That section is emptied to one slot, such as
{{ websiteDescription }}, and a build fills it from each product's own PIM
record. The page's wording doesn't have to match the PIM's word for word; the
clone only needs to know where each section goes. An FAQ becomes two slots,
{{ faq1_1 }} for the question and {{ faq1_2 }} for the answer, so the
accordion still works. The clone tells you how many PIM fields it placed.
A page that isn't a product's own page (an LP, say) gets no slots: it is kept exactly as captured. That is what a no-product build (§5.2) is for.
3.5 Upload
When you say it's ready, Claude uploads it, exactly as the kit made it. The template then appears under Pages → Clones → Templates, and on the builds domain's front page.
The session Claude uses lasts two hours. If it runs out, Claude asks the tool again; the folder on your computer is kept.
4. Manage templates
Pages → Clones → Templates lists every page type's templates in one table, each row its newest version: a screenshot of the page as cloned, its type, the page it came from, its versions (click to list them under the row), the live check, who cloned it and the default. Filter by page type, or search. Settings → Page Types shows each type's template count, and its Templates link opens this tab filtered to the type. Anyone with Build Bot sees the list; Make default, Rename and deleting are a superadmin's; a superadmin can also tick templates and Delete them, every version of each, at once. A template that pages are built from cannot be deleted (its row says how many; the server refuses too): rebuild or delete those pages first. ⭐ watches a template for this session, and Watching N filters to them.
| Action | What it does |
|---|---|
| Make default | Builds of this type use this template when none is chosen. The default is a template: it always means that template's newest version. A pinned default says so; Use newest goes back to whichever template was cloned last. |
| View | The newest version's own page: where it came from, how it checked, its slots, its files and screenshots. |
| Template | The template's HTML, with its {{ slots }}. |
| Rename | Renames the template, every version of it. Two templates can't share a name. |
| Download | A zip of the newest version, or of any version from its own row. |
| Delete version | Deletes the newest version, so the one before becomes the newest (any version can be deleted from its own row). If the default template's only version would go, choose another default first. |
5. Build pages
Build Bot → + Create New Page opens the Page Setup Wizard (Build), laid out like the Shopify page setup:
| Step | |
|---|---|
| 1. Destination | The page type and the template (the type's default is chosen for you), then products or a page name. The store is shown, not chosen: it comes from where the template was captured (a us. page is the US store). |
| 2. Slack | Send, and a channel. Left on Use routing rules, the rules in Settings → Slack decide; a channel here overrides them for this page. |
| 3. QA & Monitor | The same step as the Shopify page setup: what the page type monitors, then QA (QA this page, unticked by default), Monitor (Monitor this page, unticked by default: a monitored page is QA'd only when it has changed; Check against PIM (hourly), unticked by default) and the visual drift threshold. Check against PIM checks the page as published against the PIM every hour and posts a change to Slack once (§8.3); it is greyed out when the page type isn't checked against the PIM or the page has no product, and always on a Shopify or Proxied page. QA, Monitor and the threshold apply once the page is an Aegis page. |
| 4. Summary | What will be built, with these settings, as the Shopify wizard's summary: each row has Edit back to its step. ✅ Finalise & Build is on this step. |
| 5. Build | The build runs here, step by step, and says what it filled and what is missing, and where to fill it: "Price missing in the Range Plan", or copy and images "missing in the PIM". Close the window at any time; the build carries on. |
Change them later with Options → Edit on the page.
5.1 From Range Planner products
Tick one or more products. The list shows only Range Planner products that
don't have a page of this type yet, and you can search it. Build makes
one page per product: it fills the template's slots from the product's Range
Planner card, adds the card's product image, and builds both page.html and
page_ecommerce.html.
You can build many at once. They are sent in batches of 25, and the progress window has Working copy and Not built tabs so failures don't get lost.
5.2 With no product
Leave every product unticked and a Page name box appears. Give the page a name and press Build page: the template is built exactly as captured, with nothing from the Range Planner. Use this for landing pages and other pages that aren't one product's page.
- A template with no slots (an LP clone, for instance) can only be built this way, so the product list is hidden.
- A PDP always needs a product, because it publishes onto that product's own page.
- The page's folder is named from the page name. If the type already has a page with that name, rebuild it instead or choose another name.
5.3 Gaps
If the Range Planner or the PIM has no value for a slot, the page is still
built: the slot shows as it is (£{{ nonMembersOtpPrice }}), the Gaps
column says ✗ N failed, and the progress window says "publish blocked".
Add the value at its source, then Rebuild.
Click the ✓ pass or ✗ N failed pill to see every slot: where its value came from (Range Planner, PIM or Clone), what it was filled with, and which failed.
Use the clone's text. In that window, any slot can be set to use the clone's own content instead of its source, and set back with Use the PIM again. It applies from the next Rebuild (a button appears), is no longer a gap, and isn't counted as a change by Check against PIM. The clone's text is the cloned product's: fine for generic copy, wrong for another product's scent.
5.4 Rebuild
Options → Rebuild builds the page again from the product's current Range Planner card. It asks which template to use, and suggests the one the page was last built from. A rebuild replaces the files in the working copy; it never changes a page already on Shopify until you publish again.
6. The Build Bot table (Pages → Clones)
One row per built page, with filters for page type, template, store, status (built, archived or all) and group, a search for products and SKUs, and Watching N (shown once you watch a page) to see only your watchlist.
- Tick boxes on the left select rows (the header box ticks the page of the list). A bar appears with Rebuild, Archive, Unarchive, Add to group, Remove from group, Watch and Delete for every ticked page (Archive only for pages not archived, Unarchive only for archived ones; Archive and Delete only for superadmins or users with that permission in User Manager, as on Pages). A bulk rebuild uses each page's own template, its newest version; a progress bar shows the page it is on and the count (e.g. Deleting Daffodil Refill Pack · 19/24), then the total; only failures are listed, with why.
- Groups are shared by everyone. Add to group takes a new or existing name (a new one makes the group); a page's groups show as tags under its name, and clicking one filters to it.
- ⭐ Watch is yours, for this session, like the Pages watchlist.
| Column | |
|---|---|
| Screenshot | The product's main photo from the PIM (the page has no screenshot of its own until it is published): click to enlarge. |
| Product | The page's name and store flag (🇬🇧 / 🇺🇸), then: 👁️ the page (Shopify cart), 🛒 the Aegis Commerce page (Aegis cart and checkout), ℹ️ the page's details (its card, slots, gaps and files), and the Shopify icon for the product's own page on the store (greyed out when the store has no product with that SKU yet). |
| Type | The page type. |
| Status | One pill, as on the Pages lists: Live (on a live store or a live ecommerce route), Staging, Working copy (on no store), PIM changed, or N gaps. Click it for the window behind it: Build (when, how long, which template and clone, what is missing), Shopify (each store and theme it is on, view or switched), Ecommerce (the routes made from it), Check against PIM and QA & Monitor, each with its actions. |
| SKU / Price | From the Range Planner card ("no product" for a no-product page). |
| Gaps | ✓ pass or ✗ N failed: click for every slot and what filled it (§5.3). Failed slots block publishing. |
| Found on | The other built pages this SKU is on, as their product or as a cross-sell: click the pill for the list, with each page's template and where it's on Shopify. "only here" if none. |
Options on each row:
| Action | |
|---|---|
| Edit | The page's Slack and QA & Monitor, as set in the wizard: Check against PIM (hourly), Test, Monitor, the drift threshold. |
| Publish to Shopify / Republish to Shopify | See §8. It says Republish once the page is on Shopify. |
| Roll back | Puts a product back on the template it used before Publish switched it (§8.1). Only when a publish switched one. |
| Check against PIM | See §8.3. Only on page types set to it. |
| Rebuild | See §5.4. |
| Download | A zip of the page, its card and its details page. |
| Archive / Unarchive | Hides the page from the list and the working copy's indexes; its files stay. |
| Delete | Removes its files and its record. |
7. The working copy (builds domain)
Every build lands on https://builds.purdyandfigg.dev. Its front page lists
every page type with its templates, how many pages are built, and the last
build. Each type has a list of its pages with links to Shopify where they've
been published.
It's private. You only get in with a token from Aegis:
- From Aegis, nothing to do. Links in Build Bot, Clones → Templates and the build windows carry a short-lived token for you. If you open the builds domain directly while you're signed in to Aegis, it sends you through Aegis and straight back, signed in. If you aren't signed in, you sign in to Aegis first.
- For someone outside Aegis: Build Bot → 🔑 Builds access makes a named link that lasts 1, 7, 30 or 90 days. It's shown once, so copy it then. The same window lists every link with when it was last used, and Revoke stops one working straight away.
The link sets a cookie on the builds domain, so clicking around keeps working. If your browser blocks that cookie, the page tells you so.
8. Publish to Shopify
Options → Publish to Shopify.
Staging or Live. The page goes to the store it was cloned from (UK or US).
Theme. The store's live theme is chosen by default and named under the list. Search by name or ID to pick another.
The product check. Aegis looks for the page's SKU on that store, since add to cart needs the store's own product. If it isn't there:
- on staging you can tick Publish anyway, for testing (add to cart won't work);
- on live there's no override.
A no-product page skips this check.
Publish. Staging asks once, with the usual "don't show again" option. Live asks every time in a confirmation window.
A progress window shows each step, and Close appears when it has finished.
Republish. Once a page is on Shopify, Options says Republish to Shopify, and the window opens on the store and theme it went to last. On that theme it says it updates the page already there; choose another theme and it says the page goes there as well.
8.1 What publishing does
| Page type | On Shopify |
|---|---|
| PDP | A product template, product.aegis-<page>, and the product switches to it: /products/<handle> itself shows the built page (in a preview theme, in its preview). What the product used before is recorded, and Options → Roll back puts it back. Tick Publish as a view only to leave the product alone and see the page at /products/<handle>?view=aegis-<page>, beside the current one. |
| Every other type | A page template, page.aegis-<page>, and a Shopify page with the handle aegis-<page> using it, at /pages/aegis-<page>. The aegis- prefix means it can never overwrite the page it was cloned from. |
On the way in, the page is made to work in that theme:
- add to cart uses the PIM's variant:
subVariantIdwhen the page's Add to cart is a subscription,otpVariantIdwhen it is not (non-members PDP). Blank in the PIM stops the build and the publish, naming the field. On staging, the same SKU's variant with the same title. A variant called Unleashed (a price-test placeholder) is never used; - cross-sell add to cart buttons are matched to this store's products too (any it can't match are listed in the progress window);
- the theme's own scripts and styles are loaded, so the slide cart, spinners and button states work as on the rest of the store;
- the page sits inside the theme's own layout, like every other page on the store: the header, footer, announcement bar, cart drawer and the theme's scripts and styles are the store's current ones, and only the page's own sections come from the build (the progress window says so);
- a sticky add-to-cart bar (if the clone found one) appears once the product's Add to cart has scrolled away, as on live;
- sliders are reset so the theme can build them again.
Staging pages are visible (the store is password-protected). Publishing the same page again updates the same template and page.
8.2 What publishing won't do
- Publish a page with gaps. Fix the Range Planner and rebuild first.
- Publish a PDP without the store's product. There'd be nothing to show it on.
- Compare prices. The button shows the Range Planner price, but Shopify charges the product's own price. Growth keeps an eye on that.
8.3 Check against PIM
Options → Check against PIM compares what a page was published with (its name, SKU, prices and PIM copy) with the PIM now: per store it's on, each slot ✓ or ✗ changed. A page not on Shopify yet is checked as its working copy. When something changed: Rebuild, then Republish. A rebuild reads the Range Planner for name, SKU and prices, so a price changes only once the Range Planner has it.
It is a page type setting: Settings → Page Types → Edit → Check pages against the PIM (on for PDP). Pages of other types don't offer it.
Every hour, on its own: tick Check against PIM (hourly) when you make the page (or later, in Options → Edit). Each hour Aegis checks every store the page is published to; when something differs it posts "… differs from the PIM on UK live: Price, Product description" to Slack, once per change rather than every hour. The page's own Slack settings apply, and the update can be switched off in Settings → Slack → Build Bot → Built page differs from the PIM.
9. The rules every clone follows (Settings → Build Bot)
Settings → Build Bot holds the core files:
- PAGE_DESIGN.md: the behaviour rules for every page type.
- Extra rules for (type): optional extra rules for one page type, added after the shared ones.
The clone kit reads them from Aegis every time it runs, so an edit applies to the next clone with no deploy. Every save is kept as a version. The shared rules today:
| Rule | |
|---|---|
| PD1 | Sliders move. |
| PD2 | In-page buttons scroll to their target. |
| PD3 | Links go where they go on the live page. |
| PD4 | Forms point at the shop. |
| PD5 | Add to cart is Shopify's cart (page.html). |
| PD6 | The ecommerce page uses the Aegis cart (page_ecommerce.html). |
| PD7 | On a Shopify store, the theme runs the page -- and renders its own header, footer and cart. |
| PD8 | A sticky add-to-cart bar follows the product's button. Needs a clone made after 2026-10-06. |
10. Troubleshooting
| What you see | Why, and what to do |
|---|---|
| The clone stops at step 5 | It didn't match the live page closely enough, so it isn't kept. Claude reports the section and the score. Try again (a pop-up or animation caught mid-way can cause it). If it keeps failing, the page needs a rule in Settings → Build Bot. |
| Claude says Playwright or sharp is missing | Install them (§3.1) and ask Claude to carry on. |
| "Publish blocked" / a Gaps entry | The Range Planner card is missing that value. Add it, then Rebuild. |
| "No product with SKU … on the store" | The store doesn't have the product yet. Create it in Shopify, or tick the testing override on staging. |
| The 🛒 Aegis Commerce page's add to cart does nothing | The product isn't in the Aegis catalogue for that store (Ecommerce → Products). Add it, then rebuild. |
| The builds domain says "This needs a link from Aegis" | Open the page from Build Bot, or ask for a link (§7). |
| The builds domain says your browser didn't keep the cookie | Allow cookies for builds.purdyandfigg.dev and try again. |
| A template doesn't appear in New page | It belongs to another page type, or the clone was never uploaded (§3.5). |