@mind-your-now/myn 0.8.1 → 0.8.3

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

@@ -11,23 +11,22 @@ Unified search across all MYN entity types with filtering, pagination, and relev
 ### Search
 
 ```
-POST /api/v2/search
+GET /api/v2/search
 ```
 
-Performs a full-text search across tasks, habits, chores, events, projects, notes, and memories.
+Performs a full-text search across tasks, habits, chores, events, projects, notes, and memories using query parameters.
 
-**Body Parameters:**
+**Query Parameters:**
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `query` | string | **Required.** Search query text |
-| `types` | string[] | Entity types to search. Options: `task`, `habit`, `chore`, `event`, `project`, `note`, `memory`. Omit to search all types. |
-| `filters` | object | Optional filters to narrow results |
-| `filters.status` | string | Filter by status (e.g., `PENDING`, `COMPLETED`) |
-| `filters.priority` | string | Filter by priority (e.g., `CRITICAL`, `OPPORTUNITY_NOW`) |
-| `filters.projectId` | UUID | Filter by project |
-| `filters.dateFrom` | date | Results from this date onward (YYYY-MM-DD) |
-| `filters.dateTo` | date | Results up to this date (YYYY-MM-DD) |
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `q` | string | **Required.** Search query text |
+| `types` | string | Entity types to search (repeatable). Options: `task`, `habit`, `chore`, `event`, `project`, `note`, `memory`. Omit to search all types. |
+| `status` | string | Filter by status (e.g., `PENDING`, `IN_PROGRESS`, `COMPLETED`, `ARCHIVED`) |
+| `priority` | string | Filter by priority (e.g., `CRITICAL`, `OPPORTUNITY_NOW`, `OVER_THE_HORIZON`, `PARKING_LOT`) |
+| `projectId` | UUID | Filter by project |
+| `dateFrom` | date | Results from this date onward (YYYY-MM-DD) |
+| `dateTo` | date | Results up to this date (YYYY-MM-DD) |
 | `limit` | number | Max results (default: 20, max: 100) |
 | `offset` | number | Pagination offset (default: 0) |
 
@@ -53,45 +52,18 @@ Performs a full-text search across tasks, habits, chores, events, projects, note
 
 ```bash
 # Basic search
-curl -X POST "$MYN_API_URL/api/v2/search" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"query": "quarterly report"}'
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/search?q=quarterly+report"
 
 # Search only tasks and notes
-curl -X POST "$MYN_API_URL/api/v2/search" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "quarterly report",
-    "types": ["task", "note"],
-    "limit": 10
-  }'
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/search?q=quarterly+report&types=task&types=note&limit=10"
 
 # Search with filters
-curl -X POST "$MYN_API_URL/api/v2/search" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "budget",
-    "types": ["task", "project"],
-    "filters": {
-      "status": "PENDING",
-      "priority": "CRITICAL",
-      "dateFrom": "2026-01-01",
-      "dateTo": "2026-03-31"
-    },
-    "limit": 50,
-    "offset": 0
-  }'
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/search?q=budget&types=task&types=project&status=PENDING&priority=CRITICAL&dateFrom=2026-01-01&dateTo=2026-03-31&limit=50"
 
 # Paginated search
-curl -X POST "$MYN_API_URL/api/v2/search" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "meeting notes",
-    "limit": 20,
-    "offset": 20
-  }'
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/search?q=meeting+notes&limit=20&offset=20"
 ```

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

@@ -6,6 +6,10 @@ Unified task management covering Tasks, Habits, and Chores.
 
 `/api/v2/unified-tasks`
 
+## Actions
+
+The `myn_tasks` tool supports these actions: `list`, `get`, `create`, `update`, `complete`, `archive`, `search`.
+
 ## Endpoints
 
 ### List Tasks
@@ -18,8 +22,8 @@ GET /api/v2/unified-tasks
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `status` | string | Filter: `PENDING`, `IN_PROGRESS`, `COMPLETED`, `ARCHIVED` |
-| `priority` | string | Filter: `CRITICAL`, `OPPORTUNITY_NOW`, `OVER_THE_HORIZON`, `PARKING_LOT` |
+| `status` | string | `PENDING`, `IN_PROGRESS`, `COMPLETED`, `ARCHIVED` |
+| `priority` | string | `CRITICAL`, `OPPORTUNITY_NOW`, `OVER_THE_HORIZON`, `PARKING_LOT` |
 | `projectId` | UUID | Filter by project |
 | `startDate` | date | Filter by start date (YYYY-MM-DD) |
 | `endDate` | date | Filter by end date (YYYY-MM-DD) |
@@ -27,13 +31,11 @@ GET /api/v2/unified-tasks
 | `offset` | number | Pagination offset (default: 0) |
 
 ```bash
-# List Critical Now tasks
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/unified-tasks?priority=CRITICAL&status=PENDING"
+  "$MYN_API_URL/api/v2/unified-tasks"
 
-# List tasks for a date range
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/unified-tasks?startDate=2026-03-01&endDate=2026-03-07"
+  "$MYN_API_URL/api/v2/unified-tasks?priority=CRITICAL&status=PENDING"
 ```
 
 ### Get Task
@@ -42,9 +44,11 @@ curl -H "X-API-KEY: $MYN_API_KEY" \
 GET /api/v2/unified-tasks/{taskId}
 ```
 
+The response includes a `stateHash` field for use in write operations (MIN-740 read-before-write guard).
+
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-446655440000"
+  "$MYN_API_URL/api/v2/unified-tasks/TASK_ID"
 ```
 
 ### Create Task
@@ -57,8 +61,7 @@ POST /api/v2/unified-tasks
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `id` | UUID | Client-generated UUID |
-| `title` | string | Task title (1–200 chars) |
+| `title` | string | Task title (1-200 chars) |
 | `taskType` | string | `TASK`, `HABIT`, or `CHORE` |
 | `priority` | string | `CRITICAL`, `OPPORTUNITY_NOW`, `OVER_THE_HORIZON`, `PARKING_LOT` |
 | `startDate` | date | Start date (YYYY-MM-DD) |
@@ -67,10 +70,15 @@ POST /api/v2/unified-tasks
 
 | Field | Type | Description |
 |-------|------|-------------|
+| `id` | UUID | Optional (auto-generated if omitted). Do NOT fabricate UUIDs. |
 | `description` | string | Description (max 2000 chars) |
-| `duration` | string | Duration: `"30m"`, `"1h"`, `"1h30m"` (NOT ISO PT prefix) |
+| `duration` | string | Duration: `"30m"`, `"1h"`, `"1h30m"` |
 | `projectId` | UUID | Assign to project |
 | `recurrenceRule` | string | RRULE for HABIT/CHORE types (**required** for HABIT and CHORE) |
+| `isAutoScheduled` | boolean | Enable auto-scheduling (default: true). Only set false if user explicitly opts out. |
+| `calendarId` | string | Calendar ID to link task to (e.g. "primary") |
+| `calendarName` | string | Calendar name to resolve (e.g. "Family", "Work"). Used instead of calendarId. |
+| `scheduleNames` | string[] | Schedule names to assign (e.g. `["Morning"]`, `["Weekday Evening", "Weekend Morning"]`). Resolved to IDs automatically. |
 
 **Type-Specific Rules:**
 
@@ -84,13 +92,14 @@ curl -X POST "$MYN_API_URL/api/v2/unified-tasks" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
-    "id": "550e8400-e29b-41d4-a716-446655440000",
     "title": "Prepare quarterly report",
     "taskType": "TASK",
     "priority": "CRITICAL",
     "startDate": "2026-03-01",
     "duration": "2h",
-    "description": "Q1 financials and projections"
+    "description": "Q1 financials and projections",
+    "isAutoScheduled": true,
+    "scheduleNames": ["Morning"]
   }'
 
 # Create a habit
@@ -98,7 +107,6 @@ curl -X POST "$MYN_API_URL/api/v2/unified-tasks" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
-    "id": "660e8400-e29b-41d4-a716-446655440001",
     "title": "Morning meditation",
     "taskType": "HABIT",
     "priority": "OPPORTUNITY_NOW",
@@ -114,11 +122,17 @@ curl -X POST "$MYN_API_URL/api/v2/unified-tasks" \
 PATCH /api/v2/unified-tasks/{taskId}
 ```
 
-Send only the fields to update:
+**Uses read-before-write guard** (MIN-740). Reads task first to get `stateHash`, retries on 409.
+
+Send only the fields to update via the `updates` object. Allowed fields: `title`, `description`, `priority`, `status`, `startDate`, `endDate`, `duration`, `projectId`, `recurrenceRule`, `isAutoScheduled`, `calendarId`, `location`, `notes`, `tags`, `estimatedMinutes`, `actualMinutes`, `completedAt`, `archivedAt`, `taskType`, `assignedTo`, `scheduledAt`, `dueDate`.
 
 ```bash
-curl -X PATCH "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-446655440000" \
+HASH=$(curl -s -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/unified-tasks/TASK_ID" | jq -r .stateHash)
+
+curl -X PATCH "$MYN_API_URL/api/v2/unified-tasks/TASK_ID" \
   -H "X-API-KEY: $MYN_API_KEY" \
+  -H "X-MYN-State-Hash: $HASH" \
   -H "Content-Type: application/json" \
   -d '{"priority": "OPPORTUNITY_NOW", "startDate": "2026-03-05"}'
 ```
@@ -129,9 +143,15 @@ curl -X PATCH "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-4466554
 POST /api/v2/unified-tasks/{taskId}/complete
 ```
 
+**Uses read-before-write guard** (MIN-740).
+
 ```bash
-curl -X POST "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-446655440000/complete" \
+HASH=$(curl -s -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/unified-tasks/TASK_ID" | jq -r .stateHash)
+
+curl -X POST "$MYN_API_URL/api/v2/unified-tasks/TASK_ID/complete" \
   -H "X-API-KEY: $MYN_API_KEY" \
+  -H "X-MYN-State-Hash: $HASH" \
   -H "Content-Type: application/json" \
   -d '{}'
 ```
@@ -142,8 +162,10 @@ curl -X POST "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-44665544
 POST /api/v2/unified-tasks/{taskId}/archive
 ```
 
+**Uses read-before-write guard** (MIN-740).
+
 ```bash
-curl -X POST "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-446655440000/archive" \
+curl -X POST "$MYN_API_URL/api/v2/unified-tasks/TASK_ID/archive" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{}'
@@ -157,31 +179,16 @@ GET /api/v2/search
 
 See [search-api.md](search-api.md) for full search documentation.
 
-```bash
-curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/search?q=quarterly+report&limit=10"
-```
-
-### Get Habit Streak
+**Query Parameters:**
 
-```
-GET /api/v2/unified-tasks/{taskId}/streak
-```
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `q` | string | Search query |
+| `includeArchived` | boolean | Include archived results (default: false) |
+| `limit` | number | Max results (default: 20) |
+| `offset` | number | Pagination offset (default: 0) |
 
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/unified-tasks/660e8400-e29b-41d4-a716-446655440001/streak"
-```
-
-### Move Task to Project
-
-```
-PUT /api/v2/unified-tasks/{taskId}/project
-```
-
-```bash
-curl -X PUT "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-446655440000/project" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"projectId": "770e8400-e29b-41d4-a716-446655440002"}'
+  "$MYN_API_URL/api/v2/search?q=quarterly+report&limit=10"
 ```

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

@@ -6,6 +6,10 @@ Countdown timers, alarms, and Pomodoro sessions.
 
 `/api/v2/timers`
 
+## Actions
+
+The `myn_timers` tool supports these actions: `create_countdown`, `create_alarm`, `list`, `cancel`, `snooze`, `pomodoro`.
+
 ## Endpoints
 
 ### List Active Timers
@@ -24,7 +28,7 @@ Returns all active timers for the current user.
 | `timers[].timerId` | UUID | Timer identifier |
 | `timers[].type` | string | `COUNTDOWN`, `ALARM`, or `POMODORO` |
 | `timers[].label` | string | User-defined label (nullable) |
-| `timers[].status` | string | Current status (e.g., `RUNNING`, `PAUSED`, `SNOOZED`, `RINGING`, `COMPLETED`) |
+| `timers[].status` | string | Current status |
 | `timers[].duration` | number | Total duration in seconds (COUNTDOWN/POMODORO) |
 | `timers[].remaining` | number | Seconds remaining (COUNTDOWN/POMODORO) |
 | `timers[].endTime` | datetime | When the timer will fire (COUNTDOWN) |
@@ -40,15 +44,13 @@ curl -H "X-API-KEY: $MYN_API_KEY" \
   "$MYN_API_URL/api/v2/timers"
 ```
 
-### Create Timer
+### Create Countdown Timer
 
 ```
-POST /api/v2/timers
+POST /api/v2/timers/countdown
 ```
 
-Creates a new timer. The request body varies by timer type.
-
-#### Countdown Timer
+**Body Parameters:**
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -56,9 +58,30 @@ Creates a new timer. The request body varies by timer type.
 | `duration` | number | **Required.** Duration in seconds |
 | `label` | string | Optional label |
 
+**Tool Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `duration` | number | Duration in seconds |
+| `durationMinutes` | number | Duration in minutes (converted to seconds automatically) |
+| `label` | string | Timer label/description |
+
+One of `duration` or `durationMinutes` is required.
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `timerId` | UUID | Timer identifier |
+| `type` | string | `"COUNTDOWN"` |
+| `duration` | number | Duration in seconds |
+| `endTime` | datetime | When the timer will fire |
+| `label` | string | Timer label (nullable) |
+| `status` | string | `ACTIVE`, `PAUSED`, or `COMPLETED` |
+
 ```bash
 # 25-minute countdown
-curl -X POST "$MYN_API_URL/api/v2/timers" \
+curl -X POST "$MYN_API_URL/api/v2/timers/countdown" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
@@ -68,76 +91,67 @@ curl -X POST "$MYN_API_URL/api/v2/timers" \
   }'
 ```
 
-#### Alarm Timer
+### Create Alarm
+
+```
+POST /api/v2/timers/alarm
+```
+
+**Body Parameters:**
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `type` | string | **Required.** `"ALARM"` |
+| `name` | string | Alarm name (defaults to "Alarm" from label) |
 | `alarmTime` | datetime | **Required.** When the alarm should fire (ISO 8601) |
-| `label` | string | Optional label |
-| `recurrence` | string | Optional RRULE for repeating alarms |
-| `sound` | string | Optional alarm sound name |
+| `recurrence` | string | Optional recurrence pattern (e.g., "daily", "weekdays") |
+| `completionSound` | string | Optional alarm sound name |
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `timerId` | UUID | Timer identifier |
+| `type` | string | `"ALARM"` |
+| `alarmTime` | datetime | When the alarm will fire |
+| `label` | string | Alarm label (nullable) |
+| `recurrence` | string | Recurrence pattern (nullable) |
+| `status` | string | `ACTIVE`, `TRIGGERED`, or `SNOOZED` |
 
 ```bash
 # One-time alarm
-curl -X POST "$MYN_API_URL/api/v2/timers" \
+curl -X POST "$MYN_API_URL/api/v2/timers/alarm" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
-    "type": "ALARM",
-    "alarmTime": "2026-03-02T07:00:00Z",
-    "label": "Morning wake-up"
+    "name": "Morning wake-up",
+    "alarmTime": "2026-03-02T07:00:00Z"
   }'
 
 # Recurring weekday alarm
-curl -X POST "$MYN_API_URL/api/v2/timers" \
+curl -X POST "$MYN_API_URL/api/v2/timers/alarm" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
-    "type": "ALARM",
+    "name": "Standup reminder",
     "alarmTime": "2026-03-02T08:30:00Z",
-    "label": "Standup reminder",
     "recurrence": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
   }'
 ```
 
-#### Pomodoro Timer
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | string | **Required.** `"POMODORO"` |
-| `workDuration` | number | **Required.** Work phase duration in seconds |
-| `breakDuration` | number | **Required.** Short break duration in seconds |
-| `longBreakDuration` | number | **Required.** Long break duration in seconds (after all sessions) |
-| `sessions` | number | Number of work sessions before long break (default: 4) |
-| `autoStart` | boolean | Auto-start next phase (default: false) |
-| `label` | string | Optional label |
-
-```bash
-# Standard Pomodoro: 25min work, 5min break, 15min long break, 4 sessions
-curl -X POST "$MYN_API_URL/api/v2/timers" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "type": "POMODORO",
-    "workDuration": 1500,
-    "breakDuration": 300,
-    "longBreakDuration": 900,
-    "sessions": 4,
-    "autoStart": true,
-    "label": "Deep work block"
-  }'
-```
-
 ### Cancel Timer
 
 ```
-DELETE /api/v2/timers/{timerId}
+POST /api/v2/timers/{timerId}/cancel
 ```
 
+**Uses read-before-write guard** -- reads timer state hash before cancelling.
+
+**Response:** `{ timerId, status }`
+
 ```bash
-curl -X DELETE "$MYN_API_URL/api/v2/timers/550e8400-e29b-41d4-a716-446655440000" \
-  -H "X-API-KEY: $MYN_API_KEY"
+curl -X POST "$MYN_API_URL/api/v2/timers/TIMER_ID/cancel" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "X-MYN-State-Hash: abc123"
 ```
 
 ### Snooze Timer
@@ -148,6 +162,8 @@ POST /api/v2/timers/{timerId}/snooze
 
 Snoozes a ringing alarm or timer.
 
+**Uses read-before-write guard** -- reads timer state hash before snoozing.
+
 **Body Parameters:**
 
 | Field | Type | Description |
@@ -163,9 +179,54 @@ Snoozes a ringing alarm or timer.
 | `status` | string | `"SNOOZED"` |
 
 ```bash
-# Snooze for 10 minutes
-curl -X POST "$MYN_API_URL/api/v2/timers/550e8400-e29b-41d4-a716-446655440000/snooze" \
+curl -X POST "$MYN_API_URL/api/v2/timers/TIMER_ID/snooze" \
   -H "X-API-KEY: $MYN_API_KEY" \
+  -H "X-MYN-State-Hash: abc123" \
   -H "Content-Type: application/json" \
   -d '{"snoozeMinutes": 10}'
 ```
+
+### Create Pomodoro Timer
+
+```
+POST /api/v2/timers/countdown
+```
+
+Creates a Pomodoro timer (uses the countdown endpoint with `type: "POMODORO"`).
+
+**Body Parameters:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | string | **Required.** `"POMODORO"` |
+| `workDuration` | number | Work phase in seconds (tool accepts minutes, auto-converts) |
+| `breakDuration` | number | Short break in seconds (tool accepts minutes, auto-converts) |
+| `longBreakDuration` | number | Long break in seconds (tool accepts minutes, auto-converts) |
+| `sessions` | number | Number of work sessions (default: 4) |
+| `autoStart` | boolean | Auto-start next phase (default: false) |
+| `label` | string | Optional label |
+
+**Tool Parameters (in minutes):**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `workDuration` | number | 25 | Work duration in minutes |
+| `breakDuration` | number | 5 | Break duration in minutes |
+| `longBreakDuration` | number | 15 | Long break duration in minutes |
+| `sessions` | number | 4 | Number of pomodoro sessions |
+| `autoStart` | boolean | false | Auto-start next phase |
+
+```bash
+curl -X POST "$MYN_API_URL/api/v2/timers/countdown" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "POMODORO",
+    "workDuration": 1500,
+    "breakDuration": 300,
+    "longBreakDuration": 900,
+    "sessions": 4,
+    "autoStart": true,
+    "label": "Deep work block"
+  }'
+```