diff --git a/.docker/dockerfile.dev b/.docker/dockerfile.dev
index e8bed392..b72e629d 100644
--- a/.docker/dockerfile.dev
+++ b/.docker/dockerfile.dev
@@ -15,6 +15,7 @@ COPY packages/config/tsconfig.base.json ./packages/config/
 COPY packages/db/package.json ./packages/db/
 COPY packages/email/package.json ./packages/email/
 COPY packages/env/package.json ./packages/env/
+COPY packages/instance-config/package.json ./packages/instance-config/
 COPY packages/ui/package.json ./packages/ui/
 
 RUN bun install --frozen-lockfile --ignore-scripts
diff --git a/.env.example b/.env.example
index 2af77b0b..a753bd5a 100644
--- a/.env.example
+++ b/.env.example
@@ -13,6 +13,8 @@
 POSTGRES_PASSWORD=password
 # Signs session cookies, encrypts two-factor secrets and backup codes, and signs the bank connection state.
 BETTER_AUTH_SECRET=dev_secret_change_me_at_least_32chars
+# The setup token that claims an unclaimed instance on the setup screen. Unset, the server makes a new token at each start and prints it in its log.
+# FREENARY_SETUP_TOKEN=choose_a_long_random_value_of_32_or_more_characters
 
 # --- Public origins and cookies ---
 # The origins a browser reaches. Both default to localhost outside production,
diff --git a/apps/fumadocs/content/docs/next/contributing/data-model.mdx b/apps/fumadocs/content/docs/next/contributing/data-model.mdx
index 643e523b..7b2e29d8 100644
--- a/apps/fumadocs/content/docs/next/contributing/data-model.mdx
+++ b/apps/fumadocs/content/docs/next/contributing/data-model.mdx
@@ -8,7 +8,7 @@ This page owns the vocabulary of the schema. Every model name, column name and e
 
 ## Where the schema lives
 
-Prisma reads a directory, not one file. Five files split the model by area.
+Prisma reads a directory, not one file. Six files split the model by area.
 
 <Files>
   <Folder name="packages/db" defaultOpen>
@@ -19,9 +19,10 @@ Prisma reads a directory, not one file. Five files split the model by area.
         <File name="budget.prisma" />
         <File name="budget-profile.prisma" />
         <File name="assistant.prisma" />
+        <File name="instance.prisma" />
       </Folder>
       <Folder name="migrations">
-        <File name="7 migration directories, migration_lock.toml, .gitkeep" />
+        <File name="12 migration directories, migration_lock.toml, .gitkeep" />
       </Folder>
     </Folder>
     <File name="prisma.config.ts" />
@@ -49,7 +50,7 @@ Two places supply the URL. `packages/db/prisma.config.ts` hands `process.env.DAT
 
 | Model and table | Key fields | Constraints and notes |
 | --- | --- | --- |
-| `User`, table `user` | `id`, `name`, `email`, `emailVerified` (`false`), `twoFactorEnabled` (`false`), `image?`, `taxCountries String[]`, `onboardingCompletedAt?`, `createdAt`, `updatedAt` | `@@unique([email])`. Ten child relations, each with a cascade delete |
+| `User`, table `user` | `id`, `name`, `email`, `emailVerified` (`false`), `twoFactorEnabled` (`false`), `image?`, `taxCountries String[]`, `onboardingCompletedAt?`, `role UserRole` (`MEMBER`), `createdAt`, `updatedAt` | `@@unique([email])`. Ten child relations, each with a cascade delete. Better Auth never writes `role` |
 | `Session`, table `session` | `expiresAt`, `token`, `ipAddress?`, `userAgent?`, `userId` | `@@unique([token])`, `@@index([userId])`, cascade |
 | `Account`, table `account` | `issuer`, `accountId`, `providerId`, `userId`, `accessToken?`, `refreshToken?`, `idToken?`, `accessTokenExpiresAt?`, `refreshTokenExpiresAt?`, `scope?`, `password?` | `@@unique([issuer, accountId], map: "account_issuer_accountId_uidx")`, `@@index([userId])`. The credential and OAuth link table, never a bank account. The password hash sits in `password` |
 | `Verification`, table `verification` | `identifier`, `value`, `expiresAt` | `@@index([identifier])`. No user column and no foreign key |
@@ -156,9 +157,20 @@ The colour a subcategory shows is the stored colour of its parent, through `cust
 
 The `ordinal` column orders a conversation and `createdAt` cannot, because both rows of one turn can share a millisecond. The `parts` column holds the AI SDK message parts as the stream wrote them. So a stored answer replays with its lookup rows intact.
 
+## Instance configuration
+
+`instance.prisma` holds what an operator sets in the setup screen, and the claim that names the operator. Neither model has a user relation, and neither one cascades.
+
+| Model and table | Key fields | Constraints and notes |
+| --- | --- | --- |
+| `InstanceSetting`, table `instance_setting` | `key` (`@id`), `sealed`, `updatedAt`, `updatedBy?` | One row per environment variable the screen owns. `sealed` is AES-256-GCM ciphertext under a key derived from `BETTER_AUTH_SECRET`, with the row `key` as associated data. `updatedBy` holds a `User.id` and carries no foreign key, so deleting the operator leaves the row |
+| `InstanceSetup`, table `instance_setup` | `id` (`@id`, default `singleton`), `tokenHash?`, `claimedAt?`, `completedAt?`, `createdAt` | At most one row, for the whole setup lifecycle. `tokenHash` is the SHA-256 hex digest of the setup token, printed at start or read from `FREENARY_SETUP_TOKEN`, and the claim clears it. `claimedAt` marks the instance as owned; `completedAt` marks the wizard as finished, which is what stops the web app sending every visitor to `/setup` |
+
+The claim is one `updateMany` on `instance_setup`, matched on the hash and on `claimedAt: null`, inside the transaction that sets `User.role`. That conditional update is the lock. A second caller matches no row and is refused, so two callers cannot both become the operator.
+
 ## Enums
 
-PostgreSQL holds exactly three enum types. Every value below is verbatim, in declaration order.
+PostgreSQL holds exactly five enum types. Every value below is verbatim, in declaration order.
 
 ### `BankConnectionStatus`
 
@@ -207,6 +219,29 @@ The last column is `isInvestmentAccountType`, a TypeScript lookup in `packages/a
 | `USER`      | The question of the reader |
 | `ASSISTANT` | The answer                 |
 
+### `UserRole`
+
+`User.role` uses it, with the column default `MEMBER`.
+
+| Value | Meaning |
+| --- | --- |
+| `MEMBER` | The ordinary account. It reaches its own rows alone |
+| `OPERATOR` | The account that claimed the instance. It opens the setup screen, and it reads no financial row of another user |
+
+One `user.update`, inside the claim transaction, is the only writer of `OPERATOR`. No endpoint writes the value back to `MEMBER`.
+
+### `SyncPhase`
+
+`SyncRun.phase` uses it, and the column has no default.
+
+| Value | Meaning |
+| --- | --- |
+| `IMPORTING` | The run is reading accounts and transactions from the providers |
+| `CATEGORISING` | The import finished, and the run is resolving categories |
+| `FINISHED` | The run ended. `SyncRun.finishedAt` holds the moment |
+
+One row per user, keyed by `userId`. A user therefore has one sync run at a time, and a new run replaces the last one.
+
 ### The dropped enum
 
 `BudgetLineKind` was a fourth type with the values `REVENUE`, `INVESTMENT` and `OUTGOING`. The migration `20260904120000_derive_budget_line_kind` dropped the type together with the column `budget_line.kind`. The three names survive as a TypeScript union, and `budgetLineKindOf` derives the value from the group of a category. One group maps to each name: `income` to `REVENUE`, `investments` to `INVESTMENT` and `spending` to `OUTGOING`.
diff --git a/apps/fumadocs/content/docs/next/quickstart.mdx b/apps/fumadocs/content/docs/next/quickstart.mdx
index abff5f95..532178bb 100644
--- a/apps/fumadocs/content/docs/next/quickstart.mdx
+++ b/apps/fumadocs/content/docs/next/quickstart.mdx
@@ -87,16 +87,7 @@ The console work takes four steps, and [Bank providers](/docs/self-hosting/bank-
 3. Create a client application, and register `<CORS_ORIGIN>/callback/powens` as its redirect URI.
 4. Activate the connectors of the banks you want. A domain with no active connector answers with an empty list.
 
-Write the credentials into the same `.env` file:
-
-```dotenv
-BANKING_PROVIDER=powens
-POWENS_DOMAIN=acme-sandbox
-POWENS_CLIENT_ID=<client id>
-POWENS_CLIENT_SECRET=<client secret>
-```
-
-A later change of these values needs `docker compose up -d`. Compose recreates the `server` container with the new environment, and no image rebuild happens.
+Keep the domain, the client id and the client secret to hand. They go into the setup screen after the first start, and not into the `.env` file.
 
 </Step>
 
@@ -139,7 +130,25 @@ Open `http://localhost:3001` in a browser. The screen reads `Welcome to Freenary
 
 With no email provider configured, Freenary signs you in at once and opens the onboarding wizard. With one configured, the screen moves to `Confirm your email` and asks for the 6-digit code it sent you. That code lives 10 minutes. Freenary signs you in after you enter it.
 
-Freenary has no admin account and no owner role. The first account is an ordinary user.
+</Step>
+
+<Step>
+
+### Claim the instance, then add the credentials
+
+The first account is an ordinary user until it claims the instance. Freenary opens `/setup` for it. Read the setup link from the server log:
+
+```bash
+docker compose logs server | grep "setup token"
+```
+
+Open the link, and press `Claim`. The link puts the token into the field for you. That account becomes the operator of this instance, and no second account can take the role.
+
+Now go to the **Bank provider** step, pick `Powens`, and press `Continue`. Type the three values from the console, and press `Save and continue`. Freenary calls your Powens domain with the credentials, and saves them when the call succeeds.
+
+Go to the last step, and press `Finish setup`. The server restarts to use the credentials, and the page opens the app when the server is back.
+
+[The setup screen](/docs/self-hosting/setup) holds each card, each check and the last step in full.
 
 </Step>
 
@@ -149,6 +158,7 @@ Freenary has no admin account and no owner role. The first account is an ordinar
 
 - You are signed in to your own instance.
 - Your account sits in the PostgreSQL database of that instance.
+- You are the operator of the instance, so `/setup` opens for you and for nobody else.
 - **Settings** lists the banks of your tax residencies, because the credentials of the provider are set.
 - No bank is connected, so the Budget screen asks you to connect one.
 
@@ -170,6 +180,11 @@ Freenary has no admin account and no owner role. The first account is an ordinar
     href="/docs/self-hosting"
     description="Public origins, real secrets, and the checks that prove them."
   />
+  <Card
+    title="The setup screen"
+    href="/docs/self-hosting/setup"
+    description="Change a provider, check its credentials, and apply them."
+  />
   <Card
     title="Configuration reference"
     href="/docs/self-hosting/configuration"
diff --git a/apps/fumadocs/content/docs/next/self-hosting/backup-and-restore.mdx b/apps/fumadocs/content/docs/next/self-hosting/backup-and-restore.mdx
index 75a573d9..e89782fb 100644
--- a/apps/fumadocs/content/docs/next/self-hosting/backup-and-restore.mdx
+++ b/apps/fumadocs/content/docs/next/self-hosting/backup-and-restore.mdx
@@ -201,18 +201,19 @@ Type the `-p freenary-restore-check` flag in the `down -v` command. Without it,
 
 ## What a dump does not hold
 
-A database dump holds no configuration. The root `.env` file sits on the host, next to `docker-compose.yml`. It is outside every volume, and `.dockerignore` keeps every `.env` file out of the image layers.
+A dump holds what [the setup screen](/docs/self-hosting/setup) saved. It holds nothing from the `.env` file, which sits on the host next to `docker-compose.yml`. It is outside every volume, and `.dockerignore` keeps every `.env` file out of the image layers.
 
 | Not in the dump | What you lose without it |
 | --- | --- |
-| `BETTER_AUTH_SECRET` | Every session, and every two-factor enrolment in the restored data |
+| `BETTER_AUTH_SECRET` | Every session, every two-factor enrolment, and every row of `instance_setting` |
 | `POSTGRES_PASSWORD` | Access to the volume the old container created with it |
-| The bank provider credentials | The bank sync of every user |
-| The email provider credentials | One-time code delivery, and therefore password reset |
+| A provider credential set in `.env` | The bank sync, or the one-time code delivery, of that adapter |
+
+The `instance_setting` table is in the dump. A provider credential typed into the setup screen therefore comes back with the data. Each row is sealed with a key made from `BETTER_AUTH_SECRET`, and opens under that secret alone.
 
 <Callout type="error">
 
-Keep `BETTER_AUTH_SECRET` with the dump. That one value signs the session cookie, and it encrypts the `secret` and `backupCodes` columns of the `two_factor` table. It also signs the bank connection state that round-trips through the provider. A restore under a new secret signs every user out and breaks every two-factor enrolment.
+Keep `BETTER_AUTH_SECRET` with the dump. That one value signs the session cookie, and it encrypts the `secret` and `backupCodes` columns of the `two_factor` table. It also seals every `instance_setting` row, and signs the bank connection state that round-trips through the provider. A restore under a new secret signs every user out and breaks every two-factor enrolment. It also turns off every provider the setup screen configured.
 
 </Callout>
 
diff --git a/apps/fumadocs/content/docs/next/self-hosting/bank-providers.mdx b/apps/fumadocs/content/docs/next/self-hosting/bank-providers.mdx
index ab2bfa33..963f2af7 100644
--- a/apps/fumadocs/content/docs/next/self-hosting/bank-providers.mdx
+++ b/apps/fumadocs/content/docs/next/self-hosting/bank-providers.mdx
@@ -12,6 +12,8 @@ Freenary never talks to a bank itself. A bank provider holds that connection, an
 
 An unknown value fails the environment check at startup. A known value with no credentials turns bank linking off rather than half on.
 
+An operator sets the provider and its credentials in [the setup screen](/docs/self-hosting/setup), not only in `.env`. The screen calls the provider with the credentials before it saves them. A value already set in the environment wins, and the screen marks it read-only.
+
 **Choose Powens unless you have a reason not to.** It is the default, and it is the only adapter that imports accounts, balances and holdings. [Powens](#powens) below walks the console setup step by step. A sandbox domain costs nothing and needs no contract.
 
 ## The two adapters
diff --git a/apps/fumadocs/content/docs/next/self-hosting/configuration.mdx b/apps/fumadocs/content/docs/next/self-hosting/configuration.mdx
index c2758858..22827630 100644
--- a/apps/fumadocs/content/docs/next/self-hosting/configuration.mdx
+++ b/apps/fumadocs/content/docs/next/self-hosting/configuration.mdx
@@ -28,11 +28,24 @@ The development stack reads the same file, and the file is optional there. `dock
 
 `migrate` gets one key, `DATABASE_URL`. `postgres` gets three: `POSTGRES_DB`, `POSTGRES_USER` and `POSTGRES_PASSWORD`.
 
+## Where a value can be set
+
+Some of these variables also live in [the setup screen](/docs/self-hosting/setup). An operator types them into a form there, instead of into the file:
+
+| Integration | Variables the screen owns |
+| --- | --- |
+| Bank provider | `BANKING_PROVIDER`, `POWENS_DOMAIN`, `POWENS_CLIENT_ID`, `POWENS_CLIENT_SECRET`, `ENABLE_BANKING_APP_ID`, `ENABLE_BANKING_PRIVATE_KEY` |
+| Email delivery | `EMAIL_PROVIDER`, `EMAIL_FROM`, `RESEND_API_KEY`, `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`, `SMTP_PASSWORD` |
+
+**A value in the environment wins.** The server reads a variable from the environment first, and falls back to the row the screen wrote. A line in `.env` therefore makes the matching field read-only, and the screen names the variable the environment owns.
+
+Every other variable on this page comes from the environment alone.
+
 ## How the server checks its environment
 
 {/* env-sync:start count */}
 
-The API server checks its environment once, at startup. The schema is [`packages/env/src/schema.ts`](https://github.com/suiramdev/freenary/blob/main/packages/env/src/schema.ts). It declares 48 variables with Zod, and `packages/env/src/server.ts` hands them to `@t3-oss/env-core`. The reference below, and `.env.example`, are generated from that one file.
+The API server checks its environment once, at startup. The schema is [`packages/env/src/schema.ts`](https://github.com/suiramdev/freenary/blob/main/packages/env/src/schema.ts). It declares 49 variables with Zod, and `packages/env/src/server.ts` hands them to `@t3-oss/env-core`. The reference below, and `.env.example`, are generated from that one file.
 
 {/* env-sync:end */}
 
@@ -101,6 +114,7 @@ Outside production the same text is a `console.warn` line. Compose always sets `
 | Variable | Default | What it does | Absent or wrong |
 | --- | --- | --- | --- |
 | `BETTER_AUTH_SECRET` | `dev_secret_change_me_at_least_32chars` outside production, required in production | Signs session cookies, encrypts two-factor secrets and backup codes, and signs the bank connection state. | Under 32 characters stops the start. The development default applies outside production alone, so a production start with no value stops. |
+| `FREENARY_SETUP_TOKEN` | unset | The setup token that claims an unclaimed instance on the setup screen. Unset, the server makes a new token at each start and prints it in its log. | Under 32 characters, or a character other than a letter, a digit, `-` or `_`, stops the start. After the claim the server ignores the value. |
 | `NODE_ENV` | `development` | Picks the runtime mode: `development`, `production` or `test`. | `production` drops the log file drain and turns the cookie warning into a refusal. `test` turns the sign-in rate limits off. Compose always sets `production`. |
 | `PORT` | `3000` | The port the API server listens on. It also fills the `BETTER_AUTH_URL` default. | A non-digit character stops the start. In the Docker stack it must stay `3000`, because the healthcheck fetches port 3000 inside the container. Never put it in the root `.env` file, which the `server` service loads whole. |
 
diff --git a/apps/fumadocs/content/docs/next/self-hosting/email.mdx b/apps/fumadocs/content/docs/next/self-hosting/email.mdx
index 4a211fb3..34998433 100644
--- a/apps/fumadocs/content/docs/next/self-hosting/email.mdx
+++ b/apps/fumadocs/content/docs/next/self-hosting/email.mdx
@@ -26,6 +26,8 @@ Freenary checks `EMAIL_FROM` before `SMTP_HOST`. A stack that sets neither there
 
 [Configuration](/docs/self-hosting/configuration) defines every variable named here.
 
+An operator sets these values in [the setup screen](/docs/self-hosting/setup), and not only in the `.env` file. The screen opens the connection and signs in before it saves. A wrong password is therefore refused at the form, and not at the first one-time code. A value already set in the environment wins, and the screen marks it read-only.
+
 ## What stops with no adapter
 
 These sign-in paths still work: email and password, passkeys, and two-factor with an authenticator app.
diff --git a/apps/fumadocs/content/docs/next/self-hosting/index.mdx b/apps/fumadocs/content/docs/next/self-hosting/index.mdx
index 155d313c..4613ff5b 100644
--- a/apps/fumadocs/content/docs/next/self-hosting/index.mdx
+++ b/apps/fumadocs/content/docs/next/self-hosting/index.mdx
@@ -108,7 +108,7 @@ Put your own hostnames in the last two lines. The API server refuses a secret un
 
 ### Set up the bank provider
 
-Do this before the first start, so the instance serves working screens from the beginning.
+Do the console work before the first start, so the instance serves working screens from the beginning.
 
 Create a sandbox domain and a client application in the [Powens console](https://console.powens.com). Register this redirect URI on the client:
 
@@ -120,16 +120,9 @@ The value is your `CORS_ORIGIN` and the path `/callback/powens`. Powens matches
 
 Activate the connectors of the banks you want to offer. A domain with no active connector answers with an empty bank list.
 
-Then add the credentials of the client to `.env`:
+Keep the domain, the client id and the client secret to hand. The credentials go into [the setup screen](/docs/self-hosting/setup) after the first start, and not into the `.env` file.
 
-```dotenv
-BANKING_PROVIDER=powens
-POWENS_DOMAIN=acme-sandbox
-POWENS_CLIENT_ID=<client id>
-POWENS_CLIENT_SECRET=<client secret>
-```
-
-[Bank providers](/docs/self-hosting/bank-providers) holds each console step, the sandbox limits, and the Enable Banking alternative. An empty `POWENS_` variable turns bank linking off, and no message says so.
+[Bank providers](/docs/self-hosting/bank-providers) holds each console step, the sandbox limits, and the Enable Banking alternative. An instance with no credentials turns bank linking off, and no message says so.
 
 </Step>
 
@@ -187,12 +180,30 @@ docker compose logs -f server
 
 ### Create the first account
 
-Open the web app origin in a browser, then sign up with an email address and a password. Freenary has no admin account and no owner role, so the first account is an ordinary user. [First steps](/docs/guides/first-steps) covers what that user does next.
+Open the web app origin in a browser, then sign up with an email address and a password. [First steps](/docs/guides/first-steps) covers what that user does next.
 
 The wizard that opens proves the bank provider. It asks for a tax residency, then offers a bank step with the banks your domain activated. A missing bank step means Freenary read no credentials, and Settings then reads `Bank linking is unavailable`.
 
 </Step>
 
+<Step>
+
+### Claim the instance
+
+The account you made is an ordinary user until it claims the instance. Freenary opens `/setup` for it. Read the setup link from the server log:
+
+```bash
+docker compose logs server | grep "setup token"
+```
+
+Open the link, and press `Claim`. That account becomes the operator, and no second account can take the role. An unclaimed instance on a public origin is claimable by anybody who finds it. Do this in the same sitting.
+
+To know the token before the first start, set `FREENARY_SETUP_TOKEN`. [The setup screen](/docs/self-hosting/setup#choose-the-token-in-advance) tells how.
+
+The setup screen is where the bank and email credentials go. [The setup screen](/docs/self-hosting/setup) walks each card and the restart that applies it.
+
+</Step>
+
 </Steps>
 
 <Callout type="warn">
@@ -203,6 +214,12 @@ The first sign-up is the moment to decide about email verification. With no emai
 
 <Cards>
 
+<Card
+  title="The setup screen"
+  href="/docs/self-hosting/setup"
+  description="Claim the instance, then set the providers from the app."
+/>
+
 <Card
   title="Configuration"
   href="/docs/self-hosting/configuration"
diff --git a/apps/fumadocs/content/docs/next/self-hosting/meta.json b/apps/fumadocs/content/docs/next/self-hosting/meta.json
index 0402949a..99f8d5db 100644
--- a/apps/fumadocs/content/docs/next/self-hosting/meta.json
+++ b/apps/fumadocs/content/docs/next/self-hosting/meta.json
@@ -5,6 +5,7 @@
   "pages": [
     "index",
     "configuration",
+    "setup",
     "reverse-proxy",
     "scaling",
     "authentication",
diff --git a/apps/fumadocs/content/docs/next/self-hosting/security.mdx b/apps/fumadocs/content/docs/next/self-hosting/security.mdx
index 20e5ee68..d11cf167 100644
--- a/apps/fumadocs/content/docs/next/self-hosting/security.mdx
+++ b/apps/fumadocs/content/docs/next/self-hosting/security.mdx
@@ -44,7 +44,7 @@ No Dockerfile in the repository sets a `USER` instruction, and neither compose f
 
 | Secret | Rule | What it protects |
 | --- | --- | --- |
-| `BETTER_AUTH_SECRET` | 32 characters or more | The session cookie, the two-factor data, the bank connection state |
+| `BETTER_AUTH_SECRET` | 32 characters or more | The session cookie, the two-factor data, the bank connection state, every `instance_setting` row |
 | `POSTGRES_PASSWORD` | No default in the stack | The database itself, and the volume that holds it |
 | The bank provider credentials | Set as a pair or a triple | The bank connection of every user |
 | The email provider key | One key per adapter | One-time code delivery, and password reset |
@@ -59,6 +59,25 @@ openssl rand -hex 32   # BETTER_AUTH_SECRET
 
 `docker compose up` stops before it creates a container when either value is unset or empty. So every Docker instance holds two values you chose.
 
+## The setup token and the operator
+
+A new instance is unclaimed, and it prints a setup link to its own log at each start. The link carries a setup token after its `#`. The first account to enter that token at `/setup` becomes the operator, and the token then stops working.
+
+An unclaimed instance on a public origin is claimable by anybody who signs up and reads `/setup`. The token is what stops them, because only the operator can read the server log. Claim the instance in the same sitting as the install.
+
+`FREENARY_SETUP_TOKEN` replaces the printed token with a value you choose. Keep it as secret as `BETTER_AUTH_SECRET` until the claim. After the claim, the server ignores it.
+
+| Rule | Detail |
+| --- | --- |
+| Where a printed token appears | `docker compose logs server`. After you open the link, also the browser history and the `sessionStorage` of that tab, until the claim |
+| Where a chosen token appears | `.env` and the environment of the `server` container. The server never prints it |
+| What the reverse proxy sees | The request, but not the token. A browser does not send the part of a link after `#` |
+| What the database holds | The SHA-256 hash of the token, never the token |
+| How many operators | One. No screen and no endpoint grants the role a second time |
+| Rate limit on the claim | 5 attempts per caller address every 5 minutes |
+
+The operator role opens `/setup` alone. It grants no access to the rows of another user.
+
 <Callout type="warn">
 
 The schema default of `BETTER_AUTH_SECRET` is the literal `dev_secret_change_me_at_least_32chars`. It is 37 characters long, so it passes validation, and no production check refuses it. The Docker stack never reaches that default. A process started outside the stack does, and anyone can then forge a session cookie against it.
@@ -118,7 +137,9 @@ Treat the database and every dump of it as the financial data itself. Encrypt th
 
 Freenary enables no account deletion. No screen and no endpoint removes a user. An operator who must erase one person does it in the database. A user can delete a bank connection, and that delete removes its accounts, transactions and holdings through the database cascade.
 
-There are also no roles and no admin surface. Every signed-in account has the same rights, and each one reaches its own rows alone.
+One role exists, and it is the operator. It opens the setup screen and changes the provider settings of the instance. It reads no financial row of another user, and every signed-in account otherwise reaches its own rows alone.
+
+The `instance_setting` table holds the provider credentials the operator typed. Each row is sealed with AES-256-GCM, under a key made from `BETTER_AUTH_SECRET`. A reader of the table alone gets ciphertext.
 
 ## The checklist
 
@@ -132,7 +153,8 @@ Work through each line before real users arrive.
 - [ ] The `postgres` service publishes nothing, or it publishes to `127.0.0.1` alone.
 - [ ] `TRUSTED_PROXIES` lists every proxy in front of the API server.
 - [ ] `AUTH_COOKIE_DOMAIN` names the shared parent domain, for two subdomains.
-- [ ] `EMAIL_PROVIDER` is `resend` or `smtp`, so password reset works.
+- [ ] An account claimed the instance, so `/setup` refuses everybody else.
+- [ ] The email provider is `resend` or `smtp`, so password reset works.
 - [ ] `docker compose ps -a` shows `migrate` as `Exited (0)` and the rest as `healthy`.
 - [ ] You know which endpoint `AI_BASE_URL` names, or you left it unset.
 - [ ] A dump runs on a schedule, and you restored one to check it.
diff --git a/apps/fumadocs/content/docs/next/self-hosting/setup.mdx b/apps/fumadocs/content/docs/next/self-hosting/setup.mdx
new file mode 100644
index 00000000..96a5c540
--- /dev/null
+++ b/apps/fumadocs/content/docs/next/self-hosting/setup.mdx
@@ -0,0 +1,181 @@
+---
+title: The setup screen
+description: Claim a new instance, then set the bank and email providers from the app instead of the env file.
+icon: Wrench
+---
+
+A new instance serves a setup screen at `/setup`. It is a wizard with one step per integration. It holds the provider settings an operator changes after the install.
+
+**An instance that has not finished the wizard sends every signed-in visitor there.** The web app reads the setup state before it renders any protected screen. A fresh deployment therefore opens on the wizard, and not on an empty home screen. The redirect stops when an operator presses `Finish setup`.
+
+The screen can test each credential against the real service. `Check` makes the call and writes nothing. `Save` stores the values and makes no call.
+
+## What the screen owns, and what stays in the file
+
+The `.env` file keeps the values the instance needs before it can serve the screen at all:
+
+| Value | Why the file keeps it |
+| --- | --- |
+| `POSTGRES_PASSWORD` | The setup screen writes to the database, so the database opens first |
+| `BETTER_AUTH_SECRET` | It seals what the screen stores, and it signs the session that opens the screen |
+| `BETTER_AUTH_URL`, `CORS_ORIGIN` | The browser reaches the screen over these two origins |
+| `FREENARY_VERSION` | Compose reads it before any container starts |
+| `FREENARY_SETUP_TOKEN` | Optional. It sets the setup token before the first start, so you do not need the log to claim the instance |
+
+Everything the setup screen holds stays out of the file. [Configuration](/docs/self-hosting/configuration) lists every variable, and names the ones the screen owns.
+
+## Claim the instance
+
+The first account that opens `/setup` is not the operator yet. An instance on a public origin is open to anybody who finds it. The claim therefore needs a setup token that only the operator knows.
+
+<Steps>
+
+<Step>
+
+### Get the setup link
+
+Each start of an unclaimed instance prints a setup link to the server log:
+
+```bash
+docker compose logs server | grep "setup token"
+```
+
+The line holds the web app origin and the token:
+
+```text
+This instance is unclaimed. Open this link to claim it with its setup token: https://app.example.com/setup#token=s6kSPDviSE5J_r3wgUos1a06mq9Z1qmt
+```
+
+The server makes a new token at each start while the instance is unclaimed. Only the hash of it goes into the database. A restart therefore makes the last link useless. Read the log again after a restart.
+
+The token sits after the `#` in the link. The browser does not send that part to any server. The token therefore stays out of the logs of your reverse proxy. The web app removes it from the address bar when the page opens.
+
+</Step>
+
+<Step>
+
+### Open the link, sign up, then claim
+
+Open the link, and create an account in the usual way. The web app keeps the token while you sign up, then opens `/setup` with the token in the field. Press `Claim`.
+
+You can also open `/setup` directly and type the token.
+
+That account becomes the operator. The server prints no link after the claim, and no second account can take the role.
+
+</Step>
+
+</Steps>
+
+### Choose the token in advance
+
+Set `FREENARY_SETUP_TOKEN` in `.env` to choose the token yourself. Use a random value of 32 or more characters:
+
+```bash
+openssl rand -hex 32
+```
+
+The server then uses that value at each start, and a restart keeps it valid. The log line names the variable in place of the value. The server never prints a secret from the environment. Open `https://app.example.com/setup#token=` followed by your value.
+
+After the claim, the server ignores the variable. You can remove the line from `.env`.
+
+## Walk the steps
+
+The wizard runs `Claim`, then one step per integration, then `Done`. Each integration step has two screens. The first screen asks which provider to use. The second screen asks for the credentials of that provider.
+
+**Every integration step is optional.** Pick `Skip for now` and press `Continue` to go to the next step. When the app holds no provider for that integration, a skip writes nothing. When it holds one, a skip clears it. `Back` returns to the last screen.
+
+<Steps>
+
+<Step>
+
+### Pick the provider
+
+**Bank provider** offers Powens and Enable Banking. **Email delivery** offers Resend and SMTP. The screen selects a provider for you: the one already in use, or else the first one. Press `Continue`.
+
+</Step>
+
+<Step>
+
+### Fill the fields, then press `Save and continue`
+
+The screen shows the required fields. The optional fields, such as the SMTP port or user, are under `More options`. A link opens the setup guide of the provider.
+
+`Save and continue` first calls the service with the credentials that the server would use:
+
+| Integration    | The call it makes                                           |
+| -------------- | ----------------------------------------------------------- |
+| Powens         | Creates a throwaway user on your domain, then deletes it    |
+| Enable Banking | Signs a token with your PEM key, then reads the application |
+| Resend         | Reads the domain list of the account                        |
+| SMTP           | Opens the connection and signs in, and sends no message     |
+
+When the call succeeds, the screen saves the values and goes to the next step. When the call fails, the screen tells you what to change and saves nothing. `Show details` gives the exact answer of the service.
+
+After a failed call, the screen also offers `Save anyway`. It stores the values with no call, for a service that you cannot reach from the server yet. Such a save can hold a wrong credential. Come back and save again when the service is available.
+
+</Step>
+
+<Step>
+
+### Review, then press `Finish setup`
+
+The last step shows each integration, the provider in use, and its state: `Configured`, `Incomplete` or `Off`.
+
+The API server reads its configuration one time, at startup. When you saved a value that the server does not use yet, `Finish setup` restarts the server. The screen then waits, and opens the app when the server is back. When nothing changed, `Finish setup` opens the app at once.
+
+The restart needs a supervisor that starts the server again. The compose files set `restart: unless-stopped` for this. If the server does not come back within one minute, read [the restart fix](/docs/self-hosting/troubleshooting#the-server-does-not-restart-after-setup).
+
+After `Finish setup`, the instance stops sending visitors to `/setup`. The screen stays open for a later change.
+
+</Step>
+
+</Steps>
+
+## A value in the environment wins
+
+A variable set in the environment always beats the same value in the database. The screen therefore shows such a value as read-only, with the tag `Set by your server`.
+
+- `Save and continue` tests the environment values together with the values you typed. It stores only the fields that the environment does not set.
+- The environment can configure a provider in full. This is true when the app holds no provider for that integration, and the environment sets every required field. The step then shows a card, for example `Powens is ready`, in place of the two screens. `Show details` lists the values and the variables they come from. It also says when the provider is the default, because `BANKING_PROVIDER` is not set. `Test connection` calls the service with those values.
+- The screen shows the first four and the last four characters of a value from the environment. A value of eight characters or fewer shows as `…`. The screen never shows a secret from the environment.
+
+This keeps two habits working. An operator who holds secrets in Kubernetes, in Vault or in the file keeps that setup. The screen never fights it. An operator who wants the screen to own a value removes the line from `.env`, then runs `docker compose up -d`.
+
+## Where the values live
+
+Each value sits in one row of the `instance_setting` table, sealed with AES-256-GCM. The key comes from `BETTER_AUTH_SECRET` and the row name, so a row moved to another name no longer opens.
+
+Two results follow:
+
+- A database dump holds the credentials. It needs the same care as the `.env` file. Read [Backup and restore](/docs/self-hosting/backup-and-restore).
+- A new `BETTER_AUTH_SECRET` makes every stored value unreadable. The server logs one warning for each row it cannot open. The integration then turns off until the operator types the credential again.
+
+The screen never sends a stored secret back to the browser. A secret field shows that a value exists, and an empty box keeps it.
+
+<Cards>
+
+<Card
+  title="Bank providers"
+  href="/docs/self-hosting/bank-providers"
+  description="The console work that comes before the credentials."
+/>
+
+<Card
+  title="Email"
+  href="/docs/self-hosting/email"
+  description="What email turns on, and what each provider needs."
+/>
+
+<Card
+  title="Configuration"
+  href="/docs/self-hosting/configuration"
+  description="Every variable, its default and its refusal message."
+/>
+
+<Card
+  title="Security"
+  href="/docs/self-hosting/security"
+  description="Secrets, cookies, rate limits and what the instance exposes."
+/>
+
+</Cards>
diff --git a/apps/fumadocs/content/docs/next/self-hosting/troubleshooting.mdx b/apps/fumadocs/content/docs/next/self-hosting/troubleshooting.mdx
index 481ab474..b2677823 100644
--- a/apps/fumadocs/content/docs/next/self-hosting/troubleshooting.mdx
+++ b/apps/fumadocs/content/docs/next/self-hosting/troubleshooting.mdx
@@ -81,6 +81,26 @@ Do not set `SKIP_ENV_VALIDATION` to get past this report. The flag hides the mis
 
 </Callout>
 
+## The server does not restart after setup
+
+**What you see.** After `Finish setup`, the setup screen waits for one minute, then shows `The server did not restart`.
+
+**Why.** `Finish setup` stops the API server, so that it reads the saved configuration at the next start. A supervisor must start it again. The compose files set `restart: unless-stopped` for this. A server that runs with no supervisor, for example with `bun run dev`, stays stopped. A server that fails at startup also stays down.
+
+**Fix.** Read the log of the server:
+
+```bash
+docker compose logs server
+```
+
+Correct the error that the log names, then start the server:
+
+```bash
+docker compose up -d server
+```
+
+Press `Try again` on the setup screen. It waits for the server again, and opens the app when the server is back.
+
 ## The server refuses a proxy address
 
 **What you see.** The report above names `TRUSTED_PROXIES`, with this message:
diff --git a/apps/server/package.json b/apps/server/package.json
index e78cdd4f..90ece9b8 100644
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -16,6 +16,7 @@
     "@freenary/auth": "workspace:*",
     "@freenary/db": "workspace:*",
     "@freenary/env": "workspace:*",
+    "@freenary/instance-config": "workspace:*",
     "@orpc/openapi": "catalog:",
     "@orpc/server": "catalog:",
     "@orpc/zod": "catalog:",
diff --git a/apps/server/src/index.ts b/apps/server/src/index.ts
index 699f12e1..db568f7f 100644
--- a/apps/server/src/index.ts
+++ b/apps/server/src/index.ts
@@ -4,11 +4,13 @@ import { createContext } from "@freenary/api/context";
 import { appRouter } from "@freenary/api/routers/index";
 import { auth } from "@freenary/auth";
 import { env } from "@freenary/env/server";
+import { issueSetupToken } from "@freenary/instance-config";
 import { OpenAPIHandler } from "@orpc/openapi/fetch";
 import { OpenAPIReferencePlugin } from "@orpc/openapi/plugins";
 import { ORPCError, onError } from "@orpc/server";
 import { RPCHandler } from "@orpc/server/fetch";
 import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
+import { Effect, Option } from "effect";
 import { Elysia } from "elysia";
 import { initLogger } from "evlog";
 import { createAuthMiddleware } from "evlog/better-auth";
@@ -142,3 +144,18 @@ new Elysia()
   .listen(env.PORT, () => {
     console.log(`Server is running on http://localhost:${env.PORT}`);
   });
+
+const issuedSetupToken = await Effect.runPromise(
+  issueSetupToken(env.FREENARY_SETUP_TOKEN)
+);
+
+if (Option.isSome(issuedSetupToken)) {
+  const setupUrl = `${env.CORS_ORIGIN}/setup#token=`;
+  const issued = issuedSetupToken.value;
+
+  console.log(
+    issued.kind === "generated"
+      ? `This instance is unclaimed. Open this link to claim it with its setup token: ${setupUrl}${issued.token}`
+      : `This instance is unclaimed. To claim it with the setup token from FREENARY_SETUP_TOKEN, open ${setupUrl} followed by that value.`
+  );
+}
diff --git a/apps/web/messages/en.json b/apps/web/messages/en.json
index c26b6a7c..0a8abdef 100644
--- a/apps/web/messages/en.json
+++ b/apps/web/messages/en.json
@@ -714,12 +714,12 @@
   "settings_2fa_confirm": "Turn on two-factor authentication",
   "settings_2fa_continue": "Continue",
   "settings_2fa_description": "A code from your authenticator app, on top of your password.",
+  "settings_2fa_dialog_title_enable": "Enable two-factor authentication",
+  "settings_2fa_dialog_title_regenerate": "New recovery codes",
   "settings_2fa_disable_confirm": "Disable",
   "settings_2fa_disable_description": "Your password alone will sign you in again. Confirm it to continue.",
   "settings_2fa_disable_title": "Disable two-factor authentication?",
   "settings_2fa_disabled_toast": "Two-factor authentication is off",
-  "settings_2fa_dialog_title_enable": "Enable two-factor authentication",
-  "settings_2fa_dialog_title_regenerate": "New recovery codes",
   "settings_2fa_enabled_toast": "Two-factor authentication is on",
   "settings_2fa_error_code_format": [
     {
@@ -1023,6 +1023,99 @@
       }
     }
   ],
+  "setup_applying_description": "This page reconnects on its own.",
+  "setup_applying_title": "Applying your settings…",
+  "setup_back": "Back",
+  "setup_check": "Check",
+  "setup_claim_description": "Enter the setup token from your server log.",
+  "setup_claim_error": "That token was refused. Read the server log again and retry.",
+  "setup_claim_submit": "Claim instance",
+  "setup_claim_success": "You are now the operator of this instance.",
+  "setup_claim_title": "Claim this instance",
+  "setup_claim_token_help": "Where do I find the token?",
+  "setup_claim_token_hint": "Read the link from the server log with docker compose logs server. If the environment sets FREENARY_SETUP_TOKEN, enter that value.",
+  "setup_claim_token_label": "Setup token",
+  "setup_completed_toast": "The instance is set up.",
+  "setup_continue": "Continue",
+  "setup_credentials_description": "Enter the credentials for {provider}.",
+  "setup_credentials_title": "Connect {provider}",
+  "setup_description": "Choose the services this instance uses and enter their credentials. Freenary checks each one before it saves.",
+  "setup_environment_default_provider": "{key} is not set, so {provider} is the default.",
+  "setup_environment_learn_more": "Learn more about environment settings",
+  "setup_environment_line": "Set by your server's environment variables.",
+  "setup_environment_note": "These values come from environment variables: {keys}. The server always uses them, so you cannot change them here. To change them, edit the variables and restart the server.",
+  "setup_environment_ready": "{provider} is ready",
+  "setup_environment_unset": "Not set",
+  "setup_environment_variables": "Variables: {keys}",
+  "setup_error_environment_owned": "Your server's environment sets this provider.",
+  "setup_error_invalid": "A value has the wrong format. Check the fields and try again.",
+  "setup_error_missing_fields": "Fill in {keys}.",
+  "setup_error_probe_invalid": "A value has the wrong shape: {detail}",
+  "setup_error_probe_rejected": "{provider} refused these credentials. Check them and try again.",
+  "setup_error_probe_unreachable": "Unable to reach {provider}. Check the address and your network, then try again.",
+  "setup_fault_badge": "Configuration problem",
+  "setup_fault_title": "The stored configuration did not load: {detail}",
+  "setup_field_email_from": "Sender address",
+  "setup_field_enable_banking_app_id": "Application ID",
+  "setup_field_enable_banking_private_key": "Private key (PEM)",
+  "setup_field_optional": "(optional)",
+  "setup_field_powens_client_id": "Client ID",
+  "setup_field_powens_client_secret": "Client secret",
+  "setup_field_powens_domain": "Powens domain",
+  "setup_field_resend_api_key": "API key",
+  "setup_field_smtp_host": "Host",
+  "setup_field_smtp_password": "Password",
+  "setup_field_smtp_port": "Port",
+  "setup_field_smtp_secure": "Implicit TLS",
+  "setup_field_smtp_user": "User",
+  "setup_finish_action": "Finish setup",
+  "setup_finish_description": "Check your choices, then finish.",
+  "setup_finish_title": "Review and finish",
+  "setup_integration_banking_description": "Pick the service that connects bank accounts.",
+  "setup_integration_banking_title": "Bank provider",
+  "setup_integration_email_description": "Pick the service that sends sign-in and account emails.",
+  "setup_integration_email_title": "Email delivery",
+  "setup_loading": "Loading the setup screen",
+  "setup_locked_by_environment": "The environment sets this integration. The server always uses the environment value, so you cannot change it here. You can still check it. To set it here, remove its lines from the .env file.",
+  "setup_more_options": "More options",
+  "setup_next": "Next",
+  "setup_not_operator_description": "Another account operates this instance. Ask its operator to change the configuration.",
+  "setup_not_operator_title": "Already claimed",
+  "setup_nothing_to_save": "The environment sets every value, so there is nothing to save.",
+  "setup_progress_label": "Setup progress",
+  "setup_recap_from_environment": "From the environment",
+  "setup_save": "Save",
+  "setup_save_and_continue": "Save and continue",
+  "setup_save_anyway": "Save anyway",
+  "setup_saved": "Saved after a check. It applies when you finish setup.",
+  "setup_saved_unchecked": "Saved without a connection test.",
+  "setup_secret_from_environment": "Set in the environment",
+  "setup_secret_unchanged_hint": "Saved. Leave empty to keep it.",
+  "setup_set_by_server": "Set by your server",
+  "setup_show_details": "Show details",
+  "setup_skip": "Skip",
+  "setup_source_environment": "{key} comes from the environment. The server always uses that value.",
+  "setup_stalled_description": "It did not answer within one minute.",
+  "setup_stalled_title": "The server did not restart",
+  "setup_state_configured": "Configured",
+  "setup_state_disabled": "Off",
+  "setup_state_incomplete": "Incomplete",
+  "setup_step_bank": "Bank",
+  "setup_step_claim": "Claim",
+  "setup_step_email": "Email",
+  "setup_step_finish": "Done",
+  "setup_test_connection": "Test connection",
+  "setup_title": "Set up this instance",
+  "setup_try_again": "Try again",
+  "setup_variant_disabled": "Skip for now",
+  "setup_variant_enable_banking": "Enable Banking",
+  "setup_variant_guide": "How to get {provider} credentials",
+  "setup_variant_label": "Provider",
+  "setup_variant_powens": "Powens",
+  "setup_variant_resend": "Resend",
+  "setup_variant_smtp": "SMTP",
+  "setup_verified": "Connection works.",
+  "setup_view_troubleshooting": "View troubleshooting",
   "shell_brand_name": "Freenary",
   "shell_dashboard_welcome": "Welcome back, {name}",
   "shell_nav_planned_badge": "Planned",
diff --git a/apps/web/messages/fr.json b/apps/web/messages/fr.json
index bdc439c5..be0450b0 100644
--- a/apps/web/messages/fr.json
+++ b/apps/web/messages/fr.json
@@ -723,12 +723,12 @@
   "settings_2fa_confirm": "Activer l’authentification à deux facteurs",
   "settings_2fa_continue": "Continuer",
   "settings_2fa_description": "Un code de votre application d’authentification, en plus de votre mot de passe.",
+  "settings_2fa_dialog_title_enable": "Activer l’authentification à deux facteurs",
+  "settings_2fa_dialog_title_regenerate": "Nouveaux codes de secours",
   "settings_2fa_disable_confirm": "Désactiver",
   "settings_2fa_disable_description": "Votre mot de passe seul suffira de nouveau à vous connecter. Confirmez-le pour continuer.",
   "settings_2fa_disable_title": "Désactiver l’authentification à deux facteurs ?",
   "settings_2fa_disabled_toast": "Authentification à deux facteurs désactivée",
-  "settings_2fa_dialog_title_enable": "Activer l’authentification à deux facteurs",
-  "settings_2fa_dialog_title_regenerate": "Nouveaux codes de secours",
   "settings_2fa_enabled_toast": "Authentification à deux facteurs activée",
   "settings_2fa_error_code_format": [
     {
@@ -1032,6 +1032,99 @@
       }
     }
   ],
+  "setup_applying_description": "Cette page se reconnecte d'elle-même.",
+  "setup_applying_title": "Application de vos réglages…",
+  "setup_back": "Retour",
+  "setup_check": "Vérifier",
+  "setup_claim_description": "Saisissez le jeton d'installation indiqué dans le journal du serveur.",
+  "setup_claim_error": "Ce jeton a été refusé. Relisez le journal du serveur et réessayez.",
+  "setup_claim_submit": "Revendiquer l'instance",
+  "setup_claim_success": "Vous êtes désormais l'opérateur de cette instance.",
+  "setup_claim_title": "Revendiquer cette instance",
+  "setup_claim_token_help": "Où trouver le jeton ?",
+  "setup_claim_token_hint": "Lisez le lien dans le journal du serveur avec docker compose logs server. Si l'environnement définit FREENARY_SETUP_TOKEN, saisissez cette valeur.",
+  "setup_claim_token_label": "Jeton d'installation",
+  "setup_completed_toast": "L'instance est configurée.",
+  "setup_continue": "Continuer",
+  "setup_credentials_description": "Saisissez les identifiants de {provider}.",
+  "setup_credentials_title": "Connecter {provider}",
+  "setup_description": "Choisissez les services utilisés par cette instance et saisissez leurs identifiants. Freenary vérifie chacun d'eux avant d'enregistrer.",
+  "setup_environment_default_provider": "{key} n'est pas défini : {provider} est le choix par défaut.",
+  "setup_environment_learn_more": "En savoir plus sur les réglages d'environnement",
+  "setup_environment_line": "Défini par les variables d'environnement de votre serveur.",
+  "setup_environment_note": "Ces valeurs proviennent de variables d'environnement : {keys}. Le serveur les utilise toujours, vous ne pouvez donc pas les modifier ici. Pour les changer, modifiez les variables et redémarrez le serveur.",
+  "setup_environment_ready": "{provider} est prêt",
+  "setup_environment_unset": "Non défini",
+  "setup_environment_variables": "Variables : {keys}",
+  "setup_error_environment_owned": "L'environnement de votre serveur définit ce fournisseur.",
+  "setup_error_invalid": "Une valeur n'a pas le bon format. Vérifiez les champs et réessayez.",
+  "setup_error_missing_fields": "Renseignez {keys}.",
+  "setup_error_probe_invalid": "Une valeur n'a pas le bon format : {detail}",
+  "setup_error_probe_rejected": "{provider} a refusé ces identifiants. Vérifiez-les et réessayez.",
+  "setup_error_probe_unreachable": "Impossible de joindre {provider}. Vérifiez l'adresse et votre réseau, puis réessayez.",
+  "setup_fault_badge": "Problème de configuration",
+  "setup_fault_title": "La configuration enregistrée n'a pas pu être chargée : {detail}",
+  "setup_field_email_from": "Adresse d'expédition",
+  "setup_field_enable_banking_app_id": "Identifiant d'application",
+  "setup_field_enable_banking_private_key": "Clé privée (PEM)",
+  "setup_field_optional": "(facultatif)",
+  "setup_field_powens_client_id": "Identifiant client",
+  "setup_field_powens_client_secret": "Secret client",
+  "setup_field_powens_domain": "Domaine Powens",
+  "setup_field_resend_api_key": "Clé d'API",
+  "setup_field_smtp_host": "Hôte",
+  "setup_field_smtp_password": "Mot de passe",
+  "setup_field_smtp_port": "Port",
+  "setup_field_smtp_secure": "TLS implicite",
+  "setup_field_smtp_user": "Utilisateur",
+  "setup_finish_action": "Terminer la configuration",
+  "setup_finish_description": "Vérifiez vos choix, puis terminez.",
+  "setup_finish_title": "Vérifier et terminer",
+  "setup_integration_banking_description": "Choisissez le service qui connecte les comptes bancaires.",
+  "setup_integration_banking_title": "Fournisseur bancaire",
+  "setup_integration_email_description": "Choisissez le service qui envoie les courriels de connexion et de compte.",
+  "setup_integration_email_title": "Envoi des courriels",
+  "setup_loading": "Chargement de l'écran de configuration",
+  "setup_locked_by_environment": "L'environnement définit cette intégration. Le serveur utilise toujours la valeur de l'environnement, vous ne pouvez donc pas la modifier ici. Vous pouvez tout de même la vérifier. Pour la définir ici, retirez ses lignes du fichier .env.",
+  "setup_more_options": "Plus d'options",
+  "setup_next": "Suivant",
+  "setup_not_operator_description": "Un autre compte administre cette instance. Demandez à son opérateur de modifier la configuration.",
+  "setup_not_operator_title": "Déjà revendiquée",
+  "setup_nothing_to_save": "L'environnement définit toutes les valeurs : il n'y a rien à enregistrer.",
+  "setup_progress_label": "Progression de la configuration",
+  "setup_recap_from_environment": "Depuis l'environnement",
+  "setup_save": "Enregistrer",
+  "setup_save_and_continue": "Enregistrer et continuer",
+  "setup_save_anyway": "Enregistrer quand même",
+  "setup_saved": "Enregistré après vérification. Appliqué à la fin de la configuration.",
+  "setup_saved_unchecked": "Enregistré sans test de connexion.",
+  "setup_secret_from_environment": "Défini dans l'environnement",
+  "setup_secret_unchanged_hint": "Enregistré. Laissez vide pour le conserver.",
+  "setup_set_by_server": "Défini par votre serveur",
+  "setup_show_details": "Afficher les détails",
+  "setup_skip": "Passer",
+  "setup_source_environment": "{key} provient de l'environnement. Le serveur utilise toujours cette valeur.",
+  "setup_stalled_description": "Il n'a pas répondu en une minute.",
+  "setup_stalled_title": "Le serveur n'a pas redémarré",
+  "setup_state_configured": "Configuré",
+  "setup_state_disabled": "Désactivé",
+  "setup_state_incomplete": "Incomplet",
+  "setup_step_bank": "Banque",
+  "setup_step_claim": "Revendiquer",
+  "setup_step_email": "Courriel",
+  "setup_step_finish": "Fin",
+  "setup_test_connection": "Tester la connexion",
+  "setup_title": "Configurer cette instance",
+  "setup_try_again": "Réessayer",
+  "setup_variant_disabled": "Passer pour l'instant",
+  "setup_variant_enable_banking": "Enable Banking",
+  "setup_variant_guide": "Obtenir les identifiants {provider}",
+  "setup_variant_label": "Fournisseur",
+  "setup_variant_powens": "Powens",
+  "setup_variant_resend": "Resend",
+  "setup_variant_smtp": "SMTP",
+  "setup_verified": "La connexion fonctionne.",
+  "setup_view_troubleshooting": "Voir le dépannage",
   "shell_brand_name": "Freenary",
   "shell_dashboard_welcome": "Ravi de vous revoir, {name}",
   "shell_nav_planned_badge": "Prévu",
diff --git a/apps/web/src/app/api/get-instance.ts b/apps/web/src/app/api/get-instance.ts
new file mode 100644
index 00000000..f3604f65
--- /dev/null
+++ b/apps/web/src/app/api/get-instance.ts
@@ -0,0 +1,34 @@
+import { createServerFn } from "@tanstack/react-start";
+import { getRequestHeader } from "@tanstack/react-start/server";
+import { Data, Effect } from "effect";
+
+import { client } from "@/shared/api";
+
+export type InstanceSetup =
+  | { kind: "needs-setup" }
+  | { kind: "ready" }
+  | { kind: "unknown" };
+
+export const UNKNOWN_INSTANCE: InstanceSetup = { kind: "unknown" };
+
+class InstanceRequestFailed extends Data.TaggedError("InstanceRequestFailed")<{
+  readonly cause: unknown;
+}> {}
+
+const resolveInstance = (cookie: string | undefined) =>
+  Effect.tryPromise({
+    catch: (cause) => new InstanceRequestFailed({ cause }),
+    try: () => client.instance.status(undefined, { context: { cookie } }),
+  }).pipe(
+    Effect.map((answer): InstanceSetup =>
+      answer.completed ? { kind: "ready" } : { kind: "needs-setup" }
+    ),
+    Effect.catchTag("InstanceRequestFailed", () =>
+      Effect.succeed(UNKNOWN_INSTANCE)
+    )
+  );
+
+export const getInstanceSetup = createServerFn({ method: "GET" }).handler(
+  (): Promise<InstanceSetup> =>
+    Effect.runPromise(resolveInstance(getRequestHeader("cookie")))
+);
diff --git a/apps/web/src/app/routes/__root.tsx b/apps/web/src/app/routes/__root.tsx
index 7d3901af..b14c2691 100644
--- a/apps/web/src/app/routes/__root.tsx
+++ b/apps/web/src/app/routes/__root.tsx
@@ -14,7 +14,9 @@ import { TanStackRouterDevtools } from "@tanstack/react-router-devtools";
 import { createMiddleware } from "@tanstack/react-start";
 import { evlogErrorHandler } from "evlog/nitro/v3";
 import { ThemeProvider } from "next-themes";
+import { useEffect } from "react";
 
+import { watchSetupTokenLink } from "@/pages/setup";
 import { m } from "@/paraglide/messages.js";
 import { getLocale } from "@/paraglide/runtime.js";
 import type { orpc } from "@/shared/api";
@@ -22,6 +24,7 @@ import { publicServerUrlScript } from "@/shared/config";
 import { ffIcons } from "@/shared/lib/ff-icons";
 import { isServer } from "@/shared/lib/is-server";
 
+import { UNKNOWN_INSTANCE, getInstanceSetup } from "../api/get-instance";
 import { UNKNOWN_VIEWER, getViewer } from "../api/get-viewer";
 
 import appCss from "../styles/index.css?url";
@@ -31,62 +34,66 @@ export interface RouterAppContext {
   queryClient: QueryClient;
 }
 
-const RootDocument = () => (
-  <html lang={getLocale()} suppressHydrationWarning>
-    <head>
-      <HeadContent />
-    </head>
-    <body>
-      <ThemeProvider
-        attribute="class"
-        defaultTheme="system"
-        disableTransitionOnChange
-        enableSystem
-      >
-        <SizeProvider defaultSize="compact">
-          <IconProvider icons={ffIcons}>
-            <UiLabelsProvider
-              labels={{
-                breadcrumb: m.ui_breadcrumb(),
-                clear: m.ui_clear(),
-                close: m.ui_close(),
-                collapseSidebar: m.ui_collapse_sidebar(),
-                dismiss: m.ui_dismiss(),
-                expandSidebar: m.ui_expand_sidebar(),
-                filterResults: m.ui_filter_results(),
-                loading: m.ui_loading(),
-                loadingPreview: m.ui_loading_preview(),
-                more: m.ui_more(),
-                open: m.ui_open(),
-                peekSidebar: m.ui_peek_sidebar(),
-                remove: m.ui_remove(),
-                resizeSidebar: m.ui_resize_sidebar(),
-                run: m.ui_run(),
-                select: m.ui_select(),
-                sidebar: m.ui_sidebar(),
-                suggestedPrompts: m.ui_suggested_prompts(),
-                tabs: m.ui_tabs(),
-                thinking: m.ui_thinking(),
-                thinkingWords: [
-                  m.ui_thinking_word_thinking(),
-                  m.ui_thinking_word_reading(),
-                  m.ui_thinking_word_planning(),
-                ],
-                toggleSidebar: m.ui_toggle_sidebar(),
-              }}
-            >
-              <Outlet />
-            </UiLabelsProvider>
-          </IconProvider>
-        </SizeProvider>
-        <Toaster richColors />
-      </ThemeProvider>
-      <TanStackRouterDevtools position="bottom-left" />
-      <ReactQueryDevtools position="bottom" buttonPosition="bottom-right" />
-      <Scripts />
-    </body>
-  </html>
-);
+const RootDocument = () => {
+  useEffect(watchSetupTokenLink, []);
+
+  return (
+    <html lang={getLocale()} suppressHydrationWarning>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <ThemeProvider
+          attribute="class"
+          defaultTheme="system"
+          disableTransitionOnChange
+          enableSystem
+        >
+          <SizeProvider defaultSize="compact">
+            <IconProvider icons={ffIcons}>
+              <UiLabelsProvider
+                labels={{
+                  breadcrumb: m.ui_breadcrumb(),
+                  clear: m.ui_clear(),
+                  close: m.ui_close(),
+                  collapseSidebar: m.ui_collapse_sidebar(),
+                  dismiss: m.ui_dismiss(),
+                  expandSidebar: m.ui_expand_sidebar(),
+                  filterResults: m.ui_filter_results(),
+                  loading: m.ui_loading(),
+                  loadingPreview: m.ui_loading_preview(),
+                  more: m.ui_more(),
+                  open: m.ui_open(),
+                  peekSidebar: m.ui_peek_sidebar(),
+                  remove: m.ui_remove(),
+                  resizeSidebar: m.ui_resize_sidebar(),
+                  run: m.ui_run(),
+                  select: m.ui_select(),
+                  sidebar: m.ui_sidebar(),
+                  suggestedPrompts: m.ui_suggested_prompts(),
+                  tabs: m.ui_tabs(),
+                  thinking: m.ui_thinking(),
+                  thinkingWords: [
+                    m.ui_thinking_word_thinking(),
+                    m.ui_thinking_word_reading(),
+                    m.ui_thinking_word_planning(),
+                  ],
+                  toggleSidebar: m.ui_toggle_sidebar(),
+                }}
+              >
+                <Outlet />
+              </UiLabelsProvider>
+            </IconProvider>
+          </SizeProvider>
+          <Toaster richColors />
+        </ThemeProvider>
+        <TanStackRouterDevtools position="bottom-left" />
+        <ReactQueryDevtools position="bottom" buttonPosition="bottom-right" />
+        <Scripts />
+      </body>
+    </html>
+  );
+};
 
 export const Route = createRootRouteWithContext<RouterAppContext>()({
   server: {
@@ -94,6 +101,7 @@ export const Route = createRootRouteWithContext<RouterAppContext>()({
   },
 
   beforeLoad: async () => ({
+    instance: isServer ? await getInstanceSetup() : UNKNOWN_INSTANCE,
     viewer: isServer ? await getViewer() : UNKNOWN_VIEWER,
   }),
 
diff --git a/apps/web/src/app/routes/_auth/route.tsx b/apps/web/src/app/routes/_auth/route.tsx
index fa09c5e0..ef6603af 100644
--- a/apps/web/src/app/routes/_auth/route.tsx
+++ b/apps/web/src/app/routes/_auth/route.tsx
@@ -3,11 +3,15 @@ import { createFileRoute, redirect } from "@tanstack/react-router";
 import { AuthLayout } from "../../shell/auth-layout";
 
 export const Route = createFileRoute("/_auth")({
-  beforeLoad: ({ context: { viewer } }) => {
+  beforeLoad: ({ context: { instance, viewer } }) => {
     if (viewer.kind === "guest") {
       throw redirect({ to: "/login" });
     }
 
+    if (instance.kind === "needs-setup") {
+      throw redirect({ to: "/setup" });
+    }
+
     if (viewer.kind === "member" && !viewer.onboarded) {
       throw redirect({ to: "/onboarding" });
     }
diff --git a/apps/web/src/app/routes/login.tsx b/apps/web/src/app/routes/login.tsx
index 02bcc365..a9293df2 100644
--- a/apps/web/src/app/routes/login.tsx
+++ b/apps/web/src/app/routes/login.tsx
@@ -6,10 +6,16 @@ import { LoginPage } from "@/pages/login";
 const loginSearchSchema = z.object({ error: z.string().optional() });
 
 export const Route = createFileRoute("/login")({
-  beforeLoad: ({ context: { viewer } }) => {
-    if (viewer.kind === "member") {
-      throw redirect({ to: viewer.onboarded ? "/" : "/onboarding" });
+  beforeLoad: ({ context: { instance, viewer } }) => {
+    if (viewer.kind !== "member") {
+      return;
     }
+
+    if (instance.kind === "needs-setup") {
+      throw redirect({ to: "/setup" });
+    }
+
+    throw redirect({ to: viewer.onboarded ? "/" : "/onboarding" });
   },
   component: LoginPage,
   validateSearch: loginSearchSchema,
diff --git a/apps/web/src/app/routes/onboarding.tsx b/apps/web/src/app/routes/onboarding.tsx
index 34c532bc..68ebc07d 100644
--- a/apps/web/src/app/routes/onboarding.tsx
+++ b/apps/web/src/app/routes/onboarding.tsx
@@ -3,11 +3,15 @@ import { createFileRoute, redirect } from "@tanstack/react-router";
 import { OnboardingPage } from "@/pages/onboarding";
 
 export const Route = createFileRoute("/onboarding")({
-  beforeLoad: ({ context: { viewer } }) => {
+  beforeLoad: ({ context: { instance, viewer } }) => {
     if (viewer.kind === "guest") {
       throw redirect({ to: "/login" });
     }
 
+    if (instance.kind === "needs-setup") {
+      throw redirect({ to: "/setup" });
+    }
+
     if (viewer.kind === "member" && viewer.onboarded) {
       throw redirect({ to: "/" });
     }
diff --git a/apps/web/src/app/routes/setup.tsx b/apps/web/src/app/routes/setup.tsx
new file mode 100644
index 00000000..09ef5e0c
--- /dev/null
+++ b/apps/web/src/app/routes/setup.tsx
@@ -0,0 +1,12 @@
+import { createFileRoute, redirect } from "@tanstack/react-router";
+
+import { SetupPage } from "@/pages/setup";
+
+export const Route = createFileRoute("/setup")({
+  beforeLoad: ({ context: { viewer } }) => {
+    if (viewer.kind === "guest") {
+      throw redirect({ to: "/login" });
+    }
+  },
+  component: SetupPage,
+});
diff --git a/apps/web/src/features/auth-gate/ui/auth-gate.tsx b/apps/web/src/features/auth-gate/ui/auth-gate.tsx
index 3816a929..822cf257 100644
--- a/apps/web/src/features/auth-gate/ui/auth-gate.tsx
+++ b/apps/web/src/features/auth-gate/ui/auth-gate.tsx
@@ -8,7 +8,7 @@ import { authClient } from "@/shared/auth";
 
 type Audience = "guest" | "member" | "onboarding";
 
-type Destination = "/" | "/login" | "/onboarding";
+type Destination = "/" | "/login" | "/onboarding" | "/setup";
 
 interface AuthGateProps {
   audience: Audience;
@@ -18,12 +18,20 @@ interface AuthGateProps {
 interface Visitor {
   completed: boolean | undefined;
   isPending: boolean;
+  isSetupUnsettled: boolean;
   isSignedIn: boolean;
+  setupCompleted: boolean | undefined;
 }
 
 const redirectFor = (
   audience: Audience,
-  { completed, isPending, isSignedIn }: Visitor
+  {
+    completed,
+    isPending,
+    isSetupUnsettled,
+    isSignedIn,
+    setupCompleted,
+  }: Visitor
 ): Destination | null => {
   if (audience === "guest") {
     return isSignedIn ? "/" : null;
@@ -37,6 +45,14 @@ const redirectFor = (
     return "/login";
   }
 
+  if (setupCompleted === false) {
+    return "/setup";
+  }
+
+  if (isSetupUnsettled) {
+    return null;
+  }
+
   if (audience === "member") {
     return completed === false ? "/onboarding" : null;
   }
@@ -45,21 +61,35 @@ const redirectFor = (
 };
 
 export const AuthGate = ({ audience, children }: AuthGateProps) => {
-  const viewer = useRouteContext({
+  const { instance, viewer } = useRouteContext({
     from: "__root__",
-    select: (context) => context.viewer,
+    select: (context) => ({
+      instance: context.instance,
+      viewer: context.viewer,
+    }),
   });
 
   const navigate = useNavigate();
   const { data: session, isPending } = authClient.useSession();
+  const isSignedIn = session !== null && session !== undefined;
   const status = useQuery(
     orpc.onboarding.getStatus.queryOptions({ enabled: session !== null })
   );
 
+  const setup = useQuery(
+    orpc.instance.status.queryOptions({
+      enabled: audience !== "guest" && isSignedIn,
+    })
+  );
+
+  const isSetupUnsettled = instance.kind !== "ready" && setup.isPending;
+
   const destination = redirectFor(audience, {
     completed: status.data?.completed,
     isPending,
+    isSetupUnsettled,
     isSignedIn: session !== null,
+    setupCompleted: setup.data?.completed,
   });
 
   useEffect(() => {
@@ -84,6 +114,10 @@ export const AuthGate = ({ audience, children }: AuthGateProps) => {
     return wasServerRenderedForMember ? children : null;
   }
 
+  if (isSetupUnsettled) {
+    return null;
+  }
+
   const isOnboardingStatusUnreadable = audience === "member" && status.isError;
 
   if (isOnboardingStatusUnreadable) {
diff --git a/apps/web/src/pages/onboarding/ui/bank-connection-step.tsx b/apps/web/src/pages/onboarding/ui/bank-connection-step.tsx
index ff350f62..3851fd92 100644
--- a/apps/web/src/pages/onboarding/ui/bank-connection-step.tsx
+++ b/apps/web/src/pages/onboarding/ui/bank-connection-step.tsx
@@ -4,8 +4,7 @@ import { useIcon } from "@freenary/ui/lib/icon-context";
 import { BankConnectionPanel } from "@/features/bank-connection";
 import type { BankInstitution } from "@/features/bank-connection";
 import { m } from "@/paraglide/messages.js";
-
-import { OnboardingStepHeader } from "./onboarding-step-header";
+import { WizardStepHeader } from "@/shared/ui/wizard-step-header";
 
 interface BankConnectionStepProps {
   banks: BankInstitution[];
@@ -32,7 +31,7 @@ export const BankConnectionStep = ({
 
   return (
     <div className="flex flex-col gap-6">
-      <OnboardingStepHeader
+      <WizardStepHeader
         description={m.onboarding_bank_description()}
         title={m.onboarding_bank_title()}
       />
diff --git a/apps/web/src/pages/onboarding/ui/country-selection-step.tsx b/apps/web/src/pages/onboarding/ui/country-selection-step.tsx
index 425532e3..fe4e708e 100644
--- a/apps/web/src/pages/onboarding/ui/country-selection-step.tsx
+++ b/apps/web/src/pages/onboarding/ui/country-selection-step.tsx
@@ -20,8 +20,7 @@ import {
   isFullySupportedCountry,
 } from "@/shared/lib/countries";
 import { remixIcon } from "@/shared/lib/remix-icon";
-
-import { OnboardingStepHeader } from "./onboarding-step-header";
+import { WizardStepHeader } from "@/shared/ui/wizard-step-header";
 
 interface CountrySelectionStepProps {
   isCompleting: boolean;
@@ -58,7 +57,7 @@ export const CountrySelectionStep = ({
 
   return (
     <div className="flex flex-col gap-6">
-      <OnboardingStepHeader
+      <WizardStepHeader
         description={m.onboarding_country_description()}
         title={m.onboarding_country_title()}
       />
diff --git a/apps/web/src/pages/onboarding/ui/onboarding-wizard.tsx b/apps/web/src/pages/onboarding/ui/onboarding-wizard.tsx
index d094cb27..aebad844 100644
--- a/apps/web/src/pages/onboarding/ui/onboarding-wizard.tsx
+++ b/apps/web/src/pages/onboarding/ui/onboarding-wizard.tsx
@@ -1,25 +1,14 @@
 import { Button } from "@freenary/ui/components/button";
-import { spring } from "@freenary/ui/lib/springs";
-import { SURFACE_BG } from "@freenary/ui/lib/surface-classes";
-import { SurfaceProvider } from "@freenary/ui/lib/surface-context";
-import { cn } from "@freenary/ui/lib/utils";
-import { AnimatePresence, motion, useReducedMotion } from "motion/react";
 
 import type { BankInstitution } from "@/features/bank-connection";
 import { m } from "@/paraglide/messages.js";
-import { LocaleSwitcher } from "@/shared/ui/locale-switcher";
-import { ThemeSwitcher } from "@/shared/ui/theme-switcher";
+import { WizardShell } from "@/shared/ui/wizard-shell";
+import { WizardStepper } from "@/shared/ui/wizard-stepper";
 
 import { BankConnectionStep } from "./bank-connection-step";
 import { CountrySelectionStep } from "./country-selection-step";
-import { OnboardingStepper } from "./onboarding-stepper";
 import { OnboardingWizardSkeleton } from "./onboarding-wizard-skeleton";
 
-interface StepMotion {
-  direction: 1 | -1;
-  shift: number;
-}
-
 interface OnboardingWizardProps {
   banks: BankInstitution[];
   connectedCount: number;
@@ -48,26 +37,6 @@ const STEP_LABEL_FNS_WITHOUT_BANKING = [
   m.onboarding_step_country,
 ] as const satisfies readonly (() => string)[];
 
-const STEP_SHIFT_PX = 16;
-const NO_STEP_SHIFT_PX = 0;
-const STEP_CROSSFADE_MASK_BLUR = "blur(4px)";
-const NO_BLUR = "blur(0px)";
-
-const stepVariants = {
-  center: { filter: NO_BLUR, opacity: 1, transition: spring.slow, x: 0 },
-  enter: ({ direction, shift }: StepMotion) => ({
-    filter: shift ? STEP_CROSSFADE_MASK_BLUR : NO_BLUR,
-    opacity: 0,
-    x: direction * shift,
-  }),
-  exit: ({ direction, shift }: StepMotion) => ({
-    filter: shift ? STEP_CROSSFADE_MASK_BLUR : NO_BLUR,
-    opacity: 0,
-    transition: spring.slow.exit,
-    x: -direction * shift,
-  }),
-};
-
 export const OnboardingWizard = ({
   banks,
   connectedCount,
@@ -85,94 +54,43 @@ export const OnboardingWizard = ({
   step,
   taxCountries,
   unavailableCountries,
-}: OnboardingWizardProps) => {
-  const prefersReducedMotion = useReducedMotion();
-  const stepMotion: StepMotion = {
-    direction,
-    shift: prefersReducedMotion ? NO_STEP_SHIFT_PX : STEP_SHIFT_PX,
-  };
-
-  return (
-    <SurfaceProvider value={1}>
-      <main className={cn(SURFACE_BG[1], "flex min-h-svh flex-col")}>
-        <div className="flex items-center justify-end gap-1 px-4 py-3">
-          <ThemeSwitcher />
-          <LocaleSwitcher />
-          <Button onClick={onSignOut} type="button" variant="ghost">
-            {m.account_sign_out()}
-          </Button>
-        </div>
-
-        <div className="flex flex-1 items-center justify-center px-4 py-10">
-          <div className="relative flex w-full max-w-md flex-col gap-8">
-            <AnimatePresence initial={false} mode="popLayout">
-              {isPending ? (
-                <motion.div
-                  key="skeleton"
-                  animate={{ opacity: 1 }}
-                  initial={{ opacity: 0 }}
-                  transition={spring.moderate}
-                  exit={{ opacity: 0, transition: spring.moderate.exit }}
-                >
-                  <OnboardingWizardSkeleton />
-                </motion.div>
-              ) : (
-                <motion.div
-                  key="wizard"
-                  animate={{ opacity: 1 }}
-                  className="flex flex-col gap-8"
-                  initial={{ opacity: 0 }}
-                  transition={spring.moderate}
-                  exit={{ opacity: 0, transition: spring.moderate.exit }}
-                >
-                  <OnboardingStepper
-                    current={step}
-                    steps={
-                      hasBankStep
-                        ? STEP_LABEL_FNS
-                        : STEP_LABEL_FNS_WITHOUT_BANKING
-                    }
-                  />
-                  <AnimatePresence
-                    custom={stepMotion}
-                    initial={false}
-                    mode="popLayout"
-                  >
-                    <motion.div
-                      key={step}
-                      animate="center"
-                      custom={stepMotion}
-                      exit="exit"
-                      initial="enter"
-                      variants={stepVariants}
-                    >
-                      {step === 0 ? (
-                        <CountrySelectionStep
-                          isCompleting={isCompleting}
-                          onContinue={onCountryContinue}
-                          onCountriesChange={onCountriesChange}
-                          selected={taxCountries}
-                        />
-                      ) : (
-                        <BankConnectionStep
-                          banks={banks}
-                          connectedCount={connectedCount}
-                          isBanksError={isBanksError}
-                          isBanksPending={isBanksPending}
-                          isCompleting={isCompleting}
-                          onBack={onBack}
-                          onFinish={onFinish}
-                          unavailableCountries={unavailableCountries}
-                        />
-                      )}
-                    </motion.div>
-                  </AnimatePresence>
-                </motion.div>
-              )}
-            </AnimatePresence>
-          </div>
-        </div>
-      </main>
-    </SurfaceProvider>
-  );
-};
+}: OnboardingWizardProps) => (
+  <WizardShell
+    direction={direction}
+    isPending={isPending}
+    skeleton={<OnboardingWizardSkeleton />}
+    stepKey={String(step)}
+    stepper={
+      <WizardStepper
+        current={step}
+        label={m.onboarding_progress_label()}
+        steps={hasBankStep ? STEP_LABEL_FNS : STEP_LABEL_FNS_WITHOUT_BANKING}
+      />
+    }
+    toolbar={
+      <Button onClick={onSignOut} type="button" variant="ghost">
+        {m.account_sign_out()}
+      </Button>
+    }
+  >
+    {step === 0 ? (
+      <CountrySelectionStep
+        isCompleting={isCompleting}
+        onContinue={onCountryContinue}
+        onCountriesChange={onCountriesChange}
+        selected={taxCountries}
+      />
+    ) : (
+      <BankConnectionStep
+        banks={banks}
+        connectedCount={connectedCount}
+        isBanksError={isBanksError}
+        isBanksPending={isBanksPending}
+        isCompleting={isCompleting}
+        onBack={onBack}
+        onFinish={onFinish}
+        unavailableCountries={unavailableCountries}
+      />
+    )}
+  </WizardShell>
+);
diff --git a/apps/web/src/pages/setup/api/wait-for-server.ts b/apps/web/src/pages/setup/api/wait-for-server.ts
new file mode 100644
index 00000000..c70e4ef5
--- /dev/null
+++ b/apps/web/src/pages/setup/api/wait-for-server.ts
@@ -0,0 +1,31 @@
+import { Data, Effect, Schedule } from "effect";
+
+import { client } from "@/shared/api";
+
+const POLL_INTERVAL = "2 seconds";
+const GIVE_UP_AFTER = "60 seconds";
+
+class ServerNotApplied extends Data.TaggedError("ServerNotApplied")<{
+  readonly cause: unknown;
+}> {}
+
+const describeAppliedServer = Effect.tryPromise({
+  catch: (cause) => new ServerNotApplied({ cause }),
+  try: () => client.instance.describe(),
+}).pipe(
+  Effect.flatMap((described) =>
+    described.restartRequired
+      ? Effect.fail(new ServerNotApplied({ cause: "restart pending" }))
+      : Effect.void
+  )
+);
+
+export const waitForAppliedServer = (): Promise<boolean> =>
+  Effect.runPromise(
+    describeAppliedServer.pipe(
+      Effect.delay(POLL_INTERVAL),
+      Effect.retry(Schedule.spaced(POLL_INTERVAL)),
+      Effect.timeout(GIVE_UP_AFTER),
+      Effect.match({ onFailure: () => false, onSuccess: () => true })
+    )
+  );
diff --git a/apps/web/src/pages/setup/index.ts b/apps/web/src/pages/setup/index.ts
new file mode 100644
index 00000000..b28a5f77
--- /dev/null
+++ b/apps/web/src/pages/setup/index.ts
@@ -0,0 +1,2 @@
+export { watchSetupTokenLink } from "./lib/setup-token-link";
+export { SetupPage } from "./ui/setup-page";
diff --git a/apps/web/src/pages/setup/lib/setup-token-link.ts b/apps/web/src/pages/setup/lib/setup-token-link.ts
new file mode 100644
index 00000000..5ffa62dc
--- /dev/null
+++ b/apps/web/src/pages/setup/lib/setup-token-link.ts
@@ -0,0 +1,69 @@
+import { isServer } from "@/shared/lib/is-server";
+
+const STORAGE_KEY = "freenary:setup-token";
+const FRAGMENT_PREFIX = "#token=";
+const WELL_FORMED_TOKEN = /^[\w-]{32,}$/u;
+
+const listeners = new Set<() => void>();
+
+const tokenInFragment = (): string | null => {
+  const { hash } = window.location;
+
+  return hash.startsWith(FRAGMENT_PREFIX)
+    ? hash.slice(FRAGMENT_PREFIX.length)
+    : null;
+};
+
+const wellFormedTokenInFragment = (): string | null => {
+  const token = tokenInFragment();
+
+  return token !== null && WELL_FORMED_TOKEN.test(token) ? token : null;
+};
+
+const captureSetupTokenLink = () => {
+  if (tokenInFragment() === null) {
+    return;
+  }
+
+  const token = wellFormedTokenInFragment();
+
+  if (token !== null) {
+    sessionStorage.setItem(STORAGE_KEY, token);
+  }
+
+  window.history.replaceState(
+    window.history.state,
+    "",
+    `${window.location.pathname}${window.location.search}`
+  );
+
+  for (const notify of listeners) {
+    notify();
+  }
+};
+
+export const watchSetupTokenLink = () => {
+  captureSetupTokenLink();
+  window.addEventListener("hashchange", captureSetupTokenLink);
+
+  return () => window.removeEventListener("hashchange", captureSetupTokenLink);
+};
+
+export const subscribeToSetupTokenLink = (onLink: () => void) => {
+  listeners.add(onLink);
+
+  return () => {
+    listeners.delete(onLink);
+  };
+};
+
+export const readLinkedSetupToken = (): string =>
+  isServer
+    ? ""
+    : (wellFormedTokenInFragment() ??
+      sessionStorage.getItem(STORAGE_KEY) ??
+      "");
+
+export const clearLinkedSetupToken = () => {
+  sessionStorage.removeItem(STORAGE_KEY);
+};
diff --git a/apps/web/src/pages/setup/model/labels.ts b/apps/web/src/pages/setup/model/labels.ts
new file mode 100644
index 00000000..fa0efb64
--- /dev/null
+++ b/apps/web/src/pages/setup/model/labels.ts
@@ -0,0 +1,107 @@
+import type { BadgeColor } from "@freenary/ui/components/badge";
+
+import { m } from "@/paraglide/messages.js";
+import { docsUrl } from "@/shared/config";
+
+type Label = () => string;
+
+const FIELD_LABELS = {
+  EMAIL_FROM: m.setup_field_email_from,
+  ENABLE_BANKING_APP_ID: m.setup_field_enable_banking_app_id,
+  ENABLE_BANKING_PRIVATE_KEY: m.setup_field_enable_banking_private_key,
+  POWENS_CLIENT_ID: m.setup_field_powens_client_id,
+  POWENS_CLIENT_SECRET: m.setup_field_powens_client_secret,
+  POWENS_DOMAIN: m.setup_field_powens_domain,
+  RESEND_API_KEY: m.setup_field_resend_api_key,
+  SMTP_HOST: m.setup_field_smtp_host,
+  SMTP_PASSWORD: m.setup_field_smtp_password,
+  SMTP_PORT: m.setup_field_smtp_port,
+  SMTP_SECURE: m.setup_field_smtp_secure,
+  SMTP_USER: m.setup_field_smtp_user,
+} satisfies Record<string, Label>;
+
+const INTEGRATION_TITLES = {
+  banking: m.setup_integration_banking_title,
+  email: m.setup_integration_email_title,
+} satisfies Record<string, Label>;
+
+const INTEGRATION_DESCRIPTIONS = {
+  banking: m.setup_integration_banking_description,
+  email: m.setup_integration_email_description,
+} satisfies Record<string, Label>;
+
+const STATE_LABELS = {
+  configured: m.setup_state_configured,
+  disabled: m.setup_state_disabled,
+  incomplete: m.setup_state_incomplete,
+} satisfies Record<string, Label>;
+
+const STEP_LABELS = {
+  banking: m.setup_step_bank,
+  claim: m.setup_step_claim,
+  email: m.setup_step_email,
+  finish: m.setup_step_finish,
+} satisfies Record<string, Label>;
+
+const VARIANT_LABELS = {
+  disabled: m.setup_variant_disabled,
+  "enable-banking": m.setup_variant_enable_banking,
+  powens: m.setup_variant_powens,
+  resend: m.setup_variant_resend,
+  smtp: m.setup_variant_smtp,
+} satisfies Record<string, Label>;
+
+const VARIANT_GUIDE_PATHS: Record<string, string> = {
+  "enable-banking": "/self-hosting/bank-providers#enable-banking",
+  powens: "/self-hosting/bank-providers#powens",
+  resend: "/self-hosting/email#resend",
+  smtp: "/self-hosting/email#smtp",
+};
+
+const STATE_COLOURS: Record<string, BadgeColor> = {
+  configured: "green",
+  disabled: "gray",
+  incomplete: "amber",
+};
+
+const read = (table: Record<string, Label>, key: string): string =>
+  table[key]?.() ?? key;
+
+export const fieldLabel = (key: string): string => read(FIELD_LABELS, key);
+
+export const integrationTitle = (id: string): string =>
+  read(INTEGRATION_TITLES, id);
+
+export const integrationDescription = (id: string): string =>
+  read(INTEGRATION_DESCRIPTIONS, id);
+
+export const variantLabel = (id: string): string => read(VARIANT_LABELS, id);
+
+export const stateLabel = (id: string): string => read(STATE_LABELS, id);
+
+export const stepLabel = (id: string): string => read(STEP_LABELS, id);
+
+export const stateColour = (id: string): BadgeColor =>
+  STATE_COLOURS[id] ?? "gray";
+
+const SETUP_TOKEN_DOCS_PATH = "/self-hosting/setup#get-the-setup-link";
+
+const ENVIRONMENT_DOCS_PATH =
+  "/self-hosting/setup#a-value-in-the-environment-wins";
+
+const RESTART_DOCS_PATH =
+  "/self-hosting/troubleshooting#the-server-does-not-restart-after-setup";
+
+export const setupTokenDocsUrl = (): string =>
+  `${docsUrl()}${SETUP_TOKEN_DOCS_PATH}`;
+
+export const environmentDocsUrl = (): string =>
+  `${docsUrl()}${ENVIRONMENT_DOCS_PATH}`;
+
+export const restartDocsUrl = (): string => `${docsUrl()}${RESTART_DOCS_PATH}`;
+
+export const variantGuideUrl = (id: string): string | null => {
+  const path = VARIANT_GUIDE_PATHS[id];
+
+  return path === undefined ? null : `${docsUrl()}${path}`;
+};
diff --git a/apps/web/src/pages/setup/model/outcome.ts b/apps/web/src/pages/setup/model/outcome.ts
new file mode 100644
index 00000000..ae1373ef
--- /dev/null
+++ b/apps/web/src/pages/setup/model/outcome.ts
@@ -0,0 +1,78 @@
+import { m } from "@/paraglide/messages.js";
+
+import { fieldLabel } from "./labels";
+
+export interface SaveOutcome {
+  checked?: boolean;
+  detail?: string;
+  keys?: string[];
+  outcome: string;
+  reason?: string;
+  status?: number | null;
+}
+
+const SUCCESS_OUTCOMES: ReadonlySet<string> = new Set([
+  "saved",
+  "verified",
+  "nothing-to-save",
+]);
+
+export const isFailedOutcome = (outcome: SaveOutcome | undefined): boolean =>
+  outcome !== undefined && !SUCCESS_OUTCOMES.has(outcome.outcome);
+
+const fieldList = (keys: readonly string[] | undefined): string =>
+  (keys ?? []).map(fieldLabel).join(", ");
+
+const probeFailureMessage = (
+  outcome: SaveOutcome,
+  provider: string
+): string => {
+  if (outcome.reason === "rejected") {
+    return m.setup_error_probe_rejected({ provider });
+  }
+
+  if (outcome.reason === "invalid") {
+    return m.setup_error_invalid();
+  }
+
+  return m.setup_error_probe_unreachable({ provider });
+};
+
+export const outcomeMessage = (
+  outcome: SaveOutcome,
+  provider: string
+): string => {
+  if (outcome.outcome === "verified") {
+    return m.setup_verified();
+  }
+
+  if (outcome.outcome === "saved" || outcome.outcome === "nothing-to-save") {
+    return outcome.checked === true
+      ? m.setup_verified()
+      : m.setup_saved_unchecked();
+  }
+
+  if (outcome.outcome === "missing-fields") {
+    return m.setup_error_missing_fields({ keys: fieldList(outcome.keys) });
+  }
+
+  if (outcome.outcome === "environment-owned") {
+    return m.setup_error_environment_owned();
+  }
+
+  if (outcome.outcome === "invalid") {
+    return m.setup_error_invalid();
+  }
+
+  return probeFailureMessage(outcome, provider);
+};
+
+export const outcomeDetail = (outcome: SaveOutcome): string | null => {
+  if (outcome.detail === undefined || outcome.detail === "") {
+    return null;
+  }
+
+  return outcome.status === null || outcome.status === undefined
+    ? outcome.detail
+    : `${outcome.status}: ${outcome.detail}`;
+};
diff --git a/apps/web/src/pages/setup/model/use-setup.ts b/apps/web/src/pages/setup/model/use-setup.ts
new file mode 100644
index 00000000..59464b67
--- /dev/null
+++ b/apps/web/src/pages/setup/model/use-setup.ts
@@ -0,0 +1,177 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useNavigate } from "@tanstack/react-router";
+import { useState } from "react";
+import { toast } from "sonner";
+
+import { m } from "@/paraglide/messages.js";
+import { orpc } from "@/shared/api";
+import { authClient } from "@/shared/auth";
+
+import { waitForAppliedServer } from "../api/wait-for-server";
+import { clearLinkedSetupToken } from "../lib/setup-token-link";
+
+const CLAIM_STEP = "claim";
+
+const ADVANCING_OUTCOMES: ReadonlySet<string> = new Set([
+  "saved",
+  "nothing-to-save",
+]);
+
+const FINISH_STEP = "finish";
+
+export const useSetup = () => {
+  const queryClient = useQueryClient();
+  const navigate = useNavigate();
+  const [restartPhase, setRestartPhase] = useState<
+    "idle" | "reconnecting" | "stalled"
+  >("idle");
+
+  const [chosenStep, setChosenStep] = useState<string | null>(null);
+  const [direction, setDirection] = useState<1 | -1>(1);
+
+  const status = useQuery(orpc.instance.status.queryOptions());
+
+  const isClaimed = status.data?.claimed ?? false;
+
+  const configuration = useQuery(
+    orpc.instance.describe.queryOptions({
+      enabled: isClaimed && restartPhase === "idle",
+      retry: false,
+    })
+  );
+
+  const integrationSteps =
+    configuration.data?.integrations.map((integration) => integration.id) ?? [];
+
+  const steps = [
+    ...(isClaimed ? [] : [CLAIM_STEP]),
+    ...integrationSteps,
+    FINISH_STEP,
+  ];
+
+  const stepId = chosenStep ?? steps[0] ?? CLAIM_STEP;
+  const stepIndex = Math.max(steps.indexOf(stepId), 0);
+
+  const goTo = (next: string, heading: 1 | -1) => {
+    setDirection(heading);
+    setChosenStep(next);
+  };
+
+  const handleSignOut = async () => {
+    await authClient.signOut();
+    await navigate({ to: "/login" });
+  };
+
+  const handleNext = () => {
+    const next = steps[stepIndex + 1];
+
+    if (next !== undefined) {
+      goTo(next, 1);
+    }
+  };
+
+  const handleBack = () => {
+    const previous = steps[stepIndex - 1];
+
+    if (previous !== undefined) {
+      goTo(previous, -1);
+    }
+  };
+
+  const refreshConfiguration = async () => {
+    await queryClient.invalidateQueries({
+      queryKey: orpc.instance.describe.queryOptions().queryKey,
+    });
+  };
+
+  const claim = useMutation(
+    orpc.instance.claim.mutationOptions({
+      onError: () => toast.error(m.setup_claim_error()),
+      onSuccess: async () => {
+        clearLinkedSetupToken();
+        toast.success(m.setup_claim_success());
+
+        await queryClient.invalidateQueries({
+          queryKey: orpc.instance.status.queryOptions().queryKey,
+        });
+
+        await refreshConfiguration();
+        setChosenStep(null);
+        setDirection(1);
+      },
+    })
+  );
+
+  const save = useMutation(
+    orpc.instance.save.mutationOptions({
+      onSuccess: async (outcome) => {
+        if (outcome.outcome === "saved") {
+          await refreshConfiguration();
+        }
+
+        if (ADVANCING_OUTCOMES.has(outcome.outcome)) {
+          handleNext();
+        }
+      },
+    })
+  );
+
+  const check = useMutation(orpc.instance.check.mutationOptions());
+
+  const enterApp = async () => {
+    await queryClient.invalidateQueries({
+      queryKey: orpc.instance.status.queryOptions().queryKey,
+    });
+
+    toast.success(m.setup_completed_toast());
+    await navigate({ to: "/" });
+  };
+
+  const reconnect = async () => {
+    setRestartPhase("reconnecting");
+
+    const isBack = await waitForAppliedServer();
+
+    if (!isBack) {
+      setRestartPhase("stalled");
+
+      return;
+    }
+
+    await refreshConfiguration();
+    await enterApp();
+  };
+
+  const complete = useMutation(
+    orpc.instance.complete.mutationOptions({
+      onSuccess: async ({ restarting }) => {
+        if (restarting) {
+          await reconnect();
+
+          return;
+        }
+
+        await enterApp();
+      },
+    })
+  );
+
+  return {
+    check,
+    claim,
+    complete,
+    configuration,
+    direction,
+    handleBack,
+    handleNext,
+    handleSignOut,
+    isClaimed,
+    isPending: status.isPending || (isClaimed && configuration.isPending),
+    reconnect,
+    restartPhase,
+    save,
+    stepId,
+    stepIndex,
+    steps,
+  };
+};
diff --git a/apps/web/src/pages/setup/ui/claim-step.tsx b/apps/web/src/pages/setup/ui/claim-step.tsx
new file mode 100644
index 00000000..371e8ec0
--- /dev/null
+++ b/apps/web/src/pages/setup/ui/claim-step.tsx
@@ -0,0 +1,66 @@
+import { Button } from "@freenary/ui/components/button";
+import { Field, FieldLabel } from "@freenary/ui/components/field";
+import { Input } from "@freenary/ui/components/input";
+import { useEffect, useId, useState } from "react";
+
+import { m } from "@/paraglide/messages.js";
+import { WizardStepHeader } from "@/shared/ui/wizard-step-header";
+
+import {
+  readLinkedSetupToken,
+  subscribeToSetupTokenLink,
+} from "../lib/setup-token-link";
+import { setupTokenDocsUrl } from "../model/labels";
+
+interface ClaimStepProps {
+  isSubmitting: boolean;
+  onClaim: (token: string) => void;
+}
+
+export const ClaimStep = ({ isSubmitting, onClaim }: ClaimStepProps) => {
+  const inputId = useId();
+  const [token, setToken] = useState(readLinkedSetupToken);
+
+  useEffect(
+    () => subscribeToSetupTokenLink(() => setToken(readLinkedSetupToken())),
+    []
+  );
+
+  const trimmed = token.trim();
+
+  return (
+    <div className="flex flex-col gap-6">
+      <WizardStepHeader
+        description={m.setup_claim_description()}
+        title={m.setup_claim_title()}
+      />
+      <Field>
+        <FieldLabel htmlFor={inputId}>{m.setup_claim_token_label()}</FieldLabel>
+        <Input
+          autoComplete="off"
+          id={inputId}
+          onChange={(event) => setToken(event.target.value)}
+          value={token}
+        />
+      </Field>
+      <div className="flex items-center justify-between gap-3">
+        <a
+          className="text-muted-foreground hover:text-foreground text-sm underline underline-offset-2"
+          href={setupTokenDocsUrl()}
+          rel="noopener noreferrer"
+          target="_blank"
+        >
+          {m.setup_claim_token_help()}
+        </a>
+        <Button
+          disabled={trimmed.length === 0}
+          loading={isSubmitting}
+          onClick={() => onClaim(trimmed)}
+          type="button"
+        >
+          {m.setup_claim_submit()}
+        </Button>
+      </div>
+    </div>
+  );
+};
diff --git a/apps/web/src/pages/setup/ui/environment-summary.tsx b/apps/web/src/pages/setup/ui/environment-summary.tsx
new file mode 100644
index 00000000..72df4c1f
--- /dev/null
+++ b/apps/web/src/pages/setup/ui/environment-summary.tsx
@@ -0,0 +1,153 @@
+import { Button } from "@freenary/ui/components/button";
+import { Elevated } from "@freenary/ui/lib/elevated";
+import { useIcon } from "@freenary/ui/lib/icon-context";
+import { RiCheckLine } from "@remixicon/react";
+
+import { m } from "@/paraglide/messages.js";
+import { remixIcon } from "@/shared/lib/remix-icon";
+import { WizardStepHeader } from "@/shared/ui/wizard-step-header";
+
+import {
+  environmentDocsUrl,
+  integrationDescription,
+  integrationTitle,
+  variantLabel,
+} from "../model/labels";
+import type { SaveOutcome } from "../model/outcome";
+import { OutcomeNotice } from "./outcome-notice";
+import type { SetupIntegrationDescriptor } from "./provider-step";
+import { ServerValueRow } from "./server-value-row";
+
+const ENVIRONMENT_SOURCE = "environment";
+const SURFACE_RADIUS = "rounded-xl";
+const SURFACE_STEP = 1;
+const READY_ICON_SIZE = 16;
+const CheckIcon = remixIcon(RiCheckLine);
+
+interface EnvironmentSummaryProps {
+  descriptor: SetupIntegrationDescriptor;
+  isChecking: boolean;
+  isFirstStep: boolean;
+  onBack: () => void;
+  onCheck: (variantId: string) => void;
+  onNext: () => void;
+  outcome: SaveOutcome | undefined;
+}
+
+export const EnvironmentSummary = ({
+  descriptor,
+  isChecking,
+  isFirstStep,
+  onBack,
+  onCheck,
+  onNext,
+  outcome,
+}: EnvironmentSummaryProps) => {
+  const ArrowLeftIcon = useIcon("arrow-left");
+  const variantId = descriptor.selectedVariantId;
+  const provider = variantLabel(variantId);
+  const variant = descriptor.variants.find((entry) => entry.id === variantId);
+  const fields = variant?.fields ?? [];
+  const providerIsDefault =
+    descriptor.discriminantSource !== ENVIRONMENT_SOURCE;
+
+  const environmentKeys = [
+    ...(providerIsDefault ? [] : [descriptor.discriminantKey]),
+    ...fields.flatMap((field) =>
+      field.source === ENVIRONMENT_SOURCE ? [field.key] : []
+    ),
+  ];
+
+  return (
+    <div className="flex flex-col gap-6">
+      <WizardStepHeader
+        description={integrationDescription(descriptor.id)}
+        title={integrationTitle(descriptor.id)}
+      />
+
+      <Elevated className={SURFACE_RADIUS} offset={SURFACE_STEP}>
+        <div className="flex flex-col gap-3 p-4">
+          <div className="flex items-start gap-3">
+            <span className="bg-primary text-primary-foreground mt-0.5 flex size-6 shrink-0 items-center justify-center rounded-full">
+              <CheckIcon size={READY_ICON_SIZE} />
+            </span>
+            <div className="flex flex-col gap-1">
+              <p className="font-medium">
+                {m.setup_environment_ready({ provider })}
+              </p>
+              <p className="text-muted-foreground text-sm">
+                {m.setup_environment_line()}{" "}
+                <a
+                  className="text-foreground underline underline-offset-2"
+                  href={environmentDocsUrl()}
+                  rel="noopener noreferrer"
+                  target="_blank"
+                >
+                  {m.setup_environment_learn_more()}
+                </a>
+              </p>
+            </div>
+          </div>
+
+          <details className="ps-9">
+            <summary className="text-muted-foreground hover:text-foreground cursor-pointer text-sm select-none">
+              {m.setup_show_details()}
+            </summary>
+            <dl className="divide-border mt-2 flex flex-col divide-y">
+              {fields.map((field) => (
+                <ServerValueRow
+                  descriptor={field}
+                  key={field.key}
+                  showsSource={false}
+                />
+              ))}
+            </dl>
+            <p className="text-muted-foreground mt-2 font-mono text-xs break-words">
+              {m.setup_environment_variables({
+                keys: environmentKeys.join(", "),
+              })}
+            </p>
+            {providerIsDefault ? (
+              <p className="text-muted-foreground mt-1 text-xs">
+                {m.setup_environment_default_provider({
+                  key: descriptor.discriminantKey,
+                  provider,
+                })}
+              </p>
+            ) : null}
+          </details>
+        </div>
+      </Elevated>
+
+      <OutcomeNotice outcome={outcome} provider={provider} />
+
+      <div className="flex items-center justify-between gap-3">
+        {isFirstStep ? (
+          <span />
+        ) : (
+          <Button
+            leadingIcon={ArrowLeftIcon}
+            onClick={onBack}
+            type="button"
+            variant="ghost"
+          >
+            {m.setup_back()}
+          </Button>
+        )}
+        <div className="flex items-center gap-2">
+          <Button
+            loading={isChecking}
+            onClick={() => onCheck(variantId)}
+            type="button"
+            variant="ghost"
+          >
+            {m.setup_test_connection()}
+          </Button>
+          <Button onClick={onNext} type="button">
+            {m.setup_continue()}
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+};
diff --git a/apps/web/src/pages/setup/ui/finish-step.tsx b/apps/web/src/pages/setup/ui/finish-step.tsx
new file mode 100644
index 00000000..00efcd1e
--- /dev/null
+++ b/apps/web/src/pages/setup/ui/finish-step.tsx
@@ -0,0 +1,86 @@
+import { Badge } from "@freenary/ui/components/badge";
+import { Button } from "@freenary/ui/components/button";
+import { Elevated } from "@freenary/ui/lib/elevated";
+import { useIcon } from "@freenary/ui/lib/icon-context";
+
+import { m } from "@/paraglide/messages.js";
+import { WizardStepHeader } from "@/shared/ui/wizard-step-header";
+
+import {
+  integrationTitle,
+  stateColour,
+  stateLabel,
+  variantLabel,
+} from "../model/labels";
+import type { SetupIntegrationDescriptor } from "./provider-step";
+
+const DISABLED_STATE = "disabled";
+const SURFACE_RADIUS = "rounded-xl";
+const SURFACE_STEP = 1;
+
+interface FinishStepProps {
+  integrations: SetupIntegrationDescriptor[];
+  isCompleting: boolean;
+  onBack: () => void;
+  onFinish: () => void;
+}
+
+export const FinishStep = ({
+  integrations,
+  isCompleting,
+  onBack,
+  onFinish,
+}: FinishStepProps) => {
+  const ArrowLeftIcon = useIcon("arrow-left");
+
+  return (
+    <div className="flex flex-col gap-6">
+      <WizardStepHeader
+        description={m.setup_finish_description()}
+        title={m.setup_finish_title()}
+      />
+
+      <Elevated className={SURFACE_RADIUS} offset={SURFACE_STEP}>
+        <dl className="divide-border flex flex-col divide-y px-4">
+          {integrations.map((integration) => (
+            <div
+              className="flex items-center justify-between gap-3 py-3"
+              key={integration.id}
+            >
+              <dt className="text-sm">{integrationTitle(integration.id)}</dt>
+              <dd className="flex items-center gap-2">
+                {integration.state === DISABLED_STATE ? null : (
+                  <span className="text-muted-foreground text-sm">
+                    {variantLabel(integration.selectedVariantId)}
+                  </span>
+                )}
+                {integration.configuredBy === "environment" ? (
+                  <span className="text-muted-foreground text-xs">
+                    {m.setup_set_by_server()}
+                  </span>
+                ) : null}
+                <Badge color={stateColour(integration.state)}>
+                  {stateLabel(integration.state)}
+                </Badge>
+              </dd>
+            </div>
+          ))}
+        </dl>
+      </Elevated>
+
+      <div className="flex items-center justify-between gap-3">
+        <Button
+          leadingIcon={ArrowLeftIcon}
+          onClick={onBack}
+          type="button"
+          variant="ghost"
+        >
+          {m.setup_back()}
+        </Button>
+        <Button loading={isCompleting} onClick={onFinish} type="button">
+          {m.setup_finish_action()}
+        </Button>
+      </div>
+    </div>
+  );
+};
diff --git a/apps/web/src/pages/setup/ui/guide-link.tsx b/apps/web/src/pages/setup/ui/guide-link.tsx
new file mode 100644
index 00000000..e6c8f019
--- /dev/null
+++ b/apps/web/src/pages/setup/ui/guide-link.tsx
@@ -0,0 +1,33 @@
+import { RiArrowRightUpLine } from "@remixicon/react";
+
+import { m } from "@/paraglide/messages.js";
+import { remixIcon } from "@/shared/lib/remix-icon";
+
+import { variantGuideUrl, variantLabel } from "../model/labels";
+
+const EXTERNAL_ICON_SIZE = 14;
+const ExternalIcon = remixIcon(RiArrowRightUpLine);
+
+interface GuideLinkProps {
+  variantId: string;
+}
+
+export const GuideLink = ({ variantId }: GuideLinkProps) => {
+  const guideUrl = variantGuideUrl(variantId);
+
+  if (guideUrl === null) {
+    return null;
+  }
+
+  return (
+    <a
+      className="text-foreground inline-flex items-center gap-1 self-start text-sm underline underline-offset-2"
+      href={guideUrl}
+      rel="noopener noreferrer"
+      target="_blank"
+    >
+      {m.setup_variant_guide({ provider: variantLabel(variantId) })}
+      <ExternalIcon className="shrink-0" size={EXTERNAL_ICON_SIZE} />
+    </a>
+  );
+};
diff --git a/apps/web/src/pages/setup/ui/outcome-notice.tsx b/apps/web/src/pages/setup/ui/outcome-notice.tsx
new file mode 100644
index 00000000..112d458f
--- /dev/null
+++ b/apps/web/src/pages/setup/ui/outcome-notice.tsx
@@ -0,0 +1,75 @@
+import { cn } from "@freenary/ui/lib/utils";
+import { RiCheckLine, RiErrorWarningLine } from "@remixicon/react";
+import { AnimatePresence, motion } from "motion/react";
+
+import { m } from "@/paraglide/messages.js";
+import { remixIcon } from "@/shared/lib/remix-icon";
+
+import type { SaveOutcome } from "../model/outcome";
+import {
+  isFailedOutcome,
+  outcomeDetail,
+  outcomeMessage,
+} from "../model/outcome";
+
+const NOTICE_ICON_SIZE = 16;
+const ICON_SWAP = { bounce: 0, duration: 0.3, type: "spring" } as const;
+const ICON_HIDDEN = { filter: "blur(4px)", opacity: 0, scale: 0.25 };
+const ICON_SHOWN = { filter: "blur(0px)", opacity: 1, scale: 1 };
+const AlertIcon = remixIcon(RiErrorWarningLine);
+const CheckIcon = remixIcon(RiCheckLine);
+
+interface OutcomeNoticeProps {
+  outcome: SaveOutcome | undefined;
+  provider: string;
+}
+
+export const OutcomeNotice = ({ outcome, provider }: OutcomeNoticeProps) => {
+  if (outcome === undefined) {
+    return null;
+  }
+
+  const isFailure = isFailedOutcome(outcome);
+  const detail = isFailure ? outcomeDetail(outcome) : null;
+
+  return (
+    <div className="flex flex-col gap-1.5">
+      <p
+        className={cn(
+          "flex items-start gap-2 text-sm",
+          isFailure ? "text-destructive" : "text-muted-foreground"
+        )}
+        role={isFailure ? "alert" : "status"}
+      >
+        <span className="relative mt-0.5 flex size-4 shrink-0">
+          <AnimatePresence initial={false} mode="popLayout">
+            <motion.span
+              animate={ICON_SHOWN}
+              aria-hidden="true"
+              className="absolute inset-0 flex"
+              exit={ICON_HIDDEN}
+              initial={ICON_HIDDEN}
+              key={isFailure ? "failure" : "success"}
+              transition={ICON_SWAP}
+            >
+              {isFailure ? (
+                <AlertIcon size={NOTICE_ICON_SIZE} />
+              ) : (
+                <CheckIcon size={NOTICE_ICON_SIZE} />
+              )}
+            </motion.span>
+          </AnimatePresence>
+        </span>
+        <span className="min-w-0">{outcomeMessage(outcome, provider)}</span>
+      </p>
+      {detail === null ? null : (
+        <details className="text-muted-foreground ps-6 text-xs">
+          <summary className="cursor-pointer select-none">
+            {m.setup_show_details()}
+          </summary>
+          <p className="mt-1 font-mono break-words">{detail}</p>
+        </details>
+      )}
+    </div>
+  );
+};
diff --git a/apps/web/src/pages/setup/ui/provider-choice.tsx b/apps/web/src/pages/setup/ui/provider-choice.tsx
new file mode 100644
index 00000000..9c5e71c7
--- /dev/null
+++ b/apps/web/src/pages/setup/ui/provider-choice.tsx
@@ -0,0 +1,105 @@
+import { Button } from "@freenary/ui/components/button";
+import { useIcon } from "@freenary/ui/lib/icon-context";
+import { cn } from "@freenary/ui/lib/utils";
+import { useId } from "react";
+
+import { m } from "@/paraglide/messages.js";
+import { WizardStepHeader } from "@/shared/ui/wizard-step-header";
+
+import {
+  integrationDescription,
+  integrationTitle,
+  variantLabel,
+} from "../model/labels";
+import type { SetupIntegrationDescriptor } from "./provider-step";
+
+const SKIP_VARIANT = "disabled";
+
+const skipLast = (variantId: string): number =>
+  variantId === SKIP_VARIANT ? 1 : 0;
+
+interface ProviderChoiceProps {
+  chosen: string;
+  descriptor: SetupIntegrationDescriptor;
+  isBusy: boolean;
+  isFirstStep: boolean;
+  onBack: () => void;
+  onChoose: (variantId: string) => void;
+  onContinue: () => void;
+}
+
+export const ProviderChoice = ({
+  chosen,
+  descriptor,
+  isBusy,
+  isFirstStep,
+  onBack,
+  onChoose,
+  onContinue,
+}: ProviderChoiceProps) => {
+  const ArrowLeftIcon = useIcon("arrow-left");
+  const groupName = useId();
+  const titleId = useId();
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div id={titleId}>
+        <WizardStepHeader
+          description={integrationDescription(descriptor.id)}
+          title={integrationTitle(descriptor.id)}
+        />
+      </div>
+
+      <fieldset aria-labelledby={titleId} className="flex flex-col gap-2">
+        {descriptor.variants
+          .toSorted((first, second) => skipLast(first.id) - skipLast(second.id))
+          .map((variant) => {
+            const isChosen = variant.id === chosen;
+
+            return (
+              <label
+                className={cn(
+                  "flex cursor-pointer items-center gap-3 rounded-xl px-4 py-3 text-sm ring-1 transition-[box-shadow,background-color] duration-150 ease-out",
+                  "has-[:focus-visible]:ring-ring has-[:focus-visible]:ring-2",
+                  isChosen
+                    ? "bg-accent ring-primary"
+                    : "ring-border hover:bg-accent/60"
+                )}
+                key={variant.id}
+              >
+                <input
+                  checked={isChosen}
+                  className="accent-primary size-4 shrink-0"
+                  name={groupName}
+                  onChange={() => onChoose(variant.id)}
+                  type="radio"
+                  value={variant.id}
+                />
+                <span className={isChosen ? "font-medium" : undefined}>
+                  {variantLabel(variant.id)}
+                </span>
+              </label>
+            );
+          })}
+      </fieldset>
+
+      <div className="flex items-center justify-between gap-3">
+        {isFirstStep ? (
+          <span />
+        ) : (
+          <Button
+            leadingIcon={ArrowLeftIcon}
+            onClick={onBack}
+            type="button"
+            variant="ghost"
+          >
+            {m.setup_back()}
+          </Button>
+        )}
+        <Button loading={isBusy} onClick={onContinue} type="button">
+          {m.setup_continue()}
+        </Button>
+      </div>
+    </div>
+  );
+};
diff --git a/apps/web/src/pages/setup/ui/provider-credentials.tsx b/apps/web/src/pages/setup/ui/provider-credentials.tsx
new file mode 100644
index 00000000..bce50cde
--- /dev/null
+++ b/apps/web/src/pages/setup/ui/provider-credentials.tsx
@@ -0,0 +1,144 @@
+import { Button } from "@freenary/ui/components/button";
+import { Elevated } from "@freenary/ui/lib/elevated";
+import { useIcon } from "@freenary/ui/lib/icon-context";
+import { useState } from "react";
+
+import { m } from "@/paraglide/messages.js";
+import { WizardStepHeader } from "@/shared/ui/wizard-step-header";
+
+import { variantLabel } from "../model/labels";
+import type { SaveOutcome } from "../model/outcome";
+import { GuideLink } from "./guide-link";
+import { OutcomeNotice } from "./outcome-notice";
+import type { SetupVariantDescriptor } from "./provider-step";
+import { ServerValueRow } from "./server-value-row";
+import type { SetupFieldDescriptor } from "./setup-field";
+import { SetupField } from "./setup-field";
+
+const ENVIRONMENT_SOURCE = "environment";
+const SURFACE_RADIUS = "rounded-xl";
+const SURFACE_STEP = 1;
+const PROBE_FAILED = "probe-failed";
+
+interface ProviderCredentialsProps {
+  isBusy: boolean;
+  onBack: () => void;
+  onEdit: () => void;
+  onSave: (values: Record<string, string>, checkFirst: boolean) => void;
+  outcome: SaveOutcome | undefined;
+  variant: SetupVariantDescriptor;
+}
+
+const isFromServer = (field: SetupFieldDescriptor): boolean =>
+  field.source === ENVIRONMENT_SOURCE;
+
+const filledValuesOf = (
+  fields: readonly SetupFieldDescriptor[]
+): Record<string, string> =>
+  Object.fromEntries(
+    fields.flatMap((field) =>
+      field.value === null || isFromServer(field)
+        ? []
+        : [[field.key, field.value]]
+    )
+  );
+
+export const ProviderCredentials = ({
+  isBusy,
+  onBack,
+  onEdit,
+  onSave,
+  outcome,
+  variant,
+}: ProviderCredentialsProps) => {
+  const ArrowLeftIcon = useIcon("arrow-left");
+  const [values, setValues] = useState(() => filledValuesOf(variant.fields));
+  const provider = variantLabel(variant.id);
+
+  const fromServer = variant.fields.filter(isFromServer);
+  const editable = variant.fields.filter((field) => !isFromServer(field));
+  const required = editable.filter((field) => field.required);
+  const optional = editable.filter((field) => !field.required);
+  const checkFailed = outcome?.outcome === PROBE_FAILED;
+
+  const renderField = (field: SetupFieldDescriptor) => (
+    <SetupField
+      descriptor={field}
+      key={field.key}
+      onChange={(key, next) => {
+        onEdit();
+        setValues((held) => ({ ...held, [key]: next }));
+      }}
+      value={values[field.key]}
+    />
+  );
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <WizardStepHeader
+          description={m.setup_credentials_description({ provider })}
+          title={m.setup_credentials_title({ provider })}
+        />
+        <GuideLink variantId={variant.id} />
+      </div>
+
+      {fromServer.length > 0 ? (
+        <Elevated className={SURFACE_RADIUS} offset={SURFACE_STEP}>
+          <dl className="divide-border flex flex-col divide-y px-4">
+            {fromServer.map((field) => (
+              <ServerValueRow descriptor={field} key={field.key} showsSource />
+            ))}
+          </dl>
+        </Elevated>
+      ) : null}
+
+      {required.length > 0 ? (
+        <div className="flex flex-col gap-4">{required.map(renderField)}</div>
+      ) : null}
+
+      {optional.length > 0 ? (
+        <details className="group flex flex-col gap-4">
+          <summary className="text-muted-foreground hover:text-foreground cursor-pointer text-sm select-none">
+            {m.setup_more_options()}
+          </summary>
+          <div className="mt-4 flex flex-col gap-4">
+            {optional.map(renderField)}
+          </div>
+        </details>
+      ) : null}
+
+      <OutcomeNotice outcome={outcome} provider={provider} />
+
+      <div className="flex items-center justify-between gap-3">
+        <Button
+          leadingIcon={ArrowLeftIcon}
+          onClick={onBack}
+          type="button"
+          variant="ghost"
+        >
+          {m.setup_back()}
+        </Button>
+        <div className="flex items-center gap-2">
+          {checkFailed ? (
+            <Button
+              disabled={isBusy}
+              onClick={() => onSave(values, false)}
+              type="button"
+              variant="secondary"
+            >
+              {m.setup_save_anyway()}
+            </Button>
+          ) : null}
+          <Button
+            loading={isBusy}
+            onClick={() => onSave(values, true)}
+            type="button"
+          >
+            {m.setup_save_and_continue()}
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+};
diff --git a/apps/web/src/pages/setup/ui/provider-step.tsx b/apps/web/src/pages/setup/ui/provider-step.tsx
new file mode 100644
index 00000000..34cf7d65
--- /dev/null
+++ b/apps/web/src/pages/setup/ui/provider-step.tsx
@@ -0,0 +1,101 @@
+import { useState } from "react";
+
+import type { SaveOutcome } from "../model/outcome";
+import { ProviderChoice } from "./provider-choice";
+import { ProviderCredentials } from "./provider-credentials";
+import type { SetupFieldDescriptor } from "./setup-field";
+
+const SKIP_VARIANT = "disabled";
+
+export interface SetupVariantDescriptor {
+  fields: SetupFieldDescriptor[];
+  id: string;
+}
+
+export interface SetupIntegrationDescriptor {
+  configuredBy: string | null;
+  discriminantKey: string;
+  discriminantSource: string;
+  id: string;
+  selectedVariantId: string;
+  state: string;
+  variants: SetupVariantDescriptor[];
+}
+
+interface ProviderStepProps {
+  descriptor: SetupIntegrationDescriptor;
+  isBusy: boolean;
+  isFirstStep: boolean;
+  onBack: () => void;
+  onEdit: () => void;
+  onSave: (
+    variantId: string,
+    values: Record<string, string>,
+    checkFirst: boolean
+  ) => void;
+  onSkip: () => void;
+  outcome: SaveOutcome | undefined;
+}
+
+const defaultChoiceOf = (descriptor: SetupIntegrationDescriptor): string => {
+  if (descriptor.selectedVariantId !== SKIP_VARIANT) {
+    return descriptor.selectedVariantId;
+  }
+
+  const firstProvider = descriptor.variants.find(
+    (variant) => variant.id !== SKIP_VARIANT
+  );
+
+  return firstProvider?.id ?? SKIP_VARIANT;
+};
+
+export const ProviderStep = ({
+  descriptor,
+  isBusy,
+  isFirstStep,
+  onBack,
+  onEdit,
+  onSave,
+  onSkip,
+  outcome,
+}: ProviderStepProps) => {
+  const [chosen, setChosen] = useState(() => defaultChoiceOf(descriptor));
+  const [isConfiguring, setIsConfiguring] = useState(false);
+  const variant = descriptor.variants.find((entry) => entry.id === chosen);
+
+  if (isConfiguring && variant !== undefined) {
+    return (
+      <ProviderCredentials
+        isBusy={isBusy}
+        onBack={() => {
+          onEdit();
+          setIsConfiguring(false);
+        }}
+        onEdit={onEdit}
+        onSave={(values, checkFirst) => onSave(chosen, values, checkFirst)}
+        outcome={outcome}
+        variant={variant}
+      />
+    );
+  }
+
+  return (
+    <ProviderChoice
+      chosen={chosen}
+      descriptor={descriptor}
+      isBusy={isBusy}
+      isFirstStep={isFirstStep}
+      onBack={onBack}
+      onChoose={setChosen}
+      onContinue={() => {
+        if (chosen === SKIP_VARIANT) {
+          onSkip();
+
+          return;
+        }
+
+        setIsConfiguring(true);
+      }}
+    />
+  );
+};
diff --git a/apps/web/src/pages/setup/ui/server-value-row.tsx b/apps/web/src/pages/setup/ui/server-value-row.tsx
new file mode 100644
index 00000000..bb858c1c
--- /dev/null
+++ b/apps/web/src/pages/setup/ui/server-value-row.tsx
@@ -0,0 +1,33 @@
+import { m } from "@/paraglide/messages.js";
+
+import { fieldLabel } from "../model/labels";
+import type { SetupFieldDescriptor } from "./setup-field";
+import { isSecretKind } from "./setup-field";
+
+interface ServerValueRowProps {
+  descriptor: SetupFieldDescriptor;
+  showsSource: boolean;
+}
+
+export const ServerValueRow = ({
+  descriptor,
+  showsSource,
+}: ServerValueRowProps) => {
+  const shown = isSecretKind(descriptor.kind) ? null : descriptor.value;
+
+  return (
+    <div className="flex items-center justify-between gap-3 py-3">
+      <dt className="text-sm">{fieldLabel(descriptor.key)}</dt>
+      <dd className="text-muted-foreground flex min-w-0 items-center gap-2 text-sm">
+        {shown === null ? null : (
+          <code className="font-mono break-all">{shown}</code>
+        )}
+        {showsSource ? (
+          <span className="bg-accent text-foreground shrink-0 rounded-md px-1.5 py-0.5 text-xs">
+            {m.setup_set_by_server()}
+          </span>
+        ) : null}
+      </dd>
+    </div>
+  );
+};
diff --git a/apps/web/src/pages/setup/ui/setup-field.tsx b/apps/web/src/pages/setup/ui/setup-field.tsx
new file mode 100644
index 00000000..4f12ec46
--- /dev/null
+++ b/apps/web/src/pages/setup/ui/setup-field.tsx
@@ -0,0 +1,90 @@
+import { Field, FieldLabel } from "@freenary/ui/components/field";
+import { Input } from "@freenary/ui/components/input";
+import { Switch } from "@freenary/ui/components/switch";
+import { Textarea } from "@freenary/ui/components/textarea";
+import { useId } from "react";
+
+import { m } from "@/paraglide/messages.js";
+
+import { fieldLabel } from "../model/labels";
+
+const TRUE = "true";
+const FALSE = "false";
+const SECRET_ROWS = 6;
+
+export interface SetupFieldDescriptor {
+  key: string;
+  kind: string;
+  present: boolean;
+  required: boolean;
+  source: string;
+  value: string | null;
+}
+
+interface SetupFieldProps {
+  descriptor: SetupFieldDescriptor;
+  onChange: (key: string, value: string) => void;
+  value: string | undefined;
+}
+
+export const isSecretKind = (kind: string): boolean =>
+  kind === "secret" || kind === "secret-block";
+
+const inputType = (kind: string): string => {
+  if (kind === "secret") {
+    return "password";
+  }
+
+  return kind === "port" ? "number" : "text";
+};
+
+export const SetupField = ({
+  descriptor,
+  onChange,
+  value,
+}: SetupFieldProps) => {
+  const inputId = useId();
+  const secret = isSecretKind(descriptor.kind);
+  const secretPlaceholder =
+    secret && descriptor.present ? m.setup_secret_unchanged_hint() : undefined;
+
+  const held = value ?? descriptor.value ?? "";
+
+  if (descriptor.kind === "toggle") {
+    return (
+      <Field orientation="horizontal">
+        <FieldLabel htmlFor={inputId}>{fieldLabel(descriptor.key)}</FieldLabel>
+        <Switch
+          checked={held === TRUE}
+          id={inputId}
+          onCheckedChange={(checked) =>
+            onChange(descriptor.key, checked ? TRUE : FALSE)
+          }
+        />
+      </Field>
+    );
+  }
+
+  return (
+    <Field>
+      <FieldLabel htmlFor={inputId}>{fieldLabel(descriptor.key)}</FieldLabel>
+      {descriptor.kind === "secret-block" ? (
+        <Textarea
+          id={inputId}
+          onChange={(event) => onChange(descriptor.key, event.target.value)}
+          placeholder={secretPlaceholder}
+          rows={SECRET_ROWS}
+          value={value ?? ""}
+        />
+      ) : (
+        <Input
+          id={inputId}
+          onChange={(event) => onChange(descriptor.key, event.target.value)}
+          placeholder={secretPlaceholder}
+          type={inputType(descriptor.kind)}
+          value={secret ? (value ?? "") : held}
+        />
+      )}
+    </Field>
+  );
+};
diff --git a/apps/web/src/pages/setup/ui/setup-page.tsx b/apps/web/src/pages/setup/ui/setup-page.tsx
new file mode 100644
index 00000000..2178bf07
--- /dev/null
+++ b/apps/web/src/pages/setup/ui/setup-page.tsx
@@ -0,0 +1,225 @@
+import { Button } from "@freenary/ui/components/button";
+import {
+  Empty,
+  EmptyDescription,
+  EmptyTitle,
+} from "@freenary/ui/components/empty";
+import { Spinner } from "@freenary/ui/components/spinner";
+import { useState } from "react";
+import { toast } from "sonner";
+
+import { m } from "@/paraglide/messages.js";
+import { WizardShell } from "@/shared/ui/wizard-shell";
+import { WizardStepper } from "@/shared/ui/wizard-stepper";
+
+import { restartDocsUrl, stepLabel } from "../model/labels";
+import type { SaveOutcome } from "../model/outcome";
+import { useSetup } from "../model/use-setup";
+import { ClaimStep } from "./claim-step";
+import { EnvironmentSummary } from "./environment-summary";
+import { FinishStep } from "./finish-step";
+import { ProviderStep } from "./provider-step";
+import { SetupWizardSkeleton } from "./setup-wizard-skeleton";
+
+const CLAIM_STEP = "claim";
+const FINISH_STEP = "finish";
+const SKIP_VARIANT = "disabled";
+
+export const SetupPage = () => {
+  const setup = useSetup();
+  const [outcomes, setOutcomes] = useState<Record<string, SaveOutcome>>({});
+
+  const described = setup.configuration.data;
+  const integrations = described?.integrations ?? [];
+  const stepLabels = setup.steps.map((id) => () => stepLabel(id));
+
+  const stepper = (
+    <WizardStepper
+      current={setup.stepIndex}
+      label={m.setup_progress_label()}
+      steps={stepLabels}
+    />
+  );
+
+  const activeIntegration = integrations.find(
+    (integration) => integration.id === setup.stepId
+  );
+
+  const body = () => {
+    if (setup.restartPhase === "reconnecting") {
+      return (
+        <Empty>
+          <Spinner />
+          <EmptyTitle>{m.setup_applying_title()}</EmptyTitle>
+          <EmptyDescription>{m.setup_applying_description()}</EmptyDescription>
+        </Empty>
+      );
+    }
+
+    if (setup.restartPhase === "stalled") {
+      return (
+        <Empty>
+          <EmptyTitle>{m.setup_stalled_title()}</EmptyTitle>
+          <EmptyDescription>{m.setup_stalled_description()}</EmptyDescription>
+          <div className="flex items-center gap-3">
+            <Button onClick={() => setup.reconnect()} type="button">
+              {m.setup_try_again()}
+            </Button>
+            <a
+              className="text-muted-foreground hover:text-foreground text-sm underline underline-offset-2"
+              href={restartDocsUrl()}
+              rel="noopener noreferrer"
+              target="_blank"
+            >
+              {m.setup_view_troubleshooting()}
+            </a>
+          </div>
+        </Empty>
+      );
+    }
+
+    if (setup.configuration.isError) {
+      return (
+        <Empty>
+          <EmptyTitle>{m.setup_not_operator_title()}</EmptyTitle>
+          <EmptyDescription>
+            {m.setup_not_operator_description()}
+          </EmptyDescription>
+        </Empty>
+      );
+    }
+
+    if (setup.stepId === CLAIM_STEP) {
+      return (
+        <ClaimStep
+          isSubmitting={setup.claim.isPending}
+          onClaim={(token) => setup.claim.mutate({ token })}
+        />
+      );
+    }
+
+    if (setup.stepId === FINISH_STEP) {
+      return (
+        <FinishStep
+          integrations={integrations}
+          isCompleting={setup.complete.isPending}
+          onBack={setup.handleBack}
+          onFinish={() => setup.complete.mutate({})}
+        />
+      );
+    }
+
+    if (activeIntegration === undefined) {
+      return null;
+    }
+
+    const integrationId = activeIntegration.id;
+
+    const recordOutcome = (outcome: SaveOutcome) =>
+      setOutcomes((held) => ({ ...held, [integrationId]: outcome }));
+
+    const clearOutcome = () =>
+      setOutcomes((held) =>
+        Object.fromEntries(
+          Object.entries(held).filter(([id]) => id !== integrationId)
+        )
+      );
+
+    if (activeIntegration.configuredBy === "environment") {
+      return (
+        <EnvironmentSummary
+          descriptor={activeIntegration}
+          isChecking={setup.check.isPending}
+          isFirstStep={setup.stepIndex === 0}
+          onBack={setup.handleBack}
+          onCheck={(variantId) =>
+            setup.check.mutate(
+              { integrationId, values: {}, variantId },
+              { onSuccess: recordOutcome }
+            )
+          }
+          onNext={setup.handleNext}
+          outcome={outcomes[integrationId]}
+        />
+      );
+    }
+
+    const saveValues = (variantId: string, values: Record<string, string>) =>
+      setup.save.mutate(
+        { integrationId, values, variantId },
+        {
+          onSuccess: (outcome) => {
+            recordOutcome(outcome);
+
+            if (outcome.outcome === "saved") {
+              toast.warning(m.setup_saved_unchecked());
+            }
+          },
+        }
+      );
+
+    const checkThenSave = (variantId: string, values: Record<string, string>) =>
+      setup.check.mutate(
+        { integrationId, values, variantId },
+        {
+          onSuccess: (outcome) => {
+            if (outcome.outcome !== "verified") {
+              recordOutcome(outcome);
+
+              return;
+            }
+
+            setup.save.mutate(
+              { integrationId, values, variantId },
+              {
+                onSuccess: (saved) =>
+                  recordOutcome({ ...saved, checked: true }),
+              }
+            );
+          },
+        }
+      );
+
+    return (
+      <ProviderStep
+        descriptor={activeIntegration}
+        isBusy={setup.check.isPending || setup.save.isPending}
+        isFirstStep={setup.stepIndex === 0}
+        onBack={setup.handleBack}
+        onEdit={clearOutcome}
+        onSave={(variantId, values, checkFirst) =>
+          checkFirst
+            ? checkThenSave(variantId, values)
+            : saveValues(variantId, values)
+        }
+        onSkip={() =>
+          activeIntegration.configuredBy === "instance"
+            ? setup.save.mutate({
+                integrationId,
+                values: {},
+                variantId: SKIP_VARIANT,
+              })
+            : setup.handleNext()
+        }
+        outcome={outcomes[integrationId]}
+      />
+    );
+  };
+
+  return (
+    <WizardShell
+      direction={setup.direction}
+      isPending={setup.isPending}
+      skeleton={<SetupWizardSkeleton />}
+      stepKey={setup.stepId}
+      stepper={stepper}
+      toolbar={
+        <Button onClick={setup.handleSignOut} type="button" variant="ghost">
+          {m.account_sign_out()}
+        </Button>
+      }
+    >
+      {body()}
+    </WizardShell>
+  );
+};
diff --git a/apps/web/src/pages/setup/ui/setup-wizard-skeleton.tsx b/apps/web/src/pages/setup/ui/setup-wizard-skeleton.tsx
new file mode 100644
index 00000000..bec0c0f6
--- /dev/null
+++ b/apps/web/src/pages/setup/ui/setup-wizard-skeleton.tsx
@@ -0,0 +1,41 @@
+import { Skeleton } from "@freenary/ui/components/skeleton";
+import { useSize } from "@freenary/ui/lib/size-context";
+import { cn } from "@freenary/ui/lib/utils";
+
+import { m } from "@/paraglide/messages.js";
+
+const FIELD_ROWS = [0, 1, 2];
+
+export const SetupWizardSkeleton = () => {
+  const { control } = useSize();
+
+  return (
+    <div aria-busy="true">
+      <output className="sr-only">{m.setup_loading()}</output>
+      <div aria-hidden="true" className="flex flex-col gap-8">
+        <div className="flex items-center justify-center gap-3">
+          <div className="flex items-center gap-2.5">
+            <Skeleton className="size-7 rounded-full" />
+            <Skeleton className="h-4 w-14" />
+          </div>
+          <Skeleton className="h-px w-8 sm:w-12" />
+          <Skeleton className="size-7 rounded-full" />
+          <Skeleton className="h-px w-8 sm:w-12" />
+          <Skeleton className="size-7 rounded-full" />
+        </div>
+
+        <div className="flex flex-col gap-2">
+          <Skeleton className="h-6 w-48" />
+          <Skeleton className="h-4 w-72" />
+        </div>
+
+        {FIELD_ROWS.map((row) => (
+          <div className="flex flex-col gap-2" key={row}>
+            <Skeleton className="h-4 w-24" />
+            <Skeleton className={cn(control, "w-full rounded-md")} />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
diff --git a/apps/web/src/shared/ui/wizard-shell.tsx b/apps/web/src/shared/ui/wizard-shell.tsx
new file mode 100644
index 00000000..44ccb0e0
--- /dev/null
+++ b/apps/web/src/shared/ui/wizard-shell.tsx
@@ -0,0 +1,117 @@
+import { spring } from "@freenary/ui/lib/springs";
+import { SURFACE_BG } from "@freenary/ui/lib/surface-classes";
+import { SurfaceProvider } from "@freenary/ui/lib/surface-context";
+import { cn } from "@freenary/ui/lib/utils";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import type { ReactNode } from "react";
+
+import { LocaleSwitcher } from "@/shared/ui/locale-switcher";
+import { ThemeSwitcher } from "@/shared/ui/theme-switcher";
+
+const STEP_SHIFT_PX = 16;
+const NO_STEP_SHIFT_PX = 0;
+const STEP_CROSSFADE_MASK_BLUR = "blur(4px)";
+const NO_BLUR = "blur(0px)";
+
+interface StepMotion {
+  direction: 1 | -1;
+  shift: number;
+}
+
+const stepVariants = {
+  center: { filter: NO_BLUR, opacity: 1, transition: spring.slow, x: 0 },
+  enter: ({ direction, shift }: StepMotion) => ({
+    filter: shift ? STEP_CROSSFADE_MASK_BLUR : NO_BLUR,
+    opacity: 0,
+    x: direction * shift,
+  }),
+  exit: ({ direction, shift }: StepMotion) => ({
+    filter: shift ? STEP_CROSSFADE_MASK_BLUR : NO_BLUR,
+    opacity: 0,
+    transition: spring.slow.exit,
+    x: -direction * shift,
+  }),
+};
+
+interface WizardShellProps {
+  children: ReactNode;
+  direction: 1 | -1;
+  isPending: boolean;
+  skeleton: ReactNode;
+  stepKey: string;
+  stepper: ReactNode;
+  toolbar: ReactNode;
+}
+
+export const WizardShell = ({
+  children,
+  direction,
+  isPending,
+  skeleton,
+  stepKey,
+  stepper,
+  toolbar,
+}: WizardShellProps) => {
+  const prefersReducedMotion = useReducedMotion();
+  const stepMotion: StepMotion = {
+    direction,
+    shift: prefersReducedMotion ? NO_STEP_SHIFT_PX : STEP_SHIFT_PX,
+  };
+
+  return (
+    <SurfaceProvider value={1}>
+      <main className={cn(SURFACE_BG[1], "flex min-h-svh flex-col")}>
+        <div className="flex items-center justify-end gap-1 px-4 py-3">
+          <ThemeSwitcher />
+          <LocaleSwitcher />
+          {toolbar}
+        </div>
+
+        <div className="flex flex-1 items-center justify-center px-4 py-10">
+          <div className="relative flex w-full max-w-md flex-col gap-8">
+            <AnimatePresence initial={false} mode="popLayout">
+              {isPending ? (
+                <motion.div
+                  key="skeleton"
+                  animate={{ opacity: 1 }}
+                  exit={{ opacity: 0, transition: spring.moderate.exit }}
+                  initial={{ opacity: 0 }}
+                  transition={spring.moderate}
+                >
+                  {skeleton}
+                </motion.div>
+              ) : (
+                <motion.div
+                  key="wizard"
+                  animate={{ opacity: 1 }}
+                  className="flex flex-col gap-8"
+                  exit={{ opacity: 0, transition: spring.moderate.exit }}
+                  initial={{ opacity: 0 }}
+                  transition={spring.moderate}
+                >
+                  {stepper}
+                  <AnimatePresence
+                    custom={stepMotion}
+                    initial={false}
+                    mode="popLayout"
+                  >
+                    <motion.div
+                      key={stepKey}
+                      animate="center"
+                      custom={stepMotion}
+                      exit="exit"
+                      initial="enter"
+                      variants={stepVariants}
+                    >
+                      {children}
+                    </motion.div>
+                  </AnimatePresence>
+                </motion.div>
+              )}
+            </AnimatePresence>
+          </div>
+        </div>
+      </main>
+    </SurfaceProvider>
+  );
+};
diff --git a/apps/web/src/pages/onboarding/ui/onboarding-step-header.tsx b/apps/web/src/shared/ui/wizard-step-header.tsx
similarity index 69%
rename from apps/web/src/pages/onboarding/ui/onboarding-step-header.tsx
rename to apps/web/src/shared/ui/wizard-step-header.tsx
index bdce19bc..ddb34554 100644
--- a/apps/web/src/pages/onboarding/ui/onboarding-step-header.tsx
+++ b/apps/web/src/shared/ui/wizard-step-header.tsx
@@ -1,12 +1,12 @@
-interface OnboardingStepHeaderProps {
+interface WizardStepHeaderProps {
   description: string;
   title: string;
 }
 
-export const OnboardingStepHeader = ({
+export const WizardStepHeader = ({
   description,
   title,
-}: OnboardingStepHeaderProps) => (
+}: WizardStepHeaderProps) => (
   <div className="flex flex-col gap-1.5">
     <h1 className="text-2xl font-bold tracking-tight">{title}</h1>
     <p className="text-muted-foreground text-sm">{description}</p>
diff --git a/apps/web/src/pages/onboarding/ui/onboarding-stepper.tsx b/apps/web/src/shared/ui/wizard-stepper.tsx
similarity index 65%
rename from apps/web/src/pages/onboarding/ui/onboarding-stepper.tsx
rename to apps/web/src/shared/ui/wizard-stepper.tsx
index 093ee300..4b888548 100644
--- a/apps/web/src/pages/onboarding/ui/onboarding-stepper.tsx
+++ b/apps/web/src/shared/ui/wizard-stepper.tsx
@@ -7,43 +7,46 @@ import { cn } from "@freenary/ui/lib/utils";
 import { AnimatePresence, motion } from "motion/react";
 import { Fragment } from "react";
 
-import { m } from "@/paraglide/messages.js";
+const LABELS_FIT_UP_TO = 3;
+const ICON_SWAP = { bounce: 0, duration: 0.3, type: "spring" } as const;
+const ICON_HIDDEN = { filter: "blur(4px)", opacity: 0, scale: 0.25 };
+const ICON_SHOWN = { filter: "blur(0px)", opacity: 1, scale: 1 };
 
-interface OnboardingStepperProps {
+interface WizardStepperProps {
   current: number;
+  label: string;
   steps: readonly (() => string)[];
 }
 
-export const OnboardingStepper = ({
+export const WizardStepper = ({
   current,
+  label,
   steps,
-}: OnboardingStepperProps) => {
+}: WizardStepperProps) => {
   const CheckIcon = useIcon("check");
   const size = useSize();
   const substrate = useSurface();
+  const showsEveryLabel = steps.length <= LABELS_FIT_UP_TO;
 
   return (
-    <ol
-      aria-label={m.onboarding_progress_label()}
-      className="flex items-center justify-center"
-    >
+    <ol aria-label={label} className="flex items-center justify-center">
       {steps.map((step, index) => {
-        const label = step();
+        const stepName = step();
         const isComplete = index < current;
         const isCurrent = index === current;
 
         return (
-          <Fragment key={label}>
+          <Fragment key={stepName}>
             <li className="flex items-center gap-2.5">
               <motion.span
                 aria-current={isCurrent ? "step" : undefined}
                 className={cn(
-                  "flex aspect-square shrink-0 items-center justify-center ring-1",
+                  "flex aspect-square shrink-0 items-center justify-center rounded-full ring-1",
                   size.control,
                   size.text,
                   isComplete &&
                     "bg-primary text-primary-foreground ring-primary",
-                  isCurrent && "bg-secondary text-primary ring-primary",
+                  isCurrent && "bg-secondary text-foreground ring-primary",
                   !(isComplete || isCurrent) &&
                     cn(
                       SURFACE_BG[substrate],
@@ -55,35 +58,37 @@ export const OnboardingStepper = ({
                 <AnimatePresence initial={false} mode="wait">
                   {isComplete ? (
                     <motion.span
-                      animate={{ opacity: 1, scale: 1 }}
-                      exit={{ opacity: 0, transition: spring.fast.exit }}
-                      initial={{ opacity: 0, scale: 0.75 }}
+                      animate={ICON_SHOWN}
+                      exit={ICON_HIDDEN}
+                      initial={ICON_HIDDEN}
                       key="check"
-                      transition={spring.fast}
+                      transition={ICON_SWAP}
                     >
                       <CheckIcon size={size.icon} />
                     </motion.span>
                   ) : (
                     <motion.span
-                      animate={{ opacity: 1 }}
-                      exit={{ opacity: 0, transition: spring.fast.exit }}
-                      initial={{ opacity: 0 }}
+                      animate={ICON_SHOWN}
+                      exit={ICON_HIDDEN}
+                      initial={ICON_HIDDEN}
                       key="index"
-                      transition={spring.fast}
+                      transition={ICON_SWAP}
                     >
                       {index + 1}
                     </motion.span>
                   )}
                 </AnimatePresence>
               </motion.span>
-              <span
-                className={cn(
-                  size.text,
-                  isCurrent ? "text-foreground" : "text-muted-foreground"
-                )}
-              >
-                {label}
-              </span>
+              {showsEveryLabel || isCurrent ? (
+                <span
+                  className={cn(
+                    size.text,
+                    isCurrent ? "text-foreground" : "text-muted-foreground"
+                  )}
+                >
+                  {stepName}
+                </span>
+              ) : null}
             </li>
             {index < steps.length - 1 && (
               <span
diff --git a/bun.lock b/bun.lock
index 76751a59..d0cb83fe 100644
--- a/bun.lock
+++ b/bun.lock
@@ -74,6 +74,7 @@
         "@freenary/auth": "workspace:*",
         "@freenary/db": "workspace:*",
         "@freenary/env": "workspace:*",
+        "@freenary/instance-config": "workspace:*",
         "@orpc/openapi": "catalog:",
         "@orpc/server": "catalog:",
         "@orpc/zod": "catalog:",
@@ -157,7 +158,9 @@
         "@ai-sdk/openai-compatible": "^3.0.43",
         "@freenary/auth": "workspace:*",
         "@freenary/db": "workspace:*",
+        "@freenary/email": "workspace:*",
         "@freenary/env": "workspace:*",
+        "@freenary/instance-config": "workspace:*",
         "@openuidev/lang-core": "0.2.17",
         "@orpc/client": "catalog:",
         "@orpc/openapi": "catalog:",
@@ -219,6 +222,7 @@
       "name": "@freenary/email",
       "dependencies": {
         "@freenary/env": "workspace:*",
+        "@freenary/instance-config": "workspace:*",
         "dotenv": "catalog:",
         "effect": "catalog:",
         "nodemailer": "^7.0.10",
@@ -245,6 +249,22 @@
         "typescript": "catalog:",
       },
     },
+    "packages/instance-config": {
+      "name": "@freenary/instance-config",
+      "dependencies": {
+        "@freenary/db": "workspace:*",
+        "@freenary/env": "workspace:*",
+        "@t3-oss/env-core": "^0.13.11",
+        "dotenv": "catalog:",
+        "effect": "catalog:",
+        "zod": "catalog:",
+      },
+      "devDependencies": {
+        "@freenary/config": "workspace:*",
+        "@types/bun": "catalog:",
+        "typescript": "catalog:",
+      },
+    },
     "packages/ui": {
       "name": "@freenary/ui",
       "version": "0.0.0",
@@ -537,6 +557,8 @@
 
     "@freenary/env": ["@freenary/env@workspace:packages/env"],
 
+    "@freenary/instance-config": ["@freenary/instance-config@workspace:packages/instance-config"],
+
     "@freenary/ui": ["@freenary/ui@workspace:packages/ui"],
 
     "@fuma-translate/react": ["@fuma-translate/react@1.0.2", "", { "peerDependencies": { "@types/react": "*", "react": "^19.2.0", "react-dom": "^19.2.0" }, "optionalPeers": ["@types/react"] }, "sha512-uOiOtBx3nRXR8Nu1GzBf1tApgF1FErDBTHxRIAQeyQdyOoZbrNRN6H4kDCWObY4qyGeGbHydG0DHzgeUgFDMIw=="],
diff --git a/docs/engineering/platform.md b/docs/engineering/platform.md
index 1714b251..eaac9c2e 100644
--- a/docs/engineering/platform.md
+++ b/docs/engineering/platform.md
@@ -38,6 +38,22 @@ Durable facts that the code cannot carry in a name. Each bullet names the module
 - `packages/auth/src/providers.ts › genericOAuthProviders` — the account's identity is the verified `sub` claim, so `requireIdTokenVerification` is on and the discovery document has to publish the JWKS that proves it.
 - `packages/auth/src/providers.ts › APPLE_CALLBACK_ORIGIN` — Apple posts its callback from its own origin, so `appleid.apple.com` must be a trusted origin whenever Apple is configured.
 
+## Instance configuration
+
+- `packages/instance-config` — a package of its own rather than a second entry point of `@freenary/env`, because resolving a stored setting needs Prisma and `packages/db` already imports `@freenary/env` for `DATABASE_URL`. Putting the store beside the schema would make the two packages depend on each other. The direction that holds is `db → env`, then `instance-config → db, env`, then `auth`, `email` and `api` on top.
+- `packages/instance-config/src/resolve.ts › stored` — a top-level `await`, not an exported `init()` the server calls first. ESM evaluates a module's dependencies before its own body, so every consumer reads a resolved `settings` synchronously and no call site can observe the unresolved value. An explicit `init()` cannot give that guarantee here: `apps/server/src/index.ts` imports `@freenary/auth`, which builds the Better Auth instance in its module body, and a static import is hoisted above any `await` the entry file could run first.
+- `packages/instance-config/src/resolve.ts › loadStoredSettings` — an unreachable database stops the start in production and falls back to the environment alone everywhere else. The development fallback is what lets `bun test packages/email` run with no database, because `packages/email/src/registry.ts` reaches this module through `settings`. In production the same fallback would boot an instance with every provider silently off, which is worse than a crash loop the operator can read.
+- `packages/instance-config/src/resolve.ts › settings` — built by handing the merged record back to `createEnv` with the same `serverEnvSchema`, rather than by parsing each key by hand. One schema then covers both sources, so a stored `SMTP_PORT` is coerced to a number exactly as an environment one is, and `settings` carries the same type as `env`.
+- `packages/instance-config/src/candidate.ts › overlayOf` — the environment wins over the stored row, and never the other way round. An operator who holds secrets in Kubernetes, in Vault or in a file keeps that setup working, and the setup screen shows the field as owned by the environment instead of writing a row the boot would ignore.
+- `packages/instance-config/src/seal.ts › seal` — the row name is the GCM associated data, so a ciphertext copied from `SMTP_PASSWORD` into `SMTP_USER` fails to open rather than decrypting into the wrong variable. The key is HKDF-derived from `BETTER_AUTH_SECRET`, which already encrypts the two-factor columns, so no second secret enters the deployment and a changed secret disables the stored settings in the same way it disables the two-factor enrolments.
+- `packages/api/src/routers/instance.ts › save` — the probe runs before the write, and a failed probe writes nothing. Home Assistant's config-flow guidance is the source: an entry created first and checked afterwards leaves broken entries a user has to delete by hand. The same ordering is why the candidate record is validated against the schema before the probe, so a value the next boot would reject cannot reach the table.
+- `packages/api/src/routers/instance.ts › restart` — the process exits and the supervisor starts it again, because every consumer of a provider credential binds it at module scope: `packages/email/src/registry.ts › emailProvider`, `packages/auth/src/providers.ts › socialProviders` and the Better Auth instance the Elysia route captures. `docker-compose.yml` sets `restart: unless-stopped` on `server`, and Kubernetes and systemd behave the same way. Making these lazy and invalidatable is the change that would drop the restart.
+- `packages/instance-config/src/claim.ts › issueSetupToken` — a new token at each start while the instance is unclaimed, rather than one token kept until it is used. Only the hash is stored, so a token issued once could never be printed again, and an operator who missed the first log line would have no way to read it.
+- `packages/instance-config/src/claim.ts › issueSetupToken`, `FREENARY_SETUP_TOKEN` — a chosen token is hashed in place of a random one at every start, so a restart keeps it valid, and the server never prints it: a secret from the environment would otherwise reach every log collector. The schema allows only `[A-Za-z0-9_-]`, because the web app reads the token raw from the link fragment; a `+` or a `%` would not survive the trip.
+- `apps/web/src/pages/setup/lib/setup-token-link.ts › watchSetupTokenLink` — the token rides in the fragment (`/setup#token=…`) so no server, proxy log or `Referer` sees it. A guest who opens the link is redirected to `/login`, the browser carries the fragment over the redirect, and the root route moves the token into `sessionStorage` before sign-up navigates away; `ClaimStep` reads it from there, and the claim clears it. The `hashchange` listener is not optional: an operator already on `/setup` who pastes the link into the same tab causes a fragment-only navigation, which reloads nothing, so `ClaimStep` subscribes to the capture instead of reading once at mount.
+- `packages/instance-config/src/claim.ts › redeemSetupToken` — the `updateMany` matched on both the token hash and `claimedAt: null` is the mutex, not a preceding read of the row. A wrong token and an already-claimed instance both match no row, so the two cases are indistinguishable to the caller and two concurrent claims cannot both succeed.
+- `apps/web/src/app/api/get-instance.ts › getInstanceSetup` — the router context carries the setup state beside the viewer, because the redirect has to happen in `beforeLoad` rather than in a component: a signed-in visitor whose instance is unconfigured must reach `/setup` without the protected shell rendering first. `completedAt`, not `claimedAt`, is the gate, so an operator who claimed the instance and stopped half way is sent back to the step they left.
+
 ## API server entry
 
 - `apps/server/src/index.ts › isCallerRefusal` — only faults reach the console. A refused call is an answer the caller asked for — an unauthenticated read, a rejected input — and printing its stack buries the crashes worth reading; the request's own wide event already records that it was refused.
@@ -56,6 +72,7 @@ Durable facts that the code cannot carry in a name. Each bullet names the module
 - `scripts/dev.ts › readBranch` — `git rev-parse --abbrev-ref HEAD` prints the literal `HEAD` on a detached HEAD, which is why that ref is treated as "no branch" and the worktree directory name is used instead.
 - `scripts/dev.ts › readEnvOverride` — a value already exported in the shell outranks the worktree-local `.env`, which is read with one regexp so the script needs no dotenv dependency. `FREENARY_SLUG=… bun run dev:up` therefore renames a stack without editing a file.
 - `scripts/env-sync.ts › main` — a variable used to be declared in four places: the schema, `.env.example`, the tables of `self-hosting/configuration.mdx` and the `x-app-env` pass-through list. Only the schema had a gate, so the other three drifted silently and a reader met a variable the code had renamed or dropped. The schema is now the one authored source and both artifacts are generated from it, which turns a missing description, example or `onError` into a failed build instead of a reader's surprise.
+- `.docker/dockerfile.dev` — the workspace `package.json` files are copied one line at a time, before the source, so that `bun install` caches on the manifests alone. A new workspace therefore needs a line here or the image build fails at `bun install --frozen-lockfile` with `listed in bun.lock but not on disk`, naming every workspace that depends on the missing one. Docker has no glob that preserves the directory layout, so the list stays manual; the production images escape it because they `COPY . .` and cache on the bun install cache mount instead.
 - `docker-compose.dev.yml › x-app-env-file`, `x-app-env` — the anchor carried 32 `FOO: ${FOO:-}` lines so that a contributor's own `.env` reached the container, and every new variable needed a compose edit nobody remembered. `env_file` with `required: false` passes the whole optional root `.env` instead, and Compose gives `environment` precedence over `env_file`, so the six values derived from the worktree identity stay authoritative while nothing else has to be listed at all.
 
 ## Documentation site
diff --git a/docs/engineering/web-app.md b/docs/engineering/web-app.md
index e1bbfa0e..681d101c 100644
--- a/docs/engineering/web-app.md
+++ b/docs/engineering/web-app.md
@@ -46,6 +46,7 @@ Durable facts that the code cannot carry in a name. Each bullet names the module
 - `apps/web/steiger.config.ts`, `apps/fumadocs/steiger.config.ts` — `bun run lint:fsd` must run from the app directory: steiger reads a config only when its directory is the working directory, and silently falls back to its own defaults otherwise, which passes while checking nothing.
 - `apps/web/src/app/routes/__root.tsx › Route.beforeLoad` — the `viewer` is answered once per page load from the request's own cookies, so `/login`, `/onboarding` and `/_auth` can redirect before the first byte. In the browser it is deliberately `UNKNOWN_VIEWER`: after hydration the live session belongs to the browser, and a stale server answer would fight `AuthGate`.
 - `apps/web/src/app/routes/login.tsx`, `onboarding.tsx`, `_auth/route.tsx › Route.beforeLoad` — each redirects a `guest` or a `member` only; `unknown` falls through on purpose to `AuthGate`, which holds the live session.
+- `apps/web/src/features/auth-gate/ui/auth-gate.tsx › AuthGate`, `isSetupUnsettled` — the browser-side twin of the `instance` check in those guards. Sign-in lands with a client-side navigation, where `instance` is `unknown`, so the gate reads `instance.status` itself and sends a `member` or `onboarding` audience to `/setup` while setup is not complete. It holds every other redirect until that answer arrives: the onboarding status usually answers first, and routing on it alone flashes `/onboarding` before `/setup`. A server render that already answered `ready` skips the wait.
 - `apps/web/src/app/routes/__root.tsx › Route.head` with `apps/web/src/shared/config/server-url.ts › publicServerUrlScript` — the script must be injected through `head` because it has to run before the module scripts: the API clients are built at module scope in the browser and read `window.__FREENARY_SERVER_URL__` from it. `PUBLIC_SERVER_URL` in the web server's environment therefore wins at request time and one image serves any deployment; unset, the build-time `VITE_SERVER_URL` stays in force. Client and server read the same value back, so the head matches on both sides of hydration.
 - `apps/web/src/shared/config/server-url.ts › escapeForInlineScript` — `<` cannot appear raw in an inline `<script>`, even inside a string literal, because the HTML parser ends the element at `</`. The URL is `JSON.stringify`d with `<` rewritten to `\u003c`.
 - `apps/web/src/shared/lib/is-server.ts › isServer` — `import.meta.env.SSR` is a Vite build-time constant (verified: it inlines to `true` in the SSR build and `false` in the client build), so the environment is decided at import time instead of probed with `typeof window`.
diff --git a/packages/api/package.json b/packages/api/package.json
index d48b7408..066b93bf 100644
--- a/packages/api/package.json
+++ b/packages/api/package.json
@@ -20,7 +20,9 @@
     "@ai-sdk/openai-compatible": "^3.0.43",
     "@freenary/auth": "workspace:*",
     "@freenary/db": "workspace:*",
+    "@freenary/email": "workspace:*",
     "@freenary/env": "workspace:*",
+    "@freenary/instance-config": "workspace:*",
     "@openuidev/lang-core": "0.2.17",
     "@orpc/client": "catalog:",
     "@orpc/openapi": "catalog:",
diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
index 2276735c..b8f79d08 100644
--- a/packages/api/src/index.ts
+++ b/packages/api/src/index.ts
@@ -1,3 +1,4 @@
+import prisma from "@freenary/db";
 import { ORPCError, os } from "@orpc/server";
 
 import type { Context } from "./context";
@@ -19,3 +20,22 @@ const requireAuth = o.middleware(({ context, next }) => {
 });
 
 export const protectedProcedure = publicProcedure.use(requireAuth);
+
+const requireOperator = o.middleware(async ({ context, next }) => {
+  if (!context.session?.user) {
+    throw new ORPCError("UNAUTHORIZED");
+  }
+
+  const account = await prisma.user.findUnique({
+    select: { role: true },
+    where: { id: context.session.user.id },
+  });
+
+  if (account?.role !== "OPERATOR") {
+    throw new ORPCError("FORBIDDEN");
+  }
+
+  return next({ context: { session: context.session } });
+});
+
+export const operatorProcedure = publicProcedure.use(requireOperator);
diff --git a/packages/api/src/instance/mask.test.ts b/packages/api/src/instance/mask.test.ts
new file mode 100644
index 00000000..c852eec5
--- /dev/null
+++ b/packages/api/src/instance/mask.test.ts
@@ -0,0 +1,15 @@
+import { expect, test } from "bun:test";
+
+import { maskEnvironmentValue } from "./mask";
+
+test("keeps four characters on each side of a long value", () => {
+  expect(maskEnvironmentValue("client-1234567890abcd")).toBe("clie…abcd");
+});
+
+test("hides a value of eight characters in full", () => {
+  expect(maskEnvironmentValue("12345678")).toBe("…");
+});
+
+test("hides an empty value in full", () => {
+  expect(maskEnvironmentValue("")).toBe("…");
+});
diff --git a/packages/api/src/instance/mask.ts b/packages/api/src/instance/mask.ts
new file mode 100644
index 00000000..442165c2
--- /dev/null
+++ b/packages/api/src/instance/mask.ts
@@ -0,0 +1,10 @@
+const VISIBLE_EDGE = 4;
+const ELLIPSIS = "…";
+
+export const maskEnvironmentValue = (value: string): string => {
+  if (value.length <= VISIBLE_EDGE * 2) {
+    return ELLIPSIS;
+  }
+
+  return `${value.slice(0, VISIBLE_EDGE)}${ELLIPSIS}${value.slice(-VISIBLE_EDGE)}`;
+};
diff --git a/packages/api/src/instance/merge.test.ts b/packages/api/src/instance/merge.test.ts
new file mode 100644
index 00000000..5fb9c806
--- /dev/null
+++ b/packages/api/src/instance/merge.test.ts
@@ -0,0 +1,300 @@
+import { describe, expect, test } from "bun:test";
+
+import type { Integration } from "@freenary/instance-config/integrations";
+import {
+  findIntegration,
+  findVariant,
+} from "@freenary/instance-config/integrations";
+import { Option } from "effect";
+
+import type { OwnedByEnvironment } from "./merge";
+import {
+  candidateOf,
+  environmentVariantOf,
+  isWhollyOwnedByEnvironment,
+  missingKeysOf,
+  writesOf,
+} from "./merge";
+
+const email: Integration = Option.getOrThrow(findIntegration("email"));
+const banking: Integration = Option.getOrThrow(findIntegration("banking"));
+
+const variantOf = (integration: Integration, id: string) =>
+  Option.getOrThrow(findVariant(integration, id));
+
+const smtp = variantOf(email, "smtp");
+const resend = variantOf(email, "resend");
+const emailOff = variantOf(email, "disabled");
+const powens = variantOf(banking, "powens");
+
+const nothingOwned: OwnedByEnvironment = () => false;
+
+const ownedKeys =
+  (...keys: string[]): OwnedByEnvironment =>
+  (key) =>
+    keys.includes(key);
+
+const SMTP_FORM = {
+  EMAIL_FROM: "Freenary <no-reply@example.test>",
+  SMTP_HOST: "smtp.example.com",
+  SMTP_PORT: "587",
+};
+
+describe("candidateOf", () => {
+  test("writes the discriminant of the chosen variant", () => {
+    const candidate = candidateOf(email, smtp, SMTP_FORM, {}, nothingOwned);
+
+    expect(candidate.EMAIL_PROVIDER).toBe("smtp");
+  });
+
+  test("clears the discriminant for the disabled variant", () => {
+    const candidate = candidateOf(
+      email,
+      emailOff,
+      {},
+      {
+        EMAIL_FROM: "old@example.test",
+        EMAIL_PROVIDER: "smtp",
+      },
+      nothingOwned
+    );
+
+    expect(candidate.EMAIL_PROVIDER).toBeUndefined();
+  });
+
+  test("keeps a stored secret when its field is left empty", () => {
+    const candidate = candidateOf(
+      email,
+      smtp,
+      { ...SMTP_FORM, SMTP_PASSWORD: "" },
+      { SMTP_PASSWORD: "kept-secret" },
+      nothingOwned
+    );
+
+    expect(candidate.SMTP_PASSWORD).toBe("kept-secret");
+  });
+
+  test("replaces a stored secret when its field is filled in", () => {
+    const candidate = candidateOf(
+      email,
+      smtp,
+      { ...SMTP_FORM, SMTP_PASSWORD: "new-secret" },
+      { SMTP_PASSWORD: "kept-secret" },
+      nothingOwned
+    );
+
+    expect(candidate.SMTP_PASSWORD).toBe("new-secret");
+  });
+
+  test("drops a non-secret field that is left empty", () => {
+    const candidate = candidateOf(
+      email,
+      smtp,
+      { ...SMTP_FORM, SMTP_USER: "" },
+      { SMTP_USER: "old-user" },
+      nothingOwned
+    );
+
+    expect(candidate.SMTP_USER).toBeUndefined();
+  });
+
+  test("drops the secrets of the variant the operator moved away from", () => {
+    const candidate = candidateOf(
+      email,
+      resend,
+      {
+        EMAIL_FROM: "a@example.test",
+        RESEND_API_KEY: "re_key",
+      },
+      { SMTP_HOST: "smtp.example.com", SMTP_PASSWORD: "kept-secret" },
+      nothingOwned
+    );
+
+    expect(candidate.SMTP_PASSWORD).toBeUndefined();
+  });
+
+  test("leaves the settings of another integration alone", () => {
+    const candidate = candidateOf(
+      email,
+      smtp,
+      SMTP_FORM,
+      { POWENS_CLIENT_SECRET: "powens-secret" },
+      nothingOwned
+    );
+
+    expect(candidate.POWENS_CLIENT_SECRET).toBe("powens-secret");
+  });
+
+  test("trims a value the operator pasted with spaces", () => {
+    const candidate = candidateOf(
+      banking,
+      powens,
+      {
+        POWENS_CLIENT_ID: " 1234 ",
+        POWENS_CLIENT_SECRET: "secret",
+        POWENS_DOMAIN: "acme-sandbox",
+      },
+      {},
+      nothingOwned
+    );
+
+    expect(candidate.POWENS_CLIENT_ID).toBe("1234");
+  });
+});
+
+describe("writesOf", () => {
+  test("deletes every key of the integration the candidate does not hold", () => {
+    const writes = writesOf(
+      email,
+      { EMAIL_FROM: "a@example.test" },
+      nothingOwned
+    );
+
+    expect(writes.get("SMTP_PASSWORD")).toBeNull();
+  });
+
+  test("touches no key outside the integration", () => {
+    const writes = writesOf(email, { POWENS_DOMAIN: "acme" }, nothingOwned);
+
+    expect(writes.has("POWENS_DOMAIN")).toBe(false);
+  });
+
+  test("never writes a key the environment owns", () => {
+    const writes = writesOf(
+      email,
+      { EMAIL_FROM: "a@example.test", RESEND_API_KEY: "re_key" },
+      ownedKeys("EMAIL_FROM")
+    );
+
+    expect(writes.has("EMAIL_FROM")).toBe(false);
+    expect(writes.get("RESEND_API_KEY")).toBe("re_key");
+  });
+});
+
+describe("environment ownership", () => {
+  test("keeps a value the environment owns out of the candidate", () => {
+    const candidate = candidateOf(
+      email,
+      resend,
+      { EMAIL_FROM: "…", RESEND_API_KEY: "re_key" },
+      {},
+      ownedKeys("EMAIL_FROM")
+    );
+
+    expect(candidate.EMAIL_FROM).toBeUndefined();
+    expect(candidate.RESEND_API_KEY).toBe("re_key");
+  });
+
+  test("leaves the discriminant to the environment that sets it", () => {
+    const candidate = candidateOf(
+      banking,
+      powens,
+      {},
+      {},
+      ownedKeys("BANKING_PROVIDER")
+    );
+
+    expect(candidate.BANKING_PROVIDER).toBeUndefined();
+  });
+
+  test("counts a required field the environment sets as filled", () => {
+    const missing = missingKeysOf(
+      powens,
+      { POWENS_CLIENT_SECRET: "secret" },
+      ownedKeys("POWENS_DOMAIN", "POWENS_CLIENT_ID")
+    );
+
+    expect(missing).toEqual([]);
+  });
+
+  test("reports a required field that nothing fills", () => {
+    const missing = missingKeysOf(resend, {}, ownedKeys("EMAIL_FROM"));
+
+    expect(missing).toEqual(["RESEND_API_KEY"]);
+  });
+
+  test("sees a variant the environment sets in full", () => {
+    const owned = ownedKeys(
+      "BANKING_PROVIDER",
+      "POWENS_DOMAIN",
+      "POWENS_CLIENT_ID",
+      "POWENS_CLIENT_SECRET"
+    );
+
+    expect(isWhollyOwnedByEnvironment(banking, powens, owned)).toBe(true);
+  });
+
+  test("sees a variant with one field left to the screen", () => {
+    const owned = ownedKeys("BANKING_PROVIDER", "POWENS_DOMAIN");
+
+    expect(isWhollyOwnedByEnvironment(banking, powens, owned)).toBe(false);
+  });
+});
+
+describe("environmentVariantOf", () => {
+  const powensFields = ownedKeys(
+    "POWENS_DOMAIN",
+    "POWENS_CLIENT_ID",
+    "POWENS_CLIENT_SECRET"
+  );
+
+  test("finds the default provider when the environment holds its fields", () => {
+    const found = environmentVariantOf(
+      banking,
+      undefined,
+      "powens",
+      powensFields
+    );
+
+    expect(found?.id).toBe("powens");
+  });
+
+  test("finds the provider the environment names", () => {
+    const found = environmentVariantOf(
+      banking,
+      undefined,
+      "powens",
+      ownedKeys(
+        "BANKING_PROVIDER",
+        "POWENS_DOMAIN",
+        "POWENS_CLIENT_ID",
+        "POWENS_CLIENT_SECRET"
+      )
+    );
+
+    expect(found?.id).toBe("powens");
+  });
+
+  test("defers to a provider saved in the app", () => {
+    const found = environmentVariantOf(
+      banking,
+      "enable-banking",
+      "powens",
+      powensFields
+    );
+
+    expect(found).toBeNull();
+  });
+
+  test("ignores a provider with a required field left to the app", () => {
+    const found = environmentVariantOf(
+      banking,
+      undefined,
+      "powens",
+      ownedKeys("POWENS_DOMAIN")
+    );
+
+    expect(found).toBeNull();
+  });
+
+  test("finds nothing when no provider is in force", () => {
+    const found = environmentVariantOf(
+      email,
+      undefined,
+      undefined,
+      ownedKeys("EMAIL_FROM")
+    );
+
+    expect(found).toBeNull();
+  });
+});
diff --git a/packages/api/src/instance/merge.ts b/packages/api/src/instance/merge.ts
new file mode 100644
index 00000000..4fa058be
--- /dev/null
+++ b/packages/api/src/instance/merge.ts
@@ -0,0 +1,117 @@
+import type { StoredSettings } from "@freenary/instance-config/candidate";
+import type {
+  Integration,
+  IntegrationVariant,
+  ServerSettingKey,
+} from "@freenary/instance-config/integrations";
+import { isSecretField, keysOf } from "@freenary/instance-config/integrations";
+
+export type OwnedByEnvironment = (key: ServerSettingKey) => boolean;
+
+export const candidateOf = (
+  integration: Integration,
+  variant: IntegrationVariant,
+  supplied: Readonly<Record<string, string>>,
+  stored: StoredSettings,
+  ownedByEnvironment: OwnedByEnvironment
+): Record<string, string> => {
+  const owned = new Set<string>(keysOf(integration));
+  const candidate: Record<string, string> = {};
+
+  for (const [key, held] of Object.entries(stored)) {
+    if (!owned.has(key)) {
+      candidate[key] = held;
+    }
+  }
+
+  if (
+    variant.discriminantValue !== null &&
+    !ownedByEnvironment(integration.discriminantKey)
+  ) {
+    candidate[integration.discriminantKey] = variant.discriminantValue;
+  }
+
+  for (const field of variant.fields) {
+    const offered = supplied[field.key]?.trim();
+    const kept = stored[field.key];
+
+    if (ownedByEnvironment(field.key)) {
+      continue;
+    }
+
+    if (offered !== undefined && offered !== "") {
+      candidate[field.key] = offered;
+    } else if (isSecretField(field.kind) && kept !== undefined) {
+      candidate[field.key] = kept;
+    }
+  }
+
+  return candidate;
+};
+
+export const missingKeysOf = (
+  variant: IntegrationVariant,
+  candidate: Readonly<Record<string, string>>,
+  ownedByEnvironment: OwnedByEnvironment
+): ServerSettingKey[] =>
+  variant.fields.flatMap((field) =>
+    field.required &&
+    !ownedByEnvironment(field.key) &&
+    candidate[field.key] === undefined
+      ? [field.key]
+      : []
+  );
+
+export const isWhollyOwnedByEnvironment = (
+  integration: Integration,
+  variant: IntegrationVariant,
+  ownedByEnvironment: OwnedByEnvironment
+): boolean =>
+  ownedByEnvironment(integration.discriminantKey) &&
+  variant.fields.every((field) => ownedByEnvironment(field.key));
+
+export const writesOf = (
+  integration: Integration,
+  candidate: Readonly<Record<string, string>>,
+  ownedByEnvironment: OwnedByEnvironment
+): Map<string, string | null> => {
+  const writes = new Map<string, string | null>();
+
+  for (const key of keysOf(integration)) {
+    if (!ownedByEnvironment(key)) {
+      writes.set(key, candidate[key] ?? null);
+    }
+  }
+
+  return writes;
+};
+
+export const environmentVariantOf = (
+  integration: Integration,
+  storedProvider: string | undefined,
+  providerFromEnvironment: string | undefined,
+  ownedByEnvironment: OwnedByEnvironment
+): IntegrationVariant | null => {
+  if (
+    storedProvider !== undefined &&
+    !ownedByEnvironment(integration.discriminantKey)
+  ) {
+    return null;
+  }
+
+  const inForce = integration.variants.find(
+    (variant) =>
+      variant.discriminantValue !== null &&
+      variant.discriminantValue === providerFromEnvironment
+  );
+
+  if (inForce === undefined) {
+    return null;
+  }
+
+  const fullyOwned = inForce.fields.every(
+    (field) => !field.required || ownedByEnvironment(field.key)
+  );
+
+  return fullyOwned ? inForce : null;
+};
diff --git a/packages/api/src/instance/probes.ts b/packages/api/src/instance/probes.ts
new file mode 100644
index 00000000..0005453d
--- /dev/null
+++ b/packages/api/src/instance/probes.ts
@@ -0,0 +1,79 @@
+import { probeEmailSettings } from "@freenary/email/probe";
+import { emailSettingsOf } from "@freenary/email/registry";
+import type { ServerSettings } from "@freenary/instance-config/candidate";
+import { IntegrationProbeFailed } from "@freenary/instance-config/probe";
+import { Effect, Option } from "effect";
+
+import { probeEnableBankingCredentials } from "../providers/enable-banking/probe";
+import { probePowensCredentials } from "../providers/powens/probe";
+
+export type IntegrationProbe = (
+  candidate: ServerSettings
+) => Effect.Effect<void, IntegrationProbeFailed>;
+
+const absent = (
+  integrationId: string,
+  variantId: string,
+  key: string
+): Effect.Effect<never, IntegrationProbeFailed> =>
+  Effect.fail(
+    new IntegrationProbeFailed({
+      integrationId,
+      reason: { detail: key, kind: "invalid" },
+      variantId,
+    })
+  );
+
+const probePowens: IntegrationProbe = (candidate) => {
+  const { POWENS_CLIENT_ID, POWENS_CLIENT_SECRET, POWENS_DOMAIN } = candidate;
+
+  if (
+    POWENS_DOMAIN === undefined ||
+    POWENS_CLIENT_ID === undefined ||
+    POWENS_CLIENT_SECRET === undefined
+  ) {
+    return absent("banking", "powens", "POWENS_DOMAIN");
+  }
+
+  return probePowensCredentials({
+    clientId: POWENS_CLIENT_ID,
+    clientSecret: POWENS_CLIENT_SECRET,
+    domain: POWENS_DOMAIN,
+  });
+};
+
+const probeEnableBanking: IntegrationProbe = (candidate) => {
+  const { ENABLE_BANKING_APP_ID, ENABLE_BANKING_PRIVATE_KEY } = candidate;
+
+  if (
+    ENABLE_BANKING_APP_ID === undefined ||
+    ENABLE_BANKING_PRIVATE_KEY === undefined
+  ) {
+    return absent("banking", "enable-banking", "ENABLE_BANKING_APP_ID");
+  }
+
+  return probeEnableBankingCredentials({
+    appId: ENABLE_BANKING_APP_ID,
+    privateKey: ENABLE_BANKING_PRIVATE_KEY,
+  });
+};
+
+const probeEmail: IntegrationProbe = (candidate) =>
+  probeEmailSettings(emailSettingsOf(candidate));
+
+const nothingToProbe: IntegrationProbe = () => Effect.void;
+
+const probes: Record<string, IntegrationProbe> = {
+  "banking:disabled": nothingToProbe,
+  "banking:enable-banking": probeEnableBanking,
+  "banking:powens": probePowens,
+  "email:disabled": nothingToProbe,
+  "email:resend": probeEmail,
+  "email:smtp": probeEmail,
+};
+
+export const findProbe = (
+  integrationId: string,
+  variantId: string
+): Option.Option<IntegrationProbe> =>
+  Option.fromNullishOr(probes[`${integrationId}:${variantId}`]);
diff --git a/packages/api/src/providers/enable-banking/client.ts b/packages/api/src/providers/enable-banking/client.ts
index e18266c6..2e45043f 100644
--- a/packages/api/src/providers/enable-banking/client.ts
+++ b/packages/api/src/providers/enable-banking/client.ts
@@ -1,9 +1,9 @@
 import { createSign } from "node:crypto";
 
-import { env } from "@freenary/env/server";
+import { settings } from "@freenary/instance-config";
 import { Data, Effect, Match, Option, Schema } from "effect";
 
-interface EnableBankingCredentials {
+export interface EnableBankingCredentials {
   appId: string;
   privateKey: string;
 }
@@ -41,12 +41,12 @@ export class EnableBankingRequestFailed extends Data.TaggedError(
   }
 }
 
-const API_ORIGIN = "https://api.enablebanking.com";
+export const ENABLE_BANKING_ORIGIN = "https://api.enablebanking.com";
 const JWT_AUDIENCE = "api.enablebanking.com";
 const JWT_ISSUER = "enablebanking.com";
 const JWT_LIFETIME_SECONDS = 3600;
 const MILLISECONDS_PER_SECOND = 1000;
-const LITERAL_NEWLINE_ESCAPE = "\\n";
+export const LITERAL_NEWLINE_ESCAPE = "\\n";
 const LONGEST_HISTORY_STRATEGY = "longest";
 const NOT_FOUND = 404;
 
@@ -56,7 +56,7 @@ const base64url = (payload: Buffer | string): string => {
   return buf.toString("base64url");
 };
 
-const createJwt = (appId: string, privateKey: string): string => {
+export const createJwt = (appId: string, privateKey: string): string => {
   const header = base64url(
     JSON.stringify({ alg: "RS256", kid: appId, typ: "JWT" })
   );
@@ -81,8 +81,8 @@ const createJwt = (appId: string, privateKey: string): string => {
 };
 
 const readCredentials = (): Option.Option<EnableBankingCredentials> => {
-  const appId = env.ENABLE_BANKING_APP_ID;
-  const rawKey = env.ENABLE_BANKING_PRIVATE_KEY;
+  const appId = settings.ENABLE_BANKING_APP_ID;
+  const rawKey = settings.ENABLE_BANKING_PRIVATE_KEY;
 
   return appId && rawKey
     ? Option.some({
@@ -125,7 +125,7 @@ const send = Effect.fnUntraced(function* send(
         reason: { detail: String(cause), kind: "unreachable" },
       }),
     try: (signal) =>
-      fetch(`${API_ORIGIN}${path}`, {
+      fetch(`${ENABLE_BANKING_ORIGIN}${path}`, {
         ...init,
         headers: {
           Authorization: `Bearer ${token}`,
diff --git a/packages/api/src/providers/enable-banking/probe.ts b/packages/api/src/providers/enable-banking/probe.ts
new file mode 100644
index 00000000..46d29358
--- /dev/null
+++ b/packages/api/src/providers/enable-banking/probe.ts
@@ -0,0 +1,59 @@
+import type { ProbeFailureReason } from "@freenary/instance-config/probe";
+import { IntegrationProbeFailed } from "@freenary/instance-config/probe";
+import { Effect } from "effect";
+
+import type { EnableBankingCredentials } from "./client";
+import {
+  ENABLE_BANKING_ORIGIN,
+  LITERAL_NEWLINE_ESCAPE,
+  createJwt,
+} from "./client";
+
+const failure = (reason: ProbeFailureReason): IntegrationProbeFailed =>
+  new IntegrationProbeFailed({
+    integrationId: "banking",
+    reason,
+    variantId: "enable-banking",
+  });
+
+const signed = (credentials: EnableBankingCredentials) =>
+  Effect.try({
+    catch: (cause) => failure({ detail: String(cause), kind: "invalid" }),
+    try: () =>
+      createJwt(
+        credentials.appId,
+        credentials.privateKey.replaceAll(LITERAL_NEWLINE_ESCAPE, "\n")
+      ),
+  });
+
+export const probeEnableBankingCredentials = Effect.fn("enableBanking.probe")(
+  function* probeEnableBankingCredentials(
+    credentials: EnableBankingCredentials
+  ) {
+    const token = yield* signed(credentials);
+
+    const response = yield* Effect.tryPromise({
+      catch: (cause) => failure({ detail: String(cause), kind: "unreachable" }),
+      try: (signal) =>
+        fetch(`${ENABLE_BANKING_ORIGIN}/application`, {
+          headers: { Authorization: `Bearer ${token}` },
+          signal,
+        }),
+    });
+
+    if (response.ok) {
+      return;
+    }
+
+    const body = yield* Effect.tryPromise({
+      catch: (cause) => failure({ detail: String(cause), kind: "unreachable" }),
+      try: () => response.text(),
+    });
+
+    return yield* failure({
+      detail: body,
+      kind: "rejected",
+      status: response.status,
+    });
+  }
+);
diff --git a/packages/api/src/providers/powens/client.ts b/packages/api/src/providers/powens/client.ts
index a91a7424..c4cac5c7 100644
--- a/packages/api/src/providers/powens/client.ts
+++ b/packages/api/src/providers/powens/client.ts
@@ -1,7 +1,7 @@
-import { env } from "@freenary/env/server";
+import { settings } from "@freenary/instance-config";
 import { Data, Effect, Match, Option, Schema } from "effect";
 
-interface PowensCredentials {
+export interface PowensCredentials {
   clientId: string;
   clientSecret: string;
   domain: string;
@@ -50,7 +50,7 @@ const DOMAIN_SUFFIX = /\.biapi\.pro\/?$/u;
 const POWENS_UTC_DATETIME =
   /^(?<date>\d{4}-\d{2}-\d{2})[ T](?<time>\d{2}:\d{2}:\d{2})/u;
 
-const API_PATH = "/2.0";
+export const POWENS_API_PATH = "/2.0";
 const NOT_FOUND = 404;
 const MAX_TRANSACTIONS_PER_PAGE = 1000;
 const DEFAULT_CURRENCY_PRECISION = 2;
@@ -59,9 +59,9 @@ export const powensHost = (domain: string): string =>
   `${domain.trim().replace(DOMAIN_SUFFIX, "")}.biapi.pro`;
 
 const readCredentials = (): Option.Option<PowensCredentials> => {
-  const domain = env.POWENS_DOMAIN;
-  const clientId = env.POWENS_CLIENT_ID;
-  const clientSecret = env.POWENS_CLIENT_SECRET;
+  const domain = settings.POWENS_DOMAIN;
+  const clientId = settings.POWENS_CLIENT_ID;
+  const clientSecret = settings.POWENS_CLIENT_SECRET;
 
   return domain && clientId && clientSecret
     ? Option.some({ clientId, clientSecret, domain })
@@ -102,7 +102,7 @@ const powensUrl = Effect.fnUntraced(function* powensUrl(
 ) {
   const { domain } = yield* requireCredentials(operation);
 
-  return `https://${powensHost(domain)}${API_PATH}${path}`;
+  return `https://${powensHost(domain)}${POWENS_API_PATH}${path}`;
 });
 
 const send = Effect.fnUntraced(function* send(
diff --git a/packages/api/src/providers/powens/probe.ts b/packages/api/src/providers/powens/probe.ts
new file mode 100644
index 00000000..dd076281
--- /dev/null
+++ b/packages/api/src/providers/powens/probe.ts
@@ -0,0 +1,93 @@
+import type { ProbeFailureReason } from "@freenary/instance-config/probe";
+import { IntegrationProbeFailed } from "@freenary/instance-config/probe";
+import { Effect, Result, Schema } from "effect";
+
+import type { PowensCredentials } from "./client";
+import { POWENS_API_PATH, PowensUserSchema, powensHost } from "./client";
+
+const failure = (reason: ProbeFailureReason): IntegrationProbeFailed =>
+  new IntegrationProbeFailed({
+    integrationId: "banking",
+    reason,
+    variantId: "powens",
+  });
+
+const unreachable = (cause: unknown): IntegrationProbeFailed =>
+  failure({ detail: String(cause), kind: "unreachable" });
+
+const releaseThrowawayUser = Effect.fn("powens.probeRelease")(
+  function* releaseThrowawayUser(origin: string, token: string) {
+    const released = yield* Effect.result(
+      Effect.tryPromise({
+        catch: unreachable,
+        try: (signal) =>
+          fetch(`${origin}/users/me`, {
+            headers: { Authorization: `Bearer ${token}` },
+            method: "DELETE",
+            signal,
+          }),
+      })
+    );
+
+    yield* Result.match(released, {
+      onFailure: (cause) =>
+        Effect.logWarning(
+          `The Powens check could not release the user it created: ${cause.message}`
+        ),
+      onSuccess: (response) =>
+        response.ok
+          ? Effect.void
+          : Effect.logWarning(
+              `Powens refused to release the user the check created: ${response.status}. Delete it in the console.`
+            ),
+    });
+  }
+);
+
+export const probePowensCredentials = Effect.fn("powens.probe")(
+  function* probePowensCredentials(credentials: PowensCredentials) {
+    const origin = `https://${powensHost(credentials.domain)}${POWENS_API_PATH}`;
+
+    const response = yield* Effect.tryPromise({
+      catch: unreachable,
+      try: (signal) =>
+        fetch(`${origin}/auth/init`, {
+          body: JSON.stringify({
+            client_id: credentials.clientId,
+            client_secret: credentials.clientSecret,
+          }),
+          headers: { "Content-Type": "application/json" },
+          method: "POST",
+          signal,
+        }),
+    });
+
+    if (!response.ok) {
+      const body = yield* Effect.tryPromise({
+        catch: unreachable,
+        try: () => response.text(),
+      });
+
+      return yield* failure({
+        detail: body,
+        kind: "rejected",
+        status: response.status,
+      });
+    }
+
+    const payload = yield* Effect.tryPromise({
+      catch: unreachable,
+      try: () => response.json(),
+    });
+
+    const created = yield* Schema.decodeUnknownEffect(PowensUserSchema)(
+      payload
+    ).pipe(
+      Effect.mapError((cause: Schema.SchemaError) =>
+        failure({ detail: cause.message, kind: "invalid" })
+      )
+    );
+
+    yield* releaseThrowawayUser(origin, created.auth_token);
+  }
+);
diff --git a/packages/api/src/providers/registry.ts b/packages/api/src/providers/registry.ts
index 00fe80e3..19d12b16 100644
--- a/packages/api/src/providers/registry.ts
+++ b/packages/api/src/providers/registry.ts
@@ -1,4 +1,4 @@
-import { env } from "@freenary/env/server";
+import { settings } from "@freenary/instance-config";
 
 import { enableBankingProvider } from "./enable-banking";
 import { powensProvider } from "./powens";
@@ -20,4 +20,4 @@ export const getProvider = (id: string): BankingProvider => {
 };
 
 export const getDefaultProvider = (): BankingProvider =>
-  getProvider(env.BANKING_PROVIDER);
+  getProvider(settings.BANKING_PROVIDER);
diff --git a/packages/api/src/routers/index.ts b/packages/api/src/routers/index.ts
index ba50d6b6..980c2f3f 100644
--- a/packages/api/src/routers/index.ts
+++ b/packages/api/src/routers/index.ts
@@ -5,6 +5,7 @@ import { assistantRouter } from "./assistant";
 import { authRouter } from "./auth";
 import { bankConnectionRouter } from "./bank-connection";
 import { budgetRouter } from "./budget";
+import { instanceRouter } from "./instance";
 import { onboardingRouter } from "./onboarding";
 import { settingsRouter } from "./settings";
 
@@ -14,6 +15,7 @@ export const appRouter = {
   bankConnection: bankConnectionRouter,
   budget: budgetRouter,
   healthCheck: publicProcedure.handler(() => "OK"),
+  instance: instanceRouter,
   onboarding: onboardingRouter,
   privateData: protectedProcedure.handler(({ context }) => ({
     message: "This is private",
diff --git a/packages/api/src/routers/instance.ts b/packages/api/src/routers/instance.ts
new file mode 100644
index 00000000..da90a7ff
--- /dev/null
+++ b/packages/api/src/routers/instance.ts
@@ -0,0 +1,392 @@
+import { SETUP_CLAIM_RATE_LIMIT } from "@freenary/auth/policy";
+import type {
+  Integration,
+  IntegrationField,
+  IntegrationVariant,
+  ServerSettingKey,
+  SettingSource,
+  StoredSettings,
+} from "@freenary/instance-config";
+import {
+  environmentOwns,
+  findIntegration,
+  findVariant,
+  instanceConfigFault,
+  instanceConfigurableKeys,
+  integrations,
+  isSecretField,
+  markSetupComplete,
+  readSetupState,
+  readStoredSettings,
+  redeemSetupToken,
+  settings,
+  storedSettingsInForce,
+  validateSettings,
+  writeStoredSettings,
+} from "@freenary/instance-config";
+import { ORPCError } from "@orpc/server";
+import { Effect, Option, Result } from "effect";
+import { z } from "zod";
+
+import {
+  operatorProcedure,
+  protectedProcedure,
+  publicProcedure,
+} from "../index";
+import { maskEnvironmentValue } from "../instance/mask";
+import {
+  candidateOf,
+  environmentVariantOf,
+  isWhollyOwnedByEnvironment,
+  missingKeysOf,
+  writesOf,
+} from "../instance/merge";
+import { findProbe } from "../instance/probes";
+import { callerBucket, consumeRateLimit } from "../lib/rate-limit";
+
+const RESTART_GRACE_MS = 250;
+
+const DISABLED_VARIANT = "disabled";
+
+const readCurrentSettings = (): Promise<StoredSettings> =>
+  Effect.runPromise(readStoredSettings(settings.BETTER_AUTH_SECRET));
+
+const sourceFor = (
+  key: ServerSettingKey,
+  stored: StoredSettings
+): SettingSource => {
+  if (environmentOwns(key)) {
+    return "environment";
+  }
+
+  return stored[key] === undefined ? "unset" : "instance";
+};
+
+const heldValue = (
+  key: ServerSettingKey,
+  stored: StoredSettings
+): string | null => {
+  if (!environmentOwns(key)) {
+    return stored[key] ?? null;
+  }
+
+  const fromEnvironment = settings[key];
+
+  return fromEnvironment === undefined ? null : String(fromEnvironment);
+};
+
+const selectedVariantOf = (
+  integration: Integration,
+  stored: StoredSettings
+): string => {
+  if (sourceFor(integration.discriminantKey, stored) === "unset") {
+    return DISABLED_VARIANT;
+  }
+
+  const held = heldValue(integration.discriminantKey, stored);
+  const chosen = integration.variants.find(
+    (variant) => variant.discriminantValue === held
+  );
+
+  return chosen?.id ?? DISABLED_VARIANT;
+};
+
+const isVariantComplete = (
+  variant: IntegrationVariant,
+  stored: StoredSettings
+): boolean =>
+  variant.fields.every(
+    (field) => !field.required || heldValue(field.key, stored) !== null
+  );
+
+const MASKED_KINDS: ReadonlySet<IntegrationField["kind"]> = new Set([
+  "text",
+  "url",
+]);
+
+const shownValueOf = (
+  field: IntegrationField,
+  held: string | null
+): string | null => {
+  if (held === null || isSecretField(field.kind)) {
+    return null;
+  }
+
+  return environmentOwns(field.key) && MASKED_KINDS.has(field.kind)
+    ? maskEnvironmentValue(held)
+    : held;
+};
+
+const describeField = (field: IntegrationField, stored: StoredSettings) => {
+  const held = heldValue(field.key, stored);
+
+  return {
+    key: field.key,
+    kind: field.kind,
+    present: held !== null,
+    required: field.required,
+    source: sourceFor(field.key, stored),
+    value: shownValueOf(field, held),
+  };
+};
+
+const providerFromEnvironment = (key: ServerSettingKey): string | undefined => {
+  const resolved = Result.getOrUndefined(validateSettings({}))?.[key];
+
+  return resolved === undefined ? undefined : String(resolved);
+};
+
+const configuredByOf = (
+  integration: Integration,
+  stored: StoredSettings,
+  environmentVariant: IntegrationVariant | null
+) => {
+  if (environmentVariant !== null) {
+    return "environment" as const;
+  }
+
+  return stored[integration.discriminantKey] === undefined
+    ? null
+    : ("instance" as const);
+};
+
+const describeIntegration = (
+  integration: Integration,
+  stored: StoredSettings
+) => {
+  const environmentVariant = environmentVariantOf(
+    integration,
+    stored[integration.discriminantKey],
+    providerFromEnvironment(integration.discriminantKey),
+    environmentOwns
+  );
+
+  const selectedVariantId =
+    environmentVariant?.id ?? selectedVariantOf(integration, stored);
+
+  const selected = findVariant(integration, selectedVariantId);
+
+  return {
+    configuredBy: configuredByOf(integration, stored, environmentVariant),
+    discriminantKey: integration.discriminantKey,
+    discriminantSource: sourceFor(integration.discriminantKey, stored),
+    id: integration.id,
+    selectedVariantId,
+    state:
+      selectedVariantId === DISABLED_VARIANT
+        ? ("disabled" as const)
+        : Option.match(selected, {
+            onNone: () => "incomplete" as const,
+            onSome: (variant) =>
+              isVariantComplete(variant, stored)
+                ? ("configured" as const)
+                : ("incomplete" as const),
+          }),
+    variants: integration.variants.map((variant) => ({
+      fields: variant.fields.map((field) => describeField(field, stored)),
+      id: variant.id,
+    })),
+  };
+};
+
+const hasUnappliedChange = (stored: StoredSettings): boolean => {
+  const applied = storedSettingsInForce();
+
+  for (const key of instanceConfigurableKeys) {
+    if (!environmentOwns(key) && stored[key] !== applied[key]) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+const integrationInput = z.object({
+  integrationId: z.string(),
+  values: z.record(z.string(), z.string()),
+  variantId: z.string(),
+});
+
+type IntegrationRequest = z.infer<typeof integrationInput>;
+
+const environmentPicksAnotherVariant = (
+  integration: Integration,
+  variant: IntegrationVariant
+): boolean =>
+  environmentOwns(integration.discriminantKey) &&
+  process.env[integration.discriminantKey] !== variant.discriminantValue;
+
+const prepareIntegration = async (request: IntegrationRequest) => {
+  const integration = Option.getOrThrowWith(
+    findIntegration(request.integrationId),
+    () => new ORPCError("NOT_FOUND", { message: "Unknown integration" })
+  );
+
+  const variant = Option.getOrThrowWith(
+    findVariant(integration, request.variantId),
+    () => new ORPCError("NOT_FOUND", { message: "Unknown variant" })
+  );
+
+  if (environmentPicksAnotherVariant(integration, variant)) {
+    return {
+      kind: "refused" as const,
+      refusal: {
+        keys: [integration.discriminantKey],
+        outcome: "environment-owned" as const,
+      },
+    };
+  }
+
+  const stored = await readCurrentSettings();
+  const candidate = candidateOf(
+    integration,
+    variant,
+    request.values,
+    stored,
+    environmentOwns
+  );
+
+  const missing = missingKeysOf(variant, candidate, environmentOwns);
+
+  if (missing.length > 0) {
+    return {
+      kind: "refused" as const,
+      refusal: { keys: missing, outcome: "missing-fields" as const },
+    };
+  }
+
+  const validated = validateSettings(candidate);
+
+  if (Result.isFailure(validated)) {
+    return {
+      kind: "refused" as const,
+      refusal: {
+        detail: validated.failure.detail,
+        outcome: "invalid" as const,
+      },
+    };
+  }
+
+  return {
+    candidate,
+    integration,
+    kind: "ready" as const,
+    validated: validated.success,
+    variant,
+  };
+};
+
+export const instanceRouter = {
+  check: operatorProcedure
+    .input(integrationInput)
+    .handler(async ({ input }) => {
+      const prepared = await prepareIntegration(input);
+
+      if (prepared.kind === "refused") {
+        return prepared.refusal;
+      }
+
+      const probe = Option.getOrThrowWith(
+        findProbe(prepared.integration.id, prepared.variant.id),
+        () => new ORPCError("NOT_IMPLEMENTED", { message: "No check exists" })
+      );
+
+      const probed = await Effect.runPromise(
+        Effect.result(probe(prepared.validated))
+      );
+
+      if (Result.isFailure(probed)) {
+        const { reason } = probed.failure;
+
+        return {
+          detail: reason.detail,
+          outcome: "probe-failed" as const,
+          reason: reason.kind,
+          status: reason.kind === "rejected" ? reason.status : null,
+        };
+      }
+
+      return { outcome: "verified" as const };
+    }),
+
+  claim: protectedProcedure
+    .input(z.object({ token: z.string().min(1) }))
+    .handler(async ({ context, input }) => {
+      await consumeRateLimit(
+        `instance-claim:${callerBucket(context.headers)}`,
+        SETUP_CLAIM_RATE_LIMIT
+      );
+
+      const claimed = await Effect.runPromise(
+        Effect.result(redeemSetupToken(input.token, context.session.user.id))
+      );
+
+      if (Result.isFailure(claimed)) {
+        throw new ORPCError("FORBIDDEN", {
+          message:
+            "The setup token is wrong, or the instance is already claimed.",
+        });
+      }
+
+      return { claimed: true as const };
+    }),
+
+  complete: operatorProcedure.handler(async () => {
+    await Effect.runPromise(markSetupComplete());
+
+    const restarting = hasUnappliedChange(await readCurrentSettings());
+
+    if (restarting) {
+      setTimeout(() => process.exit(0), RESTART_GRACE_MS);
+    }
+
+    return { completed: true as const, restarting };
+  }),
+
+  describe: operatorProcedure.handler(async () => {
+    const stored = await readCurrentSettings();
+
+    return {
+      fault: Option.match(instanceConfigFault, {
+        onNone: () => null,
+        onSome: (rejected) => rejected.detail,
+      }),
+      integrations: integrations.map((integration) =>
+        describeIntegration(integration, stored)
+      ),
+      restartRequired: hasUnappliedChange(stored),
+    };
+  }),
+
+  save: operatorProcedure
+    .input(integrationInput)
+    .handler(async ({ context, input }) => {
+      const prepared = await prepareIntegration(input);
+
+      if (prepared.kind === "refused") {
+        return prepared.refusal;
+      }
+
+      if (
+        isWhollyOwnedByEnvironment(
+          prepared.integration,
+          prepared.variant,
+          environmentOwns
+        )
+      ) {
+        return { outcome: "nothing-to-save" as const };
+      }
+
+      await Effect.runPromise(
+        writeStoredSettings(
+          settings.BETTER_AUTH_SECRET,
+          writesOf(prepared.integration, prepared.candidate, environmentOwns),
+          context.session.user.id
+        )
+      );
+
+      return { outcome: "saved" as const, restartRequired: true };
+    }),
+
+  status: publicProcedure.handler(() => Effect.runPromise(readSetupState())),
+};
diff --git a/packages/auth/src/policy.ts b/packages/auth/src/policy.ts
index ffa37b32..4be9cd5f 100644
--- a/packages/auth/src/policy.ts
+++ b/packages/auth/src/policy.ts
@@ -52,3 +52,5 @@ export const RATE_LIMIT_DEFAULT = { max: 100, window: 60 };
 export const ACCOUNT_EXISTS_RATE_LIMIT = { max: 20, window: 60 };
 
 export const AI_CHAT_RATE_LIMIT = { max: 30, window: 300 };
+
+export const SETUP_CLAIM_RATE_LIMIT = { max: 5, window: 300 };
diff --git a/packages/db/prisma/migrations/20260922120000_instance_configuration/migration.sql b/packages/db/prisma/migrations/20260922120000_instance_configuration/migration.sql
new file mode 100644
index 00000000..24a0a715
--- /dev/null
+++ b/packages/db/prisma/migrations/20260922120000_instance_configuration/migration.sql
@@ -0,0 +1,28 @@
+-- Instance configuration an operator supplies through the setup screen instead
+-- of the .env file. Values are sealed before they reach this table; the server
+-- never stores a credential it could read back without BETTER_AUTH_SECRET.
+CREATE TYPE "UserRole" AS ENUM ('MEMBER', 'OPERATOR');
+
+ALTER TABLE "user" ADD COLUMN "role" "UserRole" NOT NULL DEFAULT 'MEMBER';
+
+CREATE TABLE "instance_setting" (
+  "key" TEXT NOT NULL,
+  "sealed" TEXT NOT NULL,
+  "updatedAt" TIMESTAMP(3) NOT NULL,
+  "updatedBy" TEXT,
+
+  CONSTRAINT "instance_setting_pkey" PRIMARY KEY ("key")
+);
+
+-- One row for the whole setup lifecycle: the hash of the printed token while
+-- the instance is unclaimed, the moment an operator claimed it, and the moment
+-- the operator finished the wizard.
+CREATE TABLE "instance_setup" (
+  "id" TEXT NOT NULL DEFAULT 'singleton',
+  "tokenHash" TEXT,
+  "claimedAt" TIMESTAMP(3),
+  "completedAt" TIMESTAMP(3),
+  "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  CONSTRAINT "instance_setup_pkey" PRIMARY KEY ("id")
+);
diff --git a/packages/db/prisma/schema/auth.prisma b/packages/db/prisma/schema/auth.prisma
index f7f8fec9..a57d2e4b 100644
--- a/packages/db/prisma/schema/auth.prisma
+++ b/packages/db/prisma/schema/auth.prisma
@@ -10,6 +10,7 @@ model User {
   /// institutions of every one of them.
   taxCountries          String[]
   onboardingCompletedAt DateTime?
+  role                  UserRole           @default(MEMBER)
   createdAt             DateTime           @default(now())
   updatedAt             DateTime           @updatedAt
   sessions              Session[]
diff --git a/packages/db/prisma/schema/instance.prisma b/packages/db/prisma/schema/instance.prisma
new file mode 100644
index 00000000..43f820b3
--- /dev/null
+++ b/packages/db/prisma/schema/instance.prisma
@@ -0,0 +1,36 @@
+/// One operator-supplied configuration value for this instance, sealed with a
+/// key derived from BETTER_AUTH_SECRET. A process environment variable of the
+/// same name still wins over the row, so an operator who manages secrets
+/// outside the database keeps doing so and the setup screen shows the value as
+/// owned by the environment.
+model InstanceSetting {
+  key       String   @id
+  sealed    String
+  updatedAt DateTime @updatedAt
+  updatedBy String?
+
+  @@map("instance_setting")
+}
+
+/// The setup lifecycle of this instance, in one row. `tokenHash` holds the hash
+/// of the token the server prints while the instance is unclaimed, so possession
+/// of the database is not possession of the claim. `claimedAt` is the mutex two
+/// concurrent claims compete for, and `completedAt` is what stops the landing page from
+/// sending everybody to the setup screen.
+model InstanceSetup {
+  id          String    @id @default("singleton")
+  tokenHash   String?
+  claimedAt   DateTime?
+  completedAt DateTime?
+  createdAt   DateTime  @default(now())
+
+  @@map("instance_setup")
+}
+
+/// OPERATOR configures the instance itself; MEMBER uses it. The first account
+/// to present the setup token becomes the operator, and nothing grants the role
+/// afterwards.
+enum UserRole {
+  MEMBER
+  OPERATOR
+}
diff --git a/packages/email/package.json b/packages/email/package.json
index 7ebc7f6b..094e7ace 100644
--- a/packages/email/package.json
+++ b/packages/email/package.json
@@ -13,6 +13,7 @@
   "scripts": {},
   "dependencies": {
     "@freenary/env": "workspace:*",
+    "@freenary/instance-config": "workspace:*",
     "dotenv": "catalog:",
     "effect": "catalog:",
     "nodemailer": "^7.0.10",
diff --git a/packages/email/src/probe.ts b/packages/email/src/probe.ts
new file mode 100644
index 00000000..95e3e794
--- /dev/null
+++ b/packages/email/src/probe.ts
@@ -0,0 +1,105 @@
+import type { ProbeFailureReason } from "@freenary/instance-config/probe";
+import { IntegrationProbeFailed } from "@freenary/instance-config/probe";
+import { Effect, Match } from "effect";
+import { createTransport } from "nodemailer";
+
+import type { EmailSettings } from "./registry";
+
+const RESEND_DOMAINS_ENDPOINT = "https://api.resend.com/domains";
+const IMPLICIT_TLS_PORT = 465;
+const STARTTLS_PORT = 587;
+const PROBE_TIMEOUT_MS = 10_000;
+
+const failure = (
+  variantId: string,
+  reason: ProbeFailureReason
+): IntegrationProbeFailed =>
+  new IntegrationProbeFailed({ integrationId: "email", reason, variantId });
+
+const probeResend = Effect.fn("email.probeResend")(function* probeResend(
+  apiKey: string
+) {
+  const response = yield* Effect.tryPromise({
+    catch: (cause) =>
+      failure("resend", { detail: String(cause), kind: "unreachable" }),
+    try: (signal) =>
+      fetch(RESEND_DOMAINS_ENDPOINT, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+        signal,
+      }),
+  });
+
+  if (response.ok) {
+    return;
+  }
+
+  const body = yield* Effect.tryPromise({
+    catch: (cause) =>
+      failure("resend", { detail: String(cause), kind: "unreachable" }),
+    try: () => response.text(),
+  });
+
+  return yield* failure("resend", {
+    detail: body,
+    kind: "rejected",
+    status: response.status,
+  });
+});
+
+const probeSmtp = Effect.fn("email.probeSmtp")(function* probeSmtp(
+  settings: EmailSettings
+) {
+  const host = settings.smtpHost;
+
+  if (host === undefined) {
+    return yield* failure("smtp", {
+      detail: "SMTP_HOST",
+      kind: "invalid",
+    });
+  }
+
+  const transport = yield* Effect.acquireRelease(
+    Effect.sync(() =>
+      createTransport({
+        auth:
+          settings.smtpUser === undefined
+            ? undefined
+            : { pass: settings.smtpPassword, user: settings.smtpUser },
+        connectionTimeout: PROBE_TIMEOUT_MS,
+        greetingTimeout: PROBE_TIMEOUT_MS,
+        host,
+        port:
+          settings.smtpPort ??
+          (settings.smtpSecure ? IMPLICIT_TLS_PORT : STARTTLS_PORT),
+        secure: settings.smtpSecure,
+      })
+    ),
+    (open) => Effect.sync(() => open.close())
+  );
+
+  yield* Effect.tryPromise({
+    catch: (cause) =>
+      failure("smtp", { detail: String(cause), kind: "unreachable" }),
+    try: () => transport.verify(),
+  });
+});
+
+export const probeEmailSettings = Effect.fn("email.probe")(
+  function* probeEmailSettings(settings: EmailSettings) {
+    if (settings.provider === undefined) {
+      return;
+    }
+
+    yield* Match.value(settings.provider).pipe(
+      Match.when("resend", () =>
+        settings.resendApiKey === undefined
+          ? Effect.fail(
+              failure("resend", { detail: "RESEND_API_KEY", kind: "invalid" })
+            )
+          : probeResend(settings.resendApiKey)
+      ),
+      Match.when("smtp", () => Effect.scoped(probeSmtp(settings))),
+      Match.exhaustive
+    );
+  }
+);
diff --git a/packages/email/src/registry.ts b/packages/email/src/registry.ts
index 9b2a107e..ca924ccc 100644
--- a/packages/email/src/registry.ts
+++ b/packages/email/src/registry.ts
@@ -1,4 +1,5 @@
-import { env } from "@freenary/env/server";
+import type { ServerSettings } from "@freenary/instance-config";
+import { settings as instanceSettings } from "@freenary/instance-config";
 import { Data, Match, Result } from "effect";
 
 import { createResendEmailProvider } from "./providers/resend";
@@ -89,15 +90,17 @@ export const createEmailProvider = (
   );
 };
 
+export const emailSettingsOf = (source: ServerSettings): EmailSettings => ({
+  from: source.EMAIL_FROM,
+  provider: source.EMAIL_PROVIDER,
+  resendApiKey: source.RESEND_API_KEY,
+  smtpHost: source.SMTP_HOST,
+  smtpPassword: source.SMTP_PASSWORD,
+  smtpPort: source.SMTP_PORT,
+  smtpSecure: source.SMTP_SECURE,
+  smtpUser: source.SMTP_USER,
+});
+
 export const emailProvider = Result.getOrThrow(
-  createEmailProvider({
-    from: env.EMAIL_FROM,
-    provider: env.EMAIL_PROVIDER,
-    resendApiKey: env.RESEND_API_KEY,
-    smtpHost: env.SMTP_HOST,
-    smtpPassword: env.SMTP_PASSWORD,
-    smtpPort: env.SMTP_PORT,
-    smtpSecure: env.SMTP_SECURE,
-    smtpUser: env.SMTP_USER,
-  })
+  createEmailProvider(emailSettingsOf(instanceSettings))
 );
diff --git a/packages/env/src/schema.ts b/packages/env/src/schema.ts
index a4e50565..89d3811c 100644
--- a/packages/env/src/schema.ts
+++ b/packages/env/src/schema.ts
@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 const IPV4_MAPPED_IPV6_PREFIX = /^::ffff:/iu;
+const URL_SAFE_TOKEN = /^[\w-]+$/u;
 const DEFAULT_PORT = 3000;
 
 export const CLASSIFIER_PROTOCOLS = ["llm", "system-one", "zero-shot"] as const;
@@ -218,6 +219,24 @@ export const serverEnvSchema = {
       secret: true,
       section: "bank",
     }),
+  FREENARY_SETUP_TOKEN: z
+    .string()
+    .min(32)
+    .regex(
+      URL_SAFE_TOKEN,
+      "FREENARY_SETUP_TOKEN must use letters, digits, - and _ only"
+    )
+    .optional()
+    .describe(
+      "The setup token that claims an unclaimed instance on the setup screen. Unset, the server makes a new token at each start and prints it in its log."
+    )
+    .meta({
+      example: "choose_a_long_random_value_of_32_or_more_characters",
+      onError:
+        "Under 32 characters, or a character other than a letter, a digit, `-` or `_`, stops the start. After the claim the server ignores the value.",
+      secret: true,
+      section: "core",
+    }),
   GOOGLE_CLIENT_ID: z
     .string()
     .optional()
diff --git a/packages/instance-config/package.json b/packages/instance-config/package.json
new file mode 100644
index 00000000..e426bea7
--- /dev/null
+++ b/packages/instance-config/package.json
@@ -0,0 +1,27 @@
+{
+  "name": "@freenary/instance-config",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./src/index.ts"
+    },
+    "./*": {
+      "default": "./src/*.ts"
+    }
+  },
+  "scripts": {},
+  "dependencies": {
+    "@freenary/db": "workspace:*",
+    "@freenary/env": "workspace:*",
+    "@t3-oss/env-core": "^0.13.11",
+    "dotenv": "catalog:",
+    "effect": "catalog:",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@freenary/config": "workspace:*",
+    "@types/bun": "catalog:",
+    "typescript": "catalog:"
+  }
+}
diff --git a/packages/instance-config/src/candidate.ts b/packages/instance-config/src/candidate.ts
new file mode 100644
index 00000000..ab57d954
--- /dev/null
+++ b/packages/instance-config/src/candidate.ts
@@ -0,0 +1,57 @@
+import { serverEnvSchema } from "@freenary/env/schema";
+import type { env } from "@freenary/env/server";
+import { createEnv } from "@t3-oss/env-core";
+import { Data, Result } from "effect";
+
+import { instanceConfigurableKeys } from "./integrations";
+import type { ServerSettingKey } from "./integrations";
+
+export type ServerSettings = typeof env;
+
+export type StoredSettings = Readonly<Record<string, string>>;
+
+export type SettingSource = "environment" | "instance" | "unset";
+
+export class InstanceSettingsRejected extends Data.TaggedError(
+  "InstanceSettingsRejected"
+)<{
+  readonly detail: string;
+}> {
+  override get message(): string {
+    return `The instance configuration does not validate: ${this.detail}`;
+  }
+}
+
+export const environmentOwns = (key: ServerSettingKey): boolean => {
+  const declared = process.env[key];
+
+  return declared !== undefined && declared !== "";
+};
+
+const overlayOf = (stored: StoredSettings): Record<string, string> => {
+  const overlay: Record<string, string> = {};
+
+  for (const key of instanceConfigurableKeys) {
+    const supplied = stored[key];
+
+    if (supplied !== undefined && !environmentOwns(key)) {
+      overlay[key] = supplied;
+    }
+  }
+
+  return overlay;
+};
+
+export const validateSettings = (
+  stored: StoredSettings
+): Result.Result<ServerSettings, InstanceSettingsRejected> =>
+  Result.try({
+    catch: (cause) => new InstanceSettingsRejected({ detail: String(cause) }),
+    try: () =>
+      createEnv({
+        emptyStringAsUndefined: true,
+        runtimeEnv: { ...process.env, ...overlayOf(stored) },
+        server: serverEnvSchema,
+        skipValidation: Boolean(process.env.SKIP_ENV_VALIDATION),
+      }),
+  });
diff --git a/packages/instance-config/src/claim.ts b/packages/instance-config/src/claim.ts
new file mode 100644
index 00000000..3ac38ab8
--- /dev/null
+++ b/packages/instance-config/src/claim.ts
@@ -0,0 +1,111 @@
+import { createHash, randomBytes } from "node:crypto";
+
+import prisma from "@freenary/db";
+import { Data, Effect, Option } from "effect";
+
+const SETUP_TOKEN_BYTES = 24;
+const SETUP_ROW_ID = "singleton";
+const OPERATOR_ROLE = "OPERATOR";
+
+export interface SetupState {
+  readonly claimed: boolean;
+  readonly completed: boolean;
+}
+
+export class SetupClaimRefused extends Data.TaggedError("SetupClaimRefused")<{
+  readonly userId: string;
+}> {}
+
+const hashOf = (token: string): string =>
+  createHash("sha256").update(token).digest("hex");
+
+export const readSetupState = Effect.fn("instanceConfig.readSetupState")(
+  function* readSetupState() {
+    const row = yield* Effect.promise(() =>
+      prisma.instanceSetup.findUnique({
+        select: { claimedAt: true, completedAt: true },
+        where: { id: SETUP_ROW_ID },
+      })
+    );
+
+    return {
+      claimed: (row?.claimedAt ?? null) !== null,
+      completed: (row?.completedAt ?? null) !== null,
+    } satisfies SetupState;
+  }
+);
+
+export type IssuedSetupToken =
+  | { readonly kind: "chosen" }
+  | { readonly kind: "generated"; readonly token: string };
+
+export const issueSetupToken = Effect.fn("instanceConfig.issueSetupToken")(
+  function* issueSetupToken(chosenToken: string | undefined) {
+    const { claimed } = yield* readSetupState();
+
+    if (claimed) {
+      return Option.none<IssuedSetupToken>();
+    }
+
+    const token =
+      chosenToken ?? randomBytes(SETUP_TOKEN_BYTES).toString("base64url");
+
+    yield* Effect.promise(() =>
+      prisma.instanceSetup.upsert({
+        create: { id: SETUP_ROW_ID, tokenHash: hashOf(token) },
+        update: { tokenHash: hashOf(token) },
+        where: { id: SETUP_ROW_ID },
+      })
+    );
+
+    const issued: IssuedSetupToken =
+      chosenToken === undefined
+        ? { kind: "generated", token }
+        : { kind: "chosen" };
+
+    return Option.some(issued);
+  }
+);
+
+export const redeemSetupToken = Effect.fn("instanceConfig.redeemSetupToken")(
+  function* redeemSetupToken(token: string, userId: string) {
+    const claimed = yield* Effect.promise(() =>
+      prisma.$transaction(async (tx) => {
+        const taken = await tx.instanceSetup.updateMany({
+          data: { claimedAt: new Date(), tokenHash: null },
+          where: {
+            claimedAt: null,
+            id: SETUP_ROW_ID,
+            tokenHash: hashOf(token),
+          },
+        });
+
+        if (taken.count === 0) {
+          return false;
+        }
+
+        await tx.user.update({
+          data: { role: OPERATOR_ROLE },
+          where: { id: userId },
+        });
+
+        return true;
+      })
+    );
+
+    if (!claimed) {
+      return yield* new SetupClaimRefused({ userId });
+    }
+  }
+);
+
+export const markSetupComplete = Effect.fn("instanceConfig.markSetupComplete")(
+  function* markSetupComplete() {
+    yield* Effect.promise(() =>
+      prisma.instanceSetup.updateMany({
+        data: { completedAt: new Date() },
+        where: { completedAt: null, id: SETUP_ROW_ID },
+      })
+    );
+  }
+);
diff --git a/packages/instance-config/src/index.ts b/packages/instance-config/src/index.ts
new file mode 100644
index 00000000..57c5daf9
--- /dev/null
+++ b/packages/instance-config/src/index.ts
@@ -0,0 +1,40 @@
+export type {
+  InstanceSettingsRejected,
+  ServerSettings,
+  SettingSource,
+  StoredSettings,
+} from "./candidate";
+export { environmentOwns, validateSettings } from "./candidate";
+export type { SetupState } from "./claim";
+export {
+  issueSetupToken,
+  markSetupComplete,
+  readSetupState,
+  redeemSetupToken,
+  SetupClaimRefused,
+} from "./claim";
+export type {
+  Integration,
+  IntegrationField,
+  IntegrationFieldKind,
+  IntegrationVariant,
+  ServerSettingKey,
+} from "./integrations";
+export {
+  findIntegration,
+  findVariant,
+  instanceConfigurableKeys,
+  integrations,
+  isSecretField,
+  keysOf,
+} from "./integrations";
+export {
+  instanceConfigFault,
+  settings,
+  storedSettingsInForce,
+} from "./resolve";
+export {
+  InstanceStoreUnavailable,
+  readStoredSettings,
+  writeStoredSettings,
+} from "./store";
diff --git a/packages/instance-config/src/integrations.ts b/packages/instance-config/src/integrations.ts
new file mode 100644
index 00000000..6c786d7f
--- /dev/null
+++ b/packages/instance-config/src/integrations.ts
@@ -0,0 +1,124 @@
+import type { serverEnvSchema } from "@freenary/env/schema";
+import { Option } from "effect";
+
+export type ServerSettingKey = keyof typeof serverEnvSchema;
+
+export type IntegrationFieldKind =
+  | "text"
+  | "url"
+  | "secret"
+  | "secret-block"
+  | "port"
+  | "toggle";
+
+export interface IntegrationField {
+  readonly key: ServerSettingKey;
+  readonly kind: IntegrationFieldKind;
+  readonly required: boolean;
+}
+
+export interface IntegrationVariant {
+  readonly id: string;
+  readonly discriminantValue: string | null;
+  readonly fields: readonly IntegrationField[];
+}
+
+export interface Integration {
+  readonly id: string;
+  readonly discriminantKey: ServerSettingKey;
+  readonly variants: readonly IntegrationVariant[];
+}
+
+const bankingIntegration: Integration = {
+  discriminantKey: "BANKING_PROVIDER",
+  id: "banking",
+  variants: [
+    { discriminantValue: null, fields: [], id: "disabled" },
+    {
+      discriminantValue: "powens",
+      fields: [
+        { key: "POWENS_DOMAIN", kind: "text", required: true },
+        { key: "POWENS_CLIENT_ID", kind: "text", required: true },
+        { key: "POWENS_CLIENT_SECRET", kind: "secret", required: true },
+      ],
+      id: "powens",
+    },
+    {
+      discriminantValue: "enable-banking",
+      fields: [
+        { key: "ENABLE_BANKING_APP_ID", kind: "text", required: true },
+        {
+          key: "ENABLE_BANKING_PRIVATE_KEY",
+          kind: "secret-block",
+          required: true,
+        },
+      ],
+      id: "enable-banking",
+    },
+  ],
+};
+
+const emailIntegration: Integration = {
+  discriminantKey: "EMAIL_PROVIDER",
+  id: "email",
+  variants: [
+    { discriminantValue: null, fields: [], id: "disabled" },
+    {
+      discriminantValue: "resend",
+      fields: [
+        { key: "EMAIL_FROM", kind: "text", required: true },
+        { key: "RESEND_API_KEY", kind: "secret", required: true },
+      ],
+      id: "resend",
+    },
+    {
+      discriminantValue: "smtp",
+      fields: [
+        { key: "EMAIL_FROM", kind: "text", required: true },
+        { key: "SMTP_HOST", kind: "text", required: true },
+        { key: "SMTP_PORT", kind: "port", required: false },
+        { key: "SMTP_SECURE", kind: "toggle", required: false },
+        { key: "SMTP_USER", kind: "text", required: false },
+        { key: "SMTP_PASSWORD", kind: "secret", required: false },
+      ],
+      id: "smtp",
+    },
+  ],
+};
+
+export const integrations: readonly Integration[] = [
+  bankingIntegration,
+  emailIntegration,
+];
+
+export const findIntegration = (id: string): Option.Option<Integration> =>
+  Option.fromNullishOr(
+    integrations.find((integration) => integration.id === id)
+  );
+
+export const findVariant = (
+  integration: Integration,
+  id: string
+): Option.Option<IntegrationVariant> =>
+  Option.fromNullishOr(
+    integration.variants.find((variant) => variant.id === id)
+  );
+
+export const keysOf = (integration: Integration): ServerSettingKey[] => {
+  const keys = new Set<ServerSettingKey>([integration.discriminantKey]);
+
+  for (const variant of integration.variants) {
+    for (const field of variant.fields) {
+      keys.add(field.key);
+    }
+  }
+
+  return [...keys];
+};
+
+export const instanceConfigurableKeys: ReadonlySet<ServerSettingKey> = new Set(
+  integrations.flatMap(keysOf)
+);
+
+export const isSecretField = (kind: IntegrationFieldKind): boolean =>
+  kind === "secret" || kind === "secret-block";
diff --git a/packages/instance-config/src/probe.ts b/packages/instance-config/src/probe.ts
new file mode 100644
index 00000000..1d009ac6
--- /dev/null
+++ b/packages/instance-config/src/probe.ts
@@ -0,0 +1,33 @@
+import { Data, Match } from "effect";
+
+export type ProbeFailureReason =
+  | { readonly kind: "unreachable"; readonly detail: string }
+  | {
+      readonly kind: "rejected";
+      readonly status: number;
+      readonly detail: string;
+    }
+  | { readonly kind: "invalid"; readonly detail: string };
+
+export class IntegrationProbeFailed extends Data.TaggedError(
+  "IntegrationProbeFailed"
+)<{
+  readonly integrationId: string;
+  readonly variantId: string;
+  readonly reason: ProbeFailureReason;
+}> {
+  override get message(): string {
+    const subject = `${this.integrationId} (${this.variantId})`;
+
+    return Match.value(this.reason).pipe(
+      Match.discriminatorsExhaustive("kind")({
+        invalid: ({ detail }) =>
+          `${subject} was given a value this instance cannot use: ${detail}`,
+        rejected: ({ detail, status }) =>
+          `${subject} refused the credentials: ${status} ${detail}`,
+        unreachable: ({ detail }) =>
+          `${subject} could not be reached: ${detail}`,
+      })
+    );
+  }
+}
diff --git a/packages/instance-config/src/resolve.ts b/packages/instance-config/src/resolve.ts
new file mode 100644
index 00000000..1f058a74
--- /dev/null
+++ b/packages/instance-config/src/resolve.ts
@@ -0,0 +1,46 @@
+import { env } from "@freenary/env/server";
+import { Effect, Result } from "effect";
+import type { Option } from "effect";
+
+import type {
+  InstanceSettingsRejected,
+  ServerSettings,
+  StoredSettings,
+} from "./candidate";
+import { validateSettings } from "./candidate";
+import { readStoredSettings } from "./store";
+
+const isProduction = process.env.NODE_ENV === "production";
+
+const loadStoredSettings = async (): Promise<StoredSettings> => {
+  const attempt = await Effect.runPromise(
+    Effect.result(readStoredSettings(env.BETTER_AUTH_SECRET))
+  );
+
+  if (Result.isSuccess(attempt)) {
+    return attempt.success;
+  }
+
+  if (isProduction) {
+    throw attempt.failure;
+  }
+
+  console.warn(
+    `${attempt.failure.message}. The environment alone is in force.`
+  );
+
+  return {};
+};
+
+const stored = await loadStoredSettings();
+
+const built = validateSettings(stored);
+
+const inForce: StoredSettings = Result.isSuccess(built) ? stored : {};
+
+export const instanceConfigFault: Option.Option<InstanceSettingsRejected> =
+  Result.getFailure(built);
+
+export const settings: ServerSettings = Result.getOrElse(built, () => env);
+
+export const storedSettingsInForce = (): StoredSettings => inForce;
diff --git a/packages/instance-config/src/seal.test.ts b/packages/instance-config/src/seal.test.ts
new file mode 100644
index 00000000..47cbe3e6
--- /dev/null
+++ b/packages/instance-config/src/seal.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+
+import { Result } from "effect";
+
+import { seal, unseal } from "./seal";
+
+const SECRET = "a-secret-that-is-at-least-32-characters";
+const OTHER_SECRET = "another-secret-of-at-least-32-characters";
+
+describe("seal", () => {
+  test("opens a value it sealed", () => {
+    const sealed = seal(SECRET, "SMTP_HOST", "smtp.example.com");
+
+    expect(Result.getOrThrow(unseal(SECRET, "SMTP_HOST", sealed))).toBe(
+      "smtp.example.com"
+    );
+  });
+
+  test("hides the plaintext", () => {
+    const sealed = seal(SECRET, "SMTP_HOST", "smtp.example.com");
+
+    expect(sealed).not.toContain("smtp.example.com");
+  });
+
+  test("gives a different ciphertext each time", () => {
+    const first = seal(SECRET, "SMTP_HOST", "smtp.example.com");
+    const second = seal(SECRET, "SMTP_HOST", "smtp.example.com");
+
+    expect(first).not.toBe(second);
+  });
+
+  test("refuses a value sealed under another secret", () => {
+    const sealed = seal(OTHER_SECRET, "SMTP_HOST", "smtp.example.com");
+
+    expect(Result.isFailure(unseal(SECRET, "SMTP_HOST", sealed))).toBe(true);
+  });
+
+  test("refuses a value moved to another key", () => {
+    const sealed = seal(SECRET, "SMTP_PASSWORD", "hunter2");
+
+    expect(Result.isFailure(unseal(SECRET, "SMTP_USER", sealed))).toBe(true);
+  });
+
+  test("refuses a tampered ciphertext", () => {
+    const sealed = seal(SECRET, "SMTP_HOST", "smtp.example.com");
+    const tampered = `${sealed.slice(0, -2)}${sealed.endsWith("aa") ? "bb" : "aa"}`;
+
+    expect(Result.isFailure(unseal(SECRET, "SMTP_HOST", tampered))).toBe(true);
+  });
+
+  test("refuses a value that is not sealed at all", () => {
+    expect(Result.isFailure(unseal(SECRET, "SMTP_HOST", "plain"))).toBe(true);
+  });
+
+  test("carries a multi-line PEM through unchanged", () => {
+    const pem =
+      "-----BEGIN PRIVATE KEY-----\nMIIEvQ==\n-----END PRIVATE KEY-----";
+
+    const sealed = seal(SECRET, "ENABLE_BANKING_PRIVATE_KEY", pem);
+
+    expect(
+      Result.getOrThrow(unseal(SECRET, "ENABLE_BANKING_PRIVATE_KEY", sealed))
+    ).toBe(pem);
+  });
+});
diff --git a/packages/instance-config/src/seal.ts b/packages/instance-config/src/seal.ts
new file mode 100644
index 00000000..f2b66c0d
--- /dev/null
+++ b/packages/instance-config/src/seal.ts
@@ -0,0 +1,81 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  hkdfSync,
+  randomBytes,
+} from "node:crypto";
+
+import { Data, Result } from "effect";
+
+const SEAL_ALGORITHM = "aes-256-gcm";
+const SEAL_KEY_BYTES = 32;
+const SEAL_IV_BYTES = 12;
+const SEAL_DIGEST = "sha256";
+const SEAL_INFO = "freenary/instance-setting/v1";
+const SEAL_SEPARATOR = ".";
+const SEAL_ENCODING = "base64url";
+
+export class SealedValueUnreadable extends Data.TaggedError(
+  "SealedValueUnreadable"
+)<{
+  readonly key: string;
+}> {
+  override get message(): string {
+    return `The stored value of ${this.key} does not open with the current BETTER_AUTH_SECRET.`;
+  }
+}
+
+const sealingKey = (secret: string): Buffer =>
+  Buffer.from(
+    hkdfSync(SEAL_DIGEST, secret, SEAL_INFO, SEAL_INFO, SEAL_KEY_BYTES)
+  );
+
+export const seal = (
+  secret: string,
+  key: string,
+  plaintext: string
+): string => {
+  const iv = randomBytes(SEAL_IV_BYTES);
+  const cipher = createCipheriv(SEAL_ALGORITHM, sealingKey(secret), iv);
+
+  cipher.setAAD(Buffer.from(key));
+
+  const body = Buffer.concat([
+    cipher.update(plaintext, "utf-8"),
+    cipher.final(),
+  ]);
+
+  return [
+    iv.toString(SEAL_ENCODING),
+    cipher.getAuthTag().toString(SEAL_ENCODING),
+    body.toString(SEAL_ENCODING),
+  ].join(SEAL_SEPARATOR);
+};
+
+export const unseal = (
+  secret: string,
+  key: string,
+  sealed: string
+): Result.Result<string, SealedValueUnreadable> =>
+  Result.try({
+    catch: () => new SealedValueUnreadable({ key }),
+    try: () => {
+      const [iv, authTag, body] = sealed.split(SEAL_SEPARATOR);
+      const decipher = createDecipheriv(
+        SEAL_ALGORITHM,
+        sealingKey(secret),
+        Buffer.from(iv ?? "", SEAL_ENCODING)
+      );
+
+      decipher.setAAD(Buffer.from(key));
+      decipher.setAuthTag(Buffer.from(authTag ?? "", SEAL_ENCODING));
+
+      return (
+        decipher.update(
+          Buffer.from(body ?? "", SEAL_ENCODING),
+          undefined,
+          "utf-8"
+        ) + decipher.final("utf-8")
+      );
+    },
+  });
diff --git a/packages/instance-config/src/store.ts b/packages/instance-config/src/store.ts
new file mode 100644
index 00000000..9e5a34f0
--- /dev/null
+++ b/packages/instance-config/src/store.ts
@@ -0,0 +1,85 @@
+import prisma from "@freenary/db";
+import { Data, Effect, Result } from "effect";
+
+import type { StoredSettings } from "./candidate";
+import { seal, unseal } from "./seal";
+
+export class InstanceStoreUnavailable extends Data.TaggedError(
+  "InstanceStoreUnavailable"
+)<{
+  readonly operation: string;
+  readonly detail: string;
+}> {
+  override get message(): string {
+    return `The instance configuration could not be ${this.operation}: ${this.detail}`;
+  }
+}
+
+const unavailable = (operation: string) => (cause: unknown) =>
+  new InstanceStoreUnavailable({ detail: String(cause), operation });
+
+export const readStoredSettings = Effect.fn("instanceConfig.readStored")(
+  function* readStoredSettings(secret: string) {
+    const rows = yield* Effect.tryPromise({
+      catch: unavailable("read"),
+      try: () =>
+        prisma.instanceSetting.findMany({
+          select: { key: true, sealed: true },
+        }),
+    });
+
+    const opened: Record<string, string> = {};
+
+    for (const row of rows) {
+      const plaintext = unseal(secret, row.key, row.sealed);
+
+      if (Result.isSuccess(plaintext)) {
+        opened[row.key] = plaintext.success;
+      } else {
+        yield* Effect.logWarning(plaintext.failure.message);
+      }
+    }
+
+    return opened satisfies StoredSettings;
+  }
+);
+
+export const writeStoredSettings = Effect.fn("instanceConfig.writeStored")(
+  function* writeStoredSettings(
+    secret: string,
+    entries: ReadonlyMap<string, string | null>,
+    operatorId: string
+  ) {
+    const removed: string[] = [];
+    const upserts: { key: string; sealed: string }[] = [];
+
+    for (const [key, plaintext] of entries) {
+      if (plaintext === null) {
+        removed.push(key);
+      } else {
+        upserts.push({ key, sealed: seal(secret, key, plaintext) });
+      }
+    }
+
+    yield* Effect.tryPromise({
+      catch: unavailable("written"),
+      try: () =>
+        prisma.$transaction([
+          prisma.instanceSetting.deleteMany({
+            where: { key: { in: removed } },
+          }),
+          ...upserts.map((entry) =>
+            prisma.instanceSetting.upsert({
+              create: {
+                key: entry.key,
+                sealed: entry.sealed,
+                updatedBy: operatorId,
+              },
+              update: { sealed: entry.sealed, updatedBy: operatorId },
+              where: { key: entry.key },
+            })
+          ),
+        ]),
+    });
+  }
+);
diff --git a/packages/instance-config/tsconfig.json b/packages/instance-config/tsconfig.json
new file mode 100644
index 00000000..5dd03358
--- /dev/null
+++ b/packages/instance-config/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "@freenary/config/tsconfig.base.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "composite": true,
+    "strictNullChecks": true
+  }
+}