documentation and env changes

docs/auth-and-users.md

@@ -0,0 +1,48 @@
+# Authentication & Users
+
+## Login & Registration (modal)
+- Login and sign‑up are handled in a Bootstrap modal.
+- AJAX submits keep users on the page; a successful login refreshes state.
+- Remember‑me cookie keeps users logged in across sessions.
+
+## Roles & Permissions
+- `ROLE_USER` — default for registered users
+- `ROLE_MODERATOR` — can access dashboard and user management, and moderate content
+- `ROLE_ADMIN` — adds Site Settings access and moderator promotion/demotion
+
+Promotion (from your host):
+```bash
+docker compose exec tonehaus php bin/console app:promote-moderator mod@example.com
+docker compose exec tonehaus php bin/console app:promote-admin admin@example.com
+```
+
+### Access flow
+- Visiting `/admin/*` while unauthenticated redirects through `/login`, which reopens the modal.
+- Role hierarchy applies: Admin ⊇ Moderator ⊇ User.
+- Controllers, templates, and voters enforce privilege boundaries (e.g., site settings are admin‑only).
+
+## Public registration toggle
+- Toggle in UI: `/admin/settings` (stored in DB)
+- Env override: `APP_ALLOW_REGISTRATION=0|1` (env has priority on each boot)
+- When disabled, the modal replaces “Sign up” with a tooltip explaining registration is closed. Staff can still create users via `/admin/users`.
+
+## User management (moderator+)
+- `/admin/users` lists accounts with album/review counts and actions:
+  - Create accounts inline (does not affect the current session)
+  - Delete users (guards prevent deleting self or administrators)
+  - Admins can Promote/Demote Moderator on non‑admins
+
+## Profiles & Passwords
+- `/account/profile`: update email and display name
+- `/account/password`: change password (requires current password)
+
+## Demo accounts & avatars
+```bash
+docker compose exec tonehaus php bin/console app:seed-demo-users --count=50
+docker compose exec tonehaus php bin/console app:seed-user-avatars --overwrite
+```
+
+## Logout
+- Link in the user menu calls `/logout` (handled by Symfony security).
+
+