add local build commands

Justfile

@@ -0,0 +1,48 @@
+set shell := ["zsh", "-cu"]
+
+java_home := env_var_or_default("JAVA_HOME", "/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home")
+android_home := env_var_or_default("ANDROID_HOME", "/opt/homebrew/share/android-commandlinetools")
+device := env_var_or_default("BERTS_ATLAS_DEVICE", "663c91b1")
+simulator_device := env_var_or_default("BERTS_ATLAS_SIMULATOR_DEVICE", "iPhone 17 Pro")
+simulator_destination := "platform=iOS Simulator,name=" + simulator_device
+adb := android_home + "/platform-tools/adb"
+
+export JAVA_HOME := java_home
+export ANDROID_HOME := android_home
+export ANDROID_SDK_ROOT := android_home
+
+default: build
+
+# Build both runnable apps and validate bundled content.
+build: android ios catalog
+
+# Build the Android APK only.
+android:
+    ./gradlew :androidApp:assembleDebug
+
+# Build the shared iOS simulator framework and the Xcode host app.
+ios:
+    ./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64
+    xcodebuild -project iosApp/iosApp.xcodeproj -scheme iosApp -configuration Debug -destination '{{simulator_destination}}' -derivedDataPath build/ios-derived-data build
+
+# Build, install, and launch the app on the selected iOS simulator.
+run-ios: ios
+    xcrun simctl boot '{{simulator_device}}' 2>/dev/null || true
+    xcrun simctl bootstatus '{{simulator_device}}' -b
+    xcrun simctl install '{{simulator_device}}' "build/ios-derived-data/Build/Products/Debug-iphonesimulator/Bert's Atlas.app"
+    xcrun simctl launch '{{simulator_device}}' app.bertsatlas
+
+# Install and launch the debug app on the requested OnePlus device.
+install-android: android
+    '{{adb}}' -s '{{device}}' get-state
+    '{{adb}}' -s '{{device}}' install -r androidApp/build/outputs/apk/debug/androidApp-debug.apk
+    '{{adb}}' -s '{{device}}' shell am force-stop app.bertsatlas
+    '{{adb}}' -s '{{device}}' shell monkey -p app.bertsatlas -c android.intent.category.LAUNCHER 1
+
+# Run the structural content gate; editorial release signoff remains separate.
+catalog:
+    ./gradlew :catalogTool:validateCatalog
+
+# Build release artifacts without running automated tests.
+release:
+    ./gradlew :androidApp:assembleRelease :composeApp:linkReleaseFrameworkIosArm64 :catalogTool:validateCatalogForRelease

README.md

@@ -1,33 +1,55 @@
 # Bert's Atlas
 
-Bert's Atlas is an offline geography trivia game for Android and iOS. Product behavior and acceptance criteria live in `spec.md`; engineering principles live in `principles.md`.
+Bert's Atlas is an offline geography trivia game for Android and iOS. Product behavior lives in `spec.md`, and engineering guidance lives in `principles.md`.
 
-## Project layout
+## Architecture
 
-- `domain`: pure multiplatform quiz and progression rules
+- `domain`: pure Kotlin Multiplatform quiz, timing, scoring, mastery, streak, and selection rules
-- `composeApp`: shared Compose UI and platform-neutral application code
+- `composeApp`: shared Compose UI, bundled resources, Room persistence, and platform adapters
-- `androidApp`: thin Android launcher required by Android Gradle Plugin 9
+- `catalogTool`: non-test JVM catalog validator and editorial report generator
-- `catalogTool`: JVM catalog validator and human-review report generator
+- `androidApp`: thin Android application host
-- `iosApp`: thin Xcode host for the shared Compose framework
+- `iosApp`: thin Xcode application host
 
-The extra Android launcher is deliberate. AGP 9 does not support combining `com.android.application` and Kotlin Multiplatform in one module, so the three substantive modules remain separate from both thin platform hosts.
+The platform hosts use `app.bertsatlas`. V1 has no accounts, telemetry, advertising, runtime network dependency, or Android internet permission. Catalog content and progress stay on the device.
 
-## Toolchain
+## Build and run
 
-Builds use JDK 21 and the checked-in Gradle wrapper. Compose Multiplatform 1.12 requires Android compile SDK 37; target SDK remains 36 and minimum SDK is 26.
+Install JDK 21, the Android SDK, Xcode, and `just`. The checked-in Justfile defaults to the local JDK and SDK paths used by this project; override `JAVA_HOME` or `ANDROID_HOME` when yours differ.
 
 ```sh
-export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home
+just --list
-./gradlew :androidApp:assembleDebug
+just build
-./gradlew :composeApp:linkDebugFrameworkIosSimulatorArm64
-./gradlew :catalogTool:run
 ```
 
-Generate the Xcode project after changing `iosApp/project.yml`:
+Build the Android APK, or install and launch it on the configured device:
 
 ```sh
-cd iosApp
+just android
-xcodegen generate
+just install-android
 ```
 
-No automated test sources or test dependencies are part of V1. Verification is manual and release catalog validation is performed by `catalogTool`.
+`install-android` targets OnePlus device `663c91b1` by default. Override it with `BERTS_ATLAS_DEVICE=<serial>`.
+
+Build the shared simulator framework and Xcode host, or also install and launch the host:
+
+```sh
+just ios
+just run-ios
+```
+
+The default simulator is `iPhone 17 Pro`. Override it with `BERTS_ATLAS_SIMULATOR_DEVICE="<simulator name or UDID>"`. Regenerate `iosApp/iosApp.xcodeproj` with `xcodegen generate --spec iosApp/project.yml` after changing the XcodeGen specification.
+
+## Catalog gates
+
+```sh
+just catalog
+just release
+```
+
+`just catalog` verifies that the bundled catalog is structurally safe to load and writes `catalogTool/build/reports/catalog-review.txt`. Structural success does not mean the content is editorially approved.
+
+`just release` builds release artifacts without running automated tests and invokes the stricter editorial gate. It intentionally fails while any country, capital, fact, question, confusion explanation, or flag audit lacks documented human approval.
+
+## Release prerequisites
+
+Automated test suites are outside the V1 verification strategy; follow the manual acceptance matrix in `spec.md`. The currently available OnePlus covers Android 15/API 35, and the installed simulator covers iOS 26.1. Android API 26, an iOS 15-compatible runtime or device, and a connected physical iPhone are unavailable here and remain mandatory release prerequisites. Do not publish based only on the local build recipes.