What the AI builder actually generates — and why it stays editable
A generated site is a strong first draft, not a finished one: what the engine returns, what validation silently discards, and why no later edit can be lost.
What the AI builder actually generates
A generated site is a strong first draft, not a finished one. In one turn you get structure, hierarchy and plausible copy; what you do not get is something you can ship unread. This article is about the seams — what comes back from the engine, what gets silently trimmed on the way in, and why nothing you change afterwards can be lost. It complements "The AI builder" and "Site structure", which cover the shape of the spec and the page model.
What comes back from a turn
One JSON object with two keys: reply, a sentence or two addressed to you, and spec, a SiteSpec of the form { name, theme, pages: [{ slug, title, sections }] }. The engine never emits HTML and never emits code. That single rule is why a chat edit and a drag-and-drop edit cannot disagree later — both write the same typed document, and the renderer reads only that one.
The theme is site-wide: accent, font, mode and radius, shared by every page. Pages are addressed by slug, and the first of them must be home. Thirteen section kinds exist — hero, features, richText, gallery, pricing, faq, contact, cta, stats, testimonials, team, collection and form — each typed, with its own fields. A collection section names a collection rather than swallowing its data, which is how repeatable content stays in the data plane.
What validation does to the result
The returned spec is validated before anything is stored, and on failure the engine is asked once more with the validation error in its context, at a lower temperature. Two failures and the turn errors out rather than saving a broken page. But note what validation does: it coerces, it does not repair.
| What the generator sent | What gets stored |
|---|---|
| A page whose slug duplicates one already in the spec | The page is dropped |
| A page with no slug, or no title | The page is dropped |
| More than 32 sections on one page | 32 sections; the rest are discarded |
| More than 16 pages | 16 pages |
| A slug with capitals, spaces or punctuation | Lowercased, invalid characters become dashes, leading and trailing dashes trimmed |
| A section the schema does not recognise | Dropped |
That table is the honest answer to "why did the site come back smaller than I asked for". Nothing warns you when it happens, and the reply text will not mention it.
What the engine is instructed not to do
Its instructions forbid inventing brand claims, statistics or availability promises you did not state, and ask it to keep prices realistic. Copy is written in the language of the conversation. It is asked for one to three pages unless you ask for more, and two to six sections per page, with a hero first. When you ask for something the schema cannot express, it is told to do its best inside the schema and say so in reply — which is worth reading, because that sentence is the only place the limitation is admitted.
Where a generated site disappoints
- Structure is conventional. It arranges thirteen section kinds well; it
cannot produce a layout the vocabulary does not contain. Ask for something the schema cannot express and you get the nearest thing that it can.
- Copy is plausible, not verified. It reads like marketing because it learned
from marketing. Every number, every claim about your business and every testimonial needs a human pass before the site goes live. A testimonials section full of invented quotes is the single most common thing to delete.
- It may restructure without asking. Creating, renaming or removing pages is
allowed as part of fulfilling a request; it reports what it did in reply rather than requesting permission first.
- Long conversations drift. Every turn must return the complete spec with
unchanged parts included verbatim. That instruction holds well for a few turns and approximately for many.
Why the result stays editable
Three properties, all structural rather than promised:
- The spec is the product, not an artefact of it. Each page also carries a
Markdown rendering of itself, so your copy is readable outside the renderer and portable if you leave.
- Structure and content are separate planes. Theme, pages and sections live
in the spec; repeatable content lives in collections and rows. Changing a row changes what a section displays; it does not rewrite the section.
- Publishing is a gate, not a save. Spec edits land in a staged document;
row edits land as staged rows. Publish copies the staged structure onto the live one and promotes staged rows in a single batch, then purges the site's cache tag. Nothing reaches visitors before that — see "Collections, content types and publishing state" for the exact states.
What to do with a first draft
Read it end to end, delete every invented specific, then edit the structure rather than regenerating. The engine is at its best on the second pass, when there is a real spec in context to change instead of a blank page to fill.