From b0ff434257702cd2e82181d9b8cf4d7c06e9cb6f Mon Sep 17 00:00:00 2001
From: Ole-Morten Duesund <olemd@glemt.net>
Date: Wed, 10 Jun 2026 14:46:21 +0200
Subject: [PATCH] CLAUDE.md: toolchain pins, load-bearing contracts, command
 quirks from build session

Captures what cost time this session: AGP 9 built-in Kotlin (KGP-bundled
version pinning), KSP's standalone versioning blocking Kotlin 2.4,
JAVA_HOME requirement, release signing flow, emulator verification
recipes, and the new code contracts (DoseActions single-path, backup
DTO/enum names as file-format contract, CCTV gate on kage bumps).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CLAUDE.md | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index d3b29e9..a2736a6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8,7 +8,7 @@ The name says the brief: nag me to take the dose *now*.
 - Package / applicationId: `no.naiv.meddetsamme`
 - Display name: `Med det samme` (in `strings.xml`, referenced from the manifest)
 - minSdk 26, targetSdk 35, JVM 17, Kotlin + Compose (Material3)
-- Stack: Room (+KSP), WorkManager, OkHttp, security-crypto, kotlinx-serialization.
+- Stack: Room (+KSP), WorkManager, OkHttp, kotlinx-serialization, kage (age crypto).
   Gradle Kotlin DSL + version catalog. No AWS SDK, no DI framework.
 
 <!-- Personal prefs (24h, concise, explain-why, Linux-assumed) may already be in my
@@ -43,6 +43,16 @@ The name says the brief: nag me to take the dose *now*.
 9. Refill is **derived** from inventory + consumption. Prescription renewal
    (`rxExpiryEpochDay`, `refillsRemaining`) is tracked **separately** from stock.
 
+## Toolchain (verified 2026-06, re-verify before bumping)
+- AGP 9 has built-in Kotlin: applying `org.jetbrains.kotlin.android` is an ERROR. The
+  compose/serialization plugin versions must match AGP's *bundled* KGP (2.3.10 for
+  AGP 9.2), not the newest Kotlin.
+- Kotlin stays 2.3.x until KSP supports 2.4 (KSP versions standalone since 2.3.0: plain "2.3.9").
+- compileSdk 37 (AndroidX hard-requires), targetSdk 35 — separate knobs, keep both.
+- Room 3 (`androidx.room3`) is alpha — stay on Room 2.x. `room-ktx` is merged into `room-runtime`.
+- androidx security-crypto is fully deprecated — SettingsStore is our own Keystore wrapper instead.
+- No appcompat: `?attr/colorControlNormal` doesn't exist; Compose tints icons via LocalContentColor.
+
 ## Load-bearing — change with care
 - The reminder subsystem is the reliability core. After any change, re-verify: alarms
   re-arm on boot/update, escalation cancels on Taken, the next occurrence is always
@@ -52,6 +62,13 @@ The name says the brief: nag me to take the dose *now*.
 - The S3 SigV4 signer: if a PUT fails it's almost always clock skew or a non-path-style
   endpoint, not the maths. Don't "fix" the signer first.
 - The schedule engine is pure — add tests here before touching the math.
+- DoseActions is the ONLY implementation of Taken/Snooze/Skip/Undo, shared by the
+  notification receiver and UI. Never add a second path — they'd disagree about inventory.
+- Backup DTO field names AND enum constant names (MedForm/DoseStatus) are part of the
+  backup-file contract; renaming breaks restore of old backups. Bump BackupFile.VERSION instead.
+- kage is trusted only because CctvScryptVectorTest passes — keep the vendored CCTV
+  vectors green when bumping kage.
+- Doctor PDF formatting is locale-pinned to nb; the default locale prints English month names.
 
 ## Out of scope — don't add without asking
 Caregiver/"Team" alerts, multi-profile, Health Connect, streaks/gamification,
@@ -59,8 +76,18 @@ injection-site tracking, symptom/mood diary. (Modelling "trackable" generically
 if cheap; build no diary UI.)
 
 ## Commands
+All gradlew calls need `JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64` — system java is a JDK 25 EA.
 - Build debug:  `./gradlew assembleDebug`
 - Unit tests:   `./gradlew test`
 - Lint:         `./gradlew lint`
+- Release:      `./gradlew assembleRelease` — signs via gitignored `keystore.properties`
+  (keystore in `~/.keystores/`; file absent → unsigned build, don't "fix" that)
+- adb/emulator are not on PATH: `~/android-sdk/platform-tools/adb`, `~/android-sdk/emulator/emulator`
+- Emulator verify: create a throwaway AVD from `system-images;android-35;google_apis;x86_64`,
+  delete after. NEVER use the personal `tilfluktsrom` AVD.
+- Inspect device DB: `adb shell run-as no.naiv.meddetsamme sqlite3 databases/med-det-samme.db "'SQL'"`
+- Verify alarms: `adb shell dumpsys alarm | grep meddetsamme` — `window=0` means exact
+- The phone (Pixel 7 Pro) has a RELEASE-signed install: `adb install` of debug builds is
+  rejected on signature; use release builds for the phone, emulator for debug.
 
 <!-- Once a README exists, add:  See @README.md for architecture detail. -->