Harden bulk retries, parallelize guest uploads, and move guest map below gallery

docs/mcp.md

@@ -81,8 +81,22 @@ unhealthy. Long exports can exceed this threshold and should be investigated.
 Checks run every 30 seconds, with a 5-second timeout and three retries. No worker
 health port is published. Docker health status by itself does not automatically
 restart an unhealthy container; it supplies readiness information to Coolify.
-# Bulk gallery workflows
+## Bulk gallery workflows
 
 Use `manager_photos` with `input.limit`, `input.offset`, optional `input.visibility` and `input.processingStatus` to inspect a page. Capture explicit photo IDs; a bulk request never expands to later uploads. `manager_previewBulkPhotos` checks up to 100 IDs for an action (`public`, `hidden`, `private`, `rejected`, `delete`). Pass eligible IDs to `manager_bulkPhotos` with both `input.confirm=true` and the MCP write wrapper's `confirm=true`. Results are per photo, including skipped/failed items. Permissions are rechecked during execution. Deletion skips photos still uploading or processing, permanently removes originals and variants, and can partially succeed; inspect results before retrying.
 
-For organizer uploads, `manager_createGalleryPhotos` accepts up to 25 file descriptors and returns presigned PUT URLs in input order. PUT each original directly to storage with its matching Content-Type, then call `manager_completeGalleryPhotos` with successful IDs to validate size and queue transcoding. These actions require existing `settings.manage` permission. Photos start pending review, even when guest publication is automatic. Do not blindly retry creation: it creates a new batch. No file bytes pass through MCP or Next.js.
+For organizer uploads, `manager_createGalleryPhotos` accepts up to 25 file descriptors and returns presigned PUT URLs in input order. PUT each original directly to storage with its matching Content-Type, then call `manager_completeGalleryPhotos` with successful IDs to validate size and queue transcoding. These actions require existing `settings.manage` permission. Photos start pending review, even when guest publication is automatic. No file bytes pass through MCP or Next.js.
+
+Both `manager_bulkPhotos` and `manager_createGalleryPhotos` require `input.requestId` (a UUID). Generate it once per intentional operation and reuse it with identical input after connection failures. Durable event/user-scoped receipts prevent duplicate creation and prevent an old bulk retry from undoing a newer action. A changed payload with the same request ID is rejected. For a new action, use a new UUID. Successful and skipped per-photo results are replayed; interrupted/failed transactions can retry. Permissions are always checked before replay. The receipts migration must run before deploying this code.
+
+`manager_retryGalleryPhoto` resumes an organizer upload created by the same account. If `uploadUrl` is null, bytes already exist or processing has begun: do not PUT again. Call completion if its status is still `uploading`. Retrying a completed upload never returns a replacement PUT URL. The gallery UI keeps its batch ID and files for retries while the page remains open.
+
+## Full local verification
+
+Start the local web server and Docker development services (including Mailpit), then run:
+
+```sh
+POLISH_INTEGRATION=1 GALLERY_STORAGE_INTEGRATION=1 MCP_INTEGRATION=1 EXPORT_INTEGRATION=1 EXPORT_PERMISSIONS_INTEGRATION=1 WEBHOOK_INTEGRATION=1 NOTIFICATIONS_INTEGRATION=1 PUBLISHING_INTEGRATION=1 INVITE_JOURNEY_INTEGRATION=1 bun --env-file=.env test
+```
+
+Use only local database/storage and non-production Mailpit. The MCP tests also exercise initialization and tool calls using the official SDK client over loopback HTTP. They do not configure an external assistant app or mint production tokens.