docs-and-mcps (#1)

Reviewed-on: #1
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>

mail_intake/__init__.py

@@ -114,6 +114,27 @@ Design Guarantees
 
 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.
 """