ofw-mcp 2.4.4 → 2.5.0

package/dist/sync.js

@@ -1,6 +1,6 @@
 import { setMeta, upsertMessage, getMessage, deleteMessage, setSyncState, upsertDraft, getDraft, deleteDraft, listDraftIds, upsertAttachmentForMessage, } from './cache.js';
 import { z } from 'zod';
-import { ApiRecipientSchema, mapRecipients } from './tools/_shared.js';
+import { ApiRecipientSchema, hasRealView, mapRecipients } from './tools/_shared.js';
 import { parseLenient } from '@chrischall/mcp-utils';
 // Each OFW message detail returns `files: [fileId, ...]`. We fetch the metadata
 // for each file id (cheap JSON call) so the model can see filenames/mime types
@@ -75,6 +75,9 @@ const ListResponseSchema = z.looseObject({ data: z.array(ListItemSchema).optiona
 const DetailResponseSchema = z.looseObject({
     body: z.string().optional(),
     files: z.array(z.number()).optional(),
+    // The detail endpoint carries the REAL recipient view timestamps (the list
+    // endpoint only has an epoch placeholder) — used by the view-status refresh.
+    recipients: z.array(ApiRecipientSchema).optional(),
 });
 export async function syncMessageFolder(client, folder, folderId, opts) {
     let page = 1;
@@ -92,8 +95,21 @@ export async function syncMessageFolder(client, folder, folderId, opts) {
             if (newestId === null || item.id > newestId)
                 newestId = item.id;
             const existing = getMessage(item.id);
-            if (existing)
+            if (existing) {
+                // A sent message's read status changes AFTER it's first cached, when
+                // the recipient opens it — so we can't just skip existing rows. The
+                // list item carries the reliable `showNeverViewed` boolean but only an
+                // epoch placeholder for the timestamp; the real "First Viewed" time is
+                // on the detail endpoint. So when a sent message has flipped to read
+                // and we don't yet hold a real viewed time, re-fetch detail to capture
+                // it (no body re-fetch — only the recipient view fields can change).
+                if (folder === 'sent' && item.showNeverViewed === false && !hasRealView(existing.recipients)) {
+                    const detail = parseLenient(DetailResponseSchema, await client.request('GET', `/pub/v3/messages/${item.id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (view-status refresh)' });
+                    upsertMessage({ ...existing, recipients: mapRecipients(detail.recipients), listData: item });
+                    synced++;
+                }
                 continue;
+            }
             pageHadNewItem = true;
             const isInboxUnread = folder === 'inbox' && item.showNeverViewed === true;
             const shouldFetchBody = !isInboxUnread || opts.fetchUnreadBodies;

package/dist/tools/_shared.js

@@ -15,13 +15,30 @@ export const ApiRecipientSchema = z.looseObject({
 });
 // Translates OFW API recipient shape into the cache's normalized Recipient.
 // Used wherever we surface or persist recipients (sync, get_message, send,
-// save_draft) — all five call sites had near-identical inline mappings.
+// save_draft).
+//
+// `viewedAt` is the recipient's true "First Viewed" time, or null if not yet
+// viewed. Only the DETAIL endpoint (/pub/v3/messages/{id}) carries a real
+// timestamp; the LIST endpoint returns an epoch-zero PLACEHOLDER
+// ("1970-01-01T00:00:00") in the SAME field even for read messages (on the
+// list, read status lives in `showNeverViewed`, not the timestamp). So treat
+// the epoch placeholder as "no real view time" — otherwise a list-sourced row
+// reports a bogus 1970 read time. A detail re-fetch is what fills in the truth.
 export function mapRecipients(items) {
-    return (items ?? []).map((r) => ({
-        userId: r.user?.id ?? 0,
-        name: r.user?.name ?? '',
-        viewedAt: r.viewed?.dateTime ?? null,
-    }));
+    return (items ?? []).map((r) => {
+        const dt = r.viewed?.dateTime;
+        const viewedAt = typeof dt === 'string' && !dt.startsWith('1970-01-01') ? dt : null;
+        return { userId: r.user?.id ?? 0, name: r.user?.name ?? '', viewedAt };
+    });
+}
+// True if any recipient has a *real* "First Viewed" time — i.e. present and
+// not the epoch-zero placeholder. After mapRecipients a fresh `viewedAt` is
+// only ever a real timestamp or null, but a cache row written by older code
+// (which trusted the list endpoint's `viewed`) may still hold the literal
+// "1970-01-01T00:00:00". Treating that as "not viewed" lets sync/get_message
+// re-fetch detail and self-heal the stale row to the real timestamp.
+export function hasRealView(recipients) {
+    return recipients.some((r) => r.viewedAt !== null && !r.viewedAt.startsWith('1970-01-01'));
 }
 // Expand a user-provided path: ~ → home, relative → absolute. Re-exports
 // @chrischall/mcp-utils' `expandPath`.

package/dist/tools/calendar.js

@@ -1,9 +1,113 @@
 import { z } from 'zod';
 import { jsonResponse, textResponse } from './_shared.js';
-import { getWriteMode } from '../config.js';
+import { getCalendarWritesAllowed } from '../config.js';
+import { parseLenient } from '@chrischall/mcp-utils';
+// OFW's real event-write API (reverse-engineered from the web app bundle):
+//   POST   /pub/v3/events                       create — 201 with the full event
+//   GET    /pub/v3/events/{eventRecurrenceId}   detail
+//   PUT    /pub/v3/events/{eventRecurrenceId}   update — full payload, not a patch
+//   DELETE /pub/v3/events/{eventRecurrenceId}?includeFuture=<bool>
+// The id in every URL is `eventRecurrenceId` — the same value calendar
+// listings expose as `id`. (`eventId` in the response is a different,
+// internal identifier; never put it in a URL.)
+// Payload gotchas: dates are `YYYY-MM-DD` with separate `HH:mm` times;
+// privacy is `publicFlag` (true = shared with co-parent); parent ids must be
+// OMITTED when unset — the web form's "0" placeholders draw a 409
+// "Must be a parent" from the API.
+const ofwDate = z.looseObject({ dateTime: z.string() });
+const userRef = z.looseObject({ userId: z.number() });
+const eventDetailSchema = z.looseObject({
+    eventRecurrenceId: z.number(),
+    title: z.string(),
+    allDay: z.boolean(),
+    publicFlag: z.boolean(),
+    startDate: ofwDate,
+    endDate: ofwDate,
+    location: z.string().nullish(),
+    notes: z.string().nullish(),
+    reminderMinutes: z.number().nullish(),
+    children: z.array(userRef).nullish(),
+    eventParent: userRef.nullish(),
+    dropOffParent: userRef.nullish(),
+    pickUpParent: userRef.nullish(),
+});
+const eventWriteFields = {
+    startDate: z.string().describe('Start date YYYY-MM-DD'),
+    endDate: z.string().describe('End date YYYY-MM-DD (default: startDate)').optional(),
+    startTime: z.string().describe('Start time HH:mm, 24-hour (required unless allDay)').optional(),
+    endTime: z.string().describe('End time HH:mm, 24-hour (required unless allDay)').optional(),
+    allDay: z.boolean().optional(),
+    privateEvent: z.boolean().describe('true = visible only to you; default false = shared with co-parent').optional(),
+    location: z.string().optional(),
+    notes: z.string().optional(),
+    reminderMinutes: z.number().int().min(0).optional(),
+    children: z.array(z.number()).describe('Child userIds to tag (see ofw_get_profile)').optional(),
+    eventParentId: z.number().describe("userId of the parent the event is 'for'").optional(),
+    dropOffParentId: z.number().describe('userId of the drop-off parent').optional(),
+    pickUpParentId: z.number().describe('userId of the pick-up parent').optional(),
+};
+function buildEventPayload(a) {
+    const allDay = a.allDay ?? false;
+    if (!allDay && (!a.startTime || !a.endTime)) {
+        throw new Error('startTime and endTime (HH:mm) are required unless allDay is true');
+    }
+    const payload = {
+        title: a.title,
+        startDate: a.startDate,
+        endDate: a.endDate ?? a.startDate,
+        // The web form always sends times; for all-day events it uses 01:00/02:00
+        // placeholders that OFW ignores.
+        startTime: a.startTime ?? '01:00',
+        endTime: a.endTime ?? '02:00',
+        allDay,
+        publicFlag: !(a.privateEvent ?? false),
+    };
+    if (a.location)
+        payload.location = a.location;
+    if (a.notes)
+        payload.notes = a.notes;
+    if (a.reminderMinutes !== undefined)
+        payload.reminderMinutes = String(a.reminderMinutes);
+    // Omitted `children` PRESERVES existing tags on PUT; an explicit [] CLEARS
+    // them (verified live 2026-07-13) — so send the array whenever it's defined.
+    if (a.children !== undefined)
+        payload.children = a.children;
+    if (a.eventParentId !== undefined)
+        payload.eventParentId = String(a.eventParentId);
+    if (a.dropOffParentId !== undefined)
+        payload.dropOffParentId = String(a.dropOffParentId);
+    if (a.pickUpParentId !== undefined)
+        payload.pickUpParentId = String(a.pickUpParentId);
+    return payload;
+}
+// Map a detail response back onto write-args so ofw_update_event can send the
+// full payload OFW's PUT expects while the caller only names the changes.
+function detailToWriteArgs(d) {
+    const [startDate, startClock] = d.startDate.dateTime.split('T');
+    const [endDate, endClock] = d.endDate.dateTime.split('T');
+    return {
+        title: d.title,
+        startDate,
+        endDate,
+        startTime: (startClock ?? '01:00:00').slice(0, 5),
+        endTime: (endClock ?? '02:00:00').slice(0, 5),
+        allDay: d.allDay,
+        privateEvent: !d.publicFlag,
+        location: d.location ?? undefined,
+        notes: d.notes ?? undefined,
+        reminderMinutes: d.reminderMinutes ?? undefined,
+        // Untagged (nullish or empty) → undefined, so the merged PUT omits the
+        // field (omission preserves; only a CALLER-supplied [] should clear).
+        children: d.children?.length ? d.children.map((c) => c.userId) : undefined,
+        eventParentId: d.eventParent?.userId,
+        dropOffParentId: d.dropOffParent?.userId,
+        pickUpParentId: d.pickUpParent?.userId,
+    };
+}
 export function registerCalendarTools(server, client) {
-    // Calendar writes land on the court-visible record — OFW_WRITE_MODE 'all' only.
-    const allowWrites = getWriteMode() === 'all';
+    // Calendar writes land on the court-visible record with no draft stage, but
+    // events are reversible — 'all' mode, or 'drafts' + OFW_CALENDAR_WRITES=true.
+    const allowWrites = getCalendarWritesAllowed();
     server.registerTool('ofw_list_events', {
         description: 'List OurFamilyWizard calendar events in a date range',
         annotations: { readOnlyHint: true },
@@ -19,53 +123,65 @@ export function registerCalendarTools(server, client) {
     });
     if (allowWrites)
         server.registerTool('ofw_create_event', {
-            description: 'Create a calendar event in OurFamilyWizard',
+            description: 'Create a calendar event in OurFamilyWizard. Unless privateEvent is true, the event is immediately visible to the co-parent — there is no draft stage.',
             annotations: { destructiveHint: false },
             inputSchema: {
                 title: z.string(),
-                startDate: z.string().describe('ISO datetime string'),
-                endDate: z.string().describe('ISO datetime string'),
-                allDay: z.boolean().optional(),
-                location: z.string().optional(),
-                reminder: z.string().describe('Reminder setting (e.g. "1 hour before")').optional(),
-                privateEvent: z.boolean().optional(),
-                eventFor: z.string().describe('neither | parent1 | parent2').optional(),
-                dropOffParent: z.string().optional(),
-                pickUpParent: z.string().optional(),
-                children: z.array(z.number()).describe('Array of child IDs').optional(),
+                ...eventWriteFields,
             },
         }, async (args) => {
-            const data = await client.request('POST', '/pub/v1/calendar/events', args);
-            return jsonResponse(data);
+            const raw = await client.request('POST', '/pub/v3/events', buildEventPayload(args));
+            const event = parseLenient(eventDetailSchema, raw, { label: 'ofw-mcp', context: 'POST /pub/v3/events', mode: 'strict' });
+            return jsonResponse({
+                note: `Event created. Use eventRecurrenceId ${event.eventRecurrenceId} as eventId for ofw_update_event/ofw_delete_event.`,
+                event,
+            });
         });
     if (allowWrites)
         server.registerTool('ofw_update_event', {
-            description: 'Update an existing OurFamilyWizard calendar event',
+            description: 'Update an existing OurFamilyWizard calendar event. Fetches the event, applies the given changes, and writes the merged result back (OFW has no partial update).',
             annotations: { destructiveHint: true },
             inputSchema: {
-                eventId: z.string(),
+                eventId: z.string().describe('Event id — the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event'),
                 title: z.string().optional(),
-                startDate: z.string().optional(),
-                endDate: z.string().optional(),
-                allDay: z.boolean().optional(),
-                location: z.string().optional(),
-                reminder: z.string().optional(),
-                privateEvent: z.boolean().optional(),
+                startDate: eventWriteFields.startDate.optional(),
+                endDate: eventWriteFields.endDate,
+                startTime: eventWriteFields.startTime,
+                endTime: eventWriteFields.endTime,
+                allDay: eventWriteFields.allDay,
+                privateEvent: eventWriteFields.privateEvent,
+                location: eventWriteFields.location,
+                notes: eventWriteFields.notes,
+                reminderMinutes: eventWriteFields.reminderMinutes,
+                children: z.array(z.number()).describe('Child userIds to tag; pass [] to remove all child tags (omit to keep current tags)').optional(),
+                eventParentId: eventWriteFields.eventParentId,
+                dropOffParentId: eventWriteFields.dropOffParentId,
+                pickUpParentId: eventWriteFields.pickUpParentId,
             },
         }, async (args) => {
-            const { eventId, ...updateData } = args;
-            const data = await client.request('PUT', `/pub/v1/calendar/events/${encodeURIComponent(eventId)}`, updateData);
-            return jsonResponse(data);
+            const { eventId, ...changes } = args;
+            const id = encodeURIComponent(eventId);
+            const rawDetail = await client.request('GET', `/pub/v3/events/${id}`);
+            const current = parseLenient(eventDetailSchema, rawDetail, { label: 'ofw-mcp', context: `GET /pub/v3/events/${eventId}`, mode: 'strict' });
+            const defined = Object.fromEntries(Object.entries(changes).filter(([, v]) => v !== undefined));
+            const merged = { ...detailToWriteArgs(current), ...defined };
+            await client.request('PUT', `/pub/v3/events/${id}`, buildEventPayload(merged));
+            // PUT responses aren't documented — re-fetch the detail as authoritative state.
+            const rawAfter = await client.request('GET', `/pub/v3/events/${id}`);
+            const event = parseLenient(eventDetailSchema, rawAfter, { label: 'ofw-mcp', context: `GET /pub/v3/events/${eventId} (post-update)`, mode: 'strict' });
+            return jsonResponse({ note: 'Event updated; returning re-fetched event state.', event });
         });
     if (allowWrites)
         server.registerTool('ofw_delete_event', {
             description: 'Delete an OurFamilyWizard calendar event',
             annotations: { destructiveHint: true },
             inputSchema: {
-                eventId: z.string().describe('Event ID to delete'),
+                eventId: z.string().describe('Event id — the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event'),
+                includeFuture: z.boolean().describe('For repeating events: also delete future occurrences (default false)').optional(),
             },
         }, async (args) => {
-            await client.request('DELETE', `/pub/v1/calendar/events/${encodeURIComponent(args.eventId)}`);
+            const includeFuture = args.includeFuture ?? false;
+            await client.request('DELETE', `/pub/v3/events/${encodeURIComponent(args.eventId)}?includeFuture=${includeFuture}`);
             return textResponse(`Event ${args.eventId} deleted`);
         });
 }

package/dist/tools/messages.js

@@ -5,7 +5,7 @@ import { getAttachmentsDir, getDefaultInlineAttachments, getWriteMode } from '..
 import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, join } from 'node:path';
 import { fileBlob } from '@chrischall/mcp-utils';
-import { ApiRecipientSchema, expandPath, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded } from './_shared.js';
+import { ApiRecipientSchema, expandPath, hasRealView, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded } from './_shared.js';
 import { parseLenient } from '@chrischall/mcp-utils';
 // Schemas for the load-bearing fields of each /pub/v3 response this file
 // reads (issue #83). Loose: unknown keys pass through into cached listData.
@@ -183,6 +183,32 @@ export function registerMessageTools(server, client) {
         }
         const cached = getMessage(id);
         if (cached && cached.body !== null) {
+            let row = cached;
+            // Refresh view status for a sent message we still believe is unviewed:
+            // the recipient may have opened it since the last sync, and the detail
+            // endpoint carries the real "First Viewed" timestamp (a list-synced row
+            // only knows the showNeverViewed boolean / epoch placeholder). Best-
+            // effort and one-way — once a real viewed time is cached we stop re-
+            // fetching. Sent-only: re-hitting an unread INBOX detail would mark it
+            // read on OFW.
+            if (cached.folder === 'sent' && !hasRealView(cached.recipients)) {
+                try {
+                    const detail = parseLenient(MessageDetailSchema, await client.request('GET', `/pub/v3/messages/${id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (view-status refresh)' });
+                    const recipients = mapRecipients(detail.recipients);
+                    // Keep the raw listData read-flag in step with the refreshed
+                    // recipients so `showNeverViewed` can't contradict `viewedAt`.
+                    // (Spreading a null/absent listData is a no-op, so no guard needed.)
+                    row = {
+                        ...cached,
+                        recipients,
+                        listData: { ...cached.listData, showNeverViewed: !hasRealView(recipients) },
+                    };
+                    upsertMessage(row);
+                }
+                catch {
+                    // Best-effort: fall back to the cached row on any fetch/parse error.
+                }
+            }
             let attachments = listAttachmentsForMessage(id);
             // Lazy attachment backfill. The list-endpoint payload (stored in
             // listData) hints at attachments via `files: <count>` but doesn't
@@ -191,7 +217,7 @@ export function registerMessageTools(server, client) {
             // attachments table is empty even though OFW has files. Re-hit
             // detail to harvest fileIds (idempotent: body is already cached so
             // OFW state isn't changing).
-            if (attachments.length === 0 && listDataHintsAtFiles(cached.listData)) {
+            if (attachments.length === 0 && listDataHintsAtFiles(row.listData)) {
                 try {
                     const detail = parseLenient(DetailFilesSchema, await client.request('GET', `/pub/v3/messages/${id}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (attachment backfill)' });
                     if (Array.isArray(detail.files) && detail.files.length > 0) {
@@ -203,7 +229,7 @@ export function registerMessageTools(server, client) {
                     // Backfill is best-effort. Fall through with whatever we have.
                 }
             }
-            return jsonResponse({ ...cached, attachments });
+            return jsonResponse({ ...row, attachments });
         }
         const detail = parseLenient(MessageDetailSchema, await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (ofw_get_message)' });
         const folder = cached?.folder ?? 'inbox';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ofw-mcp",
-  "version": "2.4.4",
+  "version": "2.5.0",
   "license": "MIT",
   "mcpName": "io.github.chrischall/ofw-mcp",
   "description": "OurFamilyWizard MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -32,7 +32,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.12.0",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/bootstrap": "^1.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
@@ -42,7 +42,7 @@
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     "esbuild": "^0.28.0",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.7"
   }
 }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.4.4",
+  "version": "2.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.4.4",
+      "version": "2.5.0",
       "transport": {
         "type": "stdio"
       },
@@ -34,6 +34,12 @@
           "description": "Write-tool gate: \"none\" registers no write tools; \"drafts\" registers draft-level writes only (save/delete drafts, upload attachments); \"all\" registers everything (default). Unrecognized values fail closed to \"none\".",
           "isRequired": false,
           "format": "string"
+        },
+        {
+          "name": "OFW_CALENDAR_WRITES",
+          "description": "Set to \"true\" to register calendar write tools (create/update/delete event) in \"drafts\" write mode. Events have no draft stage but are reversible. Never overrides \"none\".",
+          "isRequired": false,
+          "format": "string"
         }
       ]
     }

package/skills/ofw-fpx/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: ofw-fpx
+description: >-
+  Access OurFamilyWizard (OFW) — messages, calendar, expenses, journal —
+  from a shell with the fpx CLI (@fetchproxy/cli) instead of running the
+  ofw-mcp server: capture the signed-in web app's Bearer token once via the
+  browser bridge, then curl the REST API directly. Use when you want OFW
+  data without the MCP, in a script, or on a machine where the MCP isn't
+  installed.
+---
+
+# OurFamilyWizard via fpx + curl (no MCP)
+
+OFW's app (`ofw.ourfamilywizard.com`) has no API key a script can request —
+the only credential is the Bearer token the web app itself mints on login
+and stores in `localStorage["auth"]` (with `localStorage["tokenExpiry"]`
+alongside). Once you have that token the API itself has **no bot wall** —
+`ofw-mcp`'s own `src/client.ts` calls it with plain Node `fetch` for every
+request. So this skill is **hybrid**: `fpx` captures the token from a
+signed-in browser tab ONCE, then plain `curl` does every read/write from
+then on. fetchproxy never touches the actual API calls.
+
+**This is a shared family-court record.** Every write here (`send`,
+`create_event`, `create_expense`, `create_journal_entry`,
+`upload_attachment`, the `delete_*`/bulk-delete calls) lands on the same
+record the MCP's `OFW_WRITE_MODE` gate exists to protect. There is no
+dry-run/confirm here — curl just does it. Treat every write like the MCP's
+`all` mode: real, permanent, and visible to your co-parent.
+
+## One-time setup
+
+```sh
+npm install -g @fetchproxy/cli                                       # provides `fpx`
+fpx profile add ofw --domain ourfamilywizard.com
+fpx profile declare ofw --local-storage auth --local-storage tokenExpiry
+fpx pair -p ofw                                                       # prints a pair code → approve in Transporter
+```
+
+Requirements: the **Transporter** browser extension installed, with an
+open, signed-in `ofw.ourfamilywizard.com` (or `www.ourfamilywizard.com`)
+tab, and its Chrome **Site access** allowing `ourfamilywizard.com`. Pairing
+persists across invocations.
+
+## Capture the token (once per shell / whenever it goes stale)
+
+```sh
+LS=$(fpx local-storage auth tokenExpiry -p ofw)
+TOKEN=$(jq -r '.auth' <<<"$LS")
+EXPIRES=$(jq -r '.tokenExpiry' <<<"$LS")
+```
+
+If `auth` comes back empty, sign into OFW in the browser tab first — the
+same precondition `ofw-mcp`'s own fetchproxy fallback documents in
+`src/auth.ts`.
+
+## Core call
+
+Every request needs the bearer token plus OFW's two protocol headers
+(sent on every call, not just login):
+
+```sh
+curl -s 'https://ofw.ourfamilywizard.com/pub/v2/profiles' \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'ofw-client: WebApplication' \
+  -H 'ofw-version: 1.0.0' \
+  | jq .
+```
+
+`ofw-version` is OFW's wire-protocol version (see `src/protocol.ts`),
+unrelated to any package version — send it as-is. Writes add
+`-H 'Content-Type: application/json' --data '...'` for JSON bodies, or
+`-F` multipart fields for uploads/deletes — both shown per-endpoint in
+`references/requests.md`.
+
+## The one rule: re-GET after every message POST to confirm it landed
+
+OFW's `POST /pub/v3/messages` response is minimal (`{"entityId": <id>}` or
+legacy `{"id": <id>}`) and — worse — its draft-*replace* path silently
+no-ops while still echoing success. Never trust the POST status alone for
+a send or draft save: immediately `GET /pub/v3/messages/{id}` with the
+returned id and check the body/subject actually match what you sent. See
+§2/§3 in `references/requests.md`.
+
+## Auth-error handling
+
+- **401** — the token expired or was invalidated. OFW has no refresh-token
+  flow; re-mint by reloading/re-signing-in on the `ourfamilywizard.com`
+  tab, then re-run the capture step above.
+- **429** — OFW's own client waits 2s and retries exactly once
+  (`src/client.ts`); do the same: `sleep 2` and resend the identical
+  request. A second 429 is a real rate-limit — back off further.
+- Any other non-2xx is a real upstream error — surface the response body.
+
+All 20 endpoint operations, request bodies, and `jq` projections are in
+`references/requests.md`, transcribed from `src/tools/*.ts`, `src/sync.ts`,
+and `src/tools/_shared.ts` — nothing here is guessed.
+
+## Notes
+
+- Base URL is `https://ofw.ourfamilywizard.com` for every endpoint (the
+  `www.` host serves the web app UI, not the API).
+- `ofw-mcp` maintains a local SQLite message cache for fast list/search;
+  this skill has no cache — every list call here goes straight to OFW, and
+  `GET /pub/v3/messages/{id}` on an **unread inbox message marks it read**
+  on OFW, exactly as it does for the MCP.
+- This project is developed and maintained by AI (Claude).