fixed transfer process

docs/API_REFERENCE.md

@@ -75,7 +75,6 @@ Endpoints that accept either browser session tokens or integration tokens:
 - `/api/birds`
 - `/api/birds/:birdId/weights`
 - `/api/birds/:birdId/vet-visits`
-- `/api/transfers/draft`
 
 Read-only integration tokens can call read endpoints, but cannot call write endpoints.
 
@@ -522,40 +521,6 @@ Responses:
 - `400` for missing or expired OAuth state
 - `404` for unknown provider
 
-### Transfers
-
-#### `POST /api/transfers/draft`
-
-Requires auth with write access. Prepares a bird transfer to another owner email and optionally triggers a magic-link invite for that email when no user exists yet.
-
-Request body:
-
-```json
-{
-  "birdId": "uuid",
-  "destinationOwnerEmail": "new-owner@example.com",
-  "notes": "Optional draft note"
-}
-```
-
-Response `201`:
-
-```json
-{
-  "ok": true,
-  "bird": {},
-  "destinationOwnerEmail": "new-owner@example.com",
-  "destinationOwnerExists": false,
-  "inviteSent": true,
-  "invitePreviewUrl": "http://localhost:5000/api/auth/magic-link/verify?token=...",
-  "inviteDelivery": "preview"
-}
-```
-
-Possible errors:
-
-- `404` if the bird is not in the active workspace
-
 ### Workspaces
 
 #### `GET /api/workspaces`
@@ -776,35 +741,52 @@ Possible errors:
 
 #### `POST /api/birds/:birdId/transfer`
 
-Requires a browser session, write access, and role `owner` or `assistant`. Moves a bird from the active flock to another flock the same user can access.
+Requires a browser session, write access, and role `owner` or `assistant`. Transfers a bird from the active flock to a flock owned by the provided receiving owner email. The sender does not need access to the receiving flock.
 
 Request body:
 
 ```json
 {
-  "targetWorkspaceId": 1002
+  "destinationOwnerEmail": "new-owner@example.com"
 }
 ```
 
 Notes:
 
-- the destination flock must be different from the current flock
-- the signed-in user must already be a member of the destination flock
-- the bird keeps its existing weight and vet history because the record itself is reassigned
+- if the receiving owner email does not currently own a receiving flock, FlockPal creates a pending transfer, sends a bird-transfer invite, and returns `202`; the bird stays in the sender's flock until the recipient signs in
+- pending transfers auto-complete when the recipient signs in; FlockPal creates or uses the recipient's personal flock as the receiving flock
+- immediate transfer requires the receiving owner email to match an accepted `owner` of exactly one other flock
+- when transferred, the bird keeps its existing weight and vet history because the record itself is reassigned
 
 Response `200`:
 
 ```json
 {
-  "bird": {}
+  "bird": {},
+  "destinationOwnerEmail": "new-owner@example.com",
+  "destinationWorkspace": {}
+}
+```
+
+Response `202` when the receiving email does not currently own a receiving flock:
+
+```json
+{
+  "ok": true,
+  "bird": {},
+  "destinationOwnerEmail": "new-owner@example.com",
+  "inviteSent": true,
+  "invitePreviewUrl": "http://localhost:5000/api/auth/magic-link/verify?token=...",
+  "inviteDelivery": "preview",
+  "message": "A bird transfer invite was sent. The bird will stay in this flock until the recipient signs in, then FlockPal will automatically move it to their receiving flock."
 }
 ```
 
 Possible errors:
 
-- `400` if the destination flock is the current flock or the payload is invalid
-- `403` if the user does not have access to the destination flock
+- `400` if the payload is invalid
 - `404` if the bird is not in the active flock
+- `409` if that owner email owns more than one receiving flock
 - `409` if the destination flock already has a bird using the same `tagId`
 
 #### `DELETE /api/birds/:birdId`