diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index ba514d5..abfe4d3 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -810,6 +810,48 @@ const orderParams = {
 }
 ```
 
+### 5. Nextcloud Deck Roadmap Sync
+**Purpose:** Visual kanban board for tracking optimization roadmap progress
+
+**Key Components:**
+- `scripts/discover-deck-ids.sh` - Find Nextcloud Deck board/stack IDs
+- `scripts/sync-roadmap-to-deck.py` - Sync roadmap files to Deck cards
+- `docs/NEXTCLOUD_DECK_SYNC.md` - Complete documentation
+
+**Workflow:**
+```bash
+# One-time setup (already done)
+bash scripts/discover-deck-ids.sh  # Creates /tmp/deck-config.json
+
+# Sync roadmap to Deck (creates/updates cards)
+python3 scripts/sync-roadmap-to-deck.py --init
+
+# Always dry-run first to preview changes
+python3 scripts/sync-roadmap-to-deck.py --init --dry-run
+```
+
+**Stack Mapping:**
+- 📥 **Backlog:** Future phases, ideas, ML work (status: FUTURE)
+- 📋 **Planning:** Next phases, ready to implement (status: PENDING, NEXT)
+- 🚀 **In Progress:** Currently active work (status: CURRENT, IN PROGRESS, DEPLOYED)
+- ✅ **Complete:** Finished phases (status: COMPLETE)
+
+**Card Structure:**
+- 3 high-level initiative cards (from `OPTIMIZATION_MASTER_ROADMAP.md`)
+- 18 detailed phase cards (from individual roadmap files)
+- Total: 21 cards tracking all optimization work
+
+**When to Sync:**
+- After completing a phase (update markdown status → re-sync)
+- When starting new phase (move card in Deck UI)
+- Weekly during active development to keep visual state current
+
+**Important Notes:**
+- API doesn't support duplicate detection - always use `--dry-run` first
+- Manual card deletion required (API returns 405 on DELETE)
+- Code blocks auto-removed from descriptions (prevent API errors)
+- Card titles cleaned (no markdown, emojis removed for readability)
+
 ## Testing Commands
 
 ```bash
@@ -1389,6 +1431,13 @@ if (!enabled) {
       ```
     - Types: `feat:` (feature), `fix:` (bug fix), `docs:` (documentation), `refactor:` (code restructure)
     - This is NOT optional - code exists only when committed and pushed
+13. **NEXTCLOUD DECK SYNC (MANDATORY):** After completing phases or making significant roadmap progress:
+    - Update roadmap markdown files with new status (🔄 IN PROGRESS, ✅ COMPLETE, 🔜 NEXT)
+    - Run sync to update Deck cards: `python3 scripts/sync-roadmap-to-deck.py --init`
+    - Move cards between stacks in Nextcloud Deck UI to reflect progress visually
+    - Backlog (📥) → Planning (📋) → In Progress (🚀) → Complete (✅)
+    - Keep Deck in sync with actual work - it's the visual roadmap tracker
+    - Documentation: `docs/NEXTCLOUD_DECK_SYNC.md`
 
 ## Development Roadmap