Calendar Markdown + Google Sync Skill

Use this skill to query/update the local markdown-backed calendar safely and sync it with Google Calendar.

Source of Truth

• File: calendar.md
• Authoritative section: ## Event Records (fenced event YAML blocks)
• Human summary section: ## Event Checklist

Event Identity Rules

• id: local identifier
• externalId: stable cross-system identifier used for dedupe
• googleEventIds: per-calendar Google event mapping
• updatedAt: event-level timestamp for conflict resolution

Do not remove externalId from existing records.

Preferred Interface

Use CLI from repo root:

npm run cli -- <command>

Safe Query Flow

1. Run npm run cli -- summary.
2. If raw markdown is needed, run npm run cli -- export.

Safe Update Flow

1. Add (preferred for new events):

npm run cli -- add --title "..." --start "" --end "" --category [--shift-to-next|--allow-overlap]

1. Update:

npm run cli -- update --id [fields...]

If changing --start or --end, include --shift-to-next or --allow-overlap in non-interactive runs.

1. Check/uncheck:

npm run cli -- check --id or --undone

1. Delete:

npm run cli -- delete --id

1. Add category:

npm run cli -- category-add --id --label "Label" --color "#9ca3af" --description "..."

1. Remove category:

npm run cli -- category-remove --id --reassign

Conflict handling:

• add and time-changing update detect overlaps with existing events.
• Interactive runs can choose accept overlap, shift to next available slot, or provide a custom time.
• Non-interactive runs:
• --shift-to-next to auto-resolve to the next open window.
• --allow-overlap to keep the requested overlapping time.

Agent snapshot output:

• Every mutating CLI command writes a rolling markdown snapshot.
• Default path: ./agent-snapshot.md
• Override with CALENDAR_AGENT_SNAPSHOT.
• Recent window defaults to 14 days and is configurable with CALENDAR_AGENT_DAYS.
• Snapshot also includes upcoming 7 days when events exist.

UI Constraints

• UI does not provide add-event form/button.
• Events are created via CLI agents only.
• UI still supports drag/drop, resize, and check-off.

Google Sync Flow

1. In UI, sign in with Google.
2. Select target calendar via calendar selector controls.
3. Click Sync Now for two-way merge.

Sync state file:

• .calendar-google-sync-state.json

Import/Export

• Export: npm run cli -- export --out backup-calendar.md
• Import: npm run cli -- import --in backup-calendar.md

Notes for Agents

• Keep datetimes in ISO format.
• Prefer CLI operations over manual markdown edits.
• If categories are changed manually in frontmatter, keep id, label, and color fields valid.

Environment Variables

This skill uses the following environment variables (defined in .env):

• Google Calendar Sync (Optional)
• GOOGLE_CLIENT_ID: Google OAuth Client ID
• GOOGLE_CLIENT_SECRET: Google OAuth Client Secret
• GOOGLE_REDIRECT_URI: Should be http://localhost:/api/google/auth/callback

• Agent Configuration (Optional)
• CALENDAR_AGENT_SNAPSHOT: Custom absolute or relative path to write the Markdown snapshot. Defaults to ./agent-snapshot.md.
• CALENDAR_AGENT_DAYS: Number of historical days to include in the snapshot (defaults to 14).
• PORT: API server port (defaults to 8787).
• APP_BASE_URL: Base URL for the frontend UI.