Changeset 0.28.0.3 (#175)

docs/ICD/README.md

@@ -101,22 +101,70 @@ Standard HTTP status codes: 400 (bad request), 401 (not authenticated),
 403 (not authorized), 404 (not found), 409 (conflict), 500 (server error),
 502 (upstream provider failure).
 
-### Pagination Envelope
+### Response Envelopes
 
-Endpoints that paginate return:
+Three patterns. Every endpoint uses exactly one.
+
+**List (returns an array)** → always wrap in `{"data": []}`:
+
+```json
+{
+  "data": [...]
+}
+```
+
+If paginated, pagination fields sit alongside `data`:
 
 ```json
 {
   "data": [...],
   "page": 1,
   "per_page": 50,
-  "total": 142,
-  "total_pages": 3
+  "total": 142
 }
 ```
 
 Query params: `?page=1&per_page=50`. Not all list endpoints paginate —
-some return `{ "data": [...] }` or a bare array in a named key.
+unpaginated lists still use `{"data": [...]}`.
+
+This is a hard rule: `data` is the only array wrapper key. No
+domain-specific keys (`teams`, `members`, `configs`, etc.) for arrays.
+Clients parse every list response identically.
+
+**Single object (GET by ID, profile, health)** → return the object directly:
+
+```json
+{
+  "id": "uuid",
+  "name": "...",
+  ...
+}
+```
+
+No wrapping. The response *is* the resource.
+
+**Composite (multiple named values, not an array)** → named keys:
+
+```json
+{
+  "active": 5,
+  "pending": 2
+}
+```
+
+Used for stats, counts, status endpoints — anything returning
+multiple named scalars or heterogeneous data. The key names are
+domain-specific and documented per endpoint.
+
+**Empty arrays** must serialize as `[]`, never `null`. Go handlers
+must guard nil slices before serialization:
+
+```go
+if result == nil {
+    result = []MyType{}
+}
+c.JSON(http.StatusOK, gin.H{"data": result})
+```
 
 ### ID Format