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/schemas/post.py

@@ -1,4 +1,8 @@
-"""API schemas for posts."""
+"""API schemas for posts.
+
+This module defines Pydantic schemas for request/response validation
+in the posts API endpoints.
+"""
 
 from datetime import datetime
 from uuid import UUID
@@ -7,7 +11,14 @@ from pydantic import BaseModel, ConfigDict, Field
 
 
 class PostBaseSchema(BaseModel):
-    """Base schema for posts."""
+    """Base schema for posts.
+
+    Contains common fields shared across post schemas.
+
+    Attributes:
+        title: Post title (3-200 characters).
+        content: Post content (10-50000 characters).
+    """
 
     model_config = ConfigDict(from_attributes=True)
 
@@ -16,13 +27,27 @@ class PostBaseSchema(BaseModel):
 
 
 class PostCreateSchema(PostBaseSchema):
-    """Schema for creating a post."""
+    """Schema for creating a post.
+
+    Extends base schema with creation-specific fields.
+
+    Attributes:
+        tags: List of tags for categorization.
+    """
 
     tags: list[str] = Field(default_factory=list)
 
 
 class PostUpdateSchema(BaseModel):
-    """Schema for updating a post."""
+    """Schema for updating a post.
+
+    All fields are optional for partial updates.
+
+    Attributes:
+        title: Optional new title.
+        content: Optional new content.
+        tags: Optional new tags list.
+    """
 
     model_config = ConfigDict(from_attributes=True)
 
@@ -32,7 +57,21 @@ class PostUpdateSchema(BaseModel):
 
 
 class PostResponseSchema(BaseModel):
-    """Schema for post response."""
+    """Schema for post response.
+
+    Complete post data for API responses.
+
+    Attributes:
+        id: Unique post identifier.
+        title: Post title.
+        content: Post content.
+        slug: URL-friendly slug.
+        author_id: Author identifier.
+        published: Publication status.
+        tags: List of tags.
+        created_at: Creation timestamp.
+        updated_at: Last update timestamp.
+    """
 
     model_config = ConfigDict(from_attributes=True)
 
@@ -48,19 +87,38 @@ class PostResponseSchema(BaseModel):
 
 
 class PostListResponseSchema(BaseModel):
-    """Schema for list of posts response."""
+    """Schema for list of posts response.
+
+    Paginated response for list endpoints.
+
+    Attributes:
+        items: List of post items.
+        total: Total number of items.
+    """
 
     items: list[PostResponseSchema]
     total: int
 
 
 class PostSearchSchema(BaseModel):
-    """Schema for searching posts."""
+    """Schema for searching posts.
+
+    Search query parameters.
+
+    Attributes:
+        query: Search query string (1-100 characters).
+    """
 
     query: str = Field(..., min_length=1, max_length=100)
 
 
 class PostPublishSchema(BaseModel):
-    """Schema for publishing/unpublishing a post."""
+    """Schema for publishing/unpublishing a post.
+
+    Publication status toggle.
+
+    Attributes:
+        published: Desired publication status.
+    """
 
     published: bool