MindMachine/DEVELOPMENT.md

# MindMachine - Development Notes

## Build prerequisites

- JDK 17
- Android Studio (recommended)
- Android SDK installed
- `local.properties` configured (Android Studio usually writes this)


## Build outputs (where files end up)

- Debug APK
  - Task: `assembleDebug`
  - Output: `app/build/outputs/apk/debug/app-debug.apk`

- Release AAB (Android App Bundle)
  - Task: `bundleRelease`
  - Output: `app/build/outputs/bundle/release/app-release.aab`

- Debug AAB (rarely needed)
  - Task: `bundleDebug`
  - Output: `app/build/outputs/bundle/debug/app-debug.aab`


## Create an AAB (CLI)

Before uploading a new AAB to Google Play, make sure the app version is bumped:

- `app/build.gradle.kts` → `defaultConfig.versionCode` must be **unique and increasing** on Play Console.
- Update `versionName` as your human-readable release string.

From the repo root:

```bash
cd MindMachine
./gradlew bundleRelease
```

The bundle will be at:

```text
app/build/outputs/bundle/release/app-release.aab
```

(Optional) clean rebuild:

```bash
./gradlew clean bundleRelease
```


## Create an AAB (Android Studio)

1. **Build** → **Generate Signed Bundle / APK…**
2. Select **Android App Bundle**
3. Select **Release**
4. Select the **upload keystore**
5. Finish


## Signing setup (release bundles)

Release signing is configured in `app/build.gradle.kts` to load credentials from:

- `keystore/upload-keystore.properties`

That file should contain the standard fields:

```properties
storeFile=keystore/<your-upload-keystore>.jks
storePassword=<password>
keyAlias=<alias>
keyPassword=<password>
```

Notes:
- Treat `upload-keystore.properties` as **secret**. Do not share it publicly.
- On Google Play you typically use **Play App Signing**. You upload with your **upload key**, Google signs for distribution.


## Play Billing testing (subscribe/buy) checklist

Important: **Billing only works reliably when the app is installed from Google Play** (Internal/Closed testing). Sideloaded builds often fail Billing flows.

1. **Play Console**
   - Create your **in-app products** and/or **subscriptions** (base plans/offers).
   - Make sure each product is in an **Active** state.

2. **Add testers**
   - Add your tester Gmail(s) to the app’s **Internal testing** (or Closed testing) track.
   - Also add the same Gmail(s) to **Play Console → Setup → License testing**.

3. **Upload AAB + publish to the test track**
   - Upload the latest `app-release.aab` to the test track.
   - Publish/roll out the test release.

4. **Install from Play Store**
   - On the device, log into the Play Store using the tester account.
   - Install the app from the test track (Play will show it as available to that tester).

5. **Payment profile / payment method (if prompted)**
   - If Google prompts for payment info on the tester account, add a payment method in:
     - Play Store → **Payments & subscriptions** → **Payment methods**
     - (and/or set up the Google Payments profile for that account)
   - Test purchases will use Google’s **test purchase flow** (no real charge).

6. **Verify in the app**
   - Trigger the subscribe/buy flow and confirm the purchase dialog appears.
   - Confirm acknowledgements/entitlements are applied as expected.


## Billing logging (ADB)

Billing logs are written to Android's system log (Logcat), not displayed in the app UI.

To view billing logs:

```bash
# View only MindMachine billing logs
adb logcat -s MindMachineBilling:D

# Filter with silence for other tags
adb logcat -s MindMachineBilling:D *:S
```

Example log lines you'll see:
- `Billing setup finished: 0 OK`
- `Product details loaded: 2 items`
- `Query purchases returned X items`
- `Active entitlement: true/false`
- `Entitlement changed: false -> true`

Billing log tags:
- `MindMachineBilling` for debug/info messages
- Errors use `Log.e()` and appear as `E/MindMachineBilling` in logcat