docs: Logger daily rotation requires a PHP-user-writable log directory

rename() needs write permission on the DIRECTORY; without it rotation
fails silently while appends succeed, growing log.txt unbounded.
Documents the correct ownership/mode, the health check, and the
Nov 2021 - Jul 2026 production incident (945MB log.txt filled the
15GB disk and truncated a Solr reindex). Also notes that these logs
contain raw authenticate() passwords and must be treated as secrets.

README.md

@@ -0,0 +1,54 @@
+# php-bsrutils (`bsr/utils`)
+
+Shared utilities for the Callio API family: `Configuration`, `Logger`,
+`FileSystem`, `WhichEnv`. Consumed by `php-callioapi`, `bsr/webservice`,
+`bsr/db`.
+
+## Logger
+
+Request/diagnostic logger writing plain-text lines to the file configured as
+`log.file` (see `Configuration`). Used by `bsr/webservice` to log every API
+call as:
+
+```
+<ip> - [<date>] - <status> - <ms> - <func>(<params>)
+```
+
+### Built-in daily rotation — directory must be writable by the PHP user
+
+The Logger rotates its own file: on the first write after midnight it renames
+`log.txt` → `log.txt.2` (shifting older files up) and keeps roughly ten days
+(`log.txt.2` … `log.txt.9`; higher numbers are deleted). There is **no
+logrotate involvement** — do not add a logrotate entry for these files, it
+would race the built-in rotation.
+
+**Critical operational requirement:** `rename()` needs *write permission on
+the log directory*, not just the file. The PHP process (typically `www-data`)
+can happily keep appending to a `log.txt` it owns while every rotation
+attempt silently fails, because the directory denies it — PHP's `rename()`
+warning is not surfaced anywhere.
+
+Known real-world failure (production `callioapi`, Nov 2021 → Jul 2026): the
+log directory was owned `guillermo:users` mode `755`, so `www-data` could not
+rename. Rotation died silently and `log.txt` grew to ~945 MB, eventually
+filling the 15 GB disk and truncating a Solr reindex. The rotated-file dates
+freeze at the moment the directory permissions broke — that is the telltale
+sign to look for.
+
+Correct setup (matches the vhosts where rotation works):
+
+```sh
+chown <deploy-user>:www-data /var/www/<vhost>/log
+chmod g+w /var/www/<vhost>/log
+```
+
+Health check: `ls /var/www/<vhost>/log` — if `log.txt.2`'s mtime is older
+than yesterday while `log.txt` keeps growing, rotation is broken; check the
+directory permissions first.
+
+### Security note
+
+`bsr/webservice` logs every API call **with raw parameters**, which for
+`authenticate(user, password)` means plaintext passwords end up in these
+files. Treat the log directory as secret-bearing: never make it
+world-readable, and scrub/redact before copying logs elsewhere.