@mind-your-now/myn 0.4.0

package/skills/myn/references/authentication.md

@@ -0,0 +1,83 @@
+# Authentication
+
+## API Key Setup
+
+MYN uses API key authentication for agent access. Generate a key in the MYN app:
+
+1. Go to **Settings > API Keys**
+2. Click **Create API Key**
+3. Select the `AGENT_FULL` scope (recommended for AI agents — grants access to all non-admin endpoints)
+4. Copy the key (format: `myn_xxxx_...`)
+
+## Making Requests
+
+Include the API key in every request via the `X-API-KEY` header:
+
+```bash
+curl -H "X-API-KEY: myn_xxxx_your_key_here" \
+  https://api.mindyournow.com/api/v2/unified-tasks
+```
+
+Alternative: pass as query parameter `x-api-key` (less secure, avoid in production):
+
+```
+https://api.mindyournow.com/api/v2/unified-tasks?x-api-key=myn_xxxx_your_key_here
+```
+
+## Environment Variables
+
+Set these for the helper script and examples:
+
+```bash
+export MYN_API_URL="https://api.mindyournow.com"
+export MYN_API_KEY="myn_xxxx_your_key_here"
+```
+
+## Scopes
+
+| Scope | Description |
+|-------|------------|
+| `AGENT_FULL` | Full access to all non-admin endpoints (recommended) |
+| `TASKS_LIST` | List tasks only |
+| `TASKS_VIEW` | View individual tasks |
+| `TASKS_CREATE` | Create tasks |
+| `TASKS_UPDATE` | Update tasks |
+| `TASKS_DELETE` | Delete tasks |
+| `TASKS_CALENDAR` | Calendar task operations |
+| `SCHEDULES_*` | Schedule-related endpoints (5 scopes) |
+| `PROJECTS_*` | Project-related endpoints (5 scopes) |
+| `USER_READ` | Read user profile |
+| `ADMIN_FULL` | Admin access (not for agents) |
+
+For AI agents, always use `AGENT_FULL` — it covers all 17 non-admin scopes in a single selection.
+
+## Rate Limits
+
+| Limit | Default |
+|-------|---------|
+| Per-minute | 60 requests |
+| Per-hour | 1,000 requests |
+
+Rate limits are per API key and configurable by the account owner. When rate-limited, the API returns HTTP 429 with a `Retry-After` header.
+
+## Key Format
+
+- **Pattern**: `myn_<type>_<random>`
+- **Storage**: BCrypt-hashed, prefix-indexed for fast lookup
+- **Audit**: Every API key usage is logged (endpoint, method, status code, IP, response time)
+
+## Error Responses
+
+| Status | Meaning |
+|--------|---------|
+| 401 | Missing or invalid API key |
+| 403 | Valid key but insufficient scope |
+| 429 | Rate limit exceeded |
+
+```json
+{
+  "error": "Forbidden",
+  "message": "API key does not have required scope: TASKS_CREATE",
+  "status": 403
+}
+```

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

@@ -0,0 +1,187 @@
+# Briefing API
+
+Compass briefing system for AI-generated daily planning sessions with corrections and completion tracking.
+
+## Base Path
+
+`/api/v2/compass`
+
+## Endpoints
+
+### Get Session Status
+
+```
+GET /api/v2/compass/status
+```
+
+Returns the current briefing session state.
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `hasActiveSession` | boolean | Whether a briefing session is currently active |
+| `sessionId` | UUID | Current session ID (null if no active session) |
+| `lastBriefingId` | UUID | ID of the most recent briefing |
+| `lastBriefingTime` | datetime | Timestamp of the most recent briefing |
+| `pendingCorrections` | number | Count of unprocessed corrections |
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/compass/status"
+```
+
+### Generate Briefing
+
+```
+POST /api/v2/compass/generate
+```
+
+Generates a new Compass briefing with prioritized task lists and suggestions.
+
+**Body Parameters:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `context` | string | Optional context to guide the briefing (e.g., "busy morning, meetings after 2pm") |
+| `focusAreas` | string[] | Optional focus areas to emphasize (e.g., `["health", "work deadlines"]`) |
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `briefingId` | UUID | Unique briefing identifier |
+| `sessionId` | UUID | Session this briefing 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 | Briefing generation timestamp |
+
+```bash
+# Generate a basic briefing
+curl -X POST "$MYN_API_URL/api/v2/compass/generate" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+
+# Generate with context and focus areas
+curl -X POST "$MYN_API_URL/api/v2/compass/generate" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "context": "Working from home today, low energy",
+    "focusAreas": ["health", "project deadlines"]
+  }'
+```
+
+### Get Latest Briefing
+
+```
+GET /api/v2/compass/latest
+```
+
+Returns the most recent briefing without generating a new one.
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/compass/latest"
+```
+
+### Get Specific Briefing
+
+```
+GET /api/v2/compass/briefings/{briefingId}
+```
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/compass/briefings/550e8400-e29b-41d4-a716-446655440000"
+```
+
+### Submit Correction
+
+```
+POST /api/v2/compass/corrections
+```
+
+Submits a correction to update the active briefing session when reality diverges from the plan.
+
+**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 |
+| `briefingUpdated` | boolean | Whether the active briefing was re-ranked |
+
+```bash
+# Mark a task as completed mid-session
+curl -X POST "$MYN_API_URL/api/v2/compass/corrections" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "TASK_COMPLETED",
+    "data": {"taskId": "550e8400-e29b-41d4-a716-446655440000"},
+    "reason": "Finished the report early"
+  }'
+
+# Report a priority change
+curl -X POST "$MYN_API_URL/api/v2/compass/corrections" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "PRIORITY_CHANGED",
+    "data": {"taskId": "660e8400-e29b-41d4-a716-446655440001", "newPriority": "CRITICAL"},
+    "reason": "Client moved deadline up"
+  }'
+```
+
+### Complete Session
+
+```
+POST /api/v2/compass/complete
+```
+
+Ends the active briefing session with an optional summary and decisions record.
+
+**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 briefing (nullable) |
+| `followUps` | object[] | Auto-generated follow-up items |
+
+```bash
+# Complete the session with a summary
+curl -X POST "$MYN_API_URL/api/v2/compass/complete" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -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"
+    ]
+  }'
+```

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

@@ -0,0 +1,139 @@
+# Calendar API
+
+Calendar events and meetings management including creation, listing, and deletion.
+
+## Base Path
+
+`/api/v2/calendar`
+
+## Endpoints
+
+### List Events
+
+```
+GET /api/v2/calendar/events
+```
+
+**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 |
+| `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"
+
+# List only all-day events
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/calendar/events?allDay=true&limit=10"
+```
+
+### Create Event
+
+```
+POST /api/v2/calendar/events
+```
+
+**Required Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | string | Event title |
+| `startTime` | datetime | Start time (ISO 8601) |
+| `endTime` | datetime | End time (ISO 8601, required for non-all-day events) |
+
+**Optional Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `isAllDay` | boolean | Whether this is an all-day event (default: false) |
+| `description` | string | Event description |
+| `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`) |
+
+```bash
+# Create a one-time meeting
+curl -X POST "$MYN_API_URL/api/v2/calendar/events" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Team standup",
+    "startTime": "2026-03-02T09:00:00Z",
+    "endTime": "2026-03-02T09:30:00Z",
+    "location": "Conference Room B",
+    "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" \
+  -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"
+  }'
+```
+
+### Delete Event
+
+```
+DELETE /api/v2/calendar/events/{eventId}
+```
+
+```bash
+curl -X DELETE "$MYN_API_URL/api/v2/calendar/events/550e8400-e29b-41d4-a716-446655440000" \
+  -H "X-API-KEY: $MYN_API_KEY"
+```
+
+### List Meetings
+
+```
+GET /api/v2/calendar/meetings
+```
+
+Returns upcoming meetings with attendee information. This is a convenience view over calendar events filtered to multi-attendee meetings.
+
+**Query 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 |
+
+**Response Fields:**
+
+| 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 |
+
+```bash
+# Get meetings for the next 7 days
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/calendar/meetings"
+
+# Get meetings for the next 14 days including past
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/calendar/meetings?daysAhead=14&includePast=true&limit=25"
+```

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

@@ -0,0 +1,257 @@
+# Habits API
+
+Habit streaks, habit chains, scheduling, and reminders.
+
+## Base Path
+
+- Streaks and chains: `/api/v1/habit-chains`
+- Reminders: `/api/habits/reminders`
+
+## Endpoints
+
+### List All Habit Streaks
+
+```
+GET /api/v1/habit-chains/streaks
+```
+
+Returns streak data for all habits.
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `habits` | object[] | Array of habit streak objects |
+| `habits[].habitId` | UUID | Habit identifier |
+| `habits[].title` | string | Habit title |
+| `habits[].currentStreak` | number | Current consecutive completions |
+| `habits[].longestStreak` | number | All-time longest streak |
+| `habits[].totalCompletions` | number | Total times completed |
+| `habits[].lastCompletedAt` | datetime | Last completion timestamp |
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v1/habit-chains/streaks"
+```
+
+### Get Specific Habit Streak
+
+```
+GET /api/v1/habit-chains/{habitId}/streaks
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `includeHistory` | boolean | Include day-by-day streak history |
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `habitId` | UUID | Habit identifier |
+| `currentStreak` | number | Current consecutive completions |
+| `longestStreak` | number | All-time longest streak |
+| `totalCompletions` | number | Total times completed |
+| `lastCompletedAt` | datetime | Last completion timestamp |
+| `streakHistory` | object[] | Day-by-day history (only if `includeHistory=true`) |
+| `streakHistory[].date` | date | Calendar date |
+| `streakHistory[].completed` | boolean | Whether the habit was completed that day |
+
+```bash
+# Basic streak info
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v1/habit-chains/660e8400-e29b-41d4-a716-446655440001/streaks"
+
+# With full history
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v1/habit-chains/660e8400-e29b-41d4-a716-446655440001/streaks?includeHistory=true"
+```
+
+### Skip Habit (Preserve Streak)
+
+```
+POST /api/v1/habit-chains/{habitId}/skip
+```
+
+Marks a habit as skipped for a day without breaking the streak.
+
+**Body Parameters:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `skipDate` | date | Date to skip (default: today, YYYY-MM-DD) |
+| `reason` | string | Optional reason for skipping |
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `habitId` | UUID | Habit identifier |
+| `skippedDate` | date | The date that was skipped |
+| `streakPreserved` | boolean | Whether the streak was preserved |
+| `newStreakCount` | number | Updated streak count |
+
+```bash
+curl -X POST "$MYN_API_URL/api/v1/habit-chains/660e8400-e29b-41d4-a716-446655440001/skip" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "skipDate": "2026-03-01",
+    "reason": "Sick day"
+  }'
+```
+
+### List All Chains
+
+```
+GET /api/v1/habit-chains
+```
+
+Returns all habit chains (grouped sequences of habits).
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `chains` | object[] | Array of chain objects |
+| `chains[].chainId` | UUID | Chain identifier |
+| `chains[].name` | string | Chain name |
+| `chains[].habitCount` | number | Number of habits in the chain |
+| `chains[].totalCompletions` | number | Total completions across all habits |
+| `chains[].lastCompletedAt` | datetime | Last completion in this chain |
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v1/habit-chains"
+```
+
+### Get Specific Chain
+
+```
+GET /api/v1/habit-chains/{chainId}
+```
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `chainId` | UUID | Chain identifier |
+| `name` | string | Chain name |
+| `habits` | object[] | Ordered list of habits in the chain |
+| `habits[].habitId` | UUID | Habit identifier |
+| `habits[].title` | string | Habit title |
+| `habits[].order` | number | Position in the chain |
+| `trigger` | string | What triggers the chain (nullable) |
+| `location` | string | Where the chain is performed (nullable) |
+| `totalCompletions` | number | Total completions across all habits |
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v1/habit-chains/770e8400-e29b-41d4-a716-446655440002"
+```
+
+### Get Habit Schedule
+
+```
+GET /api/v1/habit-chains/schedule
+```
+
+Returns the habit schedule for the upcoming days.
+
+**Query Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `days` | number | Number of days to look ahead (default: 7) |
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `schedule` | object[] | Array of daily schedules |
+| `schedule[].date` | date | Calendar date |
+| `schedule[].dayOfWeek` | string | Day name (e.g., `Monday`) |
+| `schedule[].habits` | object[] | Habits due on that day |
+| `schedule[].habits[].habitId` | UUID | Habit identifier |
+| `schedule[].habits[].title` | string | Habit title |
+| `schedule[].habits[].duration` | string | Expected duration (nullable) |
+| `schedule[].habits[].completed` | boolean | Whether already completed |
+| `schedule[].habits[].chainName` | string | Parent chain name (nullable) |
+| `habitsDue` | number | Total habits due across the period |
+
+```bash
+# Default 7-day schedule
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v1/habit-chains/schedule"
+
+# 14-day schedule
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v1/habit-chains/schedule?days=14"
+```
+
+### List All Reminders
+
+```
+GET /api/habits/reminders
+```
+
+Returns reminder settings for all habits.
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `reminders` | object[] | Array of reminder objects |
+| `reminders[].habitId` | UUID | Habit identifier |
+| `reminders[].title` | string | Habit title |
+| `reminders[].enabled` | boolean | Whether the reminder is active |
+| `reminders[].reminderTime` | time | Time of day for the reminder (nullable, HH:mm) |
+| `reminders[].reminderDays` | string[] | Days the reminder fires (e.g., `["MON", "WED", "FRI"]`) |
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/habits/reminders"
+```
+
+### Get Specific Reminder
+
+```
+GET /api/habits/reminders/{habitId}
+```
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/habits/reminders/660e8400-e29b-41d4-a716-446655440001"
+```
+
+### Update Reminder
+
+```
+PUT /api/habits/reminders/{habitId}
+```
+
+**Body Parameters:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enabled` | boolean | Enable or disable the reminder |
+| `time` | time | Time of day for the reminder (HH:mm) |
+
+```bash
+# Enable a reminder at 7:30 AM
+curl -X PUT "$MYN_API_URL/api/habits/reminders/660e8400-e29b-41d4-a716-446655440001" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "enabled": true,
+    "time": "07:30"
+  }'
+
+# Disable a reminder
+curl -X PUT "$MYN_API_URL/api/habits/reminders/660e8400-e29b-41d4-a716-446655440001" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"enabled": false}'
+```