@browserstack/mcp-server 2.3.0-beta.4 → 2.3.0-beta.6

package/capability/mobiledevicecontrol.capability-index.json

@@ -76,13 +76,17 @@
      "Every session occupies a device and consumes App Automate minutes until it ends: always finish with set_session_status and then delete_session.",
      "To let a person watch the device live while the agent drives it, set interactive_debugging true and leave video on; they then open the running session on the App Automate dashboard and start the interactive session there. That window is two-way: a person's taps and scrolls reach the same device, so ask them to watch only, or re-read the page source before every action.",
      "device_name and platform_version must be a combination mobile device control offers; an unknown pair fails with a session-not-created error naming the capability.",
-     "Set appium_version to 2.19.0 for any session that will use execute_script with a `mobile:` command; the default server is 1.x and answers those with a 404 listing the commands it does know.",
+     "Set appium_version to 2.19.0 for any session that will scroll with scroll_gesture, dismiss an iOS keyboard with dismiss_keyboard_key, or use any other mobile: capability; the default server is 1.x and answers those with a 404 listing the commands it does know.",
      "enable_biometric, enable_camera_image_injection and upload_media only take effect when set here \u2014 none of them can be turned on once the session is running.",
      "Credentials belong in the Authorization header, never inside bstack:options: capabilities are echoed back in session-not-created errors.",
      "device_name and platform_version come from list_devices; get_plan first if sessions are queueing rather than starting.",
      "Treat a response without value.sessionId as a failed start even when the status is 200, and treat a failed call the same way: allocation can outlast the client's own timeout, so BrowserStack may have started a session the answer never named. One is then holding a device and consuming minutes until its idle timeout.",
      "After a start that failed or returned no session id, look for a session left running on the account and end it rather than starting another.",
-     "The response carries no link of any kind \u2014 it is the session id and the negotiated capabilities only. Call get_session for the links: browser_url to watch the run on the dashboard, and public_url to share it with someone who has no BrowserStack account."
+     "The response carries no link of any kind \u2014 it is the session id and the negotiated capabilities only. Call get_session for the links: browser_url to watch the run on the dashboard, and public_url to share it with someone who has no BrowserStack account.",
+     "LANGUAGE AND LOCALE LAND IN DIFFERENT PLACES ON THE TWO PLATFORMS. On Android they change the device, and the app with it \u2014 measured with language de and locale DE: the system's own permission dialog came up in German and the app rendered German throughout. On iOS they leave the device alone \u2014 Settings and General stay in English \u2014 and apply to the app under test at launch. Either way nothing is visible unless the app actually ships that language, so test with an app that does and read the strings back from get_page_source rather than trusting the call's 200.",
+     "Both are accepted without complaint on both platforms, so a 200 says nothing about whether anything changed. There is also no way to confirm the device locale from inside the session: read_device_property refuses getprop persist.sys.locale and ro.product.locale as unsupported commands. Judge it from what is on screen.",
+     "THIS CALL RETURNS NO LINK \u2014 only value.sessionId. Nothing here can open a browser for the user either: this surface makes HTTP requests, and on a remote server there is no browser to open. So never say a live view was opened. If the user may want to watch, call get_session straight after this and give them browser_url in the same reply, which is the session on the dashboard and needs a BrowserStack login. public_url needs no login but carries an auth token, so offer it only when they ask to share outside the team.",
+     "Someone can only WATCH AND INTERACT if interactive_debugging was set true in this call \u2014 it cannot be turned on once the session is running, it is off by default on Android, and it needs video left on. Ask for it up front when a person is going to follow along, because the alternative is restarting the session."
     ],
     "body": [
      {
@@ -209,15 +213,15 @@
       "name": "language",
       "type": "string",
       "json_path": "/capabilities/alwaysMatch/appium:language",
-      "description": "Device language code.",
-      "example": "fr"
+      "description": "Language code applied at session start. On Android it sets the DEVICE language \u2014 the system's own dialogs render in it \u2014 and the app follows. On iOS it does NOT change the device: Settings stays in English, and the code is applied to the app under test at launch instead.",
+      "example": "de"
      },
      {
       "name": "locale",
       "type": "string",
       "json_path": "/capabilities/alwaysMatch/appium:locale",
-      "description": "Device locale.",
-      "example": "fr_CA"
+      "description": "Region applied with `language`, same split: the device on Android, the app under test on iOS. Android takes a bare region code such as DE.",
+      "example": "DE"
      },
      {
       "name": "timezone",
@@ -459,12 +463,12 @@
     "entity": "app_session",
     "intent": "Type text into an input field in the app \u2014 use this to fill a search box, login form or any editable field found with find_element.",
     "guidance": [
-     "REPLACES whatever the field already holds rather than adding to it \u2014 measured on Android with and without refocusing between calls. Read the field back from get_page_source if the resulting value matters, and do not build up a value with successive calls.",
+     "WHETHER THIS REPLACES OR APPENDS DEPENDS ON THE PLATFORM: on Android it replaces whatever the field already holds, and on iOS it appends to it. Typing twice into one iOS field therefore leaves both values joined. Read the field back from get_page_source whenever the resulting value matters.",
      "The element must be an editable field (EditText on Android, TextField on iOS); typing into anything else fails with \"invalid element state\".",
      "The on-screen keyboard may stay open afterwards and cover lower elements \u2014 re-read the page source before the next tap.",
-     "The W3C specification says this appends, and other Appium drivers may; do not rely on either behaviour across platforms without checking. There is no separate way to empty a field on this surface: the standard clear endpoint answers 200 without reliably emptying the field, so typing the value you want is the way to set it.",
-     "The keyboard is usually left open afterwards: call hide_keyboard before tapping anything below the field, and is_keyboard_shown to confirm it closed.",
-     "Sending a newline submits the field and closes the keyboard on iOS, which is the most reliable way to dismiss it there."
+     "clear_element empties a field, and on iOS \u2014 where this APPENDS \u2014 it is the only way to take back what is already there. It answers 200 whether or not the field changed, so read the field back from get_page_source rather than trusting the status.",
+     "The keyboard is usually left open afterwards. On Android and on an iPad, hide_keyboard closes it. On an iPhone it cannot be closed without submitting, so read hide_keyboard's guidance before planning a tap below the field.",
+     "Sending a newline closes the keyboard on iOS by pressing Return, which an app that commits on editing-ended will treat as a submit \u2014 the field resets and the value moves wherever the app sends it. The commit is the app's doing, not the newline's: dismissing the same field any other way can commit it too. See hide_keyboard."
     ],
     "path_params": [
      {
@@ -504,6 +508,51 @@
      }
     }
    },
+   {
+    "name": "clear_element",
+    "method": "POST",
+    "path": "/wd/hub/session/{session_id}/element/{element_id}/clear",
+    "mode": "write",
+    "entity": "app_session",
+    "intent": "Empty an editable field in the app \u2014 use this before typing when the field already holds something and you need to replace rather than add to it.",
+    "guidance": [
+     "Takes no parameters of its own.",
+     "CONFIRM IT ACTUALLY EMPTIED THE FIELD by reading the field back from get_page_source: this endpoint can answer 200 without the field changing, and the status alone does not tell you which happened.",
+     "Needed far more on iOS than on Android: send_keys REPLACES the field's contents on Android, so clearing first is usually unnecessary there, while on iOS it APPENDS and this is the only way to take back what is already in the field.",
+     "The element must be an editable field \u2014 EditText on Android, TextField on iOS. Anything else answers \"invalid element state\".",
+     "The element_id must come from find_element on the current screen; after the screen changes it is stale and fails with \"stale element reference\"."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     },
+     {
+      "name": "element_id",
+      "type": "string",
+      "required": true,
+      "description": "Element id from find_element.",
+      "example": "element-6066-11e4-a52e-4f735466cecf"
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "Field emptied; value is null. The null says the call was accepted, not that the field changed \u2014 read the field back to know that.",
+      "schema": {
+       "$schema": "NullValueResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     }
+    },
+    "send_empty_body": true
+   },
    {
     "name": "perform_actions",
     "method": "POST",
@@ -516,7 +565,7 @@
      "Tap: one touch pointer with pointerMove(duration 0, x, y), pointerDown(button 0), pause(100), pointerUp(button 0).",
      "Swipe up to scroll content down: pointerMove to a low point, pointerDown, pointerMove(duration 600) to a higher point, pointerUp. Keep the start and end inside the scrollable element's bounds.",
      "Long-press: replace the pause duration with 1000 or more.",
-     "For a scroll without computing coordinates, execute_script with \"mobile: scrollGesture\" is simpler and reports whether more content remains.",
+     "For a scroll without computing coordinates, scroll_gesture is simpler on Android and reports whether more content remains; on iOS use scroll_view; compute a swipe here only when neither fits.",
      "To go back on an iOS screen that ignores press_back, swipe in from the left edge: a pointer sequence starting at exactly x=0 and moving right in several short steps. A single long move does not register."
     ],
     "path_params": [
@@ -607,6 +656,201 @@
      }
     }
    },
+   {
+    "name": "scroll_gesture",
+    "method": "POST",
+    "path": "/wd/hub/session/{session_id}/execute/sync",
+    "mode": "write",
+    "entity": "app_session",
+    "intent": "Scroll a region of the screen in a direction \u2014 use this to move through a list or page without working out start and end coordinates yourself.",
+    "guidance": [
+     "ANDROID ONLY. On iOS this is a 405 \"unknown method\"; scroll_view is the iOS counterpart.",
+     "The returned value is true when the view can still scroll further in that direction and false when it cannot \u2014 but the FIRST scroll of a freshly opened list can answer false while the screen moved and more content followed, so treat false as a hint and confirm from the page source before deciding you are at the end.",
+     "The area is a rectangle in screen pixels \u2014 get_window_rect gives the screen size to base it on \u2014 and percent is how far to scroll within it, 0 to 1.",
+     "Needs Appium 2.x: set appium_version to 2.19.0 at session start, since the default 1.x server answers mobile: commands with a 404 listing what it does know."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     }
+    ],
+    "body": [
+     {
+      "name": "script",
+      "type": "string",
+      "required": true,
+      "example": "mobile: scrollGesture",
+      "values": [
+       "mobile: scrollGesture"
+      ]
+     },
+     {
+      "name": "args",
+      "type": "array",
+      "required": true,
+      "description": "Exactly one object: the rectangle to scroll inside, the direction, and how far.",
+      "example": [
+       {
+        "left": 100,
+        "top": 500,
+        "width": 880,
+        "height": 1500,
+        "direction": "down",
+        "percent": 0.8
+       }
+      ]
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "Command result; its shape depends on the command.",
+      "schema": {
+       "$schema": "AnyValueResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     },
+     "500": {
+      "$response": "WebDriverError"
+     }
+    }
+   },
+   {
+    "name": "scroll_view",
+    "method": "POST",
+    "path": "/wd/hub/session/{session_id}/execute/sync",
+    "mode": "write",
+    "entity": "app_session",
+    "intent": "Scroll a scrollable view on iOS in a direction, or until a named element is visible \u2014 use this to move through a list or a long screen.",
+    "guidance": [
+     "iOS ONLY, and the counterpart of scroll_gesture. On Android the same command exists with a different shape and answers 400 \"invalid argument\" naming strategy and selector as missing; use scroll_gesture there.",
+     "Scroll by direction with {\"direction\":\"down\"}, or stop when something comes into view with {\"predicateString\":\"name == 'Submit'\", \"toVisible\": true} \u2014 the second is the reliable way to reach a known control without guessing how far to go.",
+     "Pass elementId in args to scroll inside that view rather than the whole screen; without one it scrolls the first scrollable view it finds, which may not be the one you meant.",
+     "Needs Appium 2.x: set appium_version to 2.19.0 at session start, since the default 1.x server answers mobile: commands with a 404 listing what it does know.",
+     "Confirm from get_page_source that the screen actually moved \u2014 this answers 200 even on a screen with nothing scrollable, so a 200 only says the gesture was delivered."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     }
+    ],
+    "body": [
+     {
+      "name": "script",
+      "type": "string",
+      "required": true,
+      "values": [
+       "mobile: scroll"
+      ],
+      "example": "mobile: scroll"
+     },
+     {
+      "name": "args",
+      "type": "array",
+      "required": true,
+      "description": "Exactly one object: a direction, or a predicateString with toVisible, optionally with elementId naming the view to scroll inside.",
+      "example": [
+       {
+        "direction": "down"
+       }
+      ]
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "Command result; its shape depends on the command.",
+      "schema": {
+       "$schema": "AnyValueResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     },
+     "500": {
+      "$response": "WebDriverError"
+     }
+    }
+   },
+   {
+    "name": "dismiss_keyboard_key",
+    "method": "POST",
+    "path": "/wd/hub/session/{session_id}/execute/sync",
+    "mode": "write",
+    "entity": "app_session",
+    "intent": "Close the on-screen keyboard by pressing one of its own keys \u2014 use this on an iPhone, where the plain hide_keyboard is refused.",
+    "guidance": [
+     "hide_keyboard already presses these keys on an iPhone when its plain call is refused \u2014 Done-type keys first, then Return \u2014 and reports each attempt. Call this directly to press exactly the key you choose: Return alone, or every key but Return when a submit must not happen.",
+     "The key must EXIST on that keyboard or this returns the same 400: read the keyboard from get_page_source and pick from the keys that are really there. An iPad carries \"Hide keyboard\"; an iPhone keyboard of this kind usually offers only Return.",
+     "Several candidates may be listed in one call and it costs nothing, but it still fails when the keyboard carries none of them \u2014 measured with [\"Done\",\"done\",\"Hide keyboard\",\"Dismiss\"].",
+     "PRESSING RETURN SUBMITS. An app that commits when the field stops being edited will commit however the keyboard is closed, so check the field afterwards rather than assuming only the keyboard moved.",
+     "Confirm with is_keyboard_shown; on Android and on an iPad hide_keyboard closes it on its own."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     }
+    ],
+    "body": [
+     {
+      "name": "script",
+      "type": "string",
+      "required": true,
+      "example": "mobile: hideKeyboard",
+      "values": [
+       "mobile: hideKeyboard"
+      ]
+     },
+     {
+      "name": "args",
+      "type": "array",
+      "required": true,
+      "description": "Exactly one object whose keys field lists the key names to try, in order.",
+      "example": [
+       {
+        "keys": [
+         "Done",
+         "done",
+         "Hide keyboard",
+         "Dismiss"
+        ]
+       }
+      ]
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "Command result; its shape depends on the command.",
+      "schema": {
+       "$schema": "AnyValueResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     },
+     "500": {
+      "$response": "WebDriverError"
+     }
+    }
+   },
    {
     "name": "execute_script",
     "method": "POST",
@@ -670,7 +914,8 @@
      "500": {
       "$response": "WebDriverError"
      }
-    }
+    },
+    "disabled": true
    },
    {
     "name": "get_window_rect",
@@ -718,7 +963,7 @@
     "guidance": [
      "There is no way to resume an ended session; any further step needs create_session again, which reinstalls the app.",
      "The session's video, logs and pass/fail status stay on the App Automate dashboard after it ends.",
-     "Call setSessionStatus through execute_script first \u2014 once the session has ended that route is gone."
+     "Mark the result with set_session_status first \u2014 it also works after the session has ended, so this is an ordering preference rather than a last chance."
     ],
     "path_params": [
      {
@@ -729,23 +974,14 @@
      }
     ],
     "returns": [
+     "state",
      "value"
     ],
     "responses": {
      "200": {
-      "description": "Session ended; state is \"success\" and value is empty.",
+      "description": "state is \"success\" and value an empty string; the body is the hub's own, not the W3C null.",
       "schema": {
-       "type": "object",
-       "properties": {
-        "state": {
-         "type": "string",
-         "description": "\"success\" when the session was ended."
-        },
-        "value": {
-         "type": "string",
-         "description": "Empty string."
-        }
-       }
+       "$schema": "SessionDeletedResponse"
       }
      },
      "404": {
@@ -860,13 +1096,14 @@
     "entity": "app_build",
     "intent": "Upload an app build to App Automate from a public download link and get back the bs:// URL a session installs \u2014 use this to make a new .apk, .aab or .ipa available to devices.",
     "guidance": [
-     "Only the download-link form can be used here. The same endpoint also accepts a multipart upload carrying the file itself, which this surface cannot send \u2014 so for a build that exists only on the caller's own machine, give them that multipart request to run themselves and take the bs:// url it returns. There is no way to hand the bytes over from here.",
+     "Only the download-link form can be used here. The same endpoint also accepts a multipart upload carrying the file itself, which this surface cannot send \u2014 so for a build that exists only on the caller's own machine, give them that multipart request to run themselves and take the bs:// url it returns. The upload answers with the bs:// url directly: there is no intermediate storage, no presigned url and no second call. There is no way to hand the bytes over from here.",
      "The url must be https and reachable by BrowserStack without credentials; a link behind a login fails on their side, not the caller's.",
      "Pass custom_id to give the build a stable name, then later sessions can use that name in place of the bs:// URL and always get the newest build under it.",
      "Re-uploading under the same custom_id adds a new build rather than replacing the old one; both stay listed.",
      "Builds expire after 30 days, so a bs:// URL held from an earlier run can stop working.",
      "Uploading a large build can take minutes \u2014 the call does not return until BrowserStack has fetched the whole file.",
-     "upload_app_build_from_file takes a build that is on this machine instead, where the server runs beside the user. It is not offered on a remote server, where a path would name the operator's disk rather than theirs."
+     "upload_app_build_from_file takes a build that is on this machine instead, where the server runs beside the user. It is not offered on a remote server, where a path would name the operator's disk rather than theirs.",
+     "Before uploading at all, check list_app_builds \u2014 a build from an earlier run is still usable for 30 days, and on a remote server reusing one is the only route that needs nothing from the user."
     ],
     "body": [
      {
@@ -913,7 +1150,8 @@
     "guidance": [
      "An account with no uploads answers with a message object or a 404 rather than an empty array; treat both as 'nothing uploaded yet'.",
      "This is only the calling user's own uploads \u2014 use list_team_app_builds for everyone on the team.",
-     "app_url is what create_session takes; app_id is an internal identifier and is not accepted there."
+     "app_url is what create_session takes; app_id is an internal identifier and is not accepted there.",
+     "On a remote server this is the first thing to try: uploading from a path is not offered there, so an existing build is the only app a session can install without either a public link or the user running an upload by hand."
     ],
     "query": [
      {
@@ -1097,8 +1335,7 @@
      "Works after the session has ended as well as during it, so the verdict can be set once the result is known.",
      "Only 'passed' and 'failed' are accepted; any other value is rejected with a 422.",
      "reason is truncated at 255 characters.",
-     "An unset session shows as neither passed nor failed on the dashboard, which reads as an abandoned run.",
-     "The same thing can be done from inside a running session with execute_script and the browserstack_executor setSessionStatus action; this way needs no open session."
+     "An unset session shows as neither passed nor failed on the dashboard, which reads as an abandoned run."
     ],
     "path_params": [
      {
@@ -1448,10 +1685,13 @@
     "entity": "app_session",
     "intent": "Close the on-screen keyboard \u2014 use this when it covers a button or field you need to tap after typing.",
     "guidance": [
-     "The response is true when a keyboard was dismissed and false when none was showing; false is not an error.",
-     "On iOS this can be refused by a keyboard the app controls; the fallback is tapping an empty area or the keyboard's own Done key.",
+     "On a plain success the response is true when a keyboard was dismissed and false when none was showing; false is not an error. A success reached through the chain below carries the key press's own null value instead.",
      "A tap aimed at a control hidden behind the keyboard lands on the keyboard instead and reports success, so close it first rather than afterwards.",
-     "On iOS this frequently leaves the keyboard open while still answering successfully, so always confirm with is_keyboard_shown. Two things do close it there: send_keys with a newline, or execute_script with 'mobile: hideKeyboard' and args [{\"keys\":[\"return\"]}]. Tapping an empty area of the screen does not, and neither does that command with no keys or with [\"Done\"], which fail as \"invalid element state\".",
+     "ON AN iPHONE THE PLAIN CALL IS REFUSED AND A CHAIN RUNS INSTEAD. That keyboard has no dismiss key, so the product answers 400 \"Did not know how to dismiss the keyboard\"; this then presses a key the keyboard actually carries \u2014 Done, Hide keyboard or Dismiss where one exists, and failing that Return. On an iPad the plain call closes it, because that keyboard carries \"Hide keyboard\"; on Android it closes it; neither runs the chain.",
+     "THE RESPONSE LISTS EVERY ATTEMPT WITH ITS STATUS under fallback.attempts, so read which one closed it. When the last attempt's keys include Return, Return is what was pressed \u2014 and in many apps that is a submit: a search runs, a form goes. Read the field and the screen back before assuming only the keyboard moved.",
+     "When no attempt answers 200 the keyboard stays up and the last 400 is the answer: the app offers no way to close it from outside, which a person on the phone would hit too. dismiss_keyboard_key is the same key press on its own, for trying exactly the key you choose \u2014 Return alone, or everything but Return.",
+     "GESTURES DO NOT DISMISS IT. Tapping an empty area above the keyboard returns 200 and changes nothing, and so does a drag downward over it \u2014 including one that starts well above the keyboard's top and moves through it in short steps, which is the form that works on a screen whose scroll view dismisses on drag. This app's does not, and neither gesture moved it.",
+     "WHETHER THE FIELD SURVIVES IS THE APP'S BUSINESS, NOT THE KEYBOARD'S. An app that commits on editing-ended will commit however the keyboard is dismissed \u2014 closing an iPad keyboard this way still moved the text out of the field. So do not expect any dismissal to be side-effect free; check the app's own behaviour. On Android it closes the keyboard, answers true, and leaves the field as it was.",
      "is_keyboard_shown reports the state this changes, and is the reliable way to tell whether the keyboard actually went away."
     ],
     "path_params": [
@@ -1462,6 +1702,50 @@
       "example": "0123456789abcdef0123456789abcdef01234567"
      }
     ],
+    "fallbacks": [
+     {
+      "when": {
+       "status": 400
+      },
+      "capability": "dismiss_keyboard_key",
+      "body": {
+       "script": "mobile: hideKeyboard",
+       "args": [
+        {
+         "keys": [
+          "Done",
+          "done",
+          "Hide keyboard",
+          "Dismiss"
+         ]
+        }
+       ]
+      }
+     },
+     {
+      "when": {
+       "status": 400
+      },
+      "capability": "dismiss_keyboard_key",
+      "body": {
+       "script": "mobile: hideKeyboard",
+       "args": [
+        {
+         "keys": [
+          "Return",
+          "return",
+          "Go",
+          "go",
+          "Next",
+          "next",
+          "Search",
+          "search"
+         ]
+        }
+       ]
+      }
+     }
+    ],
     "returns": [
      "value"
     ],
@@ -1690,11 +1974,11 @@
     "entity": "app_session",
     "intent": "Press a hardware or system key on an Android device by its key code \u2014 use this for home, enter, delete, volume or any key with no on-screen control.",
     "guidance": [
-     "Android only. iOS has no equivalent: use press_back to go back, and execute_script with 'mobile: pressButton' for home and the volume keys.",
+     "Android only. iOS has no equivalent: use press_back to go back, and press_button for home and the volume keys.",
      "Common codes: 3 home, 4 back, 66 enter, 67 delete, 61 tab, 82 menu, 84 search, 187 app switch, 24 volume up, 25 volume down, 26 power.",
      "press_back is the clearer way to send 4.",
      "The response is null on success and says nothing about what the key did.",
-     "Called on iOS this is a 405 \"unknown method\" rather than a silent no-op; use press_back or 'mobile: pressButton' there."
+     "Called on iOS this is a 405 \"unknown method\" rather than a silent no-op; use press_back or press_button there."
     ],
     "path_params": [
      {
@@ -1752,7 +2036,7 @@
      "Returns the Android package name; it answers with the launcher's package when the app has been sent to the background.",
      "This is the quickest way to learn the app under test's own package id, which launch_app and terminate_app both need.",
      "Android only; get_active_app_info is the iOS equivalent and returns an object rather than a string.",
-     "Called on iOS this is a 405 \"unknown method\" rather than a silent no-op; use 'mobile: activeAppInfo' there."
+     "Called on iOS this is a 405 \"unknown method\" rather than a silent no-op; use get_active_app_info there."
     ],
     "path_params": [
      {
@@ -1807,7 +2091,7 @@
     "entity": "app_session",
     "intent": "Bring an app to the foreground, starting it if it is not running \u2014 use this to open the app under test, return to it, or switch to another installed app.",
     "guidance": [
-     "Android takes appId and iOS takes bundleId \u2014 send exactly the one for the platform. The wrong name is refused with a 400 \"invalid argument\" that names the parameter it wanted, and no action is taken.",
+     "The app is named INSIDE `args`, which is the one object there: args [{\"appId\": \"com.example.app\"}] on Android, args [{\"bundleId\": \"com.example.app\"}] on iOS. Sending appId or bundleId as a top-level body field is refused here before anything is sent \u2014 \"unknown body: bundleId. accepted: args, script\" \u2014 and sending the wrong one for the platform is refused by the product with a 400 \"invalid argument\" naming the parameter it wanted, with no action taken.",
      "Launching an app that is already in the foreground does nothing and still reports success.",
      "To restart an app from a clean state, call terminate_app first and then this.",
      "Succeeding means the app was activated, not that it finished drawing, so give it a moment and confirm before acting. An app that cannot be brought forward at all answers 400 rather than reporting success, and get_app_state reads 4 once it really is in front \u2014 sampled too early it can still report the home screen mid-switch.",
@@ -1880,7 +2164,7 @@
     "entity": "app_session",
     "intent": "Close an app and stop it running \u2014 use this to end a session inside the app, or as the first half of a restart.",
     "guidance": [
-     "Android takes appId and iOS takes bundleId \u2014 send exactly the one for the platform. The wrong name is refused with a 400 \"invalid argument\" that names the parameter it wanted, and no action is taken.",
+     "The app is named INSIDE `args`, which is the one object there: args [{\"appId\": \"com.example.app\"}] on Android, args [{\"bundleId\": \"com.example.app\"}] on iOS. Sending appId or bundleId as a top-level body field is refused here before anything is sent \u2014 \"unknown body: bundleId. accepted: args, script\" \u2014 and sending the wrong one for the platform is refused by the product with a 400 \"invalid argument\" naming the parameter it wanted, with no action taken.",
      "Returns true when the app was running and false when it was not; false is not an error.",
      "The app stays installed and keeps its data; only the running process is stopped.",
      "This does not clear state between runs \u2014 relaunching shows the app where it was unless the app itself resets."
@@ -1952,7 +2236,7 @@
     "entity": "app_session",
     "intent": "Check whether an app is installed, running or in the foreground \u2014 use this to confirm a launch or a close actually took effect.",
     "guidance": [
-     "Android takes appId and iOS takes bundleId \u2014 send exactly the one for the platform. The wrong name is refused with a 400 \"invalid argument\" that names the parameter it wanted, and no action is taken.",
+     "The app is named INSIDE `args`, which is the one object there: args [{\"appId\": \"com.example.app\"}] on Android, args [{\"bundleId\": \"com.example.app\"}] on iOS. Sending appId or bundleId as a top-level body field is refused here before anything is sent \u2014 \"unknown body: bundleId. accepted: args, script\" \u2014 and sending the wrong one for the platform is refused by the product with a 400 \"invalid argument\" naming the parameter it wanted, with no action taken.",
      "The value is a number: 0 not installed, 1 installed but not running, 2 running in the background and suspended, 3 running in the background, 4 running in the foreground.",
      "4 is the only state in which the app is on screen and can be driven.",
      "The same scale applies on both platforms. Sending an app to the background leaves it at 3 or 2 \u2014 the system suspends it a moment after it stops being visible \u2014 so treat anything below 4 as not on screen rather than waiting for one number. Launching it again returns it to 4."
@@ -2365,7 +2649,7 @@
     "guidance": [
      "iOS only; press_keycode is the Android equivalent and the two are not interchangeable.",
      "The button names carry no separator: home, volumeup, volumedown.",
-     "Pressing home sends the app to the background \u2014 bring it back with launch_app, passing bundleId rather than appId, and confirm from the page source that the app is in front again.",
+     "Pressing home sends the app to the background \u2014 bring it back with launch_app, whose args object takes bundleId rather than appId on iOS, and confirm from the page source that the app is in front again.",
      "The response is null on success and says nothing about what the button did."
     ],
     "path_params": [
@@ -2547,7 +2831,8 @@
      "Only `getprop <property>` can be expressed: the accepted form is fixed, and a command that lists apps or system state cannot be sent through this capability. A public phone is shared between customers, and commands such as `pm list packages` or `dumpsys` report what other people's sessions left behind.",
      "BrowserStack applies its own allow-list on top of this one and accepts only some properties on a shared phone; ro.build.version.release and ro.product.manufacturer are accepted, while a bare getprop is not. A property it refuses comes back as an execution failure rather than an empty value.",
      "The device name and OS version are already in the session record, so get_session answers those without this.",
-     "The whole line must be sent exactly as shown, with no extra spaces: it is matched against a fixed form."
+     "The whole line must be sent exactly as shown, with no extra spaces: it is matched against a fixed form.",
+     "The allowed property list is narrow and locale is not on it: getprop persist.sys.locale and getprop ro.product.locale both come back HTTP 500, \"BROWSERSTACK_UNSUPPORTED_ADB_SHELL_COMMAND ... is not supported on BrowserStack currently\". ro.build.version.release and ro.product.manufacturer do work, so treat the refusal as a per-property allow-list rather than a broken capability."
     ],
     "path_params": [
      {
@@ -2599,14 +2884,25 @@
     "encoding": "multipart",
     "local_only": true,
     "intent": "Upload an app build that is on this machine to App Automate and get back the bs:// URL a session installs \u2014 use this when the .apk, .aab or .ipa is a local file rather than a download link.",
-    "guidance": [
-     "The file must sit inside the directory MCP_UPLOAD_BASE_DIR names. When that is not set the upload is refused and nothing is sent: tell the user to set it to the folder holding their builds and restart the server, then move the build there.",
-     "When it is set but the build is somewhere else, the refusal names the directory the file has to be inside. Tell the user to move it there rather than trying another path.",
-     "Only .apk, .aab and .ipa are accepted, and no part of the path may be a hidden folder, so a build under a dot-directory has to be moved out of it.",
-     "The path is checked before anything is uploaded and before the user is asked to approve, so a refusal costs nothing and means the file was never read.",
-     "upload_app_build takes a public https link instead and is the one to use when the build is not on this machine.",
-     "A large build takes minutes, because the call does not return until the whole file has been sent."
-    ],
+    "guidance": {
+     "shared": [
+      "Only .apk, .aab and .ipa are accepted.",
+      "A large build takes minutes, because the upload does not return until the whole file has been sent.",
+      "upload_app_build takes a public https link instead, and list_app_builds reuses a build already on the account \u2014 builds last 30 days."
+     ],
+     "local": [
+      "The file must sit inside the directory MCP_UPLOAD_BASE_DIR names. When that is not set the upload is refused and nothing is sent: tell the user to set it to the folder holding their builds and restart the server.",
+      "When it is set but the build is somewhere else, the refusal names the directory the file has to be inside. Tell the user to move it there rather than trying another path.",
+      "No part of the path may be a hidden folder, so a build under a dot-directory has to be moved out of it.",
+      "The path is checked before anything is uploaded and before the user is asked to approve, so a refusal costs nothing and means the file was never read."
+     ],
+     "remote": [
+      "Cheapest route first: list_app_builds or list_team_app_builds, if the build was uploaded before.",
+      "Then upload_app_build, if the build sits at a public https link \u2014 the only route that needs nothing from the user.",
+      "Otherwise the user uploads it themselves. The asset-upload helper PRINTS a curl command and nothing more \u2014 it reads no file and sends no request \u2014 so the user runs that command, and it answers with the bs:// url directly from /app-automate/upload. There is no intermediate storage and no second step.",
+      "Take the bs:// url back from them and pass it as the app for create_session."
+     ]
+    },
     "body": [
      {
       "name": "file",
@@ -2638,8 +2934,7 @@
      "401": {
       "$response": "Unauthorized"
      }
-    },
-    "unavailable_note": "This server does not run on your own machine, so it cannot read a file you name \u2014 a path sent here would point at the machine hosting the server. Upload the build yourself with a multipart request carrying the file to the same endpoint, which the asset-upload helper will write out for you, and then use the bs:// url it returns as the app for create_session. upload_app_build does the same thing from a public download link, if the build is reachable at one."
+    }
    },
    {
     "name": "find_elements",
@@ -3145,6 +3440,24 @@
       }
      }
     }
+   },
+   "SessionDeletedResponse": {
+    "type": "object",
+    "description": "What the hub returns when a session is closed. Not the W3C null: state says whether it closed and value is an empty string.",
+    "properties": {
+     "state": {
+      "type": "string",
+      "description": "\"success\" when the session was closed."
+     },
+     "status": {
+      "type": "integer",
+      "description": "The hub's own legacy status code; 0 on success."
+     },
+     "value": {
+      "type": "string",
+      "description": "Always empty on success."
+     }
+    }
    }
   },
   "responses": {
@@ -3220,7 +3533,11 @@
      "get_simulated_location",
      "get_active_app_info",
      "read_device_property",
-     "find_elements"
+     "find_elements",
+     "clear_element",
+     "scroll_gesture",
+     "dismiss_keyboard_key",
+     "scroll_view"
     ]
    },
    "device": {