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

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