updated docs strings and added README.md

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