@mind-your-now/myn 0.8.2 → 0.8.4

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

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

@@ -2,49 +2,25 @@
 
 Habit streaks, habit chains, scheduling, and reminders.
 
-## Base Path
+## Actions
 
-- Streaks and chains: `/api/v1/habit-chains`
-- Reminders: `/api/habits/reminders`
+The `myn_habits` tool supports these actions: `streaks`, `skip`, `chains`, `schedule`, `reminders`.
 
 ## Endpoints
 
-### List All Habit Streaks
+### Get Habit Streak
 
 ```
-GET /api/v1/habit-chains/streaks
+GET /api/v2/unified-tasks/{habitId}/streak
 ```
 
-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
-```
+Returns streak data for a specific habit. Requires `habitId`.
 
 **Query Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `includeHistory` | boolean | Include day-by-day streak history |
+| `includeHistory` | boolean | Include day-by-day streak history (default: false) |
 
 **Response Fields:**
 
@@ -54,7 +30,7 @@ GET /api/v1/habit-chains/{habitId}/streaks
 | `currentStreak` | number | Current consecutive completions |
 | `longestStreak` | number | All-time longest streak |
 | `totalCompletions` | number | Total times completed |
-| `lastCompletedAt` | datetime | Last completion timestamp |
+| `lastCompletedAt` | datetime | Last completion timestamp (nullable) |
 | `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 |
@@ -62,26 +38,30 @@ GET /api/v1/habit-chains/{habitId}/streaks
 ```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"
+  "$MYN_API_URL/api/v2/unified-tasks/HABIT_ID/streak"
 
 # 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"
+  "$MYN_API_URL/api/v2/unified-tasks/HABIT_ID/streak?includeHistory=true"
 ```
 
+**Note:** There is no bulk streaks endpoint. Use the `schedule` action to see all habits.
+
 ### Skip Habit (Preserve Streak)
 
 ```
-POST /api/v1/habit-chains/{habitId}/skip
+POST /api/v2/unified-tasks/{habitId}/skip
 ```
 
 Marks a habit as skipped for a day without breaking the streak.
 
+**Required:** `habitId`
+
 **Body Parameters:**
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `skipDate` | date | Date to skip (default: today, YYYY-MM-DD) |
+| `skipDate` | date | Date to skip (YYYY-MM-DD, default: today) |
 | `reason` | string | Optional reason for skipping |
 
 **Response Fields:**
@@ -94,7 +74,7 @@ Marks a habit as skipped for a day without breaking the streak.
 | `newStreakCount` | number | Updated streak count |
 
 ```bash
-curl -X POST "$MYN_API_URL/api/v1/habit-chains/660e8400-e29b-41d4-a716-446655440001/skip" \
+curl -X POST "$MYN_API_URL/api/v2/unified-tasks/HABIT_ID/skip" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
@@ -106,7 +86,7 @@ curl -X POST "$MYN_API_URL/api/v1/habit-chains/660e8400-e29b-41d4-a716-446655440
 ### List All Chains
 
 ```
-GET /api/v1/habit-chains
+GET /api/habits/chains
 ```
 
 Returns all habit chains (grouped sequences of habits).
@@ -120,17 +100,17 @@ Returns all habit chains (grouped sequences of habits).
 | `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 |
+| `chains[].lastCompletedAt` | datetime | Last completion in this chain (nullable) |
 
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v1/habit-chains"
+  "$MYN_API_URL/api/habits/chains"
 ```
 
 ### Get Specific Chain
 
 ```
-GET /api/v1/habit-chains/{chainId}
+GET /api/habits/chains/{chainId}/status
 ```
 
 **Response Fields:**
@@ -149,13 +129,13 @@ GET /api/v1/habit-chains/{chainId}
 
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v1/habit-chains/770e8400-e29b-41d4-a716-446655440002"
+  "$MYN_API_URL/api/habits/chains/CHAIN_ID/status"
 ```
 
 ### Get Habit Schedule
 
 ```
-GET /api/v1/habit-chains/schedule
+GET /api/v2/unified-tasks/schedule
 ```
 
 Returns the habit schedule for the upcoming days.
@@ -172,7 +152,7 @@ Returns the habit schedule for the upcoming days.
 |-------|------|-------------|
 | `schedule` | object[] | Array of daily schedules |
 | `schedule[].date` | date | Calendar date |
-| `schedule[].dayOfWeek` | string | Day name (e.g., `Monday`) |
+| `schedule[].dayOfWeek` | number | Day of week number |
 | `schedule[].habits` | object[] | Habits due on that day |
 | `schedule[].habits[].habitId` | UUID | Habit identifier |
 | `schedule[].habits[].title` | string | Habit title |
@@ -184,11 +164,11 @@ Returns the habit schedule for the upcoming days.
 ```bash
 # Default 7-day schedule
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v1/habit-chains/schedule"
+  "$MYN_API_URL/api/v2/unified-tasks/schedule"
 
 # 14-day schedule
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v1/habit-chains/schedule?days=14"
+  "$MYN_API_URL/api/v2/unified-tasks/schedule?days=14"
 ```
 
 ### List All Reminders
@@ -208,7 +188,7 @@ Returns reminder settings for all habits.
 | `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"]`) |
+| `reminders[].reminderDays` | number[] | Days the reminder fires |
 
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
@@ -221,9 +201,18 @@ curl -H "X-API-KEY: $MYN_API_KEY" \
 GET /api/habits/reminders/{habitId}
 ```
 
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `habitId` | UUID | Habit identifier |
+| `remindersEnabled` | boolean | Whether reminders are active |
+| `reminderTime` | time | Time of day (nullable, HH:mm) |
+| `reminderDays` | number[] | Days the reminder fires |
+
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/habits/reminders/660e8400-e29b-41d4-a716-446655440001"
+  "$MYN_API_URL/api/habits/reminders/HABIT_ID"
 ```
 
 ### Update Reminder
@@ -240,18 +229,11 @@ PUT /api/habits/reminders/{habitId}
 | `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" \
+curl -X PUT "$MYN_API_URL/api/habits/reminders/HABIT_ID" \
   -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}'
 ```

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

@@ -8,13 +8,14 @@ Household members, invites, and chore management.
 
 ## Getting the Household ID
 
-Most endpoints require a `householdId`. Get it from the user profile:
+Most endpoints require a `householdId`. The plugin auto-resolves it via:
 
-```bash
-curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/v1/customers/me"
-# → { "households": [{ "id": "uuid", "name": "Home" }] }
+```
+GET /api/v1/households/current
 ```
 
+Response: `{ "id": "uuid" }`
+
 ## Endpoints
 
 ### List Members
@@ -78,12 +79,20 @@ curl -X POST "$MYN_API_URL/api/v1/households/HOUSEHOLD_ID/invites" \
   -d '{"email": "jane@example.com", "role": "member"}'
 ```
 
-### List Chores
+### List Chores (Today)
 
 ```
-GET /api/v2/chores?householdId={householdId}
+GET /api/v2/chores/today?householdId={householdId}
 ```
 
+Returns today's chores for the household.
+
+**Query Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `householdId` | UUID | Required |
+
 **Response:**
 
 ```json
@@ -106,22 +115,31 @@ GET /api/v2/chores?householdId={householdId}
 
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/chores?householdId=HOUSEHOLD_ID"
+  "$MYN_API_URL/api/v2/chores/today?householdId=HOUSEHOLD_ID"
 ```
 
 ### Get Chore Schedule
 
 ```
-GET /api/v2/chores/schedule
+GET /api/v2/chores/schedule/range
 ```
 
+Returns chore schedule for a date range.
+
 **Query Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `householdId` | UUID | Required |
-| `date` | date | Specific date (YYYY-MM-DD) |
-| `weekStart` | date | Start of week to view |
+| `startDate` | date | Start date (YYYY-MM-DD, defaults to today) |
+| `endDate` | date | End date (YYYY-MM-DD, defaults to startDate + 7 days) |
+
+**Tool Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `date` | date | Specific date (sets both startDate and endDate) |
+| `weekStart` | date | Start of week (endDate computed as +7 days) |
 
 **Response:**
 
@@ -137,7 +155,9 @@ GET /api/v2/chores/schedule
           "title": "Take out trash",
           "assignedTo": "member-uuid",
           "estimatedMinutes": 10,
-          "completed": false
+          "completed": false,
+          "completedAt": null,
+          "completedBy": null
         }
       ]
     }
@@ -149,15 +169,17 @@ GET /api/v2/chores/schedule
 
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/chores/schedule?householdId=HOUSEHOLD_ID&date=2026-03-01"
+  "$MYN_API_URL/api/v2/chores/schedule/range?householdId=HOUSEHOLD_ID&startDate=2026-03-01&endDate=2026-03-07"
 ```
 
 ### Complete Chore
 
 ```
-POST /api/v2/chores/{choreId}/complete
+POST /api/v2/chores/instances/{choreId}/complete
 ```
 
+**Uses read-before-write guard** — reads chore instance state hash before completing.
+
 **Body:**
 
 | Field | Type | Required | Description |
@@ -168,8 +190,9 @@ POST /api/v2/chores/{choreId}/complete
 **Response:** `{ choreId, completed, completedAt, nextDueDate? }`
 
 ```bash
-curl -X POST "$MYN_API_URL/api/v2/chores/CHORE_ID/complete" \
+curl -X POST "$MYN_API_URL/api/v2/chores/instances/CHORE_ID/complete" \
   -H "X-API-KEY: $MYN_API_KEY" \
+  -H "X-MYN-State-Hash: abc123" \
   -H "Content-Type: application/json" \
   -d '{"note": "Both bins taken to curb"}'
 ```