diff --git a/orchestrator/alps.json b/orchestrator/alps.json
index 422660c..4c9f995 100644
--- a/orchestrator/alps.json
+++ b/orchestrator/alps.json
@@ -3926,6 +3926,10 @@
                                   },
                                   "sponsoredProtocolFeeUsd": {
                                     "type": "number"
+                                  },
+                                  "plannedGasPrincipalMicroUsd": {
+                                    "type": "string",
+                                    "format": "uint256"
                                   }
                                 },
                                 "required": [
@@ -6617,6 +6621,10 @@
                                     },
                                     "sponsoredProtocolFeeUsd": {
                                       "type": "number"
+                                    },
+                                    "plannedGasPrincipalMicroUsd": {
+                                      "type": "string",
+                                      "format": "uint256"
                                     }
                                   },
                                   "required": [
@@ -7750,7 +7758,7 @@
                         "amount": {
                           "type": "string",
                           "format": "uint256",
-                          "description": "The amount of the requested token (in the smallest unit). Omit for max-out.",
+                          "description": "The amount of the requested token (in the smallest unit). Omit for max-out. IMPORTANT: for a self-send with no `destinationExecutions`, any balance of this token already held on the destination chain is CREDITED against the request, so this behaves as a target final balance and an already-satisfied request delivers nothing. The credit only applies when that destination balance is in scope as a source — pinning `sourceAssets` or `sourceChains` away from the destination chain excludes it, and then this amount is delivered in full on top of whatever is already there. Same-chain intents always have the destination balance in scope, so they always credit.",
                           "example": "1000000"
                         },
                         "balance": {
@@ -7761,7 +7769,7 @@
                         "tokenAddress"
                       ]
                     },
-                    "description": "A list of token requested on the target chain"
+                    "description": "A list of tokens requested on the target chain. Note `amount` may be credited against a balance already held on the destination chain — see the field for exactly when."
                   },
                   "account": {
                     "type": "object",
@@ -8343,7 +8351,7 @@
                             "type": "integer",
                             "minimum": 0,
                             "maximum": 10000,
-                            "description": "App fee rate in basis points of the input value (0–10000 = 0–100%).",
+                            "description": "App fee rate in basis points (0–10000 = 0–100%). The base is the USD value of the intent, and which value depends on the intent shape: for a fixed-output intent it is the requested destination target(s), summed across `tokenRequests`; for a max-out intent it is the spendable source balance; for a destination-swap intent it is the swap input. Note the fixed-output base is the full requested target, not the delta over any balance already held.",
                             "example": 25
                           }
                         },
@@ -8358,7 +8366,7 @@
                             "type": "integer",
                             "minimum": 0,
                             "maximum": 10000,
-                            "description": "Rhinestone protocol fee rate in basis points of the input value (0–10000 = 0–100%). Collected alongside the app fee in one batched transfer and always accrues to Rhinestone; sponsor it via `sponsorSettings.protocolFees` to charge the integrator balance instead of the user.",
+                            "description": "Rhinestone protocol fee rate in basis points (0–10000 = 0–100%), on the same base as `appFees.feeBps` — see that field. Collected alongside the app fee in one batched transfer and always accrues to Rhinestone; sponsor it via `sponsorSettings.protocolFees` to charge the integrator balance instead of the user.",
                             "example": 35
                           }
                         },
diff --git a/orchestrator/blanc.json b/orchestrator/blanc.json
index 3aee635..d6b25ce 100644
--- a/orchestrator/blanc.json
+++ b/orchestrator/blanc.json
@@ -9191,7 +9191,7 @@
                         "amount": {
                           "type": "string",
                           "format": "uint256",
-                          "description": "The amount of the requested token (in the smallest unit). Omit for max-out.",
+                          "description": "The amount of the requested token (in the smallest unit). Omit for max-out. IMPORTANT: for a self-send with no `destinationExecutions`, any balance of this token already held on the destination chain is CREDITED against the request, so this behaves as a target final balance and an already-satisfied request delivers nothing. The credit only applies when that destination balance is in scope as a source — pinning `sourceAssets` or `sourceChains` away from the destination chain excludes it, and then this amount is delivered in full on top of whatever is already there. Same-chain intents always have the destination balance in scope, so they always credit.",
                           "example": "1000000"
                         },
                         "balance": {
@@ -9202,7 +9202,7 @@
                         "tokenAddress"
                       ]
                     },
-                    "description": "A list of token requested on the target chain"
+                    "description": "A list of tokens requested on the target chain. Note `amount` may be credited against a balance already held on the destination chain — see the field for exactly when."
                   },
                   "account": {
                     "type": "object",
@@ -9806,7 +9806,7 @@
                             "type": "integer",
                             "minimum": 0,
                             "maximum": 10000,
-                            "description": "App fee rate in basis points of the input value (0–10000 = 0–100%).",
+                            "description": "App fee rate in basis points (0–10000 = 0–100%). The base is the USD value of the intent, and which value depends on the intent shape: for a fixed-output intent it is the requested destination target(s), summed across `tokenRequests`; for a max-out intent it is the spendable source balance; for a destination-swap intent it is the swap input. Note the fixed-output base is the full requested target, not the delta over any balance already held.",
                             "example": 25
                           }
                         },
@@ -9821,7 +9821,7 @@
                             "type": "integer",
                             "minimum": 0,
                             "maximum": 10000,
-                            "description": "Rhinestone protocol fee rate in basis points of the input value (0–10000 = 0–100%). Collected alongside the app fee in one batched transfer and always accrues to Rhinestone; sponsor it via `sponsorSettings.protocolFees` to charge the integrator balance instead of the user.",
+                            "description": "Rhinestone protocol fee rate in basis points (0–10000 = 0–100%), on the same base as `appFees.feeBps` — see that field. Collected alongside the app fee in one batched transfer and always accrues to Rhinestone; sponsor it via `sponsorSettings.protocolFees` to charge the integrator balance instead of the user.",
                             "example": 35
                           }
                         },