docs: document push token and firebase notification setup

android/CHANGELOG.md

@@ -679,3 +679,24 @@
   - add contact by email,
   - remove contact,
   - loading/refresh/error/info states.
+
+### Step 104 - Push token sync (Android + backend)
+- Added backend push token lifecycle API and storage:
+  - `POST /api/v1/notifications/push-token`
+  - `DELETE /api/v1/notifications/push-token`
+  - new table `push_device_tokens` (+ Alembic migration `0027_push_device_tokens`).
+- Added Android push token sync manager:
+  - registers FCM token on app start and after auth refresh/login,
+  - updates backend token on `FirebaseMessagingService.onNewToken`,
+  - unregisters token on logout.
+- Added backend FCM delivery in Celery notification tasks:
+  - sends to registered user device tokens,
+  - auto-removes invalid/unregistered tokens,
+  - safe fallback logs when Firebase is not configured.
+
+### Step 105 - Web Firebase push registration
+- Added web-side Firebase Messaging bootstrap (env-driven, no hardcoded secrets):
+  - fetch web push token and register in backend via `/notifications/push-token`,
+  - unregister token on logout,
+  - handle foreground push payload via existing notification service worker.
+- Added required env keys to `web/.env.example` and backend Firebase env keys to root `.env.example`.

docs/api-reference.md

@@ -1106,6 +1106,36 @@ Response: `200` + `ChatAttachmentRead[]`
 Auth required.  
 Response: `200` + `NotificationRead[]`
 
+### POST `/api/v1/notifications/push-token`
+
+Auth required.  
+Body: `PushTokenUpsertRequest`
+
+```json
+{
+  "platform": "android",
+  "token": "fcm_registration_token",
+  "device_id": "optional_device_id",
+  "app_version": "0.1.0"
+}
+```
+
+Response: `204`
+
+### DELETE `/api/v1/notifications/push-token`
+
+Auth required.  
+Body: `PushTokenDeleteRequest`
+
+```json
+{
+  "platform": "web",
+  "token": "fcm_registration_token"
+}
+```
+
+Response: `204`
+
 ## 11. Realtime WebSocket
 
 ### Endpoint

docs/backend-web-android-parity.md

@@ -11,7 +11,7 @@ Backend покрывает web-функционал почти полность
 - `realtime`: websocket + typing/read/delivered/ping-pong
 - `users`: search/profile/blocked/contacts
 - `search`: global search
-- `notifications`: list
+- `notifications`: list + push-token register/unregister
 
 Вывод: текущие проблемы в основном на стороне клиентской интеграции/UX, не backend-contract.
 
@@ -19,6 +19,8 @@ Backend покрывает web-функционал почти полность
 
 - `GET /api/v1/messages/{message_id}/thread` (data layer wired, UI thread screen/jump usage pending)
 - `GET /api/v1/notifications`
+- `POST /api/v1/notifications/push-token`
+- `DELETE /api/v1/notifications/push-token`
 - `POST /api/v1/auth/resend-verification`
 
 ## 3) Practical status
@@ -32,3 +34,4 @@ Backend покрывает web-функционал почти полность
 
 - `GET /api/v1/messages/{message_id}/thread` (UI usage)
 - notifications API + UI inbox flow
+- notifications delivery polish (channels/grouping/snooze/per-chat overrides parity with web prefs)