Changeset 0.37.17 (#229)

Co-authored-by: gobha <jasafpro@gmail.com>
Co-committed-by: gobha <jasafpro@gmail.com>

docs/ICD/projects.md

@@ -223,15 +223,80 @@ Insert uses ON CONFLICT DO NOTHING (idempotent).
 
 ---
 
-## Project Files
+## Project Files (v0.37.17 — workspace-backed)
+
+Project files are stored in the project's workspace (auto-created on
+first upload). The response uses `"files"` key, not `"data"`. Files
+are `WorkspaceFile` objects with tree structure (directories + files).
+
+### List Files
 
 ```
 GET  /projects/:id/files                         → { "files": [...], "count": N }
-POST /projects/:id/files                         ← multipart/form-data
+     ?path=/docs&recursive=true
 ```
 
-Project-level file uploads (distinct from workspace files and channel
-attachments). Note: `GET` uses `"files"` key, not `"data"`.
+| Param | Default | Notes |
+|-------|---------|-------|
+| `path` | `""` | Directory to list (empty = root) |
+| `recursive` | `true` | Include subdirectories |
+
+### Upload File
+
+```
+POST /projects/:id/files                         ← multipart/form-data
+     ?path=/docs
+```
+
+Multipart form field: `file`. Optional `path` query param to upload
+into a subdirectory. Auto-creates the project workspace on first upload.
+Returns `201` with `{ path, filename, content_type, size_bytes }`.
+
+**Errors:** `413` if file exceeds size limit or workspace quota.
+
+### Download File
+
+```
+GET  /projects/:id/files/download?path=/docs/readme.md
+```
+
+Streams raw file content with `Content-Disposition: attachment`.
+
+### Delete File
+
+```
+DELETE /projects/:id/files?path=/docs/readme.md
+       &recursive=false
+```
+
+`recursive=true` to delete directories with contents.
+
+### Create Directory
+
+```
+POST /projects/:id/files/mkdir                   ← { "path": "/docs/images" }
+```
+
+Path also accepted via `?path=` query param. Returns `201`.
+
+### Upload Archive
+
+```
+POST /projects/:id/archive/upload                ← multipart/form-data
+```
+
+Multipart field: `file`. Accepts `.zip`, `.tar.gz`, `.tgz`.
+Extracts contents into the workspace root.
+Returns `{ ok: true, files_extracted: N }`.
+
+### Download Archive
+
+```
+GET  /projects/:id/archive/download?format=zip
+```
+
+Bundles all project files into a zip (or `tar.gz`).
+Streams with `Content-Disposition: attachment`.
 
 ---