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

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