@mind-your-now/myn 0.8.2 → 0.8.4

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"
 ```

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

@@ -11,23 +11,22 @@ Unified search across all MYN entity types with filtering, pagination, and relev
 ### Search
 
 ```
-POST /api/v2/search
+GET /api/v2/search
 ```
 
-Performs a full-text search across tasks, habits, chores, events, projects, notes, and memories.
+Performs a full-text search across tasks, habits, chores, events, projects, notes, and memories using query parameters.
 
-**Body Parameters:**
+**Query Parameters:**
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `query` | string | **Required.** Search query text |
-| `types` | string[] | Entity types to search. Options: `task`, `habit`, `chore`, `event`, `project`, `note`, `memory`. Omit to search all types. |
-| `filters` | object | Optional filters to narrow results |
-| `filters.status` | string | Filter by status (e.g., `PENDING`, `COMPLETED`) |
-| `filters.priority` | string | Filter by priority (e.g., `CRITICAL`, `OPPORTUNITY_NOW`) |
-| `filters.projectId` | UUID | Filter by project |
-| `filters.dateFrom` | date | Results from this date onward (YYYY-MM-DD) |
-| `filters.dateTo` | date | Results up to this date (YYYY-MM-DD) |
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `q` | string | **Required.** Search query text |
+| `types` | string | Entity types to search (repeatable). Options: `task`, `habit`, `chore`, `event`, `project`, `note`, `memory`. Omit to search all types. |
+| `status` | string | Filter by status (e.g., `PENDING`, `IN_PROGRESS`, `COMPLETED`, `ARCHIVED`) |
+| `priority` | string | Filter by priority (e.g., `CRITICAL`, `OPPORTUNITY_NOW`, `OVER_THE_HORIZON`, `PARKING_LOT`) |
+| `projectId` | UUID | Filter by project |
+| `dateFrom` | date | Results from this date onward (YYYY-MM-DD) |
+| `dateTo` | date | Results up to this date (YYYY-MM-DD) |
 | `limit` | number | Max results (default: 20, max: 100) |
 | `offset` | number | Pagination offset (default: 0) |
 
@@ -53,45 +52,18 @@ Performs a full-text search across tasks, habits, chores, events, projects, note
 
 ```bash
 # Basic search
-curl -X POST "$MYN_API_URL/api/v2/search" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"query": "quarterly report"}'
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/search?q=quarterly+report"
 
 # Search only tasks and notes
-curl -X POST "$MYN_API_URL/api/v2/search" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "quarterly report",
-    "types": ["task", "note"],
-    "limit": 10
-  }'
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/search?q=quarterly+report&types=task&types=note&limit=10"
 
 # Search with filters
-curl -X POST "$MYN_API_URL/api/v2/search" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "budget",
-    "types": ["task", "project"],
-    "filters": {
-      "status": "PENDING",
-      "priority": "CRITICAL",
-      "dateFrom": "2026-01-01",
-      "dateTo": "2026-03-31"
-    },
-    "limit": 50,
-    "offset": 0
-  }'
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/search?q=budget&types=task&types=project&status=PENDING&priority=CRITICAL&dateFrom=2026-01-01&dateTo=2026-03-31&limit=50"
 
 # Paginated search
-curl -X POST "$MYN_API_URL/api/v2/search" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "meeting notes",
-    "limit": 20,
-    "offset": 20
-  }'
+curl -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/search?q=meeting+notes&limit=20&offset=20"
 ```

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

@@ -6,6 +6,10 @@ Unified task management covering Tasks, Habits, and Chores.
 
 `/api/v2/unified-tasks`
 
+## Actions
+
+The `myn_tasks` tool supports these actions: `list`, `get`, `create`, `update`, `complete`, `archive`, `search`.
+
 ## Endpoints
 
 ### List Tasks
@@ -18,8 +22,8 @@ GET /api/v2/unified-tasks
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `status` | string | Filter: `PENDING`, `IN_PROGRESS`, `COMPLETED`, `ARCHIVED` |
-| `priority` | string | Filter: `CRITICAL`, `OPPORTUNITY_NOW`, `OVER_THE_HORIZON`, `PARKING_LOT` |
+| `status` | string | `PENDING`, `IN_PROGRESS`, `COMPLETED`, `ARCHIVED` |
+| `priority` | string | `CRITICAL`, `OPPORTUNITY_NOW`, `OVER_THE_HORIZON`, `PARKING_LOT` |
 | `projectId` | UUID | Filter by project |
 | `startDate` | date | Filter by start date (YYYY-MM-DD) |
 | `endDate` | date | Filter by end date (YYYY-MM-DD) |
@@ -27,13 +31,11 @@ GET /api/v2/unified-tasks
 | `offset` | number | Pagination offset (default: 0) |
 
 ```bash
-# List Critical Now tasks
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/unified-tasks?priority=CRITICAL&status=PENDING"
+  "$MYN_API_URL/api/v2/unified-tasks"
 
-# List tasks for a date range
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/unified-tasks?startDate=2026-03-01&endDate=2026-03-07"
+  "$MYN_API_URL/api/v2/unified-tasks?priority=CRITICAL&status=PENDING"
 ```
 
 ### Get Task
@@ -42,9 +44,11 @@ curl -H "X-API-KEY: $MYN_API_KEY" \
 GET /api/v2/unified-tasks/{taskId}
 ```
 
+The response includes a `stateHash` field for use in write operations (MIN-740 read-before-write guard).
+
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-446655440000"
+  "$MYN_API_URL/api/v2/unified-tasks/TASK_ID"
 ```
 
 ### Create Task
@@ -57,8 +61,7 @@ POST /api/v2/unified-tasks
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `id` | UUID | Client-generated UUID |
-| `title` | string | Task title (1–200 chars) |
+| `title` | string | Task title (1-200 chars) |
 | `taskType` | string | `TASK`, `HABIT`, or `CHORE` |
 | `priority` | string | `CRITICAL`, `OPPORTUNITY_NOW`, `OVER_THE_HORIZON`, `PARKING_LOT` |
 | `startDate` | date | Start date (YYYY-MM-DD) |
@@ -67,10 +70,15 @@ POST /api/v2/unified-tasks
 
 | Field | Type | Description |
 |-------|------|-------------|
+| `id` | UUID | Optional (auto-generated if omitted). Do NOT fabricate UUIDs. |
 | `description` | string | Description (max 2000 chars) |
-| `duration` | string | Duration: `"30m"`, `"1h"`, `"1h30m"` (NOT ISO PT prefix) |
+| `duration` | string | Duration: `"30m"`, `"1h"`, `"1h30m"` |
 | `projectId` | UUID | Assign to project |
 | `recurrenceRule` | string | RRULE for HABIT/CHORE types (**required** for HABIT and CHORE) |
+| `isAutoScheduled` | boolean | Enable auto-scheduling (default: true). Only set false if user explicitly opts out. |
+| `calendarId` | string | Calendar ID to link task to (e.g. "primary") |
+| `calendarName` | string | Calendar name to resolve (e.g. "Family", "Work"). Used instead of calendarId. |
+| `scheduleNames` | string[] | Schedule names to assign (e.g. `["Morning"]`, `["Weekday Evening", "Weekend Morning"]`). Resolved to IDs automatically. |
 
 **Type-Specific Rules:**
 
@@ -84,13 +92,14 @@ curl -X POST "$MYN_API_URL/api/v2/unified-tasks" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
-    "id": "550e8400-e29b-41d4-a716-446655440000",
     "title": "Prepare quarterly report",
     "taskType": "TASK",
     "priority": "CRITICAL",
     "startDate": "2026-03-01",
     "duration": "2h",
-    "description": "Q1 financials and projections"
+    "description": "Q1 financials and projections",
+    "isAutoScheduled": true,
+    "scheduleNames": ["Morning"]
   }'
 
 # Create a habit
@@ -98,7 +107,6 @@ curl -X POST "$MYN_API_URL/api/v2/unified-tasks" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
-    "id": "660e8400-e29b-41d4-a716-446655440001",
     "title": "Morning meditation",
     "taskType": "HABIT",
     "priority": "OPPORTUNITY_NOW",
@@ -114,11 +122,17 @@ curl -X POST "$MYN_API_URL/api/v2/unified-tasks" \
 PATCH /api/v2/unified-tasks/{taskId}
 ```
 
-Send only the fields to update:
+**Uses read-before-write guard** (MIN-740). Reads task first to get `stateHash`, retries on 409.
+
+Send only the fields to update via the `updates` object. Allowed fields: `title`, `description`, `priority`, `status`, `startDate`, `endDate`, `duration`, `projectId`, `recurrenceRule`, `isAutoScheduled`, `calendarId`, `location`, `notes`, `tags`, `estimatedMinutes`, `actualMinutes`, `completedAt`, `archivedAt`, `taskType`, `assignedTo`, `scheduledAt`, `dueDate`.
 
 ```bash
-curl -X PATCH "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-446655440000" \
+HASH=$(curl -s -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/unified-tasks/TASK_ID" | jq -r .stateHash)
+
+curl -X PATCH "$MYN_API_URL/api/v2/unified-tasks/TASK_ID" \
   -H "X-API-KEY: $MYN_API_KEY" \
+  -H "X-MYN-State-Hash: $HASH" \
   -H "Content-Type: application/json" \
   -d '{"priority": "OPPORTUNITY_NOW", "startDate": "2026-03-05"}'
 ```
@@ -129,9 +143,15 @@ curl -X PATCH "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-4466554
 POST /api/v2/unified-tasks/{taskId}/complete
 ```
 
+**Uses read-before-write guard** (MIN-740).
+
 ```bash
-curl -X POST "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-446655440000/complete" \
+HASH=$(curl -s -H "X-API-KEY: $MYN_API_KEY" \
+  "$MYN_API_URL/api/v2/unified-tasks/TASK_ID" | jq -r .stateHash)
+
+curl -X POST "$MYN_API_URL/api/v2/unified-tasks/TASK_ID/complete" \
   -H "X-API-KEY: $MYN_API_KEY" \
+  -H "X-MYN-State-Hash: $HASH" \
   -H "Content-Type: application/json" \
   -d '{}'
 ```
@@ -142,8 +162,10 @@ curl -X POST "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-44665544
 POST /api/v2/unified-tasks/{taskId}/archive
 ```
 
+**Uses read-before-write guard** (MIN-740).
+
 ```bash
-curl -X POST "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-446655440000/archive" \
+curl -X POST "$MYN_API_URL/api/v2/unified-tasks/TASK_ID/archive" \
   -H "X-API-KEY: $MYN_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{}'
@@ -157,31 +179,16 @@ GET /api/v2/search
 
 See [search-api.md](search-api.md) for full search documentation.
 
-```bash
-curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/search?q=quarterly+report&limit=10"
-```
-
-### Get Habit Streak
+**Query Parameters:**
 
-```
-GET /api/v2/unified-tasks/{taskId}/streak
-```
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `q` | string | Search query |
+| `includeArchived` | boolean | Include archived results (default: false) |
+| `limit` | number | Max results (default: 20) |
+| `offset` | number | Pagination offset (default: 0) |
 
 ```bash
 curl -H "X-API-KEY: $MYN_API_KEY" \
-  "$MYN_API_URL/api/v2/unified-tasks/660e8400-e29b-41d4-a716-446655440001/streak"
-```
-
-### Move Task to Project
-
-```
-PUT /api/v2/unified-tasks/{taskId}/project
-```
-
-```bash
-curl -X PUT "$MYN_API_URL/api/v2/unified-tasks/550e8400-e29b-41d4-a716-446655440000/project" \
-  -H "X-API-KEY: $MYN_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"projectId": "770e8400-e29b-41d4-a716-446655440002"}'
+  "$MYN_API_URL/api/v2/search?q=quarterly+report&limit=10"
 ```