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/domain/roles.py

@@ -1,4 +1,8 @@
-"""Role-based access control definitions."""
+"""Role-based access control definitions.
+
+This module provides role and permission definitions for the application
+along with utility functions and decorators for permission checking.
+"""
 
 from collections.abc import Callable
 from enum import Enum
@@ -9,7 +13,20 @@ from app.domain.exceptions import ForbiddenException
 
 
 class Role(str, Enum):
-    """User roles in the system."""
+    """User roles in the system.
+
+    Defines the available user roles with hierarchical permissions.
+    ADMIN has full access, USER has standard access, GUEST has read-only.
+
+    Attributes:
+        ADMIN: Administrator with full system access.
+        USER: Regular authenticated user.
+        GUEST: Unauthenticated or limited access user.
+
+    Example:
+        >>> if role == Role.ADMIN:
+        ...     grant_full_access()
+    """
 
     ADMIN = "admin"
     USER = "user"
@@ -17,9 +34,16 @@ class Role(str, Enum):
 
 
 class Permission:
-    """Permission definitions."""
+    """Permission definitions.
+
+    Contains string constants for all available permissions in the system.
+    Used for role-based access control checks.
+
+    Example:
+        >>> if has_permission(role, Permission.POST_CREATE):
+        ...     allow_post_creation()
+    """
 
-    # Post permissions
     POST_CREATE = "post:create"
     POST_READ = "post:read"
     POST_READ_UNPUBLISHED = "post:read_unpublished"
@@ -28,7 +52,6 @@ class Permission:
     POST_PUBLISH = "post:publish"
 
 
-# Role-based permission mapping
 ROLE_PERMISSIONS: dict[Role, list[str]] = {
     Role.ADMIN: [
         Permission.POST_CREATE,
@@ -52,24 +75,52 @@ ROLE_PERMISSIONS: dict[Role, list[str]] = {
 
 
 def has_permission(role: Role, permission: str) -> bool:
-    """Check if role has specific permission."""
+    """Check if role has specific permission.
+
+    Args:
+        role: User role to check.
+        permission: Permission string to verify.
+
+    Returns:
+        True if role has the permission, False otherwise.
+
+    Example:
+        >>> has_permission(Role.ADMIN, Permission.POST_DELETE)
+        True
+    """
     return permission in ROLE_PERMISSIONS.get(role, [])
 
 
 def require_permission(
     permission: str,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Decorator to require specific permission."""
+    """Decorator to require specific permission.
+
+    Creates a decorator that checks if the user has the required permission
+    before executing the decorated function.
+
+    Args:
+        permission: Permission string required for execution.
+
+    Returns:
+        Decorator function for permission checking.
+
+    Raises:
+        ForbiddenException: If user lacks the required permission.
+
+    Example:
+        >>> @require_permission(Permission.POST_CREATE)
+        ... async def create_post():
+        ...     ...
+    """
 
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
         @wraps(func)
         async def wrapper(*args: Any, **kwargs: Any) -> Any:
-            # Get token_info from kwargs
             token_info = kwargs.get("token_info")
             if not token_info:
                 raise ForbiddenException("Authentication required")
 
-            # Determine role from token or default to guest
             roles = getattr(token_info, "roles", [])
             if Role.ADMIN.value in roles:
                 role = Role.ADMIN
@@ -93,7 +144,18 @@ def require_permission(
 def get_effective_role(roles: list[str]) -> Role:
     """Determine effective role from list of roles.
 
-    Priority: admin > user > guest
+    Evaluates multiple roles and returns the highest privilege role.
+    Priority order: admin > user > guest.
+
+    Args:
+        roles: List of role strings from token.
+
+    Returns:
+        Highest privilege Role enum value.
+
+    Example:
+        >>> get_effective_role(["user", "admin"])
+        <Role.ADMIN: 'admin'>
     """
     if Role.ADMIN.value in roles:
         return Role.ADMIN