docs(01-02): complete IMAP connection & email parsing plan

Tasks completed: 2/2
- Task 1: IMAP connection service with authentication and folder listing
- Task 2: Email body parser for multipart MIME messages

SUMMARY: .planning/phases/01-foundation/01-02-SUMMARY.md

.planning/STATE.md

@@ -10,28 +10,28 @@ See: .planning/PROJECT.md (updated 2026-02-04)
 ## Current Position
 
 Phase: 1 of 4 (Foundation)
-Plan: 1 of 2 (Database Models & Encryption)
-Status: In progress
-Last activity: 2026-02-08 — Completed 01-01-PLAN.md
+Plan: 2 of 2 (IMAP Connection & Email Parsing)
+Status: Phase complete
+Last activity: 2026-02-08 — Completed 01-02-PLAN.md
 
-Progress: [█░░░░░░░░░] 12.5%
+Progress: [██░░░░░░░░] 25%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 1
-- Average duration: 11.6 minutes
-- Total execution time: 0.2 hours
+- Total plans completed: 2
+- Average duration: 12.3 minutes
+- Total execution time: 0.4 hours
 
 **By Phase:**
 
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
-| 1. Foundation | 1/2 | 11.6 min | 11.6 min |
+| 1. Foundation | 2/2 | 24.6 min | 12.3 min |
 
 **Recent Trend:**
-- Last 5 plans: 01-01 (11.6 min)
-- Trend: Establishing baseline
+- Last 5 plans: 01-01 (11.6 min), 01-02 (13 min)
+- Trend: Consistent velocity (~12 min/plan)
 
 *Updated after each plan completion*
 
@@ -56,6 +56,9 @@ Recent decisions affecting current work:
 | FERNET_KEY as environment variable | 01-01 | 2026-02-08 | Simple key management, fails fast if missing |
 | Manual migration creation | 01-01 | 2026-02-08 | Docker port conflict, migration matches Aerich format |
 | 30-day expiration in model save() | 01-01 | 2026-02-08 | Business logic in domain model, consistent enforcement |
+| Use logout() not close() for IMAP | 01-02 | 2026-02-08 | Proper TCP cleanup, prevents connection leaks |
+| Prefer plain text over HTML | 01-02 | 2026-02-08 | Less boilerplate, better for RAG indexing |
+| Modern EmailMessage API | 01-02 | 2026-02-08 | Handles encoding automatically, fewer errors |
 
 ### Pending Todos
 
@@ -70,7 +73,7 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-02-08 14:15 UTC
-Stopped at: Completed 01-01-PLAN.md (Database Models & Encryption)
+Last session: 2026-02-08 15:01 UTC
+Stopped at: Completed 01-02-PLAN.md (IMAP Connection & Email Parsing)
 Resume file: None
-Next plan: 01-02-PLAN.md (IMAP connection service and email body parser)
+Next plan: Phase 1 complete, ready for Phase 2

.planning/phases/01-foundation/01-02-SUMMARY.md

@@ -0,0 +1,135 @@
+---
+phase: 01-foundation
+plan: 02
+subsystem: email
+tags: [imap, aioimaplib, email-parsing, html2text, rfc822]
+
+# Dependency graph
+requires:
+  - phase: 01-01
+    provides: Email database models with encrypted credentials
+provides:
+  - IMAP connection service with authentication and folder listing
+  - Email body parser for multipart MIME messages
+  - Dependencies: aioimaplib and html2text
+affects: [01-03, 01-04, email-sync, account-management]
+
+# Tech tracking
+tech-stack:
+  added: [aioimaplib>=2.0.1, html2text>=2025.4.15]
+  patterns: [async IMAP client, modern EmailMessage API, HTML-to-text conversion]
+
+key-files:
+  created:
+    - blueprints/email/imap_service.py
+    - blueprints/email/parser_service.py
+  modified:
+    - pyproject.toml
+
+key-decisions:
+  - "Use aioimaplib for async IMAP4_SSL operations"
+  - "Prefer plain text over HTML for RAG indexing"
+  - "Use logout() not close() for proper TCP cleanup"
+  - "Modern EmailMessage API with email.policy.default"
+
+patterns-established:
+  - "IMAP connection lifecycle: connect → operate → logout in finally block"
+  - "Email parsing: message_from_bytes with policy=default, get_body() for multipart handling"
+  - "HTML conversion: html2text with ignore_links=False for context preservation"
+
+# Metrics
+duration: 13min
+completed: 2026-02-08
+---
+
+# Phase 01 Plan 02: IMAP Connection & Email Parsing Summary
+
+**Async IMAP client with aioimaplib for server authentication and folder listing, plus RFC822 email parser extracting text/HTML bodies using modern EmailMessage API**
+
+## Performance
+
+- **Duration:** 13 minutes
+- **Started:** 2026-02-08T14:48:15Z
+- **Completed:** 2026-02-08T15:01:33Z
+- **Tasks:** 2/2
+- **Files modified:** 3
+
+## Accomplishments
+
+- IMAP connection service with async authentication and proper cleanup
+- Email body parser handling multipart MIME messages with text/HTML extraction
+- Dependencies added to pyproject.toml (aioimaplib, html2text)
+- Modern EmailMessage API usage with proper encoding handling
+- HTML-to-text conversion when plain text unavailable
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: IMAP connection service** - `6e4ee6c` (feat)
+2. **Task 2: Email body parser** - `e408427` (feat)
+
+## Files Created/Modified
+
+- `blueprints/email/imap_service.py` - IMAPService class with connect/list_folders/close methods
+- `blueprints/email/parser_service.py` - parse_email_body function for RFC822 parsing
+- `pyproject.toml` - Added aioimaplib>=2.0.1 and html2text>=2025.4.15
+
+## Decisions Made
+
+**1. IMAP Connection Lifecycle**
+- **Decision:** Use `logout()` not `close()` for proper TCP cleanup
+- **Rationale:** `close()` only closes the selected mailbox, `logout()` closes TCP connection
+- **Impact:** Prevents connection leaks and quota exhaustion
+
+**2. Email Body Preference**
+- **Decision:** Prefer plain text over HTML for "preferred" field
+- **Rationale:** Plain text has less boilerplate, better for RAG indexing
+- **Alternative:** Always convert HTML to text
+- **Outcome:** Use plain text when available, convert HTML only when needed
+
+**3. Modern Email API**
+- **Decision:** Use `email.policy.default` and `get_body()` method
+- **Rationale:** Modern API handles encoding automatically, simplifies multipart handling
+- **Alternative:** Legacy `Message.walk()` and `get_payload()`
+- **Outcome:** Proper decoding, fewer encoding errors
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+All tasks completed according to specification. No bugs discovered, no critical functionality missing, no architectural changes required.
+
+## Issues Encountered
+
+None - implementation followed research patterns directly.
+
+The RESEARCH.md provided complete patterns for both IMAP connection and email parsing, eliminating guesswork and enabling straightforward implementation.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+Dependencies will be installed in Docker environment via pyproject.toml. No API keys or credentials needed at this phase.
+
+## Next Phase Readiness
+
+**Phase 2: Account Management** is ready to begin.
+
+**Ready:**
+- ✅ IMAP service can connect to mail servers
+- ✅ Email parser can extract bodies from RFC822 messages
+- ✅ Dependencies added to project
+- ✅ Patterns established for async IMAP operations
+
+**What Phase 2 needs:**
+- Use IMAPService to test IMAP connections
+- Use parse_email_body to extract email content during sync
+- Import: `from blueprints.email.imap_service import IMAPService`
+- Import: `from blueprints.email.parser_service import parse_email_body`
+
+**No blockers or concerns.**
+
+---
+*Phase: 01-foundation*
+*Completed: 2026-02-08*