Review and publish a CMS site

Move a CMS site from source to live delivery in separate steps. Green developer readiness confirms that authoring and preview work. It does not mean that a release has already been built or published.

If needed, configure the local host first with Set up a local storefront domain. This quickstart is complete when the live domain serves the deliberately published release and operations readiness reports no blockers.

Distinguish the states

State	Meaning	Next step
No build	The site can be edited and previewed, but no release exists yet.	Review the preview and start a build.
Build running	Workspace is creating an immutable release.	Wait for completion.
Build failed	The release was not created reliably. The status provides a redacted error code, `retryable`, and an attempt ID.	Check the recovery class; never rebuild or publish automatically.
Release unpublished	A build exists but is not live.	Review the release and publish it deliberately.
Release published	The selected release is live.	Check the live domain and operations readiness.
Live release incomplete	The active release has no complete runtime catalog, so Workspace blocks the entire release with HTTP `503`.	Build, review, and deliberately publish a new release.

When site-domain binding, DNS, and TLS are ready, Workspace returns an expected HTTP 404 instead of live content before the first publication. Treat 404 as a missing live release only in this case. Blocked domain, DNS, TLS, or binding checks indicate an infrastructure problem.

Move from preview to live

Open CMS > Sites and select the site.
Initialize an empty site once with the default kit.
Start a dev session and edit files on the Editor tab.
Generate a preview link and review the result.
Open the Releases tab and start the build.
Wait until the new release appears in the list.
Review the release and confirm Publish for that exact version.
Check the live domain and operations readiness.

A build never publishes automatically. A successful new build also leaves an existing live release unchanged until you publish explicitly.

Handle build failures safely

Keep the attemptId returned by the build request. nucli sites build <site-id> --wait accepts only a status for that attempt. When escalating, provide the attempt ID, failure.code, and failure.retryable, but do not include internal logs, file paths, or raw errors.

Failure codes	Meaning	Recovery
`SITE_BUILD_AUTHORING_REFRESH_FAILED`, `SITE_BUILD_REDIRECTS_FAILED`, `SITE_BUILD_ASSETS_FAILED`, `SITE_BUILD_RENDER_FAILED`, `SITE_BUILD_PUBLIC_FILES_FAILED`, `SITE_BUILD_ROUTING_FAILED`, `SITE_BUILD_DYNAMIC_ROUTES_FAILED`, `SITE_BUILD_SITEMAP_FAILED`, `SITE_BUILD_SEARCH_MANIFEST_FAILED`, `SITE_BUILD_IMAGES_FAILED`	An authoring-dependent build stage could not process the validated sources.	Revalidate the affected sources, then deliberately start a new build.
`SITE_BUILD_CAPACITY_UNAVAILABLE`, `SITE_BUILD_STORAGE_PREPARE_FAILED`, `SITE_BUILD_SOURCE_SNAPSHOT_FAILED`, `SITE_BUILD_STAGING_FAILED`, `SITE_BUILD_RELEASE_FINALIZE_FAILED`	An external build prerequisite was unavailable. These codes are marked `retryable`.	Have operations restore the documented capacity, storage, snapshot, staging, or release prerequisite. Only then deliberately start a new build.
`SITE_BUILD_RUNTIME_SNAPSHOT_FAILED`, `SITE_BUILD_RUNTIME_CATALOG_FAILED`, `SITE_BUILD_PRECOMPRESSION_FAILED`, `SITE_BUILD_PUBLISH_FAILED`, `SITE_BUILD_INTERNAL`	The failure requires product diagnostics or has no safe public recovery.	Escalate to the product team with the attempt ID. Do not retry or publish automatically.

retryable: true means only that another attempt may make sense after the external prerequisite has demonstrably recovered. A failed build leaves the current live release unchanged.

Navigation, page resolution, and the page feed belong to the immutable release. Editor changes therefore appear only in development and preview. They reach the live site only after a new build and an explicit publication.

After a product update, an older release without a complete runtime catalog may be blocked with HTTP 503 and ERR_SITE_RELEASE_RUNTIME_UNAVAILABLE. This is not a normal page error and does not require reverting authoring files. Build a new release, verify the release_runtime_ready check in the publish plan, and publish that exact version. Publishing rejects an incomplete target without switching the active live release.

Use preview links safely

The preview link expires with the selected review window. It is redeemed once in the intended browser and establishes preview access there. Do not test-open the link or call it automatically, because that consumes the handoff.

Never store concrete preview tokens in logs, tickets, screenshots, or documentation. Generate or copy a link only for the intended reviewer. A preview link does not publish the site.

Verify with `nucli`

bash

nucli --tenant <tenant> sites readiness <site-id>
nucli --tenant <tenant> web readiness <site-id>
nucli --tenant <tenant> sites build <site-id> --wait
nucli --tenant <tenant> sites build-status <site-id>
nucli --tenant <tenant> sites releases list <site-id>
nucli --tenant <tenant> sites inspect <site-id> --strict
nucli --tenant <tenant> sites publish plan <site-id> --release <release-id>
nucli --tenant <tenant> sites publish <site-id> --release <release-id>

sites readiness evaluates authoring and preview. Use inspect --strict only as a launch gate. web readiness evaluates domain, DNS, TLS, build, and live release. The publish plan is read-only: it may accept an unpublished release and a transition away from a blocked old live release when the selected target is runtime-ready. If the old release returns HTTP 503, this exception applies only when Workspace binds the response to the Site being probed and its active Site release. Diagnostic headers or HTTP 503 alone are insufficient. Other HTTP errors and infrastructure, release-read, or build failures remain blocking.

Approve mutating MCP calls

When an MCP agent performs this workflow, exactly these 13 Site and domain tools require the JSON Boolean approved: true in the same call:

nucleus_site_files_apply
nucleus_site_backup_save
nucleus_site_restore_apply
nucleus_site_dev_start
nucleus_site_preview_link_request
nucleus_site_dependencies_add
nucleus_site_dependencies_sync
nucleus_site_build
nucleus_site_publish
nucleus_tenant_domain_create
nucleus_tenant_domain_start_verification
nucleus_tenant_domain_verify_dns
nucleus_site_domain_bind

Approve only the concrete tool call and its complete payload. If approved is missing, false, null, or not a Boolean, nucli stops before file, secret, network, or server access. The field remains local and does not replace authentication, permissions, tenant binding, or Workspace validation. Read-only tools and the side-effect-free nucleus_site_validate and nucleus_site_restore_preview tools remain unchanged.

Verify the result

Publication is complete when web readiness reports no blockers, the selected release is marked live, and the live domain serves the reviewed content instead of the expected pre-publication 404.