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

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

@@ -0,0 +1,145 @@
+# Pattern: `external-wait`
+
+The process suspends until an outside party responds, nudges before the
+deadline, and escalates when the deadline passes. Use it when a reply may take
+hours or weeks and an SLA has to be enforced either way.
+
+## Why it works
+
+These five carry the shape. Change one and you are building something else.
+
+- **A correlation key goes out with the request.** The reply carries it back,
+  which is how the engine finds the one suspended instance that was waiting.
+  Without it a reply cannot be matched and the wait never ends.
+- **An event-based gateway makes the outcomes a race.** Reply, reminder, and
+  deadline are mutually exclusive: whichever fires first wins and the others are
+  discarded. Modelling them as parallel branches would let two fire.
+- **The reminder loops back to the same gateway.** After nudging, the process
+  resumes waiting on the gateway it already has, so the wait exists once no
+  matter how many reminders go out.
+- **Replies are validated before they are believed.** A malformed or
+  unmatched reply routes to a person instead of resuming the process on bad
+  data.
+- **Both exits are named.** A reply received, or an escalation exhausted. A
+  wait that ends without a recorded reason is indistinguishable from one that
+  never ended.
+
+## Shape
+
+Single-channel is the base shape.
+
+| Node | Element | Role |
+| --- | --- | --- |
+| `start` | `bpmn:startEvent` + message event definition | Entry |
+| `compose` | `bpmn:serviceTask` | Mechanism · insertion point — embeds the correlation key |
+| `send_request` | `bpmn:sendTask` | Placeholder |
+| `wait` | `bpmn:eventBasedGateway` | Mechanism |
+| `reply_received` | `bpmn:intermediateCatchEvent` + message event definition | Mechanism |
+| `reminder_timer` | `bpmn:intermediateCatchEvent` + timer event definition | Mechanism |
+| `send_reminder` | `bpmn:sendTask` | Placeholder |
+| `sla_deadline` | `bpmn:intermediateCatchEvent` + timer event definition | Mechanism |
+| `validate` | `bpmn:serviceTask` | Mechanism |
+| `valid_gate` | `bpmn:exclusiveGateway` | Mechanism |
+| `review_reply` | `bpmn:userTask` | Placeholder |
+| `run_escalation` | `bpmn:serviceTask` | Placeholder |
+| `end_received` | `bpmn:endEvent` | Mechanism |
+| `end_escalated` | `bpmn:endEvent` | Mechanism |
+
+Every outgoing sequence flow from `wait` must target an intermediate catch event
+or a receive task — that is a rule of the gateway, not a choice. See
+[structural-bpmn.md](../structural-bpmn.md#gateways).
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `start` → `compose` → `send_request` → `wait` | | |
+| `wait` → `reply_received` → `validate` | | |
+| `wait` → `reminder_timer` → `send_reminder` → `wait` | | the reminder loop |
+| `wait` → `sla_deadline` → `run_escalation` → `end_escalated` | | |
+| `validate` → `valid_gate` | | |
+| `valid_gate` → `end_received` | Valid | `=vars.responseValid == true` |
+| `valid_gate` → `review_reply` | Invalid | default |
+| `review_reply` → `end_received` | | |
+
+| Variable | Type | Default | Holds |
+| --- | --- | --- | --- |
+| `correlationKey` | string | | Unique ID embedded in the request |
+| `responseData` | jsonSchema | | The reply payload |
+| `responseValid` | boolean | `false` | Did it pass validation |
+| `validationIssue` | string | | Why it did not, shown to the reviewer |
+| `reviewOutcome` | string | | `Accept` or `Submit Correction` |
+| `reviewNote` | string | | Reviewer's note |
+
+## Variants
+
+| Variant | Question it answers | Delta |
+| --- | --- | --- |
+| Single-channel | — | The shape above |
+| Multi-channel | Can they reply however they like? | One catch event per channel |
+| First valid response wins | Can any of several parties fulfil it? | Fan out, first acceptable reply closes the rest |
+| Long-running probe | Can the far system push at all? | Poll on a timer instead of waiting for an event |
+
+**Multi-channel.** Replace `reply_received` with one
+`bpmn:intermediateCatchEvent` per channel — email, webhook, portal — each an
+outgoing target of `wait`, all converging on `validate`. The gateway already
+makes them a race, so the first to arrive wins and the rest are dropped. Same
+variables.
+
+**First valid response wins.** Fan out with a `bpmn:parallelGateway` to one send
+task per party, join, then open the response window and wait. An unacceptable
+reply is discarded and the wait resumes; the first acceptable one triggers a
+notification closing out the remaining parties.
+
+Variables narrow to `correlationKey` (one per party), `responseData`, and
+`replyAcceptable` (boolean, default `false`). Each request carries its own key,
+or replies cannot be told apart.
+
+**Long-running probe.** There is no event to catch, so there is no event-based
+gateway. `send_request` leads to a timer, then a poll task, then a readiness
+gateway; not-ready falls to a deadline gateway that either loops back to the
+timer or escalates.
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `ready_gate` → `end_received` | Ready | `=vars.resultReady == true` |
+| `ready_gate` → `deadline_gate` | Not yet | default |
+| `deadline_gate` → `run_escalation` | Yes | `=vars.deadlinePassed == true` |
+| `deadline_gate` → `poll_timer` | No | default |
+
+Variables are `responseData`, `resultReady` (boolean, `false`), and
+`deadlinePassed` (boolean, `false`). The loop returns to the **timer**, not the
+poll task — the wait between polls is the point. The deadline gateway is what
+stops the loop running forever; without it this shape never terminates.
+
+## What to bind
+
+- **`compose`** — build the outbound payload and embed the correlation key.
+- **`send_request`**, **`send_reminder`** — the outbound channel: email, portal
+  link, API call, EDI.
+- **Reply catch events** — the inbound channel and the message each correlates
+  on.
+- **Timer durations** — reminder cadence and the SLA deadline, as ISO 8601
+  durations on the timer event definitions.
+- **`validate`** — correlation match, parseable content, acceptable values.
+- **`review_reply`** — `Actions.HITL`.
+- **`run_escalation`** — next-level contact, alternate channel, internal owner.
+
+Fetch payloads through [registry-workflow.md](../registry-workflow.md); see
+[structural-bpmn.md](../structural-bpmn.md#events-and-the-event-definition-matrix)
+for event definition structure.
+
+## Adapting it
+
+Drop the reminder branch when there is no one to nudge — a machine counterpart
+that either answers or does not. The deadline branch stays; that is the SLA.
+
+Drop `review_reply` and route invalid replies straight to escalation when no
+human can repair a malformed reply.
+
+Add channels freely in the multi-channel variant: each is one more catch event
+on the gateway, not a structural change.
+
+## Composing
+
+Nested inside `high-volume-batch` this becomes a per-item wait, giving each item
+its own correlation key and deadline. Pair with `failure-escalation` for
+failures in sending or escalation. See [composing-guide.md](composing-guide.md).

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

@@ -0,0 +1,103 @@
+# Pattern: `failure-escalation`
+
+One error event subprocess that catches every unhandled activity failure in its
+container, classifies it, and routes business errors to a person and system
+failures to operations. Use it on any process where a failure must never
+disappear silently.
+
+## Why it works
+
+These four carry the shape. Change one and you are building something else.
+
+- **It covers by placement, not by wiring.** The net is an event subprocess with
+  no sequence flows in or out. Drop it into a container and every unhandled
+  activity failure inside routes to it, with nothing attached to any task.
+- **The engine pre-seeds the error context.** `vars.Error` arrives populated,
+  so the classification gateway reads real values with no mapping authored.
+- **It is interrupting and terminal, so outcomes must be named.** When the net
+  fires, the normal path stops and the instance records **Completed**, not
+  Faulted. Without an explicitly named end event on every branch, a handled
+  failure is indistinguishable from a success.
+- **Code-specific nets match before the catch-all.** Both can sit in one
+  container, so a known error gets a precise response while everything else
+  still lands somewhere.
+
+## Shape
+
+This pattern has no Entry row: it is never wired into a path.
+
+The net itself is a `bpmn:subProcess` with `triggeredByEvent="true"`, holding:
+
+| Node | Element | Role |
+| --- | --- | --- |
+| `err_start` | `bpmn:startEvent` + error event definition | Mechanism |
+| `classify` | `bpmn:exclusiveGateway` | Mechanism |
+| `reviewer` | `bpmn:userTask` | Placeholder |
+| `end_human` | `bpmn:endEvent` | Mechanism |
+| `record_failure` | `bpmn:serviceTask` | Placeholder |
+| `alert_oncall` | `bpmn:sendTask` | Placeholder |
+| `end_ops` | `bpmn:endEvent` | Mechanism |
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `err_start` → `classify` | | |
+| `classify` → `reviewer` | Business error | `=vars.Error.category == "User"` |
+| `reviewer` → `end_human` | | |
+| `classify` → `record_failure` | System failure | default |
+| `record_failure` → `alert_oncall` | | |
+| `alert_oncall` → `end_ops` | | |
+
+The pattern declares no process variables of its own. `vars.Error` is seeded by
+the engine — capital `E`, lowercase fields: `code`, `message`, `detail`,
+`category`, `status`, `traceId`, `response`, `element`. `category` is `User`,
+`System`, or `Deployment`; business errors arrive as `User`. See
+[expression-authoring.md](../expression-authoring.md#stored-expression-shape).
+
+## Variants
+
+| Variant | Question it answers | Delta |
+| --- | --- | --- |
+| Catch-all | What catches everything nothing else did? | The shape above |
+| Code-specific | Does one known error deserve its own response? | Bound start, no classification |
+
+**Code-specific.** Bind `err_start` to a single error code. The code already
+identifies the failure, so there is no `classify` gateway: the bound start leads
+straight to one response node and one named end event. It is the smaller net,
+and it coexists with a catch-all in the same container.
+
+## What to bind
+
+- **`reviewer`** — `Actions.HITL`. Who works a business error: an operations
+  queue, the process owner.
+- **`record_failure`** — where a system failure is durably recorded for someone
+  to work later: an exception queue, a task.
+- **`alert_oncall`** — the notification channel.
+- **The error code** on a code-specific net's `err_start`, via `errorRef` to a
+  declared `bpmn:error`.
+
+See [structural-bpmn.md](../structural-bpmn.md#subprocess-call-activity-event-subprocess-registry-gap-for-structure)
+for event subprocess structure, and
+[registry-workflow.md](../registry-workflow.md) for the payloads.
+
+## Adapting it
+
+Collapse the two branches into one when the process has no meaningful business
+errors — everything is a system failure and there is nobody to escalate to.
+Keep the named end event.
+
+Do not extend the net to resume the interrupted work. It cannot: the normal path
+has already stopped. Work that should recover and continue belongs on an error
+boundary event instead — see
+[structural-bpmn.md](../structural-bpmn.md#choosing-an-error-handling-construct).
+
+Two limits are worth knowing before relying on it. Only activities enter the
+chain, so a gateway whose condition fails to evaluate raises an incident and
+never reaches the net. And transient failures should not arrive here at all —
+they are absorbed by `uipath:retry` on the node.
+
+## Composing
+
+Nested patterns are covered for free: one net catches failures in every
+subprocess beneath it. For when a second net inside a batch iteration or a queue
+performer earns its place, see
+[composing-guide.md](composing-guide.md#scoping-the-failure-net).

package/skills/uipath-maestro-bpmn/references/patterns/high-volume-batch-guide.md

@@ -0,0 +1,107 @@
+# Pattern: `high-volume-batch`
+
+Many independent items processed in one run, fanned out in parallel, aggregated
+at the end. Use it when volume makes sequential processing impractical, items do
+not depend on each other, and some will fail without the run being a failure.
+
+## Why it works
+
+These four carry the shape. Change one and you are building something else.
+
+- **Each item runs in its own subprocess instance.** A multi-instance marker on
+  a container, not a loop drawn on the canvas. The marker gives each item its own
+  scope and lets them run concurrently — it does **not** by itself stop one
+  item's failure ending the run. An unhandled failure propagates outward, so
+  containing it needs a `failure-escalation` net placed inside the iteration.
+  Isolation is the marker plus that net, never the marker alone.
+- **Aggregation happens once, after the block completes.** The multi-instance
+  container does not exit until every instance has, which is what makes a single
+  aggregation step correct rather than a race.
+- **The policy decision is separate from the aggregation.** Aggregating counts
+  results; the gateway decides whether those counts constitute success.
+  Best-effort, all-or-nothing, and quorum are then one condition apart.
+- **The summary is sent before the verdict.** The report node sits ahead of the
+  policy gateway, so it runs on both outcomes. A failed batch is the one you
+  most need the numbers for.
+
+## Shape
+
+| Node | Element | Role |
+| --- | --- | --- |
+| `start` | `bpmn:startEvent` + message event definition | Entry |
+| `fetch_batch` | `bpmn:serviceTask` | Placeholder · insertion point |
+| `process_each` | `bpmn:subProcess`, multi-instance | Mechanism |
+| `aggregate` | `bpmn:serviceTask` | Mechanism |
+| `send_report` | `bpmn:sendTask` | Placeholder |
+| `policy_gate` | `bpmn:exclusiveGateway` | Mechanism |
+| `end_completed` | `bpmn:endEvent` | Mechanism |
+| `end_failed` | `bpmn:endEvent` | Mechanism |
+
+`process_each` holds a minimal body — a start event, one action node, an end
+event — and carries the multi-instance marker. The action node is a
+**Placeholder**.
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `start` → `fetch_batch` → `process_each` → `aggregate` → `send_report` → `policy_gate` | | |
+| `policy_gate` → `end_completed` | Yes | default |
+| `policy_gate` → `end_failed` | No | `=vars.policySatisfied == false` |
+
+| Variable | Type | Default | Holds |
+| --- | --- | --- | --- |
+| `batchItems` | jsonSchema | | The fetched items; bind as the multi-instance input collection |
+| `batchSummary` | jsonSchema | | Totals, success count, failure breakdown |
+| `policySatisfied` | boolean | `true` | Did the run meet the configured policy |
+
+The multi-instance marker and its collection binding are a **registry gap** —
+no template exists for them. Author them from the canvas contract in
+[structural-bpmn.md](../structural-bpmn.md#multi-instance--loop-characteristics-registry-gap--canvas-supports-it),
+and read the current item inside the body with `iterator[0].item` per
+[expression-authoring.md](../expression-authoring.md).
+
+## Variants
+
+One shape. Parallel versus sequential is a property of the multi-instance
+marker, not a different topology: set `isSequential` and optionally cap
+concurrency. Choose sequential when the per-item action hits a rate-limited
+system or items must be ordered.
+
+## What to bind
+
+- **`fetch_batch`** — the source: database query, file, API list, queue. Batch
+  size and filters are decided here.
+- **The action node** inside `process_each` — a UiPath agent, an RPA job,
+  Document Understanding, an API call. Place and bind the node; the per-item
+  work happens at runtime, not while authoring.
+- **`aggregate`** — apply the policy and set `policySatisfied`. Best-effort
+  always true; all-or-nothing true only with zero failures; quorum true above a
+  threshold. Evaluate it here, in a node, rather than as a
+  `bpmn:completionCondition` on the multi-instance marker. A completion
+  condition stops the block early, which is a different thing from judging the
+  run afterwards, and it cannot see the per-item results the policy needs.
+- **`send_report`** — email, chat, dashboard, audit store.
+
+Fetch payloads through [registry-workflow.md](../registry-workflow.md).
+
+## Adapting it
+
+Drop `fetch_batch` when the items arrive on the trigger rather than being
+pulled — bind the multi-instance collection straight to the input variable.
+That is the common case when this pattern is nested inside another.
+
+Drop `policy_gate` and `end_failed` when every run succeeds by definition and
+only the counts matter. Keep `send_report`.
+
+Set each item's exit status inside the body — success, failure, skipped — or
+`aggregate` has nothing to count.
+
+## Composing
+
+The per-item action is the usual nesting point: `ai-decision-review` or
+`external-wait` becomes the body of `process_each`, giving every item its own
+decision or its own wait.
+
+Place a `failure-escalation` net **inside** `process_each` so a per-item failure
+is handled per item and the run continues. A net at process level instead would
+catch the first failure and end the whole instance. See
+[composing-guide.md](composing-guide.md#scoping-the-failure-net).

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

@@ -0,0 +1,129 @@
+# Pattern: `queue-distribution`
+
+An Orchestrator queue sits between work creation and work processing. Use it
+when the two sides run in different runtimes, must scale independently, or when
+the queue itself is needed as a durable tracking surface.
+
+## Why it works
+
+These four carry the shape. Change one and you are building something else.
+
+- **The queue is the handover surface, not a message.** Priority, deferred
+  scheduling, deduplication, concurrency limits, and durable retry all come from
+  the queue and survive either side restarting. That is the reason to pay for a
+  queue instead of dispatching directly.
+- **One queue item starts one performer instance.** There is no loop in the BPMN
+  and deliberately no get-next-item step. Each unit of work is isolated and
+  independently tracked, at the cost of one process instance per item — which is
+  the trade to weigh when volume is very high.
+- **Every item ends by marking its transaction.** Successful, Failed, or
+  Postponed. An item whose instance ends without marking stays in-flight in the
+  queue and is invisible until something times it out.
+- **The two sides are independent.** Whichever side is not Maestro can be an RPA
+  robot, an integration, a web app, or a person uploading a file. Neither side
+  assumes the other is a Maestro process.
+
+## Shape
+
+Two separate shapes. Which you author depends on which side of the queue Maestro
+is on; author both when Maestro is on both.
+
+### Dispatcher — Maestro creates the items
+
+| Node | Element | Role |
+| --- | --- | --- |
+| `start` | `bpmn:startEvent` + message event definition | Entry |
+| `fetch_source` | `bpmn:serviceTask` | Placeholder · insertion point |
+| `bulk_add` | `bpmn:serviceTask` | Mechanism |
+| `end_queued` | `bpmn:endEvent` | Mechanism |
+
+Linear: `start` → `fetch_source` → `bulk_add` → `end_queued`. No conditions.
+One variable, `sourceItems` (jsonSchema), bound as the bulk-add input.
+
+Batches cap at 15,000 items and commit either all-or-nothing or per item. For
+one-at-a-time dispatch use the single create-item activity instead — same shape,
+different node.
+
+### Performer — Maestro processes the items
+
+The performer's start event **is** the queue trigger, so this shape always begins
+the process. It cannot be inserted into an existing path or nested in a
+subprocess, and it has no Entry row in the droppable sense.
+
+| Node | Element | Role |
+| --- | --- | --- |
+| `start` | `bpmn:startEvent` + message event definition, bound to the queue trigger | Mechanism |
+| `per_item_action` | `bpmn:serviceTask` | Placeholder |
+| `outcome_gate` | `bpmn:exclusiveGateway` | Mechanism |
+| `set_successful` | `bpmn:serviceTask` | Mechanism |
+| `set_failed` | `bpmn:serviceTask` | Mechanism |
+| `postpone` | `bpmn:serviceTask` | Mechanism |
+| `end_succeeded` / `end_failed` / `end_postponed` | `bpmn:endEvent` | Mechanism |
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `start` → `per_item_action` → `outcome_gate` | | |
+| `outcome_gate` → `set_successful` | Success | default |
+| `outcome_gate` → `set_failed` | Failure | `=vars.itemOutcome == "failure"` |
+| `outcome_gate` → `postpone` | Defer | `=vars.itemOutcome == "defer"` |
+| each status node → its end event | | |
+
+| Variable | Type | Holds |
+| --- | --- | --- |
+| `queueItem` | jsonSchema | The triggering item's payload |
+| `itemOutcome` | string | `success`, `failure`, or `defer` |
+
+## Variants
+
+Dispatcher and performer are not alternatives — they are the two halves, and
+which you author is a question about your architecture rather than the shape.
+
+| Maestro is | Author |
+| --- | --- |
+| The dispatcher; something else drains | Dispatcher shape |
+| The performer, hooked to an existing queue | Performer shape |
+| Both sides | Both shapes, as separate processes |
+
+The performer is the brownfield entry point: it attaches Maestro to a queue that
+already exists without touching whatever produces the items.
+
+## What to bind
+
+- **The queue** on every queue node. Never invent a queue name or key — it comes
+  from discovery or from the user (SKILL.md rule 2).
+- **`fetch_source`** — the upstream source, and the shaping of each item's
+  payload, priority, deadline, and optional postpone date.
+- **`per_item_action`** — the node that does the work at runtime: a UiPath
+  agent, Document Understanding, an API call, a HITL task, an RPA job, or a mix.
+- **`set_failed`** — include error type, reason, and detail; that is what makes
+  a failed transaction diagnosable later.
+- **`postpone`** — earliest reprocessing time, and a deadline if the item should
+  eventually stop being retried.
+
+The queue activity types this shape needs are newer than the extension list
+bundled with the validator, so do not assume the names. Resolve them with
+`uip maestro bpmn registry list --output json` and fetch each template with
+`registry get` before authoring — see
+[registry-workflow.md](../registry-workflow.md).
+
+## Adapting it
+
+Use single-item creation instead of bulk when items arrive one at a time; the
+dispatcher shape is otherwise unchanged.
+
+Drop the `defer` branch when nothing about the work is worth retrying later.
+Keep success and failure: those two are how the queue learns the item is done.
+
+Add an in-flight progress update inside `per_item_action` when operators need to
+watch long-running items move, rather than only seeing start and finish.
+
+## Composing
+
+Place `failure-escalation` **inside** the performer so a failure marks the
+transaction Failed and ends that item's instance, leaving the queue free to
+continue. Without it, a failure ends the instance without marking, and the item
+stays in-flight.
+
+The performer must be the outermost pattern in its process. Everything else it
+needs — a review, a wait — is inserted into or nested inside it, never the
+reverse. See [composing-guide.md](composing-guide.md).

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

@@ -0,0 +1,129 @@
+# Pattern: `smart-triage`
+
+Heterogeneous inbound work is classified and dispatched to the right handling
+for its category. Use it when volume is too high to sort by hand and the
+downstream paths are well defined.
+
+## Why it works
+
+These four carry the shape. Change one and you are building something else.
+
+- **The trigger normalizes the payload.** Everything downstream reads one shape,
+  so the same process serves email, tickets, forms, and webhooks. Routing never
+  learns where the item came from.
+- **Classification returns a category and a confidence.** Two values, so one
+  gateway can decide whether to trust the answer and a second can act on it.
+  A classifier returning only a category leaves nothing to gate on.
+- **The human fallback rejoins the same route gateway.** Low-confidence items go
+  to a person who picks the category, then dispatch through the identical exit.
+  One dispatch point, not two, so adding a category is one branch rather than
+  two.
+- **Triage dispatches and ends.** Each category's real work lives in its own
+  process. Keeping handling out of triage is what lets one triage process serve
+  many downstreams without becoming all of them.
+
+## Shape
+
+AI-based is the base shape. Categories `A`/`B`/`C` are illustrative — one branch
+per category the domain actually has.
+
+| Node | Element | Role |
+| --- | --- | --- |
+| `start` | `bpmn:startEvent` + message event definition | Entry |
+| `extract` | `bpmn:serviceTask` | Placeholder · insertion point |
+| `classify` | `bpmn:serviceTask` | Mechanism |
+| `conf_gate` | `bpmn:exclusiveGateway` | Mechanism |
+| `manual_triage` | `bpmn:userTask` | Mechanism |
+| `route_gate` | `bpmn:exclusiveGateway` | Mechanism |
+| `handle_a..c` | `bpmn:serviceTask` | Placeholder |
+| `routed_a..c` | `bpmn:endEvent` | Mechanism |
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `start` → `extract` → `classify` → `conf_gate` | | |
+| `conf_gate` → `route_gate` | Above floor | `=vars.aiConfidence >= 0.85` |
+| `conf_gate` → `manual_triage` | Below floor | `=vars.aiConfidence < 0.85` |
+| `manual_triage` → `route_gate` | | |
+| `route_gate` → `handle_a` | Category A | `=vars.routeCategory == "Category A"` |
+| `route_gate` → `handle_b` | Category B | `=vars.routeCategory == "Category B"` |
+| `route_gate` → `handle_c` | Category C | `=vars.routeCategory == "Category C"` |
+| `handle_a..c` → `routed_a..c` | | |
+
+`0.85` is an illustrative floor. Set it from how costly a misroute is against
+how much manual triage you can absorb.
+
+| Variable | Type | Holds |
+| --- | --- | --- |
+| `itemData` | jsonSchema | The normalized item the classifier reads |
+| `routeCategory` | string | The category to dispatch to |
+| `aiConfidence` | double | Classifier confidence, 0–1 |
+| `ruleMatched` | boolean | Rule-based and hybrid only |
+| `triageNote` | string | The manual triager's note, if any |
+
+## Variants
+
+| Variant | Question it answers | Delta |
+| --- | --- | --- |
+| AI-based | — | The shape above |
+| Rule-based | Are the categories decided by stable, auditable rules? | Business rule task and a match gateway |
+| Hybrid | Can rules handle the clear cases cheaply? | Rules first, classifier catches the rest |
+
+**Rule-based.** Replace `classify` and `conf_gate` with `apply_rules`
+(`bpmn:businessRuleTask`) and `rule_gate` (`bpmn:exclusiveGateway`).
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `rule_gate` → `route_gate` | Matched | `=vars.ruleMatched == true` |
+| `rule_gate` → `manual_triage` | No match | default |
+
+**Hybrid.** Keep both. Rules run first; an unmatched item falls through to the
+classifier rather than straight to a person, so only what neither resolves
+reaches manual triage.
+
+| Sequence flow | Label | Condition |
+| --- | --- | --- |
+| `rule_gate` → `route_gate` | Matched | `=vars.ruleMatched == true` |
+| `rule_gate` → `classify` | No match | default |
+| `conf_gate` → `route_gate` | Above floor | as above |
+| `conf_gate` → `manual_triage` | Below floor | as above |
+
+## What to bind
+
+- **`classify`** — the node that classifies at runtime, typically a UiPath agent
+  job. Place and bind it; never decide the categories or write classification
+  logic while authoring.
+- **`apply_rules`** — `Orchestrator.BusinessRules`. The rules are authored and
+  uploaded to Orchestrator separately, and the BPMN references them; there is no
+  in-file rule authoring. This applies to the rule-based and hybrid variants
+  both.
+- **`extract`** — Document Understanding, or any step that pulls the fields the
+  classifier needs out of an unstructured source.
+- **`handle_a..c`** — see Adapting below; usually a message dispatch rather than
+  work done here.
+- **`manual_triage`** — `Actions.HITL`. Bind the task's category output to
+  `routeCategory`, the same variable `route_gate` reads. Bound anywhere else,
+  low-confidence items dispatch on the classifier's original guess and the
+  review changes nothing.
+
+Fetch payloads through [registry-workflow.md](../registry-workflow.md).
+
+## Adapting it
+
+Add or remove category branches to match the domain. Each is one condition on
+`route_gate` plus its handler and end event.
+
+Drop `extract` when the trigger already delivers structured fields.
+
+The `handle_*` nodes are the pattern's main decision. Replacing each with a
+message that starts a separate process keeps triage thin, which is the intent.
+Filling them inline makes triage own the handling for every category it routes,
+and that is what the shape is trying to avoid — but it is a legitimate choice for
+one or two trivial categories.
+
+## Composing
+
+Each category's downstream is usually its own process, reached by message rather
+than nested — see
+[composing-guide.md](composing-guide.md#dispatched-by-message-to-a-separate-process).
+`approval-chain` is a common downstream. Add `failure-escalation` so a
+classifier or dispatch failure does not vanish.

package/skills/uipath-maestro-bpmn/references/registry-workflow.md

@@ -99,6 +99,12 @@ discovery or the user.
   `=bindings.<bindingId>`, and a `<uipath:binding>` of `resource="Connection"`
   with `propertyAttribute="ConnectionId"` in the process-level
   `<uipath:bindings>` holds the live connection id from `uip is connections list`.
+  The context field that carries the reference differs by node kind: activities
+  (`Intsvc.ActivityExecution`) use `connection`; connector **triggers and waits**
+  (`Intsvc.EventTrigger`, `Intsvc.WaitForEvent`) use `connectionId`. Either way
+  `uip maestro bpmn refresh` (and `pack`) materialize that binding into a
+  `Connection` resource in `bindings_v2.json` — without it the process passes
+  `validate` but faults at runtime with `Connection null` (error 102010).
 
 Declare all bindings in a single process-level `<uipath:bindings version="v1">`
 block. Each `<uipath:binding>` carries `id`, `resource`, `propertyAttribute`,
@@ -147,6 +153,15 @@ the CLI — the same enrichment path as `Intsvc.*` activities (§3). A hand-auth
 trigger shell stays **draft** until the CLI supplies the concrete trigger
 properties, connection binding, and schemas.
 
+For `Intsvc.EventTrigger` / `Intsvc.WaitForEvent` the connection is referenced
+from the node context as **`connectionId`** = `=bindings.<bindingId>` (activities
+use `connection`); the timer trigger binds no connection. After authoring the
+connection binding, run `uip maestro bpmn refresh <project>` so the binding is
+materialized into a `Connection` resource in `bindings_v2.json` — a trigger whose
+connection is not materialized passes `validate` but faults at runtime with a
+null connection (error 102010). Use `refresh`, not the deprecated
+`update-metadata`, which does not materialize connection bindings.
+
 ## Connectionless vs connector HTTP
 
 - **Connector activity** (`Intsvc.ActivityExecution` / a connector-authenticated