docs: add AI code generation requirements and comprehensive Google-style docstrings

- Add AI code generation requirements to AGENTS.md
- Add module-level docstrings to all 46 Python modules
- Add detailed Google-style docstrings to all classes and functions
- Remove all inline comments following self-documenting code principle
- Include Args, Returns, Raises sections in function docstrings
- Add Attributes and Examples sections to class docstrings

app/infrastructure/auth/models.py

@@ -1,4 +1,8 @@
-"""Keycloak authentication models."""
+"""Keycloak authentication models.
+
+This module defines data models for Keycloak authentication data
+including token info and user profiles.
+"""
 
 from dataclasses import dataclass, field
 from typing import Any
@@ -6,7 +10,24 @@ from typing import Any
 
 @dataclass(frozen=True)
 class TokenInfo:
-    """Information about validated token from Keycloak."""
+    """Information about validated token from Keycloak.
+
+    Contains the result of token introspection including user claims
+    and role information.
+
+    Attributes:
+        active: Whether the token is active and valid.
+        user_id: Subject identifier from token.
+        username: Username from token claims.
+        email: Email from token claims.
+        roles: List of roles from token.
+        raw_claims: Complete raw claims from token.
+
+    Example:
+        >>> token_info = TokenInfo(active=True, user_id="123", roles=["user"])
+        >>> if token_info.is_valid:
+        ...     grant_access()
+    """
 
     active: bool
     user_id: str = ""
@@ -17,13 +38,32 @@ class TokenInfo:
 
     @property
     def is_valid(self) -> bool:
-        """Check if token is valid and active."""
+        """Check if token is valid and active.
+
+        Returns:
+            True if token is active and has user_id.
+        """
         return self.active and bool(self.user_id)
 
 
 @dataclass(frozen=True)
 class KeycloakUser:
-    """User information from Keycloak."""
+    """User information from Keycloak.
+
+    Contains user profile data from Keycloak userinfo endpoint.
+
+    Attributes:
+        id: User subject identifier.
+        username: Username.
+        email: Email address.
+        first_name: First name.
+        last_name: Last name.
+        roles: List of user roles.
+        is_active: Whether user account is active.
+
+    Example:
+        >>> user = KeycloakUser(id="123", username="john", email="john@example.com")
+    """
 
     id: str
     username: str