feat: start mailbox evidence scanner

README.md

@@ -1,3 +1,34 @@
-# repo-seed
+# email-connect
 
-A git repository template to bootstrap coulomb projects from.
+Headless, provider-neutral email communication and evidence service.
+
+The first implementation slice is the Mailbox Evidence Scanner MVP: scan a
+return mailbox or fixture directory, classify inbound email-channel evidence,
+store scan state locally, and generate timestamped CSV reports without
+overclaiming delivery, awareness, or coordination success.
+
+## Quickstart
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+PYTHONPATH=src python3 -m email_connect.cli adapter-descriptor
+PYTHONPATH=src python3 -m email_connect.cli scan-mailbox --config config/mailbox.example.yml --out reports/
+```
+
+The example config uses `tests/fixtures/mailbox` as a mailbox source. Runtime
+state is written to `.email-connect/state.sqlite`; generated CSV reports are
+written to `reports/`.
+
+## Current Scope
+
+- Coordination-engine spec review and references.
+- Initial adapter descriptor, capability profile, evidence ceiling, and
+  limitations.
+- Conservative mailbox message parser and evidence mapper.
+- SQLite state store with message and evidence deduplication.
+- CSV report generation.
+- Golden fixture tests for hard bounce, soft bounce, out-of-office, and human
+  reply signals.
+
+IMAP access, provider webhooks, outbound sending, suppression workflows, and a
+UI are planned work, not complete in this first slice.