Project States

A Project state tells you what is happening now and what the next useful action is. You will see these labels on Project cards, in the Project Workspace header, and in the Graph summary.

Project states are not logs. They are user-facing signals: wait, review, resolve, resume, publish, or keep iterating.

How to read Project states

Most states answer one question: what should I do next?

• If a state is active, like Building or Testing, wait for Castaly to finish.
• If a state needs a decision, like Plan ready or Needs your input, open Chat and respond.
• If a state is blocked, like Build blocked or Configuration required, clear the blocker before continuing.
• If a state is ready, like Preview ready or Ready to publish, move to the next step when the result looks right.

Some internal states are simplified before they reach the UI. For example, validation or Spec updates may still appear as Build ready because the next user action is the same: review the Project and start Build when ready.

Setup states

State	What it means	What to do next
Preparing	Castaly is creating the Project and preparing the initial Spec and Graph.	Wait for setup to finish.
Setup failed	Castaly could not finish the initial Project setup. This is not a Build failure.	Retry setup if available, or check the failure message in Chat.
Needs your input	Castaly is waiting for your answer or decision before it can continue.	Open Chat, review the question, and reply.

Build states

State	What it means	What to do next
Build ready	The Project can move into Build. This can also appear after you change the Spec or add feedback that needs a new Build.	Press Build when the Spec and Graph look right.
Plan ready	A Build Plan is waiting for your review.	Accept the plan to start implementation, or keep editing first.
Build blocked	Castaly found a Spec conflict or blocker that must be resolved before Build can continue.	Resolve it in Chat, then run Build again.
Building	Castaly is implementing the accepted Build Plan.	Wait for the build to progress.
Testing	Castaly is testing, verifying, or auto-repairing the implementation.	Wait for checks to finish.
Build failed	Implementation failed before the Project reached a usable Preview.	Use the recovery action shown in the workspace, such as Retry or Continue Build.
Tests failed	Automated tests failed during Build.	Use the recovery action shown in the workspace. Castaly can usually continue from the failed point.

Preview states

State	What it means	What to do next
Deploying preview	Castaly is preparing or restoring the Preview. This can happen after Build, after retrying Preview, or after resuming an expired Preview.	Wait for the Preview result.
Preview ready	The Preview is live and ready to test.	Open Preview, test the main flows, and send feedback if needed.
Preview expired	The Preview link expired, but the build result can be restored.	Use Resume to restore the Preview.
Preview failed	Castaly could not prepare or restore the Preview.	Retry the Preview action or follow the recovery shown in the workspace.
Configuration required	The Preview exists, but a required runtime secret is missing. Preview can still run; Publish is blocked.	Use Set up to add the missing runtime secret.

Publish states

State	What it means	What to do next
Ready to publish	The current Preview can become a formal published version.	Press Publish when the Preview matches your intent.
Publishing	Castaly is creating and deploying the published Project Version.	Wait for Publish to finish.
Publish failed	Castaly could not finish publishing the Project Version.	Retry Publish after reviewing the failure message.
Published	A formal Project Version exists and the Project has a stable published site.	Open View site, share the URL, or continue iterating on the Project.

Published does not mean the Project is closed. You can keep editing the live Project. Later changes do not alter the published version until you publish again.

Where states appear

🏷️Project status

The Project card and workspace header show the whole-Project state, from Preparing to Published.

🗂️Graph summary

The Graph summary mirrors the Project stage while you inspect structure and build progress.

🖥️Preview toolbar

The Preview tab can also show Preview-specific state, such as active, expired, failed, or configuration required.

Project state vs node state

Project state describes the whole Project. Node state describes one Page or Feature on the Graph.

🏷️Project state

The overall stage of the Project: Build ready, Building, Preview ready, Published, and so on.

🔵Node state

The build progress for a specific Page or Feature: Queued, Building, Testing, Succeeded, Blocked, or Build failed.

💬Chat state

Questions, process history, failure cards, and recovery actions live in Chat when a state needs more detail.

Use the Project state to know where the whole Project stands. Use node state when you need to see which part of the Graph is still building, blocked, or failed.

Next: Resolve Blockers covers what to do when a project stalls.