diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b5a8a94b..b7970aa7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -134,6 +134,8 @@ rust_backend/ Production backend, native bindings, and unit tests
 android/      Android platform bridge and foreground worker
 ios/          iOS platform bridge and application project
 test/         Flutter unit and widget tests
+integration_test/ Device and emulator tests (including performance drivers)
+third_party/  Vendored and patched packages (audio_service, Discord bridge)
 assets/       Images, fonts, and bundled resources
 docs/         Local documentation and migration archives (gitignored)
 scripts/      Reproducible project build helpers
@@ -147,8 +149,10 @@ should consume that declaration without knowing which extension uses it.
 
 ## Generated Files
 
-- After changing ARB files, run `fvm flutter gen-l10n` and commit the resulting
-  localization sources.
+- After changing ARB files, run `fvm flutter gen-l10n` (or `fvm flutter pub get`)
+  to refresh the localization sources. They are generated and not committed:
+  `.gitignore` carries `/lib/l10n/app_localizations*.dart` ("Generated by
+  Flutter from lib/l10n/arb during pub get/build."). Commit only the ARB files.
 - Run `fvm dart run build_runner build --delete-conflicting-outputs` only when a
   model or generator input changes, then commit the relevant generated source.
 - Do not commit `build/`, `.dart_tool/`, AAR/XCFramework output, IDE state, or
@@ -164,6 +168,17 @@ Cross-language lyric usability cases live in
 tests read the same cases; add a case there when changing
 that policy.
 
+Test layers:
+
+| Layer | Location | Command |
+| --- | --- | --- |
+| Dart unit and widget | `test/` | `fvm flutter test` |
+| Device and emulator | `integration_test/` | `fvm flutter test integration_test/<file>` |
+| Performance | `integration_test/*_performance_test.dart` | `fvm flutter drive --driver=integration_test/performance_driver.dart --target=integration_test/<file> --keep-app-running` |
+| Kotlin JVM | `android/app/src/test/` | `gradle -p android :app:testDebugUnitTest` |
+| Rust | `rust_backend/` | `bash scripts/check_rust_backend.sh` |
+| Python script tests | `scripts/test_*.py` | `python3 -m unittest discover -s scripts -p 'test_<name>.py'` |
+
 Flutter and Dart:
 
 ```bash
@@ -172,17 +187,27 @@ fvm flutter analyze
 fvm flutter test
 ```
 
+Some Dart tests render audio and need `ffmpeg` and `ffprobe` on `PATH`. Set
+`SPOTIFLAC_TEST_FFMPEG` to an `ffmpeg` binary to override the lookup.
+
+Performance drive runs need a dedicated emulator, `--profile` on Android and
+`--debug` on iOS simulators. See the header of
+`integration_test/performance_driver.dart`.
+
 Rust formatting, Clippy, and unit tests:
 
 ```bash
 bash scripts/check_rust_backend.sh
 ```
 
-Android native code (Gradle builds the Rust artifacts automatically):
+Android native code (Gradle builds the Rust artifacts automatically). The
+repository has no Gradle wrapper; install the Gradle version CI uses
+(`.github/workflows/ci.yml`) and generate the Flutter configuration first:
 
 ```bash
-cd android
-./gradlew :app:compileDebugKotlin :app:testDebugUnitTest
+fvm flutter pub get
+fvm flutter build apk --config-only
+gradle -p android :app:compileDebugKotlin :app:testDebugUnitTest
 ```
 
 For user-facing changes, add or update tests where practical and include