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/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