@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-maestro-bpmn/references/diagnose/CAPABILITY.md

@@ -53,19 +53,19 @@ deployed BPMN asset correlation, element executions, cursors, generated package
 
 | Journey | Read |
 | --- | --- |
-| Triage a failed run | [references/troubleshooting-guide.md](references/troubleshooting-guide.md) |
-| Recognize recurring failure patterns | [references/failure-modes.md](references/failure-modes.md) |
+| Triage a failed run | [references/troubleshooting-guide.md](troubleshooting-guide.md) |
+| Recognize recurring failure patterns | [references/failure-modes.md](failure-modes.md) |
 
 ## Common tasks
 
 | I need to... | Read these |
 | --- | --- |
-| Find the faulting element | [references/troubleshooting-guide.md](references/troubleshooting-guide.md) |
-| Compare local and deployed BPMN | [references/troubleshooting-guide.md](references/troubleshooting-guide.md) |
-| Inspect runtime variables, cursors, or element executions | [references/troubleshooting-guide.md](references/troubleshooting-guide.md) |
-| Diagnose binding or generated JSON issues | [failure modes](references/failure-modes.md), [project layout](../shared/project-layout.md) |
-| Diagnose Integration Service runtime issues | [failure modes](references/failure-modes.md) |
-| Decide whether retry is safe | [troubleshooting guide](references/troubleshooting-guide.md), [manage guide](../operate/references/manage.md) |
+| Find the faulting element | [references/troubleshooting-guide.md](troubleshooting-guide.md) |
+| Compare local and deployed BPMN | [references/troubleshooting-guide.md](troubleshooting-guide.md) |
+| Inspect runtime variables, cursors, or element executions | [references/troubleshooting-guide.md](troubleshooting-guide.md) |
+| Diagnose binding or generated JSON issues | [failure modes](failure-modes.md), [project layout](../shared/project-layout.md) |
+| Diagnose Integration Service runtime issues | [failure modes](failure-modes.md) |
+| Decide whether retry is safe | [troubleshooting guide](troubleshooting-guide.md), [manage guide](../operate/manage.md) |
 | Fix the source | [registry-workflow.md](../registry-workflow.md) |
 
 For Integration Service enrichment details, read
@@ -84,8 +84,8 @@ For Integration Service enrichment details, read
 
 ### Diagnose-scoped
 
-- [troubleshooting-guide.md](references/troubleshooting-guide.md) - diagnostic priority ladder
-- [failure-modes.md](references/failure-modes.md) - recurring failure patterns
+- [troubleshooting-guide.md](troubleshooting-guide.md) - diagnostic priority ladder
+- [failure-modes.md](failure-modes.md) - recurring failure patterns
 
 ### Cross-capability
 

package/skills/uipath-maestro-bpmn/references/diagnose/{references/troubleshooting-guide.md → troubleshooting-guide.md}

@@ -160,5 +160,5 @@ uip maestro bpmn processes incidents <PROCESS_KEY> --output json
 ```
 
 Lifecycle commands are intentionally absent from this diagnostic command list.
-Use [operate/references/manage.md](../../operate/references/manage.md) only after the diagnosis supports a
+Use [operate/references/manage.md](../operate/manage.md) only after the diagnosis supports a
 side-effecting action and the user consents.

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

@@ -27,8 +27,18 @@ them with expressions only after the variables and scopes exist.
 - 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"`.
+- The engine surfaces a failed element's error under the capital-`Error` key
+  with lowercase fields: `code`, `message`, `detail`, `category`, `status`,
+  `traceId`, `response`, `element`. Read it as `vars.Error.<field>` — for example
+  `=vars.Error.code == "SERVICE_UNAVAILABLE"`. Both evaluators are
+  case-sensitive, so `vars.error` does not resolve. `category` is `User`
+  (HTTP 4xx), `System`, or `Deployment`.
+- Whether a binding is needed depends on what catches the failure. An **error
+  event subprocess** is handed the error context as its payload, so its
+  conditions read `vars.Error` with nothing authored. An **error boundary event**
+  and an activity's own **error mapping** are evaluated against that element's
+  declared outputs, so those need a `uipath:output` with `source="=Error"` before
+  `vars.Error` resolves.
 
 ## Inline JavaScript with `=js:`
 

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

@@ -48,20 +48,20 @@ These actions may contact UiPath services or external systems.
 
 | Journey | Read |
 | --- | --- |
-| Package and upload or publish | [references/ship.md](references/ship.md) |
-| Debug/run and inspect execution | [references/run.md](references/run.md) |
-| Manage a running instance | [references/manage.md](references/manage.md) |
+| Package and upload or publish | [references/ship.md](ship.md) |
+| Debug/run and inspect execution | [references/run.md](run.md) |
+| Manage a running instance | [references/manage.md](manage.md) |
 
 ## Common tasks
 
 | I need to... | Read these |
 | --- | --- |
-| Prepare for Studio Web upload | [references/ship.md](references/ship.md), [shared/project-layout.md](../shared/project-layout.md) |
-| Deploy to Orchestrator | [references/ship.md](references/ship.md) |
-| Run/debug a BPMN process | [references/run.md](references/run.md) |
-| Inspect job or instance status | [references/run.md](references/run.md) |
-| Pause/resume/cancel/retry | [references/manage.md](references/manage.md) |
-| Migrate or move an instance cursor | [references/manage.md](references/manage.md) |
+| Prepare for Studio Web upload | [references/ship.md](ship.md), [shared/project-layout.md](../shared/project-layout.md) |
+| Deploy to Orchestrator | [references/ship.md](ship.md) |
+| Run/debug a BPMN process | [references/run.md](run.md) |
+| Inspect job or instance status | [references/run.md](run.md) |
+| Pause/resume/cancel/retry | [references/manage.md](manage.md) |
+| Migrate or move an instance cursor | [references/manage.md](manage.md) |
 | Correlate a running instance to deployed BPMN | [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) |
 | Diagnose a failed run | [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) |
 
@@ -79,9 +79,9 @@ These actions may contact UiPath services or external systems.
 
 ### Operate-scoped
 
-- [ship.md](references/ship.md) - package, upload, publish, deploy
-- [run.md](references/run.md) - debug, run, status, traces
-- [manage.md](references/manage.md) - pause, resume, cancel, retry, migrate, cursor movement
+- [ship.md](ship.md) - package, upload, publish, deploy
+- [run.md](run.md) - debug, run, status, traces
+- [manage.md](manage.md) - pause, resume, cancel, retry, migrate, cursor movement
 
 ### Cross-capability
 

package/skills/uipath-maestro-bpmn/references/operate/{references/run.md → run.md}

@@ -25,7 +25,7 @@ BPMN project, refresh resources, and run debug from the solution directory:
 
 ```bash
 uip solution init <SolutionName> --output json
-uip solution projects import --source <ProjectDir> --solutionFile <SolutionName>/<SolutionName>.uipx --output json
+uip solution projects import <ProjectDir> --solutionFile <SolutionName>/<SolutionName>.uipx --output json
 uip solution resources refresh --solution-folder <SolutionName> --output json
 cd <SolutionName> && uip maestro bpmn debug <ProjectDirName> --output json
 ```
@@ -124,7 +124,7 @@ runtime/debug API limitation when you see it.
 Start with status and incidents before verbose traces.
 Traces can be large and should be pulled only when incidents and variables are insufficient.
 
-If execution faults, hand off to [diagnose/CAPABILITY.md](../../diagnose/CAPABILITY.md).
+If execution faults, hand off to [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md).
 
 ## Anti-patterns
 

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

@@ -25,7 +25,7 @@ Before upload, publish, deploy, or debug:
 
    Treat `bindings_v2.json`, `entry-points.json`, `operate.json`, and `package-descriptor.json` as derived unless a
    CLI contract says otherwise. See
-   [local-metadata-regeneration-guide.md](../../shared/local-metadata-regeneration-guide.md) for drift
+   [local-metadata-regeneration-guide.md](../shared/local-metadata-regeneration-guide.md) for 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
@@ -93,7 +93,7 @@ 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):
+[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.
@@ -109,7 +109,7 @@ Do not hand-patch generated files as the primary fix.
 If package or upload fails:
 
 - Capture the high-level error category.
-- Check generated package files against [shared/project-layout.md](../../shared/project-layout.md).
+- 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.

package/skills/uipath-maestro-bpmn/references/patterns/ai-decision-review-guide.md

@@ -0,0 +1,138 @@
+# Pattern: `ai-decision-review`
+
+AI produces a decision, a confidence gate auto-actions the clear cases, and a
+human reviews the rest. Use it when some items are clear-cut, others need
+judgment, and someone must stay accountable for the non-trivial ones.
+
+## Why it works
+
+These four carry the shape. Change one and you are building something else.
+
+- **One tunable threshold owns the split.** A single confidence gate separates
+  the auto-action path from the review path, so how much the AI handles on its
+  own is one number, not a topology change. The shape survives re-tuning.
+- **Validation runs before the gate.** Malformed output is not low confidence,
+  it is invalid, and it must reach a reviewer carrying the reason. Validating
+  first lets one gate handle both "unsure" and "broken" without a second branch.
+- **One action step, reached two ways.** The approve edge routes back into the
+  same action node the auto path uses. The action is implemented, bound, and
+  configured once.
+- **Every item exits through a named outcome.** Auto-actioned, or rejected by a
+  reviewer. That is what makes the decision auditable afterwards.
+
+## Shape
+
+| Node | Element | Role |
+| --- | --- | --- |
+| `start` | `bpmn:startEvent` + message event definition | Entry |
+| `analyze` | `bpmn:serviceTask` | Placeholder · insertion point |
+| `validate` | `bpmn:businessRuleTask` | Mechanism |
+| `confidence_gate` | `bpmn:exclusiveGateway` | Mechanism |
+| `perform_action` | `bpmn:serviceTask` | Placeholder · Mechanism — bind the target, but keep it a single node with two inbound edges |
+| `human_review` | `bpmn:userTask` | Mechanism |
+| `post_review_gate` | `bpmn:exclusiveGateway` | Mechanism |
+| `end_actioned` | `bpmn:endEvent` | Mechanism |
+| `end_rejected` | `bpmn:endEvent` | Mechanism |
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `start` → `analyze` | | |
+| `analyze` → `validate` | | |
+| `validate` → `confidence_gate` | | |
+| `confidence_gate` → `perform_action` | High confidence | `=vars.aiConfidenceLevel >= 0.85 && vars.validationPassed` |
+| `confidence_gate` → `human_review` | Low confidence | `=vars.aiConfidenceLevel < 0.85 \|\| !vars.validationPassed` |
+| `perform_action` → `end_actioned` | | |
+| `human_review` → `post_review_gate` | | |
+| `post_review_gate` → `perform_action` | Approved | `=vars.reviewOutcome == "Approve"` |
+| `post_review_gate` → `end_rejected` | Rejected | `=vars.reviewOutcome == "Reject"` |
+
+`0.85` is an illustrative threshold. Set it from the cost asymmetry between a
+wrong auto-action and a needless review — that number is the pattern's tuning
+knob, not part of its definition.
+
+| Variable | Type | Default | Holds |
+| --- | --- | --- | --- |
+| `aiDecision` | string | | The categorical decision |
+| `aiRationale` | string | | Reasoning, where the analyzer produces it |
+| `aiConfidenceLevel` | double | `0.95` | Confidence, 0–1 |
+| `validationPassed` | boolean | `true` | Did the output pass validation |
+| `validationFailures` | jsonSchema | | Why it did not |
+| `reviewOutcome` | string | | `Approve` or `Reject` |
+| `reviewerRationale` | string | | Reviewer's free-text reasoning |
+| `actionTakenResponse` | jsonSchema | | Response from the action target |
+
+Names are recommended, not required — they keep processes comparable. When
+inserting into a process that already holds one of these under another name,
+bind to the existing one.
+
+## Variants
+
+| Variant | Question it answers | Delta |
+| --- | --- | --- |
+| Single reviewer | — | The shape above |
+| Tiered reviewer | Do reviewers differ in authority? | Stakes gate + two reviewer paths |
+| Verification chain | Is a wrong auto-action costlier than a second AI call? | Second analyzer before validation |
+
+**Tiered reviewer.** Insert `stakes_gate` (`bpmn:exclusiveGateway`) between
+`validate` and `confidence_gate`, and split `human_review` into `junior_review`
+and `senior_review`.
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `stakes_gate` → `senior_review` | High stakes | `=vars.stakesValue >= 5000` |
+| `stakes_gate` → `confidence_gate` | Low stakes | default |
+| `confidence_gate` → `junior_review` | Low confidence | as above |
+| `senior_review` → `perform_action` | | no gate |
+| `post_review_gate` → `senior_review` | Escalate | `=vars.reviewOutcome == "Escalate"` |
+
+Adds `stakesValue` (double) — a domain signal such as loan amount or claim
+value. `5000` is illustrative. Senior review has no post-review gate on
+purpose: routing a senior verdict through a gate that can escalate again loops.
+
+**Verification chain.** Insert `verifier` (`bpmn:serviceTask`) between `analyze`
+and `validate`, and extend both gate conditions to require agreement:
+
+- Auto — `=vars.aiConfidenceLevel >= 0.85 && vars.verifierConfidence >= 0.85 && vars.verifierDecision == vars.aiDecision && vars.validationPassed`
+- Review — negate it
+
+Adds `verifierDecision` (string) and `verifierConfidence` (double). Bind the
+verifier node to a **different model** than the analyzer node; the same model
+has the same blind spots, so the second call verifies nothing.
+
+## What to bind
+
+- **`analyze`** — the node that produces the decision at runtime: a UiPath
+  agent, Document Understanding, or a chain of both. Place and bind the node.
+  Never decide the categories or hardcode a result while authoring.
+- **`perform_action`** — the downstream target: ERP, CRM, case system, outbound
+  message.
+- **`validate`** — `Orchestrator.BusinessRules`. Rules are uploaded to
+  Orchestrator separately; the BPMN references them.
+- **`human_review`** — `Actions.HITL`. Route `post_review_gate` on the exact
+  variable the template's `<uipath:output ... var="...">` binds, not a copy.
+- **Review SLA** — the timer and its breach outcome are properties of the user
+  task, not a boundary timer (SKILL.md rule 12).
+
+Fetch every payload through
+[registry-workflow.md](../registry-workflow.md); confirm type names with
+`registry list` rather than trusting the ones above.
+
+## Adapting it
+
+The commonest reduction: the process already scores the item. Insert only
+`validate` onward, bind the gate to the existing score variable, and add no
+second analyzer.
+
+`validate` is the one load-bearing step you can remove, and only when its
+mechanism is vacuous rather than unwanted: if the analyzer's output is
+schema-constrained and cannot be malformed, there is no invalid case to route,
+so simplify the gate to the confidence term alone. If malformed output is merely
+unlikely, keep it.
+
+Keep both named end events regardless; that is the audit trail.
+
+## Composing
+
+Nested inside `high-volume-batch` this becomes the per-item subprocess. Pair it
+with `failure-escalation` so a failure in `analyze` or `perform_action` does not
+vanish. See [composing-guide.md](composing-guide.md).

package/skills/uipath-maestro-bpmn/references/patterns/approval-chain-guide.md

@@ -0,0 +1,136 @@
+# Pattern: `approval-chain`
+
+A request passes through several approvers before it can be fulfilled. Use it
+when sign-off is needed from more than one person or group, and a rejection at
+any point should stop the request.
+
+## Why it works
+
+These four carry the shape. Change one and you are building something else.
+
+- **A gateway after every approver, and rejection exits.** Every rejection
+  routes to one shared notify-and-end pair rather than each step growing its own
+  exit, so adding an approver adds a row, not a new terminal branch. In the
+  sequential shape this also stops the chain at the first rejection, because the
+  next approver is reachable only through the approve branch. The parallel shape
+  cannot: its join waits for every approver, so all verdicts are collected and
+  one gateway rejects afterwards.
+- **Per-approver outcome variables.** Each step records its own verdict and
+  rationale. A single shared `outcome` variable would let the last approver
+  overwrite the audit trail of the ones before.
+- **Ordering and depth are separate questions.** Sequential and parallel answer
+  *in what order*. Risk-tiered answers *how much approval at all*, and routes to
+  a chain of either shape. That is why risk-tiered reuses the others as
+  subprocesses instead of redrawing them.
+- **Unclassified risk takes the longest chain.** The risk gateway's default
+  sequence flow points at the extended chain, so a gap in the rules over-scrutinises
+  rather than under-scrutinises.
+
+## Shape
+
+Sequential is the base shape. `N` approvers is illustrative — three below, but
+the row repeats for however many the policy needs.
+
+| Node | Element | Role |
+| --- | --- | --- |
+| `start` | `bpmn:startEvent` + message event definition | Entry |
+| `approver1..N` | `bpmn:userTask` | Mechanism · insertion point |
+| `gate1..N` | `bpmn:exclusiveGateway` | Mechanism |
+| `fulfill` | `bpmn:serviceTask` | Placeholder |
+| `notify` | `bpmn:sendTask` | Placeholder |
+| `end_fulfilled` | `bpmn:endEvent` | Mechanism |
+| `notify_rejected` | `bpmn:sendTask` | Placeholder |
+| `end_rejected` | `bpmn:endEvent` | Mechanism |
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `start` → `approver1` | | |
+| `approverI` → `gateI` | | |
+| `gateI` → `approverI+1` | Approve | `=vars.approvalIOutcome == "Approve"` |
+| `gateN` → `fulfill` | Approve | `=vars.approvalNOutcome == "Approve"` |
+| `gateI` → `notify_rejected` | Rejected | `=vars.approvalIOutcome == "Reject"` |
+| `fulfill` → `notify` → `end_fulfilled` | | |
+| `notify_rejected` → `end_rejected` | | |
+
+| Variable | Type | Holds |
+| --- | --- | --- |
+| `requestId` | string | Identifier of the request |
+| `requestType` | string | Category — vendor onboarding, expense, access |
+| `requesterId` | string | Who raised it |
+| `requestDetails` | jsonSchema | Payload: amount, sensitivity, decision fields |
+| `approvalIOutcome` | string | `Approve` or `Reject`, one per approver |
+| `approvalIRationale` | string | That approver's reasoning |
+| `fulfillmentResponse` | jsonSchema | Response from the fulfillment target |
+
+## Variants
+
+| Variant | Question it answers | Delta |
+| --- | --- | --- |
+| Sequential | — | The shape above |
+| Parallel | Does order matter? | Fork/join around simultaneous approvals |
+| Risk-tiered | How much approval does this request need? | Risk gateway selecting between chains |
+
+**Parallel.** Replace the approver rows with a `bpmn:parallelGateway` fork, one
+`bpmn:userTask` per approver, a `bpmn:parallelGateway` join, and a single
+`bpmn:exclusiveGateway` verdict. Outcome variables are suffixed `A`/`B`/`C`
+rather than numbered, since there is no order to number.
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `join` → `decision` | | |
+| `decision` → `notify_rejected` | No | `=vars.approvalAOutcome == "Reject" \|\| vars.approvalBOutcome == "Reject" \|\| vars.approvalCOutcome == "Reject"` |
+| `decision` → `fulfill` | Yes | default |
+
+The join waits for every branch, so the verdict runs once with all outcomes
+present. All-must-approve is the shape; the verdict condition is where a quorum
+rule would go instead.
+
+**Risk-tiered.** Insert `evaluate` (`bpmn:businessRuleTask`) and `risk_gate`
+(`bpmn:exclusiveGateway`) after the start, and put the chains inside
+`bpmn:subProcess` nodes.
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `risk_gate` → `fulfill` | Low | `=vars.riskTier == "low"` |
+| `risk_gate` → `standard_chain` | Standard | `=vars.riskTier == "standard"` |
+| `risk_gate` → `extended_chain` | High | default |
+| `standard_chain` / `extended_chain` → `approved_gate` | | |
+| `approved_gate` → `notify_rejected` | No | any `approvalIOutcome == "Reject"` |
+| `approved_gate` → `fulfill` | Yes | default |
+
+Adds `riskTier` (string: `low` / `standard` / `high`). Low risk reaches
+`fulfill` with no human step at all — that is the point of the tier. Both chains
+share the same approver variables because only one runs per instance.
+
+## What to bind
+
+- **Approver tasks** — `Actions.HITL`. Resolving *who* approves is a lookup
+  against your directory; the BPMN holds the task, not the roster.
+- **Per-step SLA** — timer, reassignment, and breach outcome are properties of
+  the user task, not boundary timers (SKILL.md rule 12).
+- **Segregation of duties** — enforce at approver lookup, so no one person signs
+  consecutive steps. It is not a BPMN construct.
+- **`evaluate`** — `Orchestrator.BusinessRules`, with rules uploaded to
+  Orchestrator separately.
+- **`fulfill`** — ERP, CRM, provisioning system. **`notify`** — email, chat,
+  requester callback.
+
+Fetch payloads through [registry-workflow.md](../registry-workflow.md).
+
+## Adapting it
+
+Change the approver count freely; the row is the unit. Two approvers is a chain,
+six is a chain.
+
+Reuse the shape for any all-must-agree sign-off, not only approvals — a
+multi-party sign-off on a document or a release gate is the same topology.
+
+Drop `notify` when the requester is a system that reads the outcome rather than
+a person who needs telling. Keep both named end events.
+
+## Composing
+
+Risk-tiered is already a composition: the chains are `bpmn:subProcess` nodes,
+and either can hold the sequential or the parallel shape. Add
+`failure-escalation` so a failure in `fulfill` does not vanish silently. See
+[composing-guide.md](composing-guide.md).

package/skills/uipath-maestro-bpmn/references/patterns/composing-guide.md

@@ -0,0 +1,113 @@
+# Composing Patterns
+
+Read this when a process uses more than one pattern. For a single pattern —
+greenfield or inserted into a process that already runs — its own guide is
+enough.
+
+## Patterns are graph fragments
+
+Each guide draws its pattern standalone, so the shape opens with a start event.
+That start event is an artifact of drawing it alone — it is not part of the
+pattern. A pattern goes anywhere in a graph.
+
+Keep the start event only when the pattern happens to begin the process. Author
+it into the middle of an existing process and you drop the start event entirely.
+
+Two entries are load-bearing and do constrain placement:
+
+- **`queue-distribution`'s performer** — its start event carries the queue
+  trigger, so the performer must begin the process. It cannot be inserted
+  mid-process or nested in a subprocess.
+- **`failure-escalation`** — an event subprocess with no sequence flows in or
+  out. It is placed inside the container it guards and must sit there
+  *directly*; wrapping it in another subprocess changes which failures reach
+  it.
+
+Both are engine behavior, not style.
+
+## Four ways to join
+
+Building from scratch with several patterns, the outermost one keeps its start
+event and the rest go inside it.
+
+### Inserted inline
+
+The default. Drop the pattern's start event and wire the preceding step into its
+first real node; its steps become part of the surrounding process.
+
+Use it whenever the work belongs in this process and there is no reason to
+encapsulate — adding a confidence-gated review partway through a process that
+already runs.
+
+### Nested as `bpmn:subProcess`
+
+The pattern's start event becomes the subprocess's internal start event, and the
+subprocess takes the sequence flows in and out.
+
+Prefer this over inserting when you need what a container gives you: its own
+variable scope, a multi-instance marker over the whole pattern, its own
+`failure-escalation` net, or a collapsed box that keeps the parent readable.
+
+Risk-tiered `approval-chain` already works this way internally: the standard and
+extended chains are subprocesses the risk gate routes between.
+
+### Placed, not wired
+
+`failure-escalation` composes by placement alone. Drop the event subprocess into
+the container whose failures it should catch and author no sequence flows to or
+from it.
+
+### Dispatched by message to a separate process
+
+The downstream work becomes its own Maestro process, started by a message. Use
+this when the downstream has its own lifecycle, its own trigger, or should scale
+independently.
+
+`smart-triage`'s per-category steps are placeholders for exactly this choice.
+Replacing them with a dispatch keeps triage thin; filling them inline makes
+triage own handling for every category it routes.
+
+## Adding a pattern to a process that already runs
+
+Insert only the part the process lacks, and bind to what it already holds. Each
+guide's "Adapting it" says which of its steps are commonly already present and
+which variable to bind instead of declaring.
+
+Everything the pattern does not touch stays untouched — element IDs, unknown
+`uipath:*` payloads, imported connector data. Inserting a pattern is a surgical
+edit, not a regeneration.
+
+## Scoping the failure net
+
+One net covers its whole container, including every subprocess nested under it,
+because unhandled failures propagate outward container by container. A single
+net at process level is the usual answer.
+
+Add a second net inside a multi-instance iteration or a queue performer only
+when per-item failures need per-item handling — when one bad item should be
+recorded and the batch should continue. Without an inner net, the first failure
+escalates through the process-level net and ends the instance.
+
+See
+[structural-bpmn.md](../structural-bpmn.md#choosing-an-error-handling-construct)
+for choosing between a net, a boundary event, and node retry.
+
+## Variables across a nesting boundary
+
+A nested pattern's variables are scoped to its subprocess. Anything the parent
+needs after the subprocess completes must be mapped out explicitly, and anything
+the nested pattern reads from the parent must be mapped in. Two patterns that
+both declare a variable of the same name do not share it across that boundary.
+
+Where two patterns meet, keep each one's variable names rather than merging them
+into a shared name — the guides' conditions reference those names directly.
+
+## Worked combinations
+
+| Combination | Outermost | How the rest join |
+| --- | --- | --- |
+| Batch of items, each AI-decided with review | `high-volume-batch` | `ai-decision-review` nested as the per-item subprocess |
+| Triage inbound, then approve by category | `smart-triage` | `approval-chain` per category, dispatched by message |
+| Queue performer with per-item error handling | `queue-distribution` performer | `failure-escalation` placed inside the performer |
+| Add review to a process that already runs | the existing process | `ai-decision-review` inserted inline, no start event |
+| Any production process | whichever owns the trigger | `failure-escalation` placed at process level |