Publishing

Publishing builds the site's source and puts the output live.

What a deployment is

A deployment is one set of files, with the commits it was built from. It has a status, and when it goes live it has an address.

A site has at most one live deployment. Activating a new one supersedes the last.

Two ways to publish

• POST /v1/sites/{id}/publish builds the source and activates the result. This is what an agent uses.
• The manifest flow uploads files the agent already has, with no build. Read The publish contract.

Scope

A publish has a scope.

• site builds the head of both repositories. This is the default.
• posts builds the live site's own commit with the posts as they are now.

posts is what lets a post go live while a redesign sits half done.

It also changes what a build failure means. A posts publish builds the live site's commit, so a change you just made to the site's code is not in the tree that failed. The compiler blames a version you are not looking at, and Clave says so in the message.

The build

Clave builds the source in a sandbox with no network. The sandbox runs the site's own code — astro.config.mjs and every component's frontmatter — so it holds nothing worth stealing.

A build failure carries a detail field with the build log. That log is the compiler telling whoever wrote the source what is wrong with it. It is the only place a detail field appears.

A failure of any other kind is Clave's, and it carries no build log.

Restore

Clave keeps every byte it ever published. A restore is one call and needs no upload: POST /v1/deployments/{id}/restore puts an earlier deployment back on the address.

That is what makes the archive worth holding. Cloudflare serves the files; Clave holds them.

What happens if Clave is down

A published site is served by Cloudflare and does not depend on this API. An outage here stops deploys and reads. It does not take a site down.