docs: clarify StikDebug script handling

Author: CelloSerenity

INTEGRATION.md

@@ -9,7 +9,7 @@ This guide separates two different jobs:
 - **Part 1: Add iOS 26 JIT support** changes the app's JIT memory allocator so it can cooperate with a script where TXM/SPTM is present.
 - **Part 2: Integrate StikDebug and StikJIT** adds the StikDebug URL scheme and optional Built-in StikJIT to an app that already works with iOS 26 JIT and manual StikDebug activation.
 
-If the app already enables JIT successfully after the user manually selects it and its script in StikDebug, skip Part 1. Record the script filename and complete Part 2. Part 2 does not require changing a working JIT allocator.
+If the app already enables JIT successfully after the user manually selects it and its script in StikDebug, skip Part 1. Record whether it uses `universal.js`, `legacy.js`, or a custom script file, then complete Part 2. Part 2 does not require changing a working JIT allocator.
 
 If the app does not already have script-based iOS 26 JIT, complete Part 1 first and then Part 2.
 
@@ -56,11 +56,9 @@ Use this order where TXM/SPTM is present:
 
 Preallocate executable regions before detaching. A region introduced later cannot be prepared by a script that has already detached; reconnect and repeat the protocol if the engine must add one.
 
-## Keep the legacy protocol only for backward compatibility
+> **Note:** We keep legacy script support only for backward compatibility with existing applications. If you are adding JIT support to an app now, use the universal script.
 
-The legacy script is retained only for existing engines that stop once at `brk #0x69` with the RX address in `x0` and its length in `x1`. It prepares that region, advances the program counter, and detaches. Do not build new integrations around `legacy.js`; implement the universal protocol instead.
-
-After Part 1 works with the matching script in StikDebug, continue with Part 2. The chosen script filename is developer-controlled and must not become a user setting.
+After Part 1 works with the matching script in StikDebug, continue with Part 2. The chosen script is developer-controlled and must not become a user setting.
 
 # Part 2: Integrate StikDebug and StikJIT into an existing iOS 26 JIT app
 
@@ -69,7 +67,9 @@ Part 2 assumes all of the following already work:
 - The app can wait for an external debugger and detect when JIT is ready.
 - The app's JIT allocator implements its iOS 26 breakpoint and executable-region protocol.
 - JIT works when the developer or user manually selects the app and matching script in StikDebug.
-- The developer knows which script filename the app requires, normally `universal.js`.
+- The developer knows whether the app requires `universal.js`, `legacy.js`, or a custom script file.
+
+If the app currently uses `legacy.js`, we recommend switching it to the universal method, but this is not required to complete Part 2.
 
 Part 2 preserves that existing **Wait for Debugger** path and adds automatic StikDebug URL launching and optional Built-in StikJIT. It does not change the app's JIT allocator or script protocol. If any prerequisite above is missing, complete Part 1 first.
 
@@ -262,7 +262,7 @@ try StikJIT.enableJIT(
 )
 ```
 
-Use `.universal` for new integrations. Use `.legacy` only when preserving an existing `legacy.js` ABI, or `.custom(URL)` for another established protocol. A custom script must be readable from the helper-extension process. Keep that selection in backend code and use the corresponding filename in the StikDebug URL. Do not expose script selection to the user. The user-facing `forceScript` toggle only bypasses TXM detection and runs the developer-selected script regardless.
+Use `.universal` or `.legacy` for the corresponding bundled script, or `.custom(URL)` for another established protocol. A custom script must be readable from the helper-extension process. Keep that selection in backend code. For StikDebug requests, send the matching built-in filename for universal or legacy, or send the base64-encoded contents of a custom script. Do not expose script selection to the user. The user-facing `forceScript` toggle only bypasses TXM detection and runs the developer-selected script regardless.
 
 ### When the user resets the cache
 
@@ -286,10 +286,16 @@ Route all three choices through the same host-side coordinator. Check `get-task-
 
 For **Wait for Debugger**, keep the app's existing waiting and readiness behavior. Where TXM/SPTM is present, it must continue through the existing breakpoint protocol before reporting success; an ordinary debugger attachment without the correct script is not sufficient.
 
-For **StikDebug**, construct the URL with `URLComponents` and include the bundle ID, current PID, and the developer-selected script filename:
+For **StikDebug**, always construct the URL with the bundle ID and current PID. If TXM/SPTM is present, also send the developer-selected script. Use `script-name=universal.js` or `script-name=legacy.js` for the scripts bundled with StikDebug. For any other script, base64-encode the file contents and send them as `script-data` instead. When TXM/SPTM is not present, omit both script parameters because debugger attachment alone enables JIT.
 
 ```swift
-private let stikDebugScriptName = "universal.js"
+private enum StikDebugScript {
+    case universal
+    case legacy
+    case custom(URL)
+}
+
+private let stikDebugScript: StikDebugScript = .universal
 
 guard let bundleID = Bundle.main.bundleIdentifier else {
     showJITError("Could not determine the app's bundle ID.")
@@ -302,9 +308,34 @@ components.host = "enable-jit"
 components.queryItems = [
     URLQueryItem(name: "bundle-id", value: bundleID),
     URLQueryItem(name: "pid", value: String(getpid())),
-    URLQueryItem(name: "script-name", value: stikDebugScriptName),
 ]
 
+if isTXMPresent {
+    switch stikDebugScript {
+    case .universal:
+        components.queryItems?.append(
+            URLQueryItem(name: "script-name", value: "universal.js")
+        )
+    case .legacy:
+        components.queryItems?.append(
+            URLQueryItem(name: "script-name", value: "legacy.js")
+        )
+    case .custom(let scriptURL):
+        do {
+            let scriptData = try Data(contentsOf: scriptURL)
+            components.queryItems?.append(
+                URLQueryItem(
+                    name: "script-data",
+                    value: scriptData.base64EncodedString()
+                )
+            )
+        } catch {
+            showJITError("Could not read the StikDebug script: \(error.localizedDescription)")
+            return
+        }
+    }
+}
+
 guard let url = components.url else {
     showJITError("Could not create the StikDebug request.")
     return
@@ -313,7 +344,7 @@ guard let url = components.url else {
 UIApplication.shared.open(url)
 ```
 
-Use `universal.js` for new integrations. Specify `legacy.js` only for an app that already implements the legacy ABI, or another installed script for an established custom protocol. Keep this choice in developer-controlled backend code and do not expose `script-name` as a user setting. StikDebug uses the PID to target the running process and the bundle ID to identify and return to the app.
+Send custom scripts through `script-data`; do not require users to install them in StikDebug. Keep script selection in developer-controlled backend code and do not expose it as a user setting. Resolve TXM/SPTM presence before building the request rather than treating an unknown result as absent. StikDebug uses the PID to target the running process and the bundle ID to identify and return to the app.
 
 If the app checks whether StikDebug is installed with `canOpenURL`, add this to its `Info.plist`:
 
@@ -385,15 +416,17 @@ After completing Part 1, Part 2, or both, please get in touch with us in the [id
 
 ## All methods
 
-- [ ] New iOS 26 integrations implement the universal protocol; legacy is used only for backward compatibility.
+- [ ] New iOS 26 integrations implement the universal protocol.
 - [ ] The host checks its own `get-task-allow` before starting JIT acquisition.
 - [ ] The selected script matches the app's breakpoint protocol and is not user-configurable.
 - [ ] Where TXM/SPTM is present, executable-region preparation succeeds before the workload starts.
 - [ ] Settings offer one mutually exclusive JIT method selection and start only that method.
 
 ### StikDebug
 
-- [ ] The URL includes bundle ID, current PID, and the developer-selected `script-name`.
+- [ ] The URL always includes bundle ID and current PID.
+- [ ] Where TXM/SPTM is present, the URL includes `script-name` for universal or legacy, or base64-encoded `script-data` for a custom script.
+- [ ] Where TXM/SPTM is not present, the URL omits both script parameters.
 - [ ] `stikdebug` is in `LSApplicationQueriesSchemes` if the app calls `canOpenURL`.
 - [ ] The app does not treat successful URL opening as successful JIT acquisition.
 - [ ] Inside LiveContainer, the app tells users to enable **Use LiveContainer's Bundle ID**.