@uipath/skills 1.195.0

package/skills/uipath-maestro-bpmn/references/operate/references/ship.md

@@ -0,0 +1,119 @@
+# Ship - Package, upload, publish, and deploy
+
+Use this journey to package, upload, publish, or deploy a BPMN Process Orchestration project.
+Shipping is the handoff from model-authored BPMN source to CLI-owned package metadata and cloud lifecycle.
+
+> **Target rule:** if the user says "publish" without specifying a target, default to Studio Web upload.
+> Use Orchestrator deployment only when the user explicitly asks for Orchestrator deployment or a deployed process.
+
+## Pre-flight
+
+Before upload, publish, deploy, or debug:
+
+1. Confirm the user wants a cloud-side action and identify the target: Studio Web upload, package only,
+   or Orchestrator deployment.
+2. Confirm local Author validation has run for XML parse, diagram presence, entry points, bindings,
+   and package consistency.
+3. Confirm Integration Service enrichment is complete for executable connector elements.
+   If enrichment tooling is unavailable, keep the project as a draft and do not operate it as executable.
+4. Regenerate or refresh package metadata with the supported CLI path.
+   Treat `bindings_v2.json`, `entry-points.json`, `operate.json`, and `package-descriptor.json` as derived unless a
+   CLI contract says otherwise. Use
+   [local-metadata-regeneration-guide.md](../../shared/local-metadata-regeneration-guide.md) for the local drift
+   checks that connect BPMN source, entry points, bindings, and `Intsvc.*` payload enrichment.
+   When the BPMN references external Orchestrator processes, `uip solution
+   resource refresh` expects a versioned `bindings_v2.json` object with a
+   `resources` array. Process resources should be generated or fixture-backed
+   entries with `id`, `kind`, `name`, `resourceKey`, `metadata`, `resource`,
+   `resourceSubType`, and `propertyAttribute` for name/folder-path pairs, not
+   an unwrapped array or unversioned placeholder.
+5. Confirm login for cloud actions:
+
+   ```bash
+   uip login status --output json
+   ```
+
+6. Inspect generated files for public-safety issues before committing or sharing.
+   Do not include tenant URLs, folder keys, connection IDs, user data, payloads, or local paths in docs or commits.
+
+## Package only
+
+Package when the user wants a local `.nupkg`, pre-deploy artifact, or package-shape verification:
+
+```bash
+uip maestro bpmn pack <project-path> <OutputDir> --output json
+```
+
+Use `--name` and `--version` only when the user provides a public-safe package identity.
+Report the package path and package identity returned by the CLI.
+If packing changes generated files, explain whether the change came from BPMN source, CLI enrichment,
+or package generation.
+
+## Studio Web upload
+
+Use Studio Web upload when the user says publish without specifying Orchestrator deployment.
+Studio Web upload lets the user inspect and edit the BPMN project in the browser.
+
+```bash
+uip solution upload <SolutionDir> --output json
+```
+
+If the solution has resource declarations, refresh them with the supported solution tooling in the local CLI.
+Do not invent a `solution resource` command path; verify the installed CLI help before documenting a refresh step.
+When the project declares resource dependencies, verify that refresh produced
+matching generated resource files and debug overwrite metadata. An empty
+`resources` array is valid only for projects with no generated dependencies.
+
+Report the Studio Web URL or solution ID when the CLI returns one.
+If the upload succeeds but returns no URL, say `<not returned by CLI>` instead of omitting the field.
+
+## Orchestrator deployment
+
+Only deploy to Orchestrator when the user explicitly asks for deployment.
+Confirm package identity, target folder/context, feed/package expectations, and runtime expectations before publishing.
+
+Typical path:
+
+```bash
+uip maestro bpmn pack <project-path> <OutputDir> --output json
+uip solution pack <SolutionDir> <OutputDir> --output json
+uip solution publish <PackageZip> --output json
+```
+
+Deployment and activation are platform lifecycle concerns.
+Use the platform workflow for `uip solution deploy ...` commands and keep this BPMN skill focused on the
+BPMN project/package boundary.
+
+## Import/package correlation
+
+When Studio Web import or packaging fails, inspect the generated package files against
+[shared/project-layout.md](../../shared/project-layout.md):
+
+- `bindings_v2.json` for resource and connection binding declarations generated from BPMN/enrichment.
+- `entry-points.json` for start-event entry points, schemas, and BPMN file references.
+- `operate.json` for runtime/package metadata and the intended main BPMN file.
+- `package-descriptor.json` for content manifest entries under `content/`.
+
+If the mismatch comes from process modeling, fix `.bpmn` in Author.
+If it comes from connector metadata or generated resources, rerun CLI enrichment/generation.
+Do not hand-patch generated files as the primary fix.
+
+## Failure handling
+
+If package or upload fails:
+
+- Capture the high-level error category.
+- Check generated package files against [shared/project-layout.md](../../shared/project-layout.md).
+- Correlate import errors to BPMN diagrams, start events, entry point IDs, bindings, and package descriptor entries.
+- Return to Author for BPMN/source fixes.
+- Rerun CLI enrichment/generation for CLI-owned Integration Service or generated-file issues.
+- Use Diagnose only after a process has actually run or faulted in the runtime.
+
+## Anti-patterns
+
+- **Never deploy to Orchestrator just because the user said "publish."** Studio Web upload is the default.
+- **Never upload an executable process with draft Integration Service intent.** Enrichment must resolve connector metadata,
+  connection binding, dynamic schemas, and generated resources first.
+- **Never fix a packaging error by editing generated JSON alone.** Fix BPMN source or rerun the CLI-owned
+  generation/enrichment path.
+- **Never include real tenant, folder, package feed, or connection values in examples or summaries.**

package/skills/uipath-maestro-bpmn/references/shared/bpmn-xml-contract.md

@@ -0,0 +1,197 @@
+# BPMN XML Contract
+
+This document summarizes the public-safe authoring boundary for Maestro BPMN XML. It intentionally avoids raw exported BPMN, tenant data, connection identifiers, private names, URLs, or local paths.
+
+## Baseline document
+
+Generated BPMN must be valid BPMN 2.0 with the UiPath extension namespace.
+
+- `bpmn:definitions` includes standard BPMN, BPMNDI, DI, DC, and the UiPath namespace.
+- The UiPath namespace URI is `http://uipath.org/schema/bpmn` and the preferred prefix is `uipath`.
+- Do not declare `uipath` as `http://schemas.uipath.com/workflow/activities` in
+  Maestro BPMN files.
+- Use one executable root process by default. Use collaboration/pools only when the user explicitly asks for that model.
+- Studio Web import requires at least one valid `bpmndi:BPMNDiagram` with a `bpmndi:BPMNPlane`.
+- Every visible flow node should have a `bpmndi:BPMNShape` with bounds.
+- Every visible edge should have a `bpmndi:BPMNEdge` with waypoints.
+- Conditions and scripts should use a leading `=` where Maestro expects expressions.
+- UiPath extension expressions should read BPMN variables through `vars.<variableId>`,
+  for example `=vars.Var_RequestId`, rather than bare names.
+- For lint-sensitive expression details, see [expression-authoring.md](expression-authoring.md).
+- CDATA is the expected representation for JSON bodies, schemas, scripts, variable schemas, custom output bodies, and case-management payload bodies.
+- XML comments must remain parseable. Do not put `--` inside comments, and do
+  not use dashed decorative separator lines in BPMN XML comments.
+
+## Supported model-authored BPMN
+
+For the supported element map and UiPath extension wrapper table, see [author/supported-elements.md](../author/references/supported-elements.md).
+
+The model may directly author standard BPMN structure when user intent is clear.
+Anything listed in
+[Current generation exclusions](../author/references/supported-elements.md#current-generation-exclusions)
+is preserve-only for imported files and must not be generated in new source.
+
+- Events: start, end, boundary, intermediate catch, and intermediate throw events.
+- Event definitions: none, timer, message, error, and terminate end events where supported by the runtime path.
+- Gateways: exclusive, inclusive, parallel, and event-based gateways.
+- Tasks and activities: task, service task, send task, receive task, user task, business rule task, script task, and call activity.
+- Containers: subprocess and supported event subprocesses. Expanded subprocesses need a second diagram when nested content must render in Studio Web.
+- Flow and annotation elements: sequence flow, message flow, association, data input/output association, group, text annotation, categories, messages, errors, data stores, item definitions, and resources.
+- Loop markers: documented multi-instance parallel or sequential loop metadata. UiPath collection/element metadata belongs under the loop characteristic extension elements.
+
+Conservative defaults:
+
+- Start with one root process and one blank start event unless the process needs a trigger entry point.
+- Use sequence flows for routing inside one process.
+- Put gateway conditions on outgoing sequence flows and set a default flow where appropriate.
+- Attach boundary error events to activities and reference valid error definitions.
+- Give event subprocesses exactly one start event.
+- Avoid sequence flows that cross subprocess scope or pool boundaries.
+
+## Two-pass authoring boundary
+
+For non-trivial authoring, split generation into two passes:
+
+- **Pass 1: BPMN skeleton** - author standard BPMN process structure, event definitions, gateway conditions, subprocess scopes, sequence/message flows, annotations, and BPMN DI. Use placeholder labels or annotations for resource intent. Keep gateway conditions business-readable; do not use Maestro runtime expressions such as `=vars.<variableId>` until pass 2 declares those variables. Preserve existing extension XML in brownfield files.
+- **Operator confirmation** - confirm the process shape before filling execution-specific XML.
+- **Pass 2: model-owned UiPath XML** - add root variables, entry point IDs, mappings, documented bindings, script metadata, retry/error metadata, loop metadata, and documented service shells from [wrapper-shells.md](wrapper-shells.md).
+- **CLI enrichment** - generate or enrich Integration Service activity/trigger payloads, connector bindings, dynamic schemas, and generated package files.
+
+Do not combine connector selection, connection binding, dynamic schema generation, and topology rewrites in one opaque edit.
+
+## Executable contract boundary
+
+The current confirmed generation boundary is preserve/model-shell only for areas whose runtime contract depends on tenant state, registry metadata, or non-BPMN subscriptions. Do not add generation guidance that creates executable payloads for those areas until the contract is fixture-backed and CLI-validated.
+
+- Signals: do not generate new signal definitions or signal event definitions.
+  Preserve imported signal XML and report it as unsupported for regeneration
+  unless a current product contract and local validation prove support.
+- Plain connectionless HTTP: after skeleton confirmation, model authors may use
+  the documented [HTTP request recipe](../author/references/task-recipes/http-request.md)
+  when the workflow owns the URL, method, payload, and parsing, and no
+  connector connection or dynamic connector schema is needed.
+- Integration Service: model authors may create the surrounding BPMN node and
+  document connector intent. They may also create a non-executable draft
+  `Intsvc.*` shell with `uipath:type value="Intsvc.<Variant>"` and placeholder
+  strings. Except for the documented pass-2 plain connectionless HTTP recipe,
+  executable `Intsvc.*` activity/event XML, connection bindings, connector
+  metadata, trigger property bindings, filters, parameters, and dynamic schemas
+  require live registry-backed CLI enrichment for the target tenant before
+  upload, debug, publish, or deploy.
+- Brownfield files: preserve imported signal or Integration Service extension XML unless the user explicitly asks for normalization and the CLI can validate the replacement.
+
+## UiPath extensions the model may write
+
+Use lower-case XML aliases in examples and authoring guidance:
+
+- Root `uipath:variables version="v1"` with input, input/output, and output variables.
+- Root `uipath:bindings version="v1"` for placeholder-safe resource bindings when the binding contract is documented.
+- Root-level start event `uipath:entryPointId value="..."` for runnable entry points.
+- `uipath:mapping version="v1"` for `BPMN.Variables` mappings.
+- `uipath:scriptVersion value="..."` for script task metadata. Prefer `v3` for new script tasks; preserve imported `v2` metadata unless the user explicitly migrates it.
+- `uipath:migrationVersion version="..."` as import migration metadata to preserve, including numeric values such as `5`, `11`, and `11.5`.
+- `uipath:loopCharacteristics inputCollection="..." inputElement="..."` under loop characteristic extensions.
+- `uipath:retry`, `uipath:errorMapping`, and `uipath:tags` when the user gives explicit public-safe metadata. For retry, boundary errors, event subprocesses, and error mapping shapes, see [error-handling.md](error-handling.md).
+- `uipath:activity` and `uipath:event` shells for documented non-Integration-Service service types.
+
+New authored `uipath:activity` and `uipath:event` shells use the canonical
+nested type element:
+
+```xml
+<uipath:activity version="v1">
+  <uipath:type value="Orchestrator.StartJob" version="v1" />
+</uipath:activity>
+```
+
+Do not use legacy shorthand such as `<uipath:activity type="...">` in new XML.
+For task payloads, keep the wrapper type and resource context in
+`uipath:activity`; put variable inputs and outputs in a sibling
+`uipath:mapping version="v1"` element whose `var` attributes target declared
+variable ids.
+
+For new root variables, use `uipath:input`, `uipath:inputOutput`, and
+`uipath:output` children. Do not author generic `uipath:variable
+direction="..."` entries in new source; preserve imported instances only when
+normalizing the file is out of scope.
+
+Do not invent `uipath:caseManagement` payloads without a dedicated case-management contract. Preserve imported `uipath:caseManagement` and unknown generic `uipath:Activity` payloads unless the edit explicitly normalizes them.
+
+## Non-Integration-Service task shells
+
+> Copyable minimal XML shell per wrapper: [wrapper-shells.md](wrapper-shells.md).
+
+The model may author placeholder-safe shells for documented non-Integration-Service task types when it has enough user intent and no private identifiers are embedded. Choose the BPMN wrapper first:
+
+- `BPMN.Variables`
+- `BPMN.ScriptTask` as `bpmn:scriptTask` with script CDATA, `uipath:scriptVersion`, and mapping metadata.
+- `Actions.HITL` as `bpmn:userTask`.
+- `Orchestrator.StartJob`, `Orchestrator.StartAgentJob`, `Orchestrator.ExecuteApiWorkflowAsync`, `Orchestrator.CreateAndWaitForQueueItem`, and `A2A.AgentExecution` as `bpmn:serviceTask`.
+- `Orchestrator.CreateQueueItem` as `bpmn:sendTask`.
+- `Orchestrator.BusinessRules` as `bpmn:businessRuleTask`.
+- `Orchestrator.StartAgenticProcess`, `Orchestrator.StartAgenticProcessAsync`, `Orchestrator.StartCaseMgmtProcess`, and `Orchestrator.StartCaseMgmtProcessAsync` as `bpmn:callActivity`.
+- `Maestro.ReceiveMessageEvent` and `Maestro.SendMessageEvent` as message event wrappers.
+- `Maestro.CasePlanScheduler` only when a dedicated case-management contract is available; otherwise preserve imported XML.
+
+Keep resource identity fields synthetic or placeholder-based until CLI or user-provided public-safe data resolves them.
+
+For copyable minimal XML shells, read [wrapper-shells.md](wrapper-shells.md)
+before authoring a task wrapper.
+
+### Script-task body rule
+
+A `<bpmn:script>` body on `bpmn:scriptTask` is only valid when the task also
+carries UiPath script metadata. `uip maestro bpmn validate` accepts the body
+when **at least one** of these extension elements is present inside
+`<bpmn:extensionElements>`:
+
+- `<uipath:scriptVersion value="v3" />` (preferred for new tasks; `v2` is
+  preserve-only on imports)
+- `<uipath:mapping>` containing `<uipath:type value="BPMN.ScriptTask" version="v1" />`
+- `<uipath:mapping>` containing `<uipath:type value="BPMN.Variables" version="v1" />`
+
+Without one of those, the validator rejects the body. If the task does not
+need to execute JavaScript, drop the `<bpmn:script>` and express the logic as
+a `BPMN.Variables` output mapping on a generic `bpmn:task`, or as a condition
+on a downstream gateway.
+
+## CLI-owned or CLI-enriched areas
+
+The CLI must generate, enrich, or validate these before upload, debug, publish, or deploy:
+
+- Integration Service activity operation metadata.
+- Integration Service trigger metadata and trigger property bindings.
+- Connection binding resources and connector metadata.
+- Dynamic input/output schemas for connectors, event triggers, unified HTTP, external agents, external workflows, API workflows, and generated outputs.
+- `bindings_v2.json`, including deduped resources and metadata.
+- `entry-points.json`, including schema extraction from root variables and entry point file wiring.
+- `operate.json`, including project ID, main file, content type, target framework, and runtime options.
+- `package-descriptor.json`, including manifest entries for BPMN and generated JSON.
+- Package identifiers and final package paths.
+- XML parse validation with the UiPath moddle descriptor.
+- Maestro validation parity for connections, gateways, start events, subprocess crossing, boundary errors, required fields, assignment-free expressions, variables, and resource references.
+- Project scaffolding and canonical BPMN filename selection.
+
+## Validation expectations
+
+Validation should report:
+
+- XML parse errors.
+- Missing or orphaned BPMN diagrams.
+- Missing shape/edge geometry for rendered elements.
+- Invalid root variables, bindings, migration metadata, or UiPath transaction-root markers.
+- Duplicate or invalid entry point IDs.
+- Entry point variables whose `elementId` does not match the start event.
+- Context binding expressions that do not resolve to root bindings.
+- Missing required service-type context/input fields.
+- Illegal sequence-flow or message-flow connections.
+- Gateway split/default-flow issues.
+- Multiple blank starts in a single scope.
+- Invalid event subprocess starts.
+- Invalid or duplicate error references.
+- Expressions with assignment operators in fields that require read-only expression evaluation.
+- Output references that do not match root or scoped variables.
+- Unresolved solution resources when validating inside a solution context.
+
+## Migration behavior
+
+Prefer current extension shapes instead of relying on import migrations. Preserve existing `uipath:migrationVersion` values, including numeric values like `5`, `11`, and `11.5`, and preserve unknown extension payloads such as generic `uipath:Activity`. Warn on old or unknown migrations unless the file cannot be interpreted.

package/skills/uipath-maestro-bpmn/references/shared/cli-conventions.md

@@ -0,0 +1,46 @@
+# CLI Conventions
+
+The BPMN skill assumes a split boundary: model-authored BPMN source plus CLI validation, enrichment, packaging, and cloud lifecycle.
+
+## Output parsing
+
+When a CLI result is parsed programmatically, request JSON output. If the command does not support JSON output yet, do not scrape human text silently; report that the command is not machine-readable and keep the next step manual or advisory.
+
+## Side-effect boundary
+
+Local validation, registry discovery, static inspection, and package dry-run style commands are authoring-safe. Upload, publish, deploy, debug, process run, instance lifecycle, and cloud resource mutation are operate actions and require explicit user consent.
+
+## Login boundary
+
+Authoring should work without login for local source edits and static validation. Registry-backed discovery, Integration Service enrichment, resource refresh, upload, debug, publish, process inspection, and run diagnosis may require login.
+
+## Integration Service enrichment
+
+For Integration Service nodes and triggers, use CLI or registry-backed tooling to:
+
+- Resolve connector and operation metadata.
+- Bind a selected connection.
+- Generate or enrich `uipath:activity` / `uipath:event` XML.
+- Generate `bindings_v2.json` resources.
+- Generate dynamic input and output schemas.
+- Validate required context/input fields.
+
+If enrichment tooling is unavailable, leave the element as a draft intent and record the open question. Do not hand-author connection IDs or private resource metadata.
+
+## Local metadata regeneration
+
+When BPMN source changes, regenerate or verify local package metadata before cloud actions. The derived files are `entry-points.json`, `bindings_v2.json`, `operate.json`, and `package-descriptor.json`; the BPMN source and registry-backed enrichment inputs are authoritative. Follow [local-metadata-regeneration-guide.md](local-metadata-regeneration-guide.md) for entry point schema, binding resource, and `Intsvc.*` payload drift checks.
+
+## Validation before operate
+
+Before upload, debug, publish, or deploy, run the available local checks for:
+
+- BPMN XML parse.
+- Diagram presence and geometry.
+- UiPath extension structure.
+- Entry point extraction.
+- Binding reference resolution.
+- Generated package file consistency.
+- Integration Service enrichment completeness.
+
+Warnings about CLI-owned fields are blockers when the affected element will execute in a real run.

package/skills/uipath-maestro-bpmn/references/shared/error-handling.md

@@ -0,0 +1,82 @@
+# Error Handling
+
+Maestro supports BPMN error paths plus UiPath-specific retry and error-mapping
+metadata. These features are executable behavior, so add them in pass 2 only
+after the process shape and error intent are clear.
+
+## BPMN error paths
+
+- Declare reusable errors with `bpmn:error` and a stable `errorCode`.
+- Attach `bpmn:boundaryEvent` with `bpmn:errorEventDefinition` to the activity
+  whose failure should branch locally.
+- Omit `errorRef` on an error event definition only for a deliberate catch-all
+  handler.
+- Use event subprocesses for scoped error handling that should catch errors not
+  handled by a more local boundary event.
+- Give each event subprocess exactly one start event.
+- Boundary error event outgoing flows are exception flows. Do not also list
+  those flows as normal outgoing flows on the attached activity.
+
+## Retry metadata
+
+Place retry metadata inside the activity extension elements:
+
+```xml
+<uipath:retry maxRetryCount="2" retryBackoff="PT30S" retryAllErrors="false">
+  <uipath:errorDefinition errorRef="Error_ServiceUnavailable" />
+</uipath:retry>
+```
+
+Supported retry attributes are:
+
+- `maxRetryCount`
+- `retryBackoff`
+- `retryAllErrors`
+- `retryBackoffType`
+- `maxDuration`
+- `exponentialBase`
+
+Do not use stale aliases such as `maxAttempts` or `interval` in new XML.
+
+## Error mapping metadata
+
+Use error mapping when an activity needs to classify runtime failures for
+retry, routing, or diagnostics:
+
+```xml
+<uipath:errorMapping version="v1">
+  <uipath:error
+    id="Mapped_ServiceUnavailable"
+    errorRef="Error_ServiceUnavailable"
+    priority="1"
+    condition="=vars.error.code == &quot;SERVICE_UNAVAILABLE&quot;"
+    detail="Service unavailable"
+    retryable="true" />
+</uipath:errorMapping>
+```
+
+Error mapping entries support:
+
+- `id`
+- `errorRef`
+- `priority`
+- `condition`
+- `detail`
+- `retryable`
+
+Use `errorRef` to connect to a declared `bpmn:error`. Use `priority` when
+multiple mappings may match. Conditions are lint-sensitive expressions and may
+read the built-in runtime error through `vars.error`.
+
+Do not use `code="..."` on `uipath:error` in new XML; model the code on
+`bpmn:error errorCode="..."` and reference it through `errorRef`.
+
+## Validation checklist
+
+- Every `errorRef` resolves to a declared `bpmn:error`.
+- Retry attributes use current names.
+- Error mapping priorities are numeric.
+- Error mapping `retryable` values are `true` or `false`.
+- Conditions use `=vars.error...` and contain no assignments.
+- Boundary handlers are attached to valid activities.
+- Event subprocess handlers stay inside the scope whose errors they catch.

package/skills/uipath-maestro-bpmn/references/shared/expression-authoring.md

@@ -0,0 +1,95 @@
+# Expression Authoring
+
+Use this reference whenever pass 2 writes Maestro runtime expressions in BPMN
+XML. Pass 1 may use business-readable placeholder conditions; pass 2 replaces
+them with expressions only after the variables and scopes exist.
+
+## Stored expression shape
+
+- Use a leading `=` where Maestro expects expression content.
+- Treat values without `=` as literals.
+- Read BPMN variables through `vars.<variableId>`, for example
+  `=vars.Var_RequestId`.
+- Do not use bare variable names such as `=requestId` in generated runtime XML.
+- Context bindings use `=bindings.<bindingId>`.
+- Current element outputs use `result` only in output mappings for that
+  element. Script task return values are exposed under `result.response`; use
+  `source="=result.response"` for scalar returns or
+  `source="=result.response.<field>"` for object fields.
+- Multi-instance task bodies read the current item from `iterator.item`.
+- Multi-instance subprocess bodies read the current item from
+  `iterator[0].item`. Use `iterator[1].item` (and so on) inside nested
+  multi-instance subprocesses: the index counts nesting depth from outermost
+  (`[0]`) to innermost.
+- The current 0-based loop index inside any multi-instance body is exposed as
+  `iterator.loopCounter` for tasks and `iterator[N].loopCounter` for
+  subprocesses at depth N.
+- Error mapping conditions may inspect the built-in error object through
+  `vars.error`, for example `=vars.error.code == "SERVICE_UNAVAILABLE"`.
+
+## Inline JavaScript with `=js:`
+
+When a mapping body or context value needs computation that a simple
+`=vars.<id>` expression cannot express, prefix the body with `=js:` and follow
+it with a JavaScript expression. The runtime evaluates the rest of the value
+against the same `vars`, `bindings`, `result`, and `iterator` namespaces.
+Use this form inside CDATA mapping bodies; it is the runtime-supported
+escape hatch the BPMN expression grammar does not otherwise expose.
+
+```xml
+<uipath:input name="JobArguments" type="json" target="bodyField"><![CDATA[
+{"startRow":"=js:iterator[0].loopCounter * vars.Var_RowsPerShard",
+ "endRow":"=js:(iterator[0].loopCounter + 1) * vars.Var_RowsPerShard - 1"}
+]]></uipath:input>
+```
+
+Rules:
+
+- The prefix is `=js:` (case-sensitive, no space).
+- The body must still satisfy lint-sensitive constraints: no assignment
+  operators in fields where read-only expressions are required.
+- Prefer plain `=vars.<id>` or `=bindings.<id>` when the value does not need
+  computation — `=js:` should be reserved for arithmetic, string
+  manipulation, or conditional selection.
+- A `=js:` expression that returns an object or array must produce valid JSON
+  for fields typed `json`.
+
+Prefer JavaScript-safe variable ids such as `Var_RequestId`. If a brownfield
+file contains non-identifier ids, preserve them and let the product editor or
+CLI normalize the access form; do not silently rename variables without updating
+all mappings, expressions, and generated metadata.
+
+## Lint-sensitive fields
+
+These fields must be read-only expressions:
+
+- Gateway `bpmn:conditionExpression` values.
+- Activity skip conditions.
+- Multi-instance completion and filter conditions.
+- `uipath:errorMapping` condition values.
+- Mapping values that read variables or element outputs.
+
+Do not use assignment operators in these fields. Comparisons such as `==`,
+`===`, `!=`, `!==`, `>=`, and `<=` are allowed.
+
+## Scope and availability
+
+- Root variables are visible across the root process after they are declared and
+  reachable by control flow.
+- Subprocess variables stay scoped to that subprocess.
+- Output mappings should target `uipath:inputOutput` or `uipath:output`
+  variables, not read-only `uipath:input` variables.
+- Entry point inputs that must later be updated need a separate mutable
+  `uipath:inputOutput` variable and an explicit mapping from the entry input.
+- Trigger-bound values are commonly represented as `uipath:inputOutput`
+  variables scoped with `elementId` so the trigger can write them during
+  execution.
+
+## Common mistakes
+
+- `=requestId` instead of `=vars.Var_RequestId`.
+- `var="requestId"` instead of `var="Var_RequestId"`.
+- Using `result` outside the output mapping of the element that produced it.
+- Reading `iterator[0].item` outside the multi-instance subprocess body.
+- Moving a variable into a subprocess without updating mappings that read it
+  from the root scope.