Chat and decisions
The board is the document the conversation edits. The thread on the left is not a log kept in the browser: it is read back from the project every time you open it — the versions, and the turns that made none — so it survives restarts and reads the same on every device.
Turns
Each message is a turn. The model is given, in this order: how the board came to be (the first message, which is the brief, and the last six turns with its own replies), what the pipeline found when it last built the board, the design as it stands as JSON, and your message. It answers in words, and returns a design only when something on the board should change.
A question builds nothing. What does C1 do?, why that regulator?, would this run from a LiPo? are answered in a few seconds from the design on screen; no version is made and the board is left alone. The answer is kept in the thread.
A change is built. Add a reverse-polarity diode on the input comes back as the complete revised design, keeping every refdes that should survive, so the diode is added and the regulator stays where it was. The reply is the model's own account of what it did and why, followed by a line of what actually changed, computed by diffing the two designs rather than trusting the description: parts added, removed and swapped, net changes, the version id and the cost to build one. If the electrical check found errors or parts could not be resolved, the reply says so and points at Details.
A build that is not clean is revised before you see it. When a build comes back with a part that does not exist in that package, a pin the symbol library could not match, or an electrical error, the findings go straight back to the model — the same brief the command line's --repair sends — for one revision. The revision is measured first (parts resolved, electrical rules) and built only if it scores better by the repair loop's rule, which scores a deleted part worse than a broken one, so a revision cannot pass by dropping the failing part. Both builds are versions: the reply reads The build came back with 1 part(s) or pin(s) could not be resolved, so I revised it: …, and the thread shows both. A revision that scored no better is not built and the reply says so. An unrouted net is reported to the model on the next turn but does not start a revision on its own. SOLDERMASK_AUTO_REPAIR sets the number of rounds; 0 turns it off.
A question takes seconds. A change takes one to three minutes, most of it the model and the router, and a revision doubles that on the turns that need one. While it runs the thinking bubble names the stage: thinking · resolving parts · placing · routing · writing fab files · checking stock · fetching 3D models · saving · revising. The composer is disabled until it lands. See Builds and live sync for what happens if you close the tab.
Which version an edit builds on
The version on screen. If you have opened an older version, a banner says so — Viewing v002 of v004. A new message builds on v002 — and the new version records parent: v002. History is never rewritten; the newer versions stay.
Decisions
When a prompt leaves a real architectural fork open — how the board is powered, whether firmware is field-updatable, battery or mains — the model is instructed to put it in decisions with two or three options and mark one recommended, and to build the recommended one anyway so there is always a board on screen. Decisions appear as cards under the reply. Clicking an option sends its label as the next turn. Only the newest reply's cards are live; older ones were answered by whatever came next.
The model is told not to invent choices the prompt already settled, and the schema allows at most two decisions per turn.
The seeds
An empty project offers five prompts that are known to build cleanly end to end — an LDO breakout, an I²C sensor breakout, a 555 blinker, a MOSFET low-side switch, a dual op-amp buffer. MCU modules (ESP32, LiPo chargers, USB-C PD) are deliberately not offered: they lose most of their parts to the package constraint and the board will say so.
What the model is told
The system prompt is the one in Design (the model), with a paragraph for the conversation: that reply is shown to the person, that a design is rebuilt from scratch and takes minutes so it is returned only when something on the board should change, that a returned design is the complete one with every surviving refdes kept, and that what the pipeline found on the last build is in the message and is to be fixed unless the person says otherwise. The message carries the history clipped to the brief plus the last six turns, each cut at 500 characters; the findings of the last build — unresolved parts and pins, electrical errors and warnings, unrouted nets — in the words the repair brief uses; the design as JSON; and the message. A first message on a fresh project is sent exactly as typed, so the app, the command line and the evaluator ask the same question.
When there is no model
If no backend is configured the thread says why (set GEMINI_API_KEY (or GOOGLE_API_KEY), or SOLDERMASK_BACKEND=claude) and the composer stays off. You can still import a design.json from the projects page.