updated docs strings and added README.md

mail_intake/adapters/__init__.py

@@ -1,19 +1,18 @@
 """
+# Summary
+
 Mail provider adapter implementations for Mail Intake.
 
----
-
-## Summary
-
 This package contains **adapter-layer implementations** responsible for
 interfacing with external mail providers and exposing a normalized,
 provider-agnostic contract to the rest of the system.
 
 Adapters in this package:
-- Implement the `MailIntakeAdapter` interface
-- Encapsulate all provider-specific APIs and semantics
-- Perform read-only access to mail data
-- Return provider-native payloads without interpretation
+
+- Implement the `MailIntakeAdapter` interface.
+- Encapsulate all provider-specific APIs and semantics.
+- Perform read-only access to mail data.
+- Return provider-native payloads without interpretation.
 
 Provider-specific logic **must not leak** outside of adapter implementations.
 All parsings, normalizations, and transformations must be handled by downstream
@@ -21,10 +20,10 @@ components.
 
 ---
 
-## Public API
+# Public API
 
-    MailIntakeAdapter
-    MailIntakeGmailAdapter
+- `MailIntakeAdapter`
+- `MailIntakeGmailAdapter`
 
 ---
 """

mail_intake/adapters/base.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Mail provider adapter contracts for Mail Intake.
 
----
-
-## Summary
-
 This module defines the **provider-agnostic adapter interface** used for
 read-only mail ingestion.
 
@@ -24,13 +22,13 @@ class MailIntakeAdapter(ABC):
     Notes:
         **Guarantees:**
 
-            - discover messages matching a query
-            - retrieve full message payloads
-            - retrieve full thread payloads
+            - Discover messages matching a query.
+            - Retrieve full message payloads.
+            - Retrieve full thread payloads.
 
         **Lifecycle:**
 
-            - adapters are intentionally read-only and must not mutate provider state
+            - Adapters are intentionally read-only and must not mutate provider state.
     """
 
     @abstractmethod
@@ -49,15 +47,18 @@ class MailIntakeAdapter(ABC):
         Notes:
             **Guarantees:**
 
-                - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``
+                - Implementations must yield dictionaries containing at least
+                  `message_id` and `thread_id`.
 
         Example:
             Typical yield:
 
-                {
-                    "message_id": "...",
-                    "thread_id": "..."
-                }
+            ```python
+            {
+                "message_id": "...",
+                "thread_id": "..."
+            }
+            ```
         """
         raise NotImplementedError
 

mail_intake/adapters/gmail.py

@@ -1,17 +1,16 @@
 """
+# Summary
+
 Gmail adapter implementation for Mail Intake.
 
----
-
-## Summary
-
 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
+
+- `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.
 """
@@ -37,15 +36,15 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
     Notes:
         **Responsibilities:**
 
-            - This class is the ONLY place where googleapiclient is imported
-            - Gmail REST semantics are known
-            - .execute() is called
+            - This class is the ONLY place where `googleapiclient` is imported.
+            - Gmail REST semantics are known.
+            - `.execute()` is called.
 
         **Constraints:**
-        
-            - Must remain thin and imperative
-            - Must not perform parsing or interpretation
-            - Must not expose Gmail-specific types beyond this class
+
+            - Must remain thin and imperative.
+            - Must not perform parsing or interpretation.
+            - Must not expose Gmail-specific types beyond this class.
     """
 
     def __init__(