How work ships
How work ships
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. That guide stays authoritative, and specialist contracts must not describe a different path.
prompt → validated prompt-linked commit → Staging → Release Candidate → Production (Stable)
remote canary └→ optional PR Preview ┘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 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).
- Web runs this path on Railway. 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). 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).
Contributor loop
- Start from the latest
staging, confirmentire status, and create a short-lived remote canary branch. - Make one coherent, prompt-linked change, and push checkpoints promptly.
- Run
pnpm checkwhile working: TypeScript, lint with the UI-system gates, and repository-safe integration tests. - Run
pnpm verifybefore integration: it repeats the checks and creates the production build. - Open a change review, keep the Entire session context, and integrate into
staging. Ordinary staging integration needs no owner approval. - Verify the staging deployment: exact commit, deployment result,
/api/health, private access boundary, environment label, and browser behavior.
Release loop
- The owner reviews the staging outcome and explicitly directs creation of the Release Candidate.
- Freeze the reviewed commit on
releaseand promote the identical artifact. - Verify migrations, rollback, release notes, health, authorization, and user-visible behavior.
- Present the approval packet.
- Only explicit approval of the
release→mainrelease authorizes Production. - Verify the deployed commit or checksum, health, and live behavior before marking the release complete.
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
Environments
Preview, Staging, Release Candidate, and Production, and the promotion rules between them.
Staging topology
Apps under staging.exo.now; Pages under staging.construct.page.
Releases and changelogs
Stable N, internal versions, and the approval packet.
Approval boundaries
What never follows implicitly from a green build.
Source: content/docs/shipping/index.mdx
exo-router
Exo's smart model routing — one metered AI egress where an assessor scores each task, the utility function weighs capability against cost, and the Convex AI Gateway executes. Apps never hold provider keys.
Environments
Preview, Staging, Release Candidate, and Production — one purpose, one artifact, and one approval boundary each.