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

package/skills/uipath-maestro-flow/references/operate/{references/manage.md → manage.md}

@@ -7,7 +7,7 @@ Intervene in a running or faulted Flow instance: pause, resume, cancel, retry. A
 ## Pre-flight
 
 1. **Logged in.** `uip login status --output json` returns success.
-2. **Folder key resolved.** Get it from `uip or folders list --output json` or from the job/process context. See [shared/cli-conventions.md — `--folder-key` requirement](../../shared/cli-conventions.md#6---folder-key-requirement).
+2. **Folder key resolved.** Get it from `uip or folders list --output json` or from the job/process context. See [shared/cli-conventions.md — `--folder-key` requirement](../shared/cli-conventions.md#6---folder-key-requirement).
 3. **Instance ID known.** From a debug run (`Data.instanceId`), `flow job status` response, or `instance list`.
 
 ## Lifecycle commands
@@ -30,10 +30,10 @@ uip maestro flow instance retry <INSTANCE_ID> -f <FOLDER_KEY> --output json    #
 
 ## What's next
 
-- **Need to inspect why an instance faulted before deciding pause/cancel/retry?** Triage via [diagnose/CAPABILITY.md](../../diagnose/CAPABILITY.md) first — get incidents and runtime variables before intervening.
-- **Need to look up the full `instance` CLI surface?** See [shared/cli-commands.md](../../shared/cli-commands.md) and the [Diagnose troubleshooting guide — CLI command reference](../../diagnose/references/troubleshooting-guide.md#cli-command-reference).
+- **Need to inspect why an instance faulted before deciding pause/cancel/retry?** Triage via [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) first — get incidents and runtime variables before intervening.
+- **Need to look up the full `instance` CLI surface?** See [shared/cli-commands.md](../shared/cli-commands.md) and the [Diagnose troubleshooting guide — CLI command reference](../diagnose/troubleshooting-guide.md#cli-command-reference).
 
 ## Anti-patterns
 
-- **Never `retry` a faulted instance without diagnosing the root cause first.** Triage via [diagnose/CAPABILITY.md](../../diagnose/CAPABILITY.md) — read incidents, runtime variables, and the deployed asset. Then decide whether to retry, cancel, or re-author.
+- **Never `retry` a faulted instance without diagnosing the root cause first.** Triage via [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) — read incidents, runtime variables, and the deployed asset. Then decide whether to retry, cancel, or re-author.
 - **Never skip the `--folder-key` flag.** Without it the command rejects before reaching the API.

package/skills/uipath-maestro-flow/references/operate/run.md

@@ -0,0 +1,121 @@
+# Run — Execute a Flow
+
+Execute a flow on demand and monitor progress. Three modes: **debug** (controlled re-run with full Studio Web visibility), **process run** (trigger a deployed process), **job inspection** (status and traces). All require `uip login`.
+
+## Pre-flight
+
+1. **Logged in.** `uip login status --output json` returns success. See [shared/cli-conventions.md — Login state](../shared/cli-conventions.md#5-login-state).
+2. **For debug runs: solution resources refreshed.** Always run before `flow debug` so connection and process resource declarations are in sync with project bindings:
+
+   ```bash
+   uip solution resources refresh --solution-folder <SolutionDir> --output json
+   ```
+
+## Debug — controlled end-to-end run
+
+> **Consent comes from the mandate.** `flow debug` executes the flow for real — sends emails, posts messages, calls APIs. Run it when the request is for a flow that works; ask when the request stops at build or validate. The mandate does not cover side effects that reach a third party (a real call, a message to someone who is not the user) — those need the run asked for explicitly. Never debug a solution this run did not scaffold: debug overwrites the Studio Web solution matching the local `.uipx` `SolutionId`. See rule #2 in [SKILL.md](../../SKILL.md).
+
+```bash
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json
+```
+
+The argument is the **project directory path** (the folder containing `project.uiproj`). Use `<ProjectName>/` from the solution dir, or `.` if already inside the project dir.
+
+> **Never run `flow debug` in the background.** It takes 1 to 5 minutes and prints its JSON only at exit.
+> 1. Run it in the foreground with a tool timeout of at least 10 minutes (most agent shells kill a command after 1 to 2 minutes).
+> 2. If the tool returns "still running", poll that same process until it exits. Do not read the output file yet — empty means still running.
+> 3. If stdout ends with `Debug polling timed out after <N>s`, the flow is still running on the server. Take the `instanceId` from stderr and run `uip maestro flow debug-instance status <INSTANCE_ID> --output json`.
+> 4. Never start a second debug while the first is running — it uploads and executes the flow again.
+> 5. Re-run debug only after you changed the flow.
+
+> **Do not pass `--folder-path` or `--folder-key` to `flow debug`.** Debug provisions into your personal workspace. A shared or team folder fails with `HTTP 500` at `Stage: prepare-custom-debug` and no instance starts. Shared resources the flow uses (indexes, buckets, connections) reach the run through `uip solution resources refresh`, not through the debug folder. Use the flag only when your account has no personal workspace or the flow needs folder-scoped assets or queues that exist only in that folder.
+
+Pass input arguments when the flow has input parameters:
+
+```bash
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json \
+  --inputs '{"numberA": 5, "numberB": 7}'
+```
+
+Build those inputs from real records, never from invented values — an invented key matches no record, every lookup returns `[]`, and the run faults on empty data. Read the entity `Id` from `uip df entities list --output json`, then a live record from `uip df records list <ENTITY_ID> --output json`.
+
+Bind local files to file-typed input variables with `--attachment <variableId>=<localPath>` (repeatable). `<variableId>` (left of `=`) must match the `id` of a `variables.globals[]` entry with `direction:"in"` and `type:"file"`:
+
+```bash
+# Replace <variableId> and <localPath> placeholders below with your own values.
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json \
+  --attachment <variableId>=<localPath> \
+  --attachment <variableId>=<localPath>
+```
+
+> **Pre-flight.** Confirm each `<variableId>` exists in the flow's `variables.globals[]` with `direction:"in"` and `type:"file"`. See [shared/cli-commands.md — Pre-flight](../shared/cli-commands.md#pre-flight---attachment-binding).
+
+> **Reading the bound file.** At runtime a `file` variable is an object — a Script node reads the uploaded name via `$vars.{triggerNodeId}.output.{id}.FullName`. See [shared/variables-and-expressions.md — Runtime shape of a `file` variable](../shared/variables-and-expressions.md#file-input).
+
+### Reporting debug runs to the user
+
+The CLI response includes a **Studio Web URL** (where the user inspects the run) and an **instanceId** (for log/trace correlation). Parse both from the JSON output — typically `Data.studioWebUrl` and `Data.instanceId` — and **always show them as the first two lines of the summary**:
+
+```text
+Studio Web URL: <url>
+Instance ID: <instanceId>
+
+<run status, node traces, errors, etc.>
+```
+
+If either value is missing from the response, emit the label with `<not returned by CLI>` rather than dropping the line. Do not bury these values below the run summary — the user should see them immediately without scrolling.
+
+### When the run faults
+
+`Data.finalStatus: "Faulted"` means the run failed, and the cause is already in that same response — read it there. Redirect stdout to a file and extract the cause from the file; on a faulted run the CLI ignores `--output-filter` and prints the whole envelope, so the filter is not a way to shrink it:
+
+```bash
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json > /tmp/flow-debug.json
+```
+
+Extraction commands and fault-code lookup: [diagnose/troubleshooting-guide.md — Step 0](../diagnose/troubleshooting-guide.md#step-0--read-the-cause-in-the-debug-output-you-already-have).
+
+See [shared/cli-commands.md — uip maestro flow debug](../shared/cli-commands.md#uip-maestro-flow-debug) for additional options.
+
+## Process run — trigger a deployed process
+
+For flows already deployed to Orchestrator (via [ship.md](ship.md) → Orchestrator path):
+
+```bash
+uip maestro flow process list --output json                           # discover deployed processes
+uip maestro flow process run <process-key> <folder-key> --output json # trigger a run
+```
+
+Pass input arguments and/or bind file-typed input variables:
+
+```bash
+# Replace <variableId> and <localPath> placeholders below with your own values.
+uip maestro flow process run <process-key> <folder-key> --output json \
+  --inputs '{"numberA": 5, "numberB": 7}' \
+  --attachment <variableId>=<localPath>
+```
+
+> **Pre-flight.** Confirm each `<variableId>` exists in the flow's `variables.globals[]` with `direction:"in"` and `type:"file"` — see [shared/cli-commands.md — Pre-flight](../shared/cli-commands.md#pre-flight---attachment-binding). On `process run` only: `--attachment` overrides `--inputs` on key collisions; `--validate` accepts pre-uploaded attachment references for file-typed slots (passes the JSON-schema check even though the slot's nominal type is `string`).
+
+Run `uip maestro flow process --help` for all subcommands and options.
+
+## Job inspection — status and traces
+
+```bash
+uip maestro flow job status <job-key> --output json   # check status of a running or completed job
+uip maestro flow job traces <job-key> --output json   # stream the verbose execution timeline
+```
+
+> **Traces are verbose** and contain the full execution timeline. Use them only when needed for diagnosis — start from incidents first via [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md).
+
+## What's next
+
+- **Run failed?** Triage via [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) — start with incidents, escalate to traces only if needed.
+- **Need to intervene in a running instance** (pause, resume, cancel, retry)? See [manage.md](manage.md).
+
+## Anti-patterns
+
+- **Never run `flow debug` as a validation step.** Use `uip maestro flow validate` for correctness checking; debug is for end-to-end execution.
+- **Never re-run a completed `flow debug` to re-read or reshape its output.** Each run re-uploads the solution and executes the flow again for real. Extract the report fields from the payload the completed run already returned — see [Reporting debug runs](#reporting-debug-runs-to-the-user). For a faulted run, read the cause first — see [When the run faults](#when-the-run-faults).
+- **Never skip `solution resources refresh` before debug.** Stale resource declarations cause runtime binding failures even when the local `.flow` is correct.
+- **Never start diagnosis from `job traces`.** Traces are last-resort — see [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) for the priority ladder.

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

@@ -8,8 +8,8 @@ Publish journey for a Flow project. Two paths: **Studio Web upload** (default) a
 
 Before either publish path, ensure:
 
-1. **Authoring is complete.** `uip maestro flow validate` passes and `uip maestro flow format` was run. If not, send the user back to [author/CAPABILITY.md](../../author/CAPABILITY.md).
-2. **Logged in.** `uip login status --output json` returns success. See [shared/cli-conventions.md — Login state](../../shared/cli-conventions.md#5-login-state).
+1. **Authoring is complete.** `uip maestro flow validate` passes and `uip maestro flow format` was run. If not, send the user back to [author/CAPABILITY.md](../author/CAPABILITY.md).
+2. **Logged in.** `uip login status --output json` returns success. See [shared/cli-conventions.md — Login state](../shared/cli-conventions.md#5-login-state).
 3. **Solution resources are refreshed.** Always run this before `solution upload` or `solution publish` so that connection and process resource declarations are in sync with the project bindings:
 
    ```bash
@@ -44,13 +44,13 @@ uip solution resources refresh --solution-folder <SolutionDir> --output json
 uip maestro flow pack <project-path> <OutputDir>
 ```
 
-For `uip solution publish` and the rest of the deployment workflow, see [/uipath:uipath-solution](/uipath:uipath-solution). See [shared/cli-commands.md — uip maestro flow pack](../../shared/cli-commands.md#uip-maestro-flow-pack) for `pack` flags.
+For `uip solution publish` and the rest of the deployment workflow, see [/uipath:uipath-solution](/uipath:uipath-solution). See [shared/cli-commands.md — uip maestro flow pack](../shared/cli-commands.md#uip-maestro-flow-pack) for `pack` flags.
 
 ## Anti-patterns
 
 - **Never run `solution upload` without `solution resources refresh` first.** Stale resource declarations cause runtime binding failures (the deployed flow can't find its connections).
-- **Never default to Orchestrator deploy when the user said "publish".** "Publish" without specifier means Studio Web. When the target is ambiguous, ask the user with **Studio Web upload** / **Orchestrator deploy** / **Something else** as options before running `flow pack` + `solution publish`. See the dropdown question rule in [SKILL.md](../../../SKILL.md).
-- **Never publish a flow that hasn't been validated and formatted.** `flow validate` catches schema errors; `flow format` ensures Studio Web renders nodes correctly. Both are author-side gates — see [author/CAPABILITY.md](../../author/CAPABILITY.md).
+- **Never default to Orchestrator deploy when the user said "publish".** "Publish" without specifier means Studio Web. When the target is ambiguous, ask the user with **Studio Web upload** / **Orchestrator deploy** / **Something else** as options before running `flow pack` + `solution publish`. See the dropdown question rule in [SKILL.md](../../SKILL.md).
+- **Never publish a flow that hasn't been validated and formatted.** `flow validate` catches schema errors; `flow format` ensures Studio Web renders nodes correctly. Both are author-side gates — see [author/CAPABILITY.md](../author/CAPABILITY.md).
 
 ## What's next
 

package/skills/uipath-maestro-flow/references/shared/action-nodes.md

@@ -1,16 +1,16 @@
 # Action Node Structure
 
-Reference for the boilerplate shared by every action-node `impl.md` in this skill. Plugin docs should link here for the standard parts and only spell out what is plugin-specific: the registry type string, plugin-specific input fields, plugin-specific rules, debug entries, and node-type configuration workflows.
+Reference boilerplate shared by every action-node `impl.md`. Plugin docs should link here and specify only the registry type string, plugin-specific inputs and rules, debug entries, and node-type configuration workflows.
 
 ## Registry validation
 
-Every action node should validate its registry contract before authoring:
+Before authoring, run:
 
 ```bash
 uip maestro flow registry get <node-type> --output json
 ```
 
-`registry get` returns the manifest at `Data.Node`. Do **not** inspect `Data` directly as if it were the node manifest.
+`registry get` returns the manifest at `Data.Node`; do not inspect `Data` directly as the node manifest.
 
 ```json
 {
@@ -29,18 +29,11 @@ uip maestro flow registry get <node-type> --output json
 }
 ```
 
-Inspect:
-
-- `Data.Node.handleConfiguration` — input port name and output port name(s). Array of position groups, not a map with a top-level `handles` field.
-- `Data.Node.inputDefinition` — required inputs.
-- `Data.Node.outputDefinition` — downstream payloads.
-- `Data.Node.model.serviceType` — where applicable.
-
-Plugin `impl.md` records what to confirm for that specific node type.
+Inspect `Data.Node.handleConfiguration` for input and output port names; it is an array of position groups, not a map with a top-level `handles` field. Inspect `Data.Node.inputDefinition` for required inputs, `Data.Node.outputDefinition` for downstream payloads, and `Data.Node.model.serviceType` where applicable. Each plugin `impl.md` records what to confirm for its node type.
 
 ## Standard JSON skeleton
 
-All action nodes share this base shape on the node instance:
+Every action-node instance uses this base shape:
 
 ```json
 {
@@ -66,27 +59,42 @@ All action nodes share this base shape on the node instance:
 }
 ```
 
-`outputs.output` documents the success payload referenced downstream as `=js:$vars.{nodeId}.output`. `outputs.error` documents the failure shape; the runtime routes to the implicit `error` port when the action faults. See [Implicit error port on action nodes](file-format.md#implicit-error-port-on-action-nodes).
+`outputs.output` documents the success payload referenced downstream as `=js:$vars.{nodeId}.output`; `outputs.error` documents the failure shape. Runtime faults route to the implicit `error` port. See [Implicit error port on action nodes](file-format.md#implicit-error-port-on-action-nodes).
+
+For action nodes, the instance `outputs` block is documentation, not the runtime contract. The matching `variables.nodes[]` entry exposes process-level `$vars.{nodeId}.output`; see [file-format.md — Node outputs](file-format.md#node-outputs). The BPMN emitter ignores the instance `outputs` block at serialization because the manifest's `outputDefinition` drives activity-side mapping.
+
+**Exceptions:** Orchestrator-job nodes (api-workflow, rpa-workflow, agent, agentic-process, function) have their instance `outputs` read by the converter, which copies each `source` verbatim. A wrong `source` (for example, `=result.response`) breaks `$vars.{nodeId}.output`; declare `error` only there. End / terminate nodes also have their instance `outputs` consumed to map workflow-level `out` variables.
 
-> **For action nodes the instance `outputs` block is documentation, not the runtime contract.** What actually exposes the node's outputs as process-level `$vars.{nodeId}.output` is the matching `variables.nodes[]` entry — see [file-format.md — Node outputs](file-format.md#node-outputs). The BPMN emitter ignores the action-node instance `outputs` block at serialization (the manifest's `outputDefinition` drives the activity-side mapping). **Exception — Orchestrator-job nodes** (api-workflow, rpa-workflow, agent, agentic-process, function): the converter DOES read their instance `outputs` and copies each `source` verbatim, so a wrong `source` (e.g. `=result.response`) breaks `$vars.{nodeId}.output` — declare `error` only there. End / terminate nodes are also an exception: their instance `outputs` block IS consumed to map workflow-level `out` variables. `uip maestro flow format` regenerates `variables.nodes[]` from the current node graph (MST-9972), so running format after structural edits self-heals an omitted entry.
+**Data Fabric entity nodes (`core.datafabric.*`) carry no instance `outputs` block at all** — the canvas writes none, so author `inputs` only and let `flow format` regenerate `variables.nodes[]`. They are also the one action-node family with **no `error` port**: none declares `supportsErrorHandling`, so the skeleton's `outputs.error` and the implicit error port in [Standard ports](#standard-ports) do not apply to them. See [data-fabric/impl.md](../author/plugins/data-fabric/impl.md#no-error-port).
+
+`uip maestro flow format` regenerates `variables.nodes[]` from the current node graph, so running format after structural edits self-heals an omitted entry.
 
 ## Standard ports
 
 | Direction | Common name(s) | Notes |
 | --- | --- | --- |
-| Input (target) | `input` | Every action node accepts a single input edge on `input`. |
-| Output (success, source) | `output`, `default`, or `success` | Name varies by plugin — `registry get` is authoritative. |
-| Output (error, source) | `error` | Implicit on every action node via `outputs.error`. |
+| Input (target) | `input` | Every action node accepts one input edge on `input`. |
+| Output (success, source) | `output`, `default`, or `success` | The name varies by plugin; `registry get` is authoritative. |
+| Output (error, source) | `error` | Implicit on action nodes that declare `supportsErrorHandling`, via `outputs.error`. The `core.datafabric.*` family does not — it has no `error` port. |
 
-Some plugins add dynamic source ports (e.g., HTTP `branch-{id}` from `inputs.branches`); those are documented in the plugin's own `impl.md`.
+Plugins may add dynamic source ports, such as HTTP `branch-{id}` from `inputs.branches`; document these in the plugin's `impl.md`.
 
 ## Adding and editing procedures
 
-For step-by-step add, delete, and wiring instructions, see [editing-operations.md](../author/references/editing-operations.md) and the JSON recipes in [editing-operations-json.md](../author/references/editing-operations-json.md). Plugin `impl.md` files describe only the inputs and wiring patterns that are specific to the node type.
+Use [editing-operations.md](../author/editing-operations.md) and [editing-operations-json.md](../author/editing-operations-json.md) for step-by-step add, delete, and wiring instructions. Plugin `impl.md` files should describe only node-type-specific inputs and wiring patterns.
 
 ## Migrating a plugin to reference this template
 
-When converting an existing plugin `impl.md` to use this template:
+Keep in the plugin:
+
+- registry type string and `typeVersion`;
+- plugin-specific input fields;
+- plugin-specific configuration workflows, such as `node configure` for HTTP/connector nodes;
+- plugin-specific rules, common patterns, and debug table.
+
+Replace with a link here:
 
-- **Keep in the plugin:** registry type string, `typeVersion`, plugin-specific input fields, plugin-specific configuration workflow (e.g., `node configure` for HTTP/connector nodes), plugin-specific rules, common patterns, debug table.
-- **Replace with a link here:** generic JSON skeleton, generic `outputs` block (`=result.response` / `=result.Error`), generic registry-validation prose, generic "Adding / Editing" cross-reference.
+- generic JSON skeleton;
+- generic `outputs` block (`=result.response` / `=result.Error`);
+- generic registry-validation prose;
+- generic "Adding / Editing" cross-reference.