@@ -34,7 +34,7 @@ workable default:
 | Variable | Why it must be set |
 |:---|:---|
 | `OS_DATABASE_URL` | Without it, data lands in a SQLite file under the ObjectStack home directory (`~/.objectstack`, or `<cwd>/.objectstack` next to a project config) — fine for one box, wrong for containers. Use `postgres://…`, `mysql://…`, `mongodb://…`, `libsql://…`, or a mounted `file:…` path (`postgres://…`'s driver is an **optional** package too — `npm install pg`, or the boot fails loudly rather than degrading to SQLite; `libsql://` / Turso is inferred, but its driver is an **optional** package — `npm install @objectstack/driver-turso`, or the boot fails loudly rather than degrading to SQLite; see [Drivers](/docs/data-modeling/drivers)). `mysql://…` is a supported deployment target that carries three dialect caveats — two of them integrity guarantees MySQL cannot enforce at the database — see [Drivers → MySQL dialect caveats](/docs/data-modeling/drivers#mysql-dialect-caveats) before choosing it; its driver is likewise an **optional** package — `npm install mysql2`, or the boot fails loudly rather than degrading to SQLite. `mongodb://…` is **single-tenant only**: the MongoDB driver has no row-level tenant isolation and refuses to boot unless the tenancy posture is `single` — see [Drivers → Multi-tenancy](/docs/data-modeling/drivers#multi-tenancy-not-supported). |
-| `OS_AUTH_SECRET` | Session secret for the auth plugin (`AUTH_SECRET` is the legacy alias). Without it, `/api/v1/auth/*` is **silently skipped** — the server runs unauthenticated. |
+| `OS_AUTH_SECRET` | Session secret for the auth plugin (`AUTH_SECRET` is the legacy alias). Without it, `os start` generates one and keeps it in `auth-secret` under the ObjectStack home directory, reused on restart: lose that file (a replaced container) and everyone is signed out. |
 | `OS_SECRET_KEY` | 32-byte master key encrypting every stored secret (`openssl rand -hex 32`). On a container's ephemeral filesystem the auto-minted key is **lost on restart**, making previously-encrypted secrets undecryptable. |
 | `OS_PORT` | `os start` **fails loudly** if the port is busy (it never auto-shifts like `os dev`). Pin it and keep your reverse-proxy upstream in sync. |
 
@@ -45,6 +45,40 @@ OS_AUTH_SECRET=$(openssl rand -hex 32)
 OS_SECRET_KEY=$(openssl rand -hex 32)
 ```
 
+### When the three are not set
+
+**The official image refuses to start** unless `OS_DATABASE_URL`,
+`OS_AUTH_SECRET` and `OS_SECRET_KEY` are all set explicitly. It exits naming
+the ones that are missing, before it writes a database file or a secret: a
+container's disk is the part that gets replaced, so booting on it would lose
+the data, sign everyone out and leave every saved credential unreadable. The
+image turns the check on with `OS_DEPLOYMENT_DURABILITY_CHECK_ENABLED=true` in
+its `ENV`.
+
+- An explicit `OS_DATABASE_URL=file:/path/on/a/volume/app.db` passes: SQLite on
+  a mounted volume stays a choice ([below](#docker-compose-with-postgres)).
+- **Already running on values the image generated?** Carry them over before you
+  set new ones, or the saved credentials stop decrypting and every session
+  ends. They are files in the old container's home, `/home/node/.objectstack`
+  (`docker exec <container> cat <file>`, or read them from its volume):
+  `OS_AUTH_SECRET` is the contents of `auth-secret`, `OS_SECRET_KEY` the
+  contents of `dev-crypto-key`, and the data is `data/objectstack.db`
+  (`OS_DATABASE_URL=file:…` on a kept volume, or migrate it to your database).
+  The refusal prints these paths and says which of them the container holds.
+
+**Every other `os start` keeps booting.** In production mode, when it keeps any
+of the three on its own disk, it prints a warning block naming each file and the
+variable that moves it off that disk. Administrators also see it in the Console:
+a standing notice on the home page and at the top of Setup's System Overview,
+listing the same files with a button that copies the variables to set, plus two
+lower-severity lines when uploads are stored on the local disk or no email
+service is set up. Members never see it, and it is not on the public auth
+config (it is read from `GET /api/settings/deployment/notice`, which needs
+`manage_platform_settings`). An administrator can hide it: the hide is written
+to the audit log as a `config_change` (and refused where no audit log is
+mounted), it lasts for that administrator in that browser until the findings
+change, and System Overview keeps one small line saying the notice is hidden.
+
 The full catalog is in
 [Environment Variables](/docs/deployment/environment-variables).
 
@@ -252,7 +286,9 @@ curl -fsS http://localhost:8080/api/v1/health
 
 Prefer SQLite on a single small host? Skip the `db` service, mount a volume,
 and point `OS_DATABASE_URL` at it: `file:/srv/data/app.db` (with
-`- appdata:/srv/data` on the app service). See
+`- appdata:/srv/data` on the app service). Set it explicitly even then: the
+official image refuses to start on its default database file, which lives in
+the container layer ([When the three are not set](#when-the-three-are-not-set)). See
 [Drivers](/docs/data-modeling/drivers) for when to reach for which database.
 
 ## Health checks & orchestration
 
@@ -87,15 +87,26 @@ package set or on a version range.
 ## What the image presets
 
 - `OS_ARTIFACT_PATH=/srv/app/objectstack.json`, `OS_PORT=8080`,
-  `NODE_ENV=production`
+  `NODE_ENV=production`, `OS_DEPLOYMENT_DURABILITY_CHECK_ENABLED=true`
 - Runs as the non-root `node` user
 - `HEALTHCHECK` on `/api/v1/health` (liveness); use `/api/v1/ready` as the
   readiness probe in orchestrators
 
 **You must inject at runtime:** `OS_DATABASE_URL`, `OS_AUTH_SECRET`,
-`OS_SECRET_KEY` — never bake them into an image. Full variable catalog and
-reverse-proxy / multi-node guidance:
-[Self-Hosted Deployment](https://objectstack.ai/docs/deployment/self-hosting).
+`OS_SECRET_KEY` — never bake them into an image. **The image refuses to start
+without all three** (`OS_DEPLOYMENT_DURABILITY_CHECK_ENABLED=true`): it exits
+naming the missing ones, because without them the data would be a SQLite file in
+the container layer and both secrets would be generated there, all lost when the
+container is replaced. An explicit `OS_DATABASE_URL=file:/path/on/a/volume/app.db`
+passes, so SQLite on a mounted volume still works.
+
+Upgrading a container that ran on values the image generated? Carry them over
+first, from the old container's `/home/node/.objectstack`: `OS_AUTH_SECRET` is
+the contents of `auth-secret`, `OS_SECRET_KEY` the contents of `dev-crypto-key`,
+and the data is `data/objectstack.db`. The refusal prints these paths.
+
+Full variable catalog and reverse-proxy / multi-node guidance:
+[Self-Hosted Deployment](https://objectstack.ai/docs/deployment/self-hosting#when-the-three-are-not-set).
 
 ## Local build of this image