[mattv8]

Summary

• Add actionable, secret-safe recovery guidance to rejected runtime configuration without changing validation policy or error prefixes.
• Explain the required APP_SECRET format, generation for new installations only, and unchanged APP_ENCRYPTION_KEY reuse for upgrades.
• Explain how to add APP_URL to older .env files, select the browser-facing public URL behind reverse proxies, and recreate the Compose service after edits.
• Document private .env backups and stopping MariaDB before filesystem-copy backups; extend startup guidance and disclosure regression tests.

Scope and commits

Only the four files changed for this task are included. No production .env, secrets, scratch investigation artifacts, deployments, or unrelated changes are included.

• fix: add actionable startup configuration diagnostics — validator and regression tests.
• docs: explain required application settings for upgrades — README and .env.example.

Verification

• Re-ran the host Bash startup-security suite before committing: passed; optional full container lifecycle checks skipped without POSTPORTAL_TEST_IMAGE.
• Re-ran Bash syntax checks, ShellCheck, and git whitespace checks: passed.
• Confirmed the committed patch is byte-identical to the reviewed and tested final patch from this task.
• Earlier verification of that same patch passed: Linux Bash startup suite; disposable-container entrypoint smoke tests for missing/invalid APP_SECRET and APP_URL before MariaDB starts; 57-case baseline-versus-updated validation-policy comparison; README environment-template consistency.
• Focused PHP secret/URL and migration/CLI suites on the same unchanged PHP sources: 57 tests and 146 assertions passed. PHPUnit emitted one deprecation per invocation.
• High-accuracy review and scoped re-review passed after addressing the findings.

Limitations

The full rebuilt-image database lifecycle suite was not run locally; CI remains the full integration gate. No production configuration was changed or container restarted.