file-manager/AGENTS.md

Working in this repository

Plain Files is a file manager for Android: Kotlin and Jetpack Compose, one Gradle module (app), minSdk 26, targetSdk 36, and no INTERNET permission — "nothing leaves the device" is a shipping requirement of this app, not a slogan. It is sold once (no ads, no subscription, no billing code), and the prose in docs/ is treated as part of the product.

Two habits shape everything here. The app is driven on a real device for anything a user can see, and what that proved is written down. A test name is a sentence about behaviour, so the suite doubles as the specification.

Read these two first, and only then the source

file	why
docs/CODE_MAP.md	Generated index of the source tree: what each file holds, and every test name in the suite. Start here for "which file is this in?"
docs/ROADMAP.md	Which milestone is done, the key decisions, and the deliberate deferrals

Do not read CHANGELOG.md front to back — it is long, and it is meant to be grepped by feature name once you know what you are changing.

Commands

./tools/verify.sh              # the gate: map check, detekt, tests, lint
./tools/verify.sh --release    # ...and an R8 release build (what CI runs nightly)
GRADLE_FLAGS=--offline ./tools/verify.sh   # when the network is unavailable

./gradlew :app:assembleDebug   # then: adb install -r app/build/outputs/apk/debug/app-debug.apk
./tools/measure-startup.sh 5   # cold start, median of five, on the installed device
./gradlew :benchmark:connectedDebugAndroidTest   # the four macrobenchmark tests (needs a device)
                                                  # add -PbenchmarkBuild: it targets the benchmark build
./gradlew :app:detektBaseline  # re-freezes the findings that exist now — think before running it
python3 tools/make-code-map.py # regenerate docs/CODE_MAP.md after touching source

CI (.github/workflows/verify.yml) runs the same script on every push and pull request, plus a nightly --release build, because R8 is the one check nothing else performs and it has hidden a real defect here before. git config core.hooksPath .githooks runs it before every push as well.

The detekt gap it leaves — the findings in config/detekt/baseline.xml — is a ratchet: new findings fail the build, existing ones are parked until the file they live in is touched for another reason. tools/ holds the gate and the generators; config/detekt/ holds the rules and that baseline.

Where things live, and the one rule about direction

core/       pure Kotlin, no Android imports: paths, names, kinds, sorting, planning
data/       storage backends (all-files access, SAF), volumes, shares, SQLite search/trash/favourites
domain/     operations over a source: copy/move/delete/rename, archives, search, duplicates
service/    the foreground service that keeps a long operation alive
ui/         Compose: browser/, viewer/, usage/, trash/, duplicates/, theme/
text/       domain enum to string resource

The dependency direction is ui → domain → data → core, and core/ importing android.* or androidx.* is a test failure, not a matter of taste: it is what keeps the trickiest logic testable without Robolectric. docs/CODE_MAP.md has the per-file detail.

Non-negotiables

Each of these is enforced somewhere, so breaking one fails a test, lint, or a reviewer's first comment. app/src/test/java/…/ProjectInvariantsTest.kt holds the source-level ones.

• No new permission, and never INTERNET. The manifest's permission set is asserted exactly; adding one means deciding it, explaining it in the manifest comment and the README, and updating that list deliberately.
• Every user-visible string comes from strings.xml. The debug build enables a pseudo-locale (values-en-XA), so untranslated text is visible on screen as unaccented text.
• A name is one path segment. core/FileNames.isUsableName is the only implementation; never inspect / yourself. StoragePath.child("a/b") resolves into a subfolder, so an unguarded call renames or creates something the dialog never offered.
• Nothing is overwritten silently. Operations refuse rather than destroy; deletes go through the trash (24-hour window) and offer undo; a batch that cannot succeed is refused as a whole rather than performed until it hits the problem.
• Comments explain why, not what. The house style is a KDoc paragraph per file and type that says what it is for and what was rejected — decisions and limits, not restatements of the code.
• A test name is a sentence about behaviour (a batch rename is a single undo step), because the names are read as the spec. Logic gets behaviour tests, rules about the shape of the project get source-level tests, and what a user sees gets a Compose rendering test — those run on the JVM through Robolectric, so they are part of the same gate rather than needing a device.
• The docs are part of the change. CHANGELOG.md (Added/Changed/Fixed, in the house voice), the ROADMAP.md milestone table, the README if a claim changed, and docs/EDGE_CASE_TESTING.md for anything only a device could confirm.

Traps that have cost real time here

• MIUI blocks adb install twice over. Developer options needs Install via USB, and each install then waits for a confirmation dialog that times out on its own. A bare INSTALL_FAILED_USER_RESTRICTED means the dialog was answered late, not that the APK is bad.

• Never run assembleDebug and adb install in one parallel batch. They race, the install takes the previous APK, and the feature you just wrote appears to be missing.

• R8 has hidden real bugs. A class reached only by reflection, or named only from a resource, is stripped from the release build while debug works perfectly — this happened with coil-video, where video frames decoded in debug and quietly fell back to icons for real users. When debug and release disagree, assume the shrinker removed something.

• adb input text does not deliver a /. Send input keyevent 76 instead. The slash is worth testing at all because the field accepts it and the dialog is what refuses it.

• Long-press multi-select via input swipe x y x y 900 works, but not every time — it has also landed as a plain tap. A flaky gesture is a reason to look at the screen, not to distrust the code.

• The debug build is a separate package (…filemanager.debug), so it installs beside a release build and the two can be compared directly.

• detekt 1.23 cannot run on JDK 25. It parses the version string of the JVM it runs on and throws 25.0.4.1 as the entire error message, which is why :app:detekt drives the CLI on a 21 launcher. A bare version number as a build failure is this, not the code — and a JDK 21 has to be installed for the toolchain to find: Gradle does not download one here.

• A detekt baseline has to exist before it can be read. It starts as an empty document on purpose; --create-baseline cannot conjure the path it was told to consult.

Documentation map — read on demand

file	what it is for
README.md	The tour: features, layout, build, and the honest known limitations
CHANGELOG.md	The reasoning behind each change. Grep it; do not read it end to end
docs/ROADMAP.md	Milestones with their evidence, the key decisions, the deferrals
docs/EDGE_CASE_TESTING.md	What was verified, on which device or AVD, and what was not
docs/PERFORMANCE.md	The numbers that exist, and the ones that deliberately do not yet
docs/PLAY_RELEASE_CHECKLIST.md	Release only — work it in order
docs/COMPETITIVE_ANALYSIS.md, docs/MONETISATION.md, docs/STORE_LISTING.md	Product context, pricing, and length-checked listing copy
PRIVACY.md	The policy text the store listing points at

Definition of done

1. ./tools/verify.sh green — the map current, detekt, the unit tests and lint in one command.
2. python3 tools/make-code-map.py run, so that --check passes.
3. A CHANGELOG.md entry in the house voice: what changed, why, what was rejected, and what was verified rather than assumed.
4. Anything a user can see driven on a device or emulator, with the result written into docs/EDGE_CASE_TESTING.md — including what was deliberately left untested, and why.
5. A commit whose subject is a sentence about the change and whose body explains the reasoning. The diff already says what changed; the message is there for why it is this way.