Clarify Service Contracts And Security Invariants

src/web_firmware_update.h

@@ -4,6 +4,11 @@
 
 #define WEB_FIRMWARE_UPDATE_URI "/api/firmware"
 
+/* Synchronous HTTPD POST handler; enforces admin cookie/Origin/CSRF itself.
+ * Streams a raw application/octet-stream image into the inactive OTA slot and
+ * rechecks session authority before boot selection. ESP_OK can mean a sent error
+ * response, not a committed update. Selection survives a failed success response:
+ * never blindly retry; further uploads require reboot. A sent success schedules it. */
 esp_err_t web_firmware_update_handler(httpd_req_t *request);
 
 /* Atomically exclude uploads until reset. Call immediately before an ordinary