# How work ships

https://exo.now/docs/shipping

> The one promotion path every Exo-managed App uses — canary branch → Staging → Release Candidate → Production.



This section summarizes the canonical operating guide,
[How Exo builds and ships](../../../docs/build-and-deploy.md). That guide stays authoritative, and
specialist contracts must not describe a different path.

```text
prompt → validated prompt-linked commit → Staging → Release Candidate → Production (Stable)
             remote canary └→ optional PR Preview ┘
```

## The path in one minute [#the-path-in-one-minute]

| Stage             | Plain-language meaning                                           | Git source                                      | Who moves it forward                        | Required evidence                                                     |
| ----------------- | ---------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------- |
| Plan              | Decide what outcome matters and who owns the next action.        | Exo portfolio item                              | Product owner or operator                   | Scope, owner, priority, and acceptance criteria                       |
| Build             | Make one coherent change without disturbing shared environments. | Short-lived remote canary branch from `staging` | Developer or agent                          | Pushed prompt-linked commit and relevant checks                       |
| Staging           | Show the integrated change in a private, realistic environment.  | `staging`                                       | Automatic after validation                  | Deployed commit, passing gate, health, access, and browser review     |
| Release Candidate | Freeze the exact version proposed for release.                   | `release`                                       | Owner explicitly directs candidate creation | Reviewed staging evidence, manifest, migration and rollback readiness |
| Production        | Put the approved candidate in front of its intended audience.    | `main`, channel `stable`                        | Owner explicitly approves the release       | Identical artifact, approval record, health, and live behavior        |

Preview is optional and temporary. It never replaces Staging or shortens the release path. A local
checkout is an implementation tool, never a review surface.

## Every target, one path [#every-target-one-path]

Every environment has one purpose, one artifact, and an unmistakable human approval boundary.
Responsive websites, PWAs, and iPhone apps share one versioned delivery manifest, release
identity, approval model, and evidence contract, while keeping platform-specific configuration
([cross-platform delivery](../../../docs/platform-delivery.md)).

* **Web** runs this path on [Railway](../stack/deploy.mdx). The Staging → Release Candidate →
  Production path is live for web.
* **Mobile** apps follow the same path through Exo Deploy on Expo, from TestFlight to the app
  stores ([Deploy](../stack/deploy.mdx)). Exo Deploy is accepted (ADR 0007) and planned.
* **Delivery targets are typed.** Shared release identity and evidence live at the Exo layer, and
  provider specifics stay inside target adapters.
* **Drift never rewrites the contract.** Provider observations report whether the live target
  agrees with the declared manifest
  ([environment lifecycle](../../../docs/environment-lifecycle.md)).

<Steps>
  <Step>
    ### Contributor loop [#contributor-loop]

    1. Start from the latest `staging`, confirm `entire status`, and create a short-lived remote
       canary branch.
    2. Make one coherent, prompt-linked change, and push checkpoints promptly.
    3. Run `pnpm check` while working: TypeScript, lint with the UI-system gates, and
       repository-safe integration tests.
    4. Run `pnpm verify` before integration: it repeats the checks and creates the production build.
    5. Open a change review, keep the Entire session context, and integrate into `staging`. Ordinary
       staging integration needs no owner approval.
    6. Verify the staging deployment: exact commit, deployment result, `/api/health`, private access
       boundary, environment label, and browser behavior.
  </Step>

  <Step>
    ### Release loop [#release-loop]

    1. The owner reviews the staging outcome and explicitly directs creation of the Release
       Candidate.
    2. Freeze the reviewed commit on `release` and promote the identical artifact.
    3. Verify migrations, rollback, release notes, health, authorization, and user-visible behavior.
    4. Present the [approval packet](./releases.mdx#approval-packet).
    5. Only explicit approval of the `release` → `main` release authorizes Production.
    6. Verify the deployed commit or checksum, health, and live behavior before marking the release
       complete.
  </Step>
</Steps>

## Commands by intent [#commands-by-intent]

| Intent                                 | Command                   | Changes external state?                         |
| -------------------------------------- | ------------------------- | ----------------------------------------------- |
| Run the app locally                    | `pnpm dev`                | No provider change                              |
| Check an implementation                | `pnpm check`              | No                                              |
| Verify an integration candidate        | `pnpm verify`             | No                                              |
| Inspect credential and spend readiness | `pnpm delivery:gate`      | Read-only evidence only                         |
| Inspect provider resources and health  | `pnpm services:status`    | Read-only evidence only                         |
| Prepare a service change               | `pnpm services:plan-add`  | Creates a non-mutating local plan               |
| Apply an approved service plan         | `pnpm services:apply-add` | Yes; exact approval and execution gate required |

## In this section [#in-this-section]

<Cards>
  <Card title="Environments" href="/docs/shipping/environments" description="Preview, Staging, Release Candidate, and Production, and the promotion rules between them." />

  <Card title="Staging topology" href="/docs/shipping/staging" description="Apps under staging.exo.now; Pages under staging.construct.page." />

  <Card title="Releases and changelogs" href="/docs/shipping/releases" description="Stable N, internal versions, and the approval packet." />

  <Card title="Approval boundaries" href="/docs/shipping/approvals" description="What never follows implicitly from a green build." />
</Cards>