updated docs strings and added README.md

mail_intake/credentials/store.py

@@ -1,14 +1,12 @@
 """
+# Summary
+
 Credential persistence abstractions for Mail Intake.
 
----
-
-## Summary
-
 This module defines the generic persistence contract used to store and
 retrieve authentication credentials across Mail Intake components.
 
-The ``CredentialStore`` abstraction establishes a strict separation
+The `CredentialStore` abstraction establishes a strict separation
 between credential *lifecycle management* and credential *storage*.
 Authentication providers are responsible for acquiring, validating,
 refreshing, and revoking credentials, while concrete store
@@ -30,21 +28,23 @@ T = TypeVar("T")
 
 class CredentialStore(ABC, Generic[T]):
     """
-    Abstract base class defining a generic persistence interface for
-    authentication credentials.
+    Abstract base class defining a generic persistence interface.
+
+    Used for authentication credentials across different backends.
 
     Notes:
         **Responsibilities:**
 
-            - Provide persistent storage separating life-cycle management from storage mechanics
-            - Keep implementation focused only on persistence
-            
+            - Provide persistent storage separating life-cycle management from
+              storage mechanics.
+            - Keep implementation focused only on persistence.
+
         **Constraints:**
-        
+
             - The store is intentionally agnostic to:
-                - The concrete credential type being stored
-                - The serialization format used to persist credentials
-                - The underlying storage backend or durability guarantees
+                - The concrete credential type being stored.
+                - The serialization format used to persist credentials.
+                - The underlying storage backend or durability guarantees.
     """
 
     @abstractmethod
@@ -54,14 +54,17 @@ class CredentialStore(ABC, Generic[T]):
 
         Returns:
             Optional[T]:
-                An instance of type ``T`` if credentials are available and
-                loadable; otherwise ``None``.
+                An instance of type `T` if credentials are available and
+                loadable; otherwise `None`.
 
         Notes:
             **Guarantees:**
 
-                - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized
-                - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials
+                - Implementations should return `None` when no credentials are
+                  present or when stored credentials cannot be successfully
+                  decoded or deserialized.
+                - The store must not attempt to validate, refresh, or otherwise
+                  interpret the returned credentials.
         """
 
     @abstractmethod