add documentation, especially for build processes

BUILDING.md

@@ -337,6 +337,8 @@ Prerequisites: macOS with Xcode installed
    npx cap sync ios
    ```
 
+  - If that fails with "Could not find..." then look at the "gem_path" instructions above.
+
 3. Copy the assets:
 
    ```bash
@@ -344,20 +346,38 @@ Prerequisites: macOS with Xcode installed
    npx capacitor-assets generate --ios
    ```
 
-3. Open the project in Xcode:
+4. Bump the version to match Android
+
+   ```
+   cd ios/App
+   xcrun agvtool new-version 15
+   # Unfortunately this edits Info.plist directly.
+   #xcrun agvtool new-marketing-version 0.4.5
+   cat App.xcodeproj/project.pbxproj | sed "s/MARKETING_VERSION = .*;/MARKETING_VERSION = 0.4.5;/g" > temp
+   mv temp App.xcodeproj/project.pbxproj
+   cd -
+   ```
+
+5. Open the project in Xcode:
 
    ```bash
    npx cap open ios
    ```
 
-4. Use Xcode to build and run on simulator or device.
+6. Use Xcode to build and run on simulator or device.
 
-5. Release
+7. Release
 
   * Under "General" renamed a bunch of things to "Time Safari"
-  * Choose Product -> Destination -> Any iOS
-  * Choose Product -> Archive (which will trigger a build and take time, and "login" keychain password is machine user login, repeatedly)
-    * Click Distribute
+  * Choose Product -> Destination -> Build Any iOS
+  * Choose Product -> Archive
+    * This will trigger a build and take time, needing user's "login" keychain password which is just their login password, repeatedly.
+    * If it fails with `building for 'iOS', but linking in dylib (.../.pkgx/zlib.net/v1.3.0/lib/libz.1.3.dylib) built for 'macOS'` then run XCode outside that terminal (ie. not with `npx cap open ios`).
+    * Click Distribute -> App Store Connect
+  * In AppStoreConnect, add the build to the distribution: remove the current build with the "-" when you hover over it, then "Add Build" with the new build.
+    * It can take 15 minutes for the build to show up in the list of builds.
+    * You'll probably have to "Manage" something about encryption, disallowed in France.
+    * Then "Save" and "Add to Review" and "Resubmit to App Review".
 
 #### First-time iOS Configuration
 
@@ -393,13 +413,15 @@ Prerequisites: Android Studio with SDK installed
    npx capacitor-assets generate --android
    ```
 
-4. Open the project in Android Studio:
+4. Bump version to match iOS, in android/app/build.gradleq
+
+5. Open the project in Android Studio:
 
    ```bash
    npx cap open android
    ```
 
-5. Use Android Studio to build and run on emulator or device.
+6. Use Android Studio to build and run on emulator or device.
 
 ## Android Build from the console
 
@@ -429,6 +451,12 @@ Prerequisites: Android Studio with SDK installed
 
   ... and find your `aab` file at app/build/outputs/bundle/release
 
+At play.google.com/console:
+
+- Create new release, upload, hit Next.
+
+- Save & send changes for review.
+
 
 ## First-time Android Configuration for deep links
 

README.md

@@ -31,7 +31,9 @@ See [TESTING.md](test-playwright/TESTING.md) for detailed test instructions.
 
 ## Icons
 
-To add an icon, add to main.ts and reference with `fa` element and `icon` attribute with the hyphenated name.
+Application icons are in the `assets` directory, processed by the `capacitor-assets` command.
+
+To add a Font Awesome icon, add to main.ts and reference with `font-awesome` element and `icon` attribute with the hyphenated name.
 
 ## Other
 

assets/README.md

@@ -0,0 +1,2 @@
+
+Application icons are here. They are processed for android & ios by the `capacitor-assets` command, as indicated in the BUILDING.md file.