@mind-your-now/myn 0.4.0

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

@@ -0,0 +1,175 @@
+# Household API
+
+Household members, invites, and chore management.
+
+## Base Path
+
+`/api/v1/households` and `/api/v2/chores`
+
+## Getting the Household ID
+
+Most endpoints require a `householdId`. Get it from the user profile:
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/v1/customers/me"
+# → { "households": [{ "id": "uuid", "name": "Home" }] }
+```
+
+## Endpoints
+
+### List Members
+
+```
+GET /api/v1/households/{householdId}/members
+```
+
+**Response:**
+
+```json
+{
+  "householdId": "uuid",
+  "members": [
+    {
+      "id": "uuid",
+      "name": "John Doe",
+      "email": "john@example.com",
+      "role": "owner",
+      "joinedAt": "2026-01-15T00:00:00Z",
+      "avatarUrl": "https://..."
+    }
+  ],
+  "pendingInvites": [
+    {
+      "inviteId": "uuid",
+      "email": "jane@example.com",
+      "role": "member",
+      "invitedAt": "2026-03-01T00:00:00Z",
+      "expiresAt": "2026-03-08T00:00:00Z"
+    }
+  ]
+}
+```
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v1/households/HOUSEHOLD_ID/members"
+```
+
+### Invite Member
+
+```
+POST /api/v1/households/{householdId}/invites
+```
+
+**Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email` | email | Yes | Email to invite |
+| `role` | string | No | `member` or `admin` (default: member) |
+| `message` | string | No | Custom invite message |
+
+**Response:** `{ inviteId, invited, expiresAt }`
+
+```bash
+curl -X POST "$MYN_API_URL/api/v1/households/HOUSEHOLD_ID/invites" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"email": "jane@example.com", "role": "member"}'
+```
+
+### List Chores
+
+```
+GET /api/v2/chores?householdId={householdId}
+```
+
+**Response:**
+
+```json
+{
+  "householdId": "uuid",
+  "chores": [
+    {
+      "id": "uuid",
+      "title": "Take out trash",
+      "description": "Both kitchen and recycling",
+      "recurrenceRule": "FREQ=WEEKLY;BYDAY=TU,FR",
+      "assignedTo": "member-uuid",
+      "estimatedMinutes": 10,
+      "difficulty": "easy",
+      "category": "household"
+    }
+  ]
+}
+```
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/chores?householdId=HOUSEHOLD_ID"
+```
+
+### Get Chore Schedule
+
+```
+GET /api/v2/chores/schedule
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `householdId` | UUID | Required |
+| `date` | date | Specific date (YYYY-MM-DD) |
+| `weekStart` | date | Start of week to view |
+
+**Response:**
+
+```json
+{
+  "schedule": [
+    {
+      "date": "2026-03-01",
+      "dayOfWeek": 0,
+      "chores": [
+        {
+          "choreId": "uuid",
+          "title": "Take out trash",
+          "assignedTo": "member-uuid",
+          "estimatedMinutes": 10,
+          "completed": false
+        }
+      ]
+    }
+  ],
+  "totalChores": 5,
+  "completedChores": 2
+}
+```
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/chores/schedule?householdId=HOUSEHOLD_ID&date=2026-03-01"
+```
+
+### Complete Chore
+
+```
+POST /api/v2/chores/{choreId}/complete
+```
+
+**Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `completedBy` | UUID | No | Member who completed it |
+| `note` | string | No | Completion note |
+
+**Response:** `{ choreId, completed, completedAt, nextDueDate? }`
+
+```bash
+curl -X POST "$MYN_API_URL/api/v2/chores/CHORE_ID/complete" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"note": "Both bins taken to curb"}'
+```

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

@@ -0,0 +1,180 @@
+# Lists API
+
+Grocery and shopping list management scoped to households.
+
+## Base Path
+
+`/api/v1/households/{householdId}/grocery-list`
+
+## Prerequisites
+
+All list endpoints require a `householdId`. Retrieve it from the current user profile:
+
+```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
+```
+
+## Endpoints
+
+### Get Grocery List
+
+```
+GET /api/v1/households/{householdId}/grocery-list
+```
+
+Returns the full grocery list for the household.
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `householdId` | UUID | Household identifier |
+| `items` | object[] | Array of list items |
+| `items[].id` | UUID | Item identifier |
+| `items[].name` | string | Item name |
+| `items[].category` | string | Item category (nullable, e.g., `Produce`, `Dairy`) |
+| `items[].quantity` | string | Quantity description (nullable, e.g., `2 lbs`, `1 dozen`) |
+| `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 |
+
+```bash
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v1/households/880e8400-e29b-41d4-a716-446655440003/grocery-list"
+```
+
+### Add Item
+
+```
+POST /api/v1/households/{householdId}/grocery-list/items
+```
+
+**Body Parameters:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | **Required.** Item name |
+| `category` | string | Optional category (e.g., `Produce`, `Dairy`, `Frozen`) |
+| `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 |
+
+```bash
+curl -X POST "$MYN_API_URL/api/v1/households/880e8400-e29b-41d4-a716-446655440003/grocery-list/items" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Avocados",
+    "category": "Produce",
+    "quantity": "4",
+    "notes": "Ripe ones for guacamole"
+  }'
+```
+
+### Toggle Item Checked
+
+```
+PATCH /api/v1/households/{householdId}/grocery-list/items/{itemId}
+```
+
+**Body Parameters:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `checked` | boolean | Set checked state (toggles if omitted by some clients) |
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `itemId` | UUID | Item identifier |
+| `checked` | boolean | New checked state |
+
+```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" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"checked": true}'
+```
+
+### Bulk Add Items
+
+```
+POST /api/v1/households/{householdId}/grocery-list/items/bulk
+```
+
+**Body Parameters:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `items` | object[] | **Required.** Array of items to add |
+| `items[].name` | string | **Required.** Item name |
+| `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 |
+
+```bash
+curl -X POST "$MYN_API_URL/api/v1/households/880e8400-e29b-41d4-a716-446655440003/grocery-list/items/bulk" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "items": [
+      {"name": "Milk", "category": "Dairy", "quantity": "1 gallon"},
+      {"name": "Eggs", "category": "Dairy", "quantity": "1 dozen"},
+      {"name": "Bread", "category": "Bakery"},
+      {"name": "Chicken breast", "category": "Meat", "quantity": "2 lbs"}
+    ]
+  }'
+```
+
+### Convert to Tasks
+
+```
+POST /api/v1/households/{householdId}/grocery-list/convert-to-tasks
+```
+
+Converts grocery list items into MYN tasks (e.g., for a shopping trip).
+
+**Body Parameters:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `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 |
+
+```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" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "uncheckedOnly": true,
+    "priority": "OPPORTUNITY_NOW"
+  }'
+```

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

@@ -0,0 +1,95 @@
+# Memory API
+
+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
+```
+
+**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 }`
+
+```bash
+curl -X POST "$MYN_API_URL/api/v1/customers/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"
+  }'
+```
+
+### Recall (Get Memories)
+
+```
+GET /api/v1/customers/memories
+GET /api/v1/customers/memories/{memoryId}
+```
+
+Get recent memories (default limit 10) or a specific memory by ID.
+
+**Response (specific):** `{ memoryId, content, category, tags[], importance, createdAt, accessedAt, accessCount, expiresAt? }`
+
+**Response (list):** `{ memories[{ memoryId, content, category, tags[], importance, createdAt, accessedAt? }] }`
+
+```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"
+```
+
+### Forget (Delete Memory)
+
+```
+DELETE /api/v1/customers/memories/{memoryId}
+```
+
+```bash
+curl -X DELETE "$MYN_API_URL/api/v1/customers/memories/aabb0000-0000-0000-0000-000000000001" \
+  -H "X-API-KEY: $MYN_API_KEY"
+```
+
+### Search Memories
+
+```
+GET /api/v1/customers/memories/search
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `q` | string | Search query |
+| `category` | string | Filter by category |
+| `tag` | string | Filter by tag (repeatable for multiple tags) |
+| `limit` | number | Max results (default: 10) |
+
+**Response:** `{ results[{ memoryId, content, category, tags[], importance, relevance, createdAt }], total }`
+
+```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"
+```

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

@@ -0,0 +1,191 @@
+# Planning API
+
+AI-powered planning, auto-scheduling, and rescheduling.
+
+## Base Path
+
+`/api/schedules`
+
+## Endpoints
+
+### Create Plan
+
+```
+POST /api/schedules/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"
+}
+```
+
+```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"
+    }
+  }'
+```
+
+### Auto-Schedule Day
+
+```
+POST /api/schedules/auto
+```
+
+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 }
+  }
+}
+```
+
+```bash
+curl -X POST "$MYN_API_URL/api/schedules/auto" \
+  -H "X-API-KEY: $MYN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"date": "2026-03-01", "bufferMinutes": 15}'
+```
+
+### Reschedule Tasks
+
+```
+POST /api/schedules/reschedule
+```
+
+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"]
+}
+```
+
+```bash
+curl -X POST "$MYN_API_URL/api/schedules/reschedule" \
+  -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"
+  }'
+```