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

package/skills/uipath-api-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uipath-api-workflow
-description: "UiPath API Workflow assistant — author, run, validate, package, publish, deploy, and troubleshoot JSON workflows for `uip api-workflow`. Covers logical/hierarchical structure (Sequence, Assign, JavaScript, If with #Wrapper/#Then/#Else, ForEach, DoWhile, Break, TryCatch, Wait, Response — nested patterns) AND HTTP / Integration Service connector activities (Gmail, Outlook, GitHub, Slack) authored via `uip api-workflow registry resolve`/`stub`. Operate: run locally, manage IS connections (`uip is connections`), pack/publish/deploy via `uip solution`, invoke published workflows via HTTP/schedule/event triggers. Diagnose: validate → run --no-auth loop, root-cause run/expression/connection faults, inspect job logs & traces. Triggers on UiPath API workflows, project type \"Api\", JSON files with `document.dsl`/`do[]`, those activity types, or fetching from a public/vendor API. For .flow Maestro→uipath-maestro-flow. For .xaml/coded RPA→uipath-rpa. For coded agents→uipath-agents. For Coded Apps→uipath-coded-apps."
+description: "UiPath API Workflow assistant — author, run, validate, package, publish, deploy, and troubleshoot JSON workflows for `uip api-workflow`. Load for ANY create/edit of a `Workflow.json` / API workflow project; with `evals/` present, tests come first (TDD). Covers Sequence, Assign, JavaScript, If (#Wrapper/#Then/#Else), ForEach, DoWhile, Break, TryCatch, Wait, Response, nested; files as JobAttachment refs via File to Base64 / Base64 to File (`$helpers.file.*`, `serializeData()`, `--input-file`/`--output-dir`); HTTP / IS connector activities via `uip api-workflow registry`. Operate: run, IS connections, pack/publish/deploy. Test/eval: `evals/<scope>/eval-sets/` datasets (exact-match, Evaluations panel); loop until green. Triggers on API workflows, project type \"Api\", JSON with `document.dsl`/`do[]`, those activity types, or file/base64 handling. Agent evals (`evals/eval-sets/`, no scope) & coded agents→uipath-agents. Flow & its evals→uipath-maestro-flow. .xaml/coded RPA→uipath-rpa. Coded Apps→uipath-coded-apps."
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 ---
 
@@ -8,24 +8,30 @@ allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 
 Build, run, and publish UiPath API Workflows — JSON files conforming to the CNCF Serverless Workflow DSL 1.0.0 with UiPath activity-type extensions. Executed by `@uipath/api-workflow-executor` via `uip api-workflow run`. Packaged as `Type: "Api"` projects via `uip solution pack`.
 
+> **TDD gate — read this first (rule 22).** On ANY request to create or edit a workflow, Phase 0 first checks whether the project has an `evals/` folder — it lives **inside the project directory, next to `Workflow.json`** (`<project>/evals/`), not at the workspace or solution root, so list the project directory itself. **No `evals/` folder → the Evaluations feature is not enabled for this project: skip everything about tests and loop mode and author normally.** `evals/` present → **end your turn** with two questions — **(1) tests:** the eval set has rows → "should anything change, or use as-is?" / it is empty → "want me to add some?"; **(2) loop mode:** "run the tests and re-try until every case passes, or author once?" — and NOTHING is authored until the user answers. Tests come **first**: once answered, write or update the eval set, then author the workflow to make it pass. If you are about to write `Workflow.json` in a project with `evals/` and the user has not answered these two questions in this conversation, stop. Later change requests that alter behavior can break the tests — ask before editing whether to update them (rule 22, [references/testing-and-evals.md](references/testing-and-evals.md) §3). Only a prompt that explicitly says not to ask skips the gate when `evals/` exists — and that skips the questions, not the run consent (rule 21): run rows only when the request itself asks for a run.
+
 ## When to Use This Skill
 
 - User wants to **create or edit** an API workflow JSON file
 - User wants to **run** an API workflow locally with `uip api-workflow run`
 - User wants to **package** an API workflow project into `.nupkg` / solution `.zip`
 - User wants to **publish** an API workflow to UiPath Cloud / Orchestrator
-- User asks about **activity types** (Sequence, Assign, JavaScript, If, ForEach, DoWhile, Break, TryCatch, Wait, Response, HTTP Request, Connector)
+- User asks about **activity types** (Sequence, Assign, JavaScript, If, ForEach, DoWhile, Break, TryCatch, Wait, Response, File to Base64, Base64 to File, HTTP Request, Connector)
+- User wants to **handle a file** in an API workflow — take a file input, send a file as base64 to an API, turn a base64 payload back into a file, or asks about `JobAttachment`, `$helpers.file`, `serializeData()`, `--input-file` / `--output-dir`. See [references/files-and-base64.md](references/files-and-base64.md)
 - User asks about **nested control flow** — If inside ForEach, TryCatch around a loop, conditional Break, multi-way branching, etc.
 - User asks for an **Integration Service connector activity** (Gmail Send Email, Outlook Get Newest Email, GitHub Search Issues, Slack Send Message, etc.) — follow the discovery flow in [references/connector-activity-discovery.md](references/connector-activity-discovery.md)
 - User asks for a **generic HTTP Request** that needs to render in StudioWeb's designer — same discovery flow
 - User asks about **JavaScript expressions, `$context`, `$input`, `$workflow`, `WorkflowStart`, or the `export.as` pattern**
 - User asks how to **debug** a failing API workflow run — the local `validate` → `run --no-auth` loop, or a **post-publish cloud run** (job logs/traces). See [references/operating-published-workflows.md](references/operating-published-workflows.md)
 - User wants to **operate** a published workflow — invoke it (HTTP/schedule/Integration Service event trigger), start/list/stop its Orchestrator jobs, or **manage the Integration Service connections** it uses (`uip is connections list`/`ping`/`edit`). See [references/operating-published-workflows.md](references/operating-published-workflows.md)
+- User wants to **test / evaluate** a workflow — author `(inputs, expectedOutput)` cases in the project's `evals/` folder (the dataset Studio Web's **Evaluations** panel reads), run them, score them by the project's evaluator, or **"loop until the tests pass"**. Follow [references/testing-and-evals.md](references/testing-and-evals.md). An `evals/` folder alone is not the signal — it is an API-workflow one only when it sits next to `Workflow.json` and uses the `evals/<scope>/eval-sets/` layout; low-code agents use `evals/eval-sets/` (no scope) → `uipath-agents`, Flow evals → `uipath-maestro-flow`
+- **Any authoring request** (create or edit) — Phase 0 discovery checks for an `evals/` folder; when it exists, the two test questions (change / add tests? loop mode?) are asked up front — the turn ends there — whether or not the user mentioned testing (rule 22). No `evals/` folder → the feature is off, author normally. See Phase 0 and [references/testing-and-evals.md](references/testing-and-evals.md)
 
 Do NOT use for: `.flow` Maestro flows (→ `uipath-maestro-flow`), `.xaml` / coded RPA (→ `uipath-rpa`), coded agents (→ `uipath-agents`), Coded Web Apps (→ `uipath-coded-apps`).
 
 ## Core Principles
 
+0. **Tests first — when the project has `evals/`, and only after asking.** Discover `<project>/evals/` (next to `Workflow.json`). Absent → the Evaluations feature is off for this project: author normally, no test or loop-mode questions. Present → ask the two rule-22 questions, end the turn; once answered: declare `output.schema`, eval set first, workflow second, then run the rows **only in loop mode** (that "yes" is the rule-21 consent; "author once" means hand over without running). Behavior changes later on re-open the question — the tests may need updating.
 1. **Know before you write.** Read the existing workflow file before editing. Read an example template before creating from scratch.
 2. **Start minimal, iterate to correct.** Add one activity at a time. Run with `--no-auth --output json` after each addition. Fix what breaks. Repeat.
 3. **Validate before running.** `uip api-workflow validate` is the offline static pre-flight (autonomous); `uip api-workflow run` is the runtime validator that catches what static analysis can't (live HTTP, expression evaluation, connection state) and needs user consent. See rules 20–21.
@@ -97,13 +103,32 @@ Do NOT use for: `.flow` Maestro flows (→ `uipath-maestro-flow`), `.xaml` / cod
 
     **What validate catches:** malformed JSON; unknown `activityType` values (see VALID_ACTIVITY_TYPES list in the validate source); per-activity required keys (If → `do` + inner `switch`, Sequence → `do`, Assign → `set`, ForEach → `for` + `do`, DoWhile → `for` + `doWhile`, Connector → `call` + `metadata.configuration` + `essentialConfiguration`, Response → `response`, etc.); missing `metadata.activityType`/`displayName` (warnings); bad `evaluate.language`/`evaluate.mode`; duplicate or empty-named workflow variables; empty task lists. **What it does NOT catch:** wrong `selectedResourceId`, broken connector connection IDs, runtime expression errors (`ReferenceError: x is not defined`), unwrapped string literals (rule 5), multi-key `Assign.set` (rule 6) — those still need runtime validation via `uip api-workflow run` once the user consents.
 
-21. **Never run `uip api-workflow run` without an explicit user "yes."** Validation (rule 20) is autonomous; *running* is not. Once validate passes, ask the user: (a) run now or skip, (b) if running, with `--no-auth` (fast, structure-only — IntSvc kind vendor calls fail) or with auth (real Integration Service calls — vendor side effects WILL happen: emails sent, tickets created, files uploaded). Suggest a default based on workflow content (`--no-auth` for control-flow-only + Http kind `ImplicitConnection`; with-auth for any IntSvc kind vendor activity), but wait for the user's answer. Never invoke `uip api-workflow run` with auth on speculation — once a vendor call goes out, it can't be unsent.
+21. **Never run `uip api-workflow run` without an explicit user "yes."** Validation (rule 20) is autonomous; *running* is not. Once validate passes, ask the user: (a) run now or skip, (b) if running, with `--no-auth` (fast, structure-only — IntSvc kind vendor calls fail) or with auth (real Integration Service calls — vendor side effects WILL happen: emails sent, tickets created, files uploaded). Suggest a default based on workflow content (`--no-auth` for control-flow-only + Http kind `ImplicitConnection`; with-auth for any IntSvc kind vendor activity), but wait for the user's answer. Never invoke `uip api-workflow run` with auth on speculation — once a vendor call goes out, it can't be unsent. This rule gates only `uip api-workflow run`. If the user asked to package or publish, do not stop on the run question: validate, then pack (rule 19). A local run is a separate request; do it only when the user asks for it.
+
+22. **TDD gate — only for projects with an `evals/` folder; STOP and ask before authoring; tests are written before the workflow.** Every authoring request (create OR edit — including a one-line change) runs Phase-0 discovery of the project's `evals/` folder — `<project>/evals/`, the directory next to `Workflow.json` (list that directory; the workspace or solution root is the wrong place to look):
+    - **No `evals/` folder** → the Evaluations feature is not enabled for this project. Skip the gate entirely: do not offer to create tests, do not mention loop mode, do not create the folder — author normally (Phases 1–3).
+    - **`evals/` present** → **end the turn** with two questions. Do not write or edit `Workflow.json`, and do not create or change eval files, until the user has answered both:
+      1. **Tests** — the eval set has rows → *"I found N test case(s): [one line each]. Should anything change, or use them as-is?"*; the set is empty (the panel seeds one with 0 rows) → *"There are no test cases yet — want me to add some? I'd suggest: [2–3 proposed cases]."*
+      2. **Loop mode** — *"Run in loop mode (run the tests and re-try — fix, re-run — until every case passes), or author once and you verify?"* A "yes" to loop mode is also the consent to run the rows with `--no-auth` (rule 21) — do not ask "run now?" separately; connector/authed runs still need their own explicit "yes".
+
+    **Order after the answers (TDD):** first declare `input.schema` / `output.schema` in `Workflow.json` (`init` scaffolds `output: null`, so the row keys have no other source — property names and casing come from here, and the Response must emit exactly those keys), then write or update the eval set, then author the workflow, then run the rows (loop mode) or hand over (author once — do not run). **Later change requests that alter behavior** (threshold, rounding, branch order, a new default — even with the schema unchanged) can make existing expectations wrong: before editing, list the affected rows and ask whether to update them; after editing, re-run the rows. Ask as two specific questions — never one vague "how do you want to verify it?". With `evals/` present, the gate is skipped only when the user already answered, or explicitly asked not to be prompted ("don't ask for confirmation"); then keep existing tests as-is and add tests only if requested. "Don't ask" waives the two questions, **not** rule 21's run consent: run the rows only if the request itself asks for a run or a loop ("run the evaluations", "until they pass" — that wording is the consent); otherwise author once and hand over the exact command to run them. Protocol and wording: [references/testing-and-evals.md](references/testing-and-evals.md) §3.
+
+23. **Files are references, not bytes — and base64 is a file too.** A file input or output is a `JobAttachment` (`{ ID, FullName, MimeType, Metadata? }`) pointing at a blob in Orchestrator storage; `$workflow.input.<file>` is that object, never the bytes.
+    - **The two activities.** Both are `run.script` tasks; the `$helpers.file.*` call in the script is what identifies them (it is what `validate` checks). **File to Base64** (`metadata.activityType: "FileToBase64"`, code `return { output: await $helpers.file.fileToBase64(<file ref>) }`) returns a NEW reference whose blob content IS the base64 text (`<name>.base64`, `text/plain`, `Metadata.Encoding: "base64"`). **Base64 to File** (`metadata.activityType: "Base64ToFile"`, code `return { output: await $helpers.file.base64ToFile({ base64: <ref or string>, fileName?, mimeType? }) }`) returns a binary reference. The script is that single `return` expression and nothing else: Studio Web rebuilds the script from the parsed call on every designer save and silently drops a preceding or trailing statement, a second argument, or an extra option key. `validate` warns only about the extra statements — an extra argument passes as `Valid` and still breaks — so put any pre-processing in a JavaScript activity before the conversion.
+    - **Reading results.** Read either activity's result as `$context.outputs.<Key>.output`.
+    - **Inlining file content.** To put a file's content INLINE in an HTTP request body or a Response field, call `<ref>.serializeData()` right there — it returns a deferred-read marker the engine fills at send time; never store it in a variable or use it in script logic. Nested in a JSON body it works **only for a base64 reference** (the File to Base64 output): a binary file's marker, or a bare reference, nested in a body is a send-time error — send a binary file as the *whole* body (bare reference) or convert it first.
+    - **Naming.** `fileName` / `mimeType` apply only to a raw base64 *string*; a reference keeps its own name and the engine sniffs the type from bytes (a `.txt` round-trips to an extension-less file).
+    - **Running.** Both helpers need Orchestrator blob storage:
+    `uip api-workflow run --no-auth` refuses such a workflow up front; run it signed in (`uip login`, no `--no-auth`) — it still needs the rule-21 "yes". Pass local files with `--input-file <name>=<path>` (uploaded, arriving as `$workflow.input.<name>`), collect returned files with `--output-dir <dir>` (each reference in the output gains a `LocalPath`), and `--folder-key <guid>` if the tenant's Attachments API requires a folder. In the printed output the CLI PascalCases keys (`ID` → `Id`).
+    Shapes, worked example and pitfalls: [references/files-and-base64.md](references/files-and-base64.md).
 
 ## Workflow Phases
 
 ### Phase 0: Discovery
 
-Before touching anything, understand what exists.
+Before touching anything, understand what exists — the workflow structure **and** whether the project has tests. Discovery ALWAYS includes checking for an `evals/` folder inside the project directory (`ls <project>/` — the folder is a sibling of `Workflow.json`, never at the workspace/solution root): Studio Web creates it when the Evaluations feature is enabled and the panel is opened, so its absence means the feature is off for this project. If present, read `evals/<scope>/eval-sets/*.json` (`<scope>` is `default` unless the project says otherwise) and the evaluator(s) in `evals/<scope>/evaluators/` — the same files the **Evaluations** panel reads and writes. Contract and semantics: [references/testing-and-evals.md](references/testing-and-evals.md) §1.
+
+Then apply **rule 22 (TDD gate)**: no `evals/` folder → the feature is off, continue to Phase 1 without any test or loop-mode question; `evals/` present → end the turn with the two questions — tests (change / add?) and loop mode — and start Phase 1 only after the user has answered, writing the eval set before the workflow.
 
 For **edit** requests:
 1. Read the existing workflow file with `Read`
@@ -135,6 +160,8 @@ Decide which activities to use and in what order.
 | Handle errors (skip & continue) | **TryCatch inside body** | One bad item skipped, loop continues — see [control-flow-patterns.md](references/control-flow-patterns.md#7-trycatch-inside-a-loop-body-skip-and-continue-error-handling) |
 | Return result and end | **Response** | `then: "end"`; `markJobAsFailed` sibling of `response` |
 | Pause execution | **Wait** | `wait.seconds`/`minutes`/`milliseconds` |
+| Encode a file (input or downloaded) as base64 for an API that wants inline base64 | **File to Base64** (`FileToBase64`) | `run.script` calling `await $helpers.file.fileToBase64(<ref>)`; output is a base64 FILE reference — inline it in the body with `.serializeData()`. Rule 23. |
+| Turn a base64 payload (API response string or a base64 file) back into a file | **Base64 to File** (`Base64ToFile`) | `run.script` calling `await $helpers.file.base64ToFile({ base64, fileName?, mimeType? })`; output is a binary file reference. Rule 23. |
 | Exit loop early | **Break (in If)** | Wrap Break in an If — there's no "break when" condition on Break itself. `break: "true"` (string!), `then: "exit"`, `set: "${$input}"` |
 | Exit nested loops | **Flag variable + Break twice** | Set a flag in inner loop, check + Break in outer — see [control-flow-patterns.md](references/control-flow-patterns.md#5-conditional-break-inside-a-loop) |
 | Call an arbitrary REST API (catfacts, stock prices, weather, any public/internal endpoint) | **Unified HTTP Request** (`call: "UiPath.Http"`, Http kind) | `connectionId: "ImplicitConnection"`. NEVER `call: "http"` (block icon). Via rule 16's flow. |
@@ -149,12 +176,16 @@ Before generating, determine:
 
 ### Phase 2: Generate or Edit
 
+**Precondition (projects with `evals/`):** the two rule-22 questions have been answered in this conversation and the eval set (if wanted) is already written. If not, go back to Phase 0 and ask — do not write `Workflow.json` yet. Projects without `evals/` have no such gate.
+
 For each activity, read its reference section in [references/task-types.md](references/task-types.md), copy the minimal JSON, fill in values.
 
 **For CREATE:** copy from a template, then add user activities AFTER `WorkflowStart` inside the root sequence (literally `Sequence_1.do` in the template skeleton).
 
 **For EDIT:** read the file first, identify the exact insertion / replacement point, use `Edit` with sufficient context for unique matching.
 
+If the edit **changes behavior** and the project has an eval set, rule 22 applies first: ask whether to update the expectations the change would invalidate, then edit, then re-run the rows (see [references/testing-and-evals.md](references/testing-and-evals.md) §3 step 5).
+
 Workflow skeleton:
 ```json
 {
@@ -187,7 +218,7 @@ Fix run failures in category order — **Structure > Expression > Activity Confi
 
 ### Phase 4: Package, Publish, and Operate
 
-Once the workflow runs locally, deploy via the solution packager. If the project must open in Studio Web, confirm it uses the `init`-produced shape first (rule 19a) — runtime/pack success does not prove it.
+Packaging needs a passing `validate` (rule 20), not a local run. When the request is to build, package, or publish, pack right away; rule 21 gates `uip api-workflow run`, never `uip solution pack`. Deploy via the solution packager. If the project must open in Studio Web, confirm it uses the `init`-produced shape first (rule 19a); runtime/pack success does not prove it.
 
 **Pack:**
 ```bash
@@ -223,6 +254,10 @@ uip solution init MySolution --output json
 cd ./MySolution
 uip api-workflow init MyApiProject --output json
 
+# 1b. TDD gate (rule 22): if ./MyApiProject/evals/ exists (next to Workflow.json), STOP and ask the two questions
+#     (tests: change / add?  loop mode?) and wait for the answers before step 2.
+#     No evals/ folder → the feature is off for this project; go straight to step 2.
+
 # 2. Edit MyApiProject/Workflow.json to add user activities after WorkflowStart inside the root sequence
 
 # 3. Validate (offline, autonomous — fix + re-validate until Status: Valid)
@@ -249,9 +284,11 @@ uip solution publish ./build/MyApiSolution_1.0.0.zip --tenant MyTenant --output
 | [references/control-flow-patterns.md](references/control-flow-patterns.md) | Combining activities into hierarchical structures — nested If, ForEach inside DoWhile, TryCatch around/inside loops, conditional Break, multi-way branching, key uniqueness rules |
 | [references/connector-activity-discovery.md](references/connector-activity-discovery.md) | Authoring HTTP Request / Gmail / Outlook / GitHub / Slack / etc. activities via `uip api-workflow registry resolve` + `stub` — three-step flow, sample stub output, field-shape rules, multipart subsection, worked examples |
 | [references/expressions-and-context.md](references/expressions-and-context.md) | Writing JS expressions, propagating outputs via `export.as`, accessing `$context` / `$input` / `$workflow`, JS_Invoke argument passing, strict-mode gotchas, key patterns |
+| [references/files-and-base64.md](references/files-and-base64.md) | **Files & base64** — `JobAttachment` references, the File to Base64 / Base64 to File activities (exact JSON, `$helpers.file.*`), `serializeData()` for inline bodies/Responses, passing local files in and getting files out of a run, pitfalls |
 | [references/cli-reference.md](references/cli-reference.md) | All `uip` commands — `api-workflow init`, `run`, `build`, `pack`, `validate`, `solution init`, `solution pack`, `solution publish`, `login` |
-| [references/operating-published-workflows.md](references/operating-published-workflows.md) | **Operating + diagnosing a published workflow** — invoke via HTTP/schedule/event triggers, manage Integration Service connections (`uip is connections`), start/list/stop Orchestrator jobs (`uip or jobs`), read cloud-run logs/traces (`uip or jobs logs`, `uip traces spans get`). Delegates depth to `uipath-platform` / `uipath-troubleshoot` |
+| [references/operating-published-workflows.md](references/operating-published-workflows.md) | **Operating + diagnosing a published workflow** — invoke via HTTP/schedule/event triggers, manage Integration Service connections (`uip is connections`), start/list/stop Orchestrator jobs (`uip or jobs`), diagnose a faulted cloud run (`uip or jobs get` — `jobs logs` and `traces spans get` are dead ends here). Delegates depth to `uipath-platform` / `uipath-troubleshoot` |
 | [references/troubleshooting.md](references/troubleshooting.md) | Failed runs, structure/expression/loop/nesting/response/validation pitfalls, packaging errors, publish errors, debugging strategy |
+| [references/testing-and-evals.md](references/testing-and-evals.md) | **Testing / evals** — the `evals/<scope>/eval-sets` + `evaluators` file contract shared with Studio Web's Evaluations panel, `uipath-exact-match` scoring (strict deep-equal on the RAW output — the CLI PascalCases printed keys), running a row locally with `--no-auth` (or through the host in Studio Web), and the **interactive test-until-green loop** (offer → check `evals/` → create/update cases → run/fix/repeat with progress → stale-expectation guard) |
 
 
 ## Templates
@@ -262,6 +299,7 @@ uip solution publish ./build/MyApiSolution_1.0.0.zip --tenant MyTenant --output
 | [assets/templates/conditional-workflow-example.json](assets/templates/conditional-workflow-example.json) | If branching with TryCatch — input validation + classification + error fallback |
 | [assets/templates/loop-aggregation-example.json](assets/templates/loop-aggregation-example.json) | DoWhile + ForEach + Assign accumulation — pure-compute aggregation pattern |
 | [assets/templates/nested-control-flow-example.json](assets/templates/nested-control-flow-example.json) | Heavy nesting demo — TryCatch around DoWhile around If with conditional Break |
+| [assets/templates/file-base64-roundtrip-example.json](assets/templates/file-base64-roundtrip-example.json) | **Files** — a `document` file input → File to Base64 → Base64 to File → Response returning both references. The exact `run.script` shape Studio Web writes for the two activities (rule 23). Verified end-to-end with a signed-in run: local file in → `.base64` reference → decoded file out, bytes identical. |
 | [assets/templates/connector-call-example.json](assets/templates/connector-call-example.json) | **Http kind** — HTTP Request curated activity (`call: "UiPath.Http"`) for arbitrary REST calls. Generated by `registry stub` against the catfacts URL. Shows the canonical shape: `connectionId: "ImplicitConnection"`, `unifiedTypesCompatible: true`, `savedJitInputFieldId: "in_http-request"`, URL in `bodyParameters.url`. Verified end-to-end with `uip api-workflow run --no-auth`. |
 | [assets/templates/vendor-curated-call-example.json](assets/templates/vendor-curated-call-example.json) | **IntSvc kind** — vendor curated activity (`call: "UiPath.IntSvc"`) using Outlook GetNewestEmail as exemplar. The `<REPLACE_WITH_VENDOR_CONNECTION_UUID>` placeholder is a sentinel — replace it with a pinged UUID from `uip is connections list/ping` **before** writing the workflow to disk. StudioWeb renders the literal placeholder as a broken connection if it survives. See rule 16. |
 | [assets/templates/solution-connection-resource-template.json](assets/templates/solution-connection-resource-template.json) | **Solution connection resource** — declares a IntSvc kind connection as a Solution resource. Write to `Solution/resources/solution_folder/connection/<connector-key>/<connection-name>.json`. Required for Solutions-mode projects; without it the StudioWeb properties panel flags the activity as having an invalid connection. |
@@ -274,11 +312,15 @@ The mistakes an agent makes most often (each maps to a Critical Rule above — s
 - **Do NOT** wrap connector `bodyParameters` / `queryParameters` literals as `${'literal'}` — rule 5's wrap is **inverted** for connectors; bare literals only, or the field clears on save. See rule 16.
 - **Do NOT** ship a `<REPLACE_WITH_*>` placeholder in a workflow — StudioWeb renders it as a broken connection and it 401s. No pinged UUID → ask the user. See rule 16.
 - **Do NOT** read workflow inputs as `$input.<name>` from a non-first activity — use `$workflow.input.<name>`. See rule 13.
+- **Do NOT** treat a file input or a File to Base64 result as a string — both are `JobAttachment` references. Inline a file's content only with `<ref>.serializeData()` inside an HTTP body / Response, never in an Assign or script — and inside a JSON body field only on the File to Base64 output (`$workflow.input.document.serializeData()` nested in a body fails with "Raw bytes cannot be embedded in JSON"). See rule 23.
+- **Do NOT** write `$helpers.fileToBase64(...)` / `$helpers.base64ToFile(...)` — the helpers live under `$helpers.file.`; `validate` rejects the task and the runtime says `is not a function`. See rule 23.
 - **Do NOT** invoke `uip api-workflow run` autonomously, and never with auth without an explicit "yes" — vendor calls have irreversible side effects (emails sent, tickets created). See rules 20–21.
 - **Do NOT** hand-assemble a project (`project.json` + `main.json`/`workflows/WF_*.json`). Scaffold with `uip api-workflow init <name>` — it writes the correct `project.uiproj` shape and registers it in the `.uipx`. The legacy `project.json`-only shape runs and packs but Studio Web rejects it (`invalid_project_folder`) and never shows it. See rules 19–19a.
 - **Do NOT** emit a lone `Workflow.json` with no project files, even for a quick local run. It runs under `uip api-workflow run` but is not a Studio Web project — can't be edited or shipped. Every workflow lives in an `init`-scaffolded project (`--skip-solution-registration` when no solution is needed). See rule 19a ("Which mode").
 - **Do NOT** wire a project into the solution with `uip solution projects add/remove` — it errors on an already-registered name, and `remove`+`add` destroys the project `Id`. `init` registers it; for an already-built project, edit the `.uipx` `ProjectRelativePath` in place. See rule 19a.
 - **Do NOT** trust "it packed / published / ran" as proof a project opens in Studio Web — every runtime gate passes on the wrong shape. Scaffolding with `init` is what guarantees it (rule 19a).
+- **Do NOT** copy expected outputs from the CLI's printed `Data` — `uip` PascalCases every key (`grade` → `Grade`) and `uipath-exact-match` is case-sensitive on keys, so the row passes for you and fails in the Evaluations panel. Derive keys from `output.schema` / the Response expression and read the raw output from the debug log. See [references/testing-and-evals.md](references/testing-and-evals.md) §2.
+- **Do NOT** author first and ask later in a project that has `evals/`: rule 22 ends the turn with the two test questions (change / add tests? loop mode?) BEFORE any `Workflow.json` or eval file is written, unless the user already answered or asked not to be prompted. **Do NOT** offer tests or loop mode — or create an `evals/` folder — in a project that has none: the feature is not enabled there. And **do NOT** "fix" the workflow to satisfy an expectation a requested behavior change made stale — re-derive the expected outputs instead, after asking. See rule 22 + [references/testing-and-evals.md](references/testing-and-evals.md) §3–4.
 
 ## Infinite Loop Prevention
 

package/skills/uipath-api-workflow/assets/templates/file-base64-roundtrip-example.json

@@ -0,0 +1,154 @@
+{
+  "document": {
+    "dsl": "1.0.0",
+    "namespace": "default",
+    "name": "file-base64-roundtrip",
+    "version": "0.0.1",
+    "metadata": {
+      "variables": {
+        "schema": {
+          "format": "json",
+          "document": {
+            "type": "object",
+            "properties": {},
+            "title": "Variables"
+          }
+        }
+      }
+    }
+  },
+  "evaluate": {
+    "language": "javascript",
+    "mode": "strict"
+  },
+  "input": {
+    "schema": {
+      "format": "json",
+      "document": {
+        "type": "object",
+        "properties": {
+          "document": {
+            "$ref": "#/definitions/job-attachment",
+            "description": "The file to encode (a JobAttachment reference)."
+          }
+        },
+        "required": ["document"],
+        "definitions": {
+          "job-attachment": {
+            "type": "object",
+            "properties": {
+              "ID": { "type": "string", "description": "Orchestrator attachment key" },
+              "FullName": { "type": "string" },
+              "MimeType": { "type": "string" },
+              "Metadata": { "type": "object" }
+            },
+            "required": ["ID"],
+            "x-uipath-resource-kind": "JobAttachment"
+          }
+        }
+      }
+    }
+  },
+  "output": {
+    "schema": {
+      "format": "json",
+      "document": {
+        "type": "object",
+        "properties": {
+          "encoded": { "$ref": "#/definitions/job-attachment" },
+          "decoded": { "$ref": "#/definitions/job-attachment" },
+          "encodedName": { "type": "string" },
+          "decodedName": { "type": "string" }
+        },
+        "definitions": {
+          "job-attachment": {
+            "type": "object",
+            "properties": {
+              "ID": { "type": "string", "description": "Orchestrator attachment key" },
+              "FullName": { "type": "string" },
+              "MimeType": { "type": "string" },
+              "Metadata": { "type": "object" }
+            },
+            "required": ["ID"],
+            "x-uipath-resource-kind": "JobAttachment"
+          }
+        }
+      }
+    }
+  },
+  "do": [
+    {
+      "Sequence_1": {
+        "do": [
+          {
+            "WorkflowStart": {
+              "set": "${Object.entries($workflow.definition?.document?.metadata?.variables?.schema?.document?.properties || {}).reduce((acc, [name, def]) => ({ ...acc, [name]: def?.default }), {}) }",
+              "output": { "as": "${$input}" },
+              "export": { "as": "{ ...$context, variables: { ...$context.variables, ...$output } }" },
+              "metadata": {
+                "activityType": "Assign",
+                "displayName": "Workflow start",
+                "fullName": "Assign",
+                "isTransparent": true
+              }
+            }
+          },
+          {
+            "FileToBase64_1": {
+              "run": {
+                "script": {
+                  "code": "return { output: await $helpers.file.fileToBase64($workflow.input.document) }",
+                  "language": "javascript",
+                  "arguments": "${{ \"$context\": $context, \"$workflow\": $workflow, \"$input\": $input }}"
+                }
+              },
+              "export": { "as": "{ ...$context, outputs: { ...$context?.outputs, \"FileToBase64_1\": $output } }" },
+              "metadata": {
+                "activityType": "FileToBase64",
+                "displayName": "File to Base64",
+                "fullName": "FileToBase64",
+                "icon": "sw:convert-file-to-base64"
+              }
+            }
+          },
+          {
+            "Base64ToFile_1": {
+              "run": {
+                "script": {
+                  "code": "return { output: await $helpers.file.base64ToFile({ base64: $context.outputs.FileToBase64_1.output }) }",
+                  "language": "javascript",
+                  "arguments": "${{ \"$context\": $context, \"$workflow\": $workflow, \"$input\": $input }}"
+                }
+              },
+              "export": { "as": "{ ...$context, outputs: { ...$context?.outputs, \"Base64ToFile_1\": $output } }" },
+              "metadata": {
+                "activityType": "Base64ToFile",
+                "displayName": "Base64 to File",
+                "fullName": "Base64ToFile",
+                "icon": "sw:convert-base64-to-file"
+              }
+            }
+          },
+          {
+            "Response_1": {
+              "response": "${{ encoded: $context.outputs.FileToBase64_1.output, decoded: $context.outputs.Base64ToFile_1.output, encodedName: $context.outputs.FileToBase64_1.output.FullName, decodedName: $context.outputs.Base64ToFile_1.output.FullName }}",
+              "markJobAsFailed": false,
+              "then": "end",
+              "export": { "as": "{ ...$context, outputs: { ...$context?.outputs, \"Response_1\": $output } }" },
+              "metadata": {
+                "activityType": "Response",
+                "displayName": "Response",
+                "fullName": "Response"
+              }
+            }
+          }
+        ],
+        "metadata": {
+          "activityType": "Sequence",
+          "displayName": "Sequence",
+          "fullName": "Sequence"
+        }
+      }
+    }
+  ]
+}

package/skills/uipath-api-workflow/assets/templates/nested-control-flow-example.json

@@ -182,7 +182,6 @@
                                                         "Break_1": {
                                                           "break": "true",
                                                           "then": "exit",
-                                                          "set": "${$input}",
                                                           "metadata": { "activityType": "Break", "displayName": "Out Of Retries", "fullName": "Break" }
                                                         }
                                                       }

package/skills/uipath-api-workflow/references/cli-reference.md

@@ -91,6 +91,9 @@ Execute an API workflow JSON file locally using the Serverless Workflow executor
 ```bash
 uip api-workflow run <file> \
   [--input-arguments <json>] \
+  [--input-file <name>=<path>]... \
+  [--output-dir <dir>] \
+  [--folder-key <guid>] \
   [--no-auth] \
   [--output json]
 ```
@@ -99,7 +102,10 @@ uip api-workflow run <file> \
 |-----------------|----------|-------------|
 | `<file>` | yes | Path to the workflow JSON file. |
 | `-i, --input-arguments <json>` | no | Input arguments as a JSON string (e.g., `'{"name":"World"}'`). Invalid JSON exits 1. |
-| `--no-auth` | no | Skip credential loading. Use for workflows that don't need Orchestrator/IS auth — control-flow-only workflows, or Http kind activities using `connectionId: "ImplicitConnection"`. IntSvc kind (vendor connector) activities always need auth at run time. |
+| `--input-file <name>=<path>` | no (repeatable) | Upload a local file to Orchestrator blob storage and pass the resulting `JobAttachment` reference as input `<name>` — the same object Studio Web's run panel produces, read as `$workflow.input.<name>`. MIME type from the extension. Needs a signed-in session; refused with `--no-auth`. |
+| `--output-dir <dir>` | no | After a successful run, download every `JobAttachment` reference found in the output into `<dir>`; each downloaded reference in the printed `Data` gains a `LocalPath`. Same-named blobs get an `-<Id>` suffix. Needs a signed-in session. |
+| `--folder-key <guid>` | no | Orchestrator folder key for the attachments the run creates (uploaded inputs and the files written by File to Base64 / Base64 to File). Pass it when the tenant's Attachments API rejects folder-less requests. |
+| `--no-auth` | no | Skip credential loading. Use for workflows that don't need Orchestrator/IS auth — control-flow-only workflows, or Http kind activities using `connectionId: "ImplicitConnection"`. IntSvc kind (vendor connector) activities always need auth at run time, and so do file features: a workflow calling `$helpers.file.*` (File to Base64 / Base64 to File) is refused up front under `--no-auth`, as are `--input-file` / `--output-dir`. |
 | `--output json` | no | Emit machine-readable JSON. Strongly recommended when output is parsed. |
 
 ### Success output
@@ -131,6 +137,11 @@ Exit code: `1`. Common `Message` values:
 - `"Invalid JSON in workflow file"`
 - `"Invalid JSON in --input-arguments"`
 - `"<task error>"` (executor-level failure)
+- `"Invalid --input-file value '<value>'. Expected <name>=<path> …"`
+- `"--input-file needs a signed-in session …"` / `"--output-dir needs a signed-in session …"` (used with `--no-auth`)
+- `"This workflow uses the file helpers ($helpers.file.fileToBase64 / $helpers.file.base64ToFile …) … cannot run with --no-auth"`
+- `"Input file for '<name>' not found: <path>"` / `"Failed to upload input file '<name>' (<file>): …"`
+- `"The workflow completed, but downloading its output files to <dir> failed: …"` (the run succeeded; its output — with the attachment IDs — is still printed under `Data`)
 
 ### Examples
 
@@ -142,6 +153,14 @@ uip api-workflow run ./hello.json --no-auth --output json
 uip api-workflow run ./greet.json \
   --input-arguments '{"name":"Alice","count":3}' \
   --output json
+
+# With a file input and file outputs (needs `uip login`; no --no-auth)
+uip api-workflow run ./MyApiProject/Workflow.json \
+  --input-file document=./invoice.pdf \
+  --output-dir ./out \
+  --output json
+# → Data.<Key> = { "Id": "...", "FullName": "invoice.base64", "MimeType": "text/plain",
+#                  "Metadata": { "Size": 1234, "Encoding": "base64" }, "LocalPath": "/abs/out/invoice.base64" }
 ```
 
 ## `uip api-workflow registry`

package/skills/uipath-api-workflow/references/expressions-and-context.md

@@ -11,6 +11,7 @@ API workflows use **JavaScript** for all expressions (`evaluate.language: "javas
 | `$input` | The **current task's input** = the previous task's `$output`. **NOT the workflow's input arguments.** Only equals workflow input on the very first task. | Per-task |
 | `$context` | Mutable shared state: `$context.variables.<name>`, `$context.outputs.<Activity>` | Workflow run |
 | `$output` | The current task's raw output. | This task only |
+| `$helpers` | Engine host functions, available in `run.script` code: `$helpers.file.fileToBase64(ref)` and `$helpers.file.base64ToFile({ base64, fileName?, mimeType? })` — both `async`, so `await` them. See [File references](#file-references-jobattachment-and-helpersfile). | Inside scripts |
 | Loop bindings | Whatever name you set in `for.each` / `for.at`, prefixed with `$`. Examples: `for.each: "currentItem"` → `${$currentItem}`, `for.each: "customer"` → `${$customer}`, `for.at: "idx"` → `${$idx}`. The `$` is a literal character in the identifier — the unprefixed name is NOT bound. | Inside the loop body |
 | Catch binding | `${$error}` — `catch.as: "error"` binds the global as `$error` (note the `$` prefix, same convention as loop iterators). Reference fields like `${$error.title}` / `${$error.detail}` / `${$error.originatingTaskName}`. | Inside `catch.do` |
 
@@ -259,6 +260,22 @@ Javascript_1        → adds $context.outputs.Javascript_1 (final summary comput
 Response_1          → reads any $context data, ends workflow
 ```
 
+## File References (`JobAttachment`) and `$helpers.file`
+
+A file anywhere in a workflow — a file input, a binary HTTP response, the result of the base64 activities — is a **reference**, not bytes:
+
+```json
+{ "ID": "6f1c…", "FullName": "invoice.pdf", "MimeType": "application/pdf", "Metadata": { "Size": 48213, "Encoding": "byte-array" } }
+```
+
+- `$workflow.input.<file>` is that object. `$workflow.input.document.FullName` works; there is no `.content` / `.bytes`.
+- `Metadata.Encoding` is `"byte-array"` (binary) or `"base64"` (the blob holds base64 text — what File to Base64 produces). It is a tag, nothing is converted on read.
+- `await $helpers.file.fileToBase64(ref)` → a new `"base64"`-tagged reference (`<name>.base64`). Idempotent for an already-base64 reference.
+- `await $helpers.file.base64ToFile({ base64: refOrString, fileName?, mimeType? })` → a new binary reference. `fileName` / `mimeType` only apply to a string input.
+- `ref.serializeData()` — the one way to get a file's *content* into an HTTP request body or a Response field: `"${{ content: $context.outputs.FileToBase64_1.output.serializeData() }}"`. It returns a small deferred-read marker (`{ __uipathFileRead: { ref } }`) that the engine replaces with the content at send/egress time, so large data never enters `$context`. Use it only inline in a body / Response — not in an Assign, a variable, or script logic. Nested inside a JSON body field it is valid **only on a base64 reference** (File to Base64 output); a binary reference's marker or a bare reference nested in a body is a send-time error. A bare reference as the *whole* HTTP body is sent as the file's bytes.
+
+Full guide (activity JSON, CLI run, pitfalls): [files-and-base64.md](files-and-base64.md).
+
 ## Anti-patterns
 
 - **Do NOT** use `$input.<name>` to read workflow inputs from non-first tasks — `$input` is the previous task's `$output`. Use `$workflow.input.<name>`.
@@ -267,3 +284,5 @@ Response_1          → reads any $context data, ends workflow
 - **Do NOT** use `var` inside JS_Invoke scripts — strict mode rejects implicit globals; use `const` / `let`.
 - **Do NOT** wrap loop variable names (`each`, `at`) in `${...}` — those fields take plain identifiers.
 - **Do NOT** mix `${...}` and string concatenation when a single expression form works: prefer `"${\"prefix-\" + $workflow.input.x}"` over splitting.
+- **Do NOT** read a file input as text or bytes (`$workflow.input.document.content`) — inputs of file type are `JobAttachment` references. Convert with `$helpers.file.*` or inline with `.serializeData()`.
+- **Do NOT** store `serializeData()` in a variable or pass it through a script — the marker is only resolved inside an HTTP body / Response.

package/skills/uipath-api-workflow/references/files-and-base64.md

@@ -0,0 +1,153 @@
+# Files & Base64 in API Workflows
+
+How an API workflow handles files, and how the **File to Base64** / **Base64 to File** activities work — the JSON to write, the runtime behavior to expect, and how to run such a workflow from the CLI.
+
+## 1. A file is a reference, not bytes
+
+Every file an API workflow touches is a `JobAttachment`: a small object pointing at a blob in Orchestrator storage.
+
+```json
+{
+  "ID": "6f1c0d2e-8a1b-4c3d-9e0f-123456789abc",
+  "FullName": "invoice.pdf",
+  "MimeType": "application/pdf",
+  "Metadata": { "Size": 48213, "Encoding": "byte-array" }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `ID` | Attachment key in Orchestrator (GUID) |
+| `FullName` | File name with extension |
+| `MimeType` | Content type |
+| `Metadata.Size` | Byte length, when known |
+| `Metadata.Encoding` | `"byte-array"` (binary — the default) or `"base64"` (the blob's content is base64 *text*). A tag only: nothing is converted when reading |
+
+Consequences:
+- A file input declared in `input.schema` (`"$ref": "#/definitions/job-attachment"`, `x-uipath-resource-kind: "JobAttachment"`) arrives as this object: `$workflow.input.document.FullName` works; there is no `.content`.
+- File bytes never enter `$context`, so context stays small no matter how big the file is.
+- Everything that reads or writes files goes through Orchestrator blob storage, so it needs a signed-in session.
+
+## 2. The two activities
+
+Both are ordinary `run.script` tasks. What makes them *these* activities — for Studio Web's designer, for `uip api-workflow validate`, and for the engine — is `metadata.activityType` plus the `$helpers.file.*` call in the script.
+
+**The script is one `return` expression and nothing else.** Studio Web does not keep the script text: on open it parses the `$helpers.file.*` call to fill the property panel, and on save it **rebuilds the script from the panel**. Anything the parser did not pick up is dropped silently, and the workflow breaks (or loses arguments) at the next designer save. The only shapes that survive a roundtrip:
+
+- File to Base64: `return { output: await $helpers.file.fileToBase64(<ref>) }` — exactly **one** argument
+- Base64 to File: `return { output: await $helpers.file.base64ToFile({ base64: <ref or string>, fileName?: <expr>, mimeType?: <expr> }) }` — exactly **one** object argument, only those keys
+
+Dropped on save: a statement before the `return` (`const ref = …;`), a statement after it, a second argument (`fileToBase64(ref, { extra: 1 })`), extra keys in the options object. `uip api-workflow validate` warns about the extra statements ("rebuilds the script … and drops the rest, which breaks the workflow") but reports `Valid` with **no warning** for an extra argument or extra option key — check that shape yourself before validating. Any pre-processing (picking the right reference, normalising a string) goes in a JavaScript activity *before* the conversion; pass its output in as the single argument.
+
+### File to Base64 (`FileToBase64`)
+
+`await $helpers.file.fileToBase64(<file ref>)` → a **new** reference whose blob content *is* the base64 text: `<baseName>.base64`, `text/plain`, `Metadata.Encoding: "base64"`. Idempotent for an already-base64 reference. Input must be a reference (a string is a validation error).
+
+```json
+{
+  "FileToBase64_1": {
+    "run": {
+      "script": {
+        "code": "return { output: await $helpers.file.fileToBase64($workflow.input.document) }",
+        "language": "javascript",
+        "arguments": "${{ \"$context\": $context, \"$workflow\": $workflow, \"$input\": $input }}"
+      }
+    },
+    "export": { "as": "{ ...$context, outputs: { ...$context?.outputs, \"FileToBase64_1\": $output } }" },
+    "metadata": { "activityType": "FileToBase64", "displayName": "File to Base64", "fullName": "FileToBase64", "icon": "sw:convert-file-to-base64" }
+  }
+}
+```
+
+Downstream: `$context.outputs.FileToBase64_1.output` (a `JobAttachment`).
+
+### Base64 to File (`Base64ToFile`)
+
+`await $helpers.file.base64ToFile({ base64, fileName?, mimeType? })` → a **new binary** reference.
+- `base64` is a base64 file reference (from File to Base64) **or** a raw base64 string (an API response field, a variable).
+- `fileName` / `mimeType` apply only to a **string** input. Omitted → MIME sniffed from the bytes, unique GUID-based name, extension from the MIME type. For a reference input they are ignored: the engine strips `.base64` and sniffs the type (plain text has no signature, so a `.txt` comes back extension-less as `application/octet-stream`).
+- A reference that is **not** tagged `Encoding: "base64"` (a plain binary file) is returned unchanged — there is nothing to decode. Chaining Base64 to File directly on a raw file input is therefore a no-op, not an error.
+- Omit the optional keys when unset — `fileName: ` with no value is a syntax error.
+
+```json
+{
+  "Base64ToFile_1": {
+    "run": {
+      "script": {
+        "code": "return { output: await $helpers.file.base64ToFile({ base64: $context.outputs.HTTP_Request_1.content.data, fileName: 'invoice.pdf', mimeType: 'application/pdf' }) }",
+        "language": "javascript",
+        "arguments": "${{ \"$context\": $context, \"$workflow\": $workflow, \"$input\": $input }}"
+      }
+    },
+    "export": { "as": "{ ...$context, outputs: { ...$context?.outputs, \"Base64ToFile_1\": $output } }" },
+    "metadata": { "activityType": "Base64ToFile", "displayName": "Base64 to File", "fullName": "Base64ToFile", "icon": "sw:convert-base64-to-file" }
+  }
+}
+```
+
+A disabled activity gets `"if": "${false}"` on the task, like any other.
+
+## 3. Getting a file's *content* into a request or a Response: `serializeData()`
+
+`fileToBase64` gives you a file, not a string. To send the base64 text to an API, call `serializeData()` on the reference **inside the HTTP body or the Response expression**:
+
+```json
+"bodyParameters": { "body": "${{ name: $workflow.input.document.FullName, content: $context.outputs.FileToBase64_1.output.serializeData() }}" }
+```
+
+```json
+"response": "${{ encoded: $context.outputs.FileToBase64_1.output.serializeData() }}"
+```
+
+`serializeData()` is synchronous and returns a small deferred-read marker (`{ "__uipathFileRead": { "ref": … } }`); the engine replaces it with the file's content when the request is sent / the Response leaves the run. Rules:
+- Use it **only** inline in an HTTP body or a Response field.
+- Do **not** assign it to a variable, return it from a script, or run logic on it — you would keep the marker, not the content.
+- **Nested in a JSON body field, only a base64 reference works** (the File to Base64 output). A `serializeData()` marker on a *binary* reference nested in a body fails at send time with `Raw bytes cannot be embedded in JSON — convert the file with File to Base64 first`, and a *bare* reference nested in a body fails with `A bare file reference cannot be embedded in a nested field`. So: `content: $workflow.input.document.serializeData()` is wrong; `content: $context.outputs.FileToBase64_1.output.serializeData()` is right.
+- To send a binary file **as-is**, make the bare reference the *whole* HTTP body — it is sent as the file's bytes with its `MimeType` as `Content-Type` (no `serializeData()` needed).
+- In a Response, markers are resolved anywhere; bare references are returned as references.
+
+## 4. A complete round trip
+
+[assets/templates/file-base64-roundtrip-example.json](../assets/templates/file-base64-roundtrip-example.json): `document` file input → `FileToBase64_1` → `Base64ToFile_1` → `Response_1` returning both references. The typical real-world chain is `File to Base64 → HTTP POST (body uses .serializeData()) → Base64 to File (vendor's base64 response string, with fileName/mimeType) → Response`.
+
+## 5. Running a workflow that uses files
+
+Files live in Orchestrator blob storage, so the run needs a session — `uip api-workflow run --no-auth` refuses a workflow that calls `$helpers.file.*` before the engine starts (and refuses `--input-file` / `--output-dir`). Rule 21 still applies: ask before running.
+
+```bash
+uip login                                  # once
+uip api-workflow run ./MyApiProject/Workflow.json \
+  --input-file document=./invoice.pdf \    # upload → $workflow.input.document (repeatable)
+  --output-dir ./out \                     # download every reference in the output
+  --output json
+```
+
+- `--input-file <name>=<path>`: the local file is uploaded (MIME type from the extension) and the reference is placed under `<name>` in the input — exactly what Studio Web's run panel produces.
+- `--output-dir <dir>`: every `JobAttachment` in the output is downloaded into `<dir>`; the printed reference gains `LocalPath`. Same-named blobs get an `-<Id>` suffix.
+- `--folder-key <guid>`: when the tenant's Attachments API requires a folder.
+- The CLI PascalCases printed keys: `ID` → `Id`, `encoded` → `Encoded`.
+
+Example output:
+
+```json
+{
+  "Result": "Success",
+  "Code": "WorkflowRun",
+  "Data": {
+    "Encoded": { "Id": "…", "FullName": "hello.base64", "MimeType": "text/plain", "Metadata": { "Size": 72, "Encoding": "base64" }, "LocalPath": "/abs/out/hello.base64" },
+    "Decoded": { "Id": "…", "FullName": "hello", "MimeType": "application/octet-stream", "Metadata": { "Size": 54, "Encoding": "byte-array" }, "LocalPath": "/abs/out/hello" }
+  }
+}
+```
+
+`uip api-workflow validate` covers these activities offline: it accepts `FileToBase64` / `Base64ToFile` and rejects a task of either type whose script does not call its `$helpers.file.*` function.
+
+## 6. Limits and gotchas
+
+- **Size:** file references have no practical size cap — a reference with a declared `Metadata.Size` above 1 MB, or with **no** declared size (common for job inputs), streams with bounded memory at any size. Only in-memory inputs are capped at 50 MB per conversion: a raw base64 *string*, or a reference small enough to be buffered.
+- **Namespace:** `$helpers.fileToBase64` (no `.file.`) fails with `is not a function` and fails `validate`.
+- **Invalid base64:** a `data:…;base64,` prefix and whitespace/line breaks are **tolerated** (stripped before decoding). What is rejected with `The provided value is not a valid base64 string: base64ToFile`: the URL-safe alphabet (`-` / `_`), other non-base64 characters, bad padding, and an empty string. The suffix is always the literal helper name `base64ToFile`, never your task key — grep logs for the message text, not for `Base64ToFile_1`.
+- **Names:** `fileName` / `mimeType` never rename a reference input; a decoded text file loses its extension.
+- **Preview feature:** in Studio Web the two activities sit behind the `FE.EnableBase64Activities` flag and are marked "in preview".
+
+Pitfalls with symptoms and fixes: [troubleshooting.md](troubleshooting.md#file--base64-pitfalls).

package/skills/uipath-api-workflow/references/operating-published-workflows.md

@@ -68,9 +68,10 @@ Two surfaces that look useful and are NOT, for API-workflow jobs:
 | Command | What it actually returns |
 |---------|--------------------------|
 | `uip or jobs logs <jobId>` | Lifecycle lines only — `"Workflow started"` / `"Workflow completed"`, both at level `Info`. It reports **`Workflow completed` even for a Faulted job** and never carries the error. Do not diagnose from it, and never read "completed" as success. |
-| `uip traces spans get --job-key <jobKey>` | Fails with `"Error retrieving trace ID for job"`. API-workflow jobs have no span/trace surface. |
+| `uip traces spans get --job-key <jobKey>` | Returned `"Error retrieving trace ID for job"` on every API-workflow job probed. The CLI emits that message for any trace-ID lookup failure (a malformed GUID included), so read it as "no trace resolved for this job" rather than proof the surface is absent. Either way it carries no fault detail. |
+| `uip or jobs traces <jobId>` | Documented Agent-type-process-only — not applicable to an API-workflow job. |
 
-> **Diagnose before you tear down.** Uninstalling the deployment destroys its job records — `uip or jobs get <jobId>` then returns `Result: Failure` with an empty `State`. Capture what you need while the deployment still stands.
+> **Diagnose before you tear down.** After uninstalling the deployment, `uip or jobs get <jobId>` returns `Result: Failure` with an empty `State`. Jobs themselves are immutable audit records (`uip or jobs --help`: they "cannot be deleted -- they age out per the binding process's retention period"), so the likely cause is that the folder/process context needed to resolve the job is gone, not the records. Either way, capture what you need while the deployment still stands.
 
 > For per-activity detail the local loop is stronger than anything in cloud: reproduce with `uip api-workflow run <Workflow.json> --no-auth --output json`, which names the failing activity. Cloud gives you the fault message; local gives you its position.