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/presentation/api/deps.py

@@ -1,4 +1,8 @@
-"""API dependencies using Dishka."""
+"""API dependencies using Dishka.
+
+This module defines FastAPI dependencies for authentication, authorization,
+and use case injection using Dishka DI container.
+"""
 
 from typing import Annotated, Any
 
@@ -18,7 +22,6 @@ from app.domain.exceptions import ForbiddenException, UnauthorizedException
 from app.domain.roles import Role, get_effective_role
 from app.infrastructure.auth import KeycloakAuthClient, TokenInfo
 
-# Use case dependencies - injected via Dishka
 CreatePostDep = FromDishka[CreatePostUseCase]
 GetPostDep = FromDishka[GetPostUseCase]
 UpdatePostDep = FromDishka[UpdatePostUseCase]
@@ -26,12 +29,18 @@ DeletePostDep = FromDishka[DeletePostUseCase]
 ListPostsDep = FromDishka[ListPostsUseCase]
 PublishPostDep = FromDishka[PublishPostUseCase]
 
-# Security scheme
 security = HTTPBearer(auto_error=False)
 
 
 def get_keycloak_client(request: Request) -> KeycloakAuthClient:
-    """Get Keycloak client from DI container via request state."""
+    """Get Keycloak client from DI container via request state.
+
+    Args:
+        request: FastAPI request object.
+
+    Returns:
+        KeycloakAuthClient instance from container.
+    """
     client: KeycloakAuthClient = request.state.dishka_container.get(KeycloakAuthClient)
     return client
 
@@ -40,7 +49,18 @@ async def get_current_token_info(
     credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(security)],
     request: Request,
 ) -> TokenInfo:
-    """Validate token and return token info from Keycloak."""
+    """Validate token and return token info from Keycloak.
+
+    Args:
+        credentials: HTTP authorization credentials.
+        request: FastAPI request object.
+
+    Returns:
+        Validated TokenInfo instance.
+
+    Raises:
+        UnauthorizedException: If no credentials or invalid token.
+    """
     if not credentials:
         raise UnauthorizedException("Authentication required")
 
@@ -57,7 +77,14 @@ async def get_current_token_info(
 async def get_current_user_id(
     token_info: Annotated[TokenInfo, Depends(get_current_token_info)],
 ) -> str:
-    """Get current user ID from validated token."""
+    """Get current user ID from validated token.
+
+    Args:
+        token_info: Validated token info.
+
+    Returns:
+        User ID string from token.
+    """
     return token_info.user_id
 
 
@@ -65,12 +92,21 @@ CurrentUserDep = Annotated[str, Depends(get_current_user_id)]
 TokenInfoDep = Annotated[TokenInfo, Depends(get_current_token_info)]
 
 
-# Optional auth - doesn't require authentication but provides user info if available
 async def get_optional_token_info(
     credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(security)],
     request: Request,
 ) -> TokenInfo | None:
-    """Get token info if valid token provided, otherwise None (guest)."""
+    """Get token info if valid token provided, otherwise None.
+
+    For endpoints that support both authenticated and guest access.
+
+    Args:
+        credentials: HTTP authorization credentials.
+        request: FastAPI request object.
+
+    Returns:
+        TokenInfo if valid, None otherwise.
+    """
     if not credentials:
         return None
 
@@ -90,7 +126,14 @@ OptionalTokenInfoDep = Annotated[TokenInfo | None, Depends(get_optional_token_in
 async def get_optional_user_id(
     token_info: OptionalTokenInfoDep,
 ) -> str | None:
-    """Get current user ID if token is valid, otherwise None."""
+    """Get current user ID if token is valid, otherwise None.
+
+    Args:
+        token_info: Optional token info.
+
+    Returns:
+        User ID if authenticated, None for guests.
+    """
     if token_info:
         return token_info.user_id
     return None
@@ -103,6 +146,12 @@ def get_current_role(token_info: OptionalTokenInfoDep) -> Role:
     """Get effective role from token info.
 
     Returns GUEST if no valid token provided.
+
+    Args:
+        token_info: Optional token info.
+
+    Returns:
+        Effective Role enum value.
     """
     if token_info and token_info.roles:
         return get_effective_role(token_info.roles)
@@ -113,7 +162,17 @@ CurrentRoleDep = Annotated[Role, Depends(get_current_role)]
 
 
 def require_roles(allowed_roles: list[Role]) -> Any:
-    """Create dependency that checks if user has one of the allowed roles."""
+    """Create dependency that checks if user has one of the allowed roles.
+
+    Args:
+        allowed_roles: List of roles allowed to access.
+
+    Returns:
+        FastAPI Depends for role checking.
+
+    Raises:
+        ForbiddenException: If user role is not in allowed list.
+    """
 
     async def check_role(role: CurrentRoleDep) -> Role:
         if role not in allowed_roles:
@@ -125,7 +184,6 @@ def require_roles(allowed_roles: list[Role]) -> Any:
     return Depends(check_role)
 
 
-# Predefined role requirements
 RequireAdmin = require_roles([Role.ADMIN])
 RequireUser = require_roles([Role.USER, Role.ADMIN])
 RequireAny = require_roles([Role.GUEST, Role.USER, Role.ADMIN])