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
 # ---------------------------------------------------------------------------