improvement(docs): loop and parallel var reference syntax (#2975)

Author: icecrasher321

apps/docs/content/docs/en/blocks/loop.mdx

@@ -124,11 +124,44 @@ Choose between four types of loops:
 3. Drag other blocks inside the loop container
 4. Connect the blocks as needed
 
-### Accessing Results
+### Referencing Loop Data
 
-After a loop completes, you can access aggregated results:
+There's an important distinction between referencing loop data from **inside** vs **outside** the loop:
 
-- **`<loop.results>`**: Array of results from all loop iterations
+<Tabs items={['Inside the Loop', 'Outside the Loop']}>
+  <Tab>
+    **Inside the loop**, use `<loop.>` references to access the current iteration context:
+    
+    - **`<loop.index>`**: Current iteration number (0-based)
+    - **`<loop.currentItem>`**: Current item being processed (forEach only)
+    - **`<loop.items>`**: Full collection being iterated (forEach only)
+    
+    ```
+    // Inside a Function block within the loop
+    const idx = <loop.index>;           // 0, 1, 2, ...
+    const item = <loop.currentItem>;    // Current item
+    ```
+    
+    <Callout type="info">
+      These references are only available for blocks **inside** the loop container. They give you access to the current iteration's context.
+    </Callout>
+  </Tab>
+  <Tab>
+    **Outside the loop** (after it completes), reference the loop block by its name to access aggregated results:
+    
+    - **`<LoopBlockName.results>`**: Array of results from all iterations
+    
+    ```
+    // If your loop block is named "Process Items"
+    const allResults = <processitems.results>;
+    // Returns: [result1, result2, result3, ...]
+    ```
+    
+    <Callout type="info">
+      After the loop completes, use the loop's block name (not `loop.`) to access the collected results. The block name is normalized (lowercase, no spaces).
+    </Callout>
+  </Tab>
+</Tabs>
 
 ## Example Use Cases
 
@@ -184,28 +217,29 @@ Variables (i=0) → Loop (While i<10) → Agent (Process) → Variables (i++)
     </ul>
   </Tab>
   <Tab>
+    Available **inside** the loop only:
     <ul className="list-disc space-y-2 pl-6">
       <li>
-        <strong>loop.currentItem</strong>: Current item being processed
+        <strong>{"<loop.index>"}</strong>: Current iteration number (0-based)
       </li>
       <li>
-        <strong>loop.index</strong>: Current iteration number (0-based)
+        <strong>{"<loop.currentItem>"}</strong>: Current item being processed (forEach only)
       </li>
       <li>
-        <strong>loop.items</strong>: Full collection (forEach loops)
+        <strong>{"<loop.items>"}</strong>: Full collection (forEach only)
       </li>
     </ul>
   </Tab>
   <Tab>
     <ul className="list-disc space-y-2 pl-6">
       <li>
-        <strong>loop.results</strong>: Array of all iteration results
+        <strong>{"<blockname.results>"}</strong>: Array of all iteration results (accessed via block name)
       </li>
       <li>
         <strong>Structure</strong>: Results maintain iteration order
       </li>
       <li>
-        <strong>Access</strong>: Available in blocks after the loop
+        <strong>Access</strong>: Available in blocks after the loop completes
       </li>
     </ul>
   </Tab>

apps/docs/content/docs/en/blocks/parallel.mdx

@@ -76,11 +76,44 @@ Choose between two types of parallel execution:
 3. Drag a single block inside the parallel container
 4. Connect the block as needed
 
-### Accessing Results
+### Referencing Parallel Data
 
-After a parallel block completes, you can access aggregated results:
+There's an important distinction between referencing parallel data from **inside** vs **outside** the parallel block:
 
-- **`<parallel.results>`**: Array of results from all parallel instances
+<Tabs items={['Inside the Parallel', 'Outside the Parallel']}>
+  <Tab>
+    **Inside the parallel**, use `<parallel.>` references to access the current instance context:
+    
+    - **`<parallel.index>`**: Current instance number (0-based)
+    - **`<parallel.currentItem>`**: Item for this instance (collection-based only)
+    - **`<parallel.items>`**: Full collection being distributed (collection-based only)
+    
+    ```
+    // Inside a Function block within the parallel
+    const idx = <parallel.index>;           // 0, 1, 2, ...
+    const item = <parallel.currentItem>;    // This instance's item
+    ```
+    
+    <Callout type="info">
+      These references are only available for blocks **inside** the parallel container. They give you access to the current instance's context.
+    </Callout>
+  </Tab>
+  <Tab>
+    **Outside the parallel** (after it completes), reference the parallel block by its name to access aggregated results:
+    
+    - **`<ParallelBlockName.results>`**: Array of results from all instances
+    
+    ```
+    // If your parallel block is named "Process Tasks"
+    const allResults = <processtasks.results>;
+    // Returns: [result1, result2, result3, ...]
+    ```
+    
+    <Callout type="info">
+      After the parallel completes, use the parallel's block name (not `parallel.`) to access the collected results. The block name is normalized (lowercase, no spaces).
+    </Callout>
+  </Tab>
+</Tabs>
 
 ## Example Use Cases
 
@@ -98,11 +131,11 @@ Parallel (["gpt-4o", "claude-3.7-sonnet", "gemini-2.5-pro"]) → Agent → Evalu
 
 ### Result Aggregation
 
-Results from all parallel instances are automatically collected:
+Results from all parallel instances are automatically collected and accessible via the block name:
 
 ```javascript
-// In a Function block after the parallel
-const allResults = input.parallel.results;
+// In a Function block after a parallel named "Process Tasks"
+const allResults = <processtasks.results>;
 // Returns: [result1, result2, result3, ...]
 ```
 
@@ -158,25 +191,26 @@ Understanding when to use each:
     </ul>
   </Tab>
   <Tab>
+    Available **inside** the parallel only:
     <ul className="list-disc space-y-2 pl-6">
       <li>
-        <strong>parallel.currentItem</strong>: Item for this instance
+        <strong>{"<parallel.index>"}</strong>: Instance number (0-based)
       </li>
       <li>
-        <strong>parallel.index</strong>: Instance number (0-based)
+        <strong>{"<parallel.currentItem>"}</strong>: Item for this instance (collection-based only)
       </li>
       <li>
-        <strong>parallel.items</strong>: Full collection (collection-based)
+        <strong>{"<parallel.items>"}</strong>: Full collection (collection-based only)
       </li>
     </ul>
   </Tab>
   <Tab>
     <ul className="list-disc space-y-2 pl-6">
       <li>
-        <strong>parallel.results</strong>: Array of all instance results
+        <strong>{"<blockname.results>"}</strong>: Array of all instance results (accessed via block name)
       </li>
       <li>
-        <strong>Access</strong>: Available in blocks after the parallel
+        <strong>Access</strong>: Available in blocks after the parallel completes
       </li>
     </ul>
   </Tab>