Enhance security documentation with details on administrative credentials, credential reset process, route guard dependencies, and session management.

architecture/08_concepts/03_security.md

@@ -12,6 +12,20 @@ Role-based access controls (RBAC) are implemented to restrict data access based
 
 Also see [Authentication and Authorization](../08_concepts.md#authentication-and-authorization) and the [Data Model](../08_concepts/02_data_model.md#user-roles) sections.
 
+- Default administrative credentials are provided at deployment time through environment variables (`CALMINER_SEED_ADMIN_EMAIL`, `CALMINER_SEED_ADMIN_USERNAME`, `CALMINER_SEED_ADMIN_PASSWORD`, `CALMINER_SEED_ADMIN_ROLES`). These values are consumed by a shared bootstrap helper on application startup, ensuring mandatory roles and the administrator account exist before any user interaction.
+- Operators can request a managed credential reset by setting `CALMINER_SEED_FORCE=true`. On the next startup the helper rotates the admin password and reapplies role assignments, so downstream environments must update stored secrets immediately after the reset.
+- The bootstrap helper is idempotent; when no changes are required, startup completes without mutating the database, preserving audit trails while still verifying the presence of required roles.
+
+### Route Guard Dependencies
+
+- `require_project_resource` and `require_scenario_resource` build on service-level authorization helpers to enforce role checks while resolving requested entities.
+- `require_project_scenario_resource` ensures the scenario referenced by a request belongs to the provided project identifier before continuing processing.
+- These dependencies surface 401/403/404 responses consistently across API and UI handlers and can be composed with additional ownership checks when project member metadata is introduced.
+
+## Session Management
+
+Authentication relies on a pair of signing tokens issued as `calminer_access_token` and `calminer_refresh_token` HttpOnly cookies. An `AuthSessionMiddleware` component validates incoming access tokens, refreshes them when still covered by a valid refresh token, and attaches the resolved user context to `request.state.auth_session`. Logout clears both cookies and redirects users back to the login form. This approach keeps credentials out of JavaScript, supports transparent rotation of short-lived access tokens, and ensures templates can adapt their navigation to the current session state.
+
 ## Audit Logging
 
 Comprehensive logging of user activities and system events is maintained for monitoring and auditing purposes. Also see [Error Handling and Logging](../08_concepts.md#error-handling-and-logging) section for more details.