@uipath/skills 1.195.0

package/skills/uipath-maestro-flow/references/author/references/plugins/summarize/impl.md

@@ -0,0 +1,198 @@
+# Summarize Pattern Node — Implementation
+
+Summarize synthesizes a response grounded in an attached document. Node type: `uipath.pattern.deep-rag`. BPMN service task with `serviceType: "ECS.DeepRag"`. No process bindings, no connection binding — inputs are the only source of configuration.
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get uipath.pattern.deep-rag --output json
+```
+
+Confirm:
+
+- Input port: `input`
+- Output ports: `output`, `error`
+- `model.type` — `bpmn:ServiceTask`
+- `model.serviceType` — `ECS.DeepRag`
+- `inputDefinition.properties` — `attachment` (declared `string`; runtime wants the **full Flow Attachment object** `{ ID, FullName, MimeType, Metadata }` — keys are case-sensitive, `ID` is uppercase, not `Id` — Studio Web's file-picker form serializes the whole object into that slot, the engine deserializes it back), `prompt` (string), `returnCitations` (boolean)
+- `outputDefinition.output.type` — `"object"`; `outputDefinition.output.source` — `"=response"` (the BPMN engine wraps the result under that key — same convention as every other ServiceTask)
+- `outputDefinition.output.schema` — top-level fields `id` (string) and `content` (object|null) with PascalCase nested fields:
+  - `content.Text` — string
+  - `content.Citations` — array|null of `{ Ordinal: integer, PageNumber: integer, Source: string, Reference: string }`
+- `outputDefinition.error.schema.required` — `code`, `message`, `detail`, `category`, `status`
+
+If the command errors with **"Node type not found: uipath.pattern.deep-rag"**, the CLI build predates Summarize support or the tenant's `canvas.nodes.summarize` server flag is off. Run `uip tools update` and `uip maestro flow registry pull --force`; if it still errors, confirm with your UiPath admin that `canvas.nodes.summarize` is enabled on the tenant.
+
+## Adding / Editing
+
+Pattern nodes are OOTB BPMN service tasks — they are **user-owned** per [Author capability — Node ownership](../../../CAPABILITY.md#node-ownership--who-authors-the-node), so author them by editing the `.flow` JSON directly (Edit/Write). The `uip maestro flow node add` / `edge add` CLI is reserved for CLI-owned nodes (connectors, connector-triggers, managed HTTP), where the CLI populates product-managed state. For OOTB structural edits — adding the Summarize node, wiring its edges, adding the `attachment` flow input — use Edit/Write against the `.flow` file. See [editing-operations.md](../../editing-operations.md) for the JSON authoring mechanics; the snippets below cover what is **specific** to Summarize.
+
+## Wiring `attachment` — file variable bound to the trigger
+
+The canonical canvas-produced shape is a flow `in` variable of `type: "file"` bound to the trigger via `triggerNodeId`, with the Summarize node's `attachment` referencing it through the trigger's output:
+
+```json
+"variables": {
+  "globals": [
+    {
+      "id": "documentFile",
+      "direction": "in",
+      "type": "file",
+      "triggerNodeId": "start"
+    }
+  ]
+}
+```
+
+Then on the Summarize node:
+
+```json
+"inputs": {
+  "attachment": "=js:$vars.start.output.documentFile",
+  ...
+}
+```
+
+Populate that variable at runtime with `uip maestro flow debug --attachment <variableId>=<localPath>` (example: `--attachment documentFile=./path/to/doc.pdf` for the `documentFile` variable above). The CLI uploads the file and binds it as a `{ ID, FullName, MimeType, Metadata }` Attachment object — keys are case-sensitive; `ID` is uppercase, not `Id`. The flag is repeatable; the `<variableId>` (left of `=`) must match a `variables.globals[]` entry's `id` — see [cli-commands.md — Pre-flight](../../../../shared/cli-commands.md#pre-flight---attachment-binding). Do not declare the variable as `type: "object"`, do not reference it as `=js:$vars.<variableId>` directly without the trigger output path, and do not pass a bare GUID/URL/path/`.ID`/`.FullName`.
+
+## JSON Structure
+
+```json
+{
+  "id": "summarizeContract",
+  "type": "uipath.pattern.deep-rag",
+  "typeVersion": "1.0",
+  "display": { "label": "Summarize Contract" },
+  "inputs": {
+    "attachment": "=js:$vars.start.output.documentFile",
+    "prompt": "Write a 5-bullet executive summary covering scope, term, SLAs, penalties, and termination.",
+    "returnCitations": true
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "source": "=response",
+      "var": "output",
+      "schema": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "content": {
+            "type": ["object", "null"],
+            "properties": {
+              "Text": { "type": "string" },
+              "Citations": {
+                "type": ["array", "null"],
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "Ordinal":    { "type": "integer" },
+                    "PageNumber": { "type": "integer" },
+                    "Source":     { "type": "string" },
+                    "Reference":  { "type": "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "error": {
+      "type": "object",
+      "description": "Error information if the node fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+Notes:
+
+- **No instance-level `model` block.** BPMN type and `serviceType: "ECS.DeepRag"` live only in the corresponding `definitions[]` entry — copy that verbatim from `uip maestro flow registry get uipath.pattern.deep-rag --output json`. Per [Author capability, rule 15](../../../CAPABILITY.md), node instances normally have no `model` block.
+- **`typeVersion` must match `definitions[<deep-rag>].version` exactly** — set it to the `version` field from the `registry get uipath.pattern.deep-rag` response; do not guess. Use the registry's exact form (single-dot `x.y`, e.g. `"1.0"`, not `"1.0.0"`).
+- `outputs.output.source` is the literal **`=response`** (the convention every BPMN ServiceTask follows). Do not rewrite to `=deepRagResult` or similar.
+- `outputs.output.type` is **`"object"`**, with the nested PascalCase schema above.
+- Setting `returnCitations: true` populates `content.Citations`; setting `false` omits the array entirely (the downstream consumer should tolerate either).
+
+## End-node output mapping
+
+If the flow surfaces the synthesized text or citations as flow `out` variables, the End node must map them. Per [Author capability, rule 11](../../../CAPABILITY.md), value-field expressions need the `=js:` prefix. Note the **PascalCase** field names:
+
+```json
+{
+  "id": "end",
+  "type": "core.control.end",
+  "typeVersion": "1.0",
+  "outputs": {
+    "summary":   { "source": "=js:$vars.summarizeContract.output.content.Text" },
+    "citations": { "source": "=js:$vars.summarizeContract.output.content.Citations" }
+  }
+}
+```
+
+Without `=js:`, the runtime stores the literal string (e.g. `"$vars.summarizeContract.output.content.Text"`) into the flow output instead of the real value. When `returnCitations: false`, drop the `citations` mapping rather than mapping a missing field. Lowercase variants (`.text`, `.citations`) do not exist in the response shape — they would resolve to `undefined`.
+
+## Add via CLI (opt-in, not preferred)
+
+The `uip maestro flow node add` / `edge add` CLI is **not** the canonical authoring path for OOTB pattern nodes (see [Node ownership](../../../CAPABILITY.md#node-ownership--who-authors-the-node) — pattern nodes are user-owned). Reach for it only when scripting in a context where Edit/Write isn't available. The shape:
+
+```bash
+uip maestro flow node add <FlowName>.flow uipath.pattern.deep-rag \
+  --label "<LABEL>" \
+  --input '{
+    "attachment": "=js:$vars.<triggerId>.output.<fileVarId>",
+    "prompt": "<INSTRUCTION for the synthesis>",
+    "returnCitations": true
+  }' \
+  --output json
+```
+
+`attachment` must resolve to a **full Flow Attachment object** `{ ID, FullName, MimeType, Metadata }` — keys are case-sensitive; `ID` is uppercase, not `Id`. Reference it through the trigger's output (`$vars.<triggerId>.output.<fileVarId>`) — that's how the canvas wires file-typed flow `in` variables. Do **not** pass a bare GUID, URL, byte stream, or path; even though the OOTB `inputDefinition` declares `type: "string"`, the engine wants the object. Set `returnCitations: false` (or omit) when downstream consumers do not need page-level provenance.
+
+## Accessing Output
+
+```javascript
+// Downstream Script node
+const result = $vars.summarizeContract.output;
+const text = result.content.Text;                   // the synthesized prose
+const citations = result.content.Citations ?? [];   // [{ Ordinal, PageNumber, Source, Reference }, ...]
+return {
+  summary: text,
+  citationCount: citations.length,
+};
+```
+
+Field names are **PascalCase** (`Text`, `Citations`, `Ordinal`, `PageNumber`, `Source`, `Reference`). If `returnCitations: false`, the `Citations` array is not present. Guard with `?? []` or check `result.content.Citations != null` before iterating.
+
+## Validate
+
+```bash
+uip maestro flow validate <FlowName>.flow --output json
+```
+
+The validator checks that required inputs (`attachment`, `prompt`) are present and non-empty.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| `Node type not found: uipath.pattern.deep-rag` | CLI predates Summarize support, or tenant flag `canvas.nodes.summarize` is off | `uip tools update`, `uip maestro flow registry pull --force`; check with admin that `canvas.nodes.summarize` is enabled if still missing |
+| Runtime: synthesis returns empty `content.Text` | Prompt too vague, or attachment unreadable (image-only PDF with no OCR, corrupted file) | Tighten the prompt; confirm the attachment type is supported and has selectable text |
+| `content.Citations` missing even though set `returnCitations: true` | Downstream consumer read the node's `inputDefaults` before the runtime produced the output | Reference `$vars.{nodeId}.output.content.Citations` only in nodes downstream of Summarize; do not precompute |
+| Downstream `result.content.text` / `result.content.citations` is `undefined` | Used lowercase field names — the response shape is PascalCase | Switch to `result.content.Text` / `result.content.Citations` |
+| Large documents time out | Synthesis cost scales with doc size; single call is bounded | Split the document upstream (per-section Summarize calls + a final merge step) or move to a published [Agent](../agent/impl.md) with a context-grounding resource |
+| Wrong citations (pages off by one, wrong source) | The attached document's page numbering doesn't match the displayed page ordinal | Treat `Ordinal` and `PageNumber` as advisory — present `Source`/`Reference` alongside and let the reader verify |
+
+## What NOT to Do
+
+- **Do not hand-author `model.bindings`** on the node — Summarize has no process or connector binding. Adding a `bindings` block will be stripped or cause validate errors.
+- **Do not pass `--source` on `uip maestro flow node add`** — `--source` is only for inline agent nodes. Summarize has no agent project behind it.
+- **Do not chain Summarize for multi-turn chat.** It is single-turn; each call is independent. Use a published [Agent](../agent/impl.md) for conversational flows.
+- **Do not stuff `prompt` with entire document text.** The attachment is already ingested — the prompt should describe **the task**, not the input.
+- **Do not assume `content.Citations` is always present.** When `returnCitations: false`, the field is omitted; downstream code must guard.
+- **Do not use lowercase field names** (`content.text`, `content.citations`, `.ordinal`, `.page`). The runtime emits PascalCase: `content.Text`, `content.Citations`, `Ordinal`, `PageNumber`, `Source`, `Reference`.
+- **Do not pass `attachment` as a bare string id, GUID, URL, or path.** The OOTB schema and Studio Web's file-picker UI suggest a string, but the runtime needs the **full Flow Attachment object** `{ ID, FullName, MimeType, Metadata }` — keys are case-sensitive; `ID` is uppercase, not `Id`. The canonical wiring is a flow `in` variable of `type: "file"` bound to the trigger via `triggerNodeId`, referenced as `=js:$vars.<triggerId>.output.<fileVarId>` (see Key Inputs in `planning.md`). Bare-id mistakes pass `flow validate` cleanly and fault at runtime.
+- **Do not write `outputs.output.source: "=deepRagResult"`.** The canonical value is `"=response"` (the convention every BPMN ServiceTask follows).

package/skills/uipath-maestro-flow/references/author/references/plugins/summarize/planning.md

@@ -0,0 +1,71 @@
+# Summarize Pattern Node — Planning
+
+The Summarize node runs comprehensive document synthesis over an attached file (PDF, Word, etc.): ingest, retrieve, reason, and return prose — optionally with per-sentence citations back to the source pages. It sits in the **Document Processing** category of the add-node panel.
+
+## Node Type
+
+`uipath.pattern.deep-rag`
+
+(The wire type still reads `deep-rag` even though the canvas display name is "Summarize" — the node type is contractual with the runtime serializer and was not renamed.)
+
+Fixed OOTB node type — no registry suffix, one version. It does not appear in `uip maestro flow registry list` unless the tenant has the platform-side `canvas.nodes.summarize` feature flag enabled. The uip CLI unconditionally requests this flag in its manifest fetch, so the node will appear once the server rolls it out to your tenant.
+
+## When to Use
+
+Use Summarize when the task is **"read this document and produce a thorough answer"** — summarization, Q&A, compliance checks, executive briefs — where depth matters and traceability back to the source is valuable.
+
+### Selection Heuristics
+
+| Situation | Use Summarize? |
+| --- | --- |
+| Summarize a long document (contract, policy, research paper) | Yes |
+| Answer a free-form question grounded in one attached document | Yes |
+| Produce a report where every claim must cite the source page | Yes — set `returnCitations: true` |
+| Short, single-turn Q&A over small text in-memory | No — use [Agent](../agent/planning.md) or [Script](../script/planning.md) |
+| Row-by-row enrichment of tabular data | No — use [Batch Transform](../batch-transform/planning.md) |
+| Multi-document retrieval across a corpus | No — Summarize is scoped to one attachment per call. Chain multiple Summarize nodes (one per doc) and merge results, or use a published [Agent](../agent/planning.md) with a context-grounding resource |
+| The user wants to chat with the document | No — Summarize is single-turn. Use an [Agent](../agent/planning.md) with a context resource for conversational behavior |
+
+### Anti-Patterns
+
+- **Do not use Summarize for small/simple text.** For a few paragraphs inline in `$vars`, a [Script](../script/planning.md) or [Agent](../agent/planning.md) is cheaper and faster.
+- **Do not use Summarize as a general agent.** It cannot call tools, escalate, or loop — it is a single synthesis step. For multi-step reasoning with tool use, use an [Agent](../agent/planning.md).
+- **Do not chain multiple Summarize nodes to emulate multi-document retrieval if the answer requires cross-document reasoning.** Per-document synthesis then merging loses cross-doc grounding. Use a published [Agent](../agent/planning.md) with a proper retrieval resource instead.
+
+## Ports
+
+| Port | Position | Direction | Use |
+| --- | --- | --- | --- |
+| `input` | left | target | Flow sequence input |
+| `output` | right | source | Synthesis text (plus citations if enabled) |
+| `error` | right | source | Error handler |
+
+No artifact ports. Pattern-style nodes do not wire to resource files — the prompt lives on the node inputs.
+
+## Output Variables
+
+`$vars.{nodeId}.output` is an object whose schema is published on the OOTB definition (also mirrored on the node instance's `outputs.output.schema`):
+
+- `id` — string, the result identifier
+- `content` — `object | null`
+  - `content.Text` — string, the synthesized prose
+  - `content.Citations` — `array | null`, present only when `returnCitations: true`. Each entry: `{ Ordinal: integer, PageNumber: integer, Source: string, Reference: string }`
+
+Note the **PascalCase** field names (`Text`, `Citations`, `Ordinal`, `PageNumber`, `Source`, `Reference`) — the runtime emits them this way to match the engine response shape; lowercase variants (`text`, `citations`, `page`) are wrong.
+
+`$vars.{nodeId}.error` — populated on failure: `{ code, message, detail, category, status }`.
+
+## Key Inputs
+
+| Input | Required | Type | Description |
+| --- | --- | --- | --- |
+| `attachment` | Yes | full Flow Attachment | The runtime engine wants the **full Flow Attachment object** `{ ID, FullName, MimeType, Metadata }` — keys are case-sensitive; `ID` is uppercase, not `Id`. Source it as a flow-level `in` variable of `type: "file"` bound to the trigger via `triggerNodeId: "<triggerId>"`. The variable's payload is populated by `uip maestro flow debug --attachment <fileVarId>=<path>` (repeatable; `<fileVarId>=` must match the variable's `id` — see [cli-commands.md — Pre-flight](../../../../shared/cli-commands.md#pre-flight---attachment-binding)). Reference it on the Summarize node as `=js:$vars.<triggerId>.output.<fileVarId>` — that path resolves to the whole Attachment object at runtime. The OOTB `inputDefinition.attachment` declares `type: "string"` because Studio Web's file-picker form serializes the object into that string slot at save time; the engine deserializes it back. **Never** wire a bare GUID, URL, byte stream, file path, or `.ID`/`.FullName` subfield. |
+| `prompt` | Yes | string | The task instruction — e.g., "Write a 3-paragraph executive summary", "List every SLA penalty clause", "Answer: what is the termination notice period?". |
+| `returnCitations` | No | boolean | When `true`, the `content.Citations` array is populated with per-claim page references. Default `false`. |
+
+## Planning Annotation
+
+In the architectural plan:
+
+- `pattern: summarize — <one-line purpose>` with a placeholder for the attachment source (a `=js:$vars.<triggerId>.output.<fileVarId>` reference to a trigger-bound `in` variable of `type: "file"`) and a short summary of the prompt.
+- If the downstream step needs to display or audit sources, call out `returnCitations: true` explicitly in the node table; otherwise leave it `false`.

package/skills/uipath-maestro-flow/references/author/references/plugins/switch/impl.md

@@ -0,0 +1,60 @@
+# Switch Node — Implementation
+
+## Node Type
+
+`core.logic.switch`
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get core.logic.switch --output json
+```
+
+Confirm: input port `input`, dynamic output ports `case-{id}` + `default`, required input `cases`. Set the node instance `typeVersion` to the `version` field from this response — do not hardcode it.
+
+## JSON Structure
+
+```json
+{
+  "id": "routeByPriority",
+  "type": "core.logic.switch",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Route by Priority" },
+  "inputs": {
+    "cases": [
+      {
+        "id": "high",
+        "label": "High Priority",
+        "expression": "$vars.classify.output.priority === 'high'"
+      },
+      {
+        "id": "medium",
+        "label": "Medium Priority",
+        "expression": "$vars.classify.output.priority === 'medium'"
+      },
+      {
+        "id": "low",
+        "label": "Low Priority",
+        "expression": "$vars.classify.output.priority === 'low'"
+      }
+    ]
+  }
+}
+```
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure above for the node-specific `inputs`.
+
+## Wiring
+
+Each case creates a dynamic output port `case-{id}`. An optional `default` port handles unmatched values. Ensure edge `sourcePort` matches `case-{id}` exactly. See [editing-operations.md](../../editing-operations.md) for edge add procedures.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| No case matched, no default wired | All case expressions false and no default edge | Add a `default` edge or ensure cases are exhaustive |
+| Case expression error | Invalid JavaScript in case expression | Check `=js:` expression syntax |
+| Wrong port name in edge | Port ID doesn't match case ID | Ensure edge `sourcePort` is `case-{id}` matching the case's `id` field |
+| `$vars.nodeId` is undefined | Upstream node not connected or wrong ID | Check edges and node IDs |

package/skills/uipath-maestro-flow/references/author/references/plugins/switch/planning.md

@@ -0,0 +1,38 @@
+# Switch Node — Planning
+
+## Node Type
+
+`core.logic.switch`
+
+## When to Use
+
+Use a Switch node for multi-way branching (3+ paths) based on ordered case expressions. Cases are evaluated in order; the first `true` case is taken.
+
+### Selection Heuristics
+
+| Situation | Use Switch? |
+| --- | --- |
+| Three or more paths based on different conditions | Yes |
+| Simple true/false branch | No — use [Decision](../decision/planning.md) |
+| Branch on HTTP response status codes | No — use [HTTP](../http/planning.md) built-in branches |
+| Branch requires reasoning on ambiguous input | No — use [Agent](../agent/planning.md) |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `case-{id}` (dynamic per case), `default` |
+
+## Key Inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `cases` | Yes | Array of `{ id, label, expression }` (min 1 item) |
+
+Each case creates a dynamic output port: `case-{item.id}`. An optional `default` port handles unmatched cases.
+
+## Wiring Rules
+
+- Switch nodes produce one outgoing edge per case + optionally one from `default`
+- Each case edge uses `sourcePort: "case-{id}"` where `{id}` matches the case's `id` field
+- Every case branch must lead to a downstream node

package/skills/uipath-maestro-flow/references/author/references/plugins/terminate/impl.md

@@ -0,0 +1,45 @@
+# Terminate Node — Implementation
+
+## Node Type
+
+`core.logic.terminate`
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get core.logic.terminate --output json
+```
+
+Confirm: input port `input`, no output ports. Set the node instance `typeVersion` to the `version` field from this response — do not hardcode it.
+
+## JSON Structure
+
+```json
+{
+  "id": "abortOnError",
+  "type": "core.logic.terminate",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Abort" },
+  "inputs": {}
+}
+```
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure above for the node-specific `inputs`.
+
+## Common Pattern — Error Handler
+
+```text
+HTTP Request -> Decision (error?) -> true -> Log Error (Script) -> Terminate
+                                  -> false -> Process -> End
+```
+
+The Decision node checks `$vars.httpCall.error`, routes to a Script that logs the error, then Terminate aborts the flow.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Terminate has outgoing edges | Wired an edge from Terminate to another node | Remove — Terminate has no output ports |
+| Workflow outputs missing | Expected outputs but hit Terminate | Terminate does not produce outputs — use End for paths that need output mapping |

package/skills/uipath-maestro-flow/references/author/references/plugins/terminate/planning.md

@@ -0,0 +1,29 @@
+# Terminate Node — Planning
+
+## Node Type
+
+`core.logic.terminate`
+
+## When to Use
+
+Use a Terminate node to abort the entire flow immediately on a fatal error. Unlike End, Terminate kills all branches.
+
+### Selection Heuristics
+
+| Situation | Use Terminate? |
+| --- | --- |
+| Fatal error — continuing other branches would be harmful | Yes |
+| Normal completion of one execution path | No — use [End](../end/planning.md) |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | — (none) |
+
+## Key Rules
+
+- Terminate stops the entire workflow immediately — all parallel branches are killed
+- No output mapping — Terminate does not produce workflow outputs
+- Use for error paths where recovery is not possible
+- **End vs Terminate:** End = graceful completion of one path. Terminate = abort everything.