# Site Modes

> **Audience:** Studio operators

`STUDIO_SITE_MODE` is a Worker deployment setting, not a Studio database value
or site-content preference. Studio accepts exactly four values. A missing or
unknown value fails closed.

| Mode | Intended use | Normal sign-in and product APIs | Maintenance & Recovery |
| --- | --- | --- | --- |
| `initial` | Install a new Studio database | Blocked | Installer only |
| `operational` | Normal authoring and administration | Available when the schema is current | Limited operational actions may be available |
| `maintenance` | Planned backup, schema lifecycle, reconciliation, reset, or uninstall | Blocked before product D1 access | Maintenance workflows |
| `recovery` | Out-of-band account or database recovery | Blocked before product D1 access | Recovery workflows |

## `initial`

Use `initial` only with an uninstalled Studio database, a valid temporary
`STUDIO_INSTALL_TOKEN`, and the permanent `STUDIO_AUTH_SECRET`. It exposes the
first-administrator installation flow.

Installation never changes this setting. After a successful install, remove the
install-token binding, change the mode to `operational`, and deploy the new
configuration. Keeping an install token after installation is treated as an
invalid lifecycle configuration rather than a reusable installer.

## `operational`

Use `operational` for normal sign-in, content work, settings, imports, and
Preview Data generation. It does not override database compatibility:

- an uninstalled database remains blocked;
- an older supported schema reports that an upgrade is required;
- an in-progress, malformed, or newer-than-code schema remains unavailable.

When an upgrade is required, first switch to `maintenance`. A button that merely
opens Maintenance & Recovery cannot make upgrade controls available while the
Worker remains operational.

The operations surface may expose **Clear site content** in operational mode,
but reset, uninstall, schema upgrade, Edge lifecycle, and reconciliation remain
maintenance-only.

## `maintenance`

Use `maintenance` for planned work that requires the normal Studio application
to stop. The global API gate rejects ordinary product routes before querying
the product database. Existing browser sessions do not bypass this boundary.

Maintenance is the required mode for:

- Studio DB forward-only upgrades;
- Edge DB install, explicit legacy adoption, and forward-only upgrades;
- Edge target reconciliation and orphan review;
- Reset Studio and Uninstall Studio;
- maintenance-mode database backup and supported restore workflows.

The separately deployed Edge Worker is not stopped by this mode. Disable its
`COMMENTS_ENABLED`, `FORMS_ENABLED`, and `NEWSLETTER_ENABLED` hard gates before
Edge database maintenance.

## `recovery`

Use `recovery` when normal account authentication or Studio database state is
the thing being repaired. Normal login and product APIs remain blocked. Access
uses the separately configured operations token and exact-IP boundary rather
than creating a regular Studio session.

Recovery can support administrator password/MFA recovery and appropriate SQL
restore paths. It does not expose Reset Studio or Uninstall Studio, and Edge DB
lifecycle or target reconciliation still requires `maintenance`.

## Typical transitions

```text
new deployment
  initial → install → remove install token → operational

planned schema work
  operational → maintenance → backup → upgrade → operational smoke test

lost administrator access
  operational → recovery → recover account → operational

lost access plus outdated schema
  recovery → recover account → maintenance → backup and upgrade → operational
```

No Studio button performs these mode transitions. The operator changes the
Worker configuration and deploys it explicitly.