Projects
What a project is, where the files are edited, how a preview is produced, and how a project gets published.
A project is a folder of files with a name, a kind, a history you can roll back and, optionally, an address it is published at. Everything the assistant writes goes into a project, which is what makes its changes reviewable rather than conversational.
The three views of a project
| Screen | What it is for |
|---|---|
Projects (/dashboard/projects) | The list: cards with the kind, the file count, and favourites |
A project folder (/dashboard/projects/[id]) | Managing the files themselves: what is here, what to remove |
The workbench (/dashboard/code/[id]) | Editing, previewing and publishing |
/dashboard/code lists every project in the same way and is the quicker way in when you know you want to write
something rather than to organise something.
The workbench, panel by panel
| Panel | What it does |
|---|---|
| Chat | The conversation, with the project as its context |
| Editor | Monaco, with the project's files in a tree beside it |
| Preview | The running project, in a sandboxed frame |
| Terminal | A terminal for the project's own commands |
| Inspector | What changed, and the diffs waiting to be accepted |
| Deploy | Where and how to publish, including rollback |
| GitHub | Saving the project into a repository somebody owns |
| Database | A managed database, when the project needs one |
| Notifications | Builds and deployments, as they happen |
The layout is resizable, and the panels are resizable between themselves, which matters more than it sounds once somebody is working on a small screen.
How the preview exists
Two facts make the preview work without a server of anybody else's:
- The bundler is esbuild compiled to WebAssembly and run in a worker in the browser, which is why a project can be built without a build machine.
- The preview is a sandboxed frame, so a project with a mistake in it cannot reach into the product's own page.
The file public/vendor/esbuild.wasm is the bundler, written by scripts/vendor.mjs, which runs automatically
before pnpm dev. It is why an installation needs pnpm install to have run at least once before the workbench
is useful.
Diffs, and why they matter more than the chat
When the assistant writes, it proposes. The proposal arrives in the inspector as a diff, and:
- Accepting writes the file into the project.
- Refusing writes nothing and costs nothing.
- Accepting some and not others is a normal thing to do.
The version history beside it means a project can be rolled back to an earlier state, which is the second half of the safety story: nothing is lost by accepting the wrong change, as long as it was accepted knowingly.
Publishing a project
Choose a target
The deploy panel lists the targets this installation is configured for. Targets come from
Platform → Deployments and the integration cards in Platform → Integrations, so an installation that
offers none says so rather than failing at the last step.
Give it an address
A target usually wants a domain or subdomain. What a deployment ends up at, and whether it worked, is written
down in the deploy panel and again in Platform → Deployments, where the whole history lives.
Watch it happen
Builds and deployments report into the notifications panel rather than into a modal that disappears. A failure keeps its log.
Roll back when it is wrong
A previous deployment can be made current again from the deploy panel, which is the reason the history exists.
Saving the code somewhere permanent
The GitHub panel saves a project into a repository. It uses the installation's connect application, so the token
belongs to the person who connected it, and it can write only to repositories they chose. Whether the card is
offered at all depends on the two GITHUB_CONNECT_ names, which are read by the app:
the GitHub connect application.
A project is not a repository
A project lives in the installation's own storage, with its own version history. GitHub is an export that keeps working on its own, not the place a project is edited. Both are useful, and neither replaces the other.