docs: document pinned-app editing and first-run tip

AGENTS.md

@@ -63,7 +63,7 @@ notifyListeners();
 
 - Use `context.colors` / `AppTheme` tokens, not hard-coded colors in widgets.
 - All UI copy is sentence case (except the CarDash name). Keep copy short and functional.
-- New home buttons: extend `SlotType` for fixed slots or use `LauncherController` pinned-app APIs; enforce the 16-button cap in the controller.
+- New home buttons: extend `SlotType` for fixed slots or use `LauncherController` pinned-app APIs; enforce the cap and use `pinned_app_actions.dart` for rename/icon/remove.
 - New native methods: add them to `LauncherPlatform`, `NativeBridge`, the relevant Kotlin bridge, and the test fake if used.
 - Tests: fake `LauncherPlatform`/`SecureStore`; `SharedPreferences.setMockInitialValues({})`; widget tests wrap in `MaterialApp(theme: AppTheme.light())`. Test files live in `test/` and end with `_test.dart`.
 - Run `dart format lib test` before committing. Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`).
@@ -88,7 +88,8 @@ notifyListeners();
 - `QUERY_ALL_PACKAGES` is required to list every app. It is acceptable for a launcher but is not a Play-Store-distributable choice as-is; document it.
 - The Flutter template uses AGP 9.1 built-in Kotlin support. Do not add the Kotlin Gradle plugin unless the build explicitly requires it.
 - Immersive mode is reapplied on every `resumed` lifecycle event; Android may restore system bars after dialogs or role prompts.
-- The HOME role must be granted for the dashboard to replace the tablet home screen. On the emulator use `cmd role add-role-holder`; the in-app banner and Settings row use `RoleManager`.
+- The HOME role must be granted for the dashboard to replace the tablet home screen. On the emulator use `cmd role add-role-holder`; the Settings row uses `RoleManager`.
+- There is no Home-role banner. The one-time first-run tip uses `LauncherController.homeRoleHintShown`; do not show it again.
 - Screen-space is deliberately finite: test the 16-button grid at 1280×800 and 1024×600. Avoid unbounded `ListView`s inside `Column`s.
 - `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.

README.md

@@ -27,6 +27,8 @@ Also: [16-button home](docs/screenshots/home-16.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) ·
+[pinned-app menu](docs/screenshots/home-app-menu.png) ·
+[change-icon grid](docs/screenshots/home-app-icons.png) ·
 [PIN lock](docs/screenshots/pin-lock.png) ·
 [1024×600 layout](docs/screenshots/home-compact-1024.png)
 
@@ -47,8 +49,13 @@ Also: [16-button home](docs/screenshots/home-16.png) ·
   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.
+  shrinks as it fills.
+- **Edit a pinned app** — long-press it on Home for Rename, Change icon and
+  Remove. Rename changes only the Home label; Change icon offers the app icon
+  first, then up to 24 other installed app icons in the same rounded-square
+  shape; Remove takes effect without confirmation. Re-add the app from All Apps.
+- **One-time launcher tip** — the first run shows a short notification that the
+  default-launcher setting lives in Settings. It is not shown again.
 - **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
@@ -122,8 +129,9 @@ adb shell am start -a android.intent.action.MAIN -c android.intent.category.HOME
 ```
 
 On a real tablet, use **Settings → General → Home app → Set as default** and
-accept the system prompt. The in-app "Make CarDash your home app" card does the
-same thing. Android will not let an app force itself into the home role silently.
+accept the system prompt. Android will not let an app force itself into the home
+role silently. CarDash no longer keeps a home-role banner on the dashboard; the
+first run shows a one-time tip pointing to this setting.
 
 ## Using CarDash
 
@@ -136,7 +144,7 @@ same thing. Android will not let an app force itself into the home role silently
 | 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 |
+| Long-press an added app on Home | Rename, Change icon or Remove |
 | 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 |
@@ -201,14 +209,15 @@ flutter test
 ./tool/check.sh
 ```
 
-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, 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.
+The 23 tests cover PIN hashing/persistence, settings persistence, theme and
+accent resolution, battery visibility, first-run state, slot visibility, pinned
+apps, custom labels/icons, 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, menu,
+custom-icon, user-icon and keep-awake flows were checked at 1280×800 and
+1024×600. Release 0.4.0 is installed on the emulator and the physical Android 17
+HyperOS tablet.
 
 ## Troubleshooting the emulator
 
@@ -244,6 +253,10 @@ Android 15 AVD is left running headlessly after development; use
   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.
+- **Renaming changes the Home label only.** Android does not allow a launcher to
+  rename another app's installed label.
+- **Custom icons** follow installed apps; if the chosen source app is removed,
+  the tile falls back to its own icon or the generic one.
 - **No global play/pause control.** Volume is on the home screen; playback
   buttons live in the media app itself.
 - **No weather, Bluetooth, calls or climate** in this version.

docs/IMPLEMENTATION_PLAN.md

@@ -26,6 +26,9 @@ compatibility:
 - 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.
+- The Home-role banner is gone; a one-time first-run tip points to Settings.
+- Long-pressing a pinned app opens Rename, Change icon and Remove. Rename/icon
+  changes persist; Remove needs no confirmation.
 - 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.
@@ -46,6 +49,9 @@ compatibility:
 | 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`. |
+| Home role | Settings row only; one-time first-run tip | Removes permanent dashboard chrome while keeping discovery. |
+| Pinned editing | Long-press menu: Rename / Change icon / Remove | Keeps the home page clean; removal remains immediate. |
+| Custom icon source | The app icon first, then up to 24 installed app icons | Gives a large, recognizable grid without inventing generic art. |
 | 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. |
@@ -97,11 +103,12 @@ Android (Kotlin)
 | 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 |
+| M10 | Remove Home-role banner, one-time first-run tip, pinned Rename/icon/remove menu | Done |
 
 ## 5. Verification checklist
 
 - [x] `flutter analyze` clean.
-- [x] Unit/widget tests pass (21 tests: PIN, repository, theme/accent, battery visibility, slot visibility, pinned apps, cap, dense grid, equalizer).
+- [x] Unit/widget tests pass (23 tests: PIN, repository, theme/accent, battery, first-run state, slot visibility, pinned apps, custom labels/icons, 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.
@@ -127,7 +134,10 @@ Android (Kotlin)
 - [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] No Home-role banner; the first-run tip appears once, then never again.
+- [x] Long-press pinned app shows Rename, Change icon and Remove.
+- [x] Rename updates the Home label; Change icon persists an installed app icon; Remove is immediate.
+- [x] Release 0.4.0 installed on the emulator and physical Android 17 tablet.
 - [x] Screenshots in `docs/screenshots/`; README/AGENTS/plan updated.
 
 ## 6. Known risks and mitigations
@@ -151,8 +161,10 @@ Android (Kotlin)
    foreground; it is not a background wake lock.
 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.
+9. **Pinned customizations**: Rename affects only the Home label; a custom icon
+   falls back to the app/generic icon if its source app is uninstalled.
+10. **Uninstall/reinstall** may drop the HOME role; Settings and the installer
+    script can restore it.
 
 ## 7. Out of scope (for now)
 
@@ -180,3 +192,7 @@ Android (Kotlin)
   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.
+- 2026-10-29: Removed the Home-role banner; added a once-only first-run tip.
+  Replaced immediate removal with a pinned-app menu (Rename, Change icon,
+  Remove), custom Home labels and up to 25 installed-app icon choices. Verified
+  23 tests and the full menu flow at 1280×800; 0.4.0 installed on the tablet.