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/application/use_cases/publish_post.py

@@ -1,4 +1,8 @@
-"""Publish post use case."""
+"""Publish post use case.
+
+This module implements the use case for publishing and unpublishing blog posts.
+Includes authorization checks to ensure users can only manage their own posts.
+"""
 
 from uuid import UUID
 
@@ -10,18 +14,48 @@ from app.domain.repositories import PostRepository
 
 
 class PublishPostUseCase:
-    """Use case for publishing/unpublishing a blog post."""
+    """Use case for publishing/unpublishing a blog post.
+
+    Handles post publication state changes with authorization checks.
+    Users can only publish or unpublish posts they authored.
+
+    Attributes:
+        _post_repo: Repository for post data access.
+        _tx_manager: Transaction manager for commit control.
+
+    Example:
+        >>> use_case = PublishPostUseCase(post_repo, tx_manager)
+        >>> post = await use_case.publish(post_id, user_id)
+    """
 
     def __init__(
         self,
         post_repo: PostRepository,
         tx_manager: TransactionManager,
     ) -> None:
+        """Initialize use case with dependencies.
+
+        Args:
+            post_repo: Repository for post operations.
+            tx_manager: Transaction manager instance.
+        """
         self._post_repo = post_repo
         self._tx_manager = tx_manager
 
     async def publish(self, post_id: UUID, current_user_id: str) -> PostResponseDTO:
-        """Publish a post."""
+        """Publish a post.
+
+        Args:
+            post_id: Unique identifier of the post.
+            current_user_id: ID of the user requesting publication.
+
+        Returns:
+            PostResponseDTO with updated post data.
+
+        Raises:
+            NotFoundException: If post with given ID does not exist.
+            ForbiddenException: If user is not the post author.
+        """
         post = await self._post_repo.get_by_id(post_id)
         if not post:
             raise NotFoundException(f"Post with id '{post_id}' not found")
@@ -36,7 +70,19 @@ class PublishPostUseCase:
         return self._map_to_dto(post)
 
     async def unpublish(self, post_id: UUID, current_user_id: str) -> PostResponseDTO:
-        """Unpublish a post."""
+        """Unpublish a post.
+
+        Args:
+            post_id: Unique identifier of the post.
+            current_user_id: ID of the user requesting unpublish.
+
+        Returns:
+            PostResponseDTO with updated post data.
+
+        Raises:
+            NotFoundException: If post with given ID does not exist.
+            ForbiddenException: If user is not the post author.
+        """
         post = await self._post_repo.get_by_id(post_id)
         if not post:
             raise NotFoundException(f"Post with id '{post_id}' not found")
@@ -51,7 +97,14 @@ class PublishPostUseCase:
         return self._map_to_dto(post)
 
     def _map_to_dto(self, post: Post) -> PostResponseDTO:
-        """Map domain entity to response DTO."""
+        """Map domain entity to response DTO.
+
+        Args:
+            post: Domain post entity.
+
+        Returns:
+            PostResponseDTO with all post attributes.
+        """
         return PostResponseDTO(
             id=post.id,
             title=post.title.value,