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.

.project/specs/simplesync-protocol.md

@@ -192,6 +192,7 @@ Response:
       "type": "update",
       "path": "guide.md",
       "hash": "client-hash",
+      "content": "# Guide\n\nClient edit\n",
       "size": 58,
       "modified": "2026-05-14T12:05:00Z"
     }
@@ -212,6 +213,7 @@ Response:
       "modified": "2026-05-14T12:03:00Z"
     }
   ],
+  "newSnapshotId": "snap:device:new-timestamp",
   "conflicts": [
     {
       "path": "guide.md",
@@ -225,6 +227,11 @@ Response:
 }
 ```
 
+For create/update deltas, native clients should send inline UTF-8 markdown in
+`content`. The server stores the bytes content-addressably, verifies any claimed
+`hash`, writes the markdown into the content tree, and returns a fresh
+`newSnapshotId` for the client's next sync request.
+
 ### Resolve
 
 `POST /api/sync/resolve`

.project/specs/sync-protocol-v1.md

@@ -112,6 +112,7 @@ Upload client changes and receive server changes + conflicts.
       "type": "update",
       "path": "hello.md",
       "hash": "d4e5f6...",
+      "content": "# Hello\n\nUpdated content\n",
       "size": 50,
       "modified": "2024-01-15T10:05:00Z"
     }
@@ -131,6 +132,7 @@ Upload client changes and receive server changes + conflicts.
       "modified": "2024-01-15T10:02:00Z"
     }
   ],
+  "newSnapshotId": "snap:macbook-pro-1:1234567999",
   "conflicts": [
     {
       "path": "hello.md",
@@ -144,6 +146,10 @@ Upload client changes and receive server changes + conflicts.
 }
 ```
 
+For client create/update changes, the server accepts inline UTF-8 markdown in
+`content` and recomputes the SHA-256 hash before writing the file. If `content`
+is omitted, the supplied `hash` must already exist in the server content store.
+
 ### POST /api/sync/resolve
 
 Resolve conflicts and finalize the sync.