Document NATS per-user token gotcha and Coolify deploy-status vs runtime-health distinction

CLAUDE.md

@@ -128,6 +128,12 @@ Rotating the password: PATCH the `NATS_PASSWORD` env on the Coolify app, then re
 
 To add a second user (e.g. a scoped app account), edit the `authorization.users` array in the `configs.nats-conf.content` block in `docker-compose.yml`, and set any new credential env vars in Coolify.
 
+## Gotchas learned the hard way
+
+- **No per-user `token` field in NATS config.** `authorization.users = [...]` entries only accept `user+password`, `nkey`, or JWT — a `token` key inside a users entry makes `nats-server` refuse to start with `unknown field "token"`. The `token` key is only valid at the **top level** of `authorization`, and it defines a single server-wide token (mutually exclusive with `users`). To give a specific user a bearer-token-style credential, put the random token in the `password` field. On the wire it's the standard NATS user/password auth mechanism; only the semantics (opaque random string vs. human-picked password) differ.
+
+- **Coolify's deploy status ≠ container health.** A deploy returning `status: "finished"` from `/api/v1/deployments/…` just means the build + `docker compose up -d` step ran to completion. If the container then crash-loops (e.g. bad `nats-server.conf`), the deploy is still "finished" but the app's `/api/v1/applications/{uuid}` shows `status: "restarting:unknown"` and `/api/v1/applications/{uuid}/logs` returns `Application is not running.` — no runtime logs via API. Fall back to `docker logs <container-name>` on the Coolify host to see why the process is dying. Container name pattern: `nats-<app-uuid>-<random>`.
+
 ## Files in this repo
 
 | File | Purpose |