qqq-android/AGENTS.md

Repository guidance

Read README.md, docs/SESSION-STATE.md, and docs/TODO.md for current scope; docs/history/ is historical only. Preserve unrelated changes and follow the user's current authorization for commits, publication, and deployment.

Build and tests

Use the included Gradle wrapper, Java21, and Android SDK35. local.properties, build outputs, SDK paths, and credentials are local-only.

./gradlew :qqq:android:core:testDebugUnitTest :qqq:android:mobileapp:testDebugUnitTest :scanner-host:testDebugUnitTest :scanner-host:lintDebug :scanner-host:assembleDebug

Run :qqqsampleandroidmobileapp:connectedDebugAndroidTest on an emulator for changes to native authentication/navigation/process rendering. scripts/ci/emulator-smoke.sh deliberately refuses physical devices and clears only the disposable emulator's scanner application data. Physical TC22 tests remain necessary for EMDK trigger capture, lifecycle and scanner-ownership release. Use the separate production-path QA variant and separately signed ordinary-UID probe documented in docs/ZEBRA-SCANNING.md; E2E synthetic broadcasts do not qualify production scanner security or hardware behavior. Never replace the operator's application or persistently modify DataWedge profiles for these tests.

All mobile processes require end-to-end coverage. For scanner flow changes, build :scanner-host:assembleE2e :scanner-host:assembleE2eAndroidTest and run node scripts/ci/scanner-e2e.mjs ../qbit-mobile-scanners against an emulator after building the companion demo/classpath as documented in docs/EMULATOR.md. This drives the real host and real server in the separate io.qrun.mobile.scanner.e2e application with a temporary database; never clear the operator's normal scanner application to run it. Server record actions must also be covered through both single-record and selected-bulk UI paths in the companion qbit's browser suite.

Design and safety

Reuse the existing core and mobileapp libraries and native QQQ metadata/process contracts. The scanner host adds enrollment and scanner widgets; do not introduce a competing screen engine. Preserve raw barcode strings, event identity across retries, server acknowledgments, and server-side device authorization.

All client/server operations must use the versioned semantic UI API or a registered, documented semantic extension. Discover version, required features, client channel and extension compatibility before credentials. Follow server process state and field metadata; never infer business actions from a process name or a generic field name. New required controls need native support and E2E coverage; unknown controls must stop submission explicitly. Keep the real-server OpenAPI request audit in CI.

Never log or place passwords, session cookies, or device tokens in process values, test fixtures, or documentation. Keep enrollment credentials and sessions isolated by server. Keep HTTP support limited to debug builds. Test resources under mobile-contract are sanitized real demo responses.

Repository automation

The primary forge is Gitea (git.kof22.com/QRun-IO); GitHub is a shadow/archive, so make no ordinary GitHub writes. Protected main on Gitea has .gitea/workflows/qrun-android-release.yaml calling the shared KofTwentyTwo/platform-ci android.yaml@qrun-release-v1; pull-request checks come from central Gitea policy, not from that release workflow. It is not a scanner-APK signing pipeline, and no automatic signing CI is configured. CircleCI is managed by kingsrook/qqq-orb using .qqq-ci.yml; preserve that lane and its main-only library publication. The legacy .github Scanner Android workflow builds a debug APK artifact and never publishes libraries or production releases; it and the scanner release workflow are not a selected release path. The owner has authorized production signing with the QRun-owned key qqq-mobile-release (details and fingerprint in docs/RELEASING.md) for signed-APK/MDM distribution. Do not create replacement or additional signing keys, put key material, passwords or vault item details in the repository, or use the legacy GitHub release workflows; create no tags or releases without current authorization. Do not replace managed CI with a stale local template.