Document and support StoreKit sandbox testing

APPSTORE.md

@@ -1,6 +1,6 @@
 # FuelBoard App Store Submission Plan
 
-Updated: 2026-08-16 · Target: safe App Store submission.
+Updated: 2026-09-26 · Target: safe App Store submission.
 Companion to SECURITY.md (code security) — this file is the *review-gate*
 checklist: what must happen, who owns it, and the timeline.
 
@@ -15,8 +15,104 @@ The two 2026-08-11 blockers are RESOLVED by P0 (live chain):
   Alerts** (ProximityMonitor escalates WhenInUse → Always on alert opt-in).
   Onboarding requests WhenInUse only.
 
+## StoreKit sandbox: verified working configuration and caveats
+
+### Verified configuration
+
+The FuelBoard consumable tip products are:
+
+- `com.apt.fuelboard.tip099`
+- `com.apt.fuelboard.tip299`
+- `com.apt.fuelboard.tip499`
+
+The app requests these exact **Product IDs** with StoreKit 2
+`Product.products(for:)`; the UI names are display labels and are not used for
+lookup. The app bundle ID, App Store Connect app, explicit App ID, development
+team, and Sandbox Apple Account must belong to the same developer account.
+
+Two test environments must remain distinct:
+
+- **Local StoreKit testing:** select `/Users/apt/workspace/fuelboard/FuelBoardTips.storekit`
+  in Xcode, under Product > Scheme > Edit Scheme > Run > Options. This bypasses
+  App Store Connect and confirms the app's StoreKit loading and purchase code.
+- **Apple sandbox testing:** select **None** for StoreKit Configuration, then
+  use Product > Run on a physical device with the development-signed build and
+  a Sandbox Apple Account signed in under Settings > Developer. This exercises
+  the real App Store Connect catalog.
+
+The local configuration returning all three products does not prove that the
+Apple sandbox catalog is ready. Conversely, a successful local run showing `$`
+does not mean the App Store Connect price is USD: `Product.displayPrice` is
+formatted for the active StoreKit/device storefront. Local StoreKit prices are
+placeholders and do not upload to App Store Connect.
+
+### Availability versus pricing
+
+App Store Connect has separate controls:
+
+- **Availability** controls the storefronts where the IAP is offered. The
+  verified FuelBoard configuration uses **United Kingdom only**.
+- **Price schedule** may show generated prices for **175 countries and
+  regions**. This is expected and does not make the IAP available in all 175
+  storefronts; it is Apple's price conversion schedule.
+
+The Sandbox Apple Account's App Store Country or Region must match an enabled
+IAP storefront. After changing the sandbox tester's storefront, sign out and
+back in under Settings > Developer so the storefront change activates.
+
+### Important propagation/cache caveat
+
+During sandbox diagnosis, `Product.products(for:)` completed successfully but
+returned zero products with the IAP availability set to UK. Temporarily
+changing one product's availability to all regions caused it to appear in the
+sandbox catalog; changing it back to UK left it working. This indicates an
+Apple-side catalog refresh or propagation/cache issue, not a change required in
+the StoreKit code. Apple documents that product metadata changes can take up to
+approximately one hour to appear in sandbox.
+
+If an otherwise valid product returns zero products:
+
+1. Confirm the Sandbox Apple Account belongs to the same developer team.
+2. Confirm its storefront is an enabled availability region.
+3. Sign out and back in to the sandbox account on the device.
+4. Delete/reinstall the development build and retry with StoreKit Configuration
+   set to **None**.
+5. If necessary, temporarily broaden one product's availability to all
+   regions, allow propagation, verify the product, then restore the intended
+   availability and allow propagation again.
+
+Record whether the diagnostic result is **request failed**, **completed with
+zero products**, or **a partial product set**. These are different failure
+classes. Do not add fallback prices or change product lookup to display names.
+
+Sandbox testing does not require prior App Review approval of the IAP. It does
+require active developer membership, an active Paid Applications Agreement,
+complete banking and tax information, valid product metadata and pricing, the
+correct app/team association, and a matching Sandbox Apple Account.
+
 ## Hard blockers (must happen before ANY submission)
 
+0. **[USER] Paid Applications Agreement in effect** — REQUIRED for paid IAP
+   configuration and sandbox testing. App Store Connect →
+   Business > Paid Applications Agreement → View and Agree. **This is the most
+   common cause of a 2.1(b) "unable to purchase item / error message" rejection
+   — without it every sandbox purchase fails.** (REJECTED once for this:
+   review date 2026-09-25, version 1.0 (21), iPad Air 11″ iPadOS 27.)
+   **Status 2026-09-25: agreement clicked Agree but shows "Pending user info" —
+   this is NOT in effect yet.** Complete the Banking (account + sort code/IBAN)
+   and Tax (W-8/W-9/UK tax ref, e.g. sole-trader UTR) sections under Business >
+   Payments & Tax until the agreement shows "Active" and every tab is green.
+   Only then do sandbox IAPs start working.
+0. **[USER] Tip IAPs configured and available to the sandbox** — the three
+   consumables may exist but must ALSO have complete metadata, a current price,
+   and an enabled storefront availability. Prior App Review approval or
+   `Cleared for Sale` status is **not required for sandbox product discovery**.
+   They must be backed by the **In-App Purchase capability on the App ID**
+   `com.apt.fuelboard` (developer portal → Identifiers → App ID capability).
+   3-tier tip code is already correct (retry lookup `7cb23e0`); do NOT churn
+   SettingsView.swift. Test product discovery and purchase with a Sandbox
+   Apple Account first: Settings → Support FuelBoard.
+
 1. **[USER] Apple Developer Program membership** — the app has never been
    signed (all builds are `CODE_SIGNING_ALLOWED=NO` + ad-hoc re-sign for
    SideStore). Requires a paid membership ($99/yr, up to 48 h to approve) and