Merge pull request #972 from marionbarker/claude_suggestions_bb

Update the Browser Build section using claude

Author: marionbarker

docs/browser/automatic.md

@@ -15,9 +15,9 @@ The instructions provided for building with a browser include settings to automa
 !!! warning "Browser Build Disabled"
     We do not know why, but GitHub is disabling the Build Loop Action for LoopWorkspace even though the repository is not stale.
 
-    * We think it is associated with running too many builds at a busy time that requested too many runners (virtual computers)
-    * The redesigned build action for v3.8.2 should alleviate this
-    * We also plan to reach out to GitHub after people have transitioned to the v3.8.2 build schedule
+    * The automatic build actions should occur every Sunday
+        * The automatic build using the same code works for all OS-AID apps except for *Loop*
+        * See this [GitHub Discussion topic for details](https://github.com/orgs/community/discussions/181236)
 
 ### What Manual Action is Required?
 
@@ -303,4 +303,4 @@ What if I decide I don't want the automatic building feature?
     * [GitHub Directions to Disable and Enable a Workflow](https://docs.github.com/en/actions/using-workflows/disabling-and-enabling-a-workflow#disabling-a-workflow)
     * It is the Build action that kicks off the update and build steps, so simply disabling the one action is sufficient
 
-* If you are done with Loop, you can delete the whole repository; but you should be sure about this because you'll need to start over with [Configure to use Browser](bb-overview.md#configure-to-use-browser) to restore ability to build Loop with GitHub.
+* If you are done with Loop, you can delete the whole repository; but you should be sure about this because you'll need to start over with [Configure to use Browser](bb-overview.md#step-by-step-build-process) to restore ability to build Loop with GitHub.

docs/browser/bb-errors.md

@@ -156,9 +156,9 @@ Ignore the warnings - this does not affect the build.
 
 ### Manual Enable for Build Action May be Required
 
-The automatic build actions continue to happen on schedule, but starting May 2025, you may find your build action disabled by *GitHub*. (This might happen every 60 days, but it might happen sooner.) In that case, no build actually happens, no warning email is sent and a green checkmark (✅) appears beside a very short build action in which the actual build was skipped.
+The automatic build actions should occur every Sunday. They do for all OS-AID apps except for *Loop*.  ([We do not know why.](https://github.com/orgs/community/discussions/181236)) 
 
-If necessary, enable the build action at your repository as shown in the graphic below and then launch a manual build.
+If your build action is being disabled, you need to manually enable the action at your repository as shown in the graphic below and then launch a manual build.
 
 ![fix a disabled build state](img/build-disabled-fix.png )
 
@@ -832,7 +832,7 @@ Make sure you only delete `Match-Secrets`. Do NOT delete the repository of the a
 
 When building Loop, LoopCaregiver, LoopFollow or Trio:
 
-* If you just revoked a [Distrbution Certificate](#revoke-extra-distribution-certificate) - please do not delete your `Match-Secrets`
+* If you just revoked a [Distrbution Certificate](#revoke-distribution-certificate) - please do not delete your `Match-Secrets`
 * Make sure you have `ENABLE_NUKE_CERTS` set to true
 * The next time you try to build, the information in Match-Secrets is used to remove invalid profiles
     * A new Distribution Certificate and new profiles will be generated and your Match-Secrets will be updated

docs/browser/bb-overview.md

@@ -1,11 +1,27 @@
 ## Build with a Browser
 
-* <span translate="no">Loop 3</span>&nbsp;can be built with a web browser using <span translate="no">GitHub Actions</span>
-* The app is then installed by you on your phone using the *TestFlight* app
-* If you prefer to use *Xcode* on your *Mac*, head over to [Build with *Mac*](../build/overview.md){: target="_blank" }
-* As long as you use the same *Apple Developer* account, the app you build is the same regardless of build method
+<span translate="no">Loop 3</span>&nbsp;can be built with a web browser using <span translate="no">GitHub Actions</span> and installed on your phone using the *TestFlight* app. This method works on any device with a browser (PC, Mac, tablet, or iPad) - no Mac computer required.
+
+!!! success "Same App, Different Method"
+    * If you prefer to use *Xcode* on your *Mac*, see [Build with *Mac*](../build/overview.md){: target="_blank" }
+    * As long as you use the same *Apple Developer* account, the app you build is identical regardless of build method
     * When you install the app on your phone, settings and history are preserved; pump and CGM remain attached; selected Services are maintained
 
+## Is This Method Right for You?
+
+**Choose Browser Build if:**
+
+* ✓ You don't have a Mac or prefer not to use one
+* ✓ You want automatic monthly builds (after initial setup)
+* ✓ You're comfortable following step-by-step instructions with multiple accounts (Apple, GitHub)
+* ✓ You can dedicate 2-4 hours for first-time setup (spread over several days)
+
+**Choose Mac Build if:**
+
+* You already have an up-to-date Mac and are comfortable with Xcode
+* You prefer building locally without cloud services
+* See [Build with Mac](../build/overview.md){: target="_blank" } for Mac requirements
+
 ## Requirements
 
 ### Phone, CGM and Pump
@@ -24,23 +40,28 @@ To build the&nbsp;_<span translate="no">Loop</span>_&nbsp;app using a browser, y
 1. Free *GitHub* account: (instructions found at [New *GitHub* Account](secrets.md#new-github-account){: target="_blank" })
 1. Paid *Apple* Developer account: ($99/year; instructions found at [*Apple* Developer Account](../build/apple-developer.md){: target="_blank" })
 
-## Instructions to Build with a Browser
+## Getting Started: Two Paths
 
-### The Short Version
+Choose the path that matches your experience level:
 
-Complete instructions are found at this link for those comfortable with using *GitHub* and navigating the *Apple Developer* and *Apple App Connect* pages.
+### 🟢 Path 1: Detailed Step-by-Step (Recommended for First-Time Builders)
 
-* [Using GitHub Actions + FastLane to deploy to TestFlight](https://github.com/LoopKit/LoopWorkspace/blob/main/fastlane/testflight.md)
+Follow the detailed instructions below with screenshots, explanations, and help at every step.
 
-### How-to Video to Build with a Browser
+**Start here:** [Introduction and Summary](intro-summary.md){: target="_blank" }
 
-In addition to the pages linked below in [Configure to use Browser](#configure-to-use-browser), there is a narrated video of each step needed to build using a browser. (This video shows build steps for version 3.2.3 or older. Some items are simplified for version 3.4.1 and newer.)
+### 🔵 Path 2: Quick Reference (For Experienced Users)
 
-* [How to Build the *Loop* App With a Web Browser](https://www.youtube.com/watch?v=kiu5ho0MTW8)
+If you're comfortable with GitHub and Apple Developer portals, use the condensed version:
 
-### Configure to use Browser
+* **Documentation:** [Using GitHub Actions + FastLane to deploy to TestFlight](https://github.com/LoopKit/LoopWorkspace/blob/main/fastlane/testflight.md){: target="_blank" }
+* **Video Guide:** [How to Build Loop With a Web Browser](https://www.youtube.com/watch?v=kiu5ho0MTW8) (shows version 3.2.3; some steps simplified in 3.4.1+)
 
-The steps on these pages must be completed for you to build an app using a browser:
+---
+
+## Step-by-Step Build Process
+
+The following pages guide you through the complete browser build process:
 
 1. [Introduction and Summary](intro-summary.md){: target="_blank" }
 1. [Collect Secrets](secrets.md){: target="_blank" }
@@ -52,82 +73,83 @@ The steps on these pages must be completed for you to build an app using a brows
 1. [Prepare *TestFlight* Group](tf-users.md){: target="_blank" }
 1. [Build the *Loop* App](build-yml.md){: target="_blank" }
 
-The pages of instructions listed above give detailed steps on how to build the *Loop* app. If you are building a different app, you can follow the detailed instructions but will need to know the Fork, App Name, Identifiers and in some cases App Group for the App you intend to build. Once you build one app, subsequent apps are much easier to build.
+---
+
+## After Building: Next Steps
 
-* [Build Other Apps with Browser](other-apps.md){: target="_blank" }
+Once your build completes successfully:
 
-## Install on Phone
+1. **[Install on Phone](phone-install.md){: target="_blank" }** - Use TestFlight to install the app on your iPhone
+2. **[Update/Rebuild](bb-update.md){: target="_blank" }** - Learn how to update your app (much easier than initial build!)
+3. **[Build Other Apps](other-apps.md){: target="_blank" }** - Optional: Build LoopCaregiver, LoopFollow, or other apps using the same setup
 
-Instructions to install on a phone are found at:
+---
 
-* [Install on Phone](phone-install.md){: target="_blank" }
+## Need Help?
 
-## What if I get stuck?
+!!! question "Stuck? Don't Get Frustrated!"
+    First-time setup involves many steps across different websites. If something isn't working:
 
-!!! important "How to Ask for Help"
-    First time setup should take several hours, but if you are having trouble:
+    **→ [Get Help from Mentors](bb-errors.md#help-with-errors){: target="_blank" }**
 
-    * [Click here to find help](bb-errors.md#help-with-errors){: target="_blank" }.
+    Just provide your GitHub repository link and a brief description. Mentors can view your logs and guide you.
 
-If you want to solve it yourself, try to:
+**Common troubleshooting resources:**
 
-* Scroll back in the directions and see if you missed a paragraph or step
-    * Be sure you are copying the exact **names** needed for each step or clicking on the **link** associated with a particular step - many pages look similar
-* Compare your display with the <span>graphics in *LoopDocs*</span>
-    * Is something different or does yours have an error message?
-    * Does the [Error](bb-errors.md){: target="_blank" } message guide you to the problem and solution?
-    * Be aware that *GitHub* sometimes updates displayed names or locations for menu items - search for *GitHub* directions if your display looks different than our documentation
+* [Most Common Mistakes](bb-errors.md#most-common-mistakes){: target="_blank" }
+* [Complete Error Reference](bb-errors.md){: target="_blank" }
+* [How to Find Help](../intro/loopdocs-how-to.md#how-to-find-help)
 
-## Errors while Configuring and Building
+!!! warning "Please DON'T..."
+    * Search Google or ask ChatGPT about your error
+    * Spend hours frustrated
+    * Delete your repository or GitHub account
+    * Remove your app from App Store Connect
 
-If you get an error that you cannot figure out, reach out for help before you get frustrated or begin to delete things - let a mentor help you:
+    **→ Ask a mentor instead!** They can quickly diagnose issues from your repository link.
 
-* General instructions: [How to Find Help](../intro/loopdocs-how-to.md#how-to-find-help)
-* Browser Build instructions:
-    * [Help with Errors](bb-errors.md#help-with-errors){: target="_blank" }
-    * [Most Common Mistakes](bb-errors.md#most-common-mistakes){: target="_blank" }
-    * With Browser Build, post your *GitHub* LoopWorkspace link and a brief description of your problem
+---
 
-* [Errors with Browser](bb-errors.md){: target="_blank" }
+## Additional Topics
 
-## Update the App
+### Automatic Updates
 
-Instructions to make updates are found at:
+!!! success "Check Status of Build Action Monthly"
+    The automatic build actions should occur every Sunday. They do for all OS-AID apps except for *Loop*, and even for *Loop*, some people are getting automatic builds.  ([We do not know why.](https://github.com/orgs/community/discussions/181236)) 
 
-* [Update with Browser](bb-update.md){: target="_blank" }
+    * Keep your Apple Developer account active
+    * Install updates from TestFlight when ready
+    * **Note:** Starting May 2025, you may need to [manually trigger builds](automatic.md#manual-action-for-automatic-build){: target="_blank" } every 60 days
 
-There is also a helpful video for this process. Once again, this was prepared for an earlier version 3.2.3 or older. With version 3.4.1 and newer, the update and build is automatic if your *Apple* Developer account is active, agreements are signed and certificates are valid:
+    Learn more: [Automatic Update & Build](automatic.md){: target="_blank" }
 
-* [How to Update and Rebuild DIY Loop with a Web Browser](https://www.youtube.com/watch?v=0ipTsiqbbrQ)
+### Customization
 
-> With `Loop 3.6.0`, certificates are automatically created and renewed. You no longer need to renew certificates as a separate step.
+Want to customize your Loop app? Both methods are supported:
 
-## Other Topics
+* [Customize using Browser](custom-browser.md){: target="_blank" } - Configuration changes
+* [Custom Edits with Browser](edit-browser.md){: target="_blank" } - Code modifications
 
-### Building the Development Version of the App
+### Development Version
 
-For experienced and/or advanced users who want to build the development version of the app, there is additional information at the link below. If you have not built using the browser build method before, it is suggested you first build the released version. Once you have a successful build, then follow the steps for the development version. Building the app is independent of installing the app on your phone from *TestFlight*.
+For advanced users who want cutting-edge features before official release:
 
 * [Build Development Version](build-dev-browser.md){: target="_blank" }
 
-### Mac vs Browser
-
-These considerations were prepared when most people were using a Mac computer to build the *Loop* app.
-
-* *Mac* computer is not required to build or install the app
-    * Anything with a browser works to build the *Loop* app: PC, Tablet, Mac or iPad
-    * The *TestFlight* app is used to install the *Loop* app on your iPhone
-* Compatible version of *Xcode* is provided by *GitHub*
-    * The time required for the initial setup to build with a browser may take less time than one *macOS* and *Xcode* version update for those using [Build with *Mac*](../build/overview.md){: target="_blank" }
-* Automatic Updates are loaded into *TestFlight*
-    * With version 3.4 and newer, builds are automatically prepared at least once a month
-    * You choose when to install the new app from TestFlight onto your phone
-    * **WARNING:** starting May 2025, [Manual Action for Automatic Build](automatic.md#manual-action-for-automatic-build){: target="_blank" } may be required - be sure to check monthly to see if you need to start a build manually
-* Manual Updates are easy
-    * Starting an update takes a few minutes of your time; it can be done from your phone; the rest is automatic and is done in about an hour
-* After the *GitHub* Build starts, your app is ready to install on your *iPhone* in about an hour
-* The app is delivered to your phone via *TestFlight*
-    * The app is considered "Beta" by  *Apple* and expires after 90 days
-    * <span translate="no">Loop 3.4</span>&nbsp; and newer versions provide automatic build as the default
-* Customization methods are documented at [Customize with Browser](custom-browser.md){: target="_blank" }
+!!! tip "Build Stable First"
+    We recommend building the stable release version first. Once successful, you can switch to the development version.
+
+### Comparison: Browser vs Mac Build
+
+| Feature | Browser Build | Mac Build |
+|---------|--------------|-----------|
+| **Computer Required** | Any device with browser | Mac with recent macOS |
+| **Xcode Required** | No (GitHub provides) | Yes (must update regularly) |
+| **Initial Setup Time** | 2-4 hours over several days | 1-2 hours (if Mac is ready) |
+| **Monthly Updates** | Automatic | Manual via Xcode |
+| **Build Time** | ~1 hour (in cloud) | ~30 minutes (local) |
+| **App Expiration** | 90 days (TestFlight) | 1 year |
+| **Customization** | Supported | Supported |
+
+Both methods produce the identical Loop app. Choose based on your available hardware and preferences.
 

docs/browser/bb-update.md

@@ -34,14 +34,14 @@
 
     Most users will start at [How to Update or Rebuild](#how-to-update-or-rebuild):
 
-    * If currently using verion 3.4.0 or newer, builds are automatic but you still need to do some actions:
+    * If currently using verion 3.4.0 or newer, builds are supposed to be automatic, but are being disabled by GitHub ([for Loop, not other OS-AID](https://github.com/orgs/community/discussions/181236)), so you should check the status monthly
+    * In addition to that monthly check, expect to do these actions:
         * Your *Apple Developer* account must be active
         * All agreements must be signed for your *Apple Developer* account
         * Once a year, you need to update renew certificates, but this is automatic with `Loop 3.6.0` and newer versions
 
     If you are running `Loop-dev`, be sure to review these instructions but modify for the branch you are using: refer to [Build Loop dev with Browser](build-dev-browser.md)
 
-
 ???+ question "FAQs (click to open/close)"
     - **"What is an update?"** Anytime you want to change versions or if your *TestFlight* build is about to expire, follow the instructions on this page.
     - **"Do I delete my old Loop app first?"** Definitely **not**! If you keep your Loop app on your phone, your Loop settings (and existing pod) will continue to work the same after the update. Seamless.
@@ -461,15 +461,6 @@ Click inside the box under **Test Details**. Insert the text you want to see on
 
 In this example, the branch and commit number are included followed by an indication that this version includes the customizations preferred by this person. Your test details can be as simple as "Use this for Charlie".
 
-!!! tip "Commit Number"
-    If your build includes customizations, your commit number will not match what the developer expects to see if you need to ask for help.
-
-    Use this section [Customization and SHA-1](edit-browser.md#customization-and-sha-1) to determine the SHA-1 before customization.
-
-## No Longer Needed
-
-This section contains the old directions to manually renew certificates. It is no longer needed with the automatic certificate renewal method found in `Loop 3.6.0` and newer versions.
-
 ## Renew Certificate
 
 Manual certificate renewal is not longer required if you added the `Variable` `ENABLE_NUKE_CERTS`. See [Add Variable](prepare-fork.md#add-variable){: target="_blank" }.

docs/browser/build-dev-browser.md

@@ -95,6 +95,10 @@ The [Automatic Update & Build](automatic.md){: target="_blank" } features are ap
 
 Most people should keep `main` as default and make a considered decision when to launch a manual build of the `dev` branch. At that time, it will automatically update to the latest `dev` commit unless you have modified your settings with special `Variables`: [Modify Automatic Building](automatic.md#modify-automatic-building){: target="_blank" }.
 
+> The automatic build actions should occur every Sunday. They do for all OS-AID apps except for *Loop*.  ([We do not know why.](https://github.com/orgs/community/discussions/181236)) 
+
+> See [Manual Enable for Build Action](bb-errors.md#manual-enable-for-build-action-may-be-required){: target="_blank" }
+
 ## Change Default `Branch`
 
 > **We recommend most users leave their default branch as `main`.**