From e2b77c489b5f71d91c800f48d721ff6b98f6f60c Mon Sep 17 00:00:00 2001
From: Mike Swanson <mike@azcomputerguru.com>
Date: Wed, 27 May 2026 11:10:24 -0700
Subject: [PATCH] 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                      |  1 +
 .../reference_coord_messages_api_shape.md     | 20 +++++++++++++++++++
 2 files changed, 21 insertions(+)
 create mode 100644 .claude/memory/reference_coord_messages_api_shape.md

diff --git a/.claude/memory/MEMORY.md b/.claude/memory/MEMORY.md
index 080298b..57fae8f 100644
--- a/.claude/memory/MEMORY.md
+++ b/.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).
diff --git a/.claude/memory/reference_coord_messages_api_shape.md b/.claude/memory/reference_coord_messages_api_shape.md
new file mode 100644
index 0000000..a56b91b
--- /dev/null
+++ b/.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.