docs: document appearance, media and install policy

AGENTS.md

@@ -33,15 +33,15 @@ ADB lives at `/opt/android-sdk/platform-tools/adb`; the SDK is at `/opt/android-
 
 ## 3. Architecture
 
-- `lib/core/` — theme tokens (`AppColors`, `AppTheme`), `ThemeController`, reusable widgets.
+- `lib/core/` — theme tokens (`AppColors`, `AccentChoice`), `AppTheme`, `ThemeController` (theme/accent/battery), `AppClock`, reusable widgets.
 - `lib/data/models/` — `AppEntry`, `SlotType`, `SlotAssignment`, `SystemStatus`, `VolumeInfo`.
 - `lib/data/services/` — `NativeBridge` (platform channels), `PinService`, secure-store adapter.
 - `lib/data/repositories/` — `SettingsRepository`, the SSOT for theme, night window, slot assignments, visibility flags and pinned apps.
-- `lib/features/home/` — home screen, `LauncherController` (apps, slots, pinned apps, 16-button cap, HOME role), `SystemController` (volume/battery/Wi-Fi polling).
+- `lib/features/home/` — home screen, `LauncherController` (apps, slots, pinned apps, 16-button cap, HOME role), `SystemController` (volume/battery/Wi-Fi/media polling), equalizer.
 - `lib/features/apps/` — All Apps screen and app-picker sheet.
 - `lib/features/settings/` — General and Security pages.
 - `lib/features/lock/` — PIN pad, lock screen, cold-start `LockController`.
-- `android/app/src/main/kotlin/com/wasp/cardash_launcher/` — `MainActivity` (keep-screen-on, volume keys), `LauncherBridge` (package manager, role), `SystemBridge` (battery, Wi-Fi, volume).
+- `android/app/src/main/kotlin/com/wasp/cardash_launcher/` — `MainActivity` (keep-screen-on, volume keys), `LauncherBridge` (packages, icons, system flag, role), `SystemBridge` (battery, Wi-Fi, volume, media activity).
 - `tool/` — emulator/install/check scripts. `docs/` — implementation plan and design notes.
 
 Rules:
@@ -93,4 +93,6 @@ notifyListeners();
 - `tool/emulator.sh` starts a headless AVD with the **host GPU**; SwiftShader segfaulted on this machine's API 35 image. Use `CARDASH_GPU=swiftshader_indirect` only as a fallback. Use `adb exec-out screencap -p` for screenshots; there may be multiple `adb` binaries on PATH, so use the absolute one.
 - While CarDash is foreground, `MainActivity` consumes hardware volume keys and adjusts `STREAM_MUSIC` so they match the dashboard. Do not remove that override without providing another sync path; otherwise Android controls the ring stream when no media is playing.
 - `FLAG_KEEP_SCREEN_ON` in `MainActivity` is intentional. It applies while CarDash is the foreground window; do not move it to a permission-based wake lock.
+- The Music equalizer follows `AudioManager.isMusicActive`, not the playing package. Exact attribution needs notification access and is out of scope unless requested.
+- ADB installs: always try at most twice per connected device. If both attempts fail, stop silently rather than looping or switching install methods.
 - Reinstalling the app can clear its HOME role; re-run `tool/install.sh` or use Settings > Home app.

README.md

@@ -24,7 +24,9 @@ Also: [16-button home](docs/screenshots/home-16.png) ·
 [16 buttons at 1024×600](docs/screenshots/home-16-1024.png) ·
 [All apps](docs/screenshots/all-apps.png) ·
 [app picker](docs/screenshots/app-picker.png) ·
-[Settings · home buttons](docs/screenshots/settings-buttons.png) ·
+[Settings · accent & buttons](docs/screenshots/settings-buttons.png) ·
+[Blue accent](docs/screenshots/settings-blue-accent.png) ·
+[user-app icon on Home](docs/screenshots/home-user-icon.png) ·
 [PIN lock](docs/screenshots/pin-lock.png) ·
 [1024×600 layout](docs/screenshots/home-compact-1024.png)
 
@@ -33,20 +35,30 @@ Also: [16-button home](docs/screenshots/home-16.png) ·
 - **One home screen** — no pages, no top bar, no bottom dock; information and
   controls live on the home page.
 - **Large clock and date** with the device's 12/24-hour preference.
-- **Battery, charging and Wi-Fi** status.
+- **Battery, charging and Wi-Fi** status, with one switch to hide the battery
+  level and charging bolt.
 - **Media volume** — ring, slider, step and mute controls. While CarDash is in
   front, the hardware volume keys are routed to the same media stream, so the
   dashboard and the keys always agree. This is the phone's media stream, not a
   private volume.
 - **Configurable home buttons** — switches in Settings show or hide Navigation,
-  Music and Radio. Settings and All apps are always present. Dashboard icons
-  stay generic; real app icons appear in the picker and All Apps.
+  Music and Radio. Settings and All apps are always the last two buttons.
+  User-installed apps show their own icons on Home; system apps and unassigned
+  slots keep the generic category icon.
 - **Pin any app from All Apps** — long-press an app to add it to Home. The home
   page holds up to **16 buttons including Settings and All apps**, and the grid
   shrinks as it fills. Long-press an added app on Home to remove it completely;
   add it back with another long press in All Apps.
 - **All apps** — searchable grid of every launchable app, launched full-screen.
+- **Media-aware Music tile** — while media audio is active and the Music shortcut
+  is assigned, the tile shows the selected app's icon with a small animated
+  equalizer. Android exposes media-active state, not the playing package, to a
+  normal launcher; see the limitation below.
+- **Six accent colors** — Green, Blue, Amber, Rose, Violet or Teal, applied
+  across the whole interface.
 - **Screen stays awake** while CarDash is in the foreground.
+- **A short onboarding hint** — the long-press hint fades away two minutes after
+  app start, then stays gone.
 - **Light / Dark / Automatic** theme. Automatic uses a fixed local-time window
   (default 19:00–07:00), editable in Settings.
 - **Optional PIN** — four digits, stored as a salted PBKDF2 hash in
@@ -120,11 +132,14 @@ same thing. Android will not let an app force itself into the home role silently
 | Tap Navigation / Music / Radio | Open the assigned app full-screen |
 | Long-press Navigation / Music / Radio | Pick a different installed app |
 | Tap an unassigned shortcut | Open the app picker |
+| Settings → Accent | Pick Green, Blue, Amber, Rose, Violet or Teal |
+| Settings → Battery & charging | Show or hide battery level and charging bolt |
 | Settings → Home buttons switches | Show or hide Navigation, Music, Radio |
 | Long-press an app in All Apps | Add it to Home (up to 16 buttons) |
 | Long-press an added app on Home | Remove it from Home |
-| Settings | Theme, home buttons, default-home role, PIN |
+| Settings | Theme, accent, battery, home buttons, default-home role, PIN |
 | All apps | Search every launchable app; tap to open, hold to pin |
+| Music tile while media is active | Shows the selected app icon + equalizer |
 | Screen | Stays awake while CarDash is in front |
 | Volume ring / mute | Toggle media mute |
 | Slider or − / + | Set media volume |
@@ -138,9 +153,11 @@ the app resumes.
 
 **General**
 - Light / Dark / Auto theme.
+- Accent: Green, Blue, Amber, Rose, Violet or Teal.
+- Battery & charging: one switch hides both the level and charging bolt.
 - Auto night window (default dark from 19:00, light from 07:00).
 - Home buttons: show/hide Navigation, Music, Radio; live count out of 16.
-- Assign the app for each slot; Settings and All apps are fixed.
+- Assign the app for each slot; Settings and All apps are fixed and last.
 - Home role status and shortcut to the system prompt.
 
 **Security**
@@ -184,13 +201,14 @@ flutter test
 ./tool/check.sh
 ```
 
-The 17 tests cover PIN hashing/persistence, settings persistence, theme
-resolution, slot visibility, pinned apps, the 16-button cap and the dense
-shortcut grid. Native package enumeration, the HOME role, volume, app launching
+The 21 tests cover PIN hashing/persistence, settings persistence, theme and
+accent resolution, battery visibility, slot visibility, pinned apps, the
+16-button cap, the dense shortcut grid and the equalizer animation. Native
+package enumeration, system/user app flags, the HOME role, volume, app launching
 and PIN flows were verified on API 35 and API 29 emulators, including the release
-APK. The home-button, pinning and keep-awake flows were checked at 1280×800 and
-1024×600. Release 0.2.0 is also installed on a physical Android 17 HyperOS
-tablet.
+APK. The home-button, pinning, user-icon and keep-awake flows were checked at
+1280×800 and 1024×600. Release 0.3.0 is installed on the emulator and the
+physical Android 17 HyperOS tablet.
 
 ## Troubleshooting the emulator
 
@@ -213,10 +231,17 @@ Android 15 AVD is left running headlessly after development; use
   requires a newer Android release.
 - **Landscape only** (`sensorLandscape`). The home page is designed for
   1280×800 and remains usable at 1024×600.
-- **16-button cap** includes Settings and All apps. Added apps use the generic
-  dashboard icon and their name; real icons remain in the picker and All Apps.
+- **16-button cap** includes Settings and All apps. Non-system apps use their
+  own icon on Home; system apps, unassigned slots and fixed buttons keep the
+  generic line icons.
+- **Media equalizer** reacts to system media activity, not a per-app media
+  session. Android does not expose the playing package to a normal launcher
+  without notification access; adding that permission is deliberately out of
+  scope for now.
 - **Screen-on** applies while CarDash is the foreground window. Android can
   still sleep while another app is in front.
+- **Onboarding hint** is anchored to process start and disappears after two
+  minutes; it does not return until the next cold start.
 - **No embedded third-party app UI.** Navigation/Music/Radio are launched in
   their own full-screen windows.
 - **No global play/pause control.** Volume is on the home screen; playback
@@ -232,8 +257,8 @@ Android 15 AVD is left running headlessly after development; use
 ## Design
 
 The visual language is inspired by the [TrailCurrent Godwit](https://trailcurrent.com/godwit.html)
-head unit (MIT): warm neutral surfaces, a single deep-green instrument accent,
-large numerals and quiet line icons. It is not a copy of that UI.
+head unit (MIT): warm neutral surfaces, a selectable instrument accent, large
+numerals and quiet line icons. It is not a copy of that UI.
 
 - Typeface: **Manrope** (SIL Open Font License), bundled offline.
 - Icons: **Lucide** (ISC), bundled as SVGs.
@@ -242,6 +267,7 @@ large numerals and quiet line icons. It is not a copy of that UI.
 ## Roadmap
 
 - Optional compact now-playing control beside the volume card.
+- Exact per-app media detection via notification access, if desired.
 - Release signing configuration.
 - Real-device soak test on an Android 10 car tablet.
 

docs/IMPLEMENTATION_PLAN.md

@@ -16,11 +16,16 @@ compatibility:
 - Navigation/Music/Radio are **app slots** with show/hide switches. They can be
   assigned, changed and cleared. Settings and All apps are always present.
 - Pinned apps are added by long-pressing an app in All Apps and removed by
-  long-pressing the added button on Home. Dashboard icons stay generic.
+  long-pressing the added button on Home. Settings and All apps are always last.
+  User-installed apps show their own icon; system/unassigned slots keep generic.
 - The grid adapts from 2 to 6 columns and shrinks its tiles as the count grows.
 - Every external app opens full-screen through a normal Android `Intent`.
-- Settings: light/dark/automatic theme, fixed night window, home-button switches,
-  slot assignment, HOME-role setup, four-digit PIN.
+- Settings: light/dark/automatic theme, six accent colors, battery visibility,
+  fixed night window, home-button switches, slot assignment, HOME-role setup,
+  four-digit PIN.
+- The Music tile shows the selected app icon with an animated equalizer while
+  media audio is active.
+- The long-press hint fades away two minutes after app start.
 - PIN is requested **only on a cold start**, never on resume or screen-off.
 - The screen stays awake while CarDash is the foreground window.
 - Landscape-only; tablet-first 1280×800; Android 10 minimum.
@@ -36,7 +41,11 @@ compatibility:
 | App slots | Navigation, Music, Radio with visibility switches | Kept from the original brief; Settings and All apps are fixed. |
 | Pinned apps | All Apps long-press adds, Home long-press removes | Makes any installed app reachable from Home without editing a separate layout screen. |
 | Home cap | 16 buttons total, including Settings and All apps | Keeps the single page legible at tablet resolutions; enforced in `LauncherController`. |
-| Icons | Generic for all Home buttons; real icons in pickers/All Apps | Keeps the car interface consistent; names identify pinned apps. |
+| Icons | User-installed apps use their own icon; system/unassigned slots stay generic | Identification without losing the calm fixed-button language. |
+| Accent | Six curated choices, persisted in Settings | Changes the whole theme without a color picker or arbitrary contrast failures. |
+| Battery visibility | One switch hides level and charging bolt | One control for both indicators, as requested. |
+| Media feedback | Music tile shows the selected app icon + animated bars while media is active | Compact visual feedback without adding a media control surface. |
+| Hint lifetime | Two minutes from process start, then fade out | Avoids permanent onboarding chrome; survives widget rebuilds via `AppClock`. |
 | Screen | `FLAG_KEEP_SCREEN_ON` while foreground | The dashboard is the car display; no wake-lock permission needed. |
 | Theme | Light / Dark / Automatic with fixed 19:00–07:00 window | No location permission or network; time pickers make the window adjustable. |
 | PIN | Four digits, salted PBKDF2 hash, cold start only | Matches the explicit instruction; no re-lock while running. |
@@ -54,14 +63,14 @@ Flutter
   HomeScreen
     ClockBlock / StatusCluster / VolumeCard / ShortcutGrid
     LauncherController  -> apps, slots, pinned apps, 16-button cap, default-home state
-    SystemController    -> battery/Wi-Fi/volume polling
+    SystemController    -> battery/Wi-Fi/volume/media polling
   AllAppsScreen / AppPickerSheet
   SettingsScreen -> General / Security
   PinSetupScreen / LockScreen -> LockController -> PinService
 Android (Kotlin)
   MainActivity -> keep-screen-on, volume keys
-               -> LauncherBridge (apps, launch, role)
-               -> SystemBridge (battery, Wi-Fi, volume)
+               -> LauncherBridge (packages, icons, system flag, role)
+               -> SystemBridge (battery, Wi-Fi, volume, media activity)
 ```
 
 - `SettingsRepository` is the only persistence path for theme, night window,
@@ -87,11 +96,12 @@ Android (Kotlin)
 | M6 | Interaction testing, light/dark screenshots, layout polish, API 29 verification | Done |
 | M7 | Release build, final docs, screenshots, last commits | Done |
 | M8 | Home-button visibility switches, All Apps pinning, 16-button adaptive grid, keep-awake | Done |
+| M9 | Accent colors, battery toggle, fading hint, user icons, Media equalizer, install rule | Done |
 
 ## 5. Verification checklist
 
 - [x] `flutter analyze` clean.
-- [x] Unit/widget tests pass (17 tests: PIN, repository, theme, slot visibility, pinned apps, cap, dense grid).
+- [x] Unit/widget tests pass (21 tests: PIN, repository, theme/accent, battery visibility, slot visibility, pinned apps, cap, dense grid, equalizer).
 - [x] Debug APK builds with JDK 21.
 - [x] Installs on API 35 1280×800 tablet.
 - [x] HOME role granted; Home opens CarDash.
@@ -110,7 +120,14 @@ Android (Kotlin)
 - [x] Long-press on an added app removes it; it can be re-added from All Apps.
 - [x] 16 buttons fit at 1280×800 and 1024×600; the grid uses 2–6 columns.
 - [x] `FLAG_KEEP_SCREEN_ON` is present on the dashboard window.
-- [x] Release 0.2.0 installed on a physical Android 17 HyperOS tablet.
+- [x] Six accent choices change the Material theme immediately and persist.
+- [x] Battery switch hides both the battery level and charging bolt.
+- [x] Settings/All apps are the last two Home buttons.
+- [x] A user-installed app (F-Droid) shows its own icon; system apps stay generic.
+- [x] Music equalizer widget animates; native media-active polling is wired.
+- [x] Home hint is gone after two minutes from process start.
+- [x] All Apps search icon is visibly smaller.
+- [x] Release 0.3.0 installed on the emulator and physical Android 17 tablet.
 - [x] Screenshots in `docs/screenshots/`; README/AGENTS/plan updated.
 
 ## 6. Known risks and mitigations
@@ -127,11 +144,14 @@ Android (Kotlin)
 5. **Flutter 3.47 / AGP 9.1 / JDK 21**: works on this machine; Java 27 is not the
    validated toolchain. The emulator uses the host GPU; SwiftShader segfaulted
    on the API 35 image, so the helper script defaults to `-gpu host`.
-6. **16-button density**: generic icons plus small labels are the trade-off for
-   a single page. The Settings count and grid scaling make the limit explicit.
+6. **16-button density**: small labels and generic system-app icons are the
+   trade-off for a single page. The Settings count and grid scaling make the
+   limit explicit.
 7. **Screen-on battery use**: the flag applies only while the dashboard is
    foreground; it is not a background wake lock.
-8. **Uninstall/reinstall** may drop the HOME role; Settings and the installer
+8. **Media attribution**: the equalizer follows `AudioManager.isMusicActive`,
+   not a specific package. Exact attribution would require notification access.
+9. **Uninstall/reinstall** may drop the HOME role; Settings and the installer
    script can restore it.
 
 ## 7. Out of scope (for now)
@@ -155,3 +175,8 @@ Android (Kotlin)
   a 16-button cap with an adaptive 2–6 column grid, pinned-app removal, and a
   foreground keep-screen-on flag. Verified 17 tests, 16-button layouts at
   1280×800 and 1024×600, cap/removal/re-add, and 0.2.0 on the physical tablet.
+- 2026-10-29: Added six accent choices, battery/charging visibility, a two-minute
+  fading hint anchored to process start, Settings/All apps last, user-app icons,
+  a media-active equalizer, and a smaller All Apps search icon. Added the
+  two-attempt ADB install rule. Verified 21 tests, accent/battery toggles, a
+  user-app icon (F-Droid), hint expiry, and 0.3.0 on the emulator/tablet.