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