sync app filled in

openapi/openapi.yaml

@@ -25,8 +25,9 @@ paths:
                     type: string
   /api/uploads:
     post:
-      summary: Upload a single attachment
-      operationId: uploadAttachment
+      summary: Upload a single file
+      description: Markdown, plain-text, and HTML files become rendered documents. Other supported file types remain attachments.
+      operationId: uploadFile
       requestBody:
         required: true
         content:
@@ -37,9 +38,32 @@ paths:
                 file:
                   type: string
                   format: binary
+                folder:
+                  type: string
+                  description: Optional relative destination folder for readable documents.
+                duplicateAction:
+                  type: string
+                  enum: [overwrite, rename, reuse]
+                  description: Explicit resolution after a 409 duplicate response. Use rename to keep both readable documents, overwrite to replace a readable document, or reuse to return an existing upload URL.
       responses:
+        "200":
+          description: Existing upload URL reused
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UploadResponse"
         "201":
-          description: Attachment stored
+          description: File stored
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UploadResponse"
+        "409":
+          description: A readable document name or attachment hash already exists. Ask the user how to continue and retry with duplicateAction.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UploadConflict"
   /attachments/{hash}:
     get:
       summary: Download an attachment by content hash
@@ -53,4 +77,38 @@ paths:
       responses:
         "200":
           description: Attachment content
-
+components:
+  schemas:
+    UploadResponse:
+      type: object
+      required: [hash, contentType, kind, url, attachmentUrl]
+      properties:
+        hash:
+          type: string
+        contentType:
+          type: string
+        kind:
+          type: string
+          enum: [document, attachment]
+        url:
+          type: string
+          description: Canonical rendered-document or attachment URL.
+        attachmentUrl:
+          type: string
+          deprecated: true
+          description: Compatibility alias for url.
+    UploadConflict:
+      type: object
+      required: [error, conflictType, existingHash, existingUrl]
+      properties:
+        error:
+          type: string
+        conflictType:
+          type: string
+          enum: [document, attachment]
+        existingHash:
+          type: string
+        existingPath:
+          type: string
+        existingUrl:
+          type: string