google styled doc

mail_intake/__init__.py

@@ -1,6 +1,10 @@
 """
 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.
@@ -20,9 +24,9 @@ as a first-class module at the package root:
 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:
 
@@ -35,9 +39,9 @@ Or with Poetry:
 Mail Intake is pure Python and has no runtime dependencies beyond those
 required by the selected provider (for example, Google APIs for Gmail).
 
-----------------------------------------------------------------------
-Basic Usage
-----------------------------------------------------------------------
+---
+
+## Quick start
 
 Minimal Gmail ingestion example (local development):
 
@@ -65,27 +69,41 @@ Iterating over threads:
     for thread in reader.iter_threads("subject:Interview"):
         print(thread.normalized_subject, len(thread.messages))
 
-----------------------------------------------------------------------
-Extensibility Model
-----------------------------------------------------------------------
+---
+
+## 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 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.
 
-----------------------------------------------------------------------
-Public API Surface
-----------------------------------------------------------------------
+**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:
 
@@ -101,40 +119,7 @@ The supported public API consists of the following top-level modules:
 Classes and functions should be imported explicitly from these modules.
 No individual symbols are re-exported at the package root.
 
-----------------------------------------------------------------------
-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.
-
-## Documentation Design
-
-Follow these "AI-Native" docstring principles across the codebase:
-
-### For Humans
-- **Namespace Clarity**: Always specify which module a class or function belongs to.
-- **Contract Explanations**: Use the `adapters` and `auth` base classes to explain extension requirements.
-
-### For LLMs
-- **Dotted Paths**: Use full dotted paths in docstrings to help agents link concepts across modules.
-- **Typed Interfaces**: Provide `.pyi` stubs for every public module to ensure perfect context for AI coding tools.
-- **Canonical Exceptions**: Always use `: description` pairs in `Raises` blocks to enable structured error analysis.
+---
 """