Opys Calendar Skill

---
name: opys-calendar-skill
description: "A local markdown-backed calendar with CLI and optional two-way Google Calendar sync."
---

# 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:

```bash
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 "<ISO>" --end "<ISO>" --category <id> [--shift-to-next|--allow-overlap]`
2. Update:
   `npm run cli -- update --id <event_id> [fields...]`
   If changing `--start` or `--end`, include `--shift-to-next` or `--allow-overlap` in non-interactive runs.
3. Check/uncheck:
   `npm run cli -- check --id <event_id>` or `--undone`
4. Delete:
   `npm run cli -- delete --id <event_id>`
5. Add category:
   `npm run cli -- category-add --id <id> --label "Label" --color "#9ca3af" --description "..."`
6. Remove category:
   `npm run cli -- category-remove --id <id> --reassign <id>`

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:<PORT>/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.