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/adapters/base.py

@@ -1,3 +1,14 @@
+"""
+Mail provider adapter contracts for Mail Intake.
+
+This module defines the **provider-agnostic adapter interface** used for
+read-only mail ingestion.
+
+Adapters encapsulate all provider-specific access logic and expose a
+minimal, normalized contract to the rest of the system. No provider-specific
+types or semantics should leak beyond implementations of this interface.
+"""
+
 from abc import ABC, abstractmethod
 from typing import Iterator, Dict, Any
 
@@ -6,43 +17,60 @@ class MailIntakeAdapter(ABC):
     """
     Base adapter interface for mail providers.
 
-    This interface defines the minimal contract required for
-    read-only mail ingestion. No provider-specific concepts
-    should leak beyond implementations of this class.
+    This interface defines the minimal contract required to:
+    - Discover messages matching a query
+    - Retrieve full message payloads
+    - Retrieve full thread payloads
+
+    Adapters are intentionally read-only and must not mutate provider state.
     """
 
     @abstractmethod
     def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]:
         """
-        Iterate over lightweight message references.
+        Iterate over lightweight message references matching a query.
 
-        Must yield dictionaries containing at least:
-        - message_id
-        - thread_id
+        Implementations must yield dictionaries containing at least:
+        - ``message_id``: Provider-specific message identifier
+        - ``thread_id``: Provider-specific thread identifier
+
+        Args:
+            query: Provider-specific query string used to filter messages.
+
+        Yields:
+            Dictionaries containing message and thread identifiers.
 
         Example yield:
-        {
-            "message_id": "...",
-            "thread_id": "..."
-        }
+            {
+                "message_id": "...",
+                "thread_id": "..."
+            }
         """
         raise NotImplementedError
 
     @abstractmethod
     def fetch_message(self, message_id: str) -> Dict[str, Any]:
         """
-        Fetch a full raw message by message_id.
+        Fetch a full raw message by message identifier.
 
-        Returns the provider-native message payload
-        (e.g., Gmail message JSON).
+        Args:
+            message_id: Provider-specific message identifier.
+
+        Returns:
+            Provider-native message payload
+            (e.g., Gmail message JSON structure).
         """
         raise NotImplementedError
 
     @abstractmethod
     def fetch_thread(self, thread_id: str) -> Dict[str, Any]:
         """
-        Fetch a full raw thread by thread_id.
+        Fetch a full raw thread by thread identifier.
 
-        Returns the provider-native thread payload.
+        Args:
+            thread_id: Provider-specific thread identifier.
+
+        Returns:
+            Provider-native thread payload.
         """
         raise NotImplementedError