#+TITLE: Add Calendar Event Workflow
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2026-02-01

* Overview

Workflow for creating calendar events. Uses the Google Calendar MCP server (preferred) or gcalcli (fallback, personal account only).

* Triggers

- "create an event"
- "add appointment"
- "schedule a meeting"
- "add to my calendar"
- "calendar event for..."

* Prerequisites

- Google Calendar MCP server configured and authenticated (=@cocal/google-calendar-mcp=)
- Two accounts available: =personal= (Craig Google) and =work= (Craig Deepsat)
- Fallback: gcalcli installed (personal account only)

* CRITICAL: Check All Calendars Before Scheduling

Before creating any event, ALWAYS check for conflicts across ALL calendars. Use the MCP =get-freebusy= tool to check availability, or query multiple sources:

1. *MCP server* — check both personal and work accounts via =list-events= or =get-freebusy=
2. *Emacs org files* — for Proton calendar (not accessible via MCP or gcalcli):

#+begin_src bash
grep "2026-02-18" ~/.emacs.d/data/pcal.org   # Proton calendar
#+end_src

Always verify the time slot is free across all calendars before creating.

* Workflow Steps

** 1. Parse Natural Language Input

Interpret the user's request to extract:
- Event title
- Date/time (natural language like "tomorrow 3pm", "next Tuesday at 2")
- Any mentioned location
- Any mentioned description

Examples:
- "Create an event tomorrow at 5pm called Grocery Shopping"
- "Add a meeting with Bob on Friday at 10am"
- "Schedule dentist appointment next Wednesday at 2pm at Downtown Dental"

** 2. Apply Defaults

| Field      | Default Value                    |
|------------+----------------------------------|
| Calendar   | Craig (default Google Calendar)   |
| Reminders  | 5 minutes before, at event time  |
| Duration   | NONE - always ask user           |
| Location   | None (optional)                  |

** 3. Gather Missing Information

*Always ask for:*
- Duration (required, no default)

*Ask if relevant:*
- Location (if not provided and seems like an in-person event)

*Never assume:*
- Duration - this must always be explicitly confirmed

** 4. Show Event Summary

Present the event in plain English (NOT the gcalcli command):

#+begin_example
Event: Grocery Shopping
When: Tomorrow (Feb 2) at 5:00 PM
Duration: 1 hour
Location: (none)
Reminders: 5 min before, at event time
Calendar: Personal
#+end_example

** 5. Explicit Confirmation

Ask: "Create this event? (yes/no)"

*Do NOT create the event until user confirms.*

** 6. Execute

Once confirmed, create the event.

*** MCP (preferred)

Use the =create-event= MCP tool:
- =account_id=: "personal" (default) or "work"
- =calendar_id=: calendar name or ID (default: primary)
- =summary=: event title
- =start=, =end=: ISO 8601 datetime (e.g., "2026-02-15T14:00:00-06:00")
- =location=: location string (optional)
- =description=: event notes (optional)
- =reminders=: custom reminders (optional)

*** gcalcli (fallback, personal account only)

#+begin_src bash
gcalcli --calendar "Calendar Name" add \
  --title "Event Title" \
  --when "date and time" \
  --duration MINUTES \
  --where "Location" \
  --description "Description" \
  --reminder 5 \
  --reminder 0 \
  --noprompt
#+end_src

** 7. Verify

Confirm the event was created:

*** MCP
Use =search-events= or =list-events= to verify.

*** gcalcli (fallback)
#+begin_src bash
gcalcli --calendar "Calendar Name" search "Event Title"
#+end_src

Report success or failure to user.

* Calendars

| Calendar                  | Access | Account  | Notes                          |
|---------------------------+--------+----------+--------------------------------|
| Craig Google              | owner  | personal | Default — use for most events  |
| Christine                 | owner  | personal | Christine's calendar           |
| Craig Deepsat             | owner  | work     | DeepSat work calendar          |
| Todoist                   | owner  | personal | Todoist integration            |
| Craig Jennings (TripIt)   | reader | personal | View only, no create           |
| Holidays in United States | reader | personal | View only                      |
| Craig Proton              | reader | personal | View only (no API access)      |

* Time Formats

MCP tools use ISO 8601: =2026-02-15T14:00:00-06:00=

gcalcli accepts natural language times:
- "tomorrow 3pm"
- "next Tuesday at 2"
- "2026-02-15 14:00"
- "Feb 15 2pm"
- "today 5pm"

* Duration

MCP uses explicit start/end times (no duration field — calculate end time from start + duration).

gcalcli duration shortcuts:

| Input  | Minutes |
|--------+---------|
| 30m    | 30      |
| 1h     | 60      |
| 1.5h   | 90      |
| 2h     | 120     |
| 90     | 90      |

* Error Handling

** MCP Authentication Error
Use =manage-accounts= MCP tool with =action: "add"= and the account nickname to re-authenticate.

** gcalcli Authentication Error
Run =gcalcli init= to re-authenticate.

** Calendar Not Found
MCP: Use =list-calendars= to see available calendars.
gcalcli: Use =gcalcli list=.

** Invalid Time Format
MCP: Use ISO 8601 format: =YYYY-MM-DDTHH:MM:SS±HH:MM=
gcalcli: Use explicit date format: =YYYY-MM-DD HH:MM=

* Related

- [[file:read-calendar-events.org][Read Calendar Events]] - view events
- [[file:edit-calendar-event.org][Edit Calendar Event]] - modify events
- [[file:delete-calendar-event.org][Delete Calendar Event]] - remove events