opys-calendar-skill

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

<div align="center">
  <h1>🤖 Opy's Calendar</h1>
  <p><strong>A calendar built specifically for AI agents, and optimized for humans. Designed to work seamlessly with OpenClaw and ClawHub.</strong></p>
</div>

![Main Calendar View](./public/screenshots/main-view.png)

## Overview

Opy's Calendar bridges the gap between AI scheduling and human usability. Traditional web calendars trap data in complex databases or opaque APIs. Opy's Calendar fundamentally shifts this paradigm by storing **everything in Markdown (`.md`) files**. 

This allows your local and remote AI agents (using LLMs) to *natively* read, write, and reason about your schedule, without needing complex integration wiring—while still providing you with a beautiful, fast, and fully-featured React frontend.

![Stats View](./public/screenshots/stats-view.png)

## Highlights

*   🧠 **Agent-Optimized:** Events and settings are saved on disk as plain Markdown and JSON. Your agents can read your schedule like a normal document and modify it instantly.
*   📸 **Agent Snapshots:** Configurable snapshot window sizes so your agents can perfectly recall both historical interactions and upcoming obligations.
*   📊 **Intelligent Stats & Capacity Planning:** Built-in charts break down your time allocation vs. your free capacity based on configurable working hours and subjects. 
*   🔄 **Two-Way Google Calendar Sync:** Full bi-directional synchronization with Google Calendar so you don't have to give up your existing ecosystem. Colors translate perfectly.
*   ⚡️ **Incredibly Fast:** Local-first architecture using Vite and React means zero latency rendering.
*   🎨 **Beautiful UI:** A stunning, Apple-inspired interface with dynamic dark mode, horizontal sliding week views, and categorized event chips.

## How It Works

Your entire calendar lives in a single `calendar.md` file at the root of the project. Categories are defined in the YAML frontmatter, and events are stored serially:

```markdown
---
version: 1
title: O...