Document AltStore-only iPhone deployment

AGENTS.md

@@ -130,19 +130,29 @@ iPhone (currently `xcrun simctl boot "iPhone 17 Pro"`) and open Simulator.
 CoreSimulator access may require running `xcodebuild` and `simctl` outside the
 workspace sandbox.
 
-## Post-issue release deployment
+## Post-issue release handling
 
-After an issue is verified, committed, pushed, commented on, and closed, deploy
+After an issue is verified, committed, pushed, commented on, and closed, handle
 the completed version according to the code it changes:
 
 - For CLI changes, build `gotcha-cli` in release mode and install the resulting
   `gotcha` executable in `~/.local/bin/` so the command is available on `PATH`.
-- For iOS app changes, install the completed app on the currently paired iPhone.
+- For iOS app changes, validate the completed app in the simulator. Never install
+  an Xcode-run or otherwise development-signed build on a physical iPhone; this
+  would replace the correctly signed AltStore PAL installation.
+- Physical iPhone installs and updates must use the complete AltStore PAL release
+  process: create and validate a distribution-signed Release archive, submit it
+  for notarization, publish the accepted Alternative Distribution Package and
+  source update, then install or update Gotcha through AltStore PAL.
+- Publishing an AltStore PAL release is not an automatic per-issue step. Perform
+  it only when the user explicitly requests and authorizes release publication.
 - The Gitea crate is shared by the CLI and iOS app, so changes to that crate also
-  require installing the completed app on the paired iPhone.
+  require simulator validation and inclusion in the next authorized AltStore PAL
+  release.
 
-A purely CLI change does not require an iPhone deployment. If an issue changes
+A purely CLI change does not require iOS validation. If an issue changes both
-both release surfaces, perform both deployments.
+release surfaces, install the CLI release and validate the iOS app in the
+simulator.
 
 ## Generated build data
 

README.md

@@ -136,6 +136,11 @@ Prebuilt iPhone releases will be distributed through the
 [rfc1437 Apps AltStore PAL source](https://rfc1437.de/apps/). The source page
 explains how to add it to AltStore PAL and install available apps.
 
+Development builds are validated in the iOS Simulator. Physical iPhones must
+install and update Gotcha only through the signed and notarized AltStore PAL
+release process; do not replace the marketplace installation with an Xcode-run
+or otherwise development-signed build.
+
 Server tokens are kept in the Apple Keychain; JSON preferences contain only
 server metadata, settings, and favorites. The app requires Xcode, XcodeGen, an
 installed iOS Simulator runtime, and Rust's

TESTING.md

@@ -121,8 +121,8 @@ xcrun simctl install booted "$gotcha_build_dir/Gotcha.app"
 xcrun simctl launch booted de.rfc1437.gotcha
 ```
 
-Before App Store submission, create a signed Release archive and inspect the
+Before AltStore PAL release publication, create a signed Release archive and
-packaged application rather than relying on Debug build settings:
+inspect the packaged application rather than relying on Debug build settings:
 
 ```sh
 cd ios
@@ -138,7 +138,13 @@ xcodebuild \
 Verify the archived app reports version `1.0` and a positive build number, is
 signed for distribution with the expected bundle identifier and entitlements,
 contains `PrivacyInfo.xcprivacy`, and declares the correct export-compliance
-answer before uploading it to App Store Connect.
+answer before uploading it to App Store Connect for notarization.
+
+Use the simulator for all development validation. Never install an Xcode-run or
+otherwise development-signed build on a physical iPhone because that would
+replace the correctly signed AltStore PAL installation. Physical-device release
+testing begins only after the accepted Alternative Distribution Package and
+source update are published, and installs or updates Gotcha through AltStore PAL.
 
 ## Add Server and native text editing
 
@@ -489,6 +495,7 @@ answer before uploading it to App Store Connect.
 - [ ] All build gates passed.
 - [ ] A signed Release archive passed the version, identity, entitlement,
       privacy-manifest, and export-compliance checks above.
-- [ ] Fresh-install and upgrade passes completed.
+- [ ] Fresh-install and upgrade passes completed through AltStore PAL on an
+      eligible physical iPhone.
 - [ ] Every supported iOS version and required device class completed.
 - [ ] Every scenario passed; any discovered failures were resolved and retested.