@mind-your-now/myn 0.8.1 → 0.8.3

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 '{}'
 ```

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

@@ -6,12 +6,16 @@ User information, goals, and preferences.
 
 `/api/v1/customers`
 
+## Actions
+
+The `myn_profile` tool supports these actions: `get_info`, `get_goals`, `update_goals`, `preferences`.
+
 ## Endpoints
 
 ### Get User Info
 
 ```
-GET /api/v1/customers/me
+GET /api/v1/customers
 ```
 
 **Response:**
@@ -40,7 +44,7 @@ GET /api/v1/customers/me
 ```
 
 ```bash
-curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/v1/customers/me"
+curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/v1/customers"
 ```
 
 ### Get Goals
@@ -49,100 +53,89 @@ curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/v1/customers/me"
 GET /api/v1/customers/goals
 ```
 
-**Response:** `{ goals[{ id, title, description?, targetDate?, priority, status, progress, createdAt, updatedAt, relatedTasks?[] }], activeCount, completedCount }`
+**Response:** `{ goalsAndAmbitions: string | null, stateHash: string }`
 
-- `priority`: `low`, `medium`, `high`
-- `status`: `active`, `completed`, `paused`, `abandoned`
-- `progress`: 0–100
+Goals are stored as a single markdown text field. The response includes a `stateHash` for use in the read-before-write protocol (MIN-740).
 
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/v1/customers/goals"
 ```
 
-### Create Goals
+### Update Goals
 
 ```
-POST /api/v1/customers/goals
+PUT /api/v1/customers/goals
 ```
 
-**Body:**
+**Uses read-before-write guard** (MIN-740). Reads goals first to get `stateHash`, retries on 409.
+
+The tool formats structured goal objects into markdown before sending:
+
+**Tool Parameters (goals array):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | string | **Required.** Goal title |
+| `description` | string | Goal description |
+| `targetDate` | date | Target date (YYYY-MM-DD) |
+| `priority` | string | `low`, `medium`, `high` |
+| `status` | string | `active`, `completed`, `paused`, `abandoned` |
+
+**Request Body (sent to backend):**
 
 ```json
 {
-  "goals": [
-    {
-      "title": "Run a marathon",
-      "description": "Complete a full marathon by end of year",
-      "targetDate": "2026-12-31",
-      "priority": "high"
-    }
-  ]
+  "goalsAndAmbitions": "- **Run a marathon** [active] (high priority)\n  Complete a full marathon by end of year\n  Target: 2026-12-31"
 }
 ```
 
-**Response:** `{ created[{ goalId, title }] }`
+**Response:** `{ status: "success", message: "Goals and ambitions updated successfully" }`
 
 ```bash
-curl -X POST "$MYN_API_URL/api/v1/customers/goals" \
+HASH=$(curl -s -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v1/customers/goals" | jq -r .stateHash)
+
+curl -X PUT "$MYN_API_URL/api/v1/customers/goals" \
   -H "X-API-KEY: $MYN_API_KEY" \
+  -H "X-MYN-State-Hash: $HASH" \
   -H "Content-Type: application/json" \
-  -d '{"goals": [{"title": "Read 24 books this year", "priority": "medium"}]}'
+  -d '{"goalsAndAmbitions": "- **Read 24 books this year** [active] (medium priority)"}'
 ```
 
-### Update Goal
+### Preferences
 
-```
-PUT /api/v1/customers/goals/{goalId}
-```
-
-**Body:** `{ title?, description?, targetDate?, priority?, status? }`
+Preferences are managed via dedicated endpoints, not a generic preferences store.
 
-**Response:** `{ goalId, updated }`
+**Valid preference keys:**
 
-```bash
-curl -X PUT "$MYN_API_URL/api/v1/customers/goals/aabb0000-0000-0000-0000-000000000001" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"status": "completed"}'
-```
+| Key | Endpoint |
+|-----|----------|
+| `notification-preferences` | `GET/PUT /api/v1/customers/notification-preferences` |
+| `coaching-intensity` | `GET/PUT /api/v1/customers/coaching-intensity` |
+| `theme-preference` | `GET/PUT /api/v1/customers/theme-preference` |
 
-### Get Preferences
+**Tool Behavior:**
 
-```
-GET /api/v1/customers/preferences
-GET /api/v1/customers/preferences/{key}
-```
+- With `preferenceKey` + `preferenceValue`: PUTs the value to the corresponding endpoint
+- With `preferenceKey` only: GETs from the corresponding endpoint
+- Without `preferenceKey`: GETs all preferences by fetching each endpoint
 
-**Query Parameters:**
+**Tool Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `category` | string | Filter: `notifications`, `display`, `ai`, `privacy`, `integrations` |
-
-**Response (all):** `{ preferences: { key: value, ... }, categories[] }`
-**Response (specific):** `{ key, value, category, updatedAt }`
+| `preferenceKey` | string | One of: `notification-preferences`, `coaching-intensity`, `theme-preference` |
+| `preferenceValue` | any | Value to set (triggers PUT) |
 
 ```bash
 # Get all preferences
-curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/v1/customers/preferences"
-
-# Get AI preferences only
-curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/v1/customers/preferences?category=ai"
-```
-
-### Set Preference
+curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/v1/customers/notification-preferences"
+curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/v1/customers/coaching-intensity"
+curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/v1/customers/theme-preference"
 
-```
-PUT /api/v1/customers/preferences
-```
-
-**Body:** `{ key, value, category? }`
-
-**Response:** `{ key, updated }`
-
-```bash
-curl -X PUT "$MYN_API_URL/api/v1/customers/preferences" \
+# Update theme
+curl -X PUT "$MYN_API_URL/api/v1/customers/theme-preference" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
-  -d '{"key": "ai.tone", "value": "friendly", "category": "ai"}'
+  -d '{"theme": "dark"}'
 ```

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

@@ -6,12 +6,16 @@ Project and category management for organizing tasks.
 
 `/api/project`
 
+## Actions
+
+The `myn_projects` tool supports these actions: `list`, `get`, `create`, `move_task`.
+
 ## Endpoints
 
 ### List Projects
 
 ```
-GET /api/project
+GET /api/project/defaults
 ```
 
 **Query Parameters:**
@@ -45,7 +49,7 @@ GET /api/project
 ```
 
 ```bash
-curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/project?includeStats=true"
+curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/project/defaults?includeStats=true"
 ```
 
 ### Get Project
@@ -87,14 +91,14 @@ curl -H "X-API-KEY: $MYN_API_KEY" "$MYN_API_URL/api/project/PROJECT_ID"
 ### Create Project
 
 ```
-POST /api/project
+POST /api/project/create
 ```
 
 **Body:**
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `name` | string | Yes | Project name (1–100 chars) |
+| `name` | string | Yes | Project name (1-100 chars) |
 | `description` | string | No | Description (max 500 chars) |
 | `color` | string | No | Hex color (`#3B82F6`) |
 | `icon` | string | No | Icon identifier |
@@ -103,7 +107,7 @@ POST /api/project
 **Response:** `{ id, name, created }`
 
 ```bash
-curl -X POST "$MYN_API_URL/api/project" \
+curl -X POST "$MYN_API_URL/api/project/create" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"name": "Home Renovation", "color": "#10B981", "icon": "home"}'
@@ -112,16 +116,14 @@ curl -X POST "$MYN_API_URL/api/project" \
 ### Move Task to Project
 
 ```
-PUT /api/v2/unified-tasks/{taskId}/project
+PUT /api/project/{targetProjectId}/moveTaskToProject/{taskId}
 ```
 
-**Body:** `{ projectId: "target-project-uuid" }`
+Moves a task to a different project. No request body needed.
 
 **Response:** `{ taskId, previousProjectId?, newProjectId, moved }`
 
 ```bash
-curl -X PUT "$MYN_API_URL/api/v2/unified-tasks/TASK_ID/project" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"projectId": "TARGET_PROJECT_ID"}'
+curl -X PUT "$MYN_API_URL/api/project/TARGET_PROJECT_ID/moveTaskToProject/TASK_ID" \
+  -H "X-API-KEY: $MYN_API_KEY"
 ```