docs(mail_intake): add comprehensive docstrings across ingestion, adapters, auth, and parsing layers

- docs(mail_intake/__init__.py): document module-based public API and usage patterns
- docs(mail_intake/ingestion/reader.py): document high-level ingestion orchestration
- docs(mail_intake/adapters/base.py): document adapter contract for mail providers
- docs(mail_intake/adapters/gmail.py): document Gmail adapter implementation and constraints
- docs(mail_intake/auth/base.py): document authentication provider contract
- docs(mail_intake/auth/google.py): document Google OAuth authentication provider
- docs(mail_intake/models/message.py): document canonical email message model
- docs(mail_intake/models/thread.py): document canonical email thread model
- docs(mail_intake/parsers/body.py): document message body extraction logic
- docs(mail_intake/parsers/headers.py): document message header normalization utilities
- docs(mail_intake/parsers/subject.py): document subject normalization utilities
- docs(mail_intake/config.py): document global configuration model
- docs(mail_intake/exceptions.py): document library exception hierarchy

mail_intake/auth/__init__.py

@@ -0,0 +1,26 @@
+"""
+Authentication provider implementations for Mail Intake.
+
+This package defines the **authentication layer** used by mail adapters
+to obtain provider-specific credentials.
+
+It exposes:
+- A stable, provider-agnostic authentication contract
+- Concrete authentication providers for supported platforms
+
+Authentication providers:
+- Are responsible for credential acquisition and lifecycle management
+- Are intentionally decoupled from adapter logic
+- May be extended by users to support additional providers
+
+Consumers should depend on the abstract interface and use concrete
+implementations only where explicitly required.
+"""
+
+from .base import MailIntakeAuthProvider
+from .google import MailIntakeGoogleAuth
+
+__all__ = [
+    "MailIntakeAuthProvider",
+    "MailIntakeGoogleAuth",
+]

mail_intake/auth/base.py

@@ -1,3 +1,14 @@
+"""
+Authentication provider contracts for Mail Intake.
+
+This module defines the **authentication abstraction layer** used by mail
+adapters to obtain provider-specific credentials.
+
+Authentication concerns are intentionally decoupled from adapter logic.
+Adapters depend only on this interface and must not be aware of how
+credentials are acquired, refreshed, or stored.
+"""
+
 from abc import ABC, abstractmethod
 
 
@@ -7,6 +18,17 @@ class MailIntakeAuthProvider(ABC):
 
     Mail adapters depend on this interface, not on concrete
     OAuth or credential implementations.
+
+    Authentication providers encapsulate all logic required to acquire
+    valid credentials for a mail provider.
+
+    Implementations may involve:
+    - OAuth flows
+    - Service account credentials
+    - Token refresh logic
+    - Secure credential storage
+
+    Adapters must treat the returned credentials as opaque and provider-specific.
     """
 
     @abstractmethod
@@ -16,5 +38,13 @@ class MailIntakeAuthProvider(ABC):
 
         This method is synchronous by design and must either
         return valid credentials or raise MailIntakeAuthError.
+
+        Returns:
+            Provider-specific credentials object suitable for use by
+            the corresponding mail adapter.
+
+        Raises:
+            Exception: Authentication-specific errors defined by the
+                implementation.
         """
         raise NotImplementedError

mail_intake/auth/google.py

@@ -1,3 +1,17 @@
+"""
+Google authentication provider implementation for Mail Intake.
+
+This module provides a **Google OAuth–based authentication provider**
+used primarily for Gmail access.
+
+It encapsulates all Google-specific authentication concerns, including:
+- Credential loading and persistence
+- Token refresh handling
+- Interactive OAuth flow initiation
+
+No Google authentication details should leak outside this module.
+"""
+
 import os
 import pickle
 from typing import Sequence
@@ -14,12 +28,16 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
     """
     Google OAuth provider for Gmail access.
 
-    Responsibilities:
-    - Load cached credentials from disk
-    - Refresh expired tokens when possible
-    - Trigger interactive login only when strictly required
+    This provider implements the `MailIntakeAuthProvider` interface using
+    Google's OAuth 2.0 flow and credential management libraries.
 
-    This class is synchronous and intentionally state-light.
+    Responsibilities:
+    - Load cached credentials from disk when available
+    - Refresh expired credentials when possible
+    - Initiate an interactive OAuth flow only when required
+    - Persist refreshed or newly obtained credentials
+
+    This class is synchronous by design and maintains a minimal internal state.
     """
 
     def __init__(
@@ -28,11 +46,36 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
         token_path: str,
         scopes: Sequence[str],
     ):
+        """
+        Initialize the Google authentication provider.
+
+        Args:
+            credentials_path: Path to the Google OAuth client secrets file.
+            token_path: Path where OAuth tokens will be cached.
+            scopes: OAuth scopes required for access.
+        """
         self.credentials_path = credentials_path
         self.token_path = token_path
         self.scopes = list(scopes)
 
     def get_credentials(self):
+        """
+        Retrieve valid Google OAuth credentials.
+
+        This method attempts to:
+        1. Load cached credentials from disk
+        2. Refresh expired credentials when possible
+        3. Perform an interactive OAuth login as a fallback
+        4. Persist valid credentials for future use
+
+        Returns:
+            Google OAuth credentials object suitable for use with
+            Google API clients.
+
+        Raises:
+            MailIntakeAuthError: If credentials cannot be loaded, refreshed,
+                or obtained via interactive authentication.
+        """
         creds = None
 
         # Attempt to load cached credentials