Make variables action not restricted to local scopes (#38150)

source/_docs/scripts.markdown

@@ -94,9 +94,7 @@ Variables can be templated.
 
 ### Scope of variables
 
-Variables defined by the `variables` {% term action %} have local scope. This means that if a variable is changed in a nested sequence block, that change will not be visible in an outer sequence block.
-
-Inside the `if` sequence the `variables` {% term action %} will only alter the `people` variable for that sequence.
+The `variables` {% term action %} assigns the values to previously defined variables with the same name. If a variable was not previously defined, it is assigned in the top-level (script run) scope.
 
 {% raw %}
 
@@ -111,17 +109,17 @@ sequence:
         entity_id: device_tracker.paulus
         state: "home"
     then:
-      # At this scope and this point of the sequence, people == 0
       - variables:
           people: "{{ people + 1 }}"
-      # At this scope, people will now be 1 ...
+          paulus_home: true
       - action: notify.notify
         data:
           message: "There are {{ people }} people home" # "There are 1 people home"
-  # ... but at this scope it will still be 0
+  # Variable value is now updated
   - action: notify.notify
     data:
-      message: "There are {{ people }} people home" # "There are 0 people home"
+      message: "There are {{ people }} people home {% if paulus_home is defined %}(including Paulus){% endif %}"
+      # "There are 1 people home (including Paulus)"
 ```
 
 {% endraw %}
@@ -213,8 +211,8 @@ This {% term action %} evaluates the template, and if true, the script will cont
 The template is re-evaluated whenever an entity ID that it references changes state. If you use non-deterministic functions like `now()` in the template it will not be continuously re-evaluated, but only when an entity ID that is referenced is changed. If you need to periodically re-evaluate the template, reference a sensor from the [Time and Date](/integrations/time_date/) integration that will update minutely or daily.
 
 {% raw %}
-```yaml
 
+```yaml
 # Wait until media player is stopped
 - alias: "Wait until media player is stopped"
   wait_template: "{{ is_state('media_player.floor', 'stop') }}"
@@ -258,8 +256,8 @@ With both types of waits it is possible to set a timeout after which the script
 You can also get the script to abort after the timeout by using optional `continue_on_timeout: false`.
 
 {% raw %}
-```yaml
 
+```yaml
 # Wait for IFTTT event or abort after specified timeout.
 - wait_for_trigger:
     - trigger: event
@@ -322,6 +320,7 @@ This can be used to take different actions based on whether or not the condition
   target:
     entity_id: switch.some_light
 ```
+
 {% endraw %}
 
 ## Fire an event
@@ -561,6 +560,7 @@ For example:
     sequence:
       - ...
 ```
+
 {% endraw %}
 
 ### Repeat loop variable
@@ -691,7 +691,6 @@ automation:
 
 {% endraw %}
 
-
 More `choose` can be used together. This is the case of an IF-IF.
 
 The following example shows how a single {% term automation %} can control entities that aren't related to each other but have in common the same trigger.
@@ -856,10 +855,8 @@ Some of the caveats of running {% term actions %} in parallel:
   there is no guarantee that they will be completed in the same order.
 - If one {% term action %} fails or errors, the other {% term actions %} will keep running until
   they too have finished or errored.
-- Variables created/modified in one parallelized {% term action %} are not available
-  in another parallelized {% term action %}. Each step in a parallelized has its own scope.
-- The response data of a parallelized {% term action %} is however also available outside of its
-  own scope. This is especially useful for parallelizing execution of long-running {% term actions %}. 
+- Variables created/modified in one parallelized {% term action %} can conflict with variables
+  from another parallelized {% term action %}. Make sure to give them distinct names to prevent that.
 
 ## Stopping a script sequence