docs(cli): improve push publish and batch-publish reference docs

src/pages/docs/cli/push/batch-publish.mdx

@@ -18,7 +18,9 @@ ably push batch-publish [payload] [options]
 
 ### `payload` <a id="payload"/>
 
-A JSON array of push notification payloads. This can be provided as an inline JSON string, a file path, or `-` to read from stdin.
+A JSON array of push notification payloads. This can be provided as an inline JSON string, a file path (for example `./notifications.json` or `@notifications.json`), or `-` to read from stdin.
+
+Each item must have either a `recipient` or `channels` key. Items with `channels` are routed via channel-based push. Channel items may include an optional `message` field with realtime message data (plain text or JSON object) to publish alongside the push notification. In a JSON object, the recognized message fields `name`, `data`, and `extras` are mapped directly; any other fields are merged into `data`.
 
 ## Options
 
@@ -40,7 +42,7 @@ Enable verbose logging. Can be combined with `--json` or `--pretty-json`.
 
 ## Examples
 
-Publish with an inline JSON payload:
+Publish to multiple recipients with an inline JSON payload:
 
 <Code>
 ```shell
@@ -56,6 +58,8 @@ ably push batch-publish @notifications.json
 ```
 </Code>
 
+See notification file example [below](#notifications-json-file).
+
 Publish from stdin:
 
 <Code>
@@ -64,54 +68,76 @@ cat notifications.json | ably push batch-publish -
 ```
 </Code>
 
-Batch publish a push notification to a specific client:
+Publish to a specific client:
 
 <Code>
 ```shell
 ably push batch-publish '[{"recipient":{"clientId":"user-456"},"payload":{"notification":{"title":"Hello","body":"World"}}}]'
 ```
 </Code>
 
-Batch publish a data-only push notification to a device:
+Publish a data-only notification to a device:
 
 <Code>
 ```shell
 ably push batch-publish '[{"recipient":{"deviceId":"device-123"},"payload":{"data":{"orderId":"123","action":"update"}}}]'
 ```
 </Code>
 
-Batch publish to a channel with force option:
+Publish to a channel with a message string and a force option:
 
 <Code>
 ```shell
-ably push batch-publish '[{"channels":["my-channel"],"payload":{"notification":{"title":"Hello","body":"World"}}}]' --force
+ably push batch-publish '[{"channels":["my-channel"],"payload":{"notification":{"title":"Hello","body":"World"}},"message":"Hello from push"}]' --force
 ```
 </Code>
 
-Batch publish to multiple channels:
+Publish to multiple channels with a message JSON object:
 
 <Code>
 ```shell
-ably push batch-publish '[{"channels":["channel-1","channel-2"],"payload":{"notification":{"title":"Alert","body":"Message"}}}]' --force
+ably push batch-publish '[{"channels":["channel-1","channel-2"],"payload":{"notification":{"title":"Alert","body":"Message"}},"message":{"name":"alert","data":"New alert"}}]' --force
 ```
 </Code>
 
-Batch publish combining device and channel recipients:
+Publish to device and channel recipients in one batch:
 
 <Code>
 ```shell
-ably push batch-publish '[{"recipient":{"deviceId":"device-123"},"payload":{"notification":{"title":"Hello","body":"World"}}},{"channels":["my-channel"],"payload":{"notification":{"title":"Hello","body":"World"}}}]' --force
+ably push batch-publish '[{"recipient":{"deviceId":"device-123"},"payload":{"notification":{"title":"Hello","body":"World"}}},{"channels":["my-channel"],"payload":{"notification":{"title":"Hello","body":"World"}},"message":{"name":"greeting","data":"Hello from push"}}]' --force
 ```
 </Code>
 
-Batch publish from a file and output the result in JSON format:
+Publish from a file and output in JSON format:
 
 <Code>
 ```shell
 ably push batch-publish ./notifications.json --json --force
 ```
 </Code>
 
+### Notifications.json file <a id="notifications-json-file"/>
+
+<Code>
+```json
+[
+  {
+    "recipient": {"deviceId": "device-123"},
+    "payload": {
+      "notification": {"title": "Hello", "body": "World"}
+    }
+  },
+  {
+    "channels": ["my-channel"],
+    "payload": {
+      "notification": {"title": "Hello", "body": "World"}
+    },
+    "message": {"name": "greeting", "data": "Hello from push"}
+  }
+]
+```
+</Code>
+
 ## See also
 
 * [Push](/docs/cli/push) — Explore all `ably push` commands.

src/pages/docs/cli/push/publish.mdx

@@ -34,7 +34,7 @@ The target channel name. Publishes a push notification via the channel using `ex
 
 ### `--message` <a id="message"/>
 
-Realtime message data to include alongside the push notification. Accepts either plain text or raw JSON, and the value is used as the realtime message `data` payload rather than a full message object. Only applies when publishing via `--channel`.
+Realtime message to include alongside the push notification. Accepts plain text, or a JSON object. In a JSON object, the recognized message fields `name`, `data`, and `extras` are mapped directly; any other fields are merged into `data`. Only applies when publishing via `--channel`.
 
 ### `--title` <a id="title"/>
 
@@ -102,47 +102,47 @@ Enable verbose logging. Can be combined with `--json` or `--pretty-json`.
 
 ## Examples
 
-Publish a push notification to a device:
+Publish to a device:
 
 <Code>
 ```shell
 ably push publish --device-id "device123" --title "Hello" --body "World"
 ```
 </Code>
 
-Publish a push notification to a client:
+Publish to a client:
 
 <Code>
 ```shell
 ably push publish --client-id "user456" --title "Update" --body "New content available"
 ```
 </Code>
 
-Publish a push notification to a channel:
+Publish to a channel:
 
 <Code>
 ```shell
-ably push publish --channel "announcements" --title "News" --body "Breaking update" --force
+ably push publish --channel "announcements" --title "News" --body "Breaking update" --message "Breaking update" --force
 ```
 </Code>
 
-Publish with a custom payload:
+Publish to a device with a custom payload:
 
 <Code>
 ```shell
 ably push publish --device-id "device123" --payload '{"notification":{"title":"Custom","body":"Payload"},"data":{"key":"value"}}'
 ```
 </Code>
 
-Publish a push notification to a device with additional data:
+Publish to a device with additional data:
 
 <Code>
 ```shell
 ably push publish --device-id device-123 --title Hello --body World --data '{"key":"value"}'
 ```
 </Code>
 
-Publish to a device using a custom JSON payload:
+Publish to a device using a JSON payload string:
 
 <Code>
 ```shell
@@ -158,70 +158,90 @@ ably push publish --device-id device-123 --payload ./notification.json
 ```
 </Code>
 
-Publish to a client using a custom JSON payload:
+See notification file example [below](#notification-json-file).
+
+Publish to a client using a JSON payload string:
 
 <Code>
 ```shell
 ably push publish --client-id client-1 --payload '{"notification":{"title":"Hello","body":"World"}}'
 ```
 </Code>
 
-Publish to a channel with additional data:
+Publish to a channel with a message string and additional data:
 
 <Code>
 ```shell
-ably push publish --channel my-channel --title Hello --body World --data '{"key":"value"}'
+ably push publish --channel my-channel --title Hello --body World --data '{"key":"value"}' --message 'Hello from push'
 ```
 </Code>
 
-Publish to a channel using a custom JSON payload:
+Publish to a channel using a JSON payload string:
 
 <Code>
 ```shell
-ably push publish --channel my-channel --payload '{"notification":{"title":"Hello","body":"World"},"data":{"key":"value"}}'
+ably push publish --channel my-channel --payload '{"notification":{"title":"Hello","body":"World"},"data":{"key":"value"}}' --message 'Hello from push'
 ```
 </Code>
 
-Publish a push notification to a channel with a realtime message string:
+Publish to a channel with a message JSON object (a full message object with `name` and `data` fields):
 
 <Code>
 ```shell
-ably push publish --channel my-channel --title Hello --body World --message 'Hello from push'
+ably push publish --channel my-channel --title Hello --body World --message '{"name":"greeting","data":"Welcome back"}'
 ```
 </Code>
 
-Publish a push notification to a channel with a realtime message JSON payload:
+Publish to a channel with a message `data` JSON payload (a JSON object containing arbitrary message `data` fields):
 
 <Code>
 ```shell
 ably push publish --channel my-channel --title Hello --body World --message '{"event":"push","text":"Hello"}'
 ```
 </Code>
 
-Publish to a channel using a payload from a file:
+Publish to a channel using a payload from a file and a string message:
 
 <Code>
 ```shell
-ably push publish --channel my-channel --payload ./notification.json
+ably push publish --channel my-channel --payload ./notification.json --message 'Hello from push'
 ```
 </Code>
 
-Publish to a device using raw recipient attributes:
+See notification file example [below](#notification-json-file).
+
+Publish using raw recipient attributes:
 
 <Code>
 ```shell
 ably push publish --recipient '{"transportType":"apns","deviceToken":"token123"}' --title Hello --body World
 ```
 </Code>
 
-Publish a push notification and output the result in JSON format:
+Publish and output in JSON format:
 
 <Code>
 ```shell
 ably push publish --device-id device-123 --title Hello --body World --json
 ```
 </Code>
 
+### Notification.json file <a id="notification-json-file"/>
+
+<Code>
+```json
+{
+  "notification": {
+    "title": "Hello",
+    "body": "World"
+  },
+  "data": {
+    "key": "value"
+  }
+}
+```
+</Code>
+
 ## See also
 
 * [Push](/docs/cli/push) — Explore all `ably push` commands.