Projects
The projects page lists every board on this machine. Start a new board here, or pick one to open, fork, export or archive it.
A project is one board and its history of versions.
The page has three parts, and only the list scrolls:
| Part | Where | What it holds |
|---|---|---|
| The ledger | Left | Every board, one row each, with the command line at the top |
| The disc | Right | The selected board: its picture, its checks, its versions and its actions |
| The foot | Bottom | What this machine can do, and what it is building now |
Click a row to select it, and the disc follows.
Keys
| Key | Does |
|---|---|
| J / K or ↓ / ↑ | Select the next or previous board |
| Enter, or double-click a row | Open the selected board |
| F | Fork the selected board |
| /, or Space twice | Go to the command line |
| Esc | Leave the command line. On a phone, shut the disc. |
Making one
There are five ways to start a project.
| Start from | How | What happens |
|---|---|---|
| A sentence | Type it on the command line and press Enter (Shift+Enter for a new line) | The workbench opens with the build running |
A design.json | Open a file, or drop it anywhere on the page | Built without calling the model |
A finished .kicad_pcb | Open a file, or drop it | Read and shown. Nothing is designed, priced or routed. |
A project .zip | Open a file, or drop it | The whole project comes back. Nothing is built. |
| Nothing | Fill in Name and leave the prompt empty | An empty project. Its first message builds v001. |
From a sentence. Without a name, the project is named from the first words of your prompt. When the first board arrives, it takes the board's own name from the model.
From a design.json. The file is in the design format,
for example one saved by the command line or edited by hand. Use it when no
model is set up, or to rebuild a board exactly.
From a .kicad_pcb. The parts, their positions and the nets come across.
The traces do not. It answers in about a fifth of a second. What did not happen
shows on the board:
- The checks say ERC not run and Route off, and the cost says not priced.
- The gaps say the parts are this file's footprints, not orderable parts.
- The notes list each choice made on the way in, such as parts brought up from the back or rotations snapped to a quarter turn.
A board this pipeline cannot build is refused, with the reason:
| Refused when | Limit |
|---|---|
| Copper layers | Not two |
| Size | Under 8 mm or over 150 mm on a side |
| Footprints | Fewer than 3 or more than 120 |
| Nets | Fewer than 2 |
| Packages | Any ball grid array |
From a project .zip. Use a project exported from another machine, with
Export .zip on the disc or Every version and the thread in the workbench's Export menu.
Every version, the draft and the conversation come back. See
Exports and files.
Fork. Fork from the disc, with F on a selected row, or from any version
in the workbench's version menu. The fork starts at v001 with a copy of the
chosen version, and records parent: <project>/<version>.
Pinning the microcontroller
Pin the board's microcontroller module before you describe the board. The build then uses exactly that module.
- Type
@on the command line, or press @ MCU. The roster opens: five modules, each with its family, LCSC code, price and stock. - Type to filter it. ↑ / ↓ move, and Enter or Tab pins. Esc closes the roster.
- The pinned module shows as a token in front of your words. The line under it says what the token resolves to.
- Check the module on the disc: its 3D model (drag to turn it), size, price, stock, power rails, antenna keepout and mount.
- Choose the mount: soldered down on its own pads, or on headers where the module allows it.
- Type the rest of your prompt and press Enter.
Click the token to see the module again. Its × unpins it.
Why a list and not a search. Every other part is found by searching JLCPCB, which suits a 10 kΩ resistor: forty of them will do. A module's exact identity decides the pinout, the footprint, the power rails and half the layout. It is also the part the search loses most often. Pinning it turns that search into a lookup by LCSC code.
soldermask/platforms.py holds only what no CAD data carries:
- which symbol has the pin names
- how the module may be mounted
- what its rails can supply
- where copper may not go
Geometry, price, stock and the 3D model come from the same live lookup as every other part.
The roster stays off until GET /api/platforms answers.
The ledger
Each row is one board. It shows the name and its flags (example, archived), and the current version's summary. It also shows the build's state, the version, the cost of one board and when it last changed.
The build state is the verdict, in the workbench poll's words and colours. After the word comes the first station that did not pass. Hover it for the full sentence.
| State | Means |
|---|---|
| GO | The build's own check passed |
| NO-GO · Copper 4 err | The build's own check failed. The station that holds is named. |
| UNJUDGED · ERC not run | Nothing failed, but a check the verdict needs did not run |
| UNJUDGED · no verdict | Built before verdicts existed. Rebuild it to judge it. |
| unjudged · from a file | Read from a file. Nothing was checked, routed or priced. |
| no build yet | An empty project |
| A phase and seconds | A build is running on this board now |
Gaps and ERC warnings do not change the state. They are advisories, and the disc counts them.
Facets, filter and sort
Above the rows, the facets filter the list: All, GO, NO-GO, Unjudged and Examples, each with its count. Archived is a separate toggle. Archived boards stay hidden until it is on.
- The filter matches name, summary, description and tags.
- Sort by recent, name, cost or number of versions.
Examples
Examples are rows with an example flag and their own facet. On the disc, an example's first action is Fork & edit. Your fork is your own board, and it does not keep the flag.
Flag a board you have checked yourself with
PATCH /api/projects/<slug> {"example": true}.
Live builds
A build running on any project, from any device, shows in its row as the phase
and the seconds. A build whose row is hidden by a filter shows as a row above
the list. The page checks GET /api/app every 3 seconds while a build runs, and
every 30 seconds otherwise. The list reloads when a build finishes.
The disc
The disc shows the selected board.
- The picture is the current version's board, drawn in one colour: outline, pads, copper, silkscreen and the pour's edge. The back layer is dimmer, and unrouted connections are dashed.
- The corners show the build state, the version, the date and the part count.
- The readout lists the verdict, any station that holds or did not run, the advisories, the parts and the cost.
- The versions list, newest first, links each version into the workbench, with its state and cost.
The actions:
| Action | Does |
|---|---|
| Open | Opens the board in the workbench. An example offers Fork & edit first. |
| Fork | Starts a new project from the current version |
| Export .zip | Downloads the whole project as one file |
| Rename | Changes the name and the description |
| Archive / Unarchive | Hides the board unless the Archived toggle is on |
| Delete | Moves the project to the trash. The foot's trash chip restores it, or empties the trash for good. |
The row's state, the picture's state and each version's mark come from one rule, so they always agree.
The verdict is the build's, not a fresh check
The verdict is what the build's own check said when the version was saved.
A version built before verdicts existed, or read from a file, reads
unjudged. Rebuild it to judge it. Nothing on this page re-runs KiCad's DRC.
soldermask projects rejudge runs KiCad's DRC again on saved versions'
copper, and the page then shows the new verdict. See
Versions and history.
On a phone, the disc is a sheet along the bottom. Tap its grip to open it.
The foot
The foot shows this machine as a row of chips. Each has a line under it in its state's colour. Hover a chip for what it means, or why it is not green.
| Chip | Shows |
|---|---|
| Lightcycle | The version of Lightcycle, the default router, or missing |
| A* | Whether the A* router is ready. It routes a board that names it, or when Lightcycle is not built. |
| kicad-cli | The version of KiCad's command line, the DRC judge and renderer |
| model | The model that will design boards, or none |
| catalogue | Parts on disk, and the day the catalogue was built |
| running | Builds under way |
| boards | How many projects there are |
| trash | Deleted projects. Click to restore one, or to empty the trash. |
All of it comes from GET /api/app.
The note under the command line
It names the model that will design boards, such as claude-code · claude-fable-5-2, or says why there is none. Without a model you can still
open a design.json. If no router is ready, it says boards will save
unrouted.