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

@@ -1,3 +1,17 @@
+"""
+Gmail adapter implementation for Mail Intake.
+
+This module provides a **Gmail-specific implementation** of the
+`MailIntakeAdapter` contract.
+
+It is the only place in the codebase where:
+- `googleapiclient` is imported
+- Gmail REST API semantics are known
+- Low-level `.execute()` calls are made
+
+All Gmail-specific behavior must be strictly contained within this module.
+"""
+
 from typing import Iterator, Dict, Any
 
 from googleapiclient.discovery import build
@@ -12,12 +26,19 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
     """
     Gmail read-only adapter.
 
+    This adapter implements the `MailIntakeAdapter` interface using the
+    Gmail REST API. It translates the generic mail intake contract into
+    Gmail-specific API calls.
+
     This class is the ONLY place where:
     - googleapiclient is imported
     - Gmail REST semantics are known
     - .execute() is called
 
-    It must remain thin and dumb by design.
+    Design constraints:
+    - Must remain thin and imperative
+    - Must not perform parsing or interpretation
+    - Must not expose Gmail-specific types beyond this class
     """
 
     def __init__(
@@ -25,12 +46,29 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         auth_provider: MailIntakeAuthProvider,
         user_id: str = "me",
     ):
+        """
+        Initialize the Gmail adapter.
+
+        Args:
+            auth_provider: Authentication provider capable of supplying
+                valid Gmail API credentials.
+            user_id: Gmail user identifier. Defaults to `"me"`.
+        """
         self._auth_provider = auth_provider
         self._user_id = user_id
         self._service = None
 
     @property
     def service(self):
+        """
+        Lazily initialize and return the Gmail API service client.
+
+        Returns:
+            Initialized Gmail API service instance.
+
+        Raises:
+            MailIntakeAdapterError: If the Gmail service cannot be initialized.
+        """
         if self._service is None:
             try:
                 creds = self._auth_provider.get_credentials()
@@ -45,11 +83,16 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         """
         Iterate over message references matching the query.
 
+        Args:
+            query: Gmail search query string.
+
         Yields:
-        {
-            "message_id": "...",
-            "thread_id": "..."
-        }
+            Dictionaries containing:
+            - ``message_id``: Gmail message ID
+            - ``thread_id``: Gmail thread ID
+
+        Raises:
+            MailIntakeAdapterError: If the Gmail API returns an error.
         """
         try:
             request = (
@@ -79,6 +122,18 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
             ) from exc
 
     def fetch_message(self, message_id: str) -> Dict[str, Any]:
+        """
+        Fetch a full Gmail message by message ID.
+
+        Args:
+            message_id: Gmail message identifier.
+
+        Returns:
+            Provider-native Gmail message payload.
+
+        Raises:
+            MailIntakeAdapterError: If the Gmail API returns an error.
+        """
         try:
             return (
                 self.service.users()
@@ -92,6 +147,18 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
             ) from exc
 
     def fetch_thread(self, thread_id: str) -> Dict[str, Any]:
+        """
+        Fetch a full Gmail thread by thread ID.
+
+        Args:
+            thread_id: Gmail thread identifier.
+
+        Returns:
+            Provider-native Gmail thread payload.
+
+        Raises:
+            MailIntakeAdapterError: If the Gmail API returns an error.
+        """
         try:
             return (
                 self.service.users()