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/config.py

@@ -1,3 +1,14 @@
+"""
+Global configuration models for Mail Intake.
+
+This module defines the **top-level configuration object** used to control
+mail ingestion behavior across adapters, authentication providers, and
+ingestion workflows.
+
+Configuration is intentionally explicit, immutable, and free of implicit
+environment reads to ensure predictability and testability.
+"""
+
 from dataclasses import dataclass
 from typing import Optional
 
@@ -9,12 +20,26 @@ class MailIntakeConfig:
 
     This configuration is intentionally explicit and immutable.
     No implicit environment reads or global state.
+
+    Design principles:
+    - Immutable once constructed
+    - Explicit configuration over implicit defaults
+    - No direct environment or filesystem access
+
+    This model is safe to pass across layers and suitable for serialization.
     """
 
     provider: str = "gmail"
-    user_id: str = "me"
-    readonly: bool = True
+    """Identifier of the mail provider to use (e.g., ``"gmail"``)."""
+
+    user_id: str = "me"
+    """Provider-specific user identifier. Defaults to the authenticated user."""
+
+    readonly: bool = True
+    """Whether ingestion should operate in read-only mode."""
 
-    # Provider-specific paths (optional at this layer)
     credentials_path: Optional[str] = None
+    """Optional path to provider credentials configuration."""
+
     token_path: Optional[str] = None
+    """Optional path to persisted authentication tokens."""