docs(memory): coord /messages API shape (paginated object, not array)

Pin down the coord messages endpoint shape after repeated mark-read failures:
{total,skip,limit,messages[]}; parse .messages[], strip control chars, read may be null.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.claude/memory/reference_coord_messages_api_shape.md

@@ -0,0 +1,20 @@
+---
+name: reference-coord-messages-api-shape
+description: Coord /messages endpoint returns a paginated object {total,skip,limit,messages[]}, NOT a bare array; parse .messages[] and strip control chars before JSON parse
+metadata:
+  type: reference
+---
+
+The coordination API messages endpoint `GET http://172.16.3.30:8001/api/coord/messages?to_session=<SID>` returns a **paginated object**, not a bare array:
+
+```json
+{ "total": N, "skip": 0, "limit": M, "messages": [ {...}, ... ] }
+```
+
+**How to use it reliably:**
+- Parse `.messages[]` (jq) / `data["messages"]` (python) — iterating the top-level object yields keys (strings), which is why a bare `.[]?` / `for m in data` fails with "no match" or `'str' object has no attribute 'get'`.
+- Responses can contain **unescaped control chars** (U+0000-001F) that break `jq` and `json.loads` — strip them first (`tr -d '\000-\037'` or `re.sub(r"[\x00-\x1f]"," ", raw)`).
+- The per-message `read` flag may be `null` on unread messages (not `false`); the server-side `&unread_only=true` filter has missed `read=null` messages — safest to fetch without it and filter client-side.
+- Mark read: `PUT /api/coord/messages/<id>/read`.
+
+Caused repeated mark-read failures across a session (2026-05-27) before the shape was pinned down. See the Session Start Protocol in [[CLAUDE.md]] for the coord workflow.