Install a blueprint

An install runs in four steps. The first two write nothing at all, and the third is where you decide. In the dashboard the whole walk is Blueprints → Install a blueprint: paste or upload the document, answer its questions, read the plan, tick what you accept, and install. Through the API it is the same four steps as endpoints.

#What you need first

To do this	You need
Validate a document	Any signed-in account
Plan one against a project	system/blueprints:read
Open an install, settle it, uninstall it	system/blueprints:install

Both permissions are seeded to the admin role and can be granted to any other role from the role editor.

An install needs a person. A service API key — one with nobody behind it — is refused before anything is read, because an install runs as the installer and the resources it creates are owned by them. Use a delegated key or the dashboard.

#1. Validate

Validation asks one question: can this platform read this document? It parses the front matter, the prose and every brick, and reports what is wrong with line numbers and brick ids attached. It reads nothing about your project and writes nothing, so it is safe to run against a document you have not decided about.

A document that does not read is not a broken request — you get the list of diagnostics back, each with a stable code you can look up on Reference. That distinction is what makes an authoring loop possible: fix the document, run it again.

#2. Plan

The plan is where a document meets your project. It compiles every brick, checks each call it would make against your permissions before making any of them, reads the current state of everything it would touch, and returns a verdict per brick.

It also answers the question that only your project can: has some of this been installed before? A previous install's ledger rows are the baseline, so the plan can tell a resource this blueprint made from one you made by hand.

Three things a plan tells you that are easy to miss:

• Missing secrets. A secret parameter's value never appears in a document, never reaches a plan and is never stored. The plan tells you which ones the install will still need from you.
• A permission you lack. The pre-flight is done against your own grants, so a call you could not make is reported now rather than halfway through an install with four resources already created.
• Not installable. If any brick comes back BLOCKED, the whole plan is refused for execution. A blocked brick is the plan declining to guess; the reason is named.

#Reading the verdicts

Verdict	What it means	Needs your tick
CREATE	Nothing like it exists. It will be made.	No
NOOP	This blueprint already made it and it still matches. Nothing to do.	No
ADOPT	It exists and matches, but no install claims it — made by hand, or left behind by an earlier uninstall. Accepting claims it without changing it.	Yes
UPDATE	The document changed it and you have not touched it. A clean apply.	No
DRIFT	You changed it and the document did not. Your edits are kept unless you ask for a reset.	Yes, to reset
CONFLICT	Both changed. Never merged: yours is kept unless you tick.	Yes, to reset
ORPHAN	This blueprint made it and the document no longer mentions it. Removal is offered, never done for you.	Yes
SKIPPED	It belongs to a group you declined. Nothing is emitted for it.	—
BLOCKED	The plan will not guess. Nothing installs until it is resolved.	—

The reasons a brick can be BLOCKED, and what to do about each, are on Reference. The commonest one by far is an update to a kind that cannot be updated — see Update and uninstall.

#3. Consent

The plan is the thing you approve. It is presented as the document's own groups — an assembly is a set of bricks the author bundled as one choice — with the ones the author marked required already on and the optional ones yours to decline. Declining a group is a real choice with real consequences, and a well-written document says what they are.

One rule overrides everything else on this screen: a grants brick is never applied without a tick, whatever its verdict and whatever else you accepted. A permission the blueprint hands out is a door it opens, and opening one is never a side effect of something else you agreed to.

Nothing has been written when you reach this screen. Closing the tab here leaves your project exactly as it was.

#4. Execute

Executing turns the consented plan into ordinary API calls — one per brick, in the order the document's dependencies require, each one made as you and checked by that route's own permission rules. There is no privileged path: a blueprint's install is a sequence of calls you could have made yourself.

As it goes, the install ledger records what actually happened, and it does not take the client's word for it. Each resource is recorded as pending before the call, and settled afterwards from the server's own read-back of the resource it finds. What lands in the ledger is what the server could see, not what the installer claimed — which is what makes the next plan's baseline worth comparing against. See the install ledger.

#If an install stops halfway

A closed tab or a killed terminal reports nothing, so nothing on the request path can close a run. The hourly maintenance tick finds runs left open, records the resources nobody read back as failed with an unknown outcome rather than inventing a result for them, and closes the run as partial. The bricks that did land keep their verified rows.

You recover by planning the same document again: the resources that landed come back as NOOP, anything created but never recorded comes back as ADOPT, and the rest as CREATE. Nothing has to be cleaned up by hand first.