@mind-your-now/myn 0.8.2 → 0.8.4

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"
+  }'
+```

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

@@ -0,0 +1,323 @@
+# YNAB API
+
+YNAB (You Need A Budget) integration for budget management, transactions, scheduled transactions, analytics, and category management.
+
+## Base Path
+
+`/api/v1/ynab`
+
+## Endpoints
+
+### Budget & Accounts
+
+#### Budget Overview
+
+```
+GET /api/v1/ynab/budget/overview
+```
+
+Returns the overall budget summary including ready-to-assign amount, total income, total budgeted, and total activity.
+
+#### List Categories
+
+```
+GET /api/v1/ynab/budget/categories
+```
+
+Returns all category groups and their categories with balances, budgeted amounts, and goal information.
+
+#### Category Balance (Search)
+
+```
+GET /api/v1/ynab/budget/categories/search?query={categoryName}
+```
+
+Fuzzy-searches for a category by name and returns its balance and details.
+
+#### Account Balances
+
+```
+GET /api/v1/ynab/budget/accounts
+```
+
+Returns all accounts grouped by type (checking, savings, creditCards, loans) with balances and transfer payee IDs.
+
+#### Set Budget Amount
+
+```
+PATCH /api/v1/ynab/budget/categories/{categoryId}/budget
+```
+
+**Body:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `budgetedDollars` | number | Amount in dollars to budget for the category |
+| `month` | string | Budget month in YYYY-MM format (defaults to current month) |
+
+#### Set Category Goal
+
+```
+PATCH /api/v1/ynab/budget/categories/{categoryId}/goal
+```
+
+**Body:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `goalType` | string | Goal type: `TB`, `TBD`, `MF`, `NEED` |
+| `goalTargetDollars` | number | Goal target in dollars |
+| `goalTargetMonth` | string | Target month YYYY-MM (for TBD goals, appends `-01` automatically) |
+
+#### Goal Progress
+
+```
+GET /api/v1/ynab/budget/categories
+```
+
+Same as list_categories; goal progress fields are included in category data.
+
+#### Budget Months
+
+```
+GET /api/v1/ynab/budget/months
+```
+
+Returns available budget months with summary data.
+
+#### Search Payees
+
+```
+GET /api/v1/ynab/budget/payees/search?query={payeeName}
+GET /api/v1/ynab/budget/payees
+```
+
+Search for payees by name (fuzzy match), or list all payees if no query is provided.
+
+### Transactions
+
+#### Create Transaction
+
+```
+POST /api/v1/ynab/transactions
+```
+
+**Body:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `accountId` | string | **Required.** YNAB account ID |
+| `amountMilliunits` | number | **Required.** Amount in milliunits (dollars * 1000, negative for expenses) |
+| `date` | string | **Required.** Date YYYY-MM-DD (defaults to today) |
+| `payeeName` | string | Payee name (required if no payeeId) |
+| `payeeId` | string | Payee ID (for transfers, use target account's transferPayeeId) |
+| `categoryId` | string | Category ID (resolved from categoryName by the tool) |
+| `memo` | string | Optional memo |
+| `cleared` | string | `cleared`, `uncleared`, or `reconciled` |
+
+The tool automatically performs duplicate detection by checking for existing transactions with the same amount and date.
+
+#### Create Transactions Bulk
+
+```
+POST /api/v1/ynab/transactions/bulk
+```
+
+**Body:** `{ transactions: [{ accountId, payeeName, amount, date, categoryId, memo? }] }`
+
+Amounts are in milliunits. Bypasses the single-transaction duplicate check.
+
+#### List Transactions
+
+```
+GET /api/v1/ynab/transactions
+GET /api/v1/ynab/transactions?sinceDate={YYYY-MM-DD}
+```
+
+Returns transactions, optionally filtered by date.
+
+#### Update Transaction
+
+```
+PUT /api/v1/ynab/transactions/{transactionId}
+```
+
+**Body:** Any combination of `accountId`, `payeeName`, `payeeId`, `amountMilliunits`, `date`, `memo`, `cleared`, `flagColor`, `categoryId`.
+
+#### Delete Transaction
+
+```
+DELETE /api/v1/ynab/transactions/{transactionId}
+```
+
+#### Split Transaction
+
+```
+PUT /api/v1/ynab/transactions/{transactionId}
+```
+
+Updates a transaction with `subtransactions` to split it across multiple categories. The tool validates that split amounts sum to the original transaction amount.
+
+**Body:** `{ subtransactions: [{ amount, categoryId, memo? }] }`
+
+### Scheduled Transactions & Subscriptions
+
+#### List Scheduled Transactions
+
+```
+GET /api/v1/ynab/scheduled-transactions
+```
+
+#### Create Scheduled Transaction
+
+```
+POST /api/v1/ynab/scheduled-transactions
+```
+
+**Body:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `accountId` | string | **Required.** YNAB account ID |
+| `payeeName` | string | **Required.** Payee name |
+| `amountMilliunits` | number | **Required.** Amount in milliunits |
+| `dateFirst` | string | **Required.** First occurrence date YYYY-MM-DD |
+| `dateNext` | string | Next occurrence date (defaults to dateFirst) |
+| `frequency` | string | **Required.** Recurrence: `never`, `daily`, `weekly`, `everyOtherWeek`, `twiceAMonth`, `every4Weeks`, `monthly`, `everyOtherMonth`, `every3Months`, `every4Months`, `twiceAYear`, `yearly`, `everyOtherYear` |
+| `categoryId` | string | Category ID |
+| `memo` | string | Optional memo |
+
+#### Update Scheduled Transaction
+
+```
+PUT /api/v1/ynab/scheduled-transactions/{transactionId}
+```
+
+**Body:** Any combination of `payeeName`, `amountMilliunits`, `dateNext`, `frequency`, `memo`, `categoryId`.
+
+#### Delete Scheduled Transaction
+
+```
+DELETE /api/v1/ynab/scheduled-transactions/{transactionId}
+```
+
+#### Subscriptions View
+
+```
+GET /api/v1/ynab/subscriptions
+```
+
+Returns a view of recurring scheduled transactions categorized as subscriptions.
+
+#### Upcoming Bills
+
+```
+GET /api/v1/ynab/scheduled?days={days}
+```
+
+Returns scheduled transactions due within the specified number of days (default: 7).
+
+### Analytics
+
+#### Spending Insights
+
+```
+GET /api/v1/ynab/analytics/spending?months={months}&category={categoryName}
+```
+
+Returns spending breakdown by category. Optional category filter for drilling into a specific category.
+
+#### Payee Analysis
+
+```
+GET /api/v1/ynab/analytics/payees?months={months}
+```
+
+Returns spending analysis by payee.
+
+#### Spending Trends
+
+```
+GET /api/v1/ynab/analytics/trends?months={months}
+```
+
+Returns month-over-month spending trends.
+
+#### Net Worth
+
+```
+GET /api/v1/ynab/analytics/net-worth
+```
+
+Returns net worth calculation across all accounts.
+
+#### Debt Tracking
+
+```
+GET /api/v1/ynab/analytics/debt
+```
+
+Returns debt tracking information for loan and credit card accounts.
+
+### Category Management
+
+#### Create Category Group
+
+```
+POST /api/v1/ynab/budget/category-groups
+```
+
+**Body:** `{ name: "Group Name" }`
+
+#### Create Category
+
+```
+POST /api/v1/ynab/budget/categories
+```
+
+**Body:** `{ name: "Category Name", categoryGroupId: "group-id", note?: "optional note" }`
+
+The `categoryGroupId` can be resolved from `groupName` by fuzzy match against existing groups.
+
+#### Rename Category
+
+```
+PATCH /api/v1/ynab/budget/categories/{categoryId}/details
+```
+
+**Body:** `{ name: "New Name" }`
+
+#### Move Category
+
+```
+PATCH /api/v1/ynab/budget/categories/{categoryId}/details
+```
+
+**Body:** `{ categoryGroupId: "target-group-id" }`
+
+Moves a category to a different category group.
+
+#### Rename Category Group
+
+```
+PATCH /api/v1/ynab/budget/category-groups/{groupId}
+```
+
+**Body:** `{ name: "New Group Name" }`
+
+### Connection
+
+#### Connection Status
+
+```
+GET /api/v1/ynab/status
+```
+
+Returns YNAB connection status.
+
+## Notes
+
+- All monetary amounts from the YNAB API are in milliunits (divide by 1000 for dollars). The tool automatically converts these to formatted dollar strings in responses.
+- The tool accepts amounts in dollars (e.g., `-45.50` for a $45.50 expense) and converts them to milliunits internally.
+- Category names are resolved via fuzzy search against existing categories. Always use `list_categories` first to find the correct name.
+- `categoryName` is required for all non-transfer transactions to prevent uncategorized entries in YNAB.