docs: Clarify and expand a few spots in the iOS simulator notif doc

Also make use of a handy shorthand within `jq`.

Author: gnprice

docs/howto/push-notifications-ios-simulator.md

@@ -1,23 +1,37 @@
 # Testing Push Notifications on iOS Simulator
 
 For documentation on testing push notifications on Android or a real
-iOS Device, see https://github.com/zulip/zulip-mobile/blob/main/docs/howto/push-notifications.md
+iOS device, see https://github.com/zulip/zulip-mobile/blob/main/docs/howto/push-notifications.md
 
-This doc describes how to test client side changes on iOS Simulator.
+This doc describes how to test client-side changes on iOS Simulator.
 It will demonstrate how to use APNs payloads the server sends to
-Apple's Push Notification service to show notifications on iOS
+the Apple Push Notification service to show notifications on iOS
 Simulator.
 
-<div id="receive-notification" />
 
-## Receive a notification on the iOS Simulator
+### Contents
 
-Follow the following steps if you already have a valid APNs payload.
+* [Trigger a notification on the iOS Simulator](#trigger-notification)
+* [Canned APNs payloads](#canned-payloads)
+* [Produce sample APNs payloads](#produce-payload)
 
-Otherwise, you can either use one of the pre-canned payloads
-provided [here](#pre-canned-payloads), or you can retrieve the APNs
-payload generated by the latest dev server by following the steps
-[here](#retrieve-apns-payload).
+
+<div id="trigger-notification" />
+
+## Trigger a notification on the iOS Simulator
+
+The iOS Simulator permits delivering a notification payload
+artificially, as if APNs had delivered it to the device,
+but without actually involving APNs or any other server.
+
+As input for this operation, you'll need an APNs payload,
+i.e. a JSON blob representing what APNs might deliver to the app
+for a notification.
+
+To get an APNs payload, you can generate one from a Zulip dev server
+by following the [instructions in a section below](#produce-payload),
+or you can use one of the payloads included
+in this document [below](#canned-payloads).
 
 
 ### 1. Determine the device ID of the iOS Simulator
@@ -46,8 +60,8 @@ $ xcrun simctl list devices booted
 ### 2. Trigger a notification by pushing the payload to the iOS Simulator
 
 By running the following command with a valid APNs payload, you should
-receive a notification on the iOS Simulator for the zulip-flutter app,
-and tapping on it should route to the respective conversation.
+receive a notification on the iOS Simulator for the zulip-flutter app.
+Tapping on the notification should route to the respective conversation.
 
 ```shell-session
 $ xcrun simctl push [device-id] com.zulip.flutter [payload json path]
@@ -64,19 +78,21 @@ Notification sent to 'com.zulip.flutter'
 </details>
 
 
-<div id="pre-canned-payloads" />
+<div id="canned-payloads" />
 
-## Pre-canned APNs payloads
+## Canned APNs payloads
 
 The following pre-canned APNs payloads can be used in case you don't
 have one.
 
-The following pre-canned payloads were generated from
+These canned payloads were generated from
 Zulip Server 11.0-dev+git 8fd04b0f0, API Feature Level 377,
 in April 2025.
+The `user_id` is that of `[email protected]` in the Zulip dev environment.
 
-Also, they assume that EXTERNAL_HOST has its default value for the dev
-server. If you've [set EXTERNAL_HOST to use an IP address](https://github.com/zulip/zulip-mobile/blob/main/docs/howto/dev-server.md#4-set-external_host)
+These canned payloads assume that EXTERNAL_HOST has its default value
+for the dev server. If you've
+[set EXTERNAL_HOST to use an IP address](https://github.com/zulip/zulip-mobile/blob/main/docs/howto/dev-server.md#4-set-external_host)
 in order to enable your device to connect to the dev server, you'll
 need to adjust the `realm_url` fields. You can do this by a
 find-and-replace for `localhost`; for example,
@@ -190,16 +206,16 @@ canned payloads to files `tmp/*.json`.
 </details>
 
 
-<div id="retrieve-apns-payload" />
+<div id="produce-payload" />
 
-## Retrieve an APNs payload from dev server
+## Produce sample APNs payloads
 
 ### 1. Set up dev server
 
-Follow
-[this setup tutorial](https://zulip.readthedocs.io/en/latest/development/setup-recommended.html)
-to setup and run the dev server on same the Mac machine that hosts
-the iOS Simulator.
+To set up and run the dev server on the same Mac machine that hosts
+the iOS Simulator, follow Zulip's
+[standard instructions](https://zulip.readthedocs.io/en/latest/development/setup-recommended.html)
+for setting up a dev server.
 
 If you want to run the dev server on a different machine than the Mac
 host, you'll need to follow extra steps
@@ -210,34 +226,34 @@ connect to the dev server.
 
 ### 2. Set up the dev user to receive mobile notifications.
 
-We'll use the devlogin user `[email protected]` to test notifications,
-log in to that user by going to `/devlogin` on that server on Web.
+We'll use the devlogin user `[email protected]` to test notifications.
+Log in to that user by going to `/devlogin` on that server on Web.
 
-And then follow the steps [here](https://zulip.com/help/mobile-notifications)
+Then follow the steps [here](https://zulip.com/help/mobile-notifications)
 to enable Mobile Notifications for "Channels".
 
 
 ### 3. Log in as the dev user on zulip-flutter.
 
 <!-- TODO(#405) Guide to use the new devlogin page instead -->
 
-To login to this user in the Flutter app, you'll need the password
+To log in as this user in the Flutter app, you'll need the password
 that was generated by the development server. You can print the
 password by running this command inside your `vagrant ssh` shell:
 ```
 $ ./manage.py print_initial_password [email protected]
 ```
 
 Then run the app on the iOS Simulator, accept the permission to
-receive push notifications, and then login to the dev user
+receive push notifications, and then log in as the dev user
 (`[email protected]`).
 
 
 ### 4. Edit the server code to log the notification payload.
 
 We need to retrieve the APNs payload the server generates and sends
 to the bouncer. To do that we can add a log statement after the
-server completes generating the APNs in `zerver/lib/push_notifications.py`:
+server completes generating the payload in `zerver/lib/push_notifications.py`:
 
 ```diff
      apns_payload = get_message_payload_apns(
@@ -270,12 +286,15 @@ by searching for "APNS payload".
 
 ### 6. Transform and save the payload to a file
 
-The logged payload JSON will have different structure than what an
-iOS device actually receives, to fix that and save the result to a
-file, run the payload through the following command:
+The payload JSON recorded in the steps above is in the form the
+Zulip server sends to the bouncer.  The bouncer restructures this
+slightly to produce the actual payload which it sends to APNs,
+and which APNs delivers to the app on the device.
+To apply the same restructuring, run the payload through
+the following `jq` command:
 
 ```shell-session
 $ echo '{"alert":{"title": ...' \
-    | jq '{aps: {alert: .alert, sound: .sound, badge: .badge}, zulip: .custom.zulip}' \
+    | jq '{aps: {alert, sound, badge}, zulip: .custom.zulip}' \
     > payload.json
 ```