documentation and env changes

docs/admin-and-settings.md

@@ -0,0 +1,48 @@
+# Admin & Settings
+
+## Access control
+- All `/admin/*` pages require authentication; unauthorized visitors get redirected through `/login`, which opens the auth modal automatically.
+- `ROLE_MODERATOR` grants dashboard + user list access.
+- `ROLE_ADMIN` adds settings access and moderator promotion/demotion abilities.
+
+## Site dashboard (ROLE_MODERATOR)
+- URL: `/admin/dashboard`
+- Shows total counts plus the most recent reviews and albums so staff can moderate activity quickly.
+
+## User management (ROLE_MODERATOR)
+- URL: `/admin/users`
+- Table columns:
+  - Name/email/roles + album/review counts (queried via aggregates).
+  - Action buttons always render; disabled buttons show tooltips describing why (e.g., "Administrators cannot be deleted").
+- Moderators:
+  - Create new accounts via the inline form without logging themselves out.
+  - Delete standard users or other moderators (except themselves).
+- Admins:
+  - Toggle moderator role (Promote/Demote) for non-admin accounts.
+  - Cannot delete or demote other admins—admin privileges supersede moderator status.
+
+## Site settings (ROLE_ADMIN)
+- URL: `/admin/settings`
+- Form persists Spotify Client ID/Secret in the DB (no restart needed).
+- Toggle “Allow self-service registration” to pause public sign-ups while keeping `/admin/users` creation available to staff.
+- The setting syncs with the `APP_ALLOW_REGISTRATION` environment variable each time Symfony boots (change the env value and restart to enforce). UI changes persist while the process runs.
+- CSRF + role guards prevent unauthorized updates.
+
+## User management
+- Promote an admin:
+```bash
+docker compose exec php php bin/console app:promote-admin user@example.com
+```
+- Promote a moderator:
+```bash
+docker compose exec php php bin/console app:promote-moderator user@example.com
+```
+
+## Appearance
+- `/settings` provides a dark/light mode toggle.
+- Preference saved in a cookie; applied via `data-bs-theme`.
+
+## Useful tips
+- Registration toggle can be locked by environment (`APP_ALLOW_REGISTRATION`), in which case the UI explains that the value is immutable.
+- Changing Spotify credentials in settings is effective immediately; no restart is required.
+- Admin UI actions are CSRF‑protected and role‑checked; if a button appears disabled, hover for a tooltip explanation.