POST /api/v1/gems/scan — single-call GPT-5.5 Pro scan (LNK-G55R + LNK-SIA).

Two modes (controlled by scan_intent + item_id):

new_item (default): creates a new Gemstone row with the uploaded images. Existing behavior — backwards compatible.

add_angle: attaches new images to an existing Gemstone (item_id), re-runs scan_v2 with the FULL image set (≤5 cap), updates the canonical Gemstone fields in place, and creates a Scan history row. First add_angle per Item is free (no quota consumed). Subsequent add_angles on the same Item count normally.

Pipeline (new_item):

1. Validate auth + images; a fingerprint cache hit on the caller's OWN earlier scan returns the stored result here, uncharged and exempt from the limit (LNK-SCANIDEM)
2. Scan limits + quota reservation (cache miss only); persist images
3. scan_v2(images, edge_hint) — Gemini pre-pass + GPT-5.5 Pro w/ web_search
4. ScanV2Result Pydantic validation (surfaces malformed AI output as 5xx)
5. Persist via ScanService.process_scan_v2_result (scan_version = 2)
6. Increment scan / device counter
7. Return ScanV2SuccessResponse{gemstone_id, images, scan}

Pipeline (add_angle):

1. Validate auth + scan limits (free if first add_angle for this Item)
2. Load existing Gemstone, validate ownership + combined image count ≤ 5
3. Validate + persist new images
4. Fetch existing images, combine with new, run scan_v2 with full set
5. ScanV2Result validation
6. Persist via ScanService.process_add_angle_result (update in place, add new GemstoneImage rows linked to the new Scan, increment add_angle_count)
7. Increment scan counter only if NOT free
8. Return ScanV2SuccessResponse{gemstone_id=item_id, images, scan}

Form fields (LNK-SIA additions): item_id (Optional[int]) — existing gemstone.id; required if scan_intent=add_angle scan_intent (Optional[str]) — 'new_item' (default) or 'add_angle'

Headers: Authorization (optional) — Bearer JWT for authenticated users X-Device-Id — device instance id; REQUIRED for anonymous scans (register via POST /api/v1/device first) X-Scan-Source — "mobile" (default) or "web" (requires auth)

Limits (LNK-LADDER): Authenticated FREE — base 1 scan/month + earned bonus scans (signup +1, first save-to-collection +1); 1 free add_angle per Item Authenticated PREMIUM — unlimited Anonymous — 1 free scan (ANONYMOUS_SCAN_LIMIT), tracked per device. Requests without X-Device-Id are rejected with 400 — there is no untracked anonymous mode.

Returns: 200 ScanV2SuccessResponse — successful scan, full v2 result included 200 ScanV2ErrorResponse — image rejected (not a gemstone) or AI failure 400 — invalid scan_intent / image cap exceeded / anonymous scan without X-Device-Id header 401 — web scan without authentication 402 — scan limit exceeded 403 — add_angle on Item owned by someone else 404 — add_angle item_id not found