updated docs strings and added README.md

README.md

@@ -0,0 +1,138 @@
+# mail_intake
+
+# Summary
+
+Mail Intake — provider-agnostic, read-only email ingestion framework.
+
+Mail Intake is a **contract-first library** designed to ingest, parse, and
+normalize email data from external providers (such as Gmail) into clean,
+provider-agnostic domain models.
+
+The library is intentionally structured around clear layers, each exposed
+as a first-class module at the package root:
+
+- `adapters`: Provider-specific access (e.g., Gmail).
+- `auth`: Authentication providers and credential lifecycle management.
+- `credentials`: Credential persistence abstractions and implementations.
+- `parsers`: Extraction and normalization of message content.
+- `ingestion`: Orchestration and high-level ingestion workflows.
+- `models`: Canonical, provider-agnostic data representations.
+- `config`: Explicit global configuration.
+- `exceptions`: Library-defined error hierarchy.
+
+The package root acts as a **namespace**, not a facade. Consumers are
+expected to import functionality explicitly from the appropriate module.
+
+---
+
+# Installation
+
+Install using pip:
+
+```bash
+pip install mail-intake
+```
+
+Or with Poetry:
+
+```bash
+poetry add mail-intake
+```
+
+Mail Intake is pure Python and has no runtime dependencies beyond those
+required by the selected provider (for example, Google APIs for Gmail).
+
+---
+
+# Quick Start
+
+Minimal Gmail ingestion example (local development):
+
+```python
+from mail_intake.ingestion import MailIntakeReader
+from mail_intake.adapters import MailIntakeGmailAdapter
+from mail_intake.auth import MailIntakeGoogleAuth
+from mail_intake.credentials import PickleCredentialStore
+
+store = PickleCredentialStore(path="token.pickle")
+
+auth = MailIntakeGoogleAuth(
+    credentials_path="credentials.json",
+    store=store,
+    scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+)
+
+adapter = MailIntakeGmailAdapter(auth_provider=auth)
+reader = MailIntakeReader(adapter)
+
+for message in reader.iter_messages("from:recruiter@example.com"):
+    print(message.subject, message.from_email)
+```
+
+Iterating over threads:
+
+```python
+for thread in reader.iter_threads("subject:Interview"):
+    print(thread.normalized_subject, len(thread.messages))
+```
+
+---
+
+# Architecture
+
+Mail Intake is designed to be extensible via **public contracts** exposed
+through its modules:
+
+- Users MAY implement their own mail adapters by subclassing
+  `adapters.MailIntakeAdapter`.
+- Users MAY implement their own authentication providers by subclassing
+  `auth.MailIntakeAuthProvider[T]`.
+- Users MAY implement their own credential persistence layers by implementing
+  `credentials.CredentialStore[T]`.
+
+Users SHOULD NOT subclass built-in adapter implementations. Built-in
+adapters (such as Gmail) are reference implementations and may change
+internally without notice.
+
+**Design Guarantees:**
+
+- Read-only access: no mutation of provider state.
+- Provider-agnostic domain models.
+- Explicit configuration and dependency injection.
+- No implicit global state or environment reads.
+- Deterministic, testable behavior.
+- Distributed-safe authentication design.
+
+Mail Intake favors correctness, clarity, and explicitness over convenience
+shortcuts.
+
+**Core Philosophy:**
+
+`Mail Intake` is built as a **contract-first ingestion pipeline**:
+
+1. **Layered Decoupling**: Adapters handle transport, Parsers handle format
+   normalization, and Ingestion orchestrates.
+2. **Provider Agnosticism**: Domain models and core logic never depend on
+   provider-specific (e.g., Gmail) API internals.
+3. **Stateless Workflows**: The library functions as a read-only pipe, ensuring
+   side-effect-free ingestion.
+
+---
+
+# Public API
+
+The supported public API consists of the following top-level modules:
+
+- `mail_intake.ingestion`
+- `mail_intake.adapters`
+- `mail_intake.auth`
+- `mail_intake.credentials`
+- `mail_intake.parsers`
+- `mail_intake.models`
+- `mail_intake.config`
+- `mail_intake.exceptions`
+
+Classes and functions should be imported explicitly from these modules.
+No individual symbols are re-exported at the package root.
+
+---

docs/index.md

@@ -1,4 +1,3 @@
 # mail_intake
 
 ::: mail_intake
-- [Mail Intake](mail_intake/)

mail_intake/__init__.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Mail Intake — provider-agnostic, read-only email ingestion framework.
 
----
-
-## Summary
-
 Mail Intake is a **contract-first library** designed to ingest, parse, and
 normalize email data from external providers (such as Gmail) into clean,
 provider-agnostic domain models.
@@ -12,39 +10,44 @@ provider-agnostic domain models.
 The library is intentionally structured around clear layers, each exposed
 as a first-class module at the package root:
 
-- adapters: provider-specific access (e.g. Gmail)
+- `adapters`: Provider-specific access (e.g., Gmail).
-- auth: authentication providers and credential lifecycle management
+- `auth`: Authentication providers and credential lifecycle management.
-- credentials: credential persistence abstractions and implementations
+- `credentials`: Credential persistence abstractions and implementations.
-- parsers: extraction and normalization of message content
+- `parsers`: Extraction and normalization of message content.
-- ingestion: orchestration and high-level ingestion workflows
+- `ingestion`: Orchestration and high-level ingestion workflows.
-- models: canonical, provider-agnostic data representations
+- `models`: Canonical, provider-agnostic data representations.
-- config: explicit global configuration
+- `config`: Explicit global configuration.
-- exceptions: library-defined error hierarchy
+- `exceptions`: Library-defined error hierarchy.
 
 The package root acts as a **namespace**, not a facade. Consumers are
 expected to import functionality explicitly from the appropriate module.
 
 ---
 
-## Installation
+# Installation
 
 Install using pip:
 
+```bash
 pip install mail-intake
+```
 
 Or with Poetry:
 
+```bash
 poetry add mail-intake
+```
 
 Mail Intake is pure Python and has no runtime dependencies beyond those
 required by the selected provider (for example, Google APIs for Gmail).
 
 ---
 
-## Quick start
+# Quick Start
 
 Minimal Gmail ingestion example (local development):
 
+```python
 from mail_intake.ingestion import MailIntakeReader
 from mail_intake.adapters import MailIntakeGmailAdapter
 from mail_intake.auth import MailIntakeGoogleAuth
@@ -63,58 +66,70 @@ Minimal Gmail ingestion example (local development):
 
 for message in reader.iter_messages("from:recruiter@example.com"):
     print(message.subject, message.from_email)
+```
 
 Iterating over threads:
 
+```python
 for thread in reader.iter_threads("subject:Interview"):
     print(thread.normalized_subject, len(thread.messages))
+```
 
 ---
 
-## Architecture
+# Architecture
 
 Mail Intake is designed to be extensible via **public contracts** exposed
 through its modules:
 
-- Users MAY implement their own mail adapters by subclassing ``adapters.MailIntakeAdapter``
+- Users MAY implement their own mail adapters by subclassing
-- Users MAY implement their own authentication providers by subclassing ``auth.MailIntakeAuthProvider[T]``
+  `adapters.MailIntakeAdapter`.
-- Users MAY implement their own credential persistence layers by implementing ``credentials.CredentialStore[T]``
+- Users MAY implement their own authentication providers by subclassing
+  `auth.MailIntakeAuthProvider[T]`.
+- Users MAY implement their own credential persistence layers by implementing
+  `credentials.CredentialStore[T]`.
 
 Users SHOULD NOT subclass built-in adapter implementations. Built-in
 adapters (such as Gmail) are reference implementations and may change
 internally without notice.
 
 **Design Guarantees:**
-- Read-only access: no mutation of provider state
+
-- Provider-agnostic domain models
+- Read-only access: no mutation of provider state.
-- Explicit configuration and dependency injection
+- Provider-agnostic domain models.
-- No implicit global state or environment reads
+- Explicit configuration and dependency injection.
-- Deterministic, testable behavior
+- No implicit global state or environment reads.
-- Distributed-safe authentication design
+- Deterministic, testable behavior.
+- Distributed-safe authentication design.
 
 Mail Intake favors correctness, clarity, and explicitness over convenience
 shortcuts.
 
 **Core Philosophy:**
+
 `Mail Intake` is built as a **contract-first ingestion pipeline**:
-1. **Layered Decoupling**: Adapters handle transport, Parsers handle format normalization, and Ingestion orchestrates.
+
-2. **Provider Agnosticism**: Domain models and core logic never depend on provider-specific (e.g., Gmail) API internals.
+1. **Layered Decoupling**: Adapters handle transport, Parsers handle format
-3. **Stateless Workflows**: The library functions as a read-only pipe, ensuring side-effect-free ingestion.
+   normalization, and Ingestion orchestrates.
+2. **Provider Agnosticism**: Domain models and core logic never depend on
+   provider-specific (e.g., Gmail) API internals.
+3. **Stateless Workflows**: The library functions as a read-only pipe, ensuring
+   side-effect-free ingestion.
 
 ---
 
-## Public API
+# Public API
 
 The supported public API consists of the following top-level modules:
 
-- mail_intake.ingestion
+- `mail_intake.ingestion`
-- mail_intake.adapters
+- `mail_intake.adapters`
-- mail_intake.auth
+- `mail_intake.auth`
-- mail_intake.credentials
+- `mail_intake.credentials`
-- mail_intake.parsers
+- `mail_intake.parsers`
-- mail_intake.models
+- `mail_intake.models`
-- mail_intake.config
+- `mail_intake.config`
-- mail_intake.exceptions
+- `mail_intake.exceptions`
 
 Classes and functions should be imported explicitly from these modules.
 No individual symbols are re-exported at the package root.

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
+- Implement the `MailIntakeAdapter` interface.
-- Perform read-only access to mail data
+- Encapsulate all provider-specific APIs and semantics.
-- Return provider-native payloads without interpretation
+- 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
+- `MailIntakeAdapter`
-    MailIntakeGmailAdapter
+- `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
+            - Discover messages matching a query.
-            - retrieve full message payloads
+            - Retrieve full message payloads.
-            - retrieve full thread 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:
 
+            ```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
+- `googleapiclient` is imported.
-- Low-level `.execute()` calls are made
+- 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
+            - This class is the ONLY place where `googleapiclient` is imported.
-            - Gmail REST semantics are known
+            - Gmail REST semantics are known.
-            - .execute() is called
+            - `.execute()` is called.
 
         **Constraints:**
 
-            - Must remain thin and imperative
+            - Must remain thin and imperative.
-            - Must not perform parsing or interpretation
+            - Must not perform parsing or interpretation.
-            - Must not expose Gmail-specific types beyond this class
+            - Must not expose Gmail-specific types beyond this class.
     """
 
     def __init__(

mail_intake/auth/__init__.py

@@ -1,31 +1,31 @@
 """
+# Summary
+
 Authentication provider implementations for Mail Intake.
 
----
-
-## Summary
-
 This package defines the **authentication layer** used by mail adapters
 to obtain provider-specific credentials.
 
 It exposes:
-- A stable, provider-agnostic authentication contract
+
-- Concrete authentication providers for supported platforms
+- A stable, provider-agnostic authentication contract.
+- Concrete authentication providers for supported platforms.
 
 Authentication providers:
-- Are responsible for credential acquisition and lifecycle management
+
-- Are intentionally decoupled from adapter logic
+- Are responsible for credential acquisition and lifecycle management.
-- May be extended by users to support additional providers
+- Are intentionally decoupled from adapter logic.
+- May be extended by users to support additional providers.
 
 Consumers should depend on the abstract interface and use concrete
 implementations only where explicitly required.
 
 ---
 
-## Public API
+# Public API
 
-    MailIntakeAuthProvider
+- `MailIntakeAuthProvider`
-    MailIntakeGoogleAuth
+- `MailIntakeGoogleAuth`
 
 ---
 """

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
+            - Acquire credentials from an external provider.
-            - Refresh or revalidate credentials as needed
+            - Refresh or revalidate credentials as needed.
-            - Handle authentication-specific failure modes
+            - Handle authentication-specific failure modes.
-            - Coordinate with credential persistence layers where applicable
+            - Coordinate with credential persistence layers where applicable.
 
         **Constraints:**
 
-            - Mail adapters must treat returned credentials as opaque and provider-specific
+            - Mail adapters must treat returned credentials as opaque and
-            - Mail adapters rely only on the declared credential type expected by the adapter
+              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
+                - This method is synchronous by design.
-                - Represents the sole entry point through which adapters obtain authentication material
+                - Represents the sole entry point through which adapters obtain
-                - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception
+                  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

mail_intake/auth/google.py

@@ -1,18 +1,17 @@
 """
+# Summary
+
 Google authentication provider implementation for Mail Intake.
 
----
-
-## Summary
-
 This module provides a **Google OAuth–based authentication provider**
 used primarily for Gmail access.
 
 It encapsulates all Google-specific authentication concerns, including:
-- Credential loading and persistence
+
-- Token refresh handling
+- Credential loading and persistence.
-- Interactive OAuth flow initiation
+- Token refresh handling.
-- Coordination with a credential persistence layer
+- Interactive OAuth flow initiation.
+- Coordination with a credential persistence layer.
 
 No Google authentication details should leak outside this module.
 """
@@ -40,14 +39,15 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
     Notes:
         **Responsibilities:**
 
-            - Load cached credentials from a credential store when available
+            - Load cached credentials from a credential store when available.
-            - Refresh expired credentials when possible
+            - Refresh expired credentials when possible.
-            - Initiate an interactive OAuth flow only when required
+            - Initiate an interactive OAuth flow only when required.
-            - Persist refreshed or newly obtained credentials via the store
+            - Persist refreshed or newly obtained credentials via the store.
 
         **Guarantees:**
 
-            - This class is synchronous by design and maintains a minimal internal state
+            - This class is synchronous by design and maintains a minimal
+              internal state.
     """
 
     def __init__(
@@ -79,7 +79,7 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
 
         Returns:
             Credentials:
-                A ``google.oauth2.credentials.Credentials`` instance suitable
+                A `google.oauth2.credentials.Credentials` instance suitable
                 for use with Google API clients.
 
         Raises:
@@ -90,10 +90,10 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
         Notes:
             **Lifecycle:**
 
-                - Load cached credentials from the configured credential store
+                - Load cached credentials from the configured credential store.
-                - Refresh expired credentials when possible
+                - Refresh expired credentials when possible.
-                - Perform an interactive OAuth login as a fallback
+                - Perform an interactive OAuth login as a fallback.
-                - Persist valid credentials for future use
+                - Persist valid credentials for future use.
         """
         creds = self.store.load()
 

mail_intake/config.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Global configuration models for Mail Intake.
 
----
-
-## Summary
-
 This module defines the **top-level configuration object** used to control
 mail ingestion behavior across adapters, authentication providers, and
 ingestion workflows.
@@ -20,16 +18,17 @@ from typing import Optional
 @dataclass(frozen=True)
 class MailIntakeConfig:
     """
-    Global configuration for mail-intake.
+    Global configuration for `mail-intake`.
 
     Notes:
         **Guarantees:**
 
-            - This configuration is intentionally explicit and immutable
+            - This configuration is intentionally explicit and immutable.
-            - No implicit environment reads or global state
+            - No implicit environment reads or global state.
-            - Explicit configuration over implicit defaults
+            - Explicit configuration over implicit defaults.
-            - No direct environment or filesystem access
+            - No direct environment or filesystem access.
-            - This model is safe to pass across layers and suitable for serialization
+            - This model is safe to pass across layers and suitable for
+              serialization.
     """
 
     provider: str = "gmail"

mail_intake/credentials/__init__.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Credential persistence interfaces and implementations for Mail Intake.
 
----
-
-## Summary
-
 This package defines the abstractions and concrete implementations used
 to persist authentication credentials across Mail Intake components.
 
@@ -14,20 +12,21 @@ credential acquisition, validation, and refresh, while implementations
 within this package are responsible solely for storage and retrieval.
 
 The package provides:
-- A generic ``CredentialStore`` abstraction defining the persistence contract
+
-- Local filesystem–based storage for development and single-node use
+- A generic `CredentialStore` abstraction defining the persistence contract.
-- Distributed, Redis-backed storage for production and scaled deployments
+- Local filesystem–based storage for development and single-node use.
+- Distributed, Redis-backed storage for production and scaled deployments.
 
 Credential lifecycle management, interpretation, and security policy
 decisions remain the responsibility of authentication providers.
 
 ---
 
-## Public API
+# Public API
 
-    CredentialStore
+- `CredentialStore`
-    PickleCredentialStore
+- `PickleCredentialStore`
-    RedisCredentialStore
+- `RedisCredentialStore`
 
 ---
 """

mail_intake/credentials/pickle.py

@@ -1,18 +1,16 @@
 """
+# Summary
+
 Local filesystem–based credential persistence for Mail Intake.
 
----
-
-## Summary
-
 This module provides a file-backed implementation of the
-``CredentialStore`` abstraction using Python's ``pickle`` module.
+`CredentialStore` abstraction using Python's `pickle` module.
 
-The pickle-based credential store is intended for local development,
+The `pickle`-based credential store is intended for local development,
 single-node deployments, and controlled environments where credentials
 do not need to be shared across processes or machines.
 
-Due to the security and portability risks associated with pickle-based
+Due to the security and portability risks associated with `pickle`-based
 serialization, this implementation is not suitable for distributed or
 untrusted environments.
 """
@@ -36,13 +34,14 @@ class PickleCredentialStore(CredentialStore[T]):
     Notes:
         **Guarantees:**
 
-            - Stores credentials on the local filesystem
+            - Stores credentials on the local filesystem.
-            - Uses pickle for serialization and deserialization
+            - Uses `pickle` for serialization and deserialization.
-            - Does not provide encryption, locking, or concurrency guarantees
+            - Does not provide encryption, locking, or concurrency guarantees.
 
         **Constraints:**
 
-            - Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class
+            - Credential lifecycle management, validation, and refresh logic are
+              explicitly out of scope for this class.
     """
 
     def __init__(self, path: str):
@@ -62,14 +61,16 @@ class PickleCredentialStore(CredentialStore[T]):
 
         Returns:
             Optional[T]:
-                An instance of type ``T`` if credentials are present and
+                An instance of type `T` if credentials are present and
-                successfully deserialized; otherwise ``None``.
+                successfully deserialized; otherwise `None`.
 
         Notes:
             **Guarantees:**
 
-                - If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``
+                - If the credential file does not exist or cannot be successfully
-                - The store does not attempt to validate or interpret the returned credentials
+                  deserialized, this method returns `None`.
+                - The store does not attempt to validate or interpret the
+                  returned credentials.
         """
         try:
             with open(self.path, "rb") as fh:

mail_intake/credentials/redis.py

@@ -1,12 +1,10 @@
 """
+# Summary
+
 Redis-backed credential persistence for Mail Intake.
 
----
-
-## Summary
-
 This module provides a Redis-based implementation of the
-``CredentialStore`` abstraction, enabling credential persistence
+`CredentialStore` abstraction, enabling credential persistence
 across distributed and horizontally scaled deployments.
 
 The Redis credential store is designed for environments where
@@ -15,10 +13,11 @@ processes, containers, or nodes, such as container orchestration
 platforms and microservice architectures.
 
 Key characteristics:
-- Distributed-safe, shared storage using Redis
+
-- Explicit, caller-defined serialization and deserialization
+- Distributed-safe, shared storage using Redis.
-- No reliance on unsafe mechanisms such as pickle
+- Explicit, caller-defined serialization and deserialization.
-- Optional time-to-live (TTL) support for automatic credential expiry
+- No reliance on unsafe mechanisms such as `pickle`.
+- Optional time-to-live (TTL) support for automatic credential expiry.
 
 This module is responsible solely for persistence concerns.
 Credential validation, refresh, rotation, and acquisition remain the
@@ -35,7 +34,7 @@ T = TypeVar("T")
 
 class RedisCredentialStore(CredentialStore[T]):
     """
-    Redis-backed implementation of ``CredentialStore``.
+    Redis-backed implementation of `CredentialStore`.
 
     This store persists credentials in Redis and is suitable for
     distributed and horizontally scaled deployments where credentials
@@ -44,13 +43,16 @@ class RedisCredentialStore(CredentialStore[T]):
     Notes:
         **Responsibilities:**
 
-            - This class is responsible only for persistence and retrieval
+            - This class is responsible only for persistence and retrieval.
-            - It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored
+            - It does not interpret, validate, refresh, or otherwise manage the
+              lifecycle of the credentials being stored.
 
         **Guarantees:**
 
-            - The store is intentionally generic and delegates all serialization concerns to caller-provided functions
+            - The store is intentionally generic and delegates all serialization
-            - This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited
+              concerns to caller-provided functions.
+            - This avoids unsafe mechanisms such as `pickle` and allows
+              credential formats to be explicitly controlled and audited.
     """
 
     def __init__(
@@ -92,14 +94,18 @@ class RedisCredentialStore(CredentialStore[T]):
 
         Returns:
             Optional[T]:
-                An instance of type ``T`` if credentials are present and
+                An instance of type `T` if credentials are present and
-                successfully deserialized; otherwise ``None``.
+                successfully deserialized; otherwise `None`.
 
         Notes:
             **Guarantees:**
 
-                - If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``
+                - If no value exists for the configured key, or if the stored
-                - The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable
+                  payload cannot be successfully deserialized, this method
+                  returns `None`.
+                - The store does not attempt to validate the returned
+                  credentials or determine whether they are expired or
+                  otherwise usable.
         """
         raw = self.redis.get(self.key)
         if not raw:

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
+    Abstract base class defining a generic persistence interface.
-    authentication credentials.
+
+    Used for authentication credentials across different backends.
 
     Notes:
         **Responsibilities:**
 
-            - Provide persistent storage separating life-cycle management from storage mechanics
+            - Provide persistent storage separating life-cycle management from
-            - Keep implementation focused only on persistence
+              storage mechanics.
+            - Keep implementation focused only on persistence.
 
         **Constraints:**
 
             - The store is intentionally agnostic to:
-                - The concrete credential type being stored
+                - The concrete credential type being stored.
-                - The serialization format used to persist credentials
+                - The serialization format used to persist credentials.
-                - The underlying storage backend or durability guarantees
+                - 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
+                An instance of type `T` if credentials are available and
-                loadable; otherwise ``None``.
+                loadable; otherwise `None`.
 
         Notes:
             **Guarantees:**
 
-                - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized
+                - Implementations should return `None` when no credentials are
-                - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials
+                  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

mail_intake/exceptions.py

@@ -34,7 +34,8 @@ class MailIntakeAuthError(MailIntakeError):
     Notes:
         **Lifecycle:**
 
-            - Raised when authentication providers are unable to acquire, refresh, or persist valid credentials
+            - Raised when authentication providers are unable to acquire,
+              refresh, or persist valid credentials.
     """
 
 
@@ -45,7 +46,8 @@ class MailIntakeAdapterError(MailIntakeError):
     Notes:
         **Lifecycle:**
 
-            - Raised when a provider adapter encounters API errors, transport failures, or invalid provider responses
+            - Raised when a provider adapter encounters API errors, transport
+              failures, or invalid provider responses.
     """
 
 
@@ -56,5 +58,6 @@ class MailIntakeParsingError(MailIntakeError):
     Notes:
         **Lifecycle:**
 
-            - Raised when raw provider payloads cannot be interpreted or normalized into internal domain models
+            - Raised when raw provider payloads cannot be interpreted or
+              normalized into internal domain models.
     """

mail_intake/ingestion/__init__.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Mail ingestion orchestration for Mail Intake.
 
----
-
-## Summary
-
 This package contains **high-level ingestion components** responsible for
 coordinating mail retrieval, parsing, normalization, and model construction.
 
@@ -12,19 +10,20 @@ It represents the **top of the ingestion pipeline** and is intended to be the
 primary interaction surface for library consumers.
 
 Components in this package:
-- Are provider-agnostic
+
-- Depend only on adapter and parser contracts
+- Are provider-agnostic.
-- Contain no provider-specific API logic
+- Depend only on adapter and parser contracts.
-- Expose read-only ingestion workflows
+- Contain no provider-specific API logic.
+- Expose read-only ingestion workflows.
 
 Consumers are expected to construct a mail adapter and pass it to the
 ingestion layer to begin processing messages and threads.
 
 ---
 
-## Public API
+# Public API
 
-    MailIntakeReader
+- `MailIntakeReader`
 
 ---
 """

mail_intake/ingestion/reader.py

@@ -1,18 +1,17 @@
 """
+# Summary
+
 High-level mail ingestion orchestration for Mail Intake.
 
----
-
-## Summary
-
 This module provides the primary, provider-agnostic entry point for
 reading and processing mail data.
 
 It coordinates:
-- Mail adapter access
+
-- Message and thread iteration
+- Mail adapter access.
-- Header and body parsing
+- Message and thread iteration.
-- Normalization and model construction
+- Header and body parsing.
+- Normalization and model construction.
 
 No provider-specific logic or API semantics are permitted in this layer.
 """
@@ -36,12 +35,18 @@ class MailIntakeReader:
     Notes:
         **Responsibilities:**
 
-            - This class is the primary entry point for consumers of the Mail Intake library
+            - This class is the primary entry point for consumers of the
-            - It orchestrates the full ingestion pipeline: Querying the adapter for message references, fetching raw provider messages, parsing and normalizing message data, constructing domain models
+              Mail Intake library.
+            - It orchestrates the full ingestion pipeline:
+                - Querying the adapter for message references.
+                - Fetching raw provider messages.
+                - Parsing and normalizing message data.
+                - Constructing domain models.
 
         **Constraints:**
 
-            - This class is intentionally: Provider-agnostic, stateless beyond iteration scope, read-only
+            - This class is intentionally: Provider-agnostic, stateless beyond
+              iteration scope, read-only.
     """
 
     def __init__(self, adapter: MailIntakeAdapter):
@@ -87,13 +92,14 @@ class MailIntakeReader:
                 An iterator of `MailIntakeThread` instances.
 
         Raises:
-            MailIntakeParsingError:
+            `MailIntakeParsingError`:
                 If a message cannot be parsed.
 
         Notes:
             **Guarantees:**
 
-                - Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages
+                - Messages are grouped by `thread_id` and yielded as complete
+                  thread objects containing all associated messages.
         """
         threads: Dict[str, MailIntakeThread] = {}
 

mail_intake/models/__init__.py

@@ -1,27 +1,26 @@
 """
+# Summary
+
 Domain models for Mail Intake.
 
----
-
-## Summary
-
 This package defines the **canonical, provider-agnostic data models**
 used throughout the Mail Intake ingestion pipeline.
 
 Models in this package:
-- Represent fully parsed and normalized mail data
+
-- Are safe to persist, serialize, and index
+- Represent fully parsed and normalized mail data.
-- Contain no provider-specific payloads or API semantics
+- Are safe to persist, serialize, and index.
-- Serve as stable inputs for downstream processing and analysis
+- Contain no provider-specific payloads or API semantics.
+- Serve as stable inputs for downstream processing and analysis.
 
 These models form the core internal data contract of the library.
 
 ---
 
-## Public API
+# Public API
 
-    MailIntakeMessage
+- `MailIntakeMessage`
-    MailIntakeThread
+- `MailIntakeThread`
 
 ---
 """

mail_intake/models/message.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Message domain models for Mail Intake.
 
----
-
-## Summary
-
 This module defines the **canonical, provider-agnostic representation**
 of an individual email message as used internally by the Mail Intake
 ingestion pipeline.
@@ -26,12 +24,14 @@ class MailIntakeMessage:
     Notes:
         **Guarantees:**
 
-            - This model represents a fully parsed and normalized email message
+            - This model represents a fully parsed and normalized email message.
-            - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing
+            - It is intentionally provider-agnostic and suitable for
+              persistence, indexing, and downstream processing.
 
         **Constraints:**
 
-            - No provider-specific identifiers, payloads, or API semantics should appear in this model
+            - No provider-specific identifiers, payloads, or API semantics
+              should appear in this model.
     """
 
     message_id: str

mail_intake/models/thread.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Thread domain models for Mail Intake.
 
----
-
-## Summary
-
 This module defines the **canonical, provider-agnostic representation**
 of an email thread as used internally by the Mail Intake ingestion pipeline.
 
@@ -27,9 +25,11 @@ class MailIntakeThread:
     Notes:
         **Guarantees:**
 
-            - A thread groups multiple related messages under a single subject and participant set
+            - A thread groups multiple related messages under a single subject
-            - It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions
+              and participant set.
-            - This model is provider-agnostic and safe to persist
+            - It is designed to support reasoning over conversational context
+              such as job applications, interviews, follow-ups, and ongoing discussions.
+            - This model is provider-agnostic and safe to persist.
     """
 
     thread_id: str
@@ -68,9 +68,9 @@ class MailIntakeThread:
         Notes:
             **Responsibilities:**
 
-                - Appends the message to the thread
+                - Appends the message to the thread.
-                - Tracks unique participants
+                - Tracks unique participants.
-                - Updates the last activity timestamp
+                - Updates the last activity timestamp.
         """
         self.messages.append(message)
 

mail_intake/parsers/__init__.py

@@ -1,34 +1,34 @@
 """
+# Summary
+
 Message parsing utilities for Mail Intake.
 
----
-
-## Summary
-
 This package contains **provider-aware but adapter-agnostic parsing helpers**
 used to extract and normalize structured information from raw mail payloads.
 
 Parsers in this package are responsible for:
-- Interpreting provider-native message structures
+
-- Extracting meaningful fields such as headers, body text, and subjects
+- Interpreting provider-native message structures.
-- Normalizing data into consistent internal representations
+- Extracting meaningful fields such as headers, body text, and subjects.
+- Normalizing data into consistent internal representations.
 
 This package does not:
-- Perform network or IO operations
+
-- Contain provider API logic
+- Perform network or IO operations.
-- Construct domain models directly
+- Contain provider API logic.
+- Construct domain models directly.
 
 Parsing functions are designed to be composable and are orchestrated by the
 ingestion layer.
 
 ---
 
-## Public API
+# Public API
 
-    extract_body
+- `extract_body`
-    parse_headers
+- `parse_headers`
-    extract_sender
+- `extract_sender`
-    normalize_subject
+- `normalize_subject`
 
 ---
 """

mail_intake/parsers/body.py

@@ -1,4 +1,6 @@
 """
+# Summary
+
 Message body extraction utilities for Mail Intake.
 
 This module contains helper functions for extracting a best-effort
@@ -24,13 +26,16 @@ def _decode_base64(data: str) -> str:
     omit padding and use non-standard characters.
 
     Args:
-        data: URL-safe base64-encoded string.
+        data (str):
+            URL-safe base64-encoded string.
 
     Returns:
+        str:
             Decoded UTF-8 text with replacement for invalid characters.
 
     Raises:
-        MailIntakeParsingError: If decoding fails.
+        MailIntakeParsingError:
+            If decoding fails.
     """
     try:
         padded = data.replace("-", "+").replace("_", "/")
@@ -45,14 +50,17 @@ def _extract_from_part(part: Dict[str, Any]) -> Optional[str]:
     Extract text content from a single MIME part.
 
     Supports:
-    - text/plain
+
-    - text/html (converted to plain text)
+    - `text/plain`
+    - `text/html` (converted to plain text)
 
     Args:
-        part: MIME part dictionary from a provider payload.
+        part (Dict[str, Any]):
+            MIME part dictionary from a provider payload.
 
     Returns:
-        Extracted plain-text content, or None if unsupported or empty.
+        Optional[str]:
+            Extracted plain-text content, or `None` if unsupported or empty.
     """
     mime_type = part.get("mimeType")
     body = part.get("body", {})
@@ -79,15 +87,18 @@ def extract_body(payload: Dict[str, Any]) -> str:
     Extract the best-effort message body from a Gmail payload.
 
     Priority:
-    1. text/plain
+
-    2. text/html (stripped to text)
+    1. `text/plain`
+    2. `text/html` (stripped to text)
     3. Single-part body
-    4. empty string (if nothing usable found)
+    4. Empty string (if nothing usable found)
 
     Args:
-        payload: Provider-native message payload dictionary.
+        payload (Dict[str, Any]):
+            Provider-native message payload dictionary.
 
     Returns:
+        str:
             Extracted plain-text message body.
     """
     if not payload:

mail_intake/parsers/headers.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Message header parsing utilities for Mail Intake.
 
----
-
-## Summary
-
 This module provides helper functions for normalizing and extracting
 useful information from provider-native message headers.
 
@@ -21,7 +19,7 @@ def parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]:
 
     Args:
         raw_headers (List[Dict[str, str]]):
-            List of header dictionaries, each containing ``name`` and ``value`` keys.
+            List of header dictionaries, each containing `name` and `value` keys.
 
     Returns:
         Dict[str, str]:
@@ -30,12 +28,15 @@ def parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]:
     Notes:
         **Guarantees:**
 
-            - Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings
+            - Provider payloads (such as Gmail) typically represent headers as a
-            - This function normalizes them into a case-insensitive dictionary keyed by lowercase header names
+              list of name/value mappings.
+            - This function normalizes them into a case-insensitive dictionary
+              keyed by lowercase header names.
 
     Example:
         Typical usage:
 
+        ```python
         Input:
             [
                 {"name": "From", "value": "John Doe <john@example.com>"},
@@ -47,6 +48,7 @@ def parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]:
                 "from": "John Doe <john@example.com>",
                 "subject": "Re: Interview Update",
             }
+        ```
     """
     headers: Dict[str, str] = {}
 
@@ -68,22 +70,24 @@ def extract_sender(headers: Dict[str, str]) -> Tuple[str, Optional[str]]:
 
     Args:
         headers (Dict[str, str]):
-            Normalized header dictionary as returned by :func:`parse_headers`.
+            Normalized header dictionary as returned by `parse_headers()`.
 
     Returns:
         Tuple[str, Optional[str]]:
-            A tuple ``(email, name)`` where ``email`` is the sender email address and ``name`` is the display name, or ``None`` if unavailable.
+            A tuple `(email, name)` where `email` is the sender email address
+            and `name` is the display name, or `None` if unavailable.
 
     Notes:
         **Responsibilities:**
 
-            - This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name
+            - This function parses the `From` header and attempts to extract
+              sender email address and optional human-readable display name.
 
     Example:
         Typical values:
 
-            ``"John Doe <john@example.com>"`` -> ``("john@example.com", "John Doe")``
+        - `"John Doe <john@example.com>"` -> `("john@example.com", "John Doe")`
-            ``"john@example.com"`` -> ``("john@example.com", None)``
+        - `"john@example.com"` -> `("john@example.com", None)`
     """
     from_header = headers.get("from")
     if not from_header:

mail_intake/parsers/subject.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Subject line normalization utilities for Mail Intake.
 
----
-
-## Summary
-
 This module provides helper functions for normalizing email subject lines
 to enable reliable thread-level comparison and grouping.
 
@@ -36,14 +34,15 @@ def normalize_subject(subject: str) -> str:
     Notes:
         **Responsibilities:**
 
-            - Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``
+            - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.
-            - Repeats prefix stripping to handle stacked prefixes
+            - Repeats prefix stripping to handle stacked prefixes.
-            - Collapses excessive whitespace
+            - Collapses excessive whitespace.
-            - Preserves original casing (no lowercasing)
+            - Preserves original casing (no lowercasing).
 
         **Guarantees:**
 
-            - This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject
+            - This function is intentionally conservative and avoids aggressive
+              transformations that could alter the semantic meaning of the subject.
     """
     if not subject:
         return ""

mcp_docs/modules/mail_intake.adapters.base.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.adapters.base",
   "content": {
     "path": "mail_intake.adapters.base",
-    "docstring": "Mail provider adapter contracts for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.",
+    "docstring": "# Summary\n\nMail provider adapter contracts for Mail Intake.\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.",
     "objects": {
       "ABC": {
         "name": "ABC",
@@ -43,28 +43,28 @@
         "name": "MailIntakeAdapter",
         "kind": "class",
         "path": "mail_intake.adapters.base.MailIntakeAdapter",
-        "signature": "<bound method Class.signature of Class('MailIntakeAdapter', 20, 92)>",
+        "signature": "<bound method Class.signature of Class('MailIntakeAdapter', 18, 93)>",
-        "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - discover messages matching a query\n        - retrieve full message payloads\n        - retrieve full thread payloads\n\n    **Lifecycle:**\n\n        - adapters are intentionally read-only and must not mutate provider state",
+        "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - Discover messages matching a query.\n        - Retrieve full message payloads.\n        - Retrieve full thread payloads.\n\n    **Lifecycle:**\n\n        - Adapters are intentionally read-only and must not mutate provider state.",
         "members": {
           "iter_message_refs": {
             "name": "iter_message_refs",
             "kind": "function",
             "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs",
-            "signature": "<bound method Function.signature of Function('iter_message_refs', 36, 62)>",
+            "signature": "<bound method Function.signature of Function('iter_message_refs', 34, 63)>",
-            "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``\n\nExample:\n    Typical yield:\n\n        {\n            \"message_id\": \"...\",\n            \"thread_id\": \"...\"\n        }"
+            "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
           },
           "fetch_message": {
             "name": "fetch_message",
             "kind": "function",
             "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
-            "signature": "<bound method Function.signature of Function('fetch_message', 64, 77)>",
+            "signature": "<bound method Function.signature of Function('fetch_message', 65, 78)>",
             "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id (str):\n        Provider-specific message identifier.\n\nReturns:\n    Dict[str, Any]:\n        Provider-native message payload (e.g., Gmail message JSON structure)."
           },
           "fetch_thread": {
             "name": "fetch_thread",
             "kind": "function",
             "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread",
-            "signature": "<bound method Function.signature of Function('fetch_thread', 79, 92)>",
+            "signature": "<bound method Function.signature of Function('fetch_thread', 80, 93)>",
             "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n    thread_id (str):\n        Provider-specific thread identifier.\n\nReturns:\n    Dict[str, Any]:\n        Provider-native thread payload."
           }
         }

mcp_docs/modules/mail_intake.adapters.gmail.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.adapters.gmail",
   "content": {
     "path": "mail_intake.adapters.gmail",
-    "docstring": "Gmail adapter implementation for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n- `googleapiclient` is imported\n- Gmail REST API semantics are known\n- Low-level `.execute()` calls are made\n\nAll Gmail-specific behavior must be strictly contained within this module.",
+    "docstring": "# Summary\n\nGmail adapter implementation for Mail Intake.\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n\n- `googleapiclient` is imported.\n- Gmail REST API semantics are known.\n- Low-level `.execute()` calls are made.\n\nAll Gmail-specific behavior must be strictly contained within this module.",
     "objects": {
       "Iterator": {
         "name": "Iterator",
@@ -44,14 +44,14 @@
         "kind": "class",
         "path": "mail_intake.adapters.gmail.MailIntakeAdapter",
         "signature": "<bound method Alias.signature of Alias('MailIntakeAdapter', 'mail_intake.adapters.base.MailIntakeAdapter')>",
-        "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - discover messages matching a query\n        - retrieve full message payloads\n        - retrieve full thread payloads\n\n    **Lifecycle:**\n\n        - adapters are intentionally read-only and must not mutate provider state",
+        "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - Discover messages matching a query.\n        - Retrieve full message payloads.\n        - Retrieve full thread payloads.\n\n    **Lifecycle:**\n\n        - Adapters are intentionally read-only and must not mutate provider state.",
         "members": {
           "iter_message_refs": {
             "name": "iter_message_refs",
             "kind": "function",
             "path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs",
             "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
-            "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``\n\nExample:\n    Typical yield:\n\n        {\n            \"message_id\": \"...\",\n            \"thread_id\": \"...\"\n        }"
+            "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
           },
           "fetch_message": {
             "name": "fetch_message",
@@ -74,21 +74,21 @@
         "kind": "class",
         "path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
         "signature": "<bound method Alias.signature of Alias('MailIntakeAdapterError', 'mail_intake.exceptions.MailIntakeAdapterError')>",
-        "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when a provider adapter encounters API errors, transport failures, or invalid provider responses"
+        "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when a provider adapter encounters API errors, transport\n          failures, or invalid provider responses."
       },
       "MailIntakeAuthProvider": {
         "name": "MailIntakeAuthProvider",
         "kind": "class",
         "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider",
         "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
-        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider\n        - Refresh or revalidate credentials as needed\n        - Handle authentication-specific failure modes\n        - Coordinate with credential persistence layers where applicable\n\n    **Constraints:**\n    \n        - Mail adapters must treat returned credentials as opaque and provider-specific\n        - Mail adapters rely only on the declared credential type expected by the adapter",
+        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
         "members": {
           "get_credentials": {
             "name": "get_credentials",
             "kind": "function",
             "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials",
             "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
-            "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type ``T`` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design\n        - Represents the sole entry point through which adapters obtain authentication material\n        - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception"
+            "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
           }
         }
       },
@@ -96,8 +96,8 @@
         "name": "MailIntakeGmailAdapter",
         "kind": "class",
         "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter",
-        "signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 29, 190)>",
+        "signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 28, 189)>",
-        "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the ONLY place where googleapiclient is imported\n        - Gmail REST semantics are known\n        - .execute() is called\n\n    **Constraints:**\n    \n        - Must remain thin and imperative\n        - Must not perform parsing or interpretation\n        - Must not expose Gmail-specific types beyond this class",
+        "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the ONLY place where `googleapiclient` is imported.\n        - Gmail REST semantics are known.\n        - `.execute()` is called.\n\n    **Constraints:**\n\n        - Must remain thin and imperative.\n        - Must not perform parsing or interpretation.\n        - Must not expose Gmail-specific types beyond this class.",
         "members": {
           "service": {
             "name": "service",
@@ -110,21 +110,21 @@
             "name": "iter_message_refs",
             "kind": "function",
             "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
-            "signature": "<bound method Function.signature of Function('iter_message_refs', 93, 134)>",
+            "signature": "<bound method Function.signature of Function('iter_message_refs', 92, 133)>",
             "docstring": "Iterate over message references matching the query.\n\nArgs:\n    query (str):\n        Gmail search query string.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail API returns an error."
           },
           "fetch_message": {
             "name": "fetch_message",
             "kind": "function",
             "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message",
-            "signature": "<bound method Function.signature of Function('fetch_message', 136, 162)>",
+            "signature": "<bound method Function.signature of Function('fetch_message', 135, 161)>",
             "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n    message_id (str):\n        Gmail message identifier.\n\nReturns:\n    Dict[str, Any]:\n        Provider-native Gmail message payload.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail API returns an error."
           },
           "fetch_thread": {
             "name": "fetch_thread",
             "kind": "function",
             "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread",
-            "signature": "<bound method Function.signature of Function('fetch_thread', 164, 190)>",
+            "signature": "<bound method Function.signature of Function('fetch_thread', 163, 189)>",
             "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n    thread_id (str):\n        Gmail thread identifier.\n\nReturns:\n    Dict[str, Any]:\n        Provider-native Gmail thread payload.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail API returns an error."
           }
         }

mcp_docs/modules/mail_intake.adapters.json

@@ -2,21 +2,21 @@
   "module": "mail_intake.adapters",
   "content": {
     "path": "mail_intake.adapters",
-    "docstring": "Mail provider adapter implementations for Mail Intake.\n\n---\n\n## Summary\n\nThis package contains **adapter-layer implementations** responsible for\ninterfacing with external mail providers and exposing a normalized,\nprovider-agnostic contract to the rest of the system.\n\nAdapters in this package:\n- Implement the `MailIntakeAdapter` interface\n- Encapsulate all provider-specific APIs and semantics\n- Perform read-only access to mail data\n- Return provider-native payloads without interpretation\n\nProvider-specific logic **must not leak** outside of adapter implementations.\nAll parsings, normalizations, and transformations must be handled by downstream\ncomponents.\n\n---\n\n## Public API\n\n    MailIntakeAdapter\n    MailIntakeGmailAdapter\n\n---",
+    "docstring": "# Summary\n\nMail provider adapter implementations for Mail Intake.\n\nThis package contains **adapter-layer implementations** responsible for\ninterfacing with external mail providers and exposing a normalized,\nprovider-agnostic contract to the rest of the system.\n\nAdapters in this package:\n\n- Implement the `MailIntakeAdapter` interface.\n- Encapsulate all provider-specific APIs and semantics.\n- Perform read-only access to mail data.\n- Return provider-native payloads without interpretation.\n\nProvider-specific logic **must not leak** outside of adapter implementations.\nAll parsings, normalizations, and transformations must be handled by downstream\ncomponents.\n\n---\n\n# Public API\n\n- `MailIntakeAdapter`\n- `MailIntakeGmailAdapter`\n\n---",
     "objects": {
       "MailIntakeAdapter": {
         "name": "MailIntakeAdapter",
         "kind": "class",
         "path": "mail_intake.adapters.MailIntakeAdapter",
         "signature": "<bound method Alias.signature of Alias('MailIntakeAdapter', 'mail_intake.adapters.base.MailIntakeAdapter')>",
-        "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - discover messages matching a query\n        - retrieve full message payloads\n        - retrieve full thread payloads\n\n    **Lifecycle:**\n\n        - adapters are intentionally read-only and must not mutate provider state",
+        "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - Discover messages matching a query.\n        - Retrieve full message payloads.\n        - Retrieve full thread payloads.\n\n    **Lifecycle:**\n\n        - Adapters are intentionally read-only and must not mutate provider state.",
         "members": {
           "iter_message_refs": {
             "name": "iter_message_refs",
             "kind": "function",
             "path": "mail_intake.adapters.MailIntakeAdapter.iter_message_refs",
             "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
-            "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``\n\nExample:\n    Typical yield:\n\n        {\n            \"message_id\": \"...\",\n            \"thread_id\": \"...\"\n        }"
+            "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
           },
           "fetch_message": {
             "name": "fetch_message",
@@ -39,7 +39,7 @@
         "kind": "class",
         "path": "mail_intake.adapters.MailIntakeGmailAdapter",
         "signature": "<bound method Alias.signature of Alias('MailIntakeGmailAdapter', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter')>",
-        "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the ONLY place where googleapiclient is imported\n        - Gmail REST semantics are known\n        - .execute() is called\n\n    **Constraints:**\n    \n        - Must remain thin and imperative\n        - Must not perform parsing or interpretation\n        - Must not expose Gmail-specific types beyond this class",
+        "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the ONLY place where `googleapiclient` is imported.\n        - Gmail REST semantics are known.\n        - `.execute()` is called.\n\n    **Constraints:**\n\n        - Must remain thin and imperative.\n        - Must not perform parsing or interpretation.\n        - Must not expose Gmail-specific types beyond this class.",
         "members": {
           "service": {
             "name": "service",
@@ -76,7 +76,7 @@
         "kind": "module",
         "path": "mail_intake.adapters.base",
         "signature": null,
-        "docstring": "Mail provider adapter contracts for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.",
+        "docstring": "# Summary\n\nMail provider adapter contracts for Mail Intake.\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.",
         "members": {
           "ABC": {
             "name": "ABC",
@@ -117,28 +117,28 @@
             "name": "MailIntakeAdapter",
             "kind": "class",
             "path": "mail_intake.adapters.base.MailIntakeAdapter",
-            "signature": "<bound method Class.signature of Class('MailIntakeAdapter', 20, 92)>",
+            "signature": "<bound method Class.signature of Class('MailIntakeAdapter', 18, 93)>",
-            "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - discover messages matching a query\n        - retrieve full message payloads\n        - retrieve full thread payloads\n\n    **Lifecycle:**\n\n        - adapters are intentionally read-only and must not mutate provider state",
+            "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - Discover messages matching a query.\n        - Retrieve full message payloads.\n        - Retrieve full thread payloads.\n\n    **Lifecycle:**\n\n        - Adapters are intentionally read-only and must not mutate provider state.",
             "members": {
               "iter_message_refs": {
                 "name": "iter_message_refs",
                 "kind": "function",
                 "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs",
-                "signature": "<bound method Function.signature of Function('iter_message_refs', 36, 62)>",
+                "signature": "<bound method Function.signature of Function('iter_message_refs', 34, 63)>",
-                "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``\n\nExample:\n    Typical yield:\n\n        {\n            \"message_id\": \"...\",\n            \"thread_id\": \"...\"\n        }"
+                "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
               },
               "fetch_message": {
                 "name": "fetch_message",
                 "kind": "function",
                 "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
-                "signature": "<bound method Function.signature of Function('fetch_message', 64, 77)>",
+                "signature": "<bound method Function.signature of Function('fetch_message', 65, 78)>",
                 "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id (str):\n        Provider-specific message identifier.\n\nReturns:\n    Dict[str, Any]:\n        Provider-native message payload (e.g., Gmail message JSON structure)."
               },
               "fetch_thread": {
                 "name": "fetch_thread",
                 "kind": "function",
                 "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread",
-                "signature": "<bound method Function.signature of Function('fetch_thread', 79, 92)>",
+                "signature": "<bound method Function.signature of Function('fetch_thread', 80, 93)>",
                 "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n    thread_id (str):\n        Provider-specific thread identifier.\n\nReturns:\n    Dict[str, Any]:\n        Provider-native thread payload."
               }
             }
@@ -150,7 +150,7 @@
         "kind": "module",
         "path": "mail_intake.adapters.gmail",
         "signature": null,
-        "docstring": "Gmail adapter implementation for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n- `googleapiclient` is imported\n- Gmail REST API semantics are known\n- Low-level `.execute()` calls are made\n\nAll Gmail-specific behavior must be strictly contained within this module.",
+        "docstring": "# Summary\n\nGmail adapter implementation for Mail Intake.\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n\n- `googleapiclient` is imported.\n- Gmail REST API semantics are known.\n- Low-level `.execute()` calls are made.\n\nAll Gmail-specific behavior must be strictly contained within this module.",
         "members": {
           "Iterator": {
             "name": "Iterator",
@@ -192,14 +192,14 @@
             "kind": "class",
             "path": "mail_intake.adapters.gmail.MailIntakeAdapter",
             "signature": "<bound method Alias.signature of Alias('MailIntakeAdapter', 'mail_intake.adapters.base.MailIntakeAdapter')>",
-            "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - discover messages matching a query\n        - retrieve full message payloads\n        - retrieve full thread payloads\n\n    **Lifecycle:**\n\n        - adapters are intentionally read-only and must not mutate provider state",
+            "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - Discover messages matching a query.\n        - Retrieve full message payloads.\n        - Retrieve full thread payloads.\n\n    **Lifecycle:**\n\n        - Adapters are intentionally read-only and must not mutate provider state.",
             "members": {
               "iter_message_refs": {
                 "name": "iter_message_refs",
                 "kind": "function",
                 "path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs",
                 "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
-                "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``\n\nExample:\n    Typical yield:\n\n        {\n            \"message_id\": \"...\",\n            \"thread_id\": \"...\"\n        }"
+                "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
               },
               "fetch_message": {
                 "name": "fetch_message",
@@ -222,21 +222,21 @@
             "kind": "class",
             "path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
             "signature": "<bound method Alias.signature of Alias('MailIntakeAdapterError', 'mail_intake.exceptions.MailIntakeAdapterError')>",
-            "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when a provider adapter encounters API errors, transport failures, or invalid provider responses"
+            "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when a provider adapter encounters API errors, transport\n          failures, or invalid provider responses."
           },
           "MailIntakeAuthProvider": {
             "name": "MailIntakeAuthProvider",
             "kind": "class",
             "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider",
             "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
-            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider\n        - Refresh or revalidate credentials as needed\n        - Handle authentication-specific failure modes\n        - Coordinate with credential persistence layers where applicable\n\n    **Constraints:**\n    \n        - Mail adapters must treat returned credentials as opaque and provider-specific\n        - Mail adapters rely only on the declared credential type expected by the adapter",
+            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
             "members": {
               "get_credentials": {
                 "name": "get_credentials",
                 "kind": "function",
                 "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials",
                 "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
-                "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type ``T`` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design\n        - Represents the sole entry point through which adapters obtain authentication material\n        - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception"
+                "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
               }
             }
           },
@@ -244,8 +244,8 @@
             "name": "MailIntakeGmailAdapter",
             "kind": "class",
             "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter",
-            "signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 29, 190)>",
+            "signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 28, 189)>",
-            "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the ONLY place where googleapiclient is imported\n        - Gmail REST semantics are known\n        - .execute() is called\n\n    **Constraints:**\n    \n        - Must remain thin and imperative\n        - Must not perform parsing or interpretation\n        - Must not expose Gmail-specific types beyond this class",
+            "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the ONLY place where `googleapiclient` is imported.\n        - Gmail REST semantics are known.\n        - `.execute()` is called.\n\n    **Constraints:**\n\n        - Must remain thin and imperative.\n        - Must not perform parsing or interpretation.\n        - Must not expose Gmail-specific types beyond this class.",
             "members": {
               "service": {
                 "name": "service",
@@ -258,21 +258,21 @@
                 "name": "iter_message_refs",
                 "kind": "function",
                 "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
-                "signature": "<bound method Function.signature of Function('iter_message_refs', 93, 134)>",
+                "signature": "<bound method Function.signature of Function('iter_message_refs', 92, 133)>",
                 "docstring": "Iterate over message references matching the query.\n\nArgs:\n    query (str):\n        Gmail search query string.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail API returns an error."
               },
               "fetch_message": {
                 "name": "fetch_message",
                 "kind": "function",
                 "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message",
-                "signature": "<bound method Function.signature of Function('fetch_message', 136, 162)>",
+                "signature": "<bound method Function.signature of Function('fetch_message', 135, 161)>",
                 "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n    message_id (str):\n        Gmail message identifier.\n\nReturns:\n    Dict[str, Any]:\n        Provider-native Gmail message payload.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail API returns an error."
               },
               "fetch_thread": {
                 "name": "fetch_thread",
                 "kind": "function",
                 "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread",
-                "signature": "<bound method Function.signature of Function('fetch_thread', 164, 190)>",
+                "signature": "<bound method Function.signature of Function('fetch_thread', 163, 189)>",
                 "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n    thread_id (str):\n        Gmail thread identifier.\n\nReturns:\n    Dict[str, Any]:\n        Provider-native Gmail thread payload.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail API returns an error."
               }
             }

mcp_docs/modules/mail_intake.auth.base.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.auth.base",
   "content": {
     "path": "mail_intake.auth.base",
-    "docstring": "Authentication provider contracts for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.",
+    "docstring": "# Summary\n\nAuthentication provider contracts for Mail Intake.\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.",
     "objects": {
       "ABC": {
         "name": "ABC",
@@ -43,15 +43,15 @@
         "name": "MailIntakeAuthProvider",
         "kind": "class",
         "path": "mail_intake.auth.base.MailIntakeAuthProvider",
-        "signature": "<bound method Class.signature of Class('MailIntakeAuthProvider', 22, 66)>",
+        "signature": "<bound method Class.signature of Class('MailIntakeAuthProvider', 20, 68)>",
-        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider\n        - Refresh or revalidate credentials as needed\n        - Handle authentication-specific failure modes\n        - Coordinate with credential persistence layers where applicable\n\n    **Constraints:**\n    \n        - Mail adapters must treat returned credentials as opaque and provider-specific\n        - Mail adapters rely only on the declared credential type expected by the adapter",
+        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
         "members": {
           "get_credentials": {
             "name": "get_credentials",
             "kind": "function",
             "path": "mail_intake.auth.base.MailIntakeAuthProvider.get_credentials",
-            "signature": "<bound method Function.signature of Function('get_credentials', 44, 66)>",
+            "signature": "<bound method Function.signature of Function('get_credentials', 44, 68)>",
-            "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type ``T`` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design\n        - Represents the sole entry point through which adapters obtain authentication material\n        - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception"
+            "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
           }
         }
       }

mcp_docs/modules/mail_intake.auth.google.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.auth.google",
   "content": {
     "path": "mail_intake.auth.google",
-    "docstring": "Google authentication provider implementation for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n- Credential loading and persistence\n- Token refresh handling\n- Interactive OAuth flow initiation\n- Coordination with a credential persistence layer\n\nNo Google authentication details should leak outside this module.",
+    "docstring": "# Summary\n\nGoogle authentication provider implementation for Mail Intake.\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n\n- Credential loading and persistence.\n- Token refresh handling.\n- Interactive OAuth flow initiation.\n- Coordination with a credential persistence layer.\n\nNo Google authentication details should leak outside this module.",
     "objects": {
       "os": {
         "name": "os",
@@ -51,14 +51,14 @@
         "kind": "class",
         "path": "mail_intake.auth.google.MailIntakeAuthProvider",
         "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
-        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider\n        - Refresh or revalidate credentials as needed\n        - Handle authentication-specific failure modes\n        - Coordinate with credential persistence layers where applicable\n\n    **Constraints:**\n    \n        - Mail adapters must treat returned credentials as opaque and provider-specific\n        - Mail adapters rely only on the declared credential type expected by the adapter",
+        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
         "members": {
           "get_credentials": {
             "name": "get_credentials",
             "kind": "function",
             "path": "mail_intake.auth.google.MailIntakeAuthProvider.get_credentials",
             "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
-            "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type ``T`` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design\n        - Represents the sole entry point through which adapters obtain authentication material\n        - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception"
+            "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
           }
         }
       },
@@ -67,14 +67,14 @@
         "kind": "class",
         "path": "mail_intake.auth.google.CredentialStore",
         "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
-        "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+        "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
         "members": {
           "load": {
             "name": "load",
             "kind": "function",
             "path": "mail_intake.auth.google.CredentialStore.load",
             "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
-            "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+            "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
           },
           "save": {
             "name": "save",
@@ -97,14 +97,14 @@
         "kind": "class",
         "path": "mail_intake.auth.google.MailIntakeAuthError",
         "signature": "<bound method Alias.signature of Alias('MailIntakeAuthError', 'mail_intake.exceptions.MailIntakeAuthError')>",
-        "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire, refresh, or persist valid credentials"
+        "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire,\n          refresh, or persist valid credentials."
       },
       "MailIntakeGoogleAuth": {
         "name": "MailIntakeGoogleAuth",
         "kind": "class",
         "path": "mail_intake.auth.google.MailIntakeGoogleAuth",
-        "signature": "<bound method Class.signature of Class('MailIntakeGoogleAuth', 33, 135)>",
+        "signature": "<bound method Class.signature of Class('MailIntakeGoogleAuth', 32, 135)>",
-        "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available\n        - Refresh expired credentials when possible\n        - Initiate an interactive OAuth flow only when required\n        - Persist refreshed or newly obtained credentials via the store\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal internal state",
+        "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available.\n        - Refresh expired credentials when possible.\n        - Initiate an interactive OAuth flow only when required.\n        - Persist refreshed or newly obtained credentials via the store.\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal\n          internal state.",
         "members": {
           "credentials_path": {
             "name": "credentials_path",
@@ -132,7 +132,7 @@
             "kind": "function",
             "path": "mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials",
             "signature": "<bound method Function.signature of Function('get_credentials', 76, 135)>",
-            "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A ``google.oauth2.credentials.Credentials`` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store\n        - Refresh expired credentials when possible\n        - Perform an interactive OAuth login as a fallback\n        - Persist valid credentials for future use"
+            "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A `google.oauth2.credentials.Credentials` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store.\n        - Refresh expired credentials when possible.\n        - Perform an interactive OAuth login as a fallback.\n        - Persist valid credentials for future use."
           }
         }
       },

mcp_docs/modules/mail_intake.auth.json

@@ -2,21 +2,21 @@
   "module": "mail_intake.auth",
   "content": {
     "path": "mail_intake.auth",
-    "docstring": "Authentication provider implementations for Mail Intake.\n\n---\n\n## Summary\n\nThis package defines the **authentication layer** used by mail adapters\nto obtain provider-specific credentials.\n\nIt exposes:\n- A stable, provider-agnostic authentication contract\n- Concrete authentication providers for supported platforms\n\nAuthentication providers:\n- Are responsible for credential acquisition and lifecycle management\n- Are intentionally decoupled from adapter logic\n- May be extended by users to support additional providers\n\nConsumers should depend on the abstract interface and use concrete\nimplementations only where explicitly required.\n\n---\n\n## Public API\n\n    MailIntakeAuthProvider\n    MailIntakeGoogleAuth\n\n---",
+    "docstring": "# Summary\n\nAuthentication provider implementations for Mail Intake.\n\nThis package defines the **authentication layer** used by mail adapters\nto obtain provider-specific credentials.\n\nIt exposes:\n\n- A stable, provider-agnostic authentication contract.\n- Concrete authentication providers for supported platforms.\n\nAuthentication providers:\n\n- Are responsible for credential acquisition and lifecycle management.\n- Are intentionally decoupled from adapter logic.\n- May be extended by users to support additional providers.\n\nConsumers should depend on the abstract interface and use concrete\nimplementations only where explicitly required.\n\n---\n\n# Public API\n\n- `MailIntakeAuthProvider`\n- `MailIntakeGoogleAuth`\n\n---",
     "objects": {
       "MailIntakeAuthProvider": {
         "name": "MailIntakeAuthProvider",
         "kind": "class",
         "path": "mail_intake.auth.MailIntakeAuthProvider",
         "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
-        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider\n        - Refresh or revalidate credentials as needed\n        - Handle authentication-specific failure modes\n        - Coordinate with credential persistence layers where applicable\n\n    **Constraints:**\n    \n        - Mail adapters must treat returned credentials as opaque and provider-specific\n        - Mail adapters rely only on the declared credential type expected by the adapter",
+        "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
         "members": {
           "get_credentials": {
             "name": "get_credentials",
             "kind": "function",
             "path": "mail_intake.auth.MailIntakeAuthProvider.get_credentials",
             "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
-            "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type ``T`` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design\n        - Represents the sole entry point through which adapters obtain authentication material\n        - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception"
+            "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
           }
         }
       },
@@ -25,7 +25,7 @@
         "kind": "class",
         "path": "mail_intake.auth.MailIntakeGoogleAuth",
         "signature": "<bound method Alias.signature of Alias('MailIntakeGoogleAuth', 'mail_intake.auth.google.MailIntakeGoogleAuth')>",
-        "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available\n        - Refresh expired credentials when possible\n        - Initiate an interactive OAuth flow only when required\n        - Persist refreshed or newly obtained credentials via the store\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal internal state",
+        "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available.\n        - Refresh expired credentials when possible.\n        - Initiate an interactive OAuth flow only when required.\n        - Persist refreshed or newly obtained credentials via the store.\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal\n          internal state.",
         "members": {
           "credentials_path": {
             "name": "credentials_path",
@@ -53,7 +53,7 @@
             "kind": "function",
             "path": "mail_intake.auth.MailIntakeGoogleAuth.get_credentials",
             "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials')>",
-            "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A ``google.oauth2.credentials.Credentials`` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store\n        - Refresh expired credentials when possible\n        - Perform an interactive OAuth login as a fallback\n        - Persist valid credentials for future use"
+            "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A `google.oauth2.credentials.Credentials` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store.\n        - Refresh expired credentials when possible.\n        - Perform an interactive OAuth login as a fallback.\n        - Persist valid credentials for future use."
           }
         }
       },
@@ -62,7 +62,7 @@
         "kind": "module",
         "path": "mail_intake.auth.base",
         "signature": null,
-        "docstring": "Authentication provider contracts for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.",
+        "docstring": "# Summary\n\nAuthentication provider contracts for Mail Intake.\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.",
         "members": {
           "ABC": {
             "name": "ABC",
@@ -103,15 +103,15 @@
             "name": "MailIntakeAuthProvider",
             "kind": "class",
             "path": "mail_intake.auth.base.MailIntakeAuthProvider",
-            "signature": "<bound method Class.signature of Class('MailIntakeAuthProvider', 22, 66)>",
+            "signature": "<bound method Class.signature of Class('MailIntakeAuthProvider', 20, 68)>",
-            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider\n        - Refresh or revalidate credentials as needed\n        - Handle authentication-specific failure modes\n        - Coordinate with credential persistence layers where applicable\n\n    **Constraints:**\n    \n        - Mail adapters must treat returned credentials as opaque and provider-specific\n        - Mail adapters rely only on the declared credential type expected by the adapter",
+            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
             "members": {
               "get_credentials": {
                 "name": "get_credentials",
                 "kind": "function",
                 "path": "mail_intake.auth.base.MailIntakeAuthProvider.get_credentials",
-                "signature": "<bound method Function.signature of Function('get_credentials', 44, 66)>",
+                "signature": "<bound method Function.signature of Function('get_credentials', 44, 68)>",
-                "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type ``T`` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design\n        - Represents the sole entry point through which adapters obtain authentication material\n        - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception"
+                "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
               }
             }
           }
@@ -122,7 +122,7 @@
         "kind": "module",
         "path": "mail_intake.auth.google",
         "signature": null,
-        "docstring": "Google authentication provider implementation for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n- Credential loading and persistence\n- Token refresh handling\n- Interactive OAuth flow initiation\n- Coordination with a credential persistence layer\n\nNo Google authentication details should leak outside this module.",
+        "docstring": "# Summary\n\nGoogle authentication provider implementation for Mail Intake.\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n\n- Credential loading and persistence.\n- Token refresh handling.\n- Interactive OAuth flow initiation.\n- Coordination with a credential persistence layer.\n\nNo Google authentication details should leak outside this module.",
         "members": {
           "os": {
             "name": "os",
@@ -171,14 +171,14 @@
             "kind": "class",
             "path": "mail_intake.auth.google.MailIntakeAuthProvider",
             "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
-            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider\n        - Refresh or revalidate credentials as needed\n        - Handle authentication-specific failure modes\n        - Coordinate with credential persistence layers where applicable\n\n    **Constraints:**\n    \n        - Mail adapters must treat returned credentials as opaque and provider-specific\n        - Mail adapters rely only on the declared credential type expected by the adapter",
+            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
             "members": {
               "get_credentials": {
                 "name": "get_credentials",
                 "kind": "function",
                 "path": "mail_intake.auth.google.MailIntakeAuthProvider.get_credentials",
                 "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
-                "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type ``T`` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design\n        - Represents the sole entry point through which adapters obtain authentication material\n        - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception"
+                "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
               }
             }
           },
@@ -187,14 +187,14 @@
             "kind": "class",
             "path": "mail_intake.auth.google.CredentialStore",
             "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
-            "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+            "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
             "members": {
               "load": {
                 "name": "load",
                 "kind": "function",
                 "path": "mail_intake.auth.google.CredentialStore.load",
                 "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
-                "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+                "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
               },
               "save": {
                 "name": "save",
@@ -217,14 +217,14 @@
             "kind": "class",
             "path": "mail_intake.auth.google.MailIntakeAuthError",
             "signature": "<bound method Alias.signature of Alias('MailIntakeAuthError', 'mail_intake.exceptions.MailIntakeAuthError')>",
-            "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire, refresh, or persist valid credentials"
+            "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire,\n          refresh, or persist valid credentials."
           },
           "MailIntakeGoogleAuth": {
             "name": "MailIntakeGoogleAuth",
             "kind": "class",
             "path": "mail_intake.auth.google.MailIntakeGoogleAuth",
-            "signature": "<bound method Class.signature of Class('MailIntakeGoogleAuth', 33, 135)>",
+            "signature": "<bound method Class.signature of Class('MailIntakeGoogleAuth', 32, 135)>",
-            "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available\n        - Refresh expired credentials when possible\n        - Initiate an interactive OAuth flow only when required\n        - Persist refreshed or newly obtained credentials via the store\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal internal state",
+            "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available.\n        - Refresh expired credentials when possible.\n        - Initiate an interactive OAuth flow only when required.\n        - Persist refreshed or newly obtained credentials via the store.\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal\n          internal state.",
             "members": {
               "credentials_path": {
                 "name": "credentials_path",
@@ -252,7 +252,7 @@
                 "kind": "function",
                 "path": "mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials",
                 "signature": "<bound method Function.signature of Function('get_credentials', 76, 135)>",
-                "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A ``google.oauth2.credentials.Credentials`` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store\n        - Refresh expired credentials when possible\n        - Perform an interactive OAuth login as a fallback\n        - Persist valid credentials for future use"
+                "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A `google.oauth2.credentials.Credentials` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store.\n        - Refresh expired credentials when possible.\n        - Perform an interactive OAuth login as a fallback.\n        - Persist valid credentials for future use."
               }
             }
           },

mcp_docs/modules/mail_intake.config.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.config",
   "content": {
     "path": "mail_intake.config",
-    "docstring": "Global configuration models for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **top-level configuration object** used to control\nmail ingestion behavior across adapters, authentication providers, and\ningestion workflows.\n\nConfiguration is intentionally explicit, immutable, and free of implicit\nenvironment reads to ensure predictability and testability.",
+    "docstring": "# Summary\n\nGlobal configuration models for Mail Intake.\n\nThis module defines the **top-level configuration object** used to control\nmail ingestion behavior across adapters, authentication providers, and\ningestion workflows.\n\nConfiguration is intentionally explicit, immutable, and free of implicit\nenvironment reads to ensure predictability and testability.",
     "objects": {
       "dataclass": {
         "name": "dataclass",
@@ -22,8 +22,8 @@
         "name": "MailIntakeConfig",
         "kind": "class",
         "path": "mail_intake.config.MailIntakeConfig",
-        "signature": "<bound method Class.signature of Class('MailIntakeConfig', 20, 58)>",
+        "signature": "<bound method Class.signature of Class('MailIntakeConfig', 18, 57)>",
-        "docstring": "Global configuration for mail-intake.\n\nNotes:\n    **Guarantees:**\n\n        - This configuration is intentionally explicit and immutable\n        - No implicit environment reads or global state\n        - Explicit configuration over implicit defaults\n        - No direct environment or filesystem access\n        - This model is safe to pass across layers and suitable for serialization",
+        "docstring": "Global configuration for `mail-intake`.\n\nNotes:\n    **Guarantees:**\n\n        - This configuration is intentionally explicit and immutable.\n        - No implicit environment reads or global state.\n        - Explicit configuration over implicit defaults.\n        - No direct environment or filesystem access.\n        - This model is safe to pass across layers and suitable for\n          serialization.",
         "members": {
           "provider": {
             "name": "provider",

mcp_docs/modules/mail_intake.credentials.json

@@ -2,21 +2,21 @@
   "module": "mail_intake.credentials",
   "content": {
     "path": "mail_intake.credentials",
-    "docstring": "Credential persistence interfaces and implementations for Mail Intake.\n\n---\n\n## Summary\n\nThis package defines the abstractions and concrete implementations used\nto persist authentication credentials across Mail Intake components.\n\nThe credential persistence layer is intentionally decoupled from\nauthentication logic. Authentication providers are responsible for\ncredential acquisition, validation, and refresh, while implementations\nwithin this package are responsible solely for storage and retrieval.\n\nThe package provides:\n- A generic ``CredentialStore`` abstraction defining the persistence contract\n- Local filesystem–based storage for development and single-node use\n- Distributed, Redis-backed storage for production and scaled deployments\n\nCredential lifecycle management, interpretation, and security policy\ndecisions remain the responsibility of authentication providers.\n\n---\n\n## Public API\n\n    CredentialStore\n    PickleCredentialStore\n    RedisCredentialStore\n\n---",
+    "docstring": "# Summary\n\nCredential persistence interfaces and implementations for Mail Intake.\n\nThis package defines the abstractions and concrete implementations used\nto persist authentication credentials across Mail Intake components.\n\nThe credential persistence layer is intentionally decoupled from\nauthentication logic. Authentication providers are responsible for\ncredential acquisition, validation, and refresh, while implementations\nwithin this package are responsible solely for storage and retrieval.\n\nThe package provides:\n\n- A generic `CredentialStore` abstraction defining the persistence contract.\n- Local filesystem–based storage for development and single-node use.\n- Distributed, Redis-backed storage for production and scaled deployments.\n\nCredential lifecycle management, interpretation, and security policy\ndecisions remain the responsibility of authentication providers.\n\n---\n\n# Public API\n\n- `CredentialStore`\n- `PickleCredentialStore`\n- `RedisCredentialStore`\n\n---",
     "objects": {
       "CredentialStore": {
         "name": "CredentialStore",
         "kind": "class",
         "path": "mail_intake.credentials.CredentialStore",
         "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
-        "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+        "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
         "members": {
           "load": {
             "name": "load",
             "kind": "function",
             "path": "mail_intake.credentials.CredentialStore.load",
             "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
-            "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+            "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
           },
           "save": {
             "name": "save",
@@ -39,7 +39,7 @@
         "kind": "class",
         "path": "mail_intake.credentials.PickleCredentialStore",
         "signature": "<bound method Alias.signature of Alias('PickleCredentialStore', 'mail_intake.credentials.pickle.PickleCredentialStore')>",
-        "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem\n        - Uses pickle for serialization and deserialization\n        - Does not provide encryption, locking, or concurrency guarantees\n\n    **Constraints:**\n    \n        - Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class",
+        "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem.\n        - Uses `pickle` for serialization and deserialization.\n        - Does not provide encryption, locking, or concurrency guarantees.\n\n    **Constraints:**\n\n        - Credential lifecycle management, validation, and refresh logic are\n          explicitly out of scope for this class.",
         "members": {
           "path": {
             "name": "path",
@@ -53,7 +53,7 @@
             "kind": "function",
             "path": "mail_intake.credentials.PickleCredentialStore.load",
             "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.pickle.PickleCredentialStore.load')>",
-            "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are present and\n        successfully deserialized; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``\n        - The store does not attempt to validate or interpret the returned credentials"
+            "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully\n          deserialized, this method returns `None`.\n        - The store does not attempt to validate or interpret the\n          returned credentials."
           },
           "save": {
             "name": "save",
@@ -76,7 +76,7 @@
         "kind": "class",
         "path": "mail_intake.credentials.RedisCredentialStore",
         "signature": "<bound method Alias.signature of Alias('RedisCredentialStore', 'mail_intake.credentials.redis.RedisCredentialStore')>",
-        "docstring": "Redis-backed implementation of ``CredentialStore``.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval\n        - It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization concerns to caller-provided functions\n        - This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited",
+        "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval.\n        - It does not interpret, validate, refresh, or otherwise manage the\n          lifecycle of the credentials being stored.\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization\n          concerns to caller-provided functions.\n        - This avoids unsafe mechanisms such as `pickle` and allows\n          credential formats to be explicitly controlled and audited.",
         "members": {
           "redis": {
             "name": "redis",
@@ -118,7 +118,7 @@
             "kind": "function",
             "path": "mail_intake.credentials.RedisCredentialStore.load",
             "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.redis.RedisCredentialStore.load')>",
-            "docstring": "Load credentials from Redis.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are present and\n        successfully deserialized; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``\n        - The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable"
+            "docstring": "Load credentials from Redis.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored\n          payload cannot be successfully deserialized, this method\n          returns `None`.\n        - The store does not attempt to validate the returned\n          credentials or determine whether they are expired or\n          otherwise usable."
           },
           "save": {
             "name": "save",
@@ -141,7 +141,7 @@
         "kind": "module",
         "path": "mail_intake.credentials.pickle",
         "signature": null,
-        "docstring": "Local filesystem–based credential persistence for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a file-backed implementation of the\n``CredentialStore`` abstraction using Python's ``pickle`` module.\n\nThe pickle-based credential store is intended for local development,\nsingle-node deployments, and controlled environments where credentials\ndo not need to be shared across processes or machines.\n\nDue to the security and portability risks associated with pickle-based\nserialization, this implementation is not suitable for distributed or\nuntrusted environments.",
+        "docstring": "# Summary\n\nLocal filesystem–based credential persistence for Mail Intake.\n\nThis module provides a file-backed implementation of the\n`CredentialStore` abstraction using Python's `pickle` module.\n\nThe `pickle`-based credential store is intended for local development,\nsingle-node deployments, and controlled environments where credentials\ndo not need to be shared across processes or machines.\n\nDue to the security and portability risks associated with `pickle`-based\nserialization, this implementation is not suitable for distributed or\nuntrusted environments.",
         "members": {
           "pickle": {
             "name": "pickle",
@@ -169,14 +169,14 @@
             "kind": "class",
             "path": "mail_intake.credentials.pickle.CredentialStore",
             "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
-            "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+            "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
             "members": {
               "load": {
                 "name": "load",
                 "kind": "function",
                 "path": "mail_intake.credentials.pickle.CredentialStore.load",
                 "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
-                "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+                "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
               },
               "save": {
                 "name": "save",
@@ -205,8 +205,8 @@
             "name": "PickleCredentialStore",
             "kind": "class",
             "path": "mail_intake.credentials.pickle.PickleCredentialStore",
-            "signature": "<bound method Class.signature of Class('PickleCredentialStore', 28, 108)>",
+            "signature": "<bound method Class.signature of Class('PickleCredentialStore', 26, 109)>",
-            "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem\n        - Uses pickle for serialization and deserialization\n        - Does not provide encryption, locking, or concurrency guarantees\n\n    **Constraints:**\n    \n        - Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class",
+            "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem.\n        - Uses `pickle` for serialization and deserialization.\n        - Does not provide encryption, locking, or concurrency guarantees.\n\n    **Constraints:**\n\n        - Credential lifecycle management, validation, and refresh logic are\n          explicitly out of scope for this class.",
             "members": {
               "path": {
                 "name": "path",
@@ -219,21 +219,21 @@
                 "name": "load",
                 "kind": "function",
                 "path": "mail_intake.credentials.pickle.PickleCredentialStore.load",
-                "signature": "<bound method Function.signature of Function('load', 59, 78)>",
+                "signature": "<bound method Function.signature of Function('load', 58, 79)>",
-                "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are present and\n        successfully deserialized; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``\n        - The store does not attempt to validate or interpret the returned credentials"
+                "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully\n          deserialized, this method returns `None`.\n        - The store does not attempt to validate or interpret the\n          returned credentials."
               },
               "save": {
                 "name": "save",
                 "kind": "function",
                 "path": "mail_intake.credentials.pickle.PickleCredentialStore.save",
-                "signature": "<bound method Function.signature of Function('save', 80, 94)>",
+                "signature": "<bound method Function.signature of Function('save', 81, 95)>",
                 "docstring": "Persist credentials to the local filesystem.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials at the configured path are overwritten"
               },
               "clear": {
                 "name": "clear",
                 "kind": "function",
                 "path": "mail_intake.credentials.pickle.PickleCredentialStore.clear",
-                "signature": "<bound method Function.signature of Function('clear', 96, 108)>",
+                "signature": "<bound method Function.signature of Function('clear', 97, 109)>",
                 "docstring": "Remove persisted credentials from the local filesystem.\n\nNotes:\n    **Lifecycle:**\n\n        - This method deletes the credential file if it exists and should be treated as an idempotent operation"
               }
             }
@@ -245,7 +245,7 @@
         "kind": "module",
         "path": "mail_intake.credentials.redis",
         "signature": null,
-        "docstring": "Redis-backed credential persistence for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a Redis-based implementation of the\n``CredentialStore`` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n- Distributed-safe, shared storage using Redis\n- Explicit, caller-defined serialization and deserialization\n- No reliance on unsafe mechanisms such as pickle\n- Optional time-to-live (TTL) support for automatic credential expiry\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.",
+        "docstring": "# Summary\n\nRedis-backed credential persistence for Mail Intake.\n\nThis module provides a Redis-based implementation of the\n`CredentialStore` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n\n- Distributed-safe, shared storage using Redis.\n- Explicit, caller-defined serialization and deserialization.\n- No reliance on unsafe mechanisms such as `pickle`.\n- Optional time-to-live (TTL) support for automatic credential expiry.\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.",
         "members": {
           "Optional": {
             "name": "Optional",
@@ -273,14 +273,14 @@
             "kind": "class",
             "path": "mail_intake.credentials.redis.CredentialStore",
             "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
-            "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+            "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
             "members": {
               "load": {
                 "name": "load",
                 "kind": "function",
                 "path": "mail_intake.credentials.redis.CredentialStore.load",
                 "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
-                "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+                "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
               },
               "save": {
                 "name": "save",
@@ -309,8 +309,8 @@
             "name": "RedisCredentialStore",
             "kind": "class",
             "path": "mail_intake.credentials.redis.RedisCredentialStore",
-            "signature": "<bound method Class.signature of Class('RedisCredentialStore', 36, 142)>",
+            "signature": "<bound method Class.signature of Class('RedisCredentialStore', 35, 148)>",
-            "docstring": "Redis-backed implementation of ``CredentialStore``.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval\n        - It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization concerns to caller-provided functions\n        - This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited",
+            "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval.\n        - It does not interpret, validate, refresh, or otherwise manage the\n          lifecycle of the credentials being stored.\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization\n          concerns to caller-provided functions.\n        - This avoids unsafe mechanisms such as `pickle` and allows\n          credential formats to be explicitly controlled and audited.",
             "members": {
               "redis": {
                 "name": "redis",
@@ -351,21 +351,21 @@
                 "name": "load",
                 "kind": "function",
                 "path": "mail_intake.credentials.redis.RedisCredentialStore.load",
-                "signature": "<bound method Function.signature of Function('load', 89, 110)>",
+                "signature": "<bound method Function.signature of Function('load', 91, 116)>",
-                "docstring": "Load credentials from Redis.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are present and\n        successfully deserialized; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``\n        - The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable"
+                "docstring": "Load credentials from Redis.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored\n          payload cannot be successfully deserialized, this method\n          returns `None`.\n        - The store does not attempt to validate the returned\n          credentials or determine whether they are expired or\n          otherwise usable."
               },
               "save": {
                 "name": "save",
                 "kind": "function",
                 "path": "mail_intake.credentials.redis.RedisCredentialStore.save",
-                "signature": "<bound method Function.signature of Function('save', 112, 130)>",
+                "signature": "<bound method Function.signature of Function('save', 118, 136)>",
                 "docstring": "Persist credentials to Redis.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials under the same key are overwritten\n        - If a TTL is configured, the credentials will expire automatically after the specified duration"
               },
               "clear": {
                 "name": "clear",
                 "kind": "function",
                 "path": "mail_intake.credentials.redis.RedisCredentialStore.clear",
-                "signature": "<bound method Function.signature of Function('clear', 132, 142)>",
+                "signature": "<bound method Function.signature of Function('clear', 138, 148)>",
                 "docstring": "Remove stored credentials from Redis.\n\nNotes:\n    **Lifecycle:**\n\n        - This operation deletes the configured Redis key if it exists\n        - Implementations should treat this method as idempotent"
               }
             }
@@ -384,7 +384,7 @@
         "kind": "module",
         "path": "mail_intake.credentials.store",
         "signature": null,
-        "docstring": "Credential persistence abstractions for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the generic persistence contract used to store and\nretrieve authentication credentials across Mail Intake components.\n\nThe ``CredentialStore`` abstraction establishes a strict separation\nbetween credential *lifecycle management* and credential *storage*.\nAuthentication providers are responsible for acquiring, validating,\nrefreshing, and revoking credentials, while concrete store\nimplementations are responsible solely for persistence concerns.\n\nBy remaining agnostic to credential structure, serialization format,\nand storage backend, this module enables multiple persistence\nstrategies—such as local files, in-memory caches, distributed stores,\nor secrets managers—without coupling authentication logic to any\nspecific storage mechanism.",
+        "docstring": "# Summary\n\nCredential persistence abstractions for Mail Intake.\n\nThis module defines the generic persistence contract used to store and\nretrieve authentication credentials across Mail Intake components.\n\nThe `CredentialStore` abstraction establishes a strict separation\nbetween credential *lifecycle management* and credential *storage*.\nAuthentication providers are responsible for acquiring, validating,\nrefreshing, and revoking credentials, while concrete store\nimplementations are responsible solely for persistence concerns.\n\nBy remaining agnostic to credential structure, serialization format,\nand storage backend, this module enables multiple persistence\nstrategies—such as local files, in-memory caches, distributed stores,\nor secrets managers—without coupling authentication logic to any\nspecific storage mechanism.",
         "members": {
           "ABC": {
             "name": "ABC",
@@ -432,28 +432,28 @@
             "name": "CredentialStore",
             "kind": "class",
             "path": "mail_intake.credentials.store.CredentialStore",
-            "signature": "<bound method Class.signature of Class('CredentialStore', 31, 102)>",
+            "signature": "<bound method Class.signature of Class('CredentialStore', 29, 105)>",
-            "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+            "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
             "members": {
               "load": {
                 "name": "load",
                 "kind": "function",
                 "path": "mail_intake.credentials.store.CredentialStore.load",
-                "signature": "<bound method Function.signature of Function('load', 50, 65)>",
+                "signature": "<bound method Function.signature of Function('load', 50, 68)>",
-                "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+                "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
               },
               "save": {
                 "name": "save",
                 "kind": "function",
                 "path": "mail_intake.credentials.store.CredentialStore.save",
-                "signature": "<bound method Function.signature of Function('save', 67, 86)>",
+                "signature": "<bound method Function.signature of Function('save', 70, 89)>",
                 "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Lifecycle:**\n\n        - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n    **Responsibilities:**\n\n        - Ensuring durability appropriate to the deployment context\n        - Applying encryption or access controls where required\n        - Overwriting any previously stored credentials"
               },
               "clear": {
                 "name": "clear",
                 "kind": "function",
                 "path": "mail_intake.credentials.store.CredentialStore.clear",
-                "signature": "<bound method Function.signature of Function('clear', 88, 102)>",
+                "signature": "<bound method Function.signature of Function('clear', 91, 105)>",
                 "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n    **Lifecycle:**\n\n        - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n        - Must ensure that no stale authentication material remains accessible\n\n    **Guarantees:**\n\n        - Implementations should treat this operation as idempotent"
               }
             }

mcp_docs/modules/mail_intake.credentials.pickle.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.credentials.pickle",
   "content": {
     "path": "mail_intake.credentials.pickle",
-    "docstring": "Local filesystem–based credential persistence for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a file-backed implementation of the\n``CredentialStore`` abstraction using Python's ``pickle`` module.\n\nThe pickle-based credential store is intended for local development,\nsingle-node deployments, and controlled environments where credentials\ndo not need to be shared across processes or machines.\n\nDue to the security and portability risks associated with pickle-based\nserialization, this implementation is not suitable for distributed or\nuntrusted environments.",
+    "docstring": "# Summary\n\nLocal filesystem–based credential persistence for Mail Intake.\n\nThis module provides a file-backed implementation of the\n`CredentialStore` abstraction using Python's `pickle` module.\n\nThe `pickle`-based credential store is intended for local development,\nsingle-node deployments, and controlled environments where credentials\ndo not need to be shared across processes or machines.\n\nDue to the security and portability risks associated with `pickle`-based\nserialization, this implementation is not suitable for distributed or\nuntrusted environments.",
     "objects": {
       "pickle": {
         "name": "pickle",
@@ -30,14 +30,14 @@
         "kind": "class",
         "path": "mail_intake.credentials.pickle.CredentialStore",
         "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
-        "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+        "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
         "members": {
           "load": {
             "name": "load",
             "kind": "function",
             "path": "mail_intake.credentials.pickle.CredentialStore.load",
             "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
-            "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+            "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
           },
           "save": {
             "name": "save",
@@ -66,8 +66,8 @@
         "name": "PickleCredentialStore",
         "kind": "class",
         "path": "mail_intake.credentials.pickle.PickleCredentialStore",
-        "signature": "<bound method Class.signature of Class('PickleCredentialStore', 28, 108)>",
+        "signature": "<bound method Class.signature of Class('PickleCredentialStore', 26, 109)>",
-        "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem\n        - Uses pickle for serialization and deserialization\n        - Does not provide encryption, locking, or concurrency guarantees\n\n    **Constraints:**\n    \n        - Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class",
+        "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem.\n        - Uses `pickle` for serialization and deserialization.\n        - Does not provide encryption, locking, or concurrency guarantees.\n\n    **Constraints:**\n\n        - Credential lifecycle management, validation, and refresh logic are\n          explicitly out of scope for this class.",
         "members": {
           "path": {
             "name": "path",
@@ -80,21 +80,21 @@
             "name": "load",
             "kind": "function",
             "path": "mail_intake.credentials.pickle.PickleCredentialStore.load",
-            "signature": "<bound method Function.signature of Function('load', 59, 78)>",
+            "signature": "<bound method Function.signature of Function('load', 58, 79)>",
-            "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are present and\n        successfully deserialized; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``\n        - The store does not attempt to validate or interpret the returned credentials"
+            "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully\n          deserialized, this method returns `None`.\n        - The store does not attempt to validate or interpret the\n          returned credentials."
           },
           "save": {
             "name": "save",
             "kind": "function",
             "path": "mail_intake.credentials.pickle.PickleCredentialStore.save",
-            "signature": "<bound method Function.signature of Function('save', 80, 94)>",
+            "signature": "<bound method Function.signature of Function('save', 81, 95)>",
             "docstring": "Persist credentials to the local filesystem.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials at the configured path are overwritten"
           },
           "clear": {
             "name": "clear",
             "kind": "function",
             "path": "mail_intake.credentials.pickle.PickleCredentialStore.clear",
-            "signature": "<bound method Function.signature of Function('clear', 96, 108)>",
+            "signature": "<bound method Function.signature of Function('clear', 97, 109)>",
             "docstring": "Remove persisted credentials from the local filesystem.\n\nNotes:\n    **Lifecycle:**\n\n        - This method deletes the credential file if it exists and should be treated as an idempotent operation"
           }
         }

mcp_docs/modules/mail_intake.credentials.redis.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.credentials.redis",
   "content": {
     "path": "mail_intake.credentials.redis",
-    "docstring": "Redis-backed credential persistence for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a Redis-based implementation of the\n``CredentialStore`` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n- Distributed-safe, shared storage using Redis\n- Explicit, caller-defined serialization and deserialization\n- No reliance on unsafe mechanisms such as pickle\n- Optional time-to-live (TTL) support for automatic credential expiry\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.",
+    "docstring": "# Summary\n\nRedis-backed credential persistence for Mail Intake.\n\nThis module provides a Redis-based implementation of the\n`CredentialStore` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n\n- Distributed-safe, shared storage using Redis.\n- Explicit, caller-defined serialization and deserialization.\n- No reliance on unsafe mechanisms such as `pickle`.\n- Optional time-to-live (TTL) support for automatic credential expiry.\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.",
     "objects": {
       "Optional": {
         "name": "Optional",
@@ -30,14 +30,14 @@
         "kind": "class",
         "path": "mail_intake.credentials.redis.CredentialStore",
         "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
-        "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+        "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
         "members": {
           "load": {
             "name": "load",
             "kind": "function",
             "path": "mail_intake.credentials.redis.CredentialStore.load",
             "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
-            "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+            "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
           },
           "save": {
             "name": "save",
@@ -66,8 +66,8 @@
         "name": "RedisCredentialStore",
         "kind": "class",
         "path": "mail_intake.credentials.redis.RedisCredentialStore",
-        "signature": "<bound method Class.signature of Class('RedisCredentialStore', 36, 142)>",
+        "signature": "<bound method Class.signature of Class('RedisCredentialStore', 35, 148)>",
-        "docstring": "Redis-backed implementation of ``CredentialStore``.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval\n        - It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization concerns to caller-provided functions\n        - This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited",
+        "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval.\n        - It does not interpret, validate, refresh, or otherwise manage the\n          lifecycle of the credentials being stored.\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization\n          concerns to caller-provided functions.\n        - This avoids unsafe mechanisms such as `pickle` and allows\n          credential formats to be explicitly controlled and audited.",
         "members": {
           "redis": {
             "name": "redis",
@@ -108,21 +108,21 @@
             "name": "load",
             "kind": "function",
             "path": "mail_intake.credentials.redis.RedisCredentialStore.load",
-            "signature": "<bound method Function.signature of Function('load', 89, 110)>",
+            "signature": "<bound method Function.signature of Function('load', 91, 116)>",
-            "docstring": "Load credentials from Redis.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are present and\n        successfully deserialized; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``\n        - The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable"
+            "docstring": "Load credentials from Redis.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored\n          payload cannot be successfully deserialized, this method\n          returns `None`.\n        - The store does not attempt to validate the returned\n          credentials or determine whether they are expired or\n          otherwise usable."
           },
           "save": {
             "name": "save",
             "kind": "function",
             "path": "mail_intake.credentials.redis.RedisCredentialStore.save",
-            "signature": "<bound method Function.signature of Function('save', 112, 130)>",
+            "signature": "<bound method Function.signature of Function('save', 118, 136)>",
             "docstring": "Persist credentials to Redis.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials under the same key are overwritten\n        - If a TTL is configured, the credentials will expire automatically after the specified duration"
           },
           "clear": {
             "name": "clear",
             "kind": "function",
             "path": "mail_intake.credentials.redis.RedisCredentialStore.clear",
-            "signature": "<bound method Function.signature of Function('clear', 132, 142)>",
+            "signature": "<bound method Function.signature of Function('clear', 138, 148)>",
             "docstring": "Remove stored credentials from Redis.\n\nNotes:\n    **Lifecycle:**\n\n        - This operation deletes the configured Redis key if it exists\n        - Implementations should treat this method as idempotent"
           }
         }

mcp_docs/modules/mail_intake.credentials.store.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.credentials.store",
   "content": {
     "path": "mail_intake.credentials.store",
-    "docstring": "Credential persistence abstractions for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the generic persistence contract used to store and\nretrieve authentication credentials across Mail Intake components.\n\nThe ``CredentialStore`` abstraction establishes a strict separation\nbetween credential *lifecycle management* and credential *storage*.\nAuthentication providers are responsible for acquiring, validating,\nrefreshing, and revoking credentials, while concrete store\nimplementations are responsible solely for persistence concerns.\n\nBy remaining agnostic to credential structure, serialization format,\nand storage backend, this module enables multiple persistence\nstrategies—such as local files, in-memory caches, distributed stores,\nor secrets managers—without coupling authentication logic to any\nspecific storage mechanism.",
+    "docstring": "# Summary\n\nCredential persistence abstractions for Mail Intake.\n\nThis module defines the generic persistence contract used to store and\nretrieve authentication credentials across Mail Intake components.\n\nThe `CredentialStore` abstraction establishes a strict separation\nbetween credential *lifecycle management* and credential *storage*.\nAuthentication providers are responsible for acquiring, validating,\nrefreshing, and revoking credentials, while concrete store\nimplementations are responsible solely for persistence concerns.\n\nBy remaining agnostic to credential structure, serialization format,\nand storage backend, this module enables multiple persistence\nstrategies—such as local files, in-memory caches, distributed stores,\nor secrets managers—without coupling authentication logic to any\nspecific storage mechanism.",
     "objects": {
       "ABC": {
         "name": "ABC",
@@ -50,28 +50,28 @@
         "name": "CredentialStore",
         "kind": "class",
         "path": "mail_intake.credentials.store.CredentialStore",
-        "signature": "<bound method Class.signature of Class('CredentialStore', 31, 102)>",
+        "signature": "<bound method Class.signature of Class('CredentialStore', 29, 105)>",
-        "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+        "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
         "members": {
           "load": {
             "name": "load",
             "kind": "function",
             "path": "mail_intake.credentials.store.CredentialStore.load",
-            "signature": "<bound method Function.signature of Function('load', 50, 65)>",
+            "signature": "<bound method Function.signature of Function('load', 50, 68)>",
-            "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+            "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
           },
           "save": {
             "name": "save",
             "kind": "function",
             "path": "mail_intake.credentials.store.CredentialStore.save",
-            "signature": "<bound method Function.signature of Function('save', 67, 86)>",
+            "signature": "<bound method Function.signature of Function('save', 70, 89)>",
             "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Lifecycle:**\n\n        - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n    **Responsibilities:**\n\n        - Ensuring durability appropriate to the deployment context\n        - Applying encryption or access controls where required\n        - Overwriting any previously stored credentials"
           },
           "clear": {
             "name": "clear",
             "kind": "function",
             "path": "mail_intake.credentials.store.CredentialStore.clear",
-            "signature": "<bound method Function.signature of Function('clear', 88, 102)>",
+            "signature": "<bound method Function.signature of Function('clear', 91, 105)>",
             "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n    **Lifecycle:**\n\n        - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n        - Must ensure that no stale authentication material remains accessible\n\n    **Guarantees:**\n\n        - Implementations should treat this operation as idempotent"
           }
         }

mcp_docs/modules/mail_intake.exceptions.json

@@ -15,22 +15,22 @@
         "name": "MailIntakeAuthError",
         "kind": "class",
         "path": "mail_intake.exceptions.MailIntakeAuthError",
-        "signature": "<bound method Class.signature of Class('MailIntakeAuthError', 30, 38)>",
+        "signature": "<bound method Class.signature of Class('MailIntakeAuthError', 30, 39)>",
-        "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire, refresh, or persist valid credentials"
+        "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire,\n          refresh, or persist valid credentials."
       },
       "MailIntakeAdapterError": {
         "name": "MailIntakeAdapterError",
         "kind": "class",
         "path": "mail_intake.exceptions.MailIntakeAdapterError",
-        "signature": "<bound method Class.signature of Class('MailIntakeAdapterError', 41, 49)>",
+        "signature": "<bound method Class.signature of Class('MailIntakeAdapterError', 42, 51)>",
-        "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when a provider adapter encounters API errors, transport failures, or invalid provider responses"
+        "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when a provider adapter encounters API errors, transport\n          failures, or invalid provider responses."
       },
       "MailIntakeParsingError": {
         "name": "MailIntakeParsingError",
         "kind": "class",
         "path": "mail_intake.exceptions.MailIntakeParsingError",
-        "signature": "<bound method Class.signature of Class('MailIntakeParsingError', 52, 60)>",
+        "signature": "<bound method Class.signature of Class('MailIntakeParsingError', 54, 63)>",
-        "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or normalized into internal domain models"
+        "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
       }
     }
   }

mcp_docs/modules/mail_intake.ingestion.json

@@ -2,14 +2,14 @@
   "module": "mail_intake.ingestion",
   "content": {
     "path": "mail_intake.ingestion",
-    "docstring": "Mail ingestion orchestration for Mail Intake.\n\n---\n\n## Summary\n\nThis package contains **high-level ingestion components** responsible for\ncoordinating mail retrieval, parsing, normalization, and model construction.\n\nIt represents the **top of the ingestion pipeline** and is intended to be the\nprimary interaction surface for library consumers.\n\nComponents in this package:\n- Are provider-agnostic\n- Depend only on adapter and parser contracts\n- Contain no provider-specific API logic\n- Expose read-only ingestion workflows\n\nConsumers are expected to construct a mail adapter and pass it to the\ningestion layer to begin processing messages and threads.\n\n---\n\n## Public API\n\n    MailIntakeReader\n\n---",
+    "docstring": "# Summary\n\nMail ingestion orchestration for Mail Intake.\n\nThis package contains **high-level ingestion components** responsible for\ncoordinating mail retrieval, parsing, normalization, and model construction.\n\nIt represents the **top of the ingestion pipeline** and is intended to be the\nprimary interaction surface for library consumers.\n\nComponents in this package:\n\n- Are provider-agnostic.\n- Depend only on adapter and parser contracts.\n- Contain no provider-specific API logic.\n- Expose read-only ingestion workflows.\n\nConsumers are expected to construct a mail adapter and pass it to the\ningestion layer to begin processing messages and threads.\n\n---\n\n# Public API\n\n- `MailIntakeReader`\n\n---",
     "objects": {
       "MailIntakeReader": {
         "name": "MailIntakeReader",
         "kind": "class",
         "path": "mail_intake.ingestion.MailIntakeReader",
         "signature": "<bound method Alias.signature of Alias('MailIntakeReader', 'mail_intake.ingestion.reader.MailIntakeReader')>",
-        "docstring": "High-level read-only ingestion interface.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the primary entry point for consumers of the Mail Intake library\n        - It orchestrates the full ingestion pipeline: Querying the adapter for message references, fetching raw provider messages, parsing and normalizing message data, constructing domain models\n\n    **Constraints:**\n    \n        - This class is intentionally: Provider-agnostic, stateless beyond iteration scope, read-only",
+        "docstring": "High-level read-only ingestion interface.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the primary entry point for consumers of the\n          Mail Intake library.\n        - It orchestrates the full ingestion pipeline:\n            - Querying the adapter for message references.\n            - Fetching raw provider messages.\n            - Parsing and normalizing message data.\n            - Constructing domain models.\n\n    **Constraints:**\n\n        - This class is intentionally: Provider-agnostic, stateless beyond\n          iteration scope, read-only.",
         "members": {
           "iter_messages": {
             "name": "iter_messages",
@@ -23,7 +23,7 @@
             "kind": "function",
             "path": "mail_intake.ingestion.MailIntakeReader.iter_threads",
             "signature": "<bound method Alias.signature of Alias('iter_threads', 'mail_intake.ingestion.reader.MailIntakeReader.iter_threads')>",
-            "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeThread:\n        An iterator of `MailIntakeThread` instances.\n\nRaises:\n    MailIntakeParsingError:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages"
+            "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeThread:\n        An iterator of `MailIntakeThread` instances.\n\nRaises:\n    `MailIntakeParsingError`:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete\n          thread objects containing all associated messages."
           }
         }
       },
@@ -32,7 +32,7 @@
         "kind": "module",
         "path": "mail_intake.ingestion.reader",
         "signature": null,
-        "docstring": "High-level mail ingestion orchestration for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n- Mail adapter access\n- Message and thread iteration\n- Header and body parsing\n- Normalization and model construction\n\nNo provider-specific logic or API semantics are permitted in this layer.",
+        "docstring": "# Summary\n\nHigh-level mail ingestion orchestration for Mail Intake.\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n\n- Mail adapter access.\n- Message and thread iteration.\n- Header and body parsing.\n- Normalization and model construction.\n\nNo provider-specific logic or API semantics are permitted in this layer.",
         "members": {
           "datetime": {
             "name": "datetime",
@@ -67,14 +67,14 @@
             "kind": "class",
             "path": "mail_intake.ingestion.reader.MailIntakeAdapter",
             "signature": "<bound method Alias.signature of Alias('MailIntakeAdapter', 'mail_intake.adapters.base.MailIntakeAdapter')>",
-            "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - discover messages matching a query\n        - retrieve full message payloads\n        - retrieve full thread payloads\n\n    **Lifecycle:**\n\n        - adapters are intentionally read-only and must not mutate provider state",
+            "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - Discover messages matching a query.\n        - Retrieve full message payloads.\n        - Retrieve full thread payloads.\n\n    **Lifecycle:**\n\n        - Adapters are intentionally read-only and must not mutate provider state.",
             "members": {
               "iter_message_refs": {
                 "name": "iter_message_refs",
                 "kind": "function",
                 "path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs",
                 "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
-                "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``\n\nExample:\n    Typical yield:\n\n        {\n            \"message_id\": \"...\",\n            \"thread_id\": \"...\"\n        }"
+                "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
               },
               "fetch_message": {
                 "name": "fetch_message",
@@ -97,7 +97,7 @@
             "kind": "class",
             "path": "mail_intake.ingestion.reader.MailIntakeMessage",
             "signature": "<bound method Alias.signature of Alias('MailIntakeMessage', 'mail_intake.models.message.MailIntakeMessage')>",
-            "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message\n        - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n\n    **Constraints:**\n    \n        - No provider-specific identifiers, payloads, or API semantics should appear in this model",
+            "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message.\n        - It is intentionally provider-agnostic and suitable for\n          persistence, indexing, and downstream processing.\n\n    **Constraints:**\n\n        - No provider-specific identifiers, payloads, or API semantics\n          should appear in this model.",
             "members": {
               "message_id": {
                 "name": "message_id",
@@ -169,7 +169,7 @@
             "kind": "class",
             "path": "mail_intake.ingestion.reader.MailIntakeThread",
             "signature": "<bound method Alias.signature of Alias('MailIntakeThread', 'mail_intake.models.thread.MailIntakeThread')>",
-            "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject and participant set\n        - It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions\n        - This model is provider-agnostic and safe to persist",
+            "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject\n          and participant set.\n        - It is designed to support reasoning over conversational context\n          such as job applications, interviews, follow-ups, and ongoing discussions.\n        - This model is provider-agnostic and safe to persist.",
             "members": {
               "thread_id": {
                 "name": "thread_id",
@@ -211,7 +211,7 @@
                 "kind": "function",
                 "path": "mail_intake.ingestion.reader.MailIntakeThread.add_message",
                 "signature": "<bound method Alias.signature of Alias('add_message', 'mail_intake.models.thread.MailIntakeThread.add_message')>",
-                "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread\n        - Tracks unique participants\n        - Updates the last activity timestamp"
+                "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread.\n        - Tracks unique participants.\n        - Updates the last activity timestamp."
               }
             }
           },
@@ -220,56 +220,56 @@
             "kind": "function",
             "path": "mail_intake.ingestion.reader.parse_headers",
             "signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
-            "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing ``name`` and ``value`` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings\n        - This function normalizes them into a case-insensitive dictionary keyed by lowercase header names\n\nExample:\n    Typical usage:\n    \n        Input:\n            [\n                {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n                {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n            ]\n\n        Output:\n            {\n                \"from\": \"John Doe <john@example.com>\",\n                \"subject\": \"Re: Interview Update\",\n            }"
+            "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
           },
           "extract_sender": {
             "name": "extract_sender",
             "kind": "function",
             "path": "mail_intake.ingestion.reader.extract_sender",
             "signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
-            "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by :func:`parse_headers`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple ``(email, name)`` where ``email`` is the sender email address and ``name`` is the display name, or ``None`` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name\n\nExample:\n    Typical values:\n\n        ``\"John Doe <john@example.com>\"`` -> ``(\"john@example.com\", \"John Doe\")``\n        ``\"john@example.com\"`` -> ``(\"john@example.com\", None)``"
+            "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
           },
           "extract_body": {
             "name": "extract_body",
             "kind": "function",
             "path": "mail_intake.ingestion.reader.extract_body",
             "signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
-            "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n    payload: Provider-native message payload dictionary.\n\nReturns:\n    Extracted plain-text message body."
+            "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (Dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
           },
           "normalize_subject": {
             "name": "normalize_subject",
             "kind": "function",
             "path": "mail_intake.ingestion.reader.normalize_subject",
             "signature": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.normalize_subject')>",
-            "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n        - Repeats prefix stripping to handle stacked prefixes\n        - Collapses excessive whitespace\n        - Preserves original casing (no lowercasing)\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject"
+            "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
           },
           "MailIntakeParsingError": {
             "name": "MailIntakeParsingError",
             "kind": "class",
             "path": "mail_intake.ingestion.reader.MailIntakeParsingError",
             "signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
-            "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or normalized into internal domain models"
+            "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
           },
           "MailIntakeReader": {
             "name": "MailIntakeReader",
             "kind": "class",
             "path": "mail_intake.ingestion.reader.MailIntakeReader",
-            "signature": "<bound method Class.signature of Class('MailIntakeReader', 32, 165)>",
+            "signature": "<bound method Class.signature of Class('MailIntakeReader', 31, 171)>",
-            "docstring": "High-level read-only ingestion interface.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the primary entry point for consumers of the Mail Intake library\n        - It orchestrates the full ingestion pipeline: Querying the adapter for message references, fetching raw provider messages, parsing and normalizing message data, constructing domain models\n\n    **Constraints:**\n    \n        - This class is intentionally: Provider-agnostic, stateless beyond iteration scope, read-only",
+            "docstring": "High-level read-only ingestion interface.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the primary entry point for consumers of the\n          Mail Intake library.\n        - It orchestrates the full ingestion pipeline:\n            - Querying the adapter for message references.\n            - Fetching raw provider messages.\n            - Parsing and normalizing message data.\n            - Constructing domain models.\n\n    **Constraints:**\n\n        - This class is intentionally: Provider-agnostic, stateless beyond\n          iteration scope, read-only.",
             "members": {
               "iter_messages": {
                 "name": "iter_messages",
                 "kind": "function",
                 "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages",
-                "signature": "<bound method Function.signature of Function('iter_messages', 57, 75)>",
+                "signature": "<bound method Function.signature of Function('iter_messages', 62, 80)>",
                 "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeMessage:\n        Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n    MailIntakeParsingError:\n        If a message cannot be parsed."
               },
               "iter_threads": {
                 "name": "iter_threads",
                 "kind": "function",
                 "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads",
-                "signature": "<bound method Function.signature of Function('iter_threads', 77, 114)>",
+                "signature": "<bound method Function.signature of Function('iter_threads', 82, 120)>",
-                "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeThread:\n        An iterator of `MailIntakeThread` instances.\n\nRaises:\n    MailIntakeParsingError:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages"
+                "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeThread:\n        An iterator of `MailIntakeThread` instances.\n\nRaises:\n    `MailIntakeParsingError`:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete\n          thread objects containing all associated messages."
               }
             }
           }

mcp_docs/modules/mail_intake.ingestion.reader.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.ingestion.reader",
   "content": {
     "path": "mail_intake.ingestion.reader",
-    "docstring": "High-level mail ingestion orchestration for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n- Mail adapter access\n- Message and thread iteration\n- Header and body parsing\n- Normalization and model construction\n\nNo provider-specific logic or API semantics are permitted in this layer.",
+    "docstring": "# Summary\n\nHigh-level mail ingestion orchestration for Mail Intake.\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n\n- Mail adapter access.\n- Message and thread iteration.\n- Header and body parsing.\n- Normalization and model construction.\n\nNo provider-specific logic or API semantics are permitted in this layer.",
     "objects": {
       "datetime": {
         "name": "datetime",
@@ -37,14 +37,14 @@
         "kind": "class",
         "path": "mail_intake.ingestion.reader.MailIntakeAdapter",
         "signature": "<bound method Alias.signature of Alias('MailIntakeAdapter', 'mail_intake.adapters.base.MailIntakeAdapter')>",
-        "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - discover messages matching a query\n        - retrieve full message payloads\n        - retrieve full thread payloads\n\n    **Lifecycle:**\n\n        - adapters are intentionally read-only and must not mutate provider state",
+        "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - Discover messages matching a query.\n        - Retrieve full message payloads.\n        - Retrieve full thread payloads.\n\n    **Lifecycle:**\n\n        - Adapters are intentionally read-only and must not mutate provider state.",
         "members": {
           "iter_message_refs": {
             "name": "iter_message_refs",
             "kind": "function",
             "path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs",
             "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
-            "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``\n\nExample:\n    Typical yield:\n\n        {\n            \"message_id\": \"...\",\n            \"thread_id\": \"...\"\n        }"
+            "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
           },
           "fetch_message": {
             "name": "fetch_message",
@@ -67,7 +67,7 @@
         "kind": "class",
         "path": "mail_intake.ingestion.reader.MailIntakeMessage",
         "signature": "<bound method Alias.signature of Alias('MailIntakeMessage', 'mail_intake.models.message.MailIntakeMessage')>",
-        "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message\n        - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n\n    **Constraints:**\n    \n        - No provider-specific identifiers, payloads, or API semantics should appear in this model",
+        "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message.\n        - It is intentionally provider-agnostic and suitable for\n          persistence, indexing, and downstream processing.\n\n    **Constraints:**\n\n        - No provider-specific identifiers, payloads, or API semantics\n          should appear in this model.",
         "members": {
           "message_id": {
             "name": "message_id",
@@ -139,7 +139,7 @@
         "kind": "class",
         "path": "mail_intake.ingestion.reader.MailIntakeThread",
         "signature": "<bound method Alias.signature of Alias('MailIntakeThread', 'mail_intake.models.thread.MailIntakeThread')>",
-        "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject and participant set\n        - It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions\n        - This model is provider-agnostic and safe to persist",
+        "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject\n          and participant set.\n        - It is designed to support reasoning over conversational context\n          such as job applications, interviews, follow-ups, and ongoing discussions.\n        - This model is provider-agnostic and safe to persist.",
         "members": {
           "thread_id": {
             "name": "thread_id",
@@ -181,7 +181,7 @@
             "kind": "function",
             "path": "mail_intake.ingestion.reader.MailIntakeThread.add_message",
             "signature": "<bound method Alias.signature of Alias('add_message', 'mail_intake.models.thread.MailIntakeThread.add_message')>",
-            "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread\n        - Tracks unique participants\n        - Updates the last activity timestamp"
+            "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread.\n        - Tracks unique participants.\n        - Updates the last activity timestamp."
           }
         }
       },
@@ -190,56 +190,56 @@
         "kind": "function",
         "path": "mail_intake.ingestion.reader.parse_headers",
         "signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
-        "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing ``name`` and ``value`` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings\n        - This function normalizes them into a case-insensitive dictionary keyed by lowercase header names\n\nExample:\n    Typical usage:\n    \n        Input:\n            [\n                {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n                {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n            ]\n\n        Output:\n            {\n                \"from\": \"John Doe <john@example.com>\",\n                \"subject\": \"Re: Interview Update\",\n            }"
+        "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
       },
       "extract_sender": {
         "name": "extract_sender",
         "kind": "function",
         "path": "mail_intake.ingestion.reader.extract_sender",
         "signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
-        "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by :func:`parse_headers`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple ``(email, name)`` where ``email`` is the sender email address and ``name`` is the display name, or ``None`` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name\n\nExample:\n    Typical values:\n\n        ``\"John Doe <john@example.com>\"`` -> ``(\"john@example.com\", \"John Doe\")``\n        ``\"john@example.com\"`` -> ``(\"john@example.com\", None)``"
+        "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
       },
       "extract_body": {
         "name": "extract_body",
         "kind": "function",
         "path": "mail_intake.ingestion.reader.extract_body",
         "signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
-        "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n    payload: Provider-native message payload dictionary.\n\nReturns:\n    Extracted plain-text message body."
+        "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (Dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
       },
       "normalize_subject": {
         "name": "normalize_subject",
         "kind": "function",
         "path": "mail_intake.ingestion.reader.normalize_subject",
         "signature": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.normalize_subject')>",
-        "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n        - Repeats prefix stripping to handle stacked prefixes\n        - Collapses excessive whitespace\n        - Preserves original casing (no lowercasing)\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject"
+        "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
       },
       "MailIntakeParsingError": {
         "name": "MailIntakeParsingError",
         "kind": "class",
         "path": "mail_intake.ingestion.reader.MailIntakeParsingError",
         "signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
-        "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or normalized into internal domain models"
+        "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
       },
       "MailIntakeReader": {
         "name": "MailIntakeReader",
         "kind": "class",
         "path": "mail_intake.ingestion.reader.MailIntakeReader",
-        "signature": "<bound method Class.signature of Class('MailIntakeReader', 32, 165)>",
+        "signature": "<bound method Class.signature of Class('MailIntakeReader', 31, 171)>",
-        "docstring": "High-level read-only ingestion interface.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the primary entry point for consumers of the Mail Intake library\n        - It orchestrates the full ingestion pipeline: Querying the adapter for message references, fetching raw provider messages, parsing and normalizing message data, constructing domain models\n\n    **Constraints:**\n    \n        - This class is intentionally: Provider-agnostic, stateless beyond iteration scope, read-only",
+        "docstring": "High-level read-only ingestion interface.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the primary entry point for consumers of the\n          Mail Intake library.\n        - It orchestrates the full ingestion pipeline:\n            - Querying the adapter for message references.\n            - Fetching raw provider messages.\n            - Parsing and normalizing message data.\n            - Constructing domain models.\n\n    **Constraints:**\n\n        - This class is intentionally: Provider-agnostic, stateless beyond\n          iteration scope, read-only.",
         "members": {
           "iter_messages": {
             "name": "iter_messages",
             "kind": "function",
             "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages",
-            "signature": "<bound method Function.signature of Function('iter_messages', 57, 75)>",
+            "signature": "<bound method Function.signature of Function('iter_messages', 62, 80)>",
             "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeMessage:\n        Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n    MailIntakeParsingError:\n        If a message cannot be parsed."
           },
           "iter_threads": {
             "name": "iter_threads",
             "kind": "function",
             "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads",
-            "signature": "<bound method Function.signature of Function('iter_threads', 77, 114)>",
+            "signature": "<bound method Function.signature of Function('iter_threads', 82, 120)>",
-            "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeThread:\n        An iterator of `MailIntakeThread` instances.\n\nRaises:\n    MailIntakeParsingError:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages"
+            "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeThread:\n        An iterator of `MailIntakeThread` instances.\n\nRaises:\n    `MailIntakeParsingError`:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete\n          thread objects containing all associated messages."
           }
         }
       }

mcp_docs/modules/mail_intake.json

@@ -2,14 +2,14 @@
   "module": "mail_intake",
   "content": {
     "path": "mail_intake",
-    "docstring": "Mail Intake — provider-agnostic, read-only email ingestion framework.\n\n---\n\n## Summary\n\nMail Intake is a **contract-first library** designed to ingest, parse, and\nnormalize email data from external providers (such as Gmail) into clean,\nprovider-agnostic domain models.\n\nThe library is intentionally structured around clear layers, each exposed\nas a first-class module at the package root:\n\n- adapters: provider-specific access (e.g. Gmail)\n- auth: authentication providers and credential lifecycle management\n- credentials: credential persistence abstractions and implementations\n- parsers: extraction and normalization of message content\n- ingestion: orchestration and high-level ingestion workflows\n- models: canonical, provider-agnostic data representations\n- config: explicit global configuration\n- exceptions: library-defined error hierarchy\n\nThe package root acts as a **namespace**, not a facade. Consumers are\nexpected to import functionality explicitly from the appropriate module.\n\n---\n\n## Installation\n\nInstall using pip:\n\n    pip install mail-intake\n\nOr with Poetry:\n\n    poetry add mail-intake\n\nMail Intake is pure Python and has no runtime dependencies beyond those\nrequired by the selected provider (for example, Google APIs for Gmail).\n\n---\n\n## Quick start\n\nMinimal Gmail ingestion example (local development):\n\n    from mail_intake.ingestion import MailIntakeReader\n    from mail_intake.adapters import MailIntakeGmailAdapter\n    from mail_intake.auth import MailIntakeGoogleAuth\n    from mail_intake.credentials import PickleCredentialStore\n\n    store = PickleCredentialStore(path=\"token.pickle\")\n\n    auth = MailIntakeGoogleAuth(\n        credentials_path=\"credentials.json\",\n        store=store,\n        scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n    )\n\n    adapter = MailIntakeGmailAdapter(auth_provider=auth)\n    reader = MailIntakeReader(adapter)\n\n    for message in reader.iter_messages(\"from:recruiter@example.com\"):\n        print(message.subject, message.from_email)\n\nIterating over threads:\n\n    for thread in reader.iter_threads(\"subject:Interview\"):\n        print(thread.normalized_subject, len(thread.messages))\n\n---\n\n## Architecture\n\nMail Intake is designed to be extensible via **public contracts** exposed\nthrough its modules:\n\n- Users MAY implement their own mail adapters by subclassing ``adapters.MailIntakeAdapter``\n- Users MAY implement their own authentication providers by subclassing ``auth.MailIntakeAuthProvider[T]``\n- Users MAY implement their own credential persistence layers by implementing ``credentials.CredentialStore[T]``\n\nUsers SHOULD NOT subclass built-in adapter implementations. Built-in\nadapters (such as Gmail) are reference implementations and may change\ninternally without notice.\n\n**Design Guarantees:**\n- Read-only access: no mutation of provider state\n- Provider-agnostic domain models\n- Explicit configuration and dependency injection\n- No implicit global state or environment reads\n- Deterministic, testable behavior\n- Distributed-safe authentication design\n\nMail Intake favors correctness, clarity, and explicitness over convenience\nshortcuts.\n\n**Core Philosophy:**\n`Mail Intake` is built as a **contract-first ingestion pipeline**:\n1. **Layered Decoupling**: Adapters handle transport, Parsers handle format normalization, and Ingestion orchestrates.\n2. **Provider Agnosticism**: Domain models and core logic never depend on provider-specific (e.g., Gmail) API internals.\n3. **Stateless Workflows**: The library functions as a read-only pipe, ensuring side-effect-free ingestion.\n\n---\n\n## Public API\n\nThe supported public API consists of the following top-level modules:\n\n- mail_intake.ingestion\n- mail_intake.adapters\n- mail_intake.auth\n- mail_intake.credentials\n- mail_intake.parsers\n- mail_intake.models\n- mail_intake.config\n- mail_intake.exceptions\n\nClasses and functions should be imported explicitly from these modules.\nNo individual symbols are re-exported at the package root.\n\n---",
+    "docstring": "# Summary\n\nMail Intake — provider-agnostic, read-only email ingestion framework.\n\nMail Intake is a **contract-first library** designed to ingest, parse, and\nnormalize email data from external providers (such as Gmail) into clean,\nprovider-agnostic domain models.\n\nThe library is intentionally structured around clear layers, each exposed\nas a first-class module at the package root:\n\n- `adapters`: Provider-specific access (e.g., Gmail).\n- `auth`: Authentication providers and credential lifecycle management.\n- `credentials`: Credential persistence abstractions and implementations.\n- `parsers`: Extraction and normalization of message content.\n- `ingestion`: Orchestration and high-level ingestion workflows.\n- `models`: Canonical, provider-agnostic data representations.\n- `config`: Explicit global configuration.\n- `exceptions`: Library-defined error hierarchy.\n\nThe package root acts as a **namespace**, not a facade. Consumers are\nexpected to import functionality explicitly from the appropriate module.\n\n---\n\n# Installation\n\nInstall using pip:\n\n```bash\npip install mail-intake\n```\n\nOr with Poetry:\n\n```bash\npoetry add mail-intake\n```\n\nMail Intake is pure Python and has no runtime dependencies beyond those\nrequired by the selected provider (for example, Google APIs for Gmail).\n\n---\n\n# Quick Start\n\nMinimal Gmail ingestion example (local development):\n\n```python\nfrom mail_intake.ingestion import MailIntakeReader\nfrom mail_intake.adapters import MailIntakeGmailAdapter\nfrom mail_intake.auth import MailIntakeGoogleAuth\nfrom mail_intake.credentials import PickleCredentialStore\n\nstore = PickleCredentialStore(path=\"token.pickle\")\n\nauth = MailIntakeGoogleAuth(\n    credentials_path=\"credentials.json\",\n    store=store,\n    scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n)\n\nadapter = MailIntakeGmailAdapter(auth_provider=auth)\nreader = MailIntakeReader(adapter)\n\nfor message in reader.iter_messages(\"from:recruiter@example.com\"):\n    print(message.subject, message.from_email)\n```\n\nIterating over threads:\n\n```python\nfor thread in reader.iter_threads(\"subject:Interview\"):\n    print(thread.normalized_subject, len(thread.messages))\n```\n\n---\n\n# Architecture\n\nMail Intake is designed to be extensible via **public contracts** exposed\nthrough its modules:\n\n- Users MAY implement their own mail adapters by subclassing\n  `adapters.MailIntakeAdapter`.\n- Users MAY implement their own authentication providers by subclassing\n  `auth.MailIntakeAuthProvider[T]`.\n- Users MAY implement their own credential persistence layers by implementing\n  `credentials.CredentialStore[T]`.\n\nUsers SHOULD NOT subclass built-in adapter implementations. Built-in\nadapters (such as Gmail) are reference implementations and may change\ninternally without notice.\n\n**Design Guarantees:**\n\n- Read-only access: no mutation of provider state.\n- Provider-agnostic domain models.\n- Explicit configuration and dependency injection.\n- No implicit global state or environment reads.\n- Deterministic, testable behavior.\n- Distributed-safe authentication design.\n\nMail Intake favors correctness, clarity, and explicitness over convenience\nshortcuts.\n\n**Core Philosophy:**\n\n`Mail Intake` is built as a **contract-first ingestion pipeline**:\n\n1. **Layered Decoupling**: Adapters handle transport, Parsers handle format\n   normalization, and Ingestion orchestrates.\n2. **Provider Agnosticism**: Domain models and core logic never depend on\n   provider-specific (e.g., Gmail) API internals.\n3. **Stateless Workflows**: The library functions as a read-only pipe, ensuring\n   side-effect-free ingestion.\n\n---\n\n# Public API\n\nThe supported public API consists of the following top-level modules:\n\n- `mail_intake.ingestion`\n- `mail_intake.adapters`\n- `mail_intake.auth`\n- `mail_intake.credentials`\n- `mail_intake.parsers`\n- `mail_intake.models`\n- `mail_intake.config`\n- `mail_intake.exceptions`\n\nClasses and functions should be imported explicitly from these modules.\nNo individual symbols are re-exported at the package root.\n\n---",
     "objects": {
       "config": {
         "name": "config",
         "kind": "module",
         "path": "mail_intake.config",
         "signature": null,
-        "docstring": "Global configuration models for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **top-level configuration object** used to control\nmail ingestion behavior across adapters, authentication providers, and\ningestion workflows.\n\nConfiguration is intentionally explicit, immutable, and free of implicit\nenvironment reads to ensure predictability and testability.",
+        "docstring": "# Summary\n\nGlobal configuration models for Mail Intake.\n\nThis module defines the **top-level configuration object** used to control\nmail ingestion behavior across adapters, authentication providers, and\ningestion workflows.\n\nConfiguration is intentionally explicit, immutable, and free of implicit\nenvironment reads to ensure predictability and testability.",
         "members": {
           "dataclass": {
             "name": "dataclass",
@@ -29,8 +29,8 @@
             "name": "MailIntakeConfig",
             "kind": "class",
             "path": "mail_intake.config.MailIntakeConfig",
-            "signature": "<bound method Class.signature of Class('MailIntakeConfig', 20, 58)>",
+            "signature": "<bound method Class.signature of Class('MailIntakeConfig', 18, 57)>",
-            "docstring": "Global configuration for mail-intake.\n\nNotes:\n    **Guarantees:**\n\n        - This configuration is intentionally explicit and immutable\n        - No implicit environment reads or global state\n        - Explicit configuration over implicit defaults\n        - No direct environment or filesystem access\n        - This model is safe to pass across layers and suitable for serialization",
+            "docstring": "Global configuration for `mail-intake`.\n\nNotes:\n    **Guarantees:**\n\n        - This configuration is intentionally explicit and immutable.\n        - No implicit environment reads or global state.\n        - Explicit configuration over implicit defaults.\n        - No direct environment or filesystem access.\n        - This model is safe to pass across layers and suitable for\n          serialization.",
             "members": {
               "provider": {
                 "name": "provider",
@@ -89,22 +89,22 @@
             "name": "MailIntakeAuthError",
             "kind": "class",
             "path": "mail_intake.exceptions.MailIntakeAuthError",
-            "signature": "<bound method Class.signature of Class('MailIntakeAuthError', 30, 38)>",
+            "signature": "<bound method Class.signature of Class('MailIntakeAuthError', 30, 39)>",
-            "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire, refresh, or persist valid credentials"
+            "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire,\n          refresh, or persist valid credentials."
           },
           "MailIntakeAdapterError": {
             "name": "MailIntakeAdapterError",
             "kind": "class",
             "path": "mail_intake.exceptions.MailIntakeAdapterError",
-            "signature": "<bound method Class.signature of Class('MailIntakeAdapterError', 41, 49)>",
+            "signature": "<bound method Class.signature of Class('MailIntakeAdapterError', 42, 51)>",
-            "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when a provider adapter encounters API errors, transport failures, or invalid provider responses"
+            "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when a provider adapter encounters API errors, transport\n          failures, or invalid provider responses."
           },
           "MailIntakeParsingError": {
             "name": "MailIntakeParsingError",
             "kind": "class",
             "path": "mail_intake.exceptions.MailIntakeParsingError",
-            "signature": "<bound method Class.signature of Class('MailIntakeParsingError', 52, 60)>",
+            "signature": "<bound method Class.signature of Class('MailIntakeParsingError', 54, 63)>",
-            "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or normalized into internal domain models"
+            "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
           }
         }
       },
@@ -113,21 +113,21 @@
         "kind": "module",
         "path": "mail_intake.adapters",
         "signature": null,
-        "docstring": "Mail provider adapter implementations for Mail Intake.\n\n---\n\n## Summary\n\nThis package contains **adapter-layer implementations** responsible for\ninterfacing with external mail providers and exposing a normalized,\nprovider-agnostic contract to the rest of the system.\n\nAdapters in this package:\n- Implement the `MailIntakeAdapter` interface\n- Encapsulate all provider-specific APIs and semantics\n- Perform read-only access to mail data\n- Return provider-native payloads without interpretation\n\nProvider-specific logic **must not leak** outside of adapter implementations.\nAll parsings, normalizations, and transformations must be handled by downstream\ncomponents.\n\n---\n\n## Public API\n\n    MailIntakeAdapter\n    MailIntakeGmailAdapter\n\n---",
+        "docstring": "# Summary\n\nMail provider adapter implementations for Mail Intake.\n\nThis package contains **adapter-layer implementations** responsible for\ninterfacing with external mail providers and exposing a normalized,\nprovider-agnostic contract to the rest of the system.\n\nAdapters in this package:\n\n- Implement the `MailIntakeAdapter` interface.\n- Encapsulate all provider-specific APIs and semantics.\n- Perform read-only access to mail data.\n- Return provider-native payloads without interpretation.\n\nProvider-specific logic **must not leak** outside of adapter implementations.\nAll parsings, normalizations, and transformations must be handled by downstream\ncomponents.\n\n---\n\n# Public API\n\n- `MailIntakeAdapter`\n- `MailIntakeGmailAdapter`\n\n---",
         "members": {
           "MailIntakeAdapter": {
             "name": "MailIntakeAdapter",
             "kind": "class",
             "path": "mail_intake.adapters.MailIntakeAdapter",
             "signature": "<bound method Alias.signature of Alias('MailIntakeAdapter', 'mail_intake.adapters.base.MailIntakeAdapter')>",
-            "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - discover messages matching a query\n        - retrieve full message payloads\n        - retrieve full thread payloads\n\n    **Lifecycle:**\n\n        - adapters are intentionally read-only and must not mutate provider state",
+            "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - Discover messages matching a query.\n        - Retrieve full message payloads.\n        - Retrieve full thread payloads.\n\n    **Lifecycle:**\n\n        - Adapters are intentionally read-only and must not mutate provider state.",
             "members": {
               "iter_message_refs": {
                 "name": "iter_message_refs",
                 "kind": "function",
                 "path": "mail_intake.adapters.MailIntakeAdapter.iter_message_refs",
                 "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
-                "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``\n\nExample:\n    Typical yield:\n\n        {\n            \"message_id\": \"...\",\n            \"thread_id\": \"...\"\n        }"
+                "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
               },
               "fetch_message": {
                 "name": "fetch_message",
@@ -150,7 +150,7 @@
             "kind": "class",
             "path": "mail_intake.adapters.MailIntakeGmailAdapter",
             "signature": "<bound method Alias.signature of Alias('MailIntakeGmailAdapter', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter')>",
-            "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the ONLY place where googleapiclient is imported\n        - Gmail REST semantics are known\n        - .execute() is called\n\n    **Constraints:**\n    \n        - Must remain thin and imperative\n        - Must not perform parsing or interpretation\n        - Must not expose Gmail-specific types beyond this class",
+            "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the ONLY place where `googleapiclient` is imported.\n        - Gmail REST semantics are known.\n        - `.execute()` is called.\n\n    **Constraints:**\n\n        - Must remain thin and imperative.\n        - Must not perform parsing or interpretation.\n        - Must not expose Gmail-specific types beyond this class.",
             "members": {
               "service": {
                 "name": "service",
@@ -187,7 +187,7 @@
             "kind": "module",
             "path": "mail_intake.adapters.base",
             "signature": null,
-            "docstring": "Mail provider adapter contracts for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.",
+            "docstring": "# Summary\n\nMail provider adapter contracts for Mail Intake.\n\nThis module defines the **provider-agnostic adapter interface** used for\nread-only mail ingestion.\n\nAdapters encapsulate all provider-specific access logic and expose a\nminimal, normalized contract to the rest of the system. No provider-specific\ntypes or semantics should leak beyond implementations of this interface.",
             "members": {
               "ABC": {
                 "name": "ABC",
@@ -228,28 +228,28 @@
                 "name": "MailIntakeAdapter",
                 "kind": "class",
                 "path": "mail_intake.adapters.base.MailIntakeAdapter",
-                "signature": "<bound method Class.signature of Class('MailIntakeAdapter', 20, 92)>",
+                "signature": "<bound method Class.signature of Class('MailIntakeAdapter', 18, 93)>",
-                "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - discover messages matching a query\n        - retrieve full message payloads\n        - retrieve full thread payloads\n\n    **Lifecycle:**\n\n        - adapters are intentionally read-only and must not mutate provider state",
+                "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - Discover messages matching a query.\n        - Retrieve full message payloads.\n        - Retrieve full thread payloads.\n\n    **Lifecycle:**\n\n        - Adapters are intentionally read-only and must not mutate provider state.",
                 "members": {
                   "iter_message_refs": {
                     "name": "iter_message_refs",
                     "kind": "function",
                     "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs",
-                    "signature": "<bound method Function.signature of Function('iter_message_refs', 36, 62)>",
+                    "signature": "<bound method Function.signature of Function('iter_message_refs', 34, 63)>",
-                    "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``\n\nExample:\n    Typical yield:\n\n        {\n            \"message_id\": \"...\",\n            \"thread_id\": \"...\"\n        }"
+                    "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
                   },
                   "fetch_message": {
                     "name": "fetch_message",
                     "kind": "function",
                     "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
-                    "signature": "<bound method Function.signature of Function('fetch_message', 64, 77)>",
+                    "signature": "<bound method Function.signature of Function('fetch_message', 65, 78)>",
                     "docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n    message_id (str):\n        Provider-specific message identifier.\n\nReturns:\n    Dict[str, Any]:\n        Provider-native message payload (e.g., Gmail message JSON structure)."
                   },
                   "fetch_thread": {
                     "name": "fetch_thread",
                     "kind": "function",
                     "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread",
-                    "signature": "<bound method Function.signature of Function('fetch_thread', 79, 92)>",
+                    "signature": "<bound method Function.signature of Function('fetch_thread', 80, 93)>",
                     "docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n    thread_id (str):\n        Provider-specific thread identifier.\n\nReturns:\n    Dict[str, Any]:\n        Provider-native thread payload."
                   }
                 }
@@ -261,7 +261,7 @@
             "kind": "module",
             "path": "mail_intake.adapters.gmail",
             "signature": null,
-            "docstring": "Gmail adapter implementation for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n- `googleapiclient` is imported\n- Gmail REST API semantics are known\n- Low-level `.execute()` calls are made\n\nAll Gmail-specific behavior must be strictly contained within this module.",
+            "docstring": "# Summary\n\nGmail adapter implementation for Mail Intake.\n\nThis module provides a **Gmail-specific implementation** of the\n`MailIntakeAdapter` contract.\n\nIt is the only place in the codebase where:\n\n- `googleapiclient` is imported.\n- Gmail REST API semantics are known.\n- Low-level `.execute()` calls are made.\n\nAll Gmail-specific behavior must be strictly contained within this module.",
             "members": {
               "Iterator": {
                 "name": "Iterator",
@@ -303,14 +303,14 @@
                 "kind": "class",
                 "path": "mail_intake.adapters.gmail.MailIntakeAdapter",
                 "signature": "<bound method Alias.signature of Alias('MailIntakeAdapter', 'mail_intake.adapters.base.MailIntakeAdapter')>",
-                "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - discover messages matching a query\n        - retrieve full message payloads\n        - retrieve full thread payloads\n\n    **Lifecycle:**\n\n        - adapters are intentionally read-only and must not mutate provider state",
+                "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - Discover messages matching a query.\n        - Retrieve full message payloads.\n        - Retrieve full thread payloads.\n\n    **Lifecycle:**\n\n        - Adapters are intentionally read-only and must not mutate provider state.",
                 "members": {
                   "iter_message_refs": {
                     "name": "iter_message_refs",
                     "kind": "function",
                     "path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs",
                     "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
-                    "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``\n\nExample:\n    Typical yield:\n\n        {\n            \"message_id\": \"...\",\n            \"thread_id\": \"...\"\n        }"
+                    "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
                   },
                   "fetch_message": {
                     "name": "fetch_message",
@@ -333,21 +333,21 @@
                 "kind": "class",
                 "path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
                 "signature": "<bound method Alias.signature of Alias('MailIntakeAdapterError', 'mail_intake.exceptions.MailIntakeAdapterError')>",
-                "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when a provider adapter encounters API errors, transport failures, or invalid provider responses"
+                "docstring": "Errors raised by mail provider adapters.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when a provider adapter encounters API errors, transport\n          failures, or invalid provider responses."
               },
               "MailIntakeAuthProvider": {
                 "name": "MailIntakeAuthProvider",
                 "kind": "class",
                 "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider",
                 "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
-                "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider\n        - Refresh or revalidate credentials as needed\n        - Handle authentication-specific failure modes\n        - Coordinate with credential persistence layers where applicable\n\n    **Constraints:**\n    \n        - Mail adapters must treat returned credentials as opaque and provider-specific\n        - Mail adapters rely only on the declared credential type expected by the adapter",
+                "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
                 "members": {
                   "get_credentials": {
                     "name": "get_credentials",
                     "kind": "function",
                     "path": "mail_intake.adapters.gmail.MailIntakeAuthProvider.get_credentials",
                     "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
-                    "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type ``T`` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design\n        - Represents the sole entry point through which adapters obtain authentication material\n        - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception"
+                    "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
                   }
                 }
               },
@@ -355,8 +355,8 @@
                 "name": "MailIntakeGmailAdapter",
                 "kind": "class",
                 "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter",
-                "signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 29, 190)>",
+                "signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 28, 189)>",
-                "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the ONLY place where googleapiclient is imported\n        - Gmail REST semantics are known\n        - .execute() is called\n\n    **Constraints:**\n    \n        - Must remain thin and imperative\n        - Must not perform parsing or interpretation\n        - Must not expose Gmail-specific types beyond this class",
+                "docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the ONLY place where `googleapiclient` is imported.\n        - Gmail REST semantics are known.\n        - `.execute()` is called.\n\n    **Constraints:**\n\n        - Must remain thin and imperative.\n        - Must not perform parsing or interpretation.\n        - Must not expose Gmail-specific types beyond this class.",
                 "members": {
                   "service": {
                     "name": "service",
@@ -369,21 +369,21 @@
                     "name": "iter_message_refs",
                     "kind": "function",
                     "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
-                    "signature": "<bound method Function.signature of Function('iter_message_refs', 93, 134)>",
+                    "signature": "<bound method Function.signature of Function('iter_message_refs', 92, 133)>",
                     "docstring": "Iterate over message references matching the query.\n\nArgs:\n    query (str):\n        Gmail search query string.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail API returns an error."
                   },
                   "fetch_message": {
                     "name": "fetch_message",
                     "kind": "function",
                     "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message",
-                    "signature": "<bound method Function.signature of Function('fetch_message', 136, 162)>",
+                    "signature": "<bound method Function.signature of Function('fetch_message', 135, 161)>",
                     "docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n    message_id (str):\n        Gmail message identifier.\n\nReturns:\n    Dict[str, Any]:\n        Provider-native Gmail message payload.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail API returns an error."
                   },
                   "fetch_thread": {
                     "name": "fetch_thread",
                     "kind": "function",
                     "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread",
-                    "signature": "<bound method Function.signature of Function('fetch_thread', 164, 190)>",
+                    "signature": "<bound method Function.signature of Function('fetch_thread', 163, 189)>",
                     "docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n    thread_id (str):\n        Gmail thread identifier.\n\nReturns:\n    Dict[str, Any]:\n        Provider-native Gmail thread payload.\n\nRaises:\n    MailIntakeAdapterError:\n        If the Gmail API returns an error."
                   }
                 }
@@ -397,21 +397,21 @@
         "kind": "module",
         "path": "mail_intake.auth",
         "signature": null,
-        "docstring": "Authentication provider implementations for Mail Intake.\n\n---\n\n## Summary\n\nThis package defines the **authentication layer** used by mail adapters\nto obtain provider-specific credentials.\n\nIt exposes:\n- A stable, provider-agnostic authentication contract\n- Concrete authentication providers for supported platforms\n\nAuthentication providers:\n- Are responsible for credential acquisition and lifecycle management\n- Are intentionally decoupled from adapter logic\n- May be extended by users to support additional providers\n\nConsumers should depend on the abstract interface and use concrete\nimplementations only where explicitly required.\n\n---\n\n## Public API\n\n    MailIntakeAuthProvider\n    MailIntakeGoogleAuth\n\n---",
+        "docstring": "# Summary\n\nAuthentication provider implementations for Mail Intake.\n\nThis package defines the **authentication layer** used by mail adapters\nto obtain provider-specific credentials.\n\nIt exposes:\n\n- A stable, provider-agnostic authentication contract.\n- Concrete authentication providers for supported platforms.\n\nAuthentication providers:\n\n- Are responsible for credential acquisition and lifecycle management.\n- Are intentionally decoupled from adapter logic.\n- May be extended by users to support additional providers.\n\nConsumers should depend on the abstract interface and use concrete\nimplementations only where explicitly required.\n\n---\n\n# Public API\n\n- `MailIntakeAuthProvider`\n- `MailIntakeGoogleAuth`\n\n---",
         "members": {
           "MailIntakeAuthProvider": {
             "name": "MailIntakeAuthProvider",
             "kind": "class",
             "path": "mail_intake.auth.MailIntakeAuthProvider",
             "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
-            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider\n        - Refresh or revalidate credentials as needed\n        - Handle authentication-specific failure modes\n        - Coordinate with credential persistence layers where applicable\n\n    **Constraints:**\n    \n        - Mail adapters must treat returned credentials as opaque and provider-specific\n        - Mail adapters rely only on the declared credential type expected by the adapter",
+            "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
             "members": {
               "get_credentials": {
                 "name": "get_credentials",
                 "kind": "function",
                 "path": "mail_intake.auth.MailIntakeAuthProvider.get_credentials",
                 "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
-                "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type ``T`` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design\n        - Represents the sole entry point through which adapters obtain authentication material\n        - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception"
+                "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
               }
             }
           },
@@ -420,7 +420,7 @@
             "kind": "class",
             "path": "mail_intake.auth.MailIntakeGoogleAuth",
             "signature": "<bound method Alias.signature of Alias('MailIntakeGoogleAuth', 'mail_intake.auth.google.MailIntakeGoogleAuth')>",
-            "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available\n        - Refresh expired credentials when possible\n        - Initiate an interactive OAuth flow only when required\n        - Persist refreshed or newly obtained credentials via the store\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal internal state",
+            "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available.\n        - Refresh expired credentials when possible.\n        - Initiate an interactive OAuth flow only when required.\n        - Persist refreshed or newly obtained credentials via the store.\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal\n          internal state.",
             "members": {
               "credentials_path": {
                 "name": "credentials_path",
@@ -448,7 +448,7 @@
                 "kind": "function",
                 "path": "mail_intake.auth.MailIntakeGoogleAuth.get_credentials",
                 "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials')>",
-                "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A ``google.oauth2.credentials.Credentials`` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store\n        - Refresh expired credentials when possible\n        - Perform an interactive OAuth login as a fallback\n        - Persist valid credentials for future use"
+                "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A `google.oauth2.credentials.Credentials` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store.\n        - Refresh expired credentials when possible.\n        - Perform an interactive OAuth login as a fallback.\n        - Persist valid credentials for future use."
               }
             }
           },
@@ -457,7 +457,7 @@
             "kind": "module",
             "path": "mail_intake.auth.base",
             "signature": null,
-            "docstring": "Authentication provider contracts for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.",
+            "docstring": "# Summary\n\nAuthentication provider contracts for Mail Intake.\n\nThis module defines the **authentication abstraction layer** used by mail\nadapters to obtain provider-specific credentials.\n\nAuthentication concerns are intentionally decoupled from adapter logic.\nAdapters depend only on this interface and must not be aware of how\ncredentials are acquired, refreshed, or persisted.",
             "members": {
               "ABC": {
                 "name": "ABC",
@@ -498,15 +498,15 @@
                 "name": "MailIntakeAuthProvider",
                 "kind": "class",
                 "path": "mail_intake.auth.base.MailIntakeAuthProvider",
-                "signature": "<bound method Class.signature of Class('MailIntakeAuthProvider', 22, 66)>",
+                "signature": "<bound method Class.signature of Class('MailIntakeAuthProvider', 20, 68)>",
-                "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider\n        - Refresh or revalidate credentials as needed\n        - Handle authentication-specific failure modes\n        - Coordinate with credential persistence layers where applicable\n\n    **Constraints:**\n    \n        - Mail adapters must treat returned credentials as opaque and provider-specific\n        - Mail adapters rely only on the declared credential type expected by the adapter",
+                "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
                 "members": {
                   "get_credentials": {
                     "name": "get_credentials",
                     "kind": "function",
                     "path": "mail_intake.auth.base.MailIntakeAuthProvider.get_credentials",
-                    "signature": "<bound method Function.signature of Function('get_credentials', 44, 66)>",
+                    "signature": "<bound method Function.signature of Function('get_credentials', 44, 68)>",
-                    "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type ``T`` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design\n        - Represents the sole entry point through which adapters obtain authentication material\n        - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception"
+                    "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
                   }
                 }
               }
@@ -517,7 +517,7 @@
             "kind": "module",
             "path": "mail_intake.auth.google",
             "signature": null,
-            "docstring": "Google authentication provider implementation for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n- Credential loading and persistence\n- Token refresh handling\n- Interactive OAuth flow initiation\n- Coordination with a credential persistence layer\n\nNo Google authentication details should leak outside this module.",
+            "docstring": "# Summary\n\nGoogle authentication provider implementation for Mail Intake.\n\nThis module provides a **Google OAuth–based authentication provider**\nused primarily for Gmail access.\n\nIt encapsulates all Google-specific authentication concerns, including:\n\n- Credential loading and persistence.\n- Token refresh handling.\n- Interactive OAuth flow initiation.\n- Coordination with a credential persistence layer.\n\nNo Google authentication details should leak outside this module.",
             "members": {
               "os": {
                 "name": "os",
@@ -566,14 +566,14 @@
                 "kind": "class",
                 "path": "mail_intake.auth.google.MailIntakeAuthProvider",
                 "signature": "<bound method Alias.signature of Alias('MailIntakeAuthProvider', 'mail_intake.auth.base.MailIntakeAuthProvider')>",
-                "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider\n        - Refresh or revalidate credentials as needed\n        - Handle authentication-specific failure modes\n        - Coordinate with credential persistence layers where applicable\n\n    **Constraints:**\n    \n        - Mail adapters must treat returned credentials as opaque and provider-specific\n        - Mail adapters rely only on the declared credential type expected by the adapter",
+                "docstring": "Abstract base class for authentication providers.\n\nThis interface enforces a strict contract between authentication\nproviders and mail adapters by requiring providers to explicitly\ndeclare the type of credentials they return.\n\nNotes:\n    **Responsibilities:**\n\n        - Acquire credentials from an external provider.\n        - Refresh or revalidate credentials as needed.\n        - Handle authentication-specific failure modes.\n        - Coordinate with credential persistence layers where applicable.\n\n    **Constraints:**\n\n        - Mail adapters must treat returned credentials as opaque and\n          provider-specific.\n        - Mail adapters rely only on the declared credential type expected\n          by the adapter.",
                 "members": {
                   "get_credentials": {
                     "name": "get_credentials",
                     "kind": "function",
                     "path": "mail_intake.auth.google.MailIntakeAuthProvider.get_credentials",
                     "signature": "<bound method Alias.signature of Alias('get_credentials', 'mail_intake.auth.base.MailIntakeAuthProvider.get_credentials')>",
-                    "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type ``T`` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design\n        - Represents the sole entry point through which adapters obtain authentication material\n        - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception"
+                    "docstring": "Retrieve valid, provider-specific credentials.\n\nReturns:\n    T:\n        Credentials of type `T` suitable for immediate use by the\n        corresponding mail adapter.\n\nRaises:\n    Exception:\n        An authentication-specific exception indicating that\n        credentials could not be obtained or validated.\n\nNotes:\n    **Guarantees:**\n\n        - This method is synchronous by design.\n        - Represents the sole entry point through which adapters obtain\n          authentication material.\n        - Implementations must either return credentials of the declared\n          type `T` that are valid at the time of return or raise an exception."
                   }
                 }
               },
@@ -582,14 +582,14 @@
                 "kind": "class",
                 "path": "mail_intake.auth.google.CredentialStore",
                 "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
-                "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+                "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
                 "members": {
                   "load": {
                     "name": "load",
                     "kind": "function",
                     "path": "mail_intake.auth.google.CredentialStore.load",
                     "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
-                    "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+                    "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
                   },
                   "save": {
                     "name": "save",
@@ -612,14 +612,14 @@
                 "kind": "class",
                 "path": "mail_intake.auth.google.MailIntakeAuthError",
                 "signature": "<bound method Alias.signature of Alias('MailIntakeAuthError', 'mail_intake.exceptions.MailIntakeAuthError')>",
-                "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire, refresh, or persist valid credentials"
+                "docstring": "Authentication and credential-related failures.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when authentication providers are unable to acquire,\n          refresh, or persist valid credentials."
               },
               "MailIntakeGoogleAuth": {
                 "name": "MailIntakeGoogleAuth",
                 "kind": "class",
                 "path": "mail_intake.auth.google.MailIntakeGoogleAuth",
-                "signature": "<bound method Class.signature of Class('MailIntakeGoogleAuth', 33, 135)>",
+                "signature": "<bound method Class.signature of Class('MailIntakeGoogleAuth', 32, 135)>",
-                "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available\n        - Refresh expired credentials when possible\n        - Initiate an interactive OAuth flow only when required\n        - Persist refreshed or newly obtained credentials via the store\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal internal state",
+                "docstring": "Google OAuth provider for Gmail access.\n\nThis provider implements the `MailIntakeAuthProvider` interface using\nGoogle's OAuth 2.0 flow and credential management libraries.\n\nNotes:\n    **Responsibilities:**\n\n        - Load cached credentials from a credential store when available.\n        - Refresh expired credentials when possible.\n        - Initiate an interactive OAuth flow only when required.\n        - Persist refreshed or newly obtained credentials via the store.\n\n    **Guarantees:**\n\n        - This class is synchronous by design and maintains a minimal\n          internal state.",
                 "members": {
                   "credentials_path": {
                     "name": "credentials_path",
@@ -647,7 +647,7 @@
                     "kind": "function",
                     "path": "mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials",
                     "signature": "<bound method Function.signature of Function('get_credentials', 76, 135)>",
-                    "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A ``google.oauth2.credentials.Credentials`` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store\n        - Refresh expired credentials when possible\n        - Perform an interactive OAuth login as a fallback\n        - Persist valid credentials for future use"
+                    "docstring": "Retrieve valid Google OAuth credentials.\n\nReturns:\n    Credentials:\n        A `google.oauth2.credentials.Credentials` instance suitable\n        for use with Google API clients.\n\nRaises:\n    MailIntakeAuthError:\n        If credentials cannot be loaded, refreshed,\n        or obtained via interactive authentication.\n\nNotes:\n    **Lifecycle:**\n\n        - Load cached credentials from the configured credential store.\n        - Refresh expired credentials when possible.\n        - Perform an interactive OAuth login as a fallback.\n        - Persist valid credentials for future use."
                   }
                 }
               },
@@ -667,21 +667,21 @@
         "kind": "module",
         "path": "mail_intake.credentials",
         "signature": null,
-        "docstring": "Credential persistence interfaces and implementations for Mail Intake.\n\n---\n\n## Summary\n\nThis package defines the abstractions and concrete implementations used\nto persist authentication credentials across Mail Intake components.\n\nThe credential persistence layer is intentionally decoupled from\nauthentication logic. Authentication providers are responsible for\ncredential acquisition, validation, and refresh, while implementations\nwithin this package are responsible solely for storage and retrieval.\n\nThe package provides:\n- A generic ``CredentialStore`` abstraction defining the persistence contract\n- Local filesystem–based storage for development and single-node use\n- Distributed, Redis-backed storage for production and scaled deployments\n\nCredential lifecycle management, interpretation, and security policy\ndecisions remain the responsibility of authentication providers.\n\n---\n\n## Public API\n\n    CredentialStore\n    PickleCredentialStore\n    RedisCredentialStore\n\n---",
+        "docstring": "# Summary\n\nCredential persistence interfaces and implementations for Mail Intake.\n\nThis package defines the abstractions and concrete implementations used\nto persist authentication credentials across Mail Intake components.\n\nThe credential persistence layer is intentionally decoupled from\nauthentication logic. Authentication providers are responsible for\ncredential acquisition, validation, and refresh, while implementations\nwithin this package are responsible solely for storage and retrieval.\n\nThe package provides:\n\n- A generic `CredentialStore` abstraction defining the persistence contract.\n- Local filesystem–based storage for development and single-node use.\n- Distributed, Redis-backed storage for production and scaled deployments.\n\nCredential lifecycle management, interpretation, and security policy\ndecisions remain the responsibility of authentication providers.\n\n---\n\n# Public API\n\n- `CredentialStore`\n- `PickleCredentialStore`\n- `RedisCredentialStore`\n\n---",
         "members": {
           "CredentialStore": {
             "name": "CredentialStore",
             "kind": "class",
             "path": "mail_intake.credentials.CredentialStore",
             "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
-            "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+            "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
             "members": {
               "load": {
                 "name": "load",
                 "kind": "function",
                 "path": "mail_intake.credentials.CredentialStore.load",
                 "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
-                "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+                "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
               },
               "save": {
                 "name": "save",
@@ -704,7 +704,7 @@
             "kind": "class",
             "path": "mail_intake.credentials.PickleCredentialStore",
             "signature": "<bound method Alias.signature of Alias('PickleCredentialStore', 'mail_intake.credentials.pickle.PickleCredentialStore')>",
-            "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem\n        - Uses pickle for serialization and deserialization\n        - Does not provide encryption, locking, or concurrency guarantees\n\n    **Constraints:**\n    \n        - Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class",
+            "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem.\n        - Uses `pickle` for serialization and deserialization.\n        - Does not provide encryption, locking, or concurrency guarantees.\n\n    **Constraints:**\n\n        - Credential lifecycle management, validation, and refresh logic are\n          explicitly out of scope for this class.",
             "members": {
               "path": {
                 "name": "path",
@@ -718,7 +718,7 @@
                 "kind": "function",
                 "path": "mail_intake.credentials.PickleCredentialStore.load",
                 "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.pickle.PickleCredentialStore.load')>",
-                "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are present and\n        successfully deserialized; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``\n        - The store does not attempt to validate or interpret the returned credentials"
+                "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully\n          deserialized, this method returns `None`.\n        - The store does not attempt to validate or interpret the\n          returned credentials."
               },
               "save": {
                 "name": "save",
@@ -741,7 +741,7 @@
             "kind": "class",
             "path": "mail_intake.credentials.RedisCredentialStore",
             "signature": "<bound method Alias.signature of Alias('RedisCredentialStore', 'mail_intake.credentials.redis.RedisCredentialStore')>",
-            "docstring": "Redis-backed implementation of ``CredentialStore``.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval\n        - It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization concerns to caller-provided functions\n        - This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited",
+            "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval.\n        - It does not interpret, validate, refresh, or otherwise manage the\n          lifecycle of the credentials being stored.\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization\n          concerns to caller-provided functions.\n        - This avoids unsafe mechanisms such as `pickle` and allows\n          credential formats to be explicitly controlled and audited.",
             "members": {
               "redis": {
                 "name": "redis",
@@ -783,7 +783,7 @@
                 "kind": "function",
                 "path": "mail_intake.credentials.RedisCredentialStore.load",
                 "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.redis.RedisCredentialStore.load')>",
-                "docstring": "Load credentials from Redis.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are present and\n        successfully deserialized; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``\n        - The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable"
+                "docstring": "Load credentials from Redis.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored\n          payload cannot be successfully deserialized, this method\n          returns `None`.\n        - The store does not attempt to validate the returned\n          credentials or determine whether they are expired or\n          otherwise usable."
               },
               "save": {
                 "name": "save",
@@ -806,7 +806,7 @@
             "kind": "module",
             "path": "mail_intake.credentials.pickle",
             "signature": null,
-            "docstring": "Local filesystem–based credential persistence for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a file-backed implementation of the\n``CredentialStore`` abstraction using Python's ``pickle`` module.\n\nThe pickle-based credential store is intended for local development,\nsingle-node deployments, and controlled environments where credentials\ndo not need to be shared across processes or machines.\n\nDue to the security and portability risks associated with pickle-based\nserialization, this implementation is not suitable for distributed or\nuntrusted environments.",
+            "docstring": "# Summary\n\nLocal filesystem–based credential persistence for Mail Intake.\n\nThis module provides a file-backed implementation of the\n`CredentialStore` abstraction using Python's `pickle` module.\n\nThe `pickle`-based credential store is intended for local development,\nsingle-node deployments, and controlled environments where credentials\ndo not need to be shared across processes or machines.\n\nDue to the security and portability risks associated with `pickle`-based\nserialization, this implementation is not suitable for distributed or\nuntrusted environments.",
             "members": {
               "pickle": {
                 "name": "pickle",
@@ -834,14 +834,14 @@
                 "kind": "class",
                 "path": "mail_intake.credentials.pickle.CredentialStore",
                 "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
-                "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+                "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
                 "members": {
                   "load": {
                     "name": "load",
                     "kind": "function",
                     "path": "mail_intake.credentials.pickle.CredentialStore.load",
                     "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
-                    "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+                    "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
                   },
                   "save": {
                     "name": "save",
@@ -870,8 +870,8 @@
                 "name": "PickleCredentialStore",
                 "kind": "class",
                 "path": "mail_intake.credentials.pickle.PickleCredentialStore",
-                "signature": "<bound method Class.signature of Class('PickleCredentialStore', 28, 108)>",
+                "signature": "<bound method Class.signature of Class('PickleCredentialStore', 26, 109)>",
-                "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem\n        - Uses pickle for serialization and deserialization\n        - Does not provide encryption, locking, or concurrency guarantees\n\n    **Constraints:**\n    \n        - Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class",
+                "docstring": "Filesystem-backed credential store using pickle serialization.\n\nThis store persists credentials as a pickled object on the local\nfilesystem. It is a simple implementation intended primarily for\ndevelopment, testing, and single-process execution contexts.\n\nNotes:\n    **Guarantees:**\n\n        - Stores credentials on the local filesystem.\n        - Uses `pickle` for serialization and deserialization.\n        - Does not provide encryption, locking, or concurrency guarantees.\n\n    **Constraints:**\n\n        - Credential lifecycle management, validation, and refresh logic are\n          explicitly out of scope for this class.",
                 "members": {
                   "path": {
                     "name": "path",
@@ -884,21 +884,21 @@
                     "name": "load",
                     "kind": "function",
                     "path": "mail_intake.credentials.pickle.PickleCredentialStore.load",
-                    "signature": "<bound method Function.signature of Function('load', 59, 78)>",
+                    "signature": "<bound method Function.signature of Function('load', 58, 79)>",
-                    "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are present and\n        successfully deserialized; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``\n        - The store does not attempt to validate or interpret the returned credentials"
+                    "docstring": "Load credentials from the local filesystem.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If the credential file does not exist or cannot be successfully\n          deserialized, this method returns `None`.\n        - The store does not attempt to validate or interpret the\n          returned credentials."
                   },
                   "save": {
                     "name": "save",
                     "kind": "function",
                     "path": "mail_intake.credentials.pickle.PickleCredentialStore.save",
-                    "signature": "<bound method Function.signature of Function('save', 80, 94)>",
+                    "signature": "<bound method Function.signature of Function('save', 81, 95)>",
                     "docstring": "Persist credentials to the local filesystem.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials at the configured path are overwritten"
                   },
                   "clear": {
                     "name": "clear",
                     "kind": "function",
                     "path": "mail_intake.credentials.pickle.PickleCredentialStore.clear",
-                    "signature": "<bound method Function.signature of Function('clear', 96, 108)>",
+                    "signature": "<bound method Function.signature of Function('clear', 97, 109)>",
                     "docstring": "Remove persisted credentials from the local filesystem.\n\nNotes:\n    **Lifecycle:**\n\n        - This method deletes the credential file if it exists and should be treated as an idempotent operation"
                   }
                 }
@@ -910,7 +910,7 @@
             "kind": "module",
             "path": "mail_intake.credentials.redis",
             "signature": null,
-            "docstring": "Redis-backed credential persistence for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides a Redis-based implementation of the\n``CredentialStore`` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n- Distributed-safe, shared storage using Redis\n- Explicit, caller-defined serialization and deserialization\n- No reliance on unsafe mechanisms such as pickle\n- Optional time-to-live (TTL) support for automatic credential expiry\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.",
+            "docstring": "# Summary\n\nRedis-backed credential persistence for Mail Intake.\n\nThis module provides a Redis-based implementation of the\n`CredentialStore` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n\n- Distributed-safe, shared storage using Redis.\n- Explicit, caller-defined serialization and deserialization.\n- No reliance on unsafe mechanisms such as `pickle`.\n- Optional time-to-live (TTL) support for automatic credential expiry.\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.",
             "members": {
               "Optional": {
                 "name": "Optional",
@@ -938,14 +938,14 @@
                 "kind": "class",
                 "path": "mail_intake.credentials.redis.CredentialStore",
                 "signature": "<bound method Alias.signature of Alias('CredentialStore', 'mail_intake.credentials.store.CredentialStore')>",
-                "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+                "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
                 "members": {
                   "load": {
                     "name": "load",
                     "kind": "function",
                     "path": "mail_intake.credentials.redis.CredentialStore.load",
                     "signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
-                    "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+                    "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
                   },
                   "save": {
                     "name": "save",
@@ -974,8 +974,8 @@
                 "name": "RedisCredentialStore",
                 "kind": "class",
                 "path": "mail_intake.credentials.redis.RedisCredentialStore",
-                "signature": "<bound method Class.signature of Class('RedisCredentialStore', 36, 142)>",
+                "signature": "<bound method Class.signature of Class('RedisCredentialStore', 35, 148)>",
-                "docstring": "Redis-backed implementation of ``CredentialStore``.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval\n        - It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization concerns to caller-provided functions\n        - This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited",
+                "docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is responsible only for persistence and retrieval.\n        - It does not interpret, validate, refresh, or otherwise manage the\n          lifecycle of the credentials being stored.\n\n    **Guarantees:**\n\n        - The store is intentionally generic and delegates all serialization\n          concerns to caller-provided functions.\n        - This avoids unsafe mechanisms such as `pickle` and allows\n          credential formats to be explicitly controlled and audited.",
                 "members": {
                   "redis": {
                     "name": "redis",
@@ -1016,21 +1016,21 @@
                     "name": "load",
                     "kind": "function",
                     "path": "mail_intake.credentials.redis.RedisCredentialStore.load",
-                    "signature": "<bound method Function.signature of Function('load', 89, 110)>",
+                    "signature": "<bound method Function.signature of Function('load', 91, 116)>",
-                    "docstring": "Load credentials from Redis.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are present and\n        successfully deserialized; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``\n        - The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable"
+                    "docstring": "Load credentials from Redis.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are present and\n        successfully deserialized; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - If no value exists for the configured key, or if the stored\n          payload cannot be successfully deserialized, this method\n          returns `None`.\n        - The store does not attempt to validate the returned\n          credentials or determine whether they are expired or\n          otherwise usable."
                   },
                   "save": {
                     "name": "save",
                     "kind": "function",
                     "path": "mail_intake.credentials.redis.RedisCredentialStore.save",
-                    "signature": "<bound method Function.signature of Function('save', 112, 130)>",
+                    "signature": "<bound method Function.signature of Function('save', 118, 136)>",
                     "docstring": "Persist credentials to Redis.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Responsibilities:**\n\n        - Any previously stored credentials under the same key are overwritten\n        - If a TTL is configured, the credentials will expire automatically after the specified duration"
                   },
                   "clear": {
                     "name": "clear",
                     "kind": "function",
                     "path": "mail_intake.credentials.redis.RedisCredentialStore.clear",
-                    "signature": "<bound method Function.signature of Function('clear', 132, 142)>",
+                    "signature": "<bound method Function.signature of Function('clear', 138, 148)>",
                     "docstring": "Remove stored credentials from Redis.\n\nNotes:\n    **Lifecycle:**\n\n        - This operation deletes the configured Redis key if it exists\n        - Implementations should treat this method as idempotent"
                   }
                 }
@@ -1049,7 +1049,7 @@
             "kind": "module",
             "path": "mail_intake.credentials.store",
             "signature": null,
-            "docstring": "Credential persistence abstractions for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the generic persistence contract used to store and\nretrieve authentication credentials across Mail Intake components.\n\nThe ``CredentialStore`` abstraction establishes a strict separation\nbetween credential *lifecycle management* and credential *storage*.\nAuthentication providers are responsible for acquiring, validating,\nrefreshing, and revoking credentials, while concrete store\nimplementations are responsible solely for persistence concerns.\n\nBy remaining agnostic to credential structure, serialization format,\nand storage backend, this module enables multiple persistence\nstrategies—such as local files, in-memory caches, distributed stores,\nor secrets managers—without coupling authentication logic to any\nspecific storage mechanism.",
+            "docstring": "# Summary\n\nCredential persistence abstractions for Mail Intake.\n\nThis module defines the generic persistence contract used to store and\nretrieve authentication credentials across Mail Intake components.\n\nThe `CredentialStore` abstraction establishes a strict separation\nbetween credential *lifecycle management* and credential *storage*.\nAuthentication providers are responsible for acquiring, validating,\nrefreshing, and revoking credentials, while concrete store\nimplementations are responsible solely for persistence concerns.\n\nBy remaining agnostic to credential structure, serialization format,\nand storage backend, this module enables multiple persistence\nstrategies—such as local files, in-memory caches, distributed stores,\nor secrets managers—without coupling authentication logic to any\nspecific storage mechanism.",
             "members": {
               "ABC": {
                 "name": "ABC",
@@ -1097,28 +1097,28 @@
                 "name": "CredentialStore",
                 "kind": "class",
                 "path": "mail_intake.credentials.store.CredentialStore",
-                "signature": "<bound method Class.signature of Class('CredentialStore', 31, 102)>",
+                "signature": "<bound method Class.signature of Class('CredentialStore', 29, 105)>",
-                "docstring": "Abstract base class defining a generic persistence interface for\nauthentication credentials.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from storage mechanics\n        - Keep implementation focused only on persistence\n        \n    **Constraints:**\n    \n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored\n            - The serialization format used to persist credentials\n            - The underlying storage backend or durability guarantees",
+                "docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n    **Responsibilities:**\n\n        - Provide persistent storage separating life-cycle management from\n          storage mechanics.\n        - Keep implementation focused only on persistence.\n\n    **Constraints:**\n\n        - The store is intentionally agnostic to:\n            - The concrete credential type being stored.\n            - The serialization format used to persist credentials.\n            - The underlying storage backend or durability guarantees.",
                 "members": {
                   "load": {
                     "name": "load",
                     "kind": "function",
                     "path": "mail_intake.credentials.store.CredentialStore.load",
-                    "signature": "<bound method Function.signature of Function('load', 50, 65)>",
+                    "signature": "<bound method Function.signature of Function('load', 50, 68)>",
-                    "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type ``T`` if credentials are available and\n        loadable; otherwise ``None``.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n        - The store must not attempt to validate, refresh, or otherwise interpret the returned credentials"
+                    "docstring": "Load previously persisted credentials.\n\nReturns:\n    Optional[T]:\n        An instance of type `T` if credentials are available and\n        loadable; otherwise `None`.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations should return `None` when no credentials are\n          present or when stored credentials cannot be successfully\n          decoded or deserialized.\n        - The store must not attempt to validate, refresh, or otherwise\n          interpret the returned credentials."
                   },
                   "save": {
                     "name": "save",
                     "kind": "function",
                     "path": "mail_intake.credentials.store.CredentialStore.save",
-                    "signature": "<bound method Function.signature of Function('save', 67, 86)>",
+                    "signature": "<bound method Function.signature of Function('save', 70, 89)>",
                     "docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n    credentials (T):\n        The credential object to persist.\n\nNotes:\n    **Lifecycle:**\n\n        - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n    **Responsibilities:**\n\n        - Ensuring durability appropriate to the deployment context\n        - Applying encryption or access controls where required\n        - Overwriting any previously stored credentials"
                   },
                   "clear": {
                     "name": "clear",
                     "kind": "function",
                     "path": "mail_intake.credentials.store.CredentialStore.clear",
-                    "signature": "<bound method Function.signature of Function('clear', 88, 102)>",
+                    "signature": "<bound method Function.signature of Function('clear', 91, 105)>",
                     "docstring": "Remove any persisted credentials from the store.\n\nNotes:\n    **Lifecycle:**\n\n        - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n        - Must ensure that no stale authentication material remains accessible\n\n    **Guarantees:**\n\n        - Implementations should treat this operation as idempotent"
                   }
                 }
@@ -1132,14 +1132,14 @@
         "kind": "module",
         "path": "mail_intake.ingestion",
         "signature": null,
-        "docstring": "Mail ingestion orchestration for Mail Intake.\n\n---\n\n## Summary\n\nThis package contains **high-level ingestion components** responsible for\ncoordinating mail retrieval, parsing, normalization, and model construction.\n\nIt represents the **top of the ingestion pipeline** and is intended to be the\nprimary interaction surface for library consumers.\n\nComponents in this package:\n- Are provider-agnostic\n- Depend only on adapter and parser contracts\n- Contain no provider-specific API logic\n- Expose read-only ingestion workflows\n\nConsumers are expected to construct a mail adapter and pass it to the\ningestion layer to begin processing messages and threads.\n\n---\n\n## Public API\n\n    MailIntakeReader\n\n---",
+        "docstring": "# Summary\n\nMail ingestion orchestration for Mail Intake.\n\nThis package contains **high-level ingestion components** responsible for\ncoordinating mail retrieval, parsing, normalization, and model construction.\n\nIt represents the **top of the ingestion pipeline** and is intended to be the\nprimary interaction surface for library consumers.\n\nComponents in this package:\n\n- Are provider-agnostic.\n- Depend only on adapter and parser contracts.\n- Contain no provider-specific API logic.\n- Expose read-only ingestion workflows.\n\nConsumers are expected to construct a mail adapter and pass it to the\ningestion layer to begin processing messages and threads.\n\n---\n\n# Public API\n\n- `MailIntakeReader`\n\n---",
         "members": {
           "MailIntakeReader": {
             "name": "MailIntakeReader",
             "kind": "class",
             "path": "mail_intake.ingestion.MailIntakeReader",
             "signature": "<bound method Alias.signature of Alias('MailIntakeReader', 'mail_intake.ingestion.reader.MailIntakeReader')>",
-            "docstring": "High-level read-only ingestion interface.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the primary entry point for consumers of the Mail Intake library\n        - It orchestrates the full ingestion pipeline: Querying the adapter for message references, fetching raw provider messages, parsing and normalizing message data, constructing domain models\n\n    **Constraints:**\n    \n        - This class is intentionally: Provider-agnostic, stateless beyond iteration scope, read-only",
+            "docstring": "High-level read-only ingestion interface.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the primary entry point for consumers of the\n          Mail Intake library.\n        - It orchestrates the full ingestion pipeline:\n            - Querying the adapter for message references.\n            - Fetching raw provider messages.\n            - Parsing and normalizing message data.\n            - Constructing domain models.\n\n    **Constraints:**\n\n        - This class is intentionally: Provider-agnostic, stateless beyond\n          iteration scope, read-only.",
             "members": {
               "iter_messages": {
                 "name": "iter_messages",
@@ -1153,7 +1153,7 @@
                 "kind": "function",
                 "path": "mail_intake.ingestion.MailIntakeReader.iter_threads",
                 "signature": "<bound method Alias.signature of Alias('iter_threads', 'mail_intake.ingestion.reader.MailIntakeReader.iter_threads')>",
-                "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeThread:\n        An iterator of `MailIntakeThread` instances.\n\nRaises:\n    MailIntakeParsingError:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages"
+                "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeThread:\n        An iterator of `MailIntakeThread` instances.\n\nRaises:\n    `MailIntakeParsingError`:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete\n          thread objects containing all associated messages."
               }
             }
           },
@@ -1162,7 +1162,7 @@
             "kind": "module",
             "path": "mail_intake.ingestion.reader",
             "signature": null,
-            "docstring": "High-level mail ingestion orchestration for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n- Mail adapter access\n- Message and thread iteration\n- Header and body parsing\n- Normalization and model construction\n\nNo provider-specific logic or API semantics are permitted in this layer.",
+            "docstring": "# Summary\n\nHigh-level mail ingestion orchestration for Mail Intake.\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n\n- Mail adapter access.\n- Message and thread iteration.\n- Header and body parsing.\n- Normalization and model construction.\n\nNo provider-specific logic or API semantics are permitted in this layer.",
             "members": {
               "datetime": {
                 "name": "datetime",
@@ -1197,14 +1197,14 @@
                 "kind": "class",
                 "path": "mail_intake.ingestion.reader.MailIntakeAdapter",
                 "signature": "<bound method Alias.signature of Alias('MailIntakeAdapter', 'mail_intake.adapters.base.MailIntakeAdapter')>",
-                "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - discover messages matching a query\n        - retrieve full message payloads\n        - retrieve full thread payloads\n\n    **Lifecycle:**\n\n        - adapters are intentionally read-only and must not mutate provider state",
+                "docstring": "Base adapter interface for mail providers.\n\nNotes:\n    **Guarantees:**\n\n        - Discover messages matching a query.\n        - Retrieve full message payloads.\n        - Retrieve full thread payloads.\n\n    **Lifecycle:**\n\n        - Adapters are intentionally read-only and must not mutate provider state.",
                 "members": {
                   "iter_message_refs": {
                     "name": "iter_message_refs",
                     "kind": "function",
                     "path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs",
                     "signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
-                    "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``\n\nExample:\n    Typical yield:\n\n        {\n            \"message_id\": \"...\",\n            \"thread_id\": \"...\"\n        }"
+                    "docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    Dict[str, str]:\n        Dictionaries containing message and thread identifiers.\n\nNotes:\n    **Guarantees:**\n\n        - Implementations must yield dictionaries containing at least\n          `message_id` and `thread_id`.\n\nExample:\n    Typical yield:\n\n    ```python\n    {\n        \"message_id\": \"...\",\n        \"thread_id\": \"...\"\n    }\n    ```"
                   },
                   "fetch_message": {
                     "name": "fetch_message",
@@ -1227,7 +1227,7 @@
                 "kind": "class",
                 "path": "mail_intake.ingestion.reader.MailIntakeMessage",
                 "signature": "<bound method Alias.signature of Alias('MailIntakeMessage', 'mail_intake.models.message.MailIntakeMessage')>",
-                "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message\n        - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n\n    **Constraints:**\n    \n        - No provider-specific identifiers, payloads, or API semantics should appear in this model",
+                "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message.\n        - It is intentionally provider-agnostic and suitable for\n          persistence, indexing, and downstream processing.\n\n    **Constraints:**\n\n        - No provider-specific identifiers, payloads, or API semantics\n          should appear in this model.",
                 "members": {
                   "message_id": {
                     "name": "message_id",
@@ -1299,7 +1299,7 @@
                 "kind": "class",
                 "path": "mail_intake.ingestion.reader.MailIntakeThread",
                 "signature": "<bound method Alias.signature of Alias('MailIntakeThread', 'mail_intake.models.thread.MailIntakeThread')>",
-                "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject and participant set\n        - It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions\n        - This model is provider-agnostic and safe to persist",
+                "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject\n          and participant set.\n        - It is designed to support reasoning over conversational context\n          such as job applications, interviews, follow-ups, and ongoing discussions.\n        - This model is provider-agnostic and safe to persist.",
                 "members": {
                   "thread_id": {
                     "name": "thread_id",
@@ -1341,7 +1341,7 @@
                     "kind": "function",
                     "path": "mail_intake.ingestion.reader.MailIntakeThread.add_message",
                     "signature": "<bound method Alias.signature of Alias('add_message', 'mail_intake.models.thread.MailIntakeThread.add_message')>",
-                    "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread\n        - Tracks unique participants\n        - Updates the last activity timestamp"
+                    "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread.\n        - Tracks unique participants.\n        - Updates the last activity timestamp."
                   }
                 }
               },
@@ -1350,56 +1350,56 @@
                 "kind": "function",
                 "path": "mail_intake.ingestion.reader.parse_headers",
                 "signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
-                "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing ``name`` and ``value`` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings\n        - This function normalizes them into a case-insensitive dictionary keyed by lowercase header names\n\nExample:\n    Typical usage:\n    \n        Input:\n            [\n                {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n                {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n            ]\n\n        Output:\n            {\n                \"from\": \"John Doe <john@example.com>\",\n                \"subject\": \"Re: Interview Update\",\n            }"
+                "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
               },
               "extract_sender": {
                 "name": "extract_sender",
                 "kind": "function",
                 "path": "mail_intake.ingestion.reader.extract_sender",
                 "signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
-                "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by :func:`parse_headers`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple ``(email, name)`` where ``email`` is the sender email address and ``name`` is the display name, or ``None`` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name\n\nExample:\n    Typical values:\n\n        ``\"John Doe <john@example.com>\"`` -> ``(\"john@example.com\", \"John Doe\")``\n        ``\"john@example.com\"`` -> ``(\"john@example.com\", None)``"
+                "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
               },
               "extract_body": {
                 "name": "extract_body",
                 "kind": "function",
                 "path": "mail_intake.ingestion.reader.extract_body",
                 "signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
-                "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n    payload: Provider-native message payload dictionary.\n\nReturns:\n    Extracted plain-text message body."
+                "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (Dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
               },
               "normalize_subject": {
                 "name": "normalize_subject",
                 "kind": "function",
                 "path": "mail_intake.ingestion.reader.normalize_subject",
                 "signature": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.normalize_subject')>",
-                "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n        - Repeats prefix stripping to handle stacked prefixes\n        - Collapses excessive whitespace\n        - Preserves original casing (no lowercasing)\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject"
+                "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
               },
               "MailIntakeParsingError": {
                 "name": "MailIntakeParsingError",
                 "kind": "class",
                 "path": "mail_intake.ingestion.reader.MailIntakeParsingError",
                 "signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
-                "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or normalized into internal domain models"
+                "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
               },
               "MailIntakeReader": {
                 "name": "MailIntakeReader",
                 "kind": "class",
                 "path": "mail_intake.ingestion.reader.MailIntakeReader",
-                "signature": "<bound method Class.signature of Class('MailIntakeReader', 32, 165)>",
+                "signature": "<bound method Class.signature of Class('MailIntakeReader', 31, 171)>",
-                "docstring": "High-level read-only ingestion interface.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the primary entry point for consumers of the Mail Intake library\n        - It orchestrates the full ingestion pipeline: Querying the adapter for message references, fetching raw provider messages, parsing and normalizing message data, constructing domain models\n\n    **Constraints:**\n    \n        - This class is intentionally: Provider-agnostic, stateless beyond iteration scope, read-only",
+                "docstring": "High-level read-only ingestion interface.\n\nNotes:\n    **Responsibilities:**\n\n        - This class is the primary entry point for consumers of the\n          Mail Intake library.\n        - It orchestrates the full ingestion pipeline:\n            - Querying the adapter for message references.\n            - Fetching raw provider messages.\n            - Parsing and normalizing message data.\n            - Constructing domain models.\n\n    **Constraints:**\n\n        - This class is intentionally: Provider-agnostic, stateless beyond\n          iteration scope, read-only.",
                 "members": {
                   "iter_messages": {
                     "name": "iter_messages",
                     "kind": "function",
                     "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages",
-                    "signature": "<bound method Function.signature of Function('iter_messages', 57, 75)>",
+                    "signature": "<bound method Function.signature of Function('iter_messages', 62, 80)>",
                     "docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeMessage:\n        Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n    MailIntakeParsingError:\n        If a message cannot be parsed."
                   },
                   "iter_threads": {
                     "name": "iter_threads",
                     "kind": "function",
                     "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads",
-                    "signature": "<bound method Function.signature of Function('iter_threads', 77, 114)>",
+                    "signature": "<bound method Function.signature of Function('iter_threads', 82, 120)>",
-                    "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeThread:\n        An iterator of `MailIntakeThread` instances.\n\nRaises:\n    MailIntakeParsingError:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages"
+                    "docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n    query (str):\n        Provider-specific query string used to filter messages.\n\nYields:\n    MailIntakeThread:\n        An iterator of `MailIntakeThread` instances.\n\nRaises:\n    `MailIntakeParsingError`:\n        If a message cannot be parsed.\n\nNotes:\n    **Guarantees:**\n\n        - Messages are grouped by `thread_id` and yielded as complete\n          thread objects containing all associated messages."
                   }
                 }
               }
@@ -1412,14 +1412,14 @@
         "kind": "module",
         "path": "mail_intake.models",
         "signature": null,
-        "docstring": "Domain models for Mail Intake.\n\n---\n\n## Summary\n\nThis package defines the **canonical, provider-agnostic data models**\nused throughout the Mail Intake ingestion pipeline.\n\nModels in this package:\n- Represent fully parsed and normalized mail data\n- Are safe to persist, serialize, and index\n- Contain no provider-specific payloads or API semantics\n- Serve as stable inputs for downstream processing and analysis\n\nThese models form the core internal data contract of the library.\n\n---\n\n## Public API\n\n    MailIntakeMessage\n    MailIntakeThread\n\n---",
+        "docstring": "# Summary\n\nDomain models for Mail Intake.\n\nThis package defines the **canonical, provider-agnostic data models**\nused throughout the Mail Intake ingestion pipeline.\n\nModels in this package:\n\n- Represent fully parsed and normalized mail data.\n- Are safe to persist, serialize, and index.\n- Contain no provider-specific payloads or API semantics.\n- Serve as stable inputs for downstream processing and analysis.\n\nThese models form the core internal data contract of the library.\n\n---\n\n# Public API\n\n- `MailIntakeMessage`\n- `MailIntakeThread`\n\n---",
         "members": {
           "MailIntakeMessage": {
             "name": "MailIntakeMessage",
             "kind": "class",
             "path": "mail_intake.models.MailIntakeMessage",
             "signature": "<bound method Alias.signature of Alias('MailIntakeMessage', 'mail_intake.models.message.MailIntakeMessage')>",
-            "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message\n        - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n\n    **Constraints:**\n    \n        - No provider-specific identifiers, payloads, or API semantics should appear in this model",
+            "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message.\n        - It is intentionally provider-agnostic and suitable for\n          persistence, indexing, and downstream processing.\n\n    **Constraints:**\n\n        - No provider-specific identifiers, payloads, or API semantics\n          should appear in this model.",
             "members": {
               "message_id": {
                 "name": "message_id",
@@ -1491,7 +1491,7 @@
             "kind": "class",
             "path": "mail_intake.models.MailIntakeThread",
             "signature": "<bound method Alias.signature of Alias('MailIntakeThread', 'mail_intake.models.thread.MailIntakeThread')>",
-            "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject and participant set\n        - It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions\n        - This model is provider-agnostic and safe to persist",
+            "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject\n          and participant set.\n        - It is designed to support reasoning over conversational context\n          such as job applications, interviews, follow-ups, and ongoing discussions.\n        - This model is provider-agnostic and safe to persist.",
             "members": {
               "thread_id": {
                 "name": "thread_id",
@@ -1533,7 +1533,7 @@
                 "kind": "function",
                 "path": "mail_intake.models.MailIntakeThread.add_message",
                 "signature": "<bound method Alias.signature of Alias('add_message', 'mail_intake.models.thread.MailIntakeThread.add_message')>",
-                "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread\n        - Tracks unique participants\n        - Updates the last activity timestamp"
+                "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread.\n        - Tracks unique participants.\n        - Updates the last activity timestamp."
               }
             }
           },
@@ -1542,7 +1542,7 @@
             "kind": "module",
             "path": "mail_intake.models.message",
             "signature": null,
-            "docstring": "Message domain models for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **canonical, provider-agnostic representation**\nof an individual email message as used internally by the Mail Intake\ningestion pipeline.\n\nModels in this module are safe to persist and must not contain any\nprovider-specific fields or semantics.",
+            "docstring": "# Summary\n\nMessage domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an individual email message as used internally by the Mail Intake\ningestion pipeline.\n\nModels in this module are safe to persist and must not contain any\nprovider-specific fields or semantics.",
             "members": {
               "dataclass": {
                 "name": "dataclass",
@@ -1576,8 +1576,8 @@
                 "name": "MailIntakeMessage",
                 "kind": "class",
                 "path": "mail_intake.models.message.MailIntakeMessage",
-                "signature": "<bound method Class.signature of Class('MailIntakeMessage', 21, 80)>",
+                "signature": "<bound method Class.signature of Class('MailIntakeMessage', 19, 80)>",
-                "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message\n        - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n\n    **Constraints:**\n    \n        - No provider-specific identifiers, payloads, or API semantics should appear in this model",
+                "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message.\n        - It is intentionally provider-agnostic and suitable for\n          persistence, indexing, and downstream processing.\n\n    **Constraints:**\n\n        - No provider-specific identifiers, payloads, or API semantics\n          should appear in this model.",
                 "members": {
                   "message_id": {
                     "name": "message_id",
@@ -1651,7 +1651,7 @@
             "kind": "module",
             "path": "mail_intake.models.thread",
             "signature": null,
-            "docstring": "Thread domain models for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **canonical, provider-agnostic representation**\nof an email thread as used internally by the Mail Intake ingestion pipeline.\n\nThreads group related messages and serve as the primary unit of reasoning\nfor higher-level correspondence workflows.",
+            "docstring": "# Summary\n\nThread domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an email thread as used internally by the Mail Intake ingestion pipeline.\n\nThreads group related messages and serve as the primary unit of reasoning\nfor higher-level correspondence workflows.",
             "members": {
               "dataclass": {
                 "name": "dataclass",
@@ -1693,7 +1693,7 @@
                 "kind": "class",
                 "path": "mail_intake.models.thread.MailIntakeMessage",
                 "signature": "<bound method Alias.signature of Alias('MailIntakeMessage', 'mail_intake.models.message.MailIntakeMessage')>",
-                "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message\n        - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n\n    **Constraints:**\n    \n        - No provider-specific identifiers, payloads, or API semantics should appear in this model",
+                "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message.\n        - It is intentionally provider-agnostic and suitable for\n          persistence, indexing, and downstream processing.\n\n    **Constraints:**\n\n        - No provider-specific identifiers, payloads, or API semantics\n          should appear in this model.",
                 "members": {
                   "message_id": {
                     "name": "message_id",
@@ -1764,8 +1764,8 @@
                 "name": "MailIntakeThread",
                 "kind": "class",
                 "path": "mail_intake.models.thread.MailIntakeThread",
-                "signature": "<bound method Class.signature of Class('MailIntakeThread', 22, 81)>",
+                "signature": "<bound method Class.signature of Class('MailIntakeThread', 20, 81)>",
-                "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject and participant set\n        - It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions\n        - This model is provider-agnostic and safe to persist",
+                "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject\n          and participant set.\n        - It is designed to support reasoning over conversational context\n          such as job applications, interviews, follow-ups, and ongoing discussions.\n        - This model is provider-agnostic and safe to persist.",
                 "members": {
                   "thread_id": {
                     "name": "thread_id",
@@ -1807,7 +1807,7 @@
                     "kind": "function",
                     "path": "mail_intake.models.thread.MailIntakeThread.add_message",
                     "signature": "<bound method Function.signature of Function('add_message', 60, 81)>",
-                    "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread\n        - Tracks unique participants\n        - Updates the last activity timestamp"
+                    "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread.\n        - Tracks unique participants.\n        - Updates the last activity timestamp."
                   }
                 }
               },
@@ -1827,42 +1827,42 @@
         "kind": "module",
         "path": "mail_intake.parsers",
         "signature": null,
-        "docstring": "Message parsing utilities for Mail Intake.\n\n---\n\n## Summary\n\nThis package contains **provider-aware but adapter-agnostic parsing helpers**\nused to extract and normalize structured information from raw mail payloads.\n\nParsers in this package are responsible for:\n- Interpreting provider-native message structures\n- Extracting meaningful fields such as headers, body text, and subjects\n- Normalizing data into consistent internal representations\n\nThis package does not:\n- Perform network or IO operations\n- Contain provider API logic\n- Construct domain models directly\n\nParsing functions are designed to be composable and are orchestrated by the\ningestion layer.\n\n---\n\n## Public API\n\n    extract_body\n    parse_headers\n    extract_sender\n    normalize_subject\n\n---",
+        "docstring": "# Summary\n\nMessage parsing utilities for Mail Intake.\n\nThis package contains **provider-aware but adapter-agnostic parsing helpers**\nused to extract and normalize structured information from raw mail payloads.\n\nParsers in this package are responsible for:\n\n- Interpreting provider-native message structures.\n- Extracting meaningful fields such as headers, body text, and subjects.\n- Normalizing data into consistent internal representations.\n\nThis package does not:\n\n- Perform network or IO operations.\n- Contain provider API logic.\n- Construct domain models directly.\n\nParsing functions are designed to be composable and are orchestrated by the\ningestion layer.\n\n---\n\n# Public API\n\n- `extract_body`\n- `parse_headers`\n- `extract_sender`\n- `normalize_subject`\n\n---",
         "members": {
           "extract_body": {
             "name": "extract_body",
             "kind": "function",
             "path": "mail_intake.parsers.extract_body",
             "signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
-            "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n    payload: Provider-native message payload dictionary.\n\nReturns:\n    Extracted plain-text message body."
+            "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (Dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
           },
           "parse_headers": {
             "name": "parse_headers",
             "kind": "function",
             "path": "mail_intake.parsers.parse_headers",
             "signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
-            "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing ``name`` and ``value`` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings\n        - This function normalizes them into a case-insensitive dictionary keyed by lowercase header names\n\nExample:\n    Typical usage:\n    \n        Input:\n            [\n                {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n                {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n            ]\n\n        Output:\n            {\n                \"from\": \"John Doe <john@example.com>\",\n                \"subject\": \"Re: Interview Update\",\n            }"
+            "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
           },
           "extract_sender": {
             "name": "extract_sender",
             "kind": "function",
             "path": "mail_intake.parsers.extract_sender",
             "signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
-            "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by :func:`parse_headers`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple ``(email, name)`` where ``email`` is the sender email address and ``name`` is the display name, or ``None`` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name\n\nExample:\n    Typical values:\n\n        ``\"John Doe <john@example.com>\"`` -> ``(\"john@example.com\", \"John Doe\")``\n        ``\"john@example.com\"`` -> ``(\"john@example.com\", None)``"
+            "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
           },
           "normalize_subject": {
             "name": "normalize_subject",
             "kind": "function",
             "path": "mail_intake.parsers.normalize_subject",
             "signature": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.normalize_subject')>",
-            "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n        - Repeats prefix stripping to handle stacked prefixes\n        - Collapses excessive whitespace\n        - Preserves original casing (no lowercasing)\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject"
+            "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
           },
           "body": {
             "name": "body",
             "kind": "module",
             "path": "mail_intake.parsers.body",
             "signature": null,
-            "docstring": "Message body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.",
+            "docstring": "# Summary\n\nMessage body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.",
             "members": {
               "base64": {
                 "name": "base64",
@@ -1904,14 +1904,14 @@
                 "kind": "class",
                 "path": "mail_intake.parsers.body.MailIntakeParsingError",
                 "signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
-                "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or normalized into internal domain models"
+                "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
               },
               "extract_body": {
                 "name": "extract_body",
                 "kind": "function",
                 "path": "mail_intake.parsers.body.extract_body",
-                "signature": "<bound method Function.signature of Function('extract_body', 77, 122)>",
+                "signature": "<bound method Function.signature of Function('extract_body', 85, 133)>",
-                "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n    payload: Provider-native message payload dictionary.\n\nReturns:\n    Extracted plain-text message body."
+                "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (Dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
               }
             }
           },
@@ -1920,7 +1920,7 @@
             "kind": "module",
             "path": "mail_intake.parsers.headers",
             "signature": null,
-            "docstring": "Message header parsing utilities for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.",
+            "docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.",
             "members": {
               "Dict": {
                 "name": "Dict",
@@ -1954,15 +1954,15 @@
                 "name": "parse_headers",
                 "kind": "function",
                 "path": "mail_intake.parsers.headers.parse_headers",
-                "signature": "<bound method Function.signature of Function('parse_headers', 18, 62)>",
+                "signature": "<bound method Function.signature of Function('parse_headers', 16, 64)>",
-                "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing ``name`` and ``value`` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings\n        - This function normalizes them into a case-insensitive dictionary keyed by lowercase header names\n\nExample:\n    Typical usage:\n    \n        Input:\n            [\n                {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n                {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n            ]\n\n        Output:\n            {\n                \"from\": \"John Doe <john@example.com>\",\n                \"subject\": \"Re: Interview Update\",\n            }"
+                "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
               },
               "extract_sender": {
                 "name": "extract_sender",
                 "kind": "function",
                 "path": "mail_intake.parsers.headers.extract_sender",
-                "signature": "<bound method Function.signature of Function('extract_sender', 65, 98)>",
+                "signature": "<bound method Function.signature of Function('extract_sender', 67, 102)>",
-                "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by :func:`parse_headers`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple ``(email, name)`` where ``email`` is the sender email address and ``name`` is the display name, or ``None`` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name\n\nExample:\n    Typical values:\n\n        ``\"John Doe <john@example.com>\"`` -> ``(\"john@example.com\", \"John Doe\")``\n        ``\"john@example.com\"`` -> ``(\"john@example.com\", None)``"
+                "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
               }
             }
           },
@@ -1971,7 +1971,7 @@
             "kind": "module",
             "path": "mail_intake.parsers.subject",
             "signature": null,
-            "docstring": "Subject line normalization utilities for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.",
+            "docstring": "# Summary\n\nSubject line normalization utilities for Mail Intake.\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.",
             "members": {
               "re": {
                 "name": "re",
@@ -1984,8 +1984,8 @@
                 "name": "normalize_subject",
                 "kind": "function",
                 "path": "mail_intake.parsers.subject.normalize_subject",
-                "signature": "<bound method Function.signature of Function('normalize_subject', 24, 63)>",
+                "signature": "<bound method Function.signature of Function('normalize_subject', 22, 62)>",
-                "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n        - Repeats prefix stripping to handle stacked prefixes\n        - Collapses excessive whitespace\n        - Preserves original casing (no lowercasing)\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject"
+                "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
               }
             }
           }

mcp_docs/modules/mail_intake.models.json

@@ -2,14 +2,14 @@
   "module": "mail_intake.models",
   "content": {
     "path": "mail_intake.models",
-    "docstring": "Domain models for Mail Intake.\n\n---\n\n## Summary\n\nThis package defines the **canonical, provider-agnostic data models**\nused throughout the Mail Intake ingestion pipeline.\n\nModels in this package:\n- Represent fully parsed and normalized mail data\n- Are safe to persist, serialize, and index\n- Contain no provider-specific payloads or API semantics\n- Serve as stable inputs for downstream processing and analysis\n\nThese models form the core internal data contract of the library.\n\n---\n\n## Public API\n\n    MailIntakeMessage\n    MailIntakeThread\n\n---",
+    "docstring": "# Summary\n\nDomain models for Mail Intake.\n\nThis package defines the **canonical, provider-agnostic data models**\nused throughout the Mail Intake ingestion pipeline.\n\nModels in this package:\n\n- Represent fully parsed and normalized mail data.\n- Are safe to persist, serialize, and index.\n- Contain no provider-specific payloads or API semantics.\n- Serve as stable inputs for downstream processing and analysis.\n\nThese models form the core internal data contract of the library.\n\n---\n\n# Public API\n\n- `MailIntakeMessage`\n- `MailIntakeThread`\n\n---",
     "objects": {
       "MailIntakeMessage": {
         "name": "MailIntakeMessage",
         "kind": "class",
         "path": "mail_intake.models.MailIntakeMessage",
         "signature": "<bound method Alias.signature of Alias('MailIntakeMessage', 'mail_intake.models.message.MailIntakeMessage')>",
-        "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message\n        - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n\n    **Constraints:**\n    \n        - No provider-specific identifiers, payloads, or API semantics should appear in this model",
+        "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message.\n        - It is intentionally provider-agnostic and suitable for\n          persistence, indexing, and downstream processing.\n\n    **Constraints:**\n\n        - No provider-specific identifiers, payloads, or API semantics\n          should appear in this model.",
         "members": {
           "message_id": {
             "name": "message_id",
@@ -81,7 +81,7 @@
         "kind": "class",
         "path": "mail_intake.models.MailIntakeThread",
         "signature": "<bound method Alias.signature of Alias('MailIntakeThread', 'mail_intake.models.thread.MailIntakeThread')>",
-        "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject and participant set\n        - It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions\n        - This model is provider-agnostic and safe to persist",
+        "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject\n          and participant set.\n        - It is designed to support reasoning over conversational context\n          such as job applications, interviews, follow-ups, and ongoing discussions.\n        - This model is provider-agnostic and safe to persist.",
         "members": {
           "thread_id": {
             "name": "thread_id",
@@ -123,7 +123,7 @@
             "kind": "function",
             "path": "mail_intake.models.MailIntakeThread.add_message",
             "signature": "<bound method Alias.signature of Alias('add_message', 'mail_intake.models.thread.MailIntakeThread.add_message')>",
-            "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread\n        - Tracks unique participants\n        - Updates the last activity timestamp"
+            "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread.\n        - Tracks unique participants.\n        - Updates the last activity timestamp."
           }
         }
       },
@@ -132,7 +132,7 @@
         "kind": "module",
         "path": "mail_intake.models.message",
         "signature": null,
-        "docstring": "Message domain models for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **canonical, provider-agnostic representation**\nof an individual email message as used internally by the Mail Intake\ningestion pipeline.\n\nModels in this module are safe to persist and must not contain any\nprovider-specific fields or semantics.",
+        "docstring": "# Summary\n\nMessage domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an individual email message as used internally by the Mail Intake\ningestion pipeline.\n\nModels in this module are safe to persist and must not contain any\nprovider-specific fields or semantics.",
         "members": {
           "dataclass": {
             "name": "dataclass",
@@ -166,8 +166,8 @@
             "name": "MailIntakeMessage",
             "kind": "class",
             "path": "mail_intake.models.message.MailIntakeMessage",
-            "signature": "<bound method Class.signature of Class('MailIntakeMessage', 21, 80)>",
+            "signature": "<bound method Class.signature of Class('MailIntakeMessage', 19, 80)>",
-            "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message\n        - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n\n    **Constraints:**\n    \n        - No provider-specific identifiers, payloads, or API semantics should appear in this model",
+            "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message.\n        - It is intentionally provider-agnostic and suitable for\n          persistence, indexing, and downstream processing.\n\n    **Constraints:**\n\n        - No provider-specific identifiers, payloads, or API semantics\n          should appear in this model.",
             "members": {
               "message_id": {
                 "name": "message_id",
@@ -241,7 +241,7 @@
         "kind": "module",
         "path": "mail_intake.models.thread",
         "signature": null,
-        "docstring": "Thread domain models for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **canonical, provider-agnostic representation**\nof an email thread as used internally by the Mail Intake ingestion pipeline.\n\nThreads group related messages and serve as the primary unit of reasoning\nfor higher-level correspondence workflows.",
+        "docstring": "# Summary\n\nThread domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an email thread as used internally by the Mail Intake ingestion pipeline.\n\nThreads group related messages and serve as the primary unit of reasoning\nfor higher-level correspondence workflows.",
         "members": {
           "dataclass": {
             "name": "dataclass",
@@ -283,7 +283,7 @@
             "kind": "class",
             "path": "mail_intake.models.thread.MailIntakeMessage",
             "signature": "<bound method Alias.signature of Alias('MailIntakeMessage', 'mail_intake.models.message.MailIntakeMessage')>",
-            "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message\n        - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n\n    **Constraints:**\n    \n        - No provider-specific identifiers, payloads, or API semantics should appear in this model",
+            "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message.\n        - It is intentionally provider-agnostic and suitable for\n          persistence, indexing, and downstream processing.\n\n    **Constraints:**\n\n        - No provider-specific identifiers, payloads, or API semantics\n          should appear in this model.",
             "members": {
               "message_id": {
                 "name": "message_id",
@@ -354,8 +354,8 @@
             "name": "MailIntakeThread",
             "kind": "class",
             "path": "mail_intake.models.thread.MailIntakeThread",
-            "signature": "<bound method Class.signature of Class('MailIntakeThread', 22, 81)>",
+            "signature": "<bound method Class.signature of Class('MailIntakeThread', 20, 81)>",
-            "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject and participant set\n        - It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions\n        - This model is provider-agnostic and safe to persist",
+            "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject\n          and participant set.\n        - It is designed to support reasoning over conversational context\n          such as job applications, interviews, follow-ups, and ongoing discussions.\n        - This model is provider-agnostic and safe to persist.",
             "members": {
               "thread_id": {
                 "name": "thread_id",
@@ -397,7 +397,7 @@
                 "kind": "function",
                 "path": "mail_intake.models.thread.MailIntakeThread.add_message",
                 "signature": "<bound method Function.signature of Function('add_message', 60, 81)>",
-                "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread\n        - Tracks unique participants\n        - Updates the last activity timestamp"
+                "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread.\n        - Tracks unique participants.\n        - Updates the last activity timestamp."
               }
             }
           },

mcp_docs/modules/mail_intake.models.message.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.models.message",
   "content": {
     "path": "mail_intake.models.message",
-    "docstring": "Message domain models for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **canonical, provider-agnostic representation**\nof an individual email message as used internally by the Mail Intake\ningestion pipeline.\n\nModels in this module are safe to persist and must not contain any\nprovider-specific fields or semantics.",
+    "docstring": "# Summary\n\nMessage domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an individual email message as used internally by the Mail Intake\ningestion pipeline.\n\nModels in this module are safe to persist and must not contain any\nprovider-specific fields or semantics.",
     "objects": {
       "dataclass": {
         "name": "dataclass",
@@ -36,8 +36,8 @@
         "name": "MailIntakeMessage",
         "kind": "class",
         "path": "mail_intake.models.message.MailIntakeMessage",
-        "signature": "<bound method Class.signature of Class('MailIntakeMessage', 21, 80)>",
+        "signature": "<bound method Class.signature of Class('MailIntakeMessage', 19, 80)>",
-        "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message\n        - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n\n    **Constraints:**\n    \n        - No provider-specific identifiers, payloads, or API semantics should appear in this model",
+        "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message.\n        - It is intentionally provider-agnostic and suitable for\n          persistence, indexing, and downstream processing.\n\n    **Constraints:**\n\n        - No provider-specific identifiers, payloads, or API semantics\n          should appear in this model.",
         "members": {
           "message_id": {
             "name": "message_id",

mcp_docs/modules/mail_intake.models.thread.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.models.thread",
   "content": {
     "path": "mail_intake.models.thread",
-    "docstring": "Thread domain models for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **canonical, provider-agnostic representation**\nof an email thread as used internally by the Mail Intake ingestion pipeline.\n\nThreads group related messages and serve as the primary unit of reasoning\nfor higher-level correspondence workflows.",
+    "docstring": "# Summary\n\nThread domain models for Mail Intake.\n\nThis module defines the **canonical, provider-agnostic representation**\nof an email thread as used internally by the Mail Intake ingestion pipeline.\n\nThreads group related messages and serve as the primary unit of reasoning\nfor higher-level correspondence workflows.",
     "objects": {
       "dataclass": {
         "name": "dataclass",
@@ -44,7 +44,7 @@
         "kind": "class",
         "path": "mail_intake.models.thread.MailIntakeMessage",
         "signature": "<bound method Alias.signature of Alias('MailIntakeMessage', 'mail_intake.models.message.MailIntakeMessage')>",
-        "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message\n        - It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n\n    **Constraints:**\n    \n        - No provider-specific identifiers, payloads, or API semantics should appear in this model",
+        "docstring": "Canonical internal representation of a single email message.\n\nNotes:\n    **Guarantees:**\n\n        - This model represents a fully parsed and normalized email message.\n        - It is intentionally provider-agnostic and suitable for\n          persistence, indexing, and downstream processing.\n\n    **Constraints:**\n\n        - No provider-specific identifiers, payloads, or API semantics\n          should appear in this model.",
         "members": {
           "message_id": {
             "name": "message_id",
@@ -115,8 +115,8 @@
         "name": "MailIntakeThread",
         "kind": "class",
         "path": "mail_intake.models.thread.MailIntakeThread",
-        "signature": "<bound method Class.signature of Class('MailIntakeThread', 22, 81)>",
+        "signature": "<bound method Class.signature of Class('MailIntakeThread', 20, 81)>",
-        "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject and participant set\n        - It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions\n        - This model is provider-agnostic and safe to persist",
+        "docstring": "Canonical internal representation of an email thread.\n\nNotes:\n    **Guarantees:**\n\n        - A thread groups multiple related messages under a single subject\n          and participant set.\n        - It is designed to support reasoning over conversational context\n          such as job applications, interviews, follow-ups, and ongoing discussions.\n        - This model is provider-agnostic and safe to persist.",
         "members": {
           "thread_id": {
             "name": "thread_id",
@@ -158,7 +158,7 @@
             "kind": "function",
             "path": "mail_intake.models.thread.MailIntakeThread.add_message",
             "signature": "<bound method Function.signature of Function('add_message', 60, 81)>",
-            "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread\n        - Tracks unique participants\n        - Updates the last activity timestamp"
+            "docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n    message (MailIntakeMessage):\n        Parsed mail message to add to the thread.\n\nNotes:\n    **Responsibilities:**\n\n        - Appends the message to the thread.\n        - Tracks unique participants.\n        - Updates the last activity timestamp."
           }
         }
       },

mcp_docs/modules/mail_intake.parsers.body.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.parsers.body",
   "content": {
     "path": "mail_intake.parsers.body",
-    "docstring": "Message body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.",
+    "docstring": "# Summary\n\nMessage body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.",
     "objects": {
       "base64": {
         "name": "base64",
@@ -44,14 +44,14 @@
         "kind": "class",
         "path": "mail_intake.parsers.body.MailIntakeParsingError",
         "signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
-        "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or normalized into internal domain models"
+        "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
       },
       "extract_body": {
         "name": "extract_body",
         "kind": "function",
         "path": "mail_intake.parsers.body.extract_body",
-        "signature": "<bound method Function.signature of Function('extract_body', 77, 122)>",
+        "signature": "<bound method Function.signature of Function('extract_body', 85, 133)>",
-        "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n    payload: Provider-native message payload dictionary.\n\nReturns:\n    Extracted plain-text message body."
+        "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (Dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
       }
     }
   }

mcp_docs/modules/mail_intake.parsers.headers.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.parsers.headers",
   "content": {
     "path": "mail_intake.parsers.headers",
-    "docstring": "Message header parsing utilities for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.",
+    "docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.",
     "objects": {
       "Dict": {
         "name": "Dict",
@@ -36,15 +36,15 @@
         "name": "parse_headers",
         "kind": "function",
         "path": "mail_intake.parsers.headers.parse_headers",
-        "signature": "<bound method Function.signature of Function('parse_headers', 18, 62)>",
+        "signature": "<bound method Function.signature of Function('parse_headers', 16, 64)>",
-        "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing ``name`` and ``value`` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings\n        - This function normalizes them into a case-insensitive dictionary keyed by lowercase header names\n\nExample:\n    Typical usage:\n    \n        Input:\n            [\n                {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n                {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n            ]\n\n        Output:\n            {\n                \"from\": \"John Doe <john@example.com>\",\n                \"subject\": \"Re: Interview Update\",\n            }"
+        "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
       },
       "extract_sender": {
         "name": "extract_sender",
         "kind": "function",
         "path": "mail_intake.parsers.headers.extract_sender",
-        "signature": "<bound method Function.signature of Function('extract_sender', 65, 98)>",
+        "signature": "<bound method Function.signature of Function('extract_sender', 67, 102)>",
-        "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by :func:`parse_headers`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple ``(email, name)`` where ``email`` is the sender email address and ``name`` is the display name, or ``None`` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name\n\nExample:\n    Typical values:\n\n        ``\"John Doe <john@example.com>\"`` -> ``(\"john@example.com\", \"John Doe\")``\n        ``\"john@example.com\"`` -> ``(\"john@example.com\", None)``"
+        "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
       }
     }
   }

mcp_docs/modules/mail_intake.parsers.json

@@ -2,42 +2,42 @@
   "module": "mail_intake.parsers",
   "content": {
     "path": "mail_intake.parsers",
-    "docstring": "Message parsing utilities for Mail Intake.\n\n---\n\n## Summary\n\nThis package contains **provider-aware but adapter-agnostic parsing helpers**\nused to extract and normalize structured information from raw mail payloads.\n\nParsers in this package are responsible for:\n- Interpreting provider-native message structures\n- Extracting meaningful fields such as headers, body text, and subjects\n- Normalizing data into consistent internal representations\n\nThis package does not:\n- Perform network or IO operations\n- Contain provider API logic\n- Construct domain models directly\n\nParsing functions are designed to be composable and are orchestrated by the\ningestion layer.\n\n---\n\n## Public API\n\n    extract_body\n    parse_headers\n    extract_sender\n    normalize_subject\n\n---",
+    "docstring": "# Summary\n\nMessage parsing utilities for Mail Intake.\n\nThis package contains **provider-aware but adapter-agnostic parsing helpers**\nused to extract and normalize structured information from raw mail payloads.\n\nParsers in this package are responsible for:\n\n- Interpreting provider-native message structures.\n- Extracting meaningful fields such as headers, body text, and subjects.\n- Normalizing data into consistent internal representations.\n\nThis package does not:\n\n- Perform network or IO operations.\n- Contain provider API logic.\n- Construct domain models directly.\n\nParsing functions are designed to be composable and are orchestrated by the\ningestion layer.\n\n---\n\n# Public API\n\n- `extract_body`\n- `parse_headers`\n- `extract_sender`\n- `normalize_subject`\n\n---",
     "objects": {
       "extract_body": {
         "name": "extract_body",
         "kind": "function",
         "path": "mail_intake.parsers.extract_body",
         "signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
-        "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n    payload: Provider-native message payload dictionary.\n\nReturns:\n    Extracted plain-text message body."
+        "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (Dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
       },
       "parse_headers": {
         "name": "parse_headers",
         "kind": "function",
         "path": "mail_intake.parsers.parse_headers",
         "signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
-        "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing ``name`` and ``value`` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings\n        - This function normalizes them into a case-insensitive dictionary keyed by lowercase header names\n\nExample:\n    Typical usage:\n    \n        Input:\n            [\n                {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n                {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n            ]\n\n        Output:\n            {\n                \"from\": \"John Doe <john@example.com>\",\n                \"subject\": \"Re: Interview Update\",\n            }"
+        "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
       },
       "extract_sender": {
         "name": "extract_sender",
         "kind": "function",
         "path": "mail_intake.parsers.extract_sender",
         "signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
-        "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by :func:`parse_headers`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple ``(email, name)`` where ``email`` is the sender email address and ``name`` is the display name, or ``None`` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name\n\nExample:\n    Typical values:\n\n        ``\"John Doe <john@example.com>\"`` -> ``(\"john@example.com\", \"John Doe\")``\n        ``\"john@example.com\"`` -> ``(\"john@example.com\", None)``"
+        "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
       },
       "normalize_subject": {
         "name": "normalize_subject",
         "kind": "function",
         "path": "mail_intake.parsers.normalize_subject",
         "signature": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.normalize_subject')>",
-        "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n        - Repeats prefix stripping to handle stacked prefixes\n        - Collapses excessive whitespace\n        - Preserves original casing (no lowercasing)\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject"
+        "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
       },
       "body": {
         "name": "body",
         "kind": "module",
         "path": "mail_intake.parsers.body",
         "signature": null,
-        "docstring": "Message body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.",
+        "docstring": "# Summary\n\nMessage body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.",
         "members": {
           "base64": {
             "name": "base64",
@@ -79,14 +79,14 @@
             "kind": "class",
             "path": "mail_intake.parsers.body.MailIntakeParsingError",
             "signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
-            "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or normalized into internal domain models"
+            "docstring": "Errors encountered while parsing message content.\n\nNotes:\n    **Lifecycle:**\n\n        - Raised when raw provider payloads cannot be interpreted or\n          normalized into internal domain models."
           },
           "extract_body": {
             "name": "extract_body",
             "kind": "function",
             "path": "mail_intake.parsers.body.extract_body",
-            "signature": "<bound method Function.signature of Function('extract_body', 77, 122)>",
+            "signature": "<bound method Function.signature of Function('extract_body', 85, 133)>",
-            "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n    payload: Provider-native message payload dictionary.\n\nReturns:\n    Extracted plain-text message body."
+            "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n    payload (Dict[str, Any]):\n        Provider-native message payload dictionary.\n\nReturns:\n    str:\n        Extracted plain-text message body."
           }
         }
       },
@@ -95,7 +95,7 @@
         "kind": "module",
         "path": "mail_intake.parsers.headers",
         "signature": null,
-        "docstring": "Message header parsing utilities for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.",
+        "docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.",
         "members": {
           "Dict": {
             "name": "Dict",
@@ -129,15 +129,15 @@
             "name": "parse_headers",
             "kind": "function",
             "path": "mail_intake.parsers.headers.parse_headers",
-            "signature": "<bound method Function.signature of Function('parse_headers', 18, 62)>",
+            "signature": "<bound method Function.signature of Function('parse_headers', 16, 64)>",
-            "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing ``name`` and ``value`` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings\n        - This function normalizes them into a case-insensitive dictionary keyed by lowercase header names\n\nExample:\n    Typical usage:\n    \n        Input:\n            [\n                {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n                {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n            ]\n\n        Output:\n            {\n                \"from\": \"John Doe <john@example.com>\",\n                \"subject\": \"Re: Interview Update\",\n            }"
+            "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n    raw_headers (List[Dict[str, str]]):\n        List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n    Dict[str, str]:\n        Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n    **Guarantees:**\n\n        - Provider payloads (such as Gmail) typically represent headers as a\n          list of name/value mappings.\n        - This function normalizes them into a case-insensitive dictionary\n          keyed by lowercase header names.\n\nExample:\n    Typical usage:\n\n    ```python\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }\n    ```"
           },
           "extract_sender": {
             "name": "extract_sender",
             "kind": "function",
             "path": "mail_intake.parsers.headers.extract_sender",
-            "signature": "<bound method Function.signature of Function('extract_sender', 65, 98)>",
+            "signature": "<bound method Function.signature of Function('extract_sender', 67, 102)>",
-            "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by :func:`parse_headers`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple ``(email, name)`` where ``email`` is the sender email address and ``name`` is the display name, or ``None`` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name\n\nExample:\n    Typical values:\n\n        ``\"John Doe <john@example.com>\"`` -> ``(\"john@example.com\", \"John Doe\")``\n        ``\"john@example.com\"`` -> ``(\"john@example.com\", None)``"
+            "docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n    headers (Dict[str, str]):\n        Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n    Tuple[str, Optional[str]]:\n        A tuple `(email, name)` where `email` is the sender email address\n        and `name` is the display name, or `None` if unavailable.\n\nNotes:\n    **Responsibilities:**\n\n        - This function parses the `From` header and attempts to extract\n          sender email address and optional human-readable display name.\n\nExample:\n    Typical values:\n\n    - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n    - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
           }
         }
       },
@@ -146,7 +146,7 @@
         "kind": "module",
         "path": "mail_intake.parsers.subject",
         "signature": null,
-        "docstring": "Subject line normalization utilities for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.",
+        "docstring": "# Summary\n\nSubject line normalization utilities for Mail Intake.\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.",
         "members": {
           "re": {
             "name": "re",
@@ -159,8 +159,8 @@
             "name": "normalize_subject",
             "kind": "function",
             "path": "mail_intake.parsers.subject.normalize_subject",
-            "signature": "<bound method Function.signature of Function('normalize_subject', 24, 63)>",
+            "signature": "<bound method Function.signature of Function('normalize_subject', 22, 62)>",
-            "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n        - Repeats prefix stripping to handle stacked prefixes\n        - Collapses excessive whitespace\n        - Preserves original casing (no lowercasing)\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject"
+            "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
           }
         }
       }

mcp_docs/modules/mail_intake.parsers.subject.json

@@ -2,7 +2,7 @@
   "module": "mail_intake.parsers.subject",
   "content": {
     "path": "mail_intake.parsers.subject",
-    "docstring": "Subject line normalization utilities for Mail Intake.\n\n---\n\n## Summary\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.",
+    "docstring": "# Summary\n\nSubject line normalization utilities for Mail Intake.\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.",
     "objects": {
       "re": {
         "name": "re",
@@ -15,8 +15,8 @@
         "name": "normalize_subject",
         "kind": "function",
         "path": "mail_intake.parsers.subject.normalize_subject",
-        "signature": "<bound method Function.signature of Function('normalize_subject', 24, 63)>",
+        "signature": "<bound method Function.signature of Function('normalize_subject', 22, 62)>",
-        "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n        - Repeats prefix stripping to handle stacked prefixes\n        - Collapses excessive whitespace\n        - Preserves original casing (no lowercasing)\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject"
+        "docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n    subject (str):\n        Raw subject line from a message header.\n\nReturns:\n    str:\n        Normalized subject string suitable for thread grouping.\n\nNotes:\n    **Responsibilities:**\n\n        - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n        - Repeats prefix stripping to handle stacked prefixes.\n        - Collapses excessive whitespace.\n        - Preserves original casing (no lowercasing).\n\n    **Guarantees:**\n\n        - This function is intentionally conservative and avoids aggressive\n          transformations that could alter the semantic meaning of the subject."
       }
     }
   }