fix: correct service-token one-liner; entrypoint points at --entrypoint php

The README and .env.example one-liner for generating UI_SERVICE_TOKEN ran
`docker compose run ... api php -r ...`, which the api image's dispatcher
entrypoint rejected with `Unknown mode: php`. Snippets now use
`--entrypoint php` per the SPEC's documented convention. Both image
entrypoints' "Unknown mode" error now points at `--entrypoint <bin>` so
the next operator who copy-pastes the old form gets a working hint
instead of a dead-end.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.env.example

@@ -21,9 +21,11 @@ UI_PORT=8080
 # -----------------------------------------------------------------------------
 # IRDB-format service token. The api uses this to authenticate the ui's
 # calls; the ui presents it on every API request together with
-# X-Acting-User-Id. Format: irdb_svc_<32 base32 chars>. Generate one with:
-#   docker compose run --rm -T api php -r 'require "/app/vendor/autoload.php";
-#       echo (new App\Domain\Auth\TokenIssuer())->issue(App\Domain\Auth\TokenKind::Service);'
+# X-Acting-User-Id. Format: irdb_svc_<32 base32 chars>. Generate one with
+# (note `--entrypoint php` — the api image's default entrypoint is a
+# dispatcher with `api` / `migrate` modes, so ad-hoc PHP bypasses it):
+#   docker compose run --rm -T --entrypoint php api -r 'require "/app/vendor/autoload.php";
+#       echo (new App\Domain\Auth\TokenIssuer())->issue(App\Domain\Auth\TokenKind::Service), PHP_EOL;'
 UI_SERVICE_TOKEN=
 
 # -----------------------------------------------------------------------------

CHANGELOG.md

@@ -24,6 +24,14 @@ collide with the per-component `api-v…` / `ui-v…` tags in this monorepo.
   fixed, so internal docker DNS, healthchecks, and baked Caddyfiles are
   unchanged — only the published host-side mapping moves.
 
+### Fixed
+- The "generate `UI_SERVICE_TOKEN`" one-liner in `README.md` and
+  `.env.example` was missing `--entrypoint php`, so it hit the api
+  image's `api`/`migrate` dispatcher and exited with `Unknown mode: php`.
+  Snippets are corrected, and both image entrypoints now point operators
+  at `--entrypoint <bin>` when they hit an unknown mode, so the next
+  copy-paste mistake is self-explanatory.
+
 ## [0.9] — 2026-05-06
 
 First public preview of the bundled stack. Everything specified in

README.md

@@ -49,8 +49,10 @@ secret you need to generate. Use these one-liners:
 openssl rand -hex 32
 
 # IRDB-format service token (UI_SERVICE_TOKEN — looks like irdb_svc_…)
-docker compose run --rm -T api php -r 'require "/app/vendor/autoload.php";
-    echo (new App\Domain\Auth\TokenIssuer())->issue(App\Domain\Auth\TokenKind::Service);'
+# Note the `--entrypoint php` — the api image's default entrypoint is a
+# dispatcher (`api` / `migrate` modes), so ad-hoc PHP commands bypass it.
+docker compose run --rm -T --entrypoint php api -r 'require "/app/vendor/autoload.php";
+    echo (new App\Domain\Auth\TokenIssuer())->issue(App\Domain\Auth\TokenKind::Service), PHP_EOL;'
 
 # Local admin password hash (LOCAL_ADMIN_PASSWORD_HASH — Argon2id)
 php -r "echo password_hash('your-admin-password', PASSWORD_ARGON2ID);"

api/docker/entrypoint.sh

@@ -26,6 +26,10 @@ case "$mode" in
     *)
         echo "Unknown mode: $mode" >&2
         echo "Usage: entrypoint.sh [api|migrate]" >&2
+        echo "" >&2
+        echo "To run an ad-hoc PHP command (e.g. 'php', 'composer', 'vendor/bin/phpunit')," >&2
+        echo "bypass this dispatcher with '--entrypoint <bin>'. For example:" >&2
+        echo "  docker compose run --rm --entrypoint php api bin/console auth:create-token --kind=admin --role=admin" >&2
         exit 1
         ;;
 esac

ui/docker/entrypoint.sh

@@ -10,6 +10,10 @@ case "$mode" in
     *)
         echo "Unknown mode: $mode" >&2
         echo "Usage: entrypoint.sh [ui]" >&2
+        echo "" >&2
+        echo "To run an ad-hoc PHP command (e.g. 'php', 'composer', 'vendor/bin/phpunit')," >&2
+        echo "bypass this dispatcher with '--entrypoint <bin>'. For example:" >&2
+        echo "  docker compose run --rm --entrypoint php ui vendor/bin/phpunit" >&2
         exit 1
         ;;
 esac