feat: enhance UI, branding assets, onboarding flow, and screen layouts

README.md

@@ -145,15 +145,47 @@ segmented control: that the indicator actually travels rather than jumping,
 that taps report the right index, and that each tab reaches the semantics tree
 with its selected state (the dot alone is not readable).
 
+## Device permissions
+
+Location, notifications and camera are real requests through
+`permission_handler`, wrapped in `lib/core/permissions.dart` so nothing else
+imports the plugin. Two rules that layer enforces:
+
+- **The OS is the source of truth.** The flags on `SessionState` are a cache for
+  the UI. A permission can be revoked in system settings while the app is
+  closed, so any screen that shows their state calls `refresh()` to re-read.
+- **Platforms the plugin does not implement degrade to granted.** On web and
+  desktop it returns `true` rather than throwing — the browser prompts at the
+  point of use, so asking up front is neither possible nor useful.
+
+There is no API to revoke a permission, and re-requesting a granted one is a
+no-op, so switching one off in Settings opens the system settings page instead.
+Same when a permission is permanently denied and the OS will no longer show its
+dialog.
+
+Native declarations live in `AndroidManifest.xml` and `ios/Runner/Info.plist`;
+iOS rejects builds that request a permission without a usage string.
+
+> `permission_handler_android` compiles against Android API 37, and its AAR
+> metadata requires dependents to match, so `android/app/build.gradle.kts` pins
+> `compileSdk = 37` rather than following `flutter.compileSdkVersion`. Building
+> needs the `platforms;android-37` SDK package installed.
+
 ## Wiring it to a backend
 
 The seams are deliberate. `lib/state/seed.dart` is the only source of demo data;
 swap each controller's `build()` for an API call and the screens are unchanged.
-Two places currently stand in for device APIs:
+
+What still stands in for something real:
 
 - **Geofence** — `ClockScreen` has an "at the venue" switch in place of GPS.
-  Replace with `geolocator` and a 150 m radius check against the venue.
-- **File upload** — the compliance sheet fakes a filename. Replace with
-  `image_picker` / `file_picker` and a real upload.
-
-Notifications and SMS verification are also stubbed: the OTP is always `123456`.
+  Location permission is real, but nothing measures distance yet. Add
+  `geolocator` and a 150 m radius check against the venue.
+- **PDF upload** — compliance items take a photo or a gallery image through
+  `image_picker`. Picking a document needs `file_picker`, so that option is not
+  offered rather than offered and faked.
+- **Upload** — a picked file updates local state only; nothing is sent
+  anywhere yet.
+- **Notifications** — permission is requested, but nothing is scheduled or
+  received. Needs a messaging service and a local-notifications plugin.
+- **SMS verification** — the OTP is always `123456`.