Initial GeoIntel V1 foundation

docs/13-implementation-traps/API_RESPONSE_RULES.md

@@ -0,0 +1,79 @@
+# API Response Rules
+
+All API responses must be stable and implementation-friendly.
+
+## Success Envelope
+
+For single resources:
+
+```json
+{
+  "data": {},
+  "meta": {}
+}
+```
+
+For lists:
+
+```json
+{
+  "data": [],
+  "meta": {
+    "count": 0,
+    "limit": 50,
+    "offset": 0
+  }
+}
+```
+
+## Error Envelope
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human readable message",
+    "details": {},
+    "trace_id": "optional"
+  }
+}
+```
+
+## Required Resource Fields
+
+Most persisted resources should include:
+
+- `id`
+- `created_at`
+- `updated_at`
+
+Geospatial resources should also include:
+
+- `crs`
+- `bounds`
+- `geometry_type` where applicable
+
+Analysis resources should include:
+
+- `status`
+- `parameters`
+- `outputs`
+- `metrics`
+- `error_message` when failed
+
+## Pagination
+
+Use `limit` and `offset` for V1. Cursor pagination can be added later if needed.
+
+## Sorting
+
+Default sort: newest first for projects, datasets, analyses and exports.
+
+## Contract Drift Rule
+
+If implementation changes any response shape, update:
+
+- `contracts/api/`
+- API docs
+- frontend API client types
+- tests