# 📅 "Add to Calendar" Button — UX Specification

**Author:** Daedalus 🎨  
**Director:** Matt  
**Date:** 2026-04-28  
**Status:** Ready for Socrates implementation  
**Depends on:** Icarus Telegram bot, `calendar_sync.py`, `appointment_parser.py`

---

## 1. Context & Problem

When Icarus processes a document (photo, PDF, email) and detects an appointment or event, the briefing card currently just *tells* the user about it. There's no way to act on that information from within Telegram.

**The ask:** Add an "Add to Calendar" button to briefing cards that contain appointment/event data, with a confirmation flow that shows exactly what was added and offers undo.

---

## 2. Trigger Conditions

The calendar button row appears on a briefing message **only when** the pipeline extracts appointment-eligible data:

| Condition | Show Button? |
|-----------|-------------|
| `category` is `"appointment"` or `"event"` | ✅ Yes |
| `key_details` contains `date` or `start` field | ✅ Yes |
| `suggested_actions` contains "Add to calendar" or calendar-adjacent verb | ✅ Yes |
| `category` is `"info"` with no date | ❌ No |
| `category` is `"reminder"` with no date | ❌ No |

**Logic:** If the LLM produces a parsed appointment (via `appointment_parser.py`) with a valid `start` datetime, the button row is rendered. If no appointment can be constructed (missing date, ambiguous time), the button row is omitted and the briefing falls back to text-only.

---

## 3. Briefing Card Layout (Updated)

### Before (text-only):

```
📋 *Dental Cleaning*

Sullivan's dental cleaning appointment at West Side Dental.

*Key Details:*
• Date: May 3, 2026
• Time: 2:00 PM
• Location: West Side Dental

*Confidence: 95%*
```

### After (with action buttons):

```
📋 *Dental Cleaning*

Sullivan's dental cleaning appointment at West Side Dental.

*Key Details:*
• Date: May 3, 2026
• Time: 2:00 PM
• Location: West Side Dental

*Confidence: 95%*

[🗓️ Add to Calendar]  [✏️ Edit Details]
```

### Layout Rules

| Element | Specification |
|---------|--------------|
| Button row | Single row, two buttons |
| Primary button | `🗓️ Add to Calendar` — leftmost, always present when triggered |
| Secondary button | `✏️ Edit Details` — rightmost, present when editable fields exist |
| Message format | MarkdownV2 (consistent with recipe toggle) |
| Keyboard type | `InlineKeyboardMarkup` |
| Maximum buttons | 2 per row (Telegram mobile UX) |

---

## 4. Button States & Callback Data

### Callback Data Format

```
calendar:add:{briefing_id}     → Add extracted appointment to Google Calendar
calendar:edit:{briefing_id}    → Open edit flow (future phase)
calendar:delete:{event_id}     → Remove event from calendar (undo)
calendar:done:{briefing_id}    → Dismiss confirmation card
```

Where `{briefing_id}` is a unique ID generated from the briefing (hash of summary + date), and `{event_id}` is the Google Calendar event ID returned after insertion.

### State Machine

```
┌─────────────────────────────────────────────────────────┐
│                    INITIAL STATE                         │
│                                                         │
│  Briefing card with inline keyboard:                    │
│  [🗓️ Add to Calendar]  [✏️ Edit Details]              │
│                                                         │
│  User taps "Add to Calendar"                            │
│         │                                               │
│         ▼                                               │
│  LOADING STATE                                          │
│  Message edits to:                                      │
│  "⏳ Adding to calendar..."                             │
│  Keyboard: [⏳ Adding...] (single disabled-style btn)   │
│                                                         │
│         │                                               │
│         ├── success ──→ SUCCESS STATE                   │
│         └── error ────→ ERROR STATE                     │
└─────────────────────────────────────────────────────────┘
```

---

## 5. Confirmation Card (Success State)

After the event is successfully added to Google Calendar, the message is **edited in place** (same chat message, same `message_id`) to show:

```
✅ *Added to Calendar*

_Dental Cleaning_
May 3, 2026 at 2:00 PM
West Side Dental

[✏️ Edit Event]  [🗑️ Delete]
```

### Specification

| Element | Format |
|---------|--------|
| Header | `✅ *Added to Calendar*` |
| Event title | `_Title_` (italic in MarkdownV2) |
| Date/time | Single line: `May 3, 2026 at 2:00 PM` |
| Location | Below date (omitted if empty) |
| Button row 1 | `[✏️ Edit Event]` `[🗑️ Delete]` |
| No "Done" button | Telegram inline keyboards auto-dismiss after timeout or user scrolls away |

**Design rationale:** Showing the exact event details (not just "Success!") builds trust. The user can verify at a glance that the right date, time, and location were captured. The Delete button provides immediate undo — no need to open Google Calendar.

### Message Text Template (MarkdownV2)

```
✅ *Added to Calendar*

_{title}*
{date\_formatted} at {time\_formatted}
{location\_line}

_Confidence: {confidence}%_
```

Where:
- `{title}` = appointment summary (escaped for MarkdownV2)
- `{date_formatted}` = human-readable date (e.g., "May 3, 2026")
- `{time_formatted}` = human-readable time (e.g., "2:00 PM")
- `{location_line}` = location if present, empty line otherwise
- `{confidence}` = extraction confidence percentage

**Location line:** Only rendered if location is non-empty:
```
📍 {location}     ← with pin emoji if location exists
```

### Inline Keyboard (Success State)

```python
keyboard = {
    "inline_keyboard": [
        [
            {"text": "✏️ Edit Event", "callback_data": f"calendar:edit:{event_id}"},
            {"text": "🗑️ Delete", "callback_data": f"calendar:delete:{event_id}"},
        ]
    ]
}
```

---

## 6. Delete Confirmation (Undo Flow)

When the user taps `🗑️ Delete`:

### Step 1: Confirm intent

The message edits to show a deletion confirmation:

```
⚠️ *Delete Event?*

_Dental Cleaning_
May 3, 2026 at 2:00 PM
West Side Dental

This will remove the event from your calendar.

[✅ Yes, Delete]  [❌ Cancel]
```

### Step 2: On confirm

Message edits to:

```
🗑️ *Event Deleted*

_Dental Cleaning_ has been removed from the calendar.
```

(No inline keyboard — final state.)

### Step 2: On cancel

Message reverts to the Success State card (Section 5).

### Callback Data

```
calendar:confirm_delete:{event_id}     → Confirm deletion
calendar:cancel_delete:{briefing_id}   → Cancel, revert to success state
```

---

## 7. Error State

If calendar insertion fails (API error, auth issue, network timeout):

```
❌ *Could Not Add to Calendar*

_Dental Cleaning_
May 3, 2026 at 2:00 PM

Error: {user_friendly_error_message}

[🔄 Retry]  [📋 Copy Details]
```

| Element | Specification |
|---------|---------------|
| Header | `❌ *Could Not Add to Calendar*` |
| Event details | Title, date, time (so user can manually add) |
| Error message | User-friendly, NOT a stack trace |
| Retry button | `🔄 Retry` → re-attempts the same calendar insertion |
| Copy button | `📋 Copy Details` → sends the event details as plain text in a new message so user can paste into Google Calendar manually |

### Error Categories & Messages

| Error | User Message |
|-------|-------------|
| Google API 401/403 | "Calendar permission denied. Check that the service account has edit access." |
| Google API 409 (conflict) | "This event conflicts with an existing calendar event." |
| Google API 429 (rate limit) | "Calendar is busy. Try again in a moment." |
| Network timeout | "Couldn't reach Google Calendar. Check your connection." |
| Generic/unknown | "Something went wrong adding this event." |

### Callback Data (Error State)

```
calendar:retry:{briefing_id}           → Re-attempt calendar insertion
calendar:copy_details:{briefing_id}    → Send event details as plain text message
```

---

## 8. Edit Flow (Future Phase — Stub)

The `✏️ Edit Event` button on the confirmation card and `✏️ Edit Details` on the initial card are **stubs for a future phase**. For now:

**Initial card `✏️ Edit Details`:**
- Callback: `calendar:edit:{briefing_id}`
- Response: `answerCallbackQuery("Edit flow coming soon!")` with toast text
- No message edit — button just shows a temporary toast

**Confirmation card `✏️ Edit Event`:**
- Same stub behavior

**Future implementation** will allow inline editing of:
- Date/time
- Title
- Location
- Duration

This is deliberately deferred. The primary action (Add to Calendar) is the MVP.

---

## 9. Loading State

When the user taps `🗓️ Add to Calendar`, the message immediately edits to show a loading state while the backend processes:

```
⏳ *Adding to Calendar\.\.\.*

_Dental Cleaning_
May 3, 2026 at 2:00 PM
West Side Dental
```

**Inline keyboard during loading:**
```python
keyboard = {
    "inline_keyboard": [
        [
            {"text": "⏳ Adding...", "callback_data": "calendar:noop"}
        ]
    ]
}
```

**Design rationale:**
- Immediate visual feedback that something is happening
- The `⏳ Adding...` button is non-functional (callback_data is `noop`) — prevents double-taps
- Message is edited in-place (same message_id) — no new message spam
- If the operation takes >5 seconds, the text remains as-is (no timeout message needed — the Telegram API call will either succeed or fail)

**Transition:** On success, the same message is edited again to the Success State. On error, edited to Error State. No intermediate "new" messages.

---

## 10. Data Flow (Sequence)

```
User sends document/photo to Icarus bot
    │
    ▼
Vision pipeline processes document
    │
    ▼
Briefing generated with extracted appointment data
    │
    ├── Has appointment data? ──YES──► Build briefing + inline keyboard
    │                                      │
    │                                      ▼
    │                               Send message with:
    │                               - MarkdownV2 briefing text
    │                               - InlineKeyboardMarkup with calendar buttons
    │
    └── No appointment data ──► Send text-only briefing (no keyboard)

User taps [🗓️ Add to Calendar]
    │
    ▼
Callback: calendar:add:{briefing_id}
    │
    ▼
1. Edit message → Loading state (⏳)
2. answerCallbackQuery() (no toast — visual edit is sufficient)
    │
    ▼
3. Call calendar_sync.create_event() with extracted appointment data
    │
    ├── SUCCESS ──► Edit message → Success card with [✏️ Edit] [🗑️ Delete]
    │                  answerCallbackQuery("✅ Added!")
    │
    └── ERROR ────► Edit message → Error card with [🔄 Retry] [📋 Copy]
                     answerCallbackQuery("❌ Failed to add")
```

---

## 11. Appointment Data Extraction

The calendar button needs structured appointment data. The `appointment_parser.py` module already extracts this. The briefing card must carry this data alongside the rendered text.

### Briefing Response Schema (Extended)

The `/vision/briefing` API response (and the internal briefing dict) must include:

```python
{
    "title": "Dental Cleaning",
    "summary": "Sullivan's dental cleaning appointment...",
    "key_details": {
        "date": "2026-05-03",
        "time": "2:00 PM",
        "location": "West Side Dental",
        "contact": "(920) 555-0123",
    },
    "suggested_actions": ["Sign permission slip"],
    "confidence": 0.95,
    "category": "appointment",
    
    # NEW: Structured appointment data (null if not an appointment)
    "appointment": {
        "summary": "Dental Cleaning",
        "start": "2026-05-03T14:00:00-05:00",  # ISO 8601, Chicago timezone
        "end": "2026-05-03T14:30:00-05:00",      # ISO 8601, Chicago timezone
        "location": "West Side Dental",
        "description": "Sullivan's dental cleaning appointment. Source: photo sent via Telegram.",
        "who": ["sully"],
    },
    
    # NEW: Unique ID for callback data (deterministic hash)
    "briefing_id": "dental-cleaning-20260503-ab3f"
}
```

### `briefing_id` Generation

```python
import hashlib

def generate_briefing_id(summary: str, start_iso: str) -> str:
    """Generate a deterministic, URL-safe briefing ID."""
    raw = f"{summary}|{start_iso}".lower().strip()
    hash_part = hashlib.sha256(raw.encode()).hexdigest()[:6]
    slug = summary.lower().replace(" ", "-")[:20]
    return f"{slug}-{hash_part}"
```

This ensures:
- Same document → same briefing_id (idempotent)
- Different appointments → different IDs (no collision)
- URL-safe for callback_data (max 64 bytes per Telegram spec)

### What Socrates Needs to Implement

1. **Extend the briefing pipeline** to extract structured appointment data alongside the text briefing when `category == "appointment"` or `"event"`.
2. **Add `briefing_id`** to the briefing response.
3. **Create a temporary state store** (SQLite, like `recipe_toggle`) to map `briefing_id` → appointment data, so the callback handler can reconstruct the event for calendar insertion.
4. **Implement callback handlers** for `calendar:add`, `calendar:delete`, `calendar:confirm_delete`, `calendar:cancel_delete`, `calendar:retry`, `calendar:noop`, and `calendar:copy_details`.
5. **Wire up the Telegram handler** to render inline keyboards when appointment data is present.

---

## 12. SQLite Schema (Calendar State)

```sql
CREATE TABLE calendar_pending (
    briefing_id TEXT PRIMARY KEY,
    chat_id INTEGER NOT NULL,
    message_id INTEGER NOT NULL,
    summary TEXT NOT NULL,
    start_iso TEXT NOT NULL,        -- ISO 8601 datetime (Chicago timezone)
    end_iso TEXT NOT NULL,           -- ISO 8601 datetime (Chicago timezone)
    location TEXT DEFAULT '',
    description TEXT DEFAULT '',
    who TEXT DEFAULT '[]',           -- JSON array of family member IDs
    source TEXT DEFAULT '',           -- "photo", "pdf", "email"
    confidence REAL DEFAULT 0.0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE calendar_events (
    event_id TEXT PRIMARY KEY,        -- Google Calendar event ID
    briefing_id TEXT NOT NULL,
    chat_id INTEGER NOT NULL,
    message_id INTEGER NOT NULL,      -- The confirmation message ID
    summary TEXT NOT NULL,
    start_iso TEXT NOT NULL,
    added_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

- `calendar_pending`: Stored when briefing is sent, used by `calendar:add` callback to create the event.
- `calendar_events`: Stored after successful insertion, used by `calendar:delete` callback to find and delete the event.
- **TTL:** `calendar_pending` rows expire after 24 hours (stale briefings). `calendar_events` rows persist for undo capability.

---

## 13. Callback Handler Routing

Extend the existing `process_update` callback routing in `handler.py`:

```python
# Current routing
if cb_data.startswith("toggle:"):
    await handle_toggle(callback, bot)
elif cb_data.startswith("commit:"):
    await handle_commit(callback, bot)
elif cb_data.startswith("cancel:"):
    await handle_cancel(callback, bot)
elif cb_data == "clear:groceries":
    await handle_clear_groceries(callback, bot)

# NEW: Calendar action routing
elif cb_data.startswith("calendar:add:"):
    await handle_calendar_add(callback, bot)
elif cb_data.startswith("calendar:delete:"):
    await handle_calendar_delete(callback, bot)
elif cb_data.startswith("calendar:confirm_delete:"):
    await handle_calendar_confirm_delete(callback, bot)
elif cb_data.startswith("calendar:cancel_delete:"):
    await handle_calendar_cancel_delete(callback, bot)
elif cb_data.startswith("calendar:retry:"):
    await handle_calendar_retry(callback, bot)
elif cb_data.startswith("calendar:copy_details:"):
    await handle_calendar_copy_details(callback, bot)
elif cb_data.startswith("calendar:edit:"):
    await handle_calendar_edit(callback, bot)  # stub
elif cb_data == "calendar:noop":
    await bot.answer_callback_query(callback["id"], "")
```

---

## 14. Visual Design Tokens

### Button Styling (Telegram Limitations)

Telegram does not support custom colors or fonts on inline keyboard buttons. All styling is achieved through **emoji + text composition**:

| Button | Text | Emoji | Visual Weight |
|--------|------|-------|--------------|
| **Primary action** | `🗓️ Add to Calendar` | 🗓️ | High — emoji draws eye |
| **Secondary action** | `✏️ Edit Details` | ✏️ | Low — muted, secondary |
| **Loading state** | `⏳ Adding...` | ⏳ | Transitional — clear wait state |
| **Success edit** | `✏️ Edit Event` | ✏️ | Low — secondary action |
| **Success delete** | `🗑️ Delete` | 🗑️ | Medium — destructive but accessible |
| **Confirm delete** | `✅ Yes, Delete` | ✅ | High — requires explicit confirmation |
| **Cancel delete** | `❌ Cancel` | ❌ | Medium — escape hatch |
| **Retry** | `🔄 Retry` | 🔄 | High — error recovery |
| **Copy details** | `📋 Copy Details` | 📋 | Low — fallback action |

### Message Card Typography

| Element | Format | Example |
|---------|--------|---------|
| Status header | `✅ *Bold*` | `✅ *Added to Calendar*` |
| Event title | `_Italic_` | `_Dental Cleaning_` |
| Date/time | Plain text | `May 3, 2026 at 2:00 PM` |
| Location | `📍 {location}` | `📍 West Side Dental` |
| Confidence | `_Italic_` (muted) | `_Confidence: 95%_` |
| Error text | `❌ *Bold*` | `❌ *Could Not Add to Calendar*` |

### Emoji Palette (consistent with Icarus existing patterns)

| Concept | Emoji | Usage |
|---------|-------|-------|
| Calendar | 🗓️ | Primary action button |
| Success | ✅ | Confirmation headers, success states |
| Loading | ⏳ | In-progress states |
| Error | ❌ | Error headers, destructive actions |
| Edit | ✏️ | Edit buttons |
| Delete | 🗑️ | Delete buttons |
| Location | 📍 | Location pin (in message body) |
| Document | 📋 | Briefing header, copy details |
| Warning | ⚠️ | Confirmation prompts |

---

## 15. Edge Cases

| Case | Behavior |
|------|----------|
| **Briefing has date but no time** | Default to all-day event. Show "All day" in confirmation card. |
| **Briefing has ambiguous date** | Do not show calendar button. Fall back to text-only briefing. |
| **Briefing has date + time but no end time** | Default to 1-hour duration. Show time as "2:00 PM – 3:00 PM (1 hr)" in confirmation. |
| **Briefing has multiple appointments** | Show calendar button. On tap, create ALL events. Confirmation card lists all events. |
| **Calendar API is unreachable** | Show error state with retry option. |
| **User taps "Add" on a stale briefing (>24h)** | `answerCallbackQuery("This briefing has expired. Send the document again.")` + edit message to show expired state. |
| **Event already exists (duplicate)** | Detect via `calendar_events` table or Google Calendar search. Show: `ℹ️ This event is already in your calendar.` with [✏️ Edit] [🗑️ Delete] buttons. |
| **User taps "Add" while already loading** | Second tap is ignored (callback_data is `calendar:noop` during loading). |
| **Multi-who appointment** | Create single event, add all `who` members to description. Don't create separate events per person. |

---

## 16. Animation Spec

Telegram inline keyboard buttons don't support custom animations. The "animation" is achieved through **message edits** (same `message_id`, updated text + keyboard):

```
State 1 (Initial):
  Briefing text + [🗓️ Add to Calendar] [✏️ Edit Details]
  
  ⬇️ user taps "Add to Calendar"
  
State 2 (Loading):
  "⏳ Adding to Calendar..." text + [⏳ Adding...]
  
  ⬇️ backend returns success (typically 1-3 seconds)
  
State 3 (Success):
  "✅ Added to Calendar" + event details + [✏️ Edit Event] [🗑️ Delete]
  
  ⬇️ optional: user taps "Delete"
  
State 4 (Confirm Delete):
  "⚠️ Delete Event?" + event details + [✅ Yes, Delete] [❌ Cancel]
  
  ⬇️ user taps "Yes, Delete"
  
State 5 (Deleted):
  "🗑️ Event Deleted" + title (no keyboard, final state)
```

**Timing constraints:**
- Loading → Success transition: typically 1-3 seconds (Google Calendar API latency)
- Callback query acknowledgment: immediate (`answerCallbackQuery` called within 200ms)
- Message edit: as soon as calendar API responds (no artificial delay)

---

## 17. Message Templates (MarkdownV2)

All text must be properly escaped using the `escape_markdown()` function from `recipe_toggle.py` (reused for consistency).

### Initial Briefing Card (with calendar buttons)

```python
def build_briefing_with_calendar(briefing: dict, briefing_id: str) -> tuple[str, dict]:
    """Build briefing message text + inline keyboard for appointment briefings."""
    
    title = escape_markdown(briefing["title"])
    summary = escape_markdown(briefing["summary"])
    confidence = int(briefing.get("confidence", 0.5) * 100)
    
    lines = [
        f"📋 *{title}*",
        "",
        summary,
        "",
    ]
    
    # Key details
    key_details = briefing.get("key_details", {})
    if key_details:
        for key, value in key_details.items():
            if value:
                label = escape_markdown(key.replace("_", " ").title())
                val = escape_markdown(str(value))
                lines.append(f"• {label}: {val}")
        lines.append("")
    
    # Confidence
    lines.append(f"_Confidence: {confidence}%_")
    
    # Keyboard
    keyboard = {
        "inline_keyboard": [
            [
                {"text": "🗓️ Add to Calendar", "callback_data": f"calendar:add:{briefing_id}"},
                {"text": "✏️ Edit Details", "callback_data": f"calendar:edit:{briefing_id}"},
            ]
        ]
    }
    
    return "\n".join(lines), keyboard
```

### Success Confirmation Card

```python
def build_calendar_success(event: dict, event_id: str) -> tuple[str, dict]:
    """Build success confirmation message + keyboard."""
    
    summary = escape_markdown(event["summary"])
    date_str = escape_markdown(event["date_formatted"])  # "May 3, 2026"
    time_str = escape_markdown(event["time_formatted"])  # "2:00 PM"
    location = escape_markdown(event.get("location", ""))
    confidence = event.get("confidence", 0)
    
    lines = [
        f"✅ *Added to Calendar*",
        "",
        f"_{summary}_",
        f"{date_str} at {time_str}",
    ]
    
    if location:
        lines.append(f"📍 {location}")
    
    lines.append("")
    lines.append(f"_Confidence: {confidence}%_")
    
    keyboard = {
        "inline_keyboard": [
            [
                {"text": "✏️ Edit Event", "callback_data": f"calendar:edit:{event_id}"},
                {"text": "🗑️ Delete", "callback_data": f"calendar:delete:{event_id}"},
            ]
        ]
    }
    
    return "\n".join(lines), keyboard
```

### Error Card

```python
def build_calendar_error(briefing_id: str, event: dict, error_msg: str) -> tuple[str, dict]:
    """Build error message + retry/copy keyboard."""
    
    summary = escape_markdown(event["summary"])
    date_str = escape_markdown(event["date_formatted"])
    time_str = escape_markdown(event["time_formatted"])
    error = escape_markdown(error_msg)
    
    lines = [
        f"❌ *Could Not Add to Calendar*",
        "",
        f"_{summary}_",
        f"{date_str} at {time_str}",
        "",
        f"Error: {error}",
    ]
    
    keyboard = {
        "inline_keyboard": [
            [
                {"text": "🔄 Retry", "callback_data": f"calendar:retry:{briefing_id}"},
                {"text": "📋 Copy Details", "callback_data": f"calendar:copy_details:{briefing_id}"},
            ]
        ]
    }
    
    return "\n".join(lines), keyboard
```

### Delete Confirmation Card

```python
def build_delete_confirmation(event: dict, event_id: str) -> tuple[str, dict]:
    """Build delete confirmation message + keyboard."""
    
    summary = escape_markdown(event["summary"])
    date_str = escape_markdown(event["date_formatted"])
    time_str = escape_markdown(event["time_formatted"])
    location = escape_markdown(event.get("location", ""))
    
    lines = [
        f"⚠️ *Delete Event\\?*",
        "",
        f"_{summary}_",
        f"{date_str} at {time_str}",
    ]
    
    if location:
        lines.append(f"📍 {location}")
    
    lines.append("")
    lines.append("This will remove the event from your calendar\\.")
    
    keyboard = {
        "inline_keyboard": [
            [
                {"text": "✅ Yes, Delete", "callback_data": f"calendar:confirm_delete:{event_id}"},
                {"text": "❌ Cancel", "callback_data": f"calendar:cancel_delete:{briefing_id}"},
            ]
        ]
    }
    
    return "\n".join(lines), keyboard
```

---

## 18. Conflict Detection Integration

When the user taps `🗓️ Add to Calendar`, the handler should:

1. **Check for conflicts** using `conflict_engine.detect_conflicts()` with the new event's time range
2. **If no conflicts** → proceed with insertion → Success State
3. **If conflicts found** → show conflict warning before insertion:

```
⚠️ *Calendar Conflict Detected*

_Dental Cleaning_ (May 3, 2:00 PM – 2:30 PM)
conflicts with:

• _Soccer Practice_ (2:00 PM – 3:00 PM)

[🗓️ Add Anyway]  [❌ Cancel]
```

**Callback data:**
```
calendar:add_anyway:{briefing_id}    → Force add despite conflict
calendar:cancel:{briefing_id}        → Cancel, revert to initial state
```

This mirrors the existing conflict detection in `conflict_engine.py` and integrates naturally into the calendar flow.

---

## 19. Accessibility Considerations

- All emoji are **supplementary** — button text is always meaningful without the emoji
- Color is never the sole indicator of state (emoji + text together)
- Loading state uses **both** text change and button change (not just a spinner)
- Delete confirmation requires **explicit two-tap** confirmation (no single-tap destructive actions)
- Error messages are **actionable** (retry or copy), not dead ends

---

## 20. Implementation Checklist (for Socrates)

- [ ] Extend `appointment_parser.py` output or briefing pipeline to include structured `appointment` dict
- [ ] Add `briefing_id` generation to briefing pipeline
- [ ] Create SQLite tables: `calendar_pending`, `calendar_events`
- [ ] Store pending appointment data when briefing is sent with calendar button
- [ ] Implement `handle_calendar_add()` callback handler
- [ ] Implement `handle_calendar_delete()` → `handle_calendar_confirm_delete()` flow
- [ ] Implement `handle_calendar_retry()` callback handler
- [ ] Implement `handle_calendar_copy_details()` callback handler
- [ ] Implement `handle_calendar_edit()` stub (toast: "Coming soon!")
- [ ] Add calendar callback routing to `process_update()` in `handler.py`
- [ ] Add conflict check before calendar insertion
- [ ] Build and test MarkdownV2 message templates
- [ ] Add 24-hour TTL cleanup for `calendar_pending` rows
- [ ] Test: appointment with all fields (title, date, time, location)
- [ ] Test: appointment with date but no time (all-day event)
- [ ] Test: appointment with date + time but no end time (default 1 hour)
- [ ] Test: calendar API timeout → error state → retry
- [ ] Test: duplicate event detection
- [ ] Test: conflict detection before insertion

---

## 21. File References

| File | What to modify |
|------|---------------|
| `icarus/core/telegram/handler.py` | Add calendar callback routing, import new handlers |
| `icarus/core/handlers/calendar_actions.py` | **NEW** — All calendar callback handlers |
| `icarus/core/db/calendar_state.py` | **NEW** — SQLite CRUD for `calendar_pending` and `calendar_events` |
| `icarus/core/conflict_engine.py` | No changes (reuse `detect_conflicts()`) |
| `icarus/core/calendar_sync.py` | No changes (reuse `create_event()`) |
| `icarus/core/vision/pipeline.py` | Add `appointment` dict and `briefing_id` to response |

---

_This spec is the UX contract. Socrates builds to this, Daedalus reviews the result._

— Daedalus 🎨