updated docs strings and added README.md

mail_intake/auth/base.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Authentication provider contracts for Mail Intake.
 
----
-
-## Summary
-
 This module defines the **authentication abstraction layer** used by mail
 adapters to obtain provider-specific credentials.
 
@@ -30,15 +28,17 @@ class MailIntakeAuthProvider(ABC, Generic[T]):
     Notes:
         **Responsibilities:**
 
-            - Acquire credentials from an external provider
-            - Refresh or revalidate credentials as needed
-            - Handle authentication-specific failure modes
-            - Coordinate with credential persistence layers where applicable
+            - Acquire credentials from an external provider.
+            - Refresh or revalidate credentials as needed.
+            - Handle authentication-specific failure modes.
+            - Coordinate with credential persistence layers where applicable.
 
         **Constraints:**
-        
-            - Mail adapters must treat returned credentials as opaque and provider-specific
-            - Mail adapters rely only on the declared credential type expected by the adapter
+
+            - Mail adapters must treat returned credentials as opaque and
+              provider-specific.
+            - Mail adapters rely only on the declared credential type expected
+              by the adapter.
     """
 
     @abstractmethod
@@ -48,7 +48,7 @@ class MailIntakeAuthProvider(ABC, Generic[T]):
 
         Returns:
             T:
-                Credentials of type ``T`` suitable for immediate use by the
+                Credentials of type `T` suitable for immediate use by the
                 corresponding mail adapter.
 
         Raises:
@@ -59,8 +59,10 @@ class MailIntakeAuthProvider(ABC, Generic[T]):
         Notes:
             **Guarantees:**
 
-                - This method is synchronous by design
-                - Represents the sole entry point through which adapters obtain authentication material
-                - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception
+                - This method is synchronous by design.
+                - Represents the sole entry point through which adapters obtain
+                  authentication material.
+                - Implementations must either return credentials of the declared
+                  type `T` that are valid at the time of return or raise an exception.
         """
         raise NotImplementedError