# Maintenance & Recovery

> **Audience:** trusted Studio operators

Maintenance & Recovery is a production operations surface, but it ships
disabled. It is intentionally separate from normal administrator authorization
because it can export private database contents, recover accounts, delete data,
or change database lifecycle state.

## Enable the operations boundary

The Worker requires all three settings:

| Setting | Type | Requirement |
| --- | --- | --- |
| `STUDIO_OPERATIONS_ENABLED` | Plain variable | Exact value `true` |
| `STUDIO_OPERATIONS_ALLOWED_IPS` | Plain variable | Comma-separated exact IPv4 or IPv6 addresses; no CIDR ranges |
| `STUDIO_OPERATIONS_TOKEN` | Worker secret | 32–256 printable ASCII characters from `!` through `~`, without spaces or control characters |

Generate the operations token independently from the install token and auth
secret. If the feature is disabled or the caller's IP is not explicitly
allowed, `/system/operations` behaves as not found. Secret values are never
returned by the status API.

The page performs a tokenless availability check before rendering its sensitive
controls. Passing that check does not authorize an operation. The token and,
where required, an active administrator's credentials are verified by the
Worker for each protected workflow.

## Before any database operation

1. Identify whether the Studio DB or Edge DB is the target. Their backups and
   lifecycle state are independent.
2. Select the required [site mode](../site-modes/index.md) and deploy it.
3. Stop public writes that are outside Studio's control. In particular,
   maintenance mode does not stop the separate Edge Worker.
4. Create and retain the required reviewed SQL backup when the source database
   is readable.
5. Remember that D1 SQL backups do not contain R2 objects. Back up managed media
   separately.
6. Keep the operations token, exported SQL, account data, IP addresses, and MFA
   material confidential.

Studio does not automatically change the site mode, Edge feature gates, or Edge
integration mode when work completes.

## Studio database backup, restore, and upgrade

Studio exports deterministic logical SQL for the selected database. A
data-bearing artifact contains private application and authentication data; its
checksum verifies integrity but does not encrypt it.

- A readable Studio database can be exported in maintenance mode, including
  when its schema requires an upgrade.
- Maintenance-mode export and normal restore paths re-confirm an active
  administrator.
- Recovery mode uses the exact-IP and operations-token boundary when account or
  role data cannot be trusted.
- Restore is journaled and bounded. If it is interrupted, resume the same
  restore from the recorded progress rather than starting a competing one.
- A forward-only upgrade applies reviewed consecutive schema artifacts. Each
  committed version is the retry boundary after an interrupted response.

After an upgrade reports completion, return to `operational` and smoke-test
sign-in, MFA, Dashboard, important settings, content reads, and Preview Data.
Return to maintenance and retain the backup if any check fails.

## Edge database lifecycle

Edge owns its canonical schema contract; Studio contains a reviewed,
checksum-verified copy so Maintenance & Recovery can operate without reading a
sibling source repository at runtime.

The lifecycle action depends on the inspected state:

- **Install** accepts an otherwise empty Edge application catalog.
- **Adopt** accepts only an exact unversioned Edge v1 catalog and canonical
  initial seeds, then adds lifecycle state without changing business data.
- **Upgrade** applies the next reviewed, consecutive forward-only artifact.
- Partial, unexpected, malformed, in-progress, or newer-than-code state is not
  silently repaired.

The exact default-value comparison is specific to legacy adoption. After a
database is lifecycle-managed, legitimate Edge settings may differ from their
installation defaults while required row identities and schema constraints
remain valid.

`EDGE_KV` is not required for database lifecycle work. It is checked when the
operator later enables Studio's Edge integration.

## Edge target reconciliation

Reconciliation repairs the handoff between Studio Posts/Pages and Edge comment
targets without automatically deleting Edge-only data. It proceeds in bounded,
repeatable phases:

1. drain pending target-projection events;
2. upsert Studio Posts in public-ID order;
3. upsert Studio Pages in public-ID order;
4. scan Edge targets and snapshot orphans;
5. review and optionally purge selected orphans;
6. verify an empty outbox and exact target parity before finalizing.

An orphan purge deletes at most 100 selected targets per request. Immediately
before deletion, Studio rechecks that the target is still absent, that its
identity and mutable snapshot have not changed, and that the expected comment
count still matches. A successful target deletion cascades all of its comments.
Changed or revived targets are skipped.

Steps are idempotent and safe to retry after a lost response. Cancelling removes
only the Studio reconciliation journal and orphan snapshot; already completed
upserts remain. Reconciliation never enables Edge integration automatically.

Use this Edge runbook:

```text
stop public Edge feature gates
→ switch Studio to maintenance
→ export and retain an Edge SQL backup
→ install, adopt, or upgrade Edge DB as required
→ run reconciliation and review every orphan
→ return Studio to operational
→ enable Edge Services after health checks pass
→ reactivate public Edge feature gates
```

## Account recovery

Recovery mode can replace a selected administrator's password and mandatory MFA
material without creating a normal Studio session. Use it when the account
credentials or `STUDIO_AUTH_SECRET`-protected TOTP data cannot be used.

After recovery, Studio still does not change `STUDIO_SITE_MODE`. Switch to
`operational`, complete the required password and MFA flow, and verify access.
If the schema also requires an upgrade, recover the account first, then switch
to `maintenance` and follow the backup-and-upgrade runbook.

## Destructive operations

- **Clear site content** removes site content while preserving system settings
  and the intended non-content configuration. It may be available in
  operational or maintenance mode.
- **Reset Studio** removes site configuration and content while preserving the
  current administrator so the site can be configured again. It is
  maintenance-only.
- **Uninstall Studio** removes the Studio application schema and accounts. It
  is maintenance-only and does not delete R2 objects.

Each destructive operation uses an exact confirmation phrase, administrator
reconfirmation where applicable, and a final execution confirmation. Do not
infer success from a modal closing; wait for the completed result and preserve
its report.

To reinstall after uninstall, set `STUDIO_SITE_MODE=initial`, create a new
temporary install token, deploy the configuration, and use the normal installer.

## Close the maintenance window

1. Confirm the operation's final status and retain its report and backup.
2. Change `STUDIO_SITE_MODE` to `operational` and deploy.
3. Verify password + MFA sign-in and the application smoke tests relevant to the
   operation.
4. Re-enable public Edge gates only after Edge lifecycle and reconciliation are
   complete.
5. Disable the operations surface when it is not actively needed, or restrict
   its exact-IP allowlist and token according to the site's operational policy.