# 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](/api/publish).

## 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.

---

## Where this page sits

This is one page of the Clave documentation.
Read it as a web page at https://docs.heyclave.party/concepts/publishing.
Every page has a `.md` address, and https://docs.heyclave.party/llms.txt lists them all.

- Previous: [Site source](https://docs.heyclave.party/concepts/source.md)
- Next: [Drafts and slots](https://docs.heyclave.party/concepts/drafts.md)
- Index: [Overview](https://docs.heyclave.party/index.md)