AGENTS.md

1# AGENTS.md (app subproject)
2 
3Guidelines for AI models operating inside the `app/` subproject.
4 
5## 1. Environment & Gradle Setup
6 
7- **Working Directory:** Set working directory to `app/` when working on app code.
8- **Environment Wrapper:** Standalone `./gradlew` commands MUST be prefixed with `../scripts/env.py` (e.g., `../scripts/env.py ./gradlew assembleDebug`), or run `./build.py app` from root.
9 
10## 2. Architecture & Submodules
11 
12Multi-module Gradle project structure:
13- **`:apk`** (`apk/`): Legacy app APK. **Maintenance mode:** No new features should be added here.
14- **`:apk-ng`** (`apk-ng/`): Next-gen app variant. Primary target for new UI/app features.
15- **`:core`** (`core/`): Core domain logic, resources, Room DB, services. Primary target for core feature development.
16- **`:shared`** (`shared/`): Shared utilities and common data structures.
17- **`:stub`** (`stub/`): Lightweight stub app loader for hidden installs.
18- **`:stub-res`** (`stub-res/`): Stub-specific Android resources.
19- **`:test`** (`test/`): Application testing target.
20- **`:build-logic`** (`build-logic/`): Custom Gradle plugins and build logic.
21 
22## 3. Development Guidelines
23 
24- **Feature Development:** `:apk` is in maintenance mode. All new development MUST occur in `:core` and `:apk-ng`.
25- **Language & UI:** Written in Kotlin/Java. **Prefer Kotlin for all new code.** Uses Jetpack Compose for UI (prefer over View XML).
26- **String Resources:** Default strings in `core/src/main/res/values/strings.xml` and `stub-res/src/main/res/values/strings.xml`. Translations go in `values-[lang]/strings.xml`.
27- **Data Stack:** Room, KSP, Wire (Protocol Buffers), Moshi.
28 
29## 4. Workflows & Verification (from `app/`)
30 
31Prefix commands with `../scripts/env.py`:
32- **Build Main APK (Debug):** `../scripts/env.py ./gradlew :apk:assembleDebug`
33- **Build All Variants:** `../scripts/env.py ./gradlew assembleDebug`
34- **Build Stub APK:** `../scripts/env.py ./gradlew :stub:assembleDebug`
35- **Run Lint:** `../scripts/env.py ./gradlew lint`
36- **Run Unit Tests:** `../scripts/env.py ./gradlew test`
37- **Clean Artifacts:** `../scripts/env.py ./gradlew clean`
38