feat: add clipboard file handling for Mattermost and implement batch debounce functionality

scripts/iphone-photo-inbox/README.md

@@ -9,14 +9,14 @@ clipboard behavior.
 `opencode`
 
 - Saves to `ai/inbox/photos/`
-- Copies a terminal-safe path to the clipboard
+- Copies terminal-safe paths to the clipboard
 - Best for pasting into OpenCode running in a terminal
 
 `mattermost`
 
 - Saves to `~/Pictures/iPhone Inbox`
-- Copies the image data to the clipboard
-- Best for pasting directly into Mattermost
+- Copies native macOS file URLs to the clipboard
+- Best effort for pasting one or more files directly into Mattermost
 
 `general`
 
@@ -26,6 +26,28 @@ clipboard behavior.
 
 All profiles show a macOS notification by default.
 
+## Batch debounce
+
+Uploads are grouped by profile. Every new photo extends the active profile batch
+by 10 seconds and immediately refreshes the clipboard with the full batch.
+
+Example for `opencode`:
+
+```text
+photo 1 arrives -> clipboard has photo 1 path
+photo 2 arrives within 10s -> clipboard has photo 1 + photo 2 paths
+photo 3 arrives within 10s -> clipboard has photo 1 + photo 2 + photo 3 paths
+10s pass with no new photo -> notification says the batch is ready
+```
+
+This keeps the Shortcut simple while still making the clipboard usable before
+the final notification appears.
+
+For `mattermost`, each upload rewrites the clipboard with the full batch using a
+small Swift helper and `NSPasteboard.writeObjects`. This is closer to Finder's
+file-copy behavior than the older AppleScript alias approach. If the native
+helper fails, the receiver falls back to AppleScript and logs the fallback.
+
 ## Start the receiver
 
 Recommended:
@@ -150,17 +172,25 @@ Clipboard override for all profiles:
 
 ```bash
 IPHONE_PHOTO_CLIPBOARD=image
+IPHONE_PHOTO_CLIPBOARD=files
 IPHONE_PHOTO_CLIPBOARD=terminal-path
 IPHONE_PHOTO_CLIPBOARD=path
 IPHONE_PHOTO_CLIPBOARD=file
 IPHONE_PHOTO_CLIPBOARD=none
 ```
 
+Debounce override:
+
+```bash
+IPHONE_PHOTO_DEBOUNCE_SECONDS=5
+```
+
 Other useful options:
 
 ```bash
 python3 scripts/iphone-photo-inbox/receiver.py --no-notify
 python3 scripts/iphone-photo-inbox/receiver.py --reveal
+IPHONE_PHOTO_DEBUG=1 python3 scripts/iphone-photo-inbox/receiver.py
 ```
 
 ## Troubleshooting
@@ -169,26 +199,43 @@ Startup should print each active profile:
 
 ```text
 profile opencode: dir=... clipboard=terminal-path notify=True reveal=False
-profile mattermost: dir=... clipboard=image notify=True reveal=False
+profile mattermost: dir=... clipboard=files notify=True reveal=False
 ```
 
-After upload, expect:
+After each upload, expect:
 
 ```text
-notification sent
-clipboard mode applied: terminal-path
-saved ... profile=opencode
+clipboard mode applied: terminal-path profile=opencode count=2
+saved ... profile=opencode batch_count=2
 ```
 
-For Mattermost, expect:
+After the debounce window closes, expect:
 
 ```text
-clipboard mode applied: image
+batch notification sent profile=opencode count=2
+batch finalized profile=opencode count=2 dir=...
 ```
 
+The native file clipboard helper lives at:
+
+```text
+scripts/iphone-photo-inbox/copy_files_to_clipboard.swift
+```
+
+For faster multi-file clipboard updates during debounce, compile it once:
+
+```bash
+swiftc scripts/iphone-photo-inbox/copy_files_to_clipboard.swift \
+  -o scripts/iphone-photo-inbox/copy_files_to_clipboard
+```
+
+The compiled binary is ignored by git. If it is not present, the receiver can
+run the Swift script directly, but that is slower on first use.
+
 If files arrive but clipboard/notifications do not behave as expected, check:
 
 - The Shortcut URL includes the intended `profile=`.
 - The receiver log shows the expected profile.
+- With `IPHONE_PHOTO_DEBUG=1`, the Mattermost profile should report `pasteboard files=2 items=2` after the second photo in a two-photo batch.
 - macOS Focus/Do Not Disturb is not hiding notifications.
 - Terminal/Codex has permission for AppleScript automation if macOS prompts.