# Orbit operations

Use this authoritative edition repository, Node 26.8.1 and pnpm 8.15.6. A clone contains the complete product source and portable authoring tool.

Create ignored `.seed/deployment/config.json` with Worker name, environment,
Cloudflare account ID and HTTPS origin. `pnpm setup` provisions or reuses its D1
and applies migrations. `pnpm deploy -- --owner-file /absolute/path/to/owner.json`
validates the owner and selected provider configuration, applies migrations,
bootstraps the first owner without customer samples, builds, checks resource
identity, uploads private secrets, deploys, and waits for `/health`. Repeat deploy
reuses the configured D1 and preserves data. Never commit that configuration,
owner file, session cookie, or secrets.

Native sign-in requires `MAIL_FROM` and `SENDGRID_API_KEY`. Customer outreach also
requires `MAIL_REPLY_TO` and `SENDGRID_UNSUBSCRIBE_GROUP_ID`. Configure the reply
address's SendGrid Inbound Parse route to `/api/v1/mail/events/reply` with its
`SENDGRID_PARSE_PUBLIC_KEY`. Delivery events can use native SendGrid signatures
at `/api/v1/mail/events/sendgrid` with `SENDGRID_WEBHOOK_PUBLIC_KEY`, or the pinned
Base event relay at `/api/v1/mail/events/relay` with `RER_MAIL_RELAY_SECRET`.
The relay must forward only this product's events. Do not replace another app's
provider webhook configuration. Email Activity access supports reconciliation of
unknown submissions without another send.

Signed signal sources need a persistent `ORBIT_ENCRYPTION_KEY` (32 random bytes,
64 hexadecimal characters) to encrypt their configured HMAC secrets in D1.
Configure sources in Settings/Sources; clients sign the exact raw request body
with the source's timestamp and HMAC as the source screen describes. Losing the
encryption key requires reconfiguring the source secrets; it does not erase data.

AI is optional. Set `OPENAI_API_KEY`, `AI_MODEL`,
`AI_INPUT_COST_PER_MILLION`, and `AI_OUTPUT_COST_PER_MILLION` to configure it.
`AI_CACHED_INPUT_COST_PER_MILLION` applies the selected cached-input rate. Without
that rate, estimates use the normal input rate and can overestimate. The operator
previews the exact request before generation; no AI request approves mail.

The Worker runs a minute Cron for scheduled dispatch, timed queue transitions,
retryable failures and reconciliation. Operator mutations evaluate pending changes
within their request. An ambiguous submission is reconciled by its durable key,
never blindly resent. Monitor visible message states, source diagnostics and
stale evaluations in the operator app. `/health` checks the D1 schema; provider
readiness and workflow outcome checks are separate.

Export and restore are available in Records. For an agent-controlled native
session, put only `__Host-orbit_session=...` in a private cookie file and run:

```sh
pnpm export -- --origin https://your-origin.example --session-file /private/orbit-cookie --file /private/orbit-export.json
pnpm import -- --origin https://empty-origin.example --session-file /private/orbit-cookie --file /private/orbit-export.json
```

The version 2 archive is a valid JSON document framed as bounded lines. The CLI
streams it to disk, verifies every part checksum, and publishes the private file
only after the closing record and manifest counts validate. Neither the CLI nor
the browser reads a complete archive into memory. Normal parts are at most 1,000
rows; the hard serialized-part limit is 16 MiB for large valid text records.

Each command prints its transfer ID. To resume, repeat the same command with
`--resume TRANSFER_ID` and the same archive path. Export keeps a private adjacent
`.transfer.json` checkpoint and `.partial` download until verified completion;
keep these files when interrupted. Download resume restarts the same immutable
prepared snapshot, while preparation resumes its bounded progress. Existing
completed files are never replaced. Import reads the selected file again and
verifies every previously uploaded part matches; a truncated or changed archive
cannot finalize. No ambiguous write is blindly retried by the CLI.

Records contains the same prepare, resume, download, restore and cancellation
controls. Copy the displayed transfer ID before closing a browser that cannot
retain session storage. Export takes a consistent atomic snapshot before serializing its parts; workspace
edits can continue during preparation or while preparation is paused. Discard an
unneeded snapshot in Records. Pausing a restore keeps its protected state; cancel and roll back waits
for confirmed restoration of the original empty target before unlocking it.
Prepared snapshots remain private server data until explicitly discarded.

Import requires an empty customer database and preserves domain records. Source
secrets and session credentials are intentionally excluded. Successful restore
revokes sessions; sign in again and configure source secrets separately. Export
files contain private customer data. Export/import/export equivalence and
migration recovery are tested with isolated real D1.

`pnpm verify` writes actual clause execution results and blocks uncovered, failed,
or skipped clauses. Read [ACCEPTANCE.md](ACCEPTANCE.md) for additional provider,
capacity, deployment and owner-change requirements. `node scripts/operations.mjs
check` only validates local inputs; it does not deploy or certify remote health.