# Kade v0.2.1 — Meds CRUD endpoints

**From:** Riv
**To:** Forge
**Date:** 2026-05-24
**Priority:** Jimmie hit the wall live — he tried to edit his medication schedule via Slack and Kade had to tell him no. He wants this fixed.

---

## Problem

The Kade v0.2 conversational agent (shipped today) has 7 task-side tools but ZERO med-editing tools. When Jimmie said "I need to make a correction to my medication schedule" the agent had no endpoint to call. With the v0.2.1 honesty rule I just added, Kade now says plainly "tool isn't wired yet" instead of pretending — which is correct but obviously not what Jimmie wants long-term.

## What's needed

Three bearer-auth endpoints under `/api/kade/meds/*` (same pattern as the existing meds/today, meds/fire, etc.):

### `GET /api/kade/meds/list`

Return all meds (active + inactive) so the bot can show Jimmie his current schedule before he edits.

```json
{
  "ok": true,
  "count": 5,
  "meds": [
    {
      "id": 1, "name": "Adderall", "dose_label": "morning",
      "fire_local_time": "08:00", "weekdays_mask": 127,
      "active": true, "dosage_notes": null, "follow_up_minutes": 30,
      "created_at": "...", "updated_at": "..."
    }
  ]
}
```

`weekdays_mask` is the same bitmask the existing `meds/today` query uses — bit 0 = Sun, bit 6 = Sat (127 = all 7 days). Bot will render it human-readably; you don't need to translate.

### `POST /api/kade/meds/create`

Add a new med.

**Request:**
```json
{
  "name": "Lexapro",                    // required, non-empty
  "dose_label": "morning",              // required, non-empty
  "fire_local_time": "08:30",           // required, HH:MM 24h
  "weekdays_mask": 127,                 // optional, default 127 (every day)
  "active": true,                       // optional, default true
  "dosage_notes": "with food",          // optional
  "follow_up_minutes": 30               // optional, default 30
}
```

**Response 201:** `{ "ok": true, "med_id": 6 }`
**Response 409:** if `(name, dose_label)` already exists — uniqueness should be enforced (suggest a partial unique index).

### `POST /api/kade/meds/update`

Update any subset of fields on an existing med. Same endpoint handles rename, time change, day-of-week change, activate/deactivate.

**Request:**
```json
{
  "med_id": 3,                          // required
  "name": "...",                        // optional
  "dose_label": "...",                  // optional
  "fire_local_time": "11:45",           // optional
  "weekdays_mask": 62,                  // optional (62 = M-F)
  "active": false,                      // optional — false deactivates without deleting
  "dosage_notes": "...",                // optional, null clears
  "follow_up_minutes": 45               // optional
}
```

**Response 200:**
```json
{ "ok": true, "med_id": 3, "changed": ["fire_local_time","weekdays_mask"] }
```

**Response 404** if med_id doesn't exist. **Response 400** on bad time format / weekdays_mask out of range.

---

## Out of scope for this round

- **Hard delete.** Soft-delete via `active=false` is enough — preserves the audit trail in `kade_meds_log` (fires/acks/skips referenced by med_id will FK-cascade if you hard-delete, which is bad).
- **Audit log on meds edits.** `kade_meds_log.event_type` CHECK is `('fire','ack','skip','missed')` — adding `'edited'` would need a migration. Skip for now; the `updated_at` field on `kade_meds` is sufficient diagnostic if anyone asks "when did this change."
- **Bot reload of the day's schedule.** That's MY problem on the bot side — when the agent tool-calls one of these endpoints, I'll trigger a scheduler reload in-process so the change takes effect immediately without a bot restart. You don't need to do anything about it.

---

## Validation hints (for your input parsing)

- `fire_local_time`: must match `^([01]\d|2[0-3]):[0-5]\d$`. Reject seconds.
- `weekdays_mask`: must be 0 ≤ n ≤ 127 integer.
- `follow_up_minutes`: 1 ≤ n ≤ 240.
- `name` + `dose_label`: non-empty trimmed, max ~50 chars each (current rows are well under).

---

## When you're done

Drop a one-liner here or in `Team Inbox/Forge/` confirming the endpoints respond. I'll then:
1. Extend `atlas_client.py` with the three Python wrappers
2. Add three tool definitions to `agent.py`
3. Ship a scheduler.reload() hook so meds edits take effect mid-day
4. Smoke-test against Kade with a real edit

ETA on my side after your endpoints land: ~30 min.

— Riv