General: Track only smoke locales for Play Store screenshots

.claude/CLAUDE.md

@@ -22,6 +22,7 @@ Permission Pilot is an Android app that helps users understand and manage app pe
 Detailed guidelines are in `.claude/rules/`:
 - `commit-guidelines.md` — Commit message format, PR description format, area prefixes
 - `build-commands.md` — Build, test, lint, screenshot, and release commands
+- `screenshots.md` — Play Store screenshot tracking, regeneration, and upload workflow
 - `architecture.md` — Module structure, patterns, base classes, data flow
 - `code-style.md` — Kotlin conventions, ViewModel/Compose patterns, logging
 - `testing.md` — Test locations, patterns, running tests

.claude/rules/build-commands.md

@@ -44,8 +44,10 @@
 
 ## Screenshots
 
+For the full regen + Play Store upload workflow (smoke-only tracking, on-demand full regen, manual upload), see `.claude/rules/screenshots.md`.
+
 ```bash
-# Generate all localized screenshots (39 locales x 7 screens, batched)
+# Generate all localized screenshots (39 locales x 6 screens, batched)
 ./fastlane/generate_screenshots.sh
 
 # Smoke test (6 locales for fast iteration)

.claude/rules/screenshots.md

@@ -0,0 +1,61 @@
+# Play Store Screenshots
+
+## What's tracked in git
+
+- **Smoke locales (6)** — `en-US`, `de-DE`, `ja-JP`, `ar`, `zh-CN`, `pt-BR`. PNGs under `fastlane/metadata/android/<locale>/images/phoneScreenshots/` are committed for these locales only.
+- **Other 33 locales** — gitignored. Generated on demand for upload, not committed.
+
+The `.gitignore` rule (lines following `app/src/screenshotTest*/reference/`) ignores all phone screenshots and `!`-includes only the 6 smoke locales. The smoke set matches `SMOKE_LOCALES` in `fastlane/generate_screenshots.sh`.
+
+The `--smoke` mode of `generate_screenshots.sh` is also useful for fast UI iteration on representative LTR/RTL/CJK locales without rendering all 39.
+
+## Why smoke-only
+
+- **Reviewable diffs** — a screenshot refresh that only touches 6 × 6 = 36 PNGs is reviewable; 234 PNGs is not.
+- **Repo size** — keeps binary churn out of git history.
+- **Fastlane behavior** — `supply` skips locales with no local screenshot files, so unpushed locales keep whatever Play Store currently has. This is current Fastlane uploader behavior, not a Play Store guarantee.
+
+## Full regeneration + upload (on demand)
+
+1. **Generate** all 39 locales:
+   ```bash
+   ./fastlane/generate_screenshots.sh
+   ```
+   Batched gradle screenshot rendering (~20 batches, ~10–15 min). The script exits non-zero if the final PNG count differs from the expected 234 (39 × 6).
+
+2. **Copy** rendered PNGs into fastlane metadata dirs:
+   ```bash
+   ./fastlane/copy_screenshots.sh --clean
+   ```
+   Output: `fastlane/metadata/android/<locale>/images/phoneScreenshots/*.png` for all 39 locales.
+
+3. **Verify** count before upload:
+   ```bash
+   find fastlane/metadata/android -path "*/images/phoneScreenshots/*.png" | wc -l   # expect 234
+   ```
+
+4. **Upload** to Play Store:
+   ```bash
+   cd fastlane && bundle exec fastlane screenshots_only
+   ```
+   The lane invokes `remove_unsupported_languages.sh` first, which deletes `ckb-IR` and `ku-TR` translation dirs (and harmlessly errors on the other 14 absent dirs in its list).
+
+5. **Restore** working tree post-upload:
+   ```bash
+   git clean -fdX fastlane/metadata/android      # removes only ignored files (the 33 non-smoke screenshot sets)
+   git checkout -- fastlane/metadata/android/ckb-IR fastlane/metadata/android/ku-TR
+   ```
+   `git clean -fdX` removes only gitignored files, so tracked screenshots, translations, and listing assets are untouched. The `git checkout` restores the two translation dirs the lane deleted.
+
+## After the first smoke-only upload
+
+Spot-check at least one **non-smoke** locale (e.g. `fr-FR`) in Play Console → Store listing → that locale, and confirm screenshots are still present. This validates the "Fastlane skips locales with no local files" assumption against current Play Store behavior. If non-smoke locales lose their screenshots, the workflow needs adjustment (e.g. always upload the full 39 set, or revert the gitignore split).
+
+## When smoke screenshots change
+
+Re-rendering the 6 smoke locales is part of the normal `--smoke` test loop:
+```bash
+./fastlane/generate_screenshots.sh --smoke
+./fastlane/copy_screenshots.sh --clean
+```
+Resulting changes to the 6 smoke locale PNGs go into a normal commit (typically `Apps:` / `Permissions:` / `General:` depending on what UI changed).

.gitignore

@@ -14,7 +14,19 @@
 /fastlane/report.xml
 /fastlane/Appfile
 /fastlane/README.md
-app/src/screenshotTestGplayDebug/reference/
+# Screenshot test reference images (ephemeral, regenerated on demand)
+app/src/screenshotTest*/reference/
+# Play Store phone screenshots: commit only the 6 smoke locales.
+# Full localization is generated + uploaded on demand via screenshots_only;
+# Fastlane skips locales with no local screenshot files, so absent locales
+# keep whatever Play Store currently has.
+fastlane/metadata/android/*/images/phoneScreenshots/*.png
+!fastlane/metadata/android/en-US/images/phoneScreenshots/*.png
+!fastlane/metadata/android/de-DE/images/phoneScreenshots/*.png
+!fastlane/metadata/android/ja-JP/images/phoneScreenshots/*.png
+!fastlane/metadata/android/ar/images/phoneScreenshots/*.png
+!fastlane/metadata/android/zh-CN/images/phoneScreenshots/*.png
+!fastlane/metadata/android/pt-BR/images/phoneScreenshots/*.png
 testapp/output/
 testapp/.gradle/
 testapp/build/

fastlane/generate_screenshots.sh

@@ -180,8 +180,9 @@ echo "=== Generation Complete ==="
 echo "Generated: $FINAL_COUNT images (expected: $EXPECTED)"
 
 if (( FINAL_COUNT != EXPECTED )); then
-    echo "WARNING: Count mismatch! Some screenshots may be missing."
+    echo "ERROR: Count mismatch! Some screenshots may be missing."
     echo "Check $REF_DIR for details."
+    exit 1
 fi
 
 echo ""