Add maintainer onboarding documentation

docs/SYNC_AND_BACKEND.md

@@ -0,0 +1,87 @@
+# Sync And Backend
+
+The app has a backend boundary but remains local-first by default.
+
+## Runtime Modes
+
+Fake backend:
+
+```bash
+flutter run --dart-define=USE_FAKE_BACKEND=true
+```
+
+REST backend:
+
+```bash
+flutter run \
+  --dart-define=USE_FAKE_BACKEND=false \
+  --dart-define=BACKEND_BASE_URL=https://your-api
+```
+
+`BackendGatewayFake` is the normal development path. It should stay
+offline-safe and must not seed relationship records into local state.
+
+## Backend Boundary
+
+Canonical files:
+
+- `lib/integrations/backend/backend_gateway.dart`
+- `lib/integrations/backend/backend_gateway_fake.dart`
+- `lib/integrations/backend/backend_gateway_rest.dart`
+- `lib/integrations/backend/backend_gateway_provider.dart`
+- `lib/integrations/backend/models/backend_models.dart`
+- `docs/api/openapi.yaml`
+
+The OpenAPI contract is the source for REST protocol intent. Generated Freezed
+files are committed and should be regenerated when backend models change.
+
+## Sync Queue
+
+Canonical files:
+
+- `lib/features/sync/data/sync_queue_repository.dart`
+- `lib/features/sync/application/sync_coordinator.dart`
+- `lib/features/sync/application/sync_auto_trigger_controller.dart`
+- `lib/features/sync/application/sync_background_runner.dart`
+- `lib/features/sync/presentation/sync_view.dart`
+
+Local writes enqueue `ChangeEnvelope` objects. Push accepts or rejects them.
+Rejected changes can be inspected and repaired from Sync view.
+
+## Auto Sync
+
+Background sync is disabled by default in the current local-first posture:
+
+```text
+ENABLE_BACKGROUND_SYNC=false
+```
+
+When enabled, triggers include startup, resume, periodic intervals, and
+offline-to-online transitions. REST mode is reachability-gated.
+
+## Known Mapping Gap
+
+Not every local entity maps to the backend protocol yet. Newer local-first
+entities such as facts, important dates, preference signals, shared inbox, and
+AI drafts may need explicit backend protocol decisions before real multi-device
+sync.
+
+Do not assume adding a local model automatically syncs it.
+
+## Backend Change Checklist
+
+1. Update `docs/api/openapi.yaml`.
+2. Update backend DTOs in `lib/integrations/backend/models/`.
+3. Regenerate generated models when needed.
+4. Update REST gateway mapping.
+5. Update fake gateway behavior.
+6. Update sync envelope validation.
+7. Update repository enqueue payloads.
+8. Add serialization and sync coordinator tests.
+
+Useful tests:
+
+```bash
+flutter test test/integrations/backend
+flutter test test/features/sync
+```