ship docs/ in npm package for agent access

docs/email.md

@@ -149,4 +149,31 @@ Jeśli `from` w panelu = cudza domena (np. `[email protected]`), a sender =
 `[email protected]` — Exchange zablokuje, chyba że aplikacja ma Send-As na tę
 domenę. Najbezpieczniej: `from` = `GRAPH_SENDER` (Wasza skrzynka), a adres
 klienta w `replyTo` (odpowiedzi trafią do klienta). Wtedy Send-As na cudze
-domeny nie jest potrzebny.
+domeny nie jest potrzebny.
+
+## Przełącznik transportu — mailAdapter
+
+`mailAdapter()` to dyspozytor: jeden adapter wpięty w config, wybiera transport
+(SMTP/Graph) przy KAŻDEJ wysyłce, czytając ustawienie z panelu. Dzięki temu
+przełącznik działa w panelu (Payload buduje adapter raz przy starcie, więc nie
+da się podmieniać osobnych adapterów w runtime — dyspozytor deleguje wewnątrz).
+
+```ts
+// payload.config.ts — JEDEN adapter, wybór wewnątrz
+import { mailAdapter } from '@intecion/ipal-kit'
+email: mailAdapter()
+```
+
+Panel → Site Integrations → SMTP → **Email Transport** (SMTP / Microsoft Graph).
+Dyspozytor czyta ten wybór per wysyłka. Guard: jeśli wybrano Graph, ale brak
+sekretów w .env → log + fallback na SMTP (nie cicha awaria).
+
+## Test wysyłki — przycisk w panelu
+
+W tabie SMTP jest przycisk **Send test**: podaj adres, kliknij, wyślij testowy
+mail przez AKTUALNY transport. Pokazuje wynik (✓/✗ z błędem). Endpoint
+`POST /api/ipal/test-email` (admin-only). Zapisz zmiany przed testem — endpoint
+czyta z bazy, nie z pola na ekranie.
+
+> Bezcenne przy diagnozie Graph — od razu widzisz `ErrorSendAsDenied`,
+> `Insufficient privileges` itp. zamiast zgadywać.