@uipath/skills 1.204.0 → 1.204.1

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

@@ -0,0 +1,107 @@
+# Agentic Process Node — Implementation
+
+Agentic process nodes invoke orchestration processes. Pattern: `uipath.core.agentic-process.{key}`.
+
+## Discovery
+
+### Published (tenant registry)
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "uipath.core.agentic-process" --output json
+```
+
+### In-solution (sibling projects)
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+## Registry Validation
+
+```bash
+# Published
+uip maestro flow registry get "uipath.core.agentic-process.{key}" --output json
+
+# In-solution
+uip maestro flow registry get "uipath.core.agentic-process.{key}" --local --output json
+```
+
+Confirm:
+
+- Input port: `input`
+- Output port: `output`
+- `model.serviceType` — `Orchestrator.StartAgenticProcess`
+- `model.bindings.resourceSubType` — `ProcessOrchestration`
+- `model.bindings.resourceKey` — the `<FolderPath>.<ProcessName>` string used to scope binding resolution
+- `inputDefinition` — typically empty
+- `outputDefinition.error` — error schema
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure below for the node-specific `inputs`.
+
+## JSON Structure
+
+### Node instance (inside `nodes[]`)
+
+The instance carries only per-instance data (`inputs`, `outputs`, `display`). BPMN type, serviceType, version, and binding/context templates come from the definition in `definitions[]`.
+
+```json
+{
+  "id": "runOrchestration",
+  "type": "uipath.core.agentic-process.5f9ad95a-b862-46c7-98c3-a9be2e5b922f",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Run Orchestration" },
+  "inputs": {},
+  "outputs": {
+    "error": {
+      "type": "object",
+      "description": "Error information if the agentic process fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+**Declare `error` only — `output` is derived.** Authoring it makes the converter copy your `source` verbatim; `"=result.response"` then resolves to null at runtime while `flow validate` passes. See [file-format.md § Node outputs](../../../shared/file-format.md#node-outputs).
+
+### Top-level `bindings[]` entries (sibling of `nodes`/`edges`/`definitions`)
+
+Add one entry per `(resourceKey, propertyAttribute)` pair. Share entries across node instances that reference the same agentic process — do NOT create duplicates.
+
+```json
+"bindings": [
+  {
+    "id": "bRunOrchestrationName",
+    "name": "name",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "Shared.My Orchestration",
+    "default": "My Orchestration",
+    "propertyAttribute": "name",
+    "resourceSubType": "ProcessOrchestration"
+  },
+  {
+    "id": "bRunOrchestrationFolderPath",
+    "name": "folderPath",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "Shared.My Orchestration",
+    "default": "Shared",
+    "propertyAttribute": "folderPath",
+    "resourceSubType": "ProcessOrchestration"
+  }
+]
+```
+
+> For the resolution mechanics and why these entries are required, see [file-format.md — Bindings](../../../shared/file-format.md#bindings--orchestrator-resource-bindings-top-level-bindings).
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Node type not found in registry | Process not published or registry stale | Run `uip login` then `uip maestro flow registry pull --force`; for in-solution processes use `--local` |
+| Process execution failed | Underlying orchestration errored | Check `$vars.{nodeId}.error` for details |

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

@@ -0,0 +1,61 @@
+# Agentic Process Node — Planning
+
+Agentic process nodes invoke orchestration processes from within a flow. Published processes appear in the registry after `uip login` + `uip maestro flow registry pull`. **In-solution** (unpublished) processes in sibling projects are discovered via `--local` — no login or publish required.
+
+## Node Type Pattern
+
+`uipath.core.agentic-process.{key}`
+
+## When to Use
+
+Use an Agentic Process node when the flow needs to invoke a published orchestration process.
+
+### Selection Heuristics
+
+| Situation | Use Agentic Process? |
+| --- | --- |
+| Invoke a published orchestration process | Yes |
+| Invoke a published AI agent | No — use [Agent](../agent/planning.md) |
+| Call another published flow | No — use [Flow](../flow/planning.md) |
+| Need desktop/browser automation | No — use [RPA Workflow](../rpa/planning.md) |
+| Process not yet published but in the same solution | Yes — discover with `--local` (no login or publish needed) |
+| Process does not exist yet | Create it in the same solution, then use `--local` discovery |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `output`, `error` |
+
+The `error` port is the implicit error port shared with all action nodes — see [Implicit error port on action nodes](../../../shared/file-format.md#implicit-error-port-on-action-nodes).
+
+## Output Variables
+
+- `$vars.{nodeId}.error` — error details if execution fails (`code`, `message`, `detail`, `category`, `status`)
+
+## Discovery
+
+### Published (tenant registry)
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "uipath.core.agentic-process" --output json
+```
+
+Requires `uip login`. Only published agentic processes from your tenant appear.
+
+### In-solution (sibling projects)
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+No login or publish required. Discovers unpublished agentic processes in sibling projects within the same solution.
+
+## Planning Annotation
+
+In the architectural plan:
+
+- If the process exists: note as `resource: <name> (agentic-process)`
+- If it does not exist: note as `[CREATE NEW] <description>`

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

@@ -0,0 +1,108 @@
+# API Workflow Node — Implementation
+
+API workflow nodes invoke API functions. Pattern: `uipath.core.api-workflow.{key}`.
+
+## Discovery
+
+### Published (tenant registry)
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "uipath.core.api-workflow" --output json
+```
+
+### In-solution (sibling projects)
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+## Registry Validation
+
+```bash
+# Published
+uip maestro flow registry get "uipath.core.api-workflow.{key}" --output json
+
+# In-solution
+uip maestro flow registry get "uipath.core.api-workflow.{key}" --local --output json
+```
+
+Confirm:
+
+- Input port: `input`
+- Output port: `output`
+- `model.serviceType` — `Orchestrator.ExecuteApiWorkflowAsync`
+- `model.bindings.resourceSubType` — `Api`
+- `model.bindings.resourceKey` — the `<FolderPath>.<ApiName>` string used to scope binding resolution
+- `inputDefinition` — typically empty
+- `outputDefinition` — always `error` (`source: "=Error"`). Whether it also declares `output` varies per published API workflow; either way, do not author `output` on the instance (see § JSON Structure)
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure below for the node-specific `inputs`.
+
+## JSON Structure
+
+### Node instance (inside `nodes[]`)
+
+The instance carries only per-instance data (`inputs`, `outputs`, `display`). BPMN type, serviceType, version, and binding/context templates come from the definition in `definitions[]`.
+
+```json
+{
+  "id": "callApiFunction",
+  "type": "uipath.core.api-workflow.346b8959-c126-48d3-9c46-942abcf944d7",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Call API Function" },
+  "inputs": {},
+  "outputs": {
+    "error": {
+      "type": "object",
+      "description": "Error information if the API workflow fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+**Declare `error` only — `output` is derived.** Authoring it makes the converter copy your `source` verbatim; `"=result.response"` then resolves to null at runtime while `flow validate` passes. See [file-format.md § Node outputs](../../../shared/file-format.md#node-outputs).
+
+### Top-level `bindings[]` entries (sibling of `nodes`/`edges`/`definitions`)
+
+Add one entry per `(resourceKey, propertyAttribute)` pair. Share entries across node instances that reference the same API workflow — do NOT create duplicates.
+
+```json
+"bindings": [
+  {
+    "id": "bCallApiFunctionName",
+    "name": "name",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "Shared.My API Function",
+    "default": "My API Function",
+    "propertyAttribute": "name",
+    "resourceSubType": "Api"
+  },
+  {
+    "id": "bCallApiFunctionFolderPath",
+    "name": "folderPath",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "Shared.My API Function",
+    "default": "Shared",
+    "propertyAttribute": "folderPath",
+    "resourceSubType": "Api"
+  }
+]
+```
+
+> For the resolution mechanics and why these entries are required, see [file-format.md — Bindings](../../../shared/file-format.md#bindings--orchestrator-resource-bindings-top-level-bindings).
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Node type not found in registry | API workflow not published or registry stale | Run `uip login` then `uip maestro flow registry pull --force`; for in-solution API workflows use `--local` |
+| Execution failed | Underlying API workflow errored | Check `$vars.{nodeId}.error` for details |
+| Node Completed but `$vars.{nodeId}.output` is null downstream (consumer agent faults `AGENT_STARTUP.INPUT_VALIDATION_ERROR` / incident `170002`) | Instance declares `outputs.output` with `source: "=result.response"`, suppressing the injected `=this` output | Delete the `output` entry — keep `error` only |

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

@@ -0,0 +1,60 @@
+# API Workflow Node — Planning
+
+API workflow nodes invoke API functions from within a flow. Published API workflows appear in the registry after `uip login` + `uip maestro flow registry pull`. **In-solution** (unpublished) API workflows in sibling projects are discovered via `--local` — no login or publish required.
+
+## Node Type Pattern
+
+`uipath.core.api-workflow.{key}`
+
+## When to Use
+
+Use an API Workflow node when the flow needs to call a published UiPath API function.
+
+### Selection Heuristics
+
+| Situation | Use API Workflow? |
+| --- | --- |
+| Call a published UiPath API function | Yes |
+| Call an external REST API | No — use [HTTP](../http/planning.md) or [Connector](../connector/planning.md) |
+| Invoke a published RPA process | No — use [RPA Workflow](../rpa/planning.md) |
+| API workflow not yet published but in the same solution | Yes — discover with `--local` (no login or publish needed) |
+| API workflow does not exist yet | Create it in the same solution, then use `--local` discovery |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `output`, `error` |
+
+The `error` port is the implicit error port shared with all action nodes — see [Implicit error port on action nodes](../../../shared/file-format.md#implicit-error-port-on-action-nodes).
+
+## Output Variables
+
+- `$vars.{nodeId}.error` — error details if execution fails (`code`, `message`, `detail`, `category`, `status`)
+
+## Discovery
+
+### Published (tenant registry)
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "uipath.core.api-workflow" --output json
+```
+
+Requires `uip login`. Only published API workflows from your tenant appear.
+
+### In-solution (sibling projects)
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+No login or publish required. Discovers unpublished API workflows in sibling projects within the same solution.
+
+## Planning Annotation
+
+In the architectural plan:
+
+- If the API workflow exists: note as `resource: <name> (api-workflow)`
+- If it does not exist: note as `[CREATE NEW] <description>`

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

@@ -0,0 +1,171 @@
+# Batch Transform Pattern Node — Implementation
+
+Batch Transform runs an LLM row-by-row over an attached CSV and appends LLM-generated columns. Node type: `uipath.pattern.batch-transform`; BPMN service task with `serviceType: "ECS.BatchTransform"`. It has no process or connection bindings; inputs are the only configuration source.
+
+## Registry validation
+
+Run:
+
+```bash
+uip maestro flow registry get uipath.pattern.batch-transform --output json
+```
+
+Confirm:
+
+- Input port: `input`.
+- Output ports: `output`, `error`.
+- `model.type`: `bpmn:ServiceTask`.
+- `model.serviceType`: `ECS.BatchTransform`.
+- `inputDefinition.properties`: `attachment` (declared `string`, but runtime requires the full Flow Attachment object `{ ID, FullName, MimeType, Metadata }`; keys are case-sensitive and `ID` is uppercase), `prompt` (string), `enableWebSearchGrounding` (boolean), and `outputColumns` (array of `{ name, description }`). Studio Web's file-picker form serializes the whole object into `attachment` and the engine deserializes it back.
+- `outputDefinition.output.type`: `"file"`.
+- `outputDefinition.output.source`: `"=response"` (the BPMN engine wraps the result under that key, as for every ServiceTask).
+- `outputDefinition.error.schema.required`: `code`, `message`, `detail`, `category`, `status`.
+
+If the command reports **"Node type not found: uipath.pattern.batch-transform"**, run `uip tools update` and `uip maestro flow registry pull --force`. If it still fails, this CLI build does not carry the node — there is no tenant setting behind it and no admin to escalate to.
+
+## Add or edit the node
+
+Pattern nodes are OOTB BPMN service tasks and are **user-owned** per [Author capability — Node ownership](../../CAPABILITY.md#node-ownership--who-authors-the-node). Author them by editing the `.flow` JSON directly with Edit/Write. The `uip maestro flow node add` / `edge add` CLI is reserved for CLI-owned nodes such as connectors, connector-triggers, and managed HTTP. Use Edit/Write for OOTB structural edits—adding the node, wiring edges, and adding the `attachment` flow input. See [editing-operations.md](../../editing-operations.md) for JSON authoring mechanics.
+
+## Attachment wiring
+
+Declare a flow `in` variable of `type: "file"` bound to the trigger by `triggerNodeId`:
+
+```json
+"variables": {
+  "globals": [
+    {
+      "id": "csvFile",
+      "direction": "in",
+      "type": "file",
+      "triggerNodeId": "start"
+    }
+  ]
+}
+```
+
+Reference it through the trigger output:
+
+```json
+"attachment": "=js:$vars.start.output.csvFile"
+```
+
+Populate it by running `uip maestro flow debug --attachment <variableId>=<localPath>` (for example, `--attachment csvFile=./path/to/data.csv`). The flag is repeatable; `<variableId>` must match a `variables.globals[]` entry's `id`. See [cli-commands.md — Pre-flight](../../../shared/cli-commands.md#pre-flight---attachment-binding). The CLI uploads the file and binds a full Flow Attachment object `{ ID, FullName, MimeType, Metadata }`; `ID` is uppercase, not `Id`.
+
+Do not declare the variable as `type: "object"`, reference it directly as `=js:$vars.<variableId>` without the trigger output path, or pass a bare GUID, URL, path, `.ID`, or `.FullName`.
+
+## JSON structure
+
+```json
+{
+  "id": "categorizeRows",
+  "type": "uipath.pattern.batch-transform",
+  "typeVersion": "1.0",
+  "display": { "label": "Categorize Invoices" },
+  "inputs": {
+    "attachment": "=js:$vars.start.output.csvFile",
+    "prompt": "Classify each invoice by category and write a one-line summary.",
+    "enableWebSearchGrounding": false,
+    "outputColumns": [
+      { "name": "Category", "description": "One of: Utility, Software, Travel, Other" },
+      { "name": "Summary", "description": "Plain-English one-line summary of the invoice" }
+    ]
+  },
+  "outputs": {
+    "output": { "type": "file", "source": "=response", "var": "output" },
+    "error": {
+      "type": "object",
+      "description": "Error information if the node fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+Rules:
+
+- Do not add an instance-level `model` block. BPMN type and `serviceType: "ECS.BatchTransform"` belong only in the corresponding `definitions[]` entry; copy that entry verbatim from `uip maestro flow registry get uipath.pattern.batch-transform --output json`. Per [Author capability, rule 15](../../CAPABILITY.md), node instances normally have no `model` block.
+- Set `typeVersion` exactly to `definitions[<batch-transform>].version` from the registry response. Do not guess; use the registry's exact single-dot `x.y` form, such as `"1.0"`, not `"1.0.0"`.
+- `inputs.outputColumns` must be an array of objects with exactly `name` and `description`; do not use a map or string array.
+- Set `outputs.output.source` to the literal `=response`, not `=batchTransformResult`, `=result.output`, or another value.
+- Set `outputs.output.type` to `"file"`; the result is a file handle, not a row array.
+
+## End-node output mapping
+
+When exposing the result through a flow `out` variable, map the file handle with an `=js:` value expression. Per [Author capability, rule 11](../../CAPABILITY.md), use:
+
+```json
+{
+  "id": "end",
+  "type": "core.control.end",
+  "typeVersion": "1.0",
+  "outputs": {
+    "result": { "source": "=js:$vars.categorizeRows.output" }
+  }
+}
+```
+
+Without `=js:`, the runtime stores the literal string `"$vars.categorizeRows.output"`.
+
+## Add via CLI (opt-in, not preferred)
+
+The `uip maestro flow node add` / `edge add` CLI is not canonical for OOTB pattern nodes because they are user-owned. Use it only when scripting where Edit/Write is unavailable:
+
+```bash
+uip maestro flow node add <FlowName>.flow uipath.pattern.batch-transform \
+  --label "<LABEL>" \
+  --input '{
+    "attachment": "=js:$vars.<triggerId>.output.<fileVarId>",
+    "prompt": "<INSTRUCTION describing every output column>",
+    "outputColumns": [
+      { "name": "<COLUMN_NAME>", "description": "<WHAT TO PUT IN THIS COLUMN>" }
+    ],
+    "enableWebSearchGrounding": false
+  }' \
+  --output json
+```
+
+`attachment` must resolve through `$vars.<triggerId>.output.<fileVarId>` to the full Flow Attachment object `{ ID, FullName, MimeType, Metadata }`, with case-sensitive keys and uppercase `ID`. Do not pass a bare GUID, URL, byte stream, or path, even though the OOTB `inputDefinition` declares `type: "string"`.
+
+## Output access
+
+`$vars.{nodeId}.output` is a file handle, not transformed rows. Pass it to a downstream file-consuming node, such as another Batch Transform, an upload/download HTTP or connector step, or a Script that fetches and parses it:
+
+```javascript
+const resultFile = $vars.categorizeRows.output;
+return { resultFile };
+```
+
+To obtain rows as JSON, add a downstream step that fetches and parses the file. Batch Transform never materializes rows into `$vars`.
+
+## Validate
+
+Run:
+
+```bash
+uip maestro flow validate <FlowName>.flow --output json
+```
+
+The validator checks that `attachment`, `prompt`, and `outputColumns` are present and non-empty, and that each `outputColumns` entry has `name` and `description`. It may not catch a bare attachment identifier; such mistakes can pass validation and fail at runtime.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| `Node type not found: uipath.pattern.batch-transform` | This CLI build predates Batch Transform support | Run `uip tools update`, then `uip maestro flow registry pull --force`; no tenant setting governs this, so there is no admin to escalate to |
+| Validate rejects `outputColumns` | Wrong shape, such as a map `{ name: description }` or string array | Use `[{ "name": "...", "description": "..." }, ...]` |
+| Runtime error `exceeded maxColumns` | More than 10 output columns | Reduce to ≤10 or split across two Batch Transform nodes chained on the output file |
+| All rows produce blank values for a column | `description` is vague or references fields absent from the source CSV | Name the source column(s) in the description and test with a small sample |
+| Latency spikes / higher cost than expected | `enableWebSearchGrounding: true` is unnecessary | Set it to false unless rows need facts the LLM cannot infer from the row itself |
+| Output file has the original row count but no new columns | Requested transformations duplicate source columns, so the LLM skipped them | Ensure every `outputColumns[].name` is new and not already in the source CSV |
+
+## What not to do
+
+- Do not hand-author `model.bindings`; Batch Transform has no process or connector binding. A `bindings` block may be stripped or cause validation errors.
+- Do not pass `--source` to `uip maestro flow node add`; `--source` is only for inline agent nodes (`uipath.agent.autonomous`).
+- Do not reshape `outputColumns` into a map; the array of `{name, description}` is contractual with the canvas property panel and BPMN `ECS.BatchTransform` serializer.
+- Do not reference downstream rows inside the prompt; rows are processed independently and sibling rows are unavailable. Pre-aggregate or use [Summarize](../summarize/impl.md) on a synthesized document instead.
+- Do not chain `$vars.{nodeId}.output` directly into a Script expecting rows; it is a file handle.
+- Do not pass `attachment` as a bare string id, GUID, URL, or path. The runtime requires `{ ID, FullName, MimeType, Metadata }`, with uppercase `ID`; use a `type: "file"` flow `in` variable bound by `triggerNodeId` and reference it as `=js:$vars.<triggerId>.output.<fileVarId>` (see Key Inputs in `planning.md).
+- Do not write `outputs.output.source: "=batchTransformResult"`; the canonical value is `"=response"`, as for every BPMN ServiceTask.

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

@@ -0,0 +1,72 @@
+# Batch Transform Pattern Node — Planning
+
+The Batch Transform node runs an LLM over every row of an attached CSV (or similar tabular file) and appends one or more **LLM-generated columns** to each row. Think "row-wise enrichment with a prompt" — classification, summarization, entity extraction, categorization. It lives in the **Tool** section of the add-node panel (between Script and Transform).
+
+## Node Type
+
+`uipath.pattern.batch-transform`
+
+This is a fixed OOTB node type — no registry suffix, one version. Whether it appears in `uip maestro flow registry list` is a property of the CLI build, not of the tenant: the CLI asks for a fixed set of OOTB node manifests, and the server only adds dynamic nodes on top — it never withholds an OOTB one. If the node is missing, upgrade the CLI.
+
+## When to Use
+
+Use Batch Transform when the task is **"do this to every row"** and the per-row work requires natural-language reasoning that is impractical to express as code.
+
+### Selection Heuristics
+
+| Situation | Use Batch Transform? |
+| --- | --- |
+| Add LLM-generated columns to each row of a CSV (category, sentiment, one-line summary) | Yes |
+| Enrich rows with web-searched facts (e.g., look up a company's HQ city per row) | Yes — set `enableWebSearchGrounding: true` |
+| Small ad-hoc data shape change (rename, filter, groupBy) on an in-memory array | No — use [Transform](../transform/planning.md) |
+| Per-row side effects (API calls, DB writes) | No — use [Loop](../loop/planning.md) with the per-row action inside |
+| Reason over a **single** document and produce a synthesis with citations | No — use [Summarize](../summarize/planning.md) |
+| Row-count unknown but small (< 20) and the agent should decide how to reason | Consider [Agent](../agent/planning.md) with the collection in its context instead |
+
+### Anti-Patterns
+
+- **Do not use Batch Transform for deterministic work.** If the new column is a formula, regex match, or date reformat, use [Transform](../transform/planning.md) or [Script](../script/planning.md) — the LLM adds cost and latency for no accuracy gain.
+- **Do not use Batch Transform as a general loop.** It only produces new columns attached to the same rows; it cannot call APIs or perform side effects per row. Use [Loop](../loop/planning.md) for that.
+- **Do not pass reasoning-heavy instructions that depend on the whole document.** Each row is processed with only its own values plus the prompt — it cannot "see" other rows or an external document. For cross-row reasoning, pre-aggregate with [Transform](../transform/planning.md) first, or use [Summarize](../summarize/planning.md) over a synthesized attachment.
+
+## Ports
+
+| Port | Position | Direction | Use |
+| --- | --- | --- | --- |
+| `input` | left | target | Flow sequence input |
+| `output` | right | source | Produced file handle with the new columns appended |
+| `error` | right | source | Error handler (populated when the batch job fails) |
+
+No artifact ports. Pattern-style nodes do not wire to resource files — the prompt and column definitions live on the node inputs.
+
+## Output Variables
+
+- `$vars.{nodeId}.output` — the result file handle. The OOTB definition declares `outputDefinition.output.type: "file"` (no nested schema today), and `source: "=response"` — i.e. the BPMN engine returns its result wrapped under the `response` key. Pass `$vars.{nodeId}.output` to downstream nodes that consume files (e.g., another Batch Transform, a connector that uploads the result, a Script that fetches and parses).
+- `$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 Batch Transform 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 instruction describing what each output column should contain. Can reference column names from the source via natural language ("summarize the `Description` field"). |
+| `outputColumns` | Yes | array of `{ name, description }` | The columns to produce. Max 10. `name` is the column header; `description` tells the LLM what to put in it. |
+| `enableWebSearchGrounding` | No | boolean | When `true`, the LLM can issue web searches per row to ground its answer. Slower and costlier — use only when rows need external facts. Default `false`. |
+
+### `outputColumns` shape
+
+```json
+[
+  { "name": "Category", "description": "One of: Invoice, Receipt, Contract, Other" },
+  { "name": "Summary",  "description": "One-line plain-English summary of the row" }
+]
+```
+
+Do not reshape — the canvas editor writes exactly this `{ name, description }` shape, and downstream serialization (BPMN `ECS.BatchTransform` service task) depends on it.
+
+## Planning Annotation
+
+In the architectural plan:
+
+- `pattern: batch-transform — <one-line purpose>` with a placeholder for the attachment source (usually a `$vars.<upstream>.output.*` file handle) and the list of output column names.
+- Call out `enableWebSearchGrounding` in **Open Questions** if the requirements hint at external lookups but are not explicit — the cost/latency jump warrants confirmation.