docs: add project planning documents

docs/adrs/adr-006-email-strategy.md

@@ -0,0 +1,79 @@
+# ADR-006: Email Integration
+
+## Status
+Accepted
+
+## Context
+The platform needs to send email notifications for: file changes (to watchers), new comments, conflict alerts, and digest summaries. It must also receive email replies and convert them to comments. Requirement: use Postmark email gateway with plain-text only.
+
+## Decision
+**Postmark HTTP API for outgoing email, Postmark inbound webhook for incoming email.**
+
+### Implementation
+
+1. **Outgoing Email**:
+   - Go adapter using `github.com/keighl/postmark`
+   - Plain-text templates (no HTML)
+   - Message-ID generated per email for threading
+   - Templates: notification, digest, conflict-alert, welcome
+
+2. **Incoming Email**:
+   - Postmark inbound webhook POSTs to `/webhooks/email`
+   - Webhook payload parsed for: from, subject, body, in-reply-to
+   - Reply matched to comment thread via In-Reply-To header
+   - Body converted to plain text comment
+   - Authentication: webhook signature verification
+
+3. **Email Format**:
+   ```
+   From: MD Hub Secure <notifications@example.com>
+   To: user@example.com
+   Subject: [docs/getting-started.md] Comment from Alice
+   Message-ID: <comment-123@example.com>
+   In-Reply-To: <comment-122@example.com>
+   
+   Alice commented on "Getting Started":
+   
+   > This section needs clarification...
+   
+   Reply to this email to add a comment.
+   
+   View online: https://example.com/docs/getting-started#comment-123
+   ```
+
+## Consequences
+
+### Positive
+- Postmark has excellent deliverability reputation
+- Plain-text emails are accessible and lightweight
+- Email threading works in all clients
+- No HTML parsing/rendering security risks
+- Webhook integration is simple and reliable
+
+### Negative
+- Postmark is a paid service (though inexpensive)
+- Requires DNS setup (SPF, DKIM) for deliverability
+- Plain-text limits formatting options (intentional trade-off)
+- Rate limits on Postmark API (mitigated by queue + retry)
+
+## Alternatives Considered
+
+### SMTP Direct Delivery
+- **Pros**: No third-party dependency, full control
+- **Cons**: Complex deliverability management, IP reputation, spam folder issues
+- **Rejected**: Operational burden too high for small team
+
+### SendGrid / Mailgun
+- **Pros**: Similar features to Postmark
+- **Cons**: More expensive at scale, complex APIs
+- **Rejected**: Postmark has better reputation for transactional email
+
+### No Email (In-App Only)
+- **Pros**: Zero email complexity
+- **Cons**: Users must check app for notifications; poor for async collaboration
+- **Rejected**: Email is core to collaboration workflow
+
+## References
+- Postmark API docs: https://postmarkapp.com/developer
+- keighl/postmark Go library: https://github.com/keighl/postmark
+- Email threading RFC: https://www.ietf.org/rfc/rfc2822.txt