docs: wave 11 accepted; SPEC records auth refresh + why the 404 rule needs it

HANDOFF: expired-token incident, local data loss, verification incl. live
sync against the public URL, phone recovery path, HAZARD #12 (slow storage).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/SPEC.md

@@ -82,6 +82,16 @@ Pull:  GET /api/collections/{c}/records?filter=(updated>'{cursor}')&sort=updated
 Push:  records where syncState != SYNCED. PENDING_CREATE -> POST (with our id),
        PENDING_UPDATE -> PATCH, PENDING_DELETE -> PATCH {deleted:true}.
        On 404 for update/delete: drop local record. On 409/duplicate id: switch to PATCH.
+Auth:  EVERY sync starts with POST /api/collections/users/auth-refresh and stores the
+       new token, BEFORE any push or pull. 401/403 (from refresh or any later call)
+       -> clear the token only (keep URL + email), stop, report AuthExpired: the UI
+       says "sign in again" and routes to setup, pre-filled. Offline -> ordinary
+       failure, token kept. WHY: PocketBase does not reject an expired token, it
+       treats the request as anonymous, and the rules then 404 on records that
+       exist — so the 404 rule above is only safe on a freshly-proven token
+       (2026-09-17: five books hard-deleted locally this way). User tokens last
+       180 days server-side (migration 1789608448).
+       Sign-in clears all pull cursors, so every fresh session reconciles fully.
 Order: push THEN pull (so our writes come back canonical).
 Conflict: last-write-wins on `updated`. Document this in README; do not build
   anything cleverer.
@@ -147,6 +157,7 @@ scan     Camera + reticle; on hit -> bottom sheet w/ fetched book + shelf picker
 locations Bookcases -> shelves tree. CRUD + reorder. Book counts per shelf.
          Tap a shelf -> library filtered to it. "Move books" bulk action.
 settings Server, account, sign out, manual sync + last-sync time, book/cover counts.
+         Session expired -> "sign in again" + Sign in button instead of Sync now.
 
 ## Quality bar
 - No emulator on this box (no KVM). Verify via: `./gradlew assembleDebug`,