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/MEMORY.md

@@ -17,6 +17,7 @@
 - [GuruRMM Server Layout](reference_gururmm_server.md) - SSH as `guru`, repo at /home/guru/gururmm, deploy to /var/www/gururmm/dashboard/
 - [GuruRMM API — run script on agent](reference_gururmm_api.md) — POST /api/agents/:id/command (command_type=powershell); poll /api/commands/:id for output. Beats ScreenConnect copy-paste.
 - [Pluto Build Server](reference_pluto_build_server.md) — Windows build VM, 172.16.3.36, SSH Administrator, MSVC + WiX. Use for any EXE/MSI build.
+- [Coord /messages API shape](reference_coord_messages_api_shape.md) — GET /api/coord/messages returns {total,skip,limit,messages[]} NOT a bare array; parse .messages[], strip control chars, read flag may be null.
 
 ## Users
 - [Howard Enos](user_howard.md) — Mike's brother, technician, full access. Machines: ACG-TECH03L, Howard-Home (authoritative in users.json).

.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.