php-fpm: refactor with deterministic config files & improved debug

README.md

@@ -31,12 +31,21 @@ The CI workflow is configured to build with the repository root as the Docker bu
 
 - Images use `/var/www/html` as the webroot. When you mount a host directory over that path the mount replaces the image contents, including ownership.
 - Recommended safe options:
+
   - Pre-chown host files to UID/GID 1000 before starting containers:
+
   ```bash
   sudo chown -R 1000:1000 ./wp_root
   ```
+
   - Or enable the entrypoint-based fixup in php-fpm by setting `CHOWN_ON_START=1` for the `php-fpm` service (the entrypoint is guarded — it only runs when this env is explicitly enabled).
 
+  ## Logging & debugging
+
+  - PHP-FPM is configured to stream its master/process worker logs and PHP error log to stderr, so `docker compose logs php-fpm` (or your platform equivalent) will always contain fatal errors.
+  - When you need full stack traces in the browser, set `FORCE_DEBUG_ERRORS=1` on the `php-fpm` service. The shipped `force-debug.php` bootstrap will notice the flag, turn on verbose error reporting, and emit a single log line indicating that debug mode is active.
+  - Remove or unset `FORCE_DEBUG_ERRORS` after troubleshooting so production responses stay clean.
+
 ## Local Testing & Development
 
 Use the provided `docker-compose.yml` in the repo root for local development — it builds images from the repo (so shared files are available) and mounts `./wp_root` for site content.