sync app filled in

.project/macos-app-api-gaps.md

@@ -0,0 +1,70 @@
+# macOS App API Gaps
+
+## Missing API Endpoints
+
+### 1. List Uploaded Attachments
+**Status:** IMPLEMENTED (see `apps/server/internal/httpserver/handlers.go` `handleAttachmentsList`)
+
+The app needs a way to show an index of all uploaded files. The current API only allows uploading (`POST /api/uploads`) and downloading (`GET /attachments/{hash}`).
+
+**Needed:**
+```
+GET /api/attachments
+Response: {
+  "attachments": [
+    {
+      "hash": "sha256",
+      "originalName": "filename.pdf",
+      "contentType": "application/pdf",
+      "sizeBytes": 12345,
+      "createdAt": "2024-01-01T00:00:00Z",
+      "url": "/attachments/{hash}"
+    }
+  ]
+}
+```
+
+### 2. Create Document from Content
+**Status:** AVAILABLE BY PATH
+
+The existing `POST /api/documents/{path}` works but requires knowing the path upfront. For the "new note from clipboard" feature, it would be cleaner to have:
+
+```
+POST /api/documents
+Body: {
+  "content": "# Note Title\n\nBody...",
+  "folder": "inbox" // optional, defaults to root
+}
+Response: {
+  "path": "inbox/note-title.md",
+  "title": "Note Title",
+  "hash": "sha256"
+}
+```
+
+The current workaround is to POST to `/api/documents/{path}` with the desired path.
+
+### 3. Inbox/Upload Folder Concept
+**Status:** NOT IMPLEMENTED
+
+The server has no concept of a default upload folder or inbox. All documents live in a flat-ish hierarchy under the content source directory. The macOS app will:
+- Allow the user to configure a default upload folder (e.g., "inbox/")
+- Fall back to root if not configured
+- Document this as a client-side convention
+
+## Stub Implementations
+
+The attachment list placeholder has been replaced with a repository-backed implementation. Native sync deltas now apply non-conflicting create/update/delete/rename changes and return `newSnapshotId`; create/update changes should include inline markdown `content` or reference a hash already present in the content store.
+
+## Authentication
+
+The app uses the existing Bearer token (API key) auth flow:
+1. User creates an API token via the web UI at `/account`
+2. Token is stored in macOS Keychain
+3. All requests include `Authorization: Bearer <token>`
+
+## Notes
+
+- File sync uses the existing `/api/sync/*` protocol. Clients should persist `newSnapshotId` after each delta response.
+- Upload uses `POST /api/uploads`. Markdown, plain-text, and HTML files are promoted into readable documents; other supported files remain attachments.
+- Uploaded file listing uses the repository-backed `GET /api/attachments` endpoint. Its `url` field points to the rendered page for promoted documents.