docs: add wiki and refresh flat lib with mcp artifacts

- Add hand-written wiki (index, overview, how-to, extending, dev)
  following the platform anatomy
- Remove stale nested docs/lib/mail_intake and regenerate the flat
  lib reference to match docforge.nav.yml
- Regenerate MCP bundle with standardized docstrings

docs/wiki/02_how_to_use.md

@@ -0,0 +1,105 @@
+# 🖥️ How to Use
+
+This page walks through authenticating, ingesting, and parsing mail with the
+built-in Gmail support.
+
+---
+
+## 🔐 Authentication
+
+Create a credential store and an auth provider:
+
+```python
+from mail_intake.auth import MailIntakeGoogleAuth
+from mail_intake.credentials import PickleCredentialStore, RedisCredentialStore
+
+store = PickleCredentialStore(path="token.pickle")          # local dev
+
+auth = MailIntakeGoogleAuth(
+    credentials_path="credentials.json",                    # your OAuth client file
+    store=store,
+    scopes=["https://www.googleapis.com/auth/gmail.readonly"],
+)
+```
+
+> OAuth credentials come from the Google Cloud Console and are provided via
+> file paths — never hard-code tokens or secrets in source. Once authorized,
+> the token is persisted by the credential store and refreshed automatically.
+
+For distributed deployments, use Redis instead of pickle:
+
+```python
+store = RedisCredentialStore(redis_client=redis_client)     # production
+```
+
+---
+
+## 📥 Ingesting messages
+
+Build an adapter and a reader, then iterate:
+
+```python
+from mail_intake.ingestion import MailIntakeReader
+from mail_intake.adapters import MailIntakeGmailAdapter
+
+adapter = MailIntakeGmailAdapter(auth_provider=auth)
+reader = MailIntakeReader(adapter)
+
+for message in reader.iter_messages("from:recruiter@example.com"):
+    print(message.subject, message.from_email, message.timestamp)
+```
+
+Access the full model:
+
+```python
+message.message_id    # provider id
+message.thread_id
+message.body_text     # plain-text body
+message.raw_headers   # unmodified headers dict
+```
+
+---
+
+## 🔖 Ingesting threads
+
+```python
+for thread in reader.iter_threads("subject:Interview"):
+    print(thread.normalized_subject)
+    print(thread.participants)
+    print(len(thread.messages))
+    print(thread.last_activity_at)
+```
+
+`MailIntakeThread` aggregates its messages, participants, and last activity.
+
+---
+
+## 🧪 Parsers
+
+Parsers normalize provider payloads and are used by the reader internally.
+They are also importable on their own:
+
+```python
+from mail_intake.parsers import extract_body, parse_headers, normalize_subject
+```
+
+- `extract_body(...)` — plain-text body extraction.
+- `parse_headers(...)` — structured header parsing.
+- `extract_sender(...)` — sender email/name extraction.
+- `normalize_subject(...)` — subject normalization for threading.
+
+---
+
+## ✅ Checklist
+
+1. Provide OAuth credentials via a file path and a credential store.
+2. Build the `MailIntakeGoogleAuth` provider with the Gmail read-only scope.
+3. Wrap the adapter in a `MailIntakeReader`.
+4. Consume `iter_messages` / `iter_threads`; never call provider APIs directly.
+
+---
+
+## 📚 Read Next
+
+- [Overview](01_overview.md) — layers and domain models.
+- [Extending Mail Intake](03_extending.md) — custom providers and stores.