@mind-your-now/myn 0.8.2 → 0.8.4

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

@@ -6,15 +6,16 @@ Grocery and shopping list management scoped to households.
 
 `/api/v1/households/{householdId}/grocery-list`
 
+## Actions
+
+The `myn_lists` tool supports these actions: `get`, `add`, `update`, `toggle`, `delete`, `delete_checked`, `bulk_add`, `convert_to_tasks`.
+
 ## Prerequisites
 
-All list endpoints require a `householdId`. Retrieve it from the current user profile:
+All list endpoints require a `householdId`. The plugin auto-resolves it via:
 
-```bash
-# Get your household ID
-curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v1/customers/me"
-# Response includes: households[0].id
+```
+GET /api/v1/households/current
 ```
 
 ## Endpoints
@@ -31,7 +32,7 @@ Returns the full grocery list for the household.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `householdId` | UUID | Household identifier |
+| `success` | boolean | Operation success |
 | `items` | object[] | Array of list items |
 | `items[].id` | UUID | Item identifier |
 | `items[].name` | string | Item name |
@@ -40,19 +41,22 @@ Returns the full grocery list for the household.
 | `items[].notes` | string | Additional notes (nullable) |
 | `items[].checked` | boolean | Whether the item has been picked up |
 | `items[].addedAt` | datetime | When the item was added |
-| `items[].addedBy` | string | Name of the user who added the item |
-| `categories` | string[] | All distinct categories in the list |
-| `lastModified` | datetime | Last modification timestamp |
+| `items[].addedBy` | number | User ID who added the item |
+| `items[].addedByName` | string | Name of the user who added the item (nullable) |
+| `items[].position` | number | Sort position |
+| `items[].householdId` | UUID | Household ID |
+| `items[].createdAt` | datetime | Creation timestamp |
+| `items[].updatedAt` | datetime | Last update timestamp |
 
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v1/households/880e8400-e29b-41d4-a716-446655440003/grocery-list"
+  "$MYN_API_URL/api/v1/households/HOUSEHOLD_ID/grocery-list"
 ```
 
 ### Add Item
 
 ```
-POST /api/v1/households/{householdId}/grocery-list/items
+POST /api/v1/households/{householdId}/grocery-list
 ```
 
 **Body Parameters:**
@@ -64,15 +68,10 @@ POST /api/v1/households/{householdId}/grocery-list/items
 | `quantity` | string | Optional quantity (e.g., `2 lbs`, `1 gallon`) |
 | `notes` | string | Optional notes |
 
-**Response Fields:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `itemId` | UUID | New item identifier |
-| `added` | boolean | Whether the item was successfully added |
+**Response:** `{ success, item: { id, name, category?, quantity?, notes?, checked, addedAt, addedByName? } }`
 
 ```bash
-curl -X POST "$MYN_API_URL/api/v1/households/880e8400-e29b-41d4-a716-446655440003/grocery-list/items" \
+curl -X POST "$MYN_API_URL/api/v1/households/HOUSEHOLD_ID/grocery-list" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
@@ -83,37 +82,83 @@ curl -X POST "$MYN_API_URL/api/v1/households/880e8400-e29b-41d4-a716-44665544000
   }'
 ```
 
-### Toggle Item Checked
+### Update Item
 
 ```
-PATCH /api/v1/households/{householdId}/grocery-list/items/{itemId}
+PATCH /api/v1/households/{householdId}/grocery-list/{itemId}
 ```
 
+Updates an existing grocery list item. At least one field is required.
+
 **Body Parameters:**
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `checked` | boolean | Set checked state (toggles if omitted by some clients) |
+| `name` | string | New item name |
+| `category` | string | New category |
+| `quantity` | string | New quantity |
+| `notes` | string | New notes |
 
-**Response Fields:**
+**Response:** `{ success, item: { id, name, category?, quantity?, notes?, checked } }`
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `itemId` | UUID | Item identifier |
-| `checked` | boolean | New checked state |
+```bash
+curl -X PATCH "$MYN_API_URL/api/v1/households/HOUSEHOLD_ID/grocery-list/ITEM_ID" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"quantity": "6", "notes": "Updated quantity"}'
+```
+
+### Toggle Item Checked
+
+```
+PATCH /api/v1/households/{householdId}/grocery-list/{itemId}/toggle
+```
+
+Toggles the checked state of a grocery list item.
+
+**Response:** `{ success, item: { id, name, checked }, checked }`
 
 ```bash
-# Mark an item as picked up
-curl -X PATCH "$MYN_API_URL/api/v1/households/880e8400-e29b-41d4-a716-446655440003/grocery-list/items/990e8400-e29b-41d4-a716-446655440004" \
+curl -X PATCH "$MYN_API_URL/api/v1/households/HOUSEHOLD_ID/grocery-list/ITEM_ID/toggle" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
-  -d '{"checked": true}'
+  -d '{}'
+```
+
+### Delete Item
+
+```
+DELETE /api/v1/households/{householdId}/grocery-list/{itemId}
+```
+
+Deletes a single grocery list item.
+
+**Response:** `{ success, deleted }`
+
+```bash
+curl -X DELETE "$MYN_API_URL/api/v1/households/HOUSEHOLD_ID/grocery-list/ITEM_ID" \
+  -H "X-API-KEY: $MYN_API_KEY"
+```
+
+### Delete Checked Items
+
+```
+DELETE /api/v1/households/{householdId}/grocery-list/checked
+```
+
+Deletes all checked (completed) items from the grocery list.
+
+**Response:** `{ success, deletedCount, undoAvailable }`
+
+```bash
+curl -X DELETE "$MYN_API_URL/api/v1/households/HOUSEHOLD_ID/grocery-list/checked" \
+  -H "X-API-KEY: $MYN_API_KEY"
 ```
 
 ### Bulk Add Items
 
 ```
-POST /api/v1/households/{householdId}/grocery-list/items/bulk
+POST /api/v1/households/{householdId}/grocery-list/bulk
 ```
 
 **Body Parameters:**
@@ -125,15 +170,10 @@ POST /api/v1/households/{householdId}/grocery-list/items/bulk
 | `items[].category` | string | Optional category |
 | `items[].quantity` | string | Optional quantity |
 
-**Response Fields:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `addedCount` | number | Number of items added |
-| `itemIds` | UUID[] | IDs of the newly created items |
+**Response:** `{ success, items: [{ id, name, category?, quantity?, checked }], count }`
 
 ```bash
-curl -X POST "$MYN_API_URL/api/v1/households/880e8400-e29b-41d4-a716-446655440003/grocery-list/items/bulk" \
+curl -X POST "$MYN_API_URL/api/v1/households/HOUSEHOLD_ID/grocery-list/bulk" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
@@ -161,16 +201,10 @@ Converts grocery list items into MYN tasks (e.g., for a shopping trip).
 | `uncheckedOnly` | boolean | Only convert unchecked items (default: true) |
 | `priority` | string | Priority for created tasks (e.g., `OPPORTUNITY_NOW`) |
 
-**Response Fields:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `convertedCount` | number | Number of items converted to tasks |
-| `taskIds` | UUID[] | IDs of the created tasks |
+**Response:** `{ success, tasks: [{ id, title }], count }`
 
 ```bash
-# Convert unchecked items to Opportunity Now tasks
-curl -X POST "$MYN_API_URL/api/v1/households/880e8400-e29b-41d4-a716-446655440003/grocery-list/convert-to-tasks" \
+curl -X POST "$MYN_API_URL/api/v1/households/HOUSEHOLD_ID/grocery-list/convert-to-tasks" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{

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

@@ -2,63 +2,79 @@
 
 Agent memory for storing and retrieving contextual information about users.
 
-## Base Path
-
-`/api/v1/customers/memories`
-
 ## Endpoints
 
 ### Remember (Store Memory)
 
 ```
-POST /api/v1/customers/memories
+POST /api/v1/agent/memories
 ```
 
 **Body:**
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `content` | string | Yes | Memory content to store |
-| `category` | string | No | `user_preference`, `work_context`, `personal_info`, `decision`, `insight`, `routine` |
-| `tags` | string[] | No | Tags for categorization |
-| `importance` | string | No | `low`, `medium`, `high`, `critical` |
-| `expiresAt` | datetime | No | Optional expiration date (ISO 8601) |
-
-**Response:** `{ memoryId, stored, createdAt }`
+| `content` | string | Yes | Memory content to store (max 500 chars) |
+| `type` | string | No | `PREFERENCE`, `PATTERN`, `STYLE`, `MYN_BEHAVIOR`, `PERSONAL`, `RELATIONSHIP` |
+
+**Note:** The tool accepts `category` as the input parameter name, but sends it as the `type` field in the request body.
+
+**Response:**
+
+```json
+{
+  "id": "uuid",
+  "type": "PREFERENCE",
+  "content": "User prefers morning meetings before 10am",
+  "confidence": 0.95,
+  "duplicate": false,
+  "message": "Memory stored successfully"
+}
+```
 
 ```bash
-curl -X POST "$MYN_API_URL/api/v1/customers/memories" \
+curl -X POST "$MYN_API_URL/api/v1/agent/memories" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "content": "User prefers morning meetings before 10am",
-    "category": "user_preference",
-    "tags": ["meetings", "preferences"],
-    "importance": "medium"
+    "type": "PREFERENCE"
   }'
 ```
 
 ### Recall (Get Memories)
 
 ```
-GET /api/v1/customers/memories
-GET /api/v1/customers/memories/{memoryId}
+GET /api/v1/customers/memories?limit=50
 ```
 
-Get recent memories (default limit 10) or a specific memory by ID.
+Returns all memories (up to 50). Optionally filter client-side by `memoryId`.
 
-**Response (specific):** `{ memoryId, content, category, tags[], importance, createdAt, accessedAt, accessCount, expiresAt? }`
+**Query Parameters:**
 
-**Response (list):** `{ memories[{ memoryId, content, category, tags[], importance, createdAt, accessedAt? }] }`
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `limit` | number | Max results (default: 50) |
+
+**Response:** Array of memory objects:
+
+```json
+[
+  {
+    "memoryId": "uuid",
+    "content": "User prefers morning meetings",
+    "category": "PREFERENCE",
+    "tags": [],
+    "importance": "medium",
+    "createdAt": "2026-03-01T00:00:00Z",
+    "accessedAt": "2026-03-09T10:00:00Z"
+  }
+]
+```
 
 ```bash
-# Get recent memories
-curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v1/customers/memories?limit=10"
-
-# Get specific memory
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v1/customers/memories/aabb0000-0000-0000-0000-000000000001"
+  "$MYN_API_URL/api/v1/customers/memories?limit=50"
 ```
 
 ### Forget (Delete Memory)
@@ -68,28 +84,44 @@ DELETE /api/v1/customers/memories/{memoryId}
 ```
 
 ```bash
-curl -X DELETE "$MYN_API_URL/api/v1/customers/memories/aabb0000-0000-0000-0000-000000000001" \
+curl -X DELETE "$MYN_API_URL/api/v1/customers/memories/MEMORY_ID" \
   -H "X-API-KEY: $MYN_API_KEY"
 ```
 
 ### Search Memories
 
 ```
-GET /api/v1/customers/memories/search
+GET /api/v1/agent/memories/search
 ```
 
+Semantic search across agent memories.
+
 **Query Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `q` | string | Search query |
-| `category` | string | Filter by category |
-| `tag` | string | Filter by tag (repeatable for multiple tags) |
+| `query` | string | **Required.** Search query |
 | `limit` | number | Max results (default: 10) |
 
-**Response:** `{ results[{ memoryId, content, category, tags[], importance, relevance, createdAt }], total }`
+**Response:**
+
+```json
+{
+  "results": [
+    {
+      "id": "uuid",
+      "type": "PREFERENCE",
+      "content": "User prefers morning meetings",
+      "confidence": 0.95,
+      "createdAt": "2026-03-01T00:00:00Z",
+      "topics": ["meetings", "scheduling"]
+    }
+  ],
+  "total": 1
+}
+```
 
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v1/customers/memories/search?q=meeting+preference&category=user_preference&limit=5"
+  "$MYN_API_URL/api/v1/agent/memories/search?query=meeting+preference&limit=5"
 ```

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

@@ -4,188 +4,91 @@ AI-powered planning, auto-scheduling, and rescheduling.
 
 ## Base Path
 
-`/api/schedules`
+`/planning`
+
+## Actions
+
+The `myn_planning` tool supports these actions: `plan`, `schedule_all`, `reschedule`.
 
 ## Endpoints
 
-### Create Plan
+### Plan (Trigger AI Planning)
 
 ```
-POST /api/schedules/plan
+GET /planning/plan
 ```
 
-Generate an AI plan for a goal or set of tasks.
-
-**Body:**
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `goal` | string | Yes* | What you want to accomplish |
-| `tasks` | array | Yes* | Tasks to plan (alternative to goal) |
-| `tasks[].title` | string | Yes | Task title |
-| `tasks[].estimatedDuration` | number | No | Duration in minutes |
-| `tasks[].dependsOn` | string[] | No | Task titles this depends on |
-| `tasks[].fixedTime` | datetime | No | Fixed time slot |
-| `constraints` | object | No | Planning constraints |
-| `constraints.availableHours` | number | No | Available hours |
-| `constraints.preferredTimes` | string[] | No | Preferred time slots |
-| `constraints.avoidTimes` | string[] | No | Times to avoid |
-| `constraints.deadline` | datetime | No | Hard deadline |
-| `constraints.priority` | string | No | `CRITICAL`, `OPPORTUNITY_NOW`, `OVER_THE_HORIZON` |
-
-*At least one of `goal` or `tasks` is required.
-
-**Response:**
-
-```json
-{
-  "planId": "uuid",
-  "goal": "Complete Q1 planning",
-  "estimatedDuration": 240,
-  "schedule": [
-    {
-      "step": 1,
-      "title": "Review last quarter metrics",
-      "description": "Pull Q4 data and analyze trends",
-      "estimatedMinutes": 60,
-      "suggestedTimeSlot": {
-        "start": "2026-03-01T09:00:00Z",
-        "end": "2026-03-01T10:00:00Z"
-      },
-      "dependencies": []
-    }
-  ],
-  "conflicts": [
-    {
-      "taskTitle": "Team standup",
-      "reason": "Overlaps with suggested time slot",
-      "suggestion": "Move to 10:30 AM"
-    }
-  ],
-  "suggestions": ["Consider breaking the budget review into two sessions"],
-  "createdAt": "2026-03-01T08:00:00Z"
-}
-```
+Triggers the AI planning engine to plan/schedule tasks for the current user. The backend handles this automatically based on the authenticated user's tasks -- no request body is needed.
+
+**Tool Parameters (accepted but not sent to backend):**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `goal` | string | What you want to accomplish |
+| `constraints` | object | Planning constraints |
+| `constraints.availableHours` | number | Available hours |
+| `constraints.preferredTimes` | string[] | Preferred time slots |
+| `constraints.avoidTimes` | string[] | Times to avoid |
+| `constraints.deadline` | datetime | Hard deadline |
+| `constraints.priority` | string | `CRITICAL`, `OPPORTUNITY_NOW`, `OVER_THE_HORIZON` |
+| `tasks` | array | Tasks to plan |
+
+**Response:** String result from the planning engine.
 
 ```bash
-curl -X POST "$MYN_API_URL/api/schedules/plan" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "goal": "Complete Q1 planning",
-    "constraints": {
-      "availableHours": 4,
-      "deadline": "2026-03-05T17:00:00Z",
-      "priority": "CRITICAL"
-    }
-  }'
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/planning/plan"
 ```
 
-### Auto-Schedule Day
+### Schedule All
 
 ```
-POST /api/schedules/auto
+POST /planning/scheduleAll
 ```
 
-Automatically schedule all unscheduled tasks for a day.
-
-**Body:**
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `date` | date | No | Date to schedule (default: today) |
-| `respectExisting` | boolean | No | Keep existing calendar items (default: true) |
-| `bufferMinutes` | number | No | Buffer between tasks (default: 15) |
-
-**Response:**
-
-```json
-{
-  "date": "2026-03-01",
-  "scheduled": [
-    {
-      "taskId": "uuid",
-      "title": "Prepare report",
-      "scheduledStart": "2026-03-01T09:00:00Z",
-      "scheduledEnd": "2026-03-01T11:00:00Z",
-      "priority": "CRITICAL"
-    }
-  ],
-  "unscheduled": [
-    {
-      "taskId": "uuid",
-      "title": "Research competitors",
-      "reason": "Not enough available time"
-    }
-  ],
-  "conflicts": [
-    {
-      "type": "overlap",
-      "description": "Two critical tasks competing for morning slot",
-      "tasksInvolved": ["uuid1", "uuid2"]
-    }
-  ],
-  "stats": {
-    "totalScheduled": 5,
-    "totalMinutes": 300,
-    "byPriority": { "CRITICAL": 2, "OPPORTUNITY_NOW": 3 }
-  }
-}
-```
+Auto-schedules all eligible tasks (today or past start date, not completed, not OVER_THE_HORIZON/PARKING_LOT) for the authenticated user, then triggers planning. No request body needed.
+
+**Note (MIN-740):** Changed from GET to POST.
 
 ```bash
-curl -X POST "$MYN_API_URL/api/schedules/auto" \
+curl -X POST "$MYN_API_URL/planning/scheduleAll" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
-  -d '{"date": "2026-03-01", "bufferMinutes": 15}'
+  -d '{}'
 ```
 
-### Reschedule Tasks
+### Reschedule (Kick the Can)
 
 ```
-POST /api/schedules/reschedule
+POST /planning/kickTheCan?rebalance={true|false}
 ```
 
-Move tasks to a different date.
-
-**Body:**
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `taskIds` | UUID[] | Yes | Tasks to reschedule |
-| `reason` | string | No | Why rescheduling |
-| `targetDate` | date | No | New target date |
-| `spreadOverDays` | number | No | Spread across N days (default: 1) |
-
-**Response:**
-
-```json
-{
-  "rescheduled": [
-    {
-      "taskId": "uuid",
-      "title": "Budget review",
-      "oldDate": "2026-03-01",
-      "newDate": "2026-03-03"
-    }
-  ],
-  "failed": [
-    {
-      "taskId": "uuid",
-      "reason": "Task is already completed"
-    }
-  ],
-  "suggestions": ["Consider spreading over 2 days to avoid overload"]
-}
-```
+Reschedules overdue/today tasks into the future based on priority. Optionally redistributes all uncompleted tasks evenly.
+
+**Note (MIN-740):** Changed from GET to POST.
+
+**Query Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `rebalance` | boolean | If `true`, redistribute all uncompleted tasks evenly (default: false) |
+
+**Tool Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `spreadOverDays` | number | If > 1, sets `rebalance=true` (default: 1) |
 
 ```bash
-curl -X POST "$MYN_API_URL/api/schedules/reschedule" \
+# Basic reschedule — defer overdue tasks
+curl -X POST "$MYN_API_URL/planning/kickTheCan?rebalance=false" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+
+# Rebalance — spread all uncompleted tasks evenly
+curl -X POST "$MYN_API_URL/planning/kickTheCan?rebalance=true" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
-  -d '{
-    "taskIds": ["uuid1", "uuid2"],
-    "targetDate": "2026-03-05",
-    "reason": "Meeting overran, no time today"
-  }'
+  -d '{}'
 ```