fix(deploy): close the POSTGRES_PASSWORD trap that broke a fresh deploy either way

README step 2 said to set "DOMAIN, JWT_SECRET, ADMIN_PASSWORD_HASH, EVENT_NAME, etc."
-- POSTGRES_PASSWORD was not in that list. .env.example said to set it and keep it in
sync with DATABASE_URL. The two documents disagreed, and both readings ended badly.

Branch A, README verbatim: the stack came up GREEN and healthy on
CHANGE_ME_use_a_strong_password -- a database credential published in the public repo.
The production secret guard covered JWT_SECRET and ADMIN_PASSWORD_HASH, and nothing
anywhere looked at the Postgres password.

Branch B, .env.example verbatim: a permanent restart loop, "password authentication
failed for user eventsnap".

The guard's own design made Branch B near-certain. It stops the APP on the first
`docker compose up -d` -- but not the `db` service in that same command, which
initialises its data directory and bakes in whatever password was in .env at that
moment. POSTGRES_PASSWORD is honoured ONLY at initdb. So the intended recovery -- see
the refusal, fix your secrets, boot again -- was exactly the sequence that broke it.
Nothing in the error named the cause, and the remedy (`down -v`) is both unguessable
and the one command you must never run once real data exists.

Three changes, which have to ship together: the guard alone would just move operators
out of Branch A and into Branch B.

- The guard now rejects a placeholder DATABASE_URL in production (the password rides
  in that URL, which is what the app actually reads). Branch A can no longer boot.
- It reports EVERY unset secret in one message instead of returning on the first.
  Fixing two secrets used to cost two boot cycles, on a stack where Caddy waits on the
  unhealthy app throughout, and each avoidable cycle is another chance to reach for -v.
- A 28P01 handler in db.rs turns the unguessable failure into a self-explaining one:
  it names the initdb semantics, gives `down -v` with an explicit "deletes db + media +
  exports, no undo", and gives the ALTER ROLE alternative for when data already exists.

Docs: step 2 now names POSTGRES_PASSWORD and says every secret must be set BEFORE the
first up; the troubleshooting block covers the auth-failure loop and both remedies.

Also replaces htpasswd (apache2-utils -- not on a stock VPS) with
`docker run --rm caddy:2-alpine caddy hash-password`, an image the stack already pulls,
in README, .env.example and the guard's own message. Verified the output ($2a$14)
against the shipped $2y$12 example.

Verified on a real Postgres, not just in tests: Branch A refuses and names DATABASE_URL;
all three placeholders report in one boot; a volume initialised with one password and
connected to with another prints the diagnostic; an unrelated connect failure (dead
port) stays silent. 8 unit tests, including that non-prod ignores all of it so the e2e
stack is unaffected.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.env.example

@@ -12,6 +12,14 @@ APP_ENV=production
 # ── Database ──────────────────────────────────────────────────────────────────
 # Set a strong password and keep it in sync between DATABASE_URL and
 # POSTGRES_PASSWORD. Generate one with: openssl rand -hex 24
+#
+# SET THIS BEFORE THE FIRST `docker compose up -d`. Postgres reads POSTGRES_PASSWORD
+# only when it initialises its data directory, on that very first boot. Change it
+# afterwards and the app authenticates with the new password against a volume still
+# holding the old one — a permanent restart loop ("password authentication failed").
+# The only ways out are restoring the old password or `docker compose down -v`, which
+# deletes the database, the media and the exports. In production the app refuses to
+# boot while this is still the placeholder below, so it cannot be missed by accident.
 DATABASE_URL=postgres://eventsnap:CHANGE_ME_use_a_strong_password@db:5432/eventsnap
 POSTGRES_USER=eventsnap
 POSTGRES_PASSWORD=CHANGE_ME_use_a_strong_password
@@ -30,7 +38,9 @@ JWT_SECRET=change_me_to_a_random_64_byte_hex_string
 SESSION_EXPIRY_DAYS=30
 
 # Admin dashboard password (bcrypt hash).
-# Generate with: htpasswd -bnBC 12 "" yourpassword | tr -d ':\n'
+# Generate with an image the stack already pulls (htpasswd needs apache2-utils, which
+# a stock VPS does not have):
+#   docker run --rm caddy:2-alpine caddy hash-password --plaintext 'yourpassword'
 # IMPORTANT: keep the SINGLE QUOTES. A bcrypt hash is full of `$` (e.g. $2b$12$…$…),
 # and both Docker Compose's env_file interpolation and dotenvy's variable substitution
 # would otherwise eat the `$…` segments (reading them as unset vars) and corrupt the