snapshot: preserve session hardening and account surface

backend/workflows/roles.py

@@ -4,6 +4,10 @@ from django.contrib.auth import get_user_model
 from django.contrib.auth.models import Group
 from django.utils.translation import gettext_lazy as _
 
+# Product-level and company-level roles intentionally coexist here.
+# Workdock uses capability checks as the long-term contract so app-registry
+# visibility can stay a presentation concern instead of an authorization layer.
+
 ROLE_PLATFORM_OWNER = 'platform_owner'
 ROLE_SUPER_ADMIN = 'super_admin'
 ROLE_ADMIN = 'admin'
@@ -27,6 +31,7 @@ ROLE_LABELS = {
 }
 
 CAPABILITIES = {
+    # Platform-only capabilities stay above any customer-company admin role.
     'manage_users': {ROLE_PLATFORM_OWNER, ROLE_SUPER_ADMIN},
     'manage_product_branding': {ROLE_PLATFORM_OWNER},
     'manage_company_config': {ROLE_PLATFORM_OWNER},
@@ -94,6 +99,8 @@ def ensure_bootstrap_role_assignments() -> None:
 
 
 def get_user_role_key(user) -> str:
+    # Keep a conservative fallback for legacy staff users until a later
+    # dedicated cleanup phase removes the remaining historical assumptions.
     if not getattr(user, 'is_authenticated', False):
         return ROLE_STAFF
     if getattr(user, 'is_superuser', False):