From 6c312edf91f137f790b139a24f5360e7e86b1501 Mon Sep 17 00:00:00 2001
From: Tretzi <tretzi@openclaw.local>
Date: Wed, 15 Apr 2026 10:44:05 -0500
Subject: [PATCH] Docs: AAB build steps + Play Billing testing checklist

---
 ARCHITECTURE.md |   8 ++++
 DEVELOPMENT.md  | 105 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 113 insertions(+)
 create mode 100644 DEVELOPMENT.md

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 3ebcb36..d5bb089 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -218,6 +218,14 @@ Pattern implementations should be strategy-based, for example:
 ## 11. Safety Architecture
 
 Safety checks should exist in more than one place:
+
+---
+
+## Development notes
+
+Build/release steps (AAB) and Play Billing testing checklist live in:
+
+- `DEVELOPMENT.md`
 - onboarding acknowledgment,
 - pre-session checks,
 - runtime interruption handling,
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..04030c6
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,105 @@
+# 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)
+
+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.