1 files changed, 46 insertions, 0 deletions

diff --git a/issues/phase4_step2_efficient_sync.md b/issues/phase4_step2_efficient_sync.md
new file mode 100644
index 0000000..92fa03c
--- /dev/null
+++ b/issues/phase4_step2_efficient_sync.md
@@ -0,0 +1,46 @@
+# Phase 4 Step 2: Efficient Sync Research & Implementation
+
+## Status: COMPLETE
+
+## Goal
+Improve the efficiency of data synchronization to reduce API calls and latency. Previously, the dashboard fetched all data on every refresh.
+
+## Implementation
+
+### Todoist Sync API v9
+- **Endpoint**: `https://api.todoist.com/sync/v9/sync`
+- **Method**: POST with `sync_token` and `resource_types`
+- **Full sync**: When token is `*` or empty, returns all items
+- **Incremental sync**: With valid token, returns only changes since last sync
+- **Response**: Contains `sync_token` (for next request), `full_sync` flag, `items`, `projects`
+
+### Storage
+- New `sync_tokens` table in SQLite for persisting tokens across restarts
+- Store methods: `GetSyncToken()`, `SetSyncToken()`, `ClearSyncToken()`
+- Incremental update methods: `UpsertTask()`, `DeleteTasksByIDs()`
+
+### Handler Logic
+- `fetchTasks()` uses Sync API with stored token
+- If `FullSync=true`: Replace all cached tasks
+- If `FullSync=false`: Merge changes (upsert active, delete completed/deleted)
+- Falls back to cached data on API errors
+
+### Trello Optimization
+- Added `fields` parameter to API calls to reduce response payload:
+  - `GetBoards()`: `fields=id,name`
+  - `GetCards()`: `fields=id,name,idList,due,url,idBoard`
+  - `getLists()`: `fields=id,name`
+
+## Files Modified
+- `migrations/003_add_sync_tokens.sql` (new)
+- `internal/store/sqlite.go` - Added sync token and incremental update methods
+- `internal/api/todoist.go` - Added Sync API support
+- `internal/api/interfaces.go` - Added Sync method to interface
+- `internal/api/trello.go` - Added field filtering
+- `internal/handlers/handlers.go` - Updated fetchTasks to use Sync API
+- `internal/handlers/handlers_test.go` - Updated mock to implement Sync
+
+## Benefits
+- **Todoist**: Reduced data transfer on subsequent syncs (only changes returned)
+- **Trello**: Smaller API responses (only required fields)
+- **Persistence**: Sync token survives restarts, enabling incremental sync on startup