@mind-your-now/myn 0.8.1 → 0.8.3

package/skills/myn/references/calendar-api.md

@@ -1,50 +1,128 @@
 # Calendar API
 
-Calendar events and meetings management including creation, listing, and deletion.
+Calendar events and meetings management including listing calendars, creating, updating, moving, and deleting events.
 
 ## Base Path
 
 `/api/v2/calendar`
 
+## Actions
+
+The `myn_calendar` tool supports these actions: `list_calendars`, `list_events`, `get_event`, `create_event`, `update_event`, `delete_event`, `move_event`, `meetings`.
+
 ## Endpoints
 
+### List Calendars
+
+```
+GET /api/v1/customers/calendars
+```
+
+Returns all connected calendars with metadata.
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `calendars` | object[] | Array of calendar objects |
+| `calendars[].id` | string | Calendar identifier |
+| `calendars[].name` | string | Calendar display name |
+| `calendars[].using` | boolean | Whether the calendar is active/in use |
+| `calendars[].timeZone` | string | Calendar timezone |
+| `calendars[].accessRole` | string | User's access role |
+| `calendars[].accountEmail` | string | Associated account email |
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v1/customers/calendars"
+```
+
 ### List Events
 
 ```
 GET /api/v2/calendar/events
 ```
 
+Fetches events from all connected calendars within a date range. Descriptions are automatically truncated to 200 chars and attendee lists are stripped to reduce token bloat.
+
 **Query Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `start` | datetime | Filter events starting at or after this time (ISO 8601) |
-| `end` | datetime | Filter events ending at or before this time (ISO 8601) |
-| `calendarId` | string | Filter by specific calendar |
-| `allDay` | boolean | Filter for all-day events only |
+| `start` | datetime | Start of range (ISO 8601). Defaults to today |
+| `end` | datetime | End of range (ISO 8601). Defaults to start + 7 days |
 | `limit` | number | Max results (default: 50) |
 
-```bash
-# List events for this week
-curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/calendar/events?start=2026-03-01T00:00:00Z&end=2026-03-07T23:59:59Z"
+**Tool Parameters:**
 
-# List only all-day events
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `startDate` | datetime | Maps to `start` query param |
+| `endDate` | datetime | Maps to `end` query param |
+| `daysAhead` | number | Alternative to `endDate` — computes end date N days from now |
+| `limit` | number | Max results (default: 50) |
+
+**Response:**
+
+```json
+{
+  "events": [
+    {
+      "id": "google-event-id-123",
+      "title": "Team Standup",
+      "startTime": "2026-03-09T09:00:00",
+      "endTime": "2026-03-09T09:30:00",
+      "location": "Conference Room B",
+      "calendarId": "primary",
+      "calendarName": "Edward Becker",
+      "provider": "google",
+      "allDay": false,
+      "taskId": "550e8400-e29b-41d4-a716-446655440000",
+      "status": "confirmed"
+    }
+  ],
+  "total": 1,
+  "start": "2026-03-09T00:00:00",
+  "end": "2026-03-16T00:00:00"
+}
+```
+
+**Note:** When a calendar event is linked to a MYN task, the response includes a `taskId` field (UUID string) referencing the linked task.
+
+### Get Event
+
+```
+GET /api/v2/calendar/events/{eventId}
+```
+
+Returns full details for a single event including description and attendees. Results are cached in-memory (10-minute TTL) with hash-based change detection.
+
+**Required Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `eventId` | string | Calendar event ID |
+
+**Response:** Full event object plus `_cached` (boolean, whether unchanged since last fetch) and `_hash` (content hash).
+
+```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/calendar/events?allDay=true&limit=10"
+  "$MYN_API_URL/api/v2/calendar/events/EVENT_ID"
 ```
 
 ### Create Event
 
 ```
-POST /api/v2/calendar/events
+POST /api/v2/calendar/standalone-events
 ```
 
+Creates a new calendar event (not linked to a MYN task).
+
 **Required Fields:**
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `title` | string | Event title |
+| `title` | string | Event title (1-200 chars) |
 | `startTime` | datetime | Start time (ISO 8601) |
 | `endTime` | datetime | End time (ISO 8601, required for non-all-day events) |
 
@@ -52,17 +130,24 @@ POST /api/v2/calendar/events
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `isAllDay` | boolean | Whether this is an all-day event (default: false) |
-| `description` | string | Event description |
+| `isAllDay` | boolean | All-day event (default: false) |
+| `description` | string | Event description (max 2000 chars) |
 | `location` | string | Event location |
 | `calendarId` | string | Target calendar ID |
-| `attendees` | string[] | List of attendee email addresses |
-| `recurrence` | string | Recurrence rule (RRULE format, e.g., `FREQ=WEEKLY;BYDAY=MO,WE,FR`) |
-| `reminders` | object[] | Reminders, each with `minutes` (number) and `method` (`popup` or `email`) |
+| `calendarName` | string | Calendar name to resolve to ID (e.g. "Family", "Work") |
+| `attendees` | string[] | Email addresses, household member first names, or "family"/"everyone" to invite all household members |
+| `timezone` | string | Timezone (e.g., "America/New_York") |
+| `recurrence` | string | RRULE format (e.g., `FREQ=WEEKLY;BYDAY=MO,WE,FR`) |
+| `reminders` | object[] | Each with `minutes` (number) and `method` (`popup` or `email`) |
+
+**Calendar Selection Logic:**
+1. Explicit `calendarId` takes precedence
+2. `calendarName` is resolved by fuzzy match against available calendars
+3. If attendees include household members, auto-detects family/shared calendar
+4. Falls back to "primary"
 
 ```bash
-# Create a one-time meeting
-curl -X POST "$MYN_API_URL/api/v2/calendar/events" \
+curl -X POST "$MYN_API_URL/api/v2/calendar/standalone-events" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
@@ -73,18 +158,42 @@ curl -X POST "$MYN_API_URL/api/v2/calendar/events" \
     "attendees": ["alice@example.com", "bob@example.com"],
     "reminders": [{"minutes": 10, "method": "popup"}]
   }'
+```
 
-# Create a recurring all-day event
-curl -X POST "$MYN_API_URL/api/v2/calendar/events" \
+### Update Event
+
+```
+PATCH /api/v2/calendar/standalone-events/{eventId}?calendarId={calendarId}
+```
+
+Updates an existing calendar event. Only provided fields are changed.
+
+**Required Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `eventId` | string | Calendar event ID |
+
+**Update Fields (all optional, at least one required):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `newTitle` | string | New title |
+| `newDescription` | string | New description |
+| `newLocation` | string | New location |
+| `newStartTime` | datetime | New start time (ISO 8601) |
+| `newEndTime` | datetime | New end time (ISO 8601) |
+| `newAttendees` | string[] | Replace attendee list (email addresses or household member names) |
+| `addAttendees` | string[] | Add to existing attendee list |
+| `calendarId` | string | Calendar ID (defaults to "primary") |
+| `calendarName` | string | Calendar name to resolve |
+| `timezone` | string | Timezone for start/end times |
+
+```bash
+curl -X PATCH "$MYN_API_URL/api/v2/calendar/standalone-events/EVENT_ID?calendarId=primary" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
-  -d '{
-    "title": "Sprint review",
-    "startTime": "2026-03-06T00:00:00Z",
-    "isAllDay": true,
-    "recurrence": "FREQ=WEEKLY;INTERVAL=2;BYDAY=FR",
-    "description": "Bi-weekly sprint review"
-  }'
+  -d '{"title": "Updated meeting title", "location": "Room C"}'
 ```
 
 ### Delete Event
@@ -93,47 +202,60 @@ curl -X POST "$MYN_API_URL/api/v2/calendar/events" \
 DELETE /api/v2/calendar/events/{eventId}
 ```
 
+**Uses read-before-write guard** (agent reads event state hash before deleting).
+
 ```bash
-curl -X DELETE "$MYN_API_URL/api/v2/calendar/events/550e8400-e29b-41d4-a716-446655440000" \
-  -H "X-API-KEY: $MYN_API_KEY"
+curl -X DELETE "$MYN_API_URL/api/v2/calendar/events/EVENT_ID" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "X-MYN-State-Hash: abc123"
 ```
 
-### List Meetings
+### Move Event
 
 ```
-GET /api/v2/calendar/meetings
+POST /api/v2/calendar/standalone-events/{eventId}/move?sourceCalendarId={source}&destinationCalendarId={destination}
 ```
 
-Returns upcoming meetings with attendee information. This is a convenience view over calendar events filtered to multi-attendee meetings.
+Moves an event from one calendar to another.
 
-**Query Parameters:**
+**Required Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `includePast` | boolean | Include past meetings (default: false) |
-| `daysAhead` | number | Number of days to look ahead (default: 7) |
-| `limit` | number | Max results |
+| `eventId` | string | Calendar event ID |
+| `destinationCalendarId` | string | Target calendar ID (or use `destinationCalendarName`) |
 
-**Response Fields:**
+**Optional Parameters:**
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `meetings` | object[] | Array of meeting objects |
-| `meetings[].id` | string | Meeting/event ID |
-| `meetings[].title` | string | Meeting title |
-| `meetings[].startTime` | datetime | Start time |
-| `meetings[].endTime` | datetime | End time |
-| `meetings[].attendees` | string[] | List of attendee emails |
-| `meetings[].location` | string | Meeting location (nullable) |
-| `meetings[].isRecurring` | boolean | Whether the meeting recurs |
-| `total` | number | Total matching meetings |
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `destinationCalendarName` | string | Target calendar name (resolved by fuzzy match) |
+| `sourceCalendarId` | string | Source calendar ID (defaults to "primary") |
 
 ```bash
-# Get meetings for the next 7 days
-curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/calendar/meetings"
+curl -X POST "$MYN_API_URL/api/v2/calendar/standalone-events/EVENT_ID/move?sourceCalendarId=primary&destinationCalendarId=DEST_ID" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+### Meetings
 
-# Get meetings for the next 14 days including past
+```
+GET /api/v2/calendar/events (filtered to events with attendees)
+```
+
+Returns upcoming meetings (events that have attendees). This action uses the standard events endpoint with date range filtering, then filters to only events with attendees.
+
+**Tool Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `includePast` | boolean | Include today's past meetings (default: false) |
+| `daysAhead` | number | Days to look ahead (default: 7) |
+| `limit` | number | Max results |
+
+```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/calendar/meetings?daysAhead=14&includePast=true&limit=25"
+  "$MYN_API_URL/api/v2/calendar/events?start=2026-03-09T00:00:00&end=2026-03-16T00:00:00"
 ```

package/skills/myn/references/debrief-api.md

@@ -0,0 +1,182 @@
+# Daily Debrief API
+
+Daily Debrief system for AI-generated daily planning sessions with corrections and completion tracking.
+
+## Base Path
+
+`/api/v2/debrief`
+
+## Actions
+
+The `myn_debrief` tool supports these actions: `status`, `generate`, `get`, `apply_correction`, `complete_session`.
+
+## Endpoints
+
+### Get Session Status
+
+```
+GET /api/v2/debrief/status
+```
+
+Returns the current debrief session state.
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `hasActiveSession` | boolean | Whether a debrief session is currently active |
+| `sessionId` | UUID | Current session ID (nullable) |
+| `lastDebriefId` | UUID | ID of the most recent debrief (nullable) |
+| `lastDebriefTime` | datetime | Timestamp of the most recent debrief (nullable) |
+| `pendingCorrections` | number | Count of unprocessed corrections |
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/debrief/status"
+```
+
+### Generate Debrief
+
+```
+POST /api/v2/debrief/generate
+```
+
+Generates a new Daily Debrief with prioritized task lists and suggestions.
+
+**Body Parameters:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | string | Debrief type: `DAILY`, `EVENING`, `WEEKLY`, `WEEKLY_AND_DAILY`, `ON_DEMAND` (default: `DAILY`) |
+| `context` | string | Optional context to guide the debrief (e.g., "busy morning, meetings after 2pm") |
+| `focusAreas` | string[] | Optional focus areas to emphasize (e.g., `["health", "work deadlines"]`) |
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `debriefId` | UUID | Unique debrief identifier |
+| `sessionId` | UUID | Session this debrief belongs to |
+| `summary` | string | Natural language summary of the day |
+| `criticalNow` | object[] | Tasks requiring immediate attention |
+| `opportunityNow` | object[] | Tasks worth doing if time allows |
+| `overTheHorizon` | object[] | Tasks to keep in mind for later |
+| `upcomingMeetings` | object[] | Meetings and calendar events today |
+| `habitsDue` | object[] | Habits scheduled for today |
+| `suggestions` | string[] | AI-generated actionable suggestions |
+| `createdAt` | datetime | Debrief generation timestamp |
+
+```bash
+# Generate a basic daily debrief
+curl -X POST "$MYN_API_URL/api/v2/debrief/generate" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "DAILY"}'
+
+# Generate with context and focus areas
+curl -X POST "$MYN_API_URL/api/v2/debrief/generate" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "DAILY",
+    "context": "Working from home today, low energy",
+    "focusAreas": ["health", "project deadlines"]
+  }'
+
+# Evening debrief
+curl -X POST "$MYN_API_URL/api/v2/debrief/generate" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"type": "EVENING"}'
+```
+
+### Get Current Debrief
+
+```
+GET /api/v2/debrief/current
+```
+
+Returns the most recent debrief without generating a new one. Used both for the `get` action (with or without `debriefId`).
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/debrief/current"
+```
+
+### Submit Correction
+
+```
+POST /api/v2/debrief/corrections/apply
+```
+
+Submits a correction to update the active debrief session when reality diverges from the plan.
+
+**Uses read-before-write guard** -- reads current debrief state hash before applying.
+
+**Body Parameters:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | string | **Required.** One of: `TASK_COMPLETED`, `TASK_MISSED`, `TASK_RESCHEDULED`, `TASK_ADDED`, `PRIORITY_CHANGED`, `OTHER` |
+| `data` | object | Optional data relevant to the correction type (e.g., `{"taskId": "..."}`) |
+| `reason` | string | Optional human-readable reason for the correction |
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `correctionId` | UUID | Unique correction identifier |
+| `appliedAt` | datetime | When the correction was applied |
+| `debriefUpdated` | boolean | Whether the active debrief was re-ranked |
+
+```bash
+curl -X POST "$MYN_API_URL/api/v2/debrief/corrections/apply" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "X-MYN-State-Hash: abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "TASK_COMPLETED",
+    "data": {"taskId": "550e8400-e29b-41d4-a716-446655440000"},
+    "reason": "Finished the report early"
+  }'
+```
+
+### Complete Session
+
+```
+POST /api/v2/debrief/complete
+```
+
+Ends the active debrief session with an optional summary and decisions record.
+
+**Uses read-before-write guard** -- reads current debrief state hash before completing.
+
+**Body Parameters:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `summary` | string | Optional end-of-session summary |
+| `decisions` | string[] | Optional list of key decisions made during the session |
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sessionId` | UUID | The completed session ID |
+| `completedAt` | datetime | Session completion timestamp |
+| `nextSessionRecommended` | datetime | Suggested time for next debrief (nullable) |
+| `followUps` | object[] | Auto-generated follow-up items |
+
+```bash
+curl -X POST "$MYN_API_URL/api/v2/debrief/complete" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "X-MYN-State-Hash: abc123" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "summary": "Productive morning, cleared all Critical Now items",
+    "decisions": [
+      "Postponed quarterly review to Friday",
+      "Delegated invoice follow-up to Sarah"
+    ]
+  }'
+```