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/value_objects/__init__.py

@@ -1,4 +1,8 @@
-"""Value objects."""
+"""Value objects.
+
+This module re-exports all domain value objects that represent
+immutable validated domain concepts.
+"""
 
 from app.domain.value_objects.base import ValueObject
 from app.domain.value_objects.content import Content

app/domain/value_objects/base.py

@@ -1,4 +1,9 @@
-"""Base value object for DDD domain layer."""
+"""Base value object for DDD domain layer.
+
+This module provides the foundational ValueObject class that all domain
+value objects must inherit from. Implements equality, hashing, and
+validation patterns for immutable value objects.
+"""
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
@@ -9,29 +14,78 @@ T = TypeVar("T")
 
 @dataclass(frozen=True, slots=True)
 class ValueObject(ABC, Generic[T]):
-    """Base class for all value objects."""
+    """Base class for all value objects.
+
+    Value objects are immutable objects defined by their attributes rather
+    than identity. They are validated on creation and provide type safety.
+
+    Attributes:
+        value: The underlying value wrapped by the value object.
+
+    Type Parameters:
+        T: Type of the wrapped value.
+
+    Example:
+        >>> class Email(ValueObject[str]):
+        ...     def _validate(self) -> None:
+        ...         if "@" not in self.value:
+        ...             raise ValueError("Invalid email")
+    """
 
     value: T
 
     def __post_init__(self) -> None:
+        """Validate value object after initialization.
+
+        Automatically called by dataclass after __init__. Triggers
+        the validation method to ensure value integrity.
+        """
         self._validate()
 
     @abstractmethod
     def _validate(self) -> None:
-        """Validate the value object. Raise ValueError if invalid."""
+        """Validate the value object.
+
+        Must be implemented by subclasses to enforce value constraints.
+
+        Raises:
+            ValueError: If the value does not meet validation criteria.
+        """
         ...
 
     def __eq__(self, other: object) -> bool:
+        """Compare value objects by value.
+
+        Args:
+            other: Another object to compare with.
+
+        Returns:
+            True if both are ValueObjects with equal values.
+        """
         if not isinstance(other, ValueObject):
             return False
         return bool(self.value == other.value)
 
     def __hash__(self) -> int:
+        """Get hash based on wrapped value.
+
+        Returns:
+            Hash of the underlying value.
+        """
         return hash(self.value)
 
     def __str__(self) -> str:
+        """Convert value object to string.
+
+        Returns:
+            String representation of the wrapped value.
+        """
         return str(self.value)
 
     def to_primitive(self) -> Any:
-        """Convert value object to primitive type."""
+        """Convert value object to primitive type.
+
+        Returns:
+            The underlying primitive value.
+        """
         return self.value

app/domain/value_objects/content.py

@@ -1,4 +1,8 @@
-"""Content value object."""
+"""Content value object.
+
+This module defines the Content value object for blog post content
+with validation for minimum and maximum length constraints.
+"""
 
 from dataclasses import dataclass
 
@@ -7,12 +11,35 @@ from app.domain.value_objects.base import ValueObject
 
 @dataclass(frozen=True, slots=True)
 class Content(ValueObject[str]):
-    """Blog post content value object."""
+    """Blog post content value object.
+
+    Wraps and validates blog post content ensuring it meets length
+    requirements and is not empty.
+
+    Attributes:
+        value: The content string value.
+        MIN_LENGTH: Minimum allowed content length (10 characters).
+        MAX_LENGTH: Maximum allowed content length (50000 characters).
+
+    Raises:
+        ValueError: If content is empty, too short, or too long.
+
+    Example:
+        >>> content = Content("This is valid content...")
+        >>> print(content.value)
+    """
 
     MIN_LENGTH: int = 10
     MAX_LENGTH: int = 50000
 
     def _validate(self) -> None:
+        """Validate content string.
+
+        Checks that content is a non-empty string within length bounds.
+
+        Raises:
+            ValueError: If content fails validation criteria.
+        """
         if not isinstance(self.value, str):
             raise ValueError("Content must be a string")
         if not self.value.strip():

app/domain/value_objects/slug.py

@@ -1,4 +1,9 @@
-"""Slug value object for URL-friendly identifiers."""
+"""Slug value object for URL-friendly identifiers.
+
+This module defines the Slug value object for generating and validating
+URL-friendly slugs from titles. Enforces lowercase, alphanumeric, and
+hyphen-only format.
+"""
 
 import re
 from dataclasses import dataclass
@@ -8,12 +13,36 @@ from app.domain.value_objects.base import ValueObject
 
 @dataclass(frozen=True, slots=True)
 class Slug(ValueObject[str]):
-    """URL slug value object."""
+    """URL slug value object.
+
+    Represents a URL-friendly identifier generated from titles.
+    Validates format and provides factory method for slug generation.
+
+    Attributes:
+        value: The slug string value.
+        MAX_LENGTH: Maximum allowed slug length (200 characters).
+        SLUG_PATTERN: Regex pattern for valid slug format.
+
+    Raises:
+        ValueError: If slug format is invalid.
+
+    Example:
+        >>> slug = Slug.from_title("My First Post!")
+        >>> print(slug.value)
+        'my-first-post'
+    """
 
     MAX_LENGTH: int = 200
     SLUG_PATTERN: str = r"^[a-z0-9]+(?:-[a-z0-9]+)*$"
 
     def _validate(self) -> None:
+        """Validate slug format.
+
+        Ensures slug contains only lowercase letters, numbers, and hyphens.
+
+        Raises:
+            ValueError: If slug format is invalid.
+        """
         if not isinstance(self.value, str):
             raise ValueError("Slug must be a string")
         if len(self.value) > self.MAX_LENGTH:
@@ -23,17 +52,22 @@ class Slug(ValueObject[str]):
 
     @classmethod
     def from_title(cls, title: str) -> "Slug":
-        """Generate slug from title."""
-        # Convert to lowercase, replace spaces with hyphens
+        """Generate slug from title.
+
+        Converts title to URL-friendly format by lowercasing, removing
+        special characters, and replacing spaces with hyphens.
+
+        Args:
+            title: Source title string.
+
+        Returns:
+            New Slug instance with generated value.
+        """
         slug = title.lower().strip()
-        # Keep only alphanumeric, spaces, and hyphens
         slug = re.sub(r"[^a-z0-9\s-]", "", slug)
-        # Replace spaces and multiple hyphens with single hyphen
         slug = re.sub(r"[-\s]+", "-", slug)
-        # Limit length and strip hyphens
-        max_len = 200  # Same as MAX_LENGTH
+        max_len = 200
         slug = slug[:max_len].strip("-")
-        # Ensure we have at least one character
         if not slug:
             slug = "post"
         return cls(value=slug)

app/domain/value_objects/title.py

@@ -1,4 +1,8 @@
-"""Title value object."""
+"""Title value object.
+
+This module defines the Title value object for blog post titles
+with validation for minimum and maximum length constraints.
+"""
 
 from dataclasses import dataclass
 
@@ -7,12 +11,35 @@ from app.domain.value_objects.base import ValueObject
 
 @dataclass(frozen=True, slots=True)
 class Title(ValueObject[str]):
-    """Blog post title value object."""
+    """Blog post title value object.
+
+    Wraps and validates blog post titles ensuring they meet length
+    requirements and are not empty.
+
+    Attributes:
+        value: The title string value.
+        MIN_LENGTH: Minimum allowed title length (3 characters).
+        MAX_LENGTH: Maximum allowed title length (200 characters).
+
+    Raises:
+        ValueError: If title is empty, too short, or too long.
+
+    Example:
+        >>> title = Title("My Blog Post")
+        >>> print(title.value)
+    """
 
     MIN_LENGTH: int = 3
     MAX_LENGTH: int = 200
 
     def _validate(self) -> None:
+        """Validate title string.
+
+        Checks that title is a non-empty string within length bounds.
+
+        Raises:
+            ValueError: If title fails validation criteria.
+        """
         if not isinstance(self.value, str):
             raise ValueError("Title must be a string")
         if len(self.value) < self.MIN_LENGTH: