docs: a new install could not start, and nothing told anyone why (#3422)

The install path milestone 328 wrote produces a web container that exits on
boot. entrypoint.sh runs alembic, then app construction raises:

  MissingCredentialKey: Fernet key file not found at
  /images/secrets/credential_key.b64. For first-time setup, set
  CURATOR_BOOTSTRAP_NEW_KEY=1.

That variable appeared in no README, no .env.example and no compose file —
only in backend/. So a stranger following the documented steps got an app
that does not start and an error with no context. Found by the milestone-362
smoke gate on its first real run (#3422).

The product behaviour stays exactly as it is. credential_crypto refuses to
mint a key because the 2026-06-02 audit found a partial restore — database
back, ./images/secrets lost — silently generating a fresh one and producing a
healthy-looking instance where every authenticated download failed AUTH_ERROR.
Failing fast is right; not saying so is the bug.

So: .env.example carries the variable in its own FIRST BOOT ONLY section with
the reasoning and an instruction to delete the line afterwards, and README's
First run leads with it, because "the app will not start" belongs before "the
ML worker downloads weights". Both say to back up ./images/secrets/ alongside
the database, which is the part that costs real data if it is learned late.

**compose had to change too, and this is the part that would have shipped a
second broken instruction.** A variable in `.env` is only used for ${...}
interpolation — it does not reach the container unless the service names it.
Telling people to set it in .env, without that, would have documented a step
that does nothing. Added to the shared app_env anchor, defaulted to empty so
the refusal still stands for everyone who has not opted in.

Not taken: auto-bootstrapping when the credential table is empty, which would
remove the manual step entirely and keep the audit's protection for restores.
That is the better product and it is a code change with a predicate that has
to be exactly right; this is the smallest correct fix, and #3422 stays open
for the other one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TTjbZZ6JirCMSaJzQV1RhA

.env.example

@@ -34,6 +34,34 @@ DB_PASSWORD=
 SECRET_KEY=
 
 
+# ---------------------------------------------------------------------------
+# FIRST BOOT ONLY — then delete this line
+# ---------------------------------------------------------------------------
+
+# FabledCurator encrypts your stored platform credentials with a Fernet key it
+# keeps at /images/secrets/credential_key.b64 — inside the ./images bind mount,
+# so it outlives the container. On a brand-new install that file does not exist
+# yet, and the app REFUSES TO START rather than quietly create one:
+#
+#     MissingCredentialKey: Fernet key file not found at
+#     /images/secrets/credential_key.b64
+#
+# That refusal is deliberate. Auto-creating a key is indistinguishable from the
+# disaster case — a restore that brought the database back but lost
+# ./images/secrets — and there it would mint a key that cannot decrypt anything,
+# leaving an instance that looks healthy while every paywalled download fails.
+# So the choice is yours to make explicitly, once.
+#
+# Set this for your first `up`, watch the container come up, then DELETE THE
+# LINE. Leaving it set disarms the protection permanently, on an instance that
+# by then has credentials worth protecting.
+#
+# BACK UP ./images/secrets/ ALONGSIDE YOUR DATABASE. The key is the only thing
+# that can read your stored credentials; a database restored without it needs
+# every credential re-entered by hand.
+CURATOR_BOOTSTRAP_NEW_KEY=1
+
+
 # ---------------------------------------------------------------------------
 # Optional — defaults are fine
 # ---------------------------------------------------------------------------

README.md

@@ -90,7 +90,31 @@ If you forget it, the symptom is a long build instead of a quick pull.
 The database schema is created automatically on first start — the web container
 runs its migrations before serving. Nothing to initialise by hand.
 
-A few things are worth knowing about the first few minutes:
+**One thing does need a deliberate act, and the app will not start without it.**
+FabledCurator encrypts your stored platform credentials with a key it keeps at
+`./images/secrets/credential_key.b64`. On a brand-new install that file does not
+exist, and rather than quietly creating one the app stops:
+
+```
+MissingCredentialKey: Fernet key file not found at /images/secrets/credential_key.b64
+```
+
+Set `CURATOR_BOOTSTRAP_NEW_KEY=1` in your `.env` for the first `up`, then delete
+the line once the container is running. `.env.example` ships it with that
+instruction attached.
+
+The refusal is deliberate, and worth understanding rather than working around:
+auto-creating a key is indistinguishable from the disaster case — a restore that
+brought the database back but lost `./images/secrets` — where it would mint a key
+that cannot decrypt anything, leaving an instance that looks healthy while every
+paywalled download fails. Making you say so once, on an empty install, is the
+price of that not happening silently later.
+
+**Which means: back up `./images/secrets/` alongside your database.** It is the
+only thing that can read your stored credentials. A database restored without it
+needs every credential entered again by hand.
+
+A few other things are worth knowing about the first few minutes:
 
 - **The ML worker downloads its model weights on first boot**, several GB from
   HuggingFace into `./models`. Until that finishes, tagging is queued rather

docker-compose.yml

@@ -133,6 +133,20 @@ services:
       CELERY_RESULT_BACKEND: redis://redis:6379/0
       SECRET_KEY: ${SECRET_KEY:-dev_secret_key_not_for_production_change_me}
       LOG_LEVEL: ${LOG_LEVEL:-INFO}
+      # First boot only. FabledCurator refuses to start until the credential
+      # encryption key at /images/secrets/credential_key.b64 exists, and
+      # refuses to create one unless told to — auto-creating is
+      # indistinguishable from a restore that lost ./images/secrets, where it
+      # would mint a key that decrypts nothing and leave an instance that looks
+      # healthy while every paywalled download fails.
+      #
+      # Passed through EXPLICITLY because a variable in `.env` is only used for
+      # ${...} interpolation; it does not reach the container unless it is
+      # named here. Defaulted to empty so the refusal stands for everyone who
+      # has not opted in — the app tests for exactly "1".
+      #
+      # Set it in .env for one `up`, then remove it. See .env.example.
+      CURATOR_BOOTSTRAP_NEW_KEY: ${CURATOR_BOOTSTRAP_NEW_KEY:-}
     volumes:
       - ./images:/images
       - ./import:/import