@uipath/skills 1.195.0

package/skills/uipath-api-workflow/references/control-flow-patterns.md

@@ -0,0 +1,265 @@
+# Control Flow Patterns
+
+Hierarchical structures combining If, ForEach, DoWhile, Break, and TryCatch. Use this reference when authoring workflows whose logic goes more than one level deep.
+
+For per-activity field-level details (required fields, export patterns, minimal JSON), see [task-types.md](task-types.md). This document focuses on **how to combine them**.
+
+## Core Structural Rules
+
+1. **Every key in the workflow must be globally unique.** This includes wrapper / branch / body suffixes. Two `If_1#Then` blocks anywhere in the workflow — even at totally different nesting levels — is invalid. Increment the number suffix when you reuse a pattern.
+2. **Wrapper / Body suffixes are part of the key.** `If_1#Wrapper`, `If_1#Then`, `If_1#Else`, `For_Each_1#Body`, `Do_While_1#Body` are FOUR separate keys (or five for If). All five count toward uniqueness.
+3. **`then: "exit"` exits the immediately enclosing container** (the If's branch, the Sequence, etc.) — it's a "stop processing this list" signal, not a workflow terminator.
+4. **`then: "end"` terminates the entire workflow run.** Only Response activities use it.
+5. **Break exits only the innermost enclosing loop.** To exit multiple loops, use a flag variable + a check + another Break.
+6. **`#Wrapper` and `#Body` are not interchangeable.** If's wrapper is `#Wrapper`. ForEach/DoWhile body is `#Body`. There is no `#Body` for If, and no `#Wrapper` for loops.
+7. **Loop iteration variables (`for.each` / `for.at`) are scoped to that loop's body** AND get a literal `$` prefix when referenced. `for.each: "currentItem"` → reference as `$currentItem` (with the `$` character in the identifier name). Same for `for.at: "currentItemIndex"` → `$currentItemIndex`, and `catch.as: "error"` → `$error`. Nested loops MUST use distinct names — `outerItem` / `outerIndex` for the outer, `innerItem` / `innerIndex` for the inner (referenced as `$outerItem` / `$innerItem` in expressions).
+
+## Key Numbering Convention
+
+When you nest, increment numbers monotonically across the whole workflow — don't restart per scope.
+
+```
+Sequence_1
+├─ Assign_1
+├─ For_Each_1
+│   └─ For_Each_1#Body
+│       ├─ If_1#Wrapper        ← inside the loop body, but uses _1 because no other If yet
+│       │   ├─ If_1
+│       │   ├─ If_1#Then
+│       │   └─ If_1#Else
+│       └─ Try_Catch_1         ← _1 because no other TryCatch yet
+└─ If_2#Wrapper                ← _2 because If_1 was already used inside the loop
+    ├─ If_2
+    ├─ If_2#Then
+    └─ If_2#Else
+```
+
+The numbering reflects **author order across the whole workflow**, not nesting depth.
+
+## Pattern Catalog
+
+### 1. Nested If (multi-level decision tree)
+
+When you have decisions inside decisions. Each If gets its own wrapper/then/else suffix set.
+
+```
+Sequence_1
+└─ If_1#Wrapper                         (outer: amount > 1000?)
+    ├─ If_1
+    ├─ If_1#Then
+    │   └─ If_2#Wrapper                 (inner: priority === 'high'?)
+    │       ├─ If_2
+    │       ├─ If_2#Then  → [Assign tier=PLATINUM]
+    │       └─ If_2#Else  → [Assign tier=GOLD]
+    └─ If_1#Else
+        └─ Assign tier=STANDARD
+```
+
+The inner If is a child of `If_1#Then.do[]`. Its `If_2#Then` and `If_2#Else` are siblings of `If_2`. **All five suffixes are unique keys.**
+
+```json
+{
+  "If_1#Then": {
+    "do": [
+      {
+        "If_2#Wrapper": {
+          "do": [
+            { "If_2": { "switch": [
+                { "case": { "when": "${$context.variables.priority === 'high'}", "then": "If_2#Then" } },
+                { "default": { "then": "If_2#Else" } }
+              ], "metadata": { "displayName": "If" } } },
+            { "If_2#Then": { "do": [ /* tier=PLATINUM */ ], "then": "exit" } },
+            { "If_2#Else": { "do": [ /* tier=GOLD */ ], "then": "exit" } }
+          ],
+          "export": { "as": "{ ...$context, outputs: { ...$context?.outputs, \"If_2\": $output } }" },
+          "metadata": { "activityType": "If", "displayName": "If", "fullName": "If" }
+        }
+      }
+    ],
+    "then": "exit"
+  }
+}
+```
+
+### 2. Multi-way branching (3+ outcomes)
+
+The cleanest authorings is **a chain of two-way Ifs**. Each If's `#Else` contains the next If.
+
+```
+If_1#Wrapper        (x > 100?)
+├─ If_1#Then  → [tier=PLATINUM]
+└─ If_1#Else
+    └─ If_2#Wrapper (x > 50?)
+        ├─ If_2#Then  → [tier=GOLD]
+        └─ If_2#Else
+            └─ If_3#Wrapper (x > 0?)
+                ├─ If_3#Then  → [tier=STANDARD]
+                └─ If_3#Else  → [tier=NONE]
+```
+
+Why chain rather than packing many cases into one switch: StudioWeb's designer renders two-way If cards cleanly; multi-case switches render less predictably.
+
+### 3. ForEach with per-iteration If (filter / classify)
+
+Common pattern: iterate, decide per item, do something different per branch.
+
+```
+For_Each_1
+└─ For_Each_1#Body
+    ├─ If_1#Wrapper          ($currentItem.priority === 'high'?)
+    │   ├─ If_1#Then  → [Assign highCount = highCount + 1]
+    │   └─ If_1#Else  → [Assign lowCount = lowCount + 1]
+    └─ Javascript_1          (transform $currentItem and accumulate)
+```
+
+Inside `If_1`'s `when`, use `$currentItem` (with the `$` literal prefix — NOT `currentItem`, NOT `$context.variables.currentItem`):
+
+```json
+"when": "${$currentItem.priority === 'high'}"
+```
+
+### 4. ForEach inside ForEach (nested iteration)
+
+Outer and inner loops MUST use distinct iterator/index names — either semantic (`outerItem` / `innerItem`, `customer` / `order`) or incremental (`item1` / `item2`, `currentItem` / `currentItem2`). The constraint is "not the same string", not "different concepts".
+
+```
+For_Each_1 (each: outerItem, in: $workflow.input.matrix, at: outerIdx)
+└─ For_Each_1#Body
+    └─ For_Each_2 (each: innerItem, in: ${$outerItem.children}, at: innerIdx)
+        └─ For_Each_2#Body
+            └─ Javascript_1   (sees $outerItem, $innerItem, $outerIdx, $innerIdx as globals)
+```
+
+The inner loop's `for.in` reads from the outer iterator: `"${$outerItem.children}"`. Both `$outerItem` and `$innerItem` are globals available inside the inner body.
+
+### 5. Conditional Break inside a loop
+
+Break must be wrapped in an If — there's no "break when" condition on Break itself.
+
+```
+For_Each_1#Body
+├─ Javascript_1   (process $currentItem)
+└─ If_1#Wrapper   (some stop condition?)
+    ├─ If_1#Then  → [Break_1]
+    └─ If_1#Else  → []
+```
+
+The Break exits the *innermost* loop. To break out of TWO nested loops:
+
+```
+For_Each_1 (outer)
+└─ For_Each_1#Body
+    ├─ For_Each_2 (inner)
+    │   └─ For_Each_2#Body
+    │       └─ If_1#Wrapper
+    │           ├─ If_1#Then → [Assign abortFlag = true, Break_1]   ← exits inner only
+    │           └─ If_1#Else → []
+    └─ If_2#Wrapper                                                 ← after inner loop
+        ├─ If_2 (when: ${$context.variables.abortFlag})
+        ├─ If_2#Then  → [Break_2]                                   ← exits outer
+        └─ If_2#Else  → []
+```
+
+`abortFlag` must be a workflow variable so it persists across iteration boundaries.
+
+### 6. TryCatch around a loop (whole-batch error handling)
+
+If any iteration throws, the whole loop aborts and execution jumps to `catch.do`. Use when one bad item should kill the batch.
+
+```
+Try_Catch_1
+├─ try:
+│   └─ For_Each_1
+│       └─ For_Each_1#Body
+│           └─ Javascript_1   (might throw)
+└─ catch (as: error):
+    └─ Assign  errorMsg = ${$error.title}, status = "batch-failed"
+```
+
+### 7. TryCatch inside a loop body (skip-and-continue error handling)
+
+Each iteration has its own try/catch. A failure in one iteration is caught locally; the loop continues to the next iteration. **More common in practice than pattern 6.**
+
+```
+For_Each_1
+└─ For_Each_1#Body
+    └─ Try_Catch_1
+        ├─ try:
+        │   └─ Javascript_1   (might throw)
+        └─ catch (as: error):
+            └─ Assign  failedItems = failedItems + 1
+```
+
+The TryCatch's number suffix (`Try_Catch_1`) is fine inside the body even though the body runs N times — keys are checked structurally, not per-iteration. Each iteration sees the same key.
+
+### 8. DoWhile with mid-body Break
+
+Use a DoWhile when the iteration count depends on per-iteration logic, not a precomputed array. Add a Break for early exit.
+
+```
+Do_While_1                       (doWhile: ${$context.variables.attempts < maxAttempts && !$context.variables.found})
+└─ Do_While_1#Body
+    ├─ Javascript_1              (does some probe; sets $output)
+    ├─ Assign  attempts = attempts + 1
+    └─ If_1#Wrapper              (success?)
+        ├─ If_1#Then  → [Assign found = true, Break_1]
+        └─ If_1#Else  → []
+```
+
+The `doWhile` condition is evaluated AFTER each iteration. The body always runs at least once. The Break takes effect immediately — the `doWhile` re-evaluation is skipped.
+
+### 9. TryCatch inside If branch
+
+Handle a risky operation that's only attempted on certain conditions.
+
+```
+If_1#Wrapper                     (should we attempt the risky op?)
+├─ If_1#Then
+│   └─ Try_Catch_1
+│       ├─ try:  → [Javascript_1 risky]
+│       └─ catch (as: e):
+│           └─ Assign  status = "failed-with-fallback"
+└─ If_1#Else
+    └─ Assign  status = "skipped"
+```
+
+### 10. Per-iteration result aggregation across nested control flow
+
+If you want a clean array of per-iteration results that includes results from inside nested Ifs, the For_Each body's standard accumulation pattern (the index-aware `results: [...]` export) handles it — the body's `$output` is whatever the last activity in the body produced.
+
+```
+For_Each_1#Body
+├─ If_1#Wrapper
+│   ├─ If_1#Then → [Javascript_1 → returns { kind: "high", ... }]
+│   └─ If_1#Else → [Javascript_2 → returns { kind: "low", ... }]
+└─ Javascript_3 → returns { ...$context.outputs.If_1, processed_at: Date.now() }
+```
+
+The body's `$output` will be `Javascript_3`'s return value (last activity wins). The accumulation pattern appends that to `For_Each_1.results`.
+
+If you want to capture the If's own output too, use `$context.outputs.If_1` (the wrapper exports under the If's number, not the branch name).
+
+## Anti-patterns
+
+- **Reusing `If_1#Then` in two different Ifs** — even at different nesting levels. Always increment.
+- **Forgetting `then: "exit"` on inner If branches** — fall-through still happens at every nesting level.
+- **Putting Break in a TryCatch's catch.do that's not inside a loop** — Break has no enclosing loop to exit.
+- **Reusing iteration variable names across nested loops** — inner loop's `currentItem` shadows the outer one. Use `outerItem` / `innerItem` or descriptive names.
+- **Using a workflow variable as a loop iterator** — the variable's value will be the LAST iteration's item after the loop ends, plus you've polluted `$context.variables`. Use `for.each` (a loop-local binding), not Assign-then-iterate.
+- **Mixing `then: "exit"` and `then: "end"`** — `exit` stops the current container; `end` terminates the workflow. Only Response uses `end`.
+- **Trying to short-circuit evaluation in the switch via `case` ordering** — first matching case wins, but ALL cases' `when` expressions are evaluated. Don't rely on side effects in earlier `when`s.
+
+## Decision Cheat Sheet
+
+| You want… | Use |
+|-----------|-----|
+| Branch on a condition | If with `#Wrapper` / `#Then` / `#Else` |
+| Three+ branches | Chain of two-way Ifs (each `#Else` holds the next If) |
+| Iterate over an array | ForEach with `for.each` / `for.in` / `for.at` |
+| Loop until a condition | DoWhile with `for.in: "${ [1] }"` and `doWhile: "${...}"` |
+| Exit a loop early | Break inside an If inside the loop's `#Body` |
+| Exit nested loops | Flag variable + Break in inner + If + Break in outer |
+| Catch errors anywhere | TryCatch — choose `around-loop` vs `inside-body` based on whether one error should kill the batch |
+| Run two activities in order | Place both inside a Sequence's `do` array — order is preserved |
+| Branch on an error type | If inside `catch.do`, switching on `${$error.title}` or `${$error.originatingTaskName}` |
+| Conditionally return early | Response inside an If's `#Then` (with `then: "end"`) |

package/skills/uipath-api-workflow/references/expressions-and-context.md

@@ -0,0 +1,269 @@
+# Expressions & Context
+
+API workflows use **JavaScript** for all expressions (`evaluate.language: "javascript"`, `evaluate.mode: "strict"`).
+
+## Available Scopes
+
+| Scope | Source | Lifetime |
+|-------|--------|----------|
+| `$workflow.input` | The workflow's input arguments (from `--input-arguments` JSON or caller). Constant for the entire run. | Workflow run |
+| `$workflow` | Workflow runtime info: `{ id, definition, input, startedAt }`. Use `$workflow.input` to read inputs. | Workflow run |
+| `$input` | The **current task's input** = the previous task's `$output`. **NOT the workflow's input arguments.** Only equals workflow input on the very first task. | Per-task |
+| `$context` | Mutable shared state: `$context.variables.<name>`, `$context.outputs.<TaskName>` | Workflow run |
+| `$output` | The current task's raw output. | This task only |
+| Loop bindings | Whatever name you set in `for.each` / `for.at`, prefixed with `$`. Examples: `for.each: "currentItem"` → `${$currentItem}`, `for.each: "customer"` → `${$customer}`, `for.at: "idx"` → `${$idx}`. The `$` is a literal character in the identifier — the unprefixed name is NOT bound. | Inside the loop body |
+| Catch binding | `${$error}` — `catch.as: "error"` binds the global as `$error` (note the `$` prefix, same convention as loop iterators). Reference fields like `${$error.title}` / `${$error.detail}` / `${$error.originatingTaskName}`. | Inside `catch.do` |
+
+> ⚠️ **Critical:** `$input` inside a JS_Invoke that runs *after* other tasks does NOT contain the workflow's input arguments — it contains the previous task's output. To read workflow inputs reliably from anywhere, use `$workflow.input.<name>`.
+
+## Expression Syntax
+
+| Form | Meaning |
+|------|---------|
+| `"plain string"` | Literal string. |
+| `"${expr}"` | Single expression — result replaces the string. |
+| `"prefix-${expr}-suffix"` | String interpolation. |
+| `"${{ key: value }}"` | Object literal expression (note: double braces). |
+
+Examples:
+```json
+"url":       "${\"https://api.example.com/users/\" + $workflow.input.userId}"
+"body":      { "name": "${$workflow.input.name}" }
+"arguments": "${{ \"$context\": $context, \"$workflow\": $workflow, \"$input\": $input }}"
+```
+
+## Expression Patterns
+
+### Variable Access
+
+```javascript
+// Read a variable
+${$context.variables.myVar}
+
+// Read with null safety
+${$context.variables?.myVar ?? "default"}
+```
+
+### Output Access
+
+```javascript
+// Read activity output
+${$context.outputs.Javascript_1}
+
+// Read nested property
+${$context.outputs.Javascript_1.totalAmount}
+
+// Read with null safety
+${$context.outputs?.Javascript_1?.items ?? []}
+```
+
+### Connector Output Access (Http kind + IntSvc kind)
+
+Connector activities (`call: "UiPath.Http"` / `call: "UiPath.IntSvc"`) wrap the response — the actual payload lives under **`.content`** (the wrapper also carries `statusCode`, `statusText`, `headers`, `ok`, `request`, `vendorProcessingTimeMs`; usually you only need `.content`). Reading at the root returns `undefined`. Use `Data.ExportBucketKey` from the stub — for connector activities the slot key (in the `do` array) and the export-bucket key (what `$context.outputs.<X>` reads as) can differ; the stub returns both.
+
+**The fields available under `.content` come from the stub's `Data.ResponseFields` array — never guess.** If a property isn't listed there, it's not in the response shape. See [connector-activity-discovery.md — Vendor curated activity response shape](connector-activity-discovery.md#vendor-curated-activity-response-shape--contentx-not-x).
+
+```javascript
+// ❌ Wrong — always undefined (root has no payload fields)
+${$context.outputs.getNewestEmail_1.subject}
+${$context.outputs.GetNewestEmail_1.content.subject}   // wrong casing too
+
+// ✅ Correct — IntSvc kind (Outlook GetNewestEmail)
+${$context.outputs.getNewestEmail_1.content.subject}
+${$context.outputs.getNewestEmail_1.content.from.emailAddress.address}
+
+// ✅ Correct — Http kind (any REST API)
+${$context.outputs.http_request_1.statusCode}    // 200
+${$context.outputs.http_request_1.content}       // parsed JSON body
+${$context.outputs.http_request_1.content.fact}  // example: top-level field
+
+// ✅ Slack Send Message / Send Reply
+${$context.outputs.slack_send_message_1.content.ok}      // true
+${$context.outputs.slack_send_message_1.content.ts}      // message timestamp
+${$context.outputs.slack_send_message_1.content.channel}
+
+// ✅ List-shaped vendor responses — .content is usually the array directly
+// (IS proxy strips vendor list envelopes like M365 Graph's { value: [...] }).
+// Read the stub's outputJsonSchema.type to confirm:
+//   type: "array"  → .content IS the array        → .content[0].<field>
+//   type: "object" → .content is a single object  → .content.<field>
+${$context.outputs.listEmails_1.content}                       // verified: bare array (Outlook ListEmails)
+${$context.outputs.listEmails_1.content?.[0]?.subject}
+${$context.outputs.listEmails_1.content?.length}
+
+// ✅ Null-safe chains for optional fields
+${$context.outputs?.getNewestEmail_1?.content?.subject ?? "(no subject)"}
+```
+
+Inside a JsInvoke script, the local CLI runtime sometimes returns `content` as a JSON string while cloud returns it pre-parsed — handle both:
+
+```javascript
+const out = $context.outputs.getNewestEmail_1;
+const raw = out && (out.content !== undefined ? out.content : out);
+const body = (typeof raw === 'string') ? JSON.parse(raw) : raw;
+const item = Array.isArray(body) ? body[0] : body;
+const subject = item?.subject ?? '';
+return { subject };
+```
+
+### Input Access
+
+```javascript
+// Read workflow input from anywhere — preferred
+${$workflow.input.fieldName}
+
+// Read task input — only equals workflow input on the very first task
+${$input.fieldName}
+```
+
+### Common Idioms
+
+```javascript
+// String concatenation
+${"Hello, " + $context.variables.name}
+
+// Ternary
+${$context.variables.count > 0 ? "has items" : "empty"}
+
+// Array length
+${$context.outputs.Javascript_1.items.length}
+
+// JSON stringify
+${JSON.stringify($context.outputs.Javascript_1)}
+
+// Type coercion
+${Number($context.variables.countStr)}
+${String($context.variables.count)}
+```
+
+## The `export.as` Pattern
+
+Each task's raw output is in `$output`. To make it available to later tasks, you must `export` it back into `$context`. Two patterns by category:
+
+| Category | Activities | Export Pattern |
+|----------|-----------|----------------|
+| **Variables** | Assign | `{ ...$context, variables: { ...$context.variables, ...$output } }` |
+| **Outputs** | Everything else (JS_Invoke, If, ForEach, DoWhile, TryCatch, Response, Wait) | `{ ...$context, outputs: { ...$context?.outputs, "ActivityKey": $output } }` |
+
+### Output key
+
+The output key in the export pattern matches the activity key as-is. Activity key `Javascript_1` → export key `"Javascript_1"`. Read it back the same way: `$context.outputs.Javascript_1`.
+
+### Without `export`
+
+If you omit `export`, the task's output disappears from context after the next task. Only `$output` (the most recent task's output) is reliably visible. Always `export` unless you specifically want the output discarded.
+
+## Reading Prior Outputs
+
+```js
+// Javascript_1 returned { tier: "GOLD", credits: 1500 }
+$context.outputs.Javascript_1.tier
+
+// Inside a JS_Invoke script — $context is a global:
+"code": "return { greeting: 'Hello ' + $context.outputs.Javascript_1.tier };"
+```
+
+## Reading Workflow Inputs
+
+```js
+// User ran: uip api-workflow run wf.json --input-arguments '{"name":"Alice","count":3}'
+
+$workflow.input.name    // "Alice"
+$workflow.input.count   // 3
+```
+
+`$workflow.input` is bound at workflow start and never changes. Use `$workflow.input.<name>` everywhere — including inside JS_Invoke, where it's also a global.
+
+If the input is missing, `$workflow.input.<name>` is `undefined`. Provide defaults via `document.metadata.variables.schema.document.properties.<name>.default` — `WorkflowStart` hydrates these into `$context.variables` automatically.
+
+## JS_Invoke Context Access
+
+Scripts read `$context`, `$workflow`, `$input` directly as globals.
+
+```js
+// Inside a JsInvoke script:
+const userName = $context.variables.userName;
+const inputArg = $workflow.input.userId;
+return { upper: userName.toUpperCase(), id: inputArg };
+```
+
+The task body's `run.script.arguments` field — the standard `"${{ \"$context\": $context, \"$workflow\": $workflow, \"$input\": $input }}"` block — is StudioWeb designer scaffolding. Keep it for designer roundtrip; the runtime ignores it.
+
+## Strict Mode Gotchas
+
+`evaluate.mode: "strict"` enforces strict JavaScript:
+
+- Accessing a property on `undefined` throws — always use optional chaining (`?.`)
+- Use `?? "default"` for null coalescing
+- Array spread on `undefined` throws — guard with `?? []`
+- `with` statements rejected
+- Duplicate property names rejected in object literals
+- Implicit globals rejected — use `const` / `let` inside scripts
+
+```js
+// Safe nested access:
+${$context.outputs?.Javascript_1?.items ?? []}
+
+// Inside ForEach over a possibly-missing array:
+"in": "${$context.outputs?.Javascript_1?.items ?? []}"
+```
+
+## Key Patterns
+
+### Globally Unique Keys
+
+Every key in the workflow must be globally unique, including suffixes:
+- Activity keys: `Assign_1`, `Javascript_1`, `Wait_1`, `Try_Catch_1`
+- Wrapper suffixes: `If_1#Wrapper`, `If_1#Then`, `If_1#Else`
+- Body suffixes: `For_Each_1#Body`, `Do_While_1#Body`
+
+When adding activities, scan existing keys to avoid collisions. Increment the number suffix.
+
+### Export Merging
+
+Exports use spread to preserve existing context while adding new data:
+```javascript
+// Preserves all existing outputs and adds/overwrites the specific activity output
+{ ...$context, outputs: { ...$context?.outputs, "ActivityKey": $output } }
+```
+
+The `?.` on `$context?.outputs` prevents errors when no outputs exist yet.
+
+### Wrapper Pattern (If)
+
+The If activity uses a wrapper because the designer needs a single container:
+1. `If_N#Wrapper` — outer container with export and metadata
+2. `If_N` — inner switch with condition logic
+3. `If_N#Then` — true branch with `then: "exit"`
+4. `If_N#Else` — false branch with `then: "exit"`
+
+`then: "exit"` on branches prevents fall-through to the next branch.
+
+### Body Pattern (Loops)
+
+ForEach and DoWhile both wrap their inner activities in a `#Body`:
+- `For_Each_N#Body` — index-aware accumulation pattern (resets `results` array on iteration 0)
+- `Do_While_N#Body` — simple accumulation pattern (no reset, since iteration count is condition-driven)
+
+See [task-types.md](task-types.md) for the exact body export expressions.
+
+### Context Chaining
+
+Activities execute sequentially. Each activity's export updates `$context`, making its output available to subsequent activities:
+
+```
+WorkflowStart       → sets $context.variables (from variable defaults)
+Assign_1            → updates $context.variables (e.g. classifies the input)
+For_Each_1          → adds $context.outputs.For_Each_1.results (per-iteration accumulation)
+Javascript_1        → adds $context.outputs.Javascript_1 (final summary computation)
+Response_1          → reads any $context data, ends workflow
+```
+
+## Anti-patterns
+
+- **Do NOT** use `$input.<name>` to read workflow inputs from non-first tasks — `$input` is the previous task's `$output`. Use `$workflow.input.<name>`.
+- **Do NOT** mutate `$context` directly inside a JS_Invoke script — return a new value and let `export.as` merge it.
+- **Do NOT** rely on `$output` two tasks later — it is overwritten by the next task. Always `export` to `$context.outputs.<TaskName>` if you need it.
+- **Do NOT** use `var` inside JS_Invoke scripts — strict mode rejects implicit globals; use `const` / `let`.
+- **Do NOT** wrap loop variable names (`each`, `at`) in `${...}` — those fields take plain identifiers.
+- **Do NOT** mix `${...}` and string concatenation when a single expression form works: prefer `"${\"prefix-\" + $workflow.input.x}"` over splitting.