Document safe simulator biometric workflow

AGENTS.md

@@ -46,12 +46,34 @@ cargo test --workspace
 For Apple project changes, also run `xcodegen generate` from `apple/` and build
 the affected simulator targets.
 
+### Updating the Simulator app
+
+Treat the booted simulator and its app container as persistent test state. To
+update IronStorage, build for that simulator and install the new `.app` over
+the existing installation with `xcrun simctl install <device-udid> <app-path>`.
+Keep the same device UDID and bundle identifier.
+
+Do not uninstall IronStorage, erase or recreate the simulator, reset its
+keychain, install app-data packages, or delete its app container during an app
+update. Those are destructive reset operations, not update steps, and can
+remove preferences, repositories, credentials, and biometric enrollment state.
+
 ### Simulator biometric validation
 
-Before testing biometric unlock, enable Biometric Unlock once in the iPhone
-app so its protected passphrase is enrolled. In Simulator, use **Features >
-Face ID > Enrolled**, trigger an IronStorage unlock, then choose **Matching
-Face**. Verify the app changes from locked to unlocked. Use **Non-matching
-Face** to test rejection, and clear **Enrolled** to test unavailable or changed
-biometric enrollment.
-Always tap the entry's **Unlock** control before **Features > Face ID > Matching Face**; a simulated match does nothing without an active authentication request.
+For initial setup only, select **Features > Face ID > Enrolled** before enabling
+Biometric Unlock in the iPhone app. The user must then enable Biometric Unlock
+and enter the GPG passphrase once so the protected passphrase is enrolled.
+
+For normal validation, do not toggle **Enrolled** again. Tap the entry's
+**Unlock** control first so an authentication request is active, then select
+**Features > Face ID > Matching Face** and verify the app changes from locked to
+unlocked. A matching face presented before **Unlock** does nothing. Use
+**Non-matching Face** to test rejection without changing enrollment.
+
+Apple's `biometryCurrentSet` access control invalidates a protected Keychain
+item when Face ID is re-enrolled. Clearing or toggling **Enrolled** is therefore
+a destructive negative test, not part of the normal unlock sequence. Only do it
+when the issue explicitly requires changed-enrollment coverage and the user is
+available to enter the GPG passphrase again. When deliberately returning to a
+manual baseline, disable Biometric Unlock in IronStorage while the protected
+record is still valid, then clear **Enrolled**.