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

package/skills/uipath-api-workflow/references/task-types.md

@@ -14,6 +14,8 @@ Detailed reference for the activity types supported in the API Workflow DSL —
 | TryCatch | `try` + `catch` | Error handling |
 | Wait | `wait` | Pause execution |
 | Response | `response` + `then: "end"` | Return result and end the workflow |
+| File to Base64 | `run.script` calling `$helpers.file.fileToBase64` | Encode a file reference as a base64 file. See [files-and-base64.md](files-and-base64.md) |
+| Base64 to File | `run.script` calling `$helpers.file.base64ToFile` | Decode a base64 file reference or string into a binary file. See [files-and-base64.md](files-and-base64.md) |
 | HTTP Request (Http kind) | `call: "UiPath.Http"` | Call an arbitrary REST API — use `uip api-workflow registry resolve` + `stub`. See [connector-activity-discovery.md](connector-activity-discovery.md) |
 | Connector activity (IntSvc kind) | `call: "UiPath.IntSvc"` | Call a vendor service (Slack, Outlook, Gmail, GitHub, …) — use `uip api-workflow registry resolve` + `stub` with a pinged connection. See [connector-activity-discovery.md](connector-activity-discovery.md) |
 
@@ -307,7 +309,12 @@ The body MUST update the condition variable, otherwise the loop runs forever.
 
 Exits a loop early. Only valid inside `For_Each_N#Body` or `Do_While_N#Body`.
 
-**Required fields:** `break: "true"` (string!), `then: "exit"`, `set: "${$input}"`, `metadata`
+**Required fields:** `break: "true"` (string!), `then: "exit"`, `metadata`
+
+> **Do NOT add `set` to a Break.** The schema rejects it: a Break carrying
+> `set: "${$input}"` fails `validate` with **7797 errors**; removing that one key makes it
+> Valid, with identical runtime output (same `Completed`/`Failed`). Break needs no `set` —
+> it does not propagate context.
 
 **Minimal JSON:**
 ```json
@@ -315,7 +322,6 @@ Exits a loop early. Only valid inside `For_Each_N#Body` or `Do_While_N#Body`.
   "Break_1": {
     "break": "true",
     "then": "exit",
-    "set": "${$input}",
     "metadata": { "activityType": "Break", "displayName": "Break", "fullName": "Break" }
   }
 }
@@ -326,7 +332,7 @@ Typically wrapped in an `If` inside the body — break only when a condition is
 **Common mistakes:**
 - Boolean `true` instead of string `"true"` (must be a JSON string)
 - Placing Break outside a loop `#Body`
-- Missing `set: "${$input}"` (required for context propagation)
+- Adding `set` to the Break (schema rejects it — see the note above)
 
 **Scoping:**
 - Break exits **only the innermost enclosing loop**. To exit an outer loop from inside a nested loop, set a flag variable (Assign) before Break, then check the flag in the outer loop's `doWhile` (or in an `If` after the inner loop) and Break again.
@@ -480,3 +486,83 @@ The simple single-expression form is fine; the designer corruption only affects
 - Nesting `markJobAsFailed` inside `response` — it MUST be a sibling
 - Placing Response in the middle of a sequence — it should be at the end of an execution path
 - Using legacy `set: <object>` form instead of `response` + `then: "end"` — runtime accepts it but designer roundtrip breaks
+
+---
+
+## 11. File to Base64
+
+Encodes a file reference as base64 — the result is a NEW `JobAttachment` whose blob content **is** the base64 text (`<name>.base64`, `text/plain`, `Metadata.Encoding: "base64"`). It is a `run.script` task; what makes it this activity is `metadata.activityType: "FileToBase64"` plus the `$helpers.file.fileToBase64(...)` call (Studio Web restores the property panel by parsing that call).
+
+**Required fields:** `run.script.code` (`return { output: await $helpers.file.fileToBase64(<file ref>) }`), `run.script.language: "javascript"`, `run.script.arguments` (standard block), `export.as`, `metadata.activityType: "FileToBase64"`
+
+**Export pattern:**
+```
+{ ...$context, outputs: { ...$context?.outputs, "FileToBase64_N": $output } }
+```
+
+**Output:** `$context.outputs.FileToBase64_N.output` — a `JobAttachment`. To inline the base64 text in an HTTP body or Response: `$context.outputs.FileToBase64_N.output.serializeData()`.
+
+**Minimal JSON:**
+```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" }
+  }
+}
+```
+
+**Common mistakes:**
+- `$helpers.fileToBase64(...)` (namespace dropped) — `validate` errors, runtime `is not a function`
+- Anything besides the single `return` expression — a statement before/after it, or a second argument (`fileToBase64(ref, { extra: 1 })`) — Studio Web drops it on save; `validate` warns about the statements only, an extra argument passes silently
+- Using the output as a string (`.length`, concatenation, `Assign` into a string variable) — it is a file reference; use `.serializeData()` inline in a body/Response
+- Passing a base64 string instead of a file reference — `fileToBase64` accepts only a reference; a string input is a validation error
+- Running with `--no-auth` — needs Orchestrator blob storage (see [files-and-base64.md](files-and-base64.md))
+
+---
+
+## 12. Base64 to File
+
+Decodes base64 into a binary file reference. Input is either a base64 **file** reference (from File to Base64) or a raw base64 **string** (an API response field, a variable). `fileName` / `mimeType` are optional and used only for a string input; omitted → MIME sniffed from the bytes, unique GUID name.
+
+**Required fields:** `run.script.code` (`return { output: await $helpers.file.base64ToFile({ base64: <ref or string>, fileName?: <expr>, mimeType?: <expr> }) }`), `run.script.language: "javascript"`, `run.script.arguments`, `export.as`, `metadata.activityType: "Base64ToFile"`
+
+**Export pattern:**
+```
+{ ...$context, outputs: { ...$context?.outputs, "Base64ToFile_N": $output } }
+```
+
+**Output:** `$context.outputs.Base64ToFile_N.output` — a binary `JobAttachment` (`Metadata.Encoding: "byte-array"`).
+
+**Minimal JSON (string input with a name and type):**
+```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" }
+  }
+}
+```
+
+For a file-reference input drop `fileName` / `mimeType`: `base64ToFile({ base64: $context.outputs.FileToBase64_1.output })`. Omit the optional keys entirely when unset — a dangling `fileName: ` is a syntax error.
+
+**Common mistakes:**
+- `$helpers.base64ToFile(...)` (namespace dropped)
+- Anything besides the single `return` expression — a statement before/after it, or extra keys in the options object — Studio Web drops it on save; `validate` warns about the statements only, extra keys pass silently
+- Expecting `fileName` / `mimeType` to rename a reference input — they are ignored for references
+- URL-safe base64 (`-` / `_`), non-base64 characters, bad padding or an empty string → `The provided value is not a valid base64 string: base64ToFile` at runtime — the suffix is the literal helper name, not the task key (a `data:…;base64,` prefix and whitespace are tolerated and stripped)
+- Chaining it directly on a *binary* reference — a reference without `Encoding: "base64"` is returned unchanged (no-op), so nothing happens

package/skills/uipath-api-workflow/references/testing-and-evals.md

@@ -0,0 +1,224 @@
+# Testing API Workflows — Evals & the Test-Until-Green Loop
+
+API Workflows have a **dataset-test / eval** capability: a set of `(inputs, expectedOutput)` rows the workflow is run against, each scored by an evaluator. The dataset is **plain JSON files inside the project** (`evals/…`), so it is shared between:
+
+- **Studio Web's designer** — the **Evaluations** panel in the bottom dock of an API-workflow project (local *and* cloud workspaces; feature-flagged). It runs each row through the normal debug pipeline, scores it, and shows pass/fail, actual vs expected, and the run's logs. Results live in memory only — there is **no results file**.
+- **This skill / an agent** — which authors the same files, runs the rows headlessly with `uip api-workflow run`, scores them the same way, and reports.
+
+Because the tests are files, the agent can author them, run them, fix the workflow, and repeat — a **test-until-green loop**. The panel live-reloads external edits to `evals/` (local: file watcher; cloud: file-system notifications), so what you write shows up there.
+
+---
+
+## 1. The eval files (the contract)
+
+```
+<PROJECT>/evals/<SCOPE>/eval-sets/<set>.json          # datasets — one file per eval set
+<PROJECT>/evals/<SCOPE>/evaluators/<evaluator>.json   # scorers — one file per evaluator
+<PROJECT>/evals/<SCOPE>/eval-files/                   # panel-managed uploads — leave alone
+```
+
+`<SCOPE>` is `default` unless the project already uses another one. Studio Web creates the folder when the Evaluations feature is enabled and the panel is first opened, seeding `evals/default/evaluators/exact-match-evaluator.json` and an empty `evals/default/eval-sets/evaluation-set.json`. **A project without an `evals/` folder has the feature turned off — leave it that way (SKILL.md rule 22).** When you add rows or files inside an existing folder, use the same names and shapes.
+
+**`evals/default/eval-sets/evaluation-set.json`** — the dataset:
+
+```json
+{
+  "version": "1.0",
+  "id": "eval-set-001",
+  "name": "Dataset",
+  "evaluatorRefs": ["exact-match-evaluator"],
+  "evaluations": [
+    {
+      "id": "6f1c1b4e-2c3a-4d5e-9f10-111213141516",
+      "name": "score 85 passes",
+      "inputs": { "score": 85 },
+      "evaluationCriterias": {
+        "exact-match-evaluator": { "expectedOutput": { "grade": "PASS" } }
+      }
+    }
+  ]
+}
+```
+
+**`evals/default/evaluators/exact-match-evaluator.json`** — how rows are scored:
+
+```json
+{
+  "version": "1.0",
+  "id": "exact-match-eval-001",
+  "name": "Exact Match",
+  "description": "Exact Match",
+  "evaluatorTypeId": "uipath-exact-match",
+  "evaluatorConfig": {
+    "name": "Exact Match",
+    "targetOutputKey": "*",
+    "defaultEvaluationCriteria": { "expectedOutput": {} }
+  }
+}
+```
+
+**Rules.**
+
+1. **Refs are file base names, not ids.** Every entry of `evaluatorRefs` and every key of a row's `evaluationCriterias` is the evaluator's **file name without `.json`** (`exact-match-evaluator` above) — not its `id`. Renaming the evaluator file orphans every row ("No expected output could be matched to this evaluator" → fail). Keep one exact-match evaluator per set unless the project already has more.
+2. **Expected output goes in `evaluationCriterias["<ref>"].expectedOutput`**, never at the row top level. It is an object shaped like the workflow output (a JSON string is tolerated and parsed, but write an object).
+3. **Score with the evaluator the PROJECT declares — read `evaluatorTypeId`, don't assume.** Studio Web's panel supports exactly one type today, **`uipath-exact-match`**; if a project ever declares another, honor it instead of forcing exact-match.
+4. **`uipath-exact-match` is a strict machine deep-equal, not a "looks right" judgment.** Key order is ignored; **key names, their exact casing, value types, and object shape must all equal the workflow's RAW output**. `{ "sum": 5 }` ≠ `{ "Sum": 5 }` → fail, even though the number is right. `evaluatorConfig.targetOutputKey` picks what is compared: `"*"` (or absent) compares the whole output object with the whole `expectedOutput`; a dotted path such as `details.rawScore` compares `output.details.rawScore` with `expectedOutput.details.rawScore` (so `expectedOutput` stays a full nested object); an array compares every listed path. A path missing on both sides is a **fail**, not a vacuous pass. `ignoreCase` / `negated` are not applied by the designer — don't rely on them.
+5. **"Output" means the workflow's Response payload, raw.** Original key casing, as the `Response` expression produces it. A bare primitive or array is wrapped as `{ "result": <value> }`.
+6. **Patch the files in place.** The panel adds bookkeeping fields (`schemaVersion`, `target`, `fileName`, `createdAt`, `updatedAt`) — keep whatever is there, never reshape or regenerate a file the user may have edited in the UI. An open edit form in the panel still wins on save (last writer wins).
+7. **Results are not files.** Report verdicts in the conversation; do not write run results under `evals/` — nothing reads them.
+
+---
+
+## 2. Running a test row from the CLI
+
+Run the workflow with the row's inputs, then read the **raw** output from the debug log:
+
+```bash
+uip api-workflow run <PROJECT>/Workflow.json \
+  --input-arguments '<ROW_INPUTS_JSON>' \
+  --no-auth --output json --log-level debug --log-file <LOG_PATH>
+```
+
+- `Result: "Success"` means the run completed; `Data` is the output **with every key PascalCased** (`grade` → `Grade`, `details.rawScore` → `Details.RawScore`). **Never compare against or copy from `Data`** — a row derived from it passes for you and fails in the panel (this is the `sum` vs `Sum` failure).
+- The raw output is the `response` of the last `Response task evaluated successfully for "<key>": {…}` line in the log file:
+
+  ```bash
+  grep 'Response task evaluated successfully' <LOG_PATH> | tail -1 \
+    | sed 's/^.*successfully for "[^"]*": //' \
+    | python3 -c 'import json,sys; print(json.dumps(json.load(sys.stdin)["response"]))'
+  ```
+
+- Deep-equal that object against the row's `expectedOutput` under the evaluator's `targetOutputKey` (§1 rule 4). A run whose `Result` is not `Success` is an **error** verdict — triage it, don't score it.
+- **Derive `expectedOutput` from `output.schema`** (exact property names and casing) — declare the schema first if the project has none (`init` leaves `output: null`); the Response must emit exactly those keys. Mismatched keys/casing here is the usual reason "the agent said it passed" while every row fails in the panel.
+
+**Batch comparator — score every row in one command.** Do not eyeball outputs and do not hand-roll a comparison per row: write this once to a file **outside the project** (e.g. `/tmp/score-evals.py` — never under `evals/`, the panel reads that folder) and run it after each change. It mirrors the panel: raw output from the debug log, strict deep-equal under the evaluator's `targetOutputKey`, refs matched as file base names.
+
+```python
+#!/usr/bin/env python3
+"""score-evals.py <project-dir>: run every eval row with `uip api-workflow run --no-auth` and
+score it like Studio Web's Evaluations panel (uipath-exact-match, strict deep-equal on the RAW
+output). Exit 0 only when every row passes."""
+import json, re, subprocess, sys, tempfile
+from pathlib import Path
+
+LINE = re.compile(r'Response task evaluated successfully for "[^"]*": (\{.*\})\s*$')
+
+def run(wf, inputs):
+    log = tempfile.NamedTemporaryFile(suffix=".log", delete=False).name
+    p = subprocess.run(["uip", "api-workflow", "run", str(wf), "--input-arguments", json.dumps(inputs),
+                        "--no-auth", "--output", "json", "--log-level", "debug", "--log-file", log],
+                       capture_output=True, text=True, timeout=120)
+    try:
+        env = json.loads(p.stdout)
+    except json.JSONDecodeError:
+        return None, f"non-JSON CLI output: {p.stdout[:200]}"
+    if env.get("Result") != "Success":
+        return None, f"run failed: {env.get('Message')}"
+    raw = None
+    for line in Path(log).read_text(errors="replace").splitlines():
+        m = LINE.search(line)
+        if m:
+            raw = json.loads(m.group(1)).get("response")
+    return (raw if isinstance(raw, dict) else {"result": raw}), None
+
+def eq(a, e):  # lodash isEqual for JSON: bool != number, key order ignored, shapes must match
+    if isinstance(a, bool) or isinstance(e, bool):
+        return isinstance(a, bool) and isinstance(e, bool) and a == e
+    if isinstance(a, dict) and isinstance(e, dict):
+        return a.keys() == e.keys() and all(eq(a[k], e[k]) for k in a)
+    if isinstance(a, list) and isinstance(e, list):
+        return len(a) == len(e) and all(eq(x, y) for x, y in zip(a, e))
+    if isinstance(a, (int, float)) and isinstance(e, (int, float)):
+        return a == e
+    return type(a) is type(e) and a == e
+
+def at(v, path):
+    for seg in [s for s in path.split(".") if s]:
+        if not isinstance(v, dict) or seg not in v:
+            return KeyError
+        v = v[seg]
+    return v
+
+def match(actual, expected, target):
+    if isinstance(target, list):
+        return bool(target) and all(match(actual, expected, t) for t in target)
+    if isinstance(target, str) and target not in ("", "*"):
+        a, e = at(actual, target), at(expected, target)
+        return a is not KeyError and e is not KeyError and eq(a, e)
+    return eq(actual, expected)
+
+project = Path(sys.argv[1] if len(sys.argv) > 1 else ".")
+evaluators = {p.stem: json.loads(p.read_text()) for p in project.glob("evals/*/evaluators/*.json")}
+ok_all, n = True, 0
+for set_path in sorted(project.glob("evals/*/eval-sets/*.json")):
+    es = json.loads(set_path.read_text())
+    for row in es.get("evaluations", []):
+        actual, err = run(project / "Workflow.json", row.get("inputs") or {})
+        for ref in es.get("evaluatorRefs", []):
+            n += 1
+            ev, crit = evaluators.get(ref), (row.get("evaluationCriterias") or {}).get(ref)
+            label = f"{set_path.name} :: {row.get('name') or row.get('id')} ({ref})"
+            if ev is None or ev.get("evaluatorTypeId") != "uipath-exact-match":
+                verdict, detail = "ERROR", f"evaluator {ref!r} missing or not uipath-exact-match (refs are file base names)"
+            elif not isinstance(crit, dict) or "expectedOutput" not in crit:
+                verdict, detail = "ERROR", f"no evaluationCriterias[{ref!r}].expectedOutput"
+            elif err:
+                verdict, detail = "ERROR", err
+            else:
+                exp = crit["expectedOutput"]
+                exp = json.loads(exp) if isinstance(exp, str) else exp
+                target = (ev.get("evaluatorConfig") or {}).get("targetOutputKey", "*")
+                verdict = "PASS" if match(actual, exp, target) else "FAIL"
+                detail = f"actual={json.dumps(actual)} expected={json.dumps(exp)}"
+            ok_all &= verdict == "PASS"
+            print(f"[{verdict:5}] {label} inputs={json.dumps(row.get('inputs'))} {detail}")
+sys.exit(0 if n and ok_all else 1)
+```
+
+Run it as the whole iteration: `python3 /tmp/score-evals.py <PROJECT>` — one tool call, every row, panel-equivalent verdicts.
+- **Inside Studio Web** (no local CLI): rows run through the host instead — ask the user to press **Run** in the Evaluations panel (its verdicts are authoritative), or, with explicit consent (rule 21), invoke `RunProject` once per row with that row's `inputs`; the host result is the raw output. Derive `expectedOutput` from it or from `output.schema`, exactly as above.
+- `--no-auth` is fine for control-flow-only workflows and `Http` activities using `connectionId: "ImplicitConnection"`. **IntSvc (vendor connector) activities need auth** and have real side effects (emails sent, tickets created) — rules 20–21 in SKILL.md apply: never run autonomously, never with auth without an explicit "yes".
+
+---
+
+## 3. The test-until-green loop (interactive protocol)
+
+This is SKILL.md **rule 22**, and it applies **only to projects that have an `evals/` folder** — its absence means the Evaluations feature is not enabled for the project, so steps 2–5 are skipped and the workflow is authored normally. Where it applies it is test-driven development: the questions come before any authoring, the eval set is written **before** the workflow, and the workflow is then authored to make the rows pass. The turn **ends** at step 3 — the workflow is not written or edited, and no eval file is created, until the user has answered. Ask the questions as written, one numbered list, never a vague "how do you want to verify it?". With `evals/` present, skip steps 2–3 only when the user already answered or explicitly asked not to be prompted ("don't ask for confirmation"); then keep an existing eval set as-is and add tests only if they were requested. "Don't ask" waives the questions, not the run consent (SKILL.md rule 21): run the rows only when the request itself asks for a run or a loop ("run the evaluations", "fix it until every case passes"); otherwise author once and hand over the command to run them.
+
+1. **Look for the `evals/` folder** (Phase 0 discovery) — `<project>/evals/`, a sibling of `Workflow.json` inside the project directory; list that directory, not the workspace or solution root. **Absent → stop here:** the feature is off for this project; no test or loop-mode question, no folder creation — author normally. Present → read `evals/<SCOPE>/eval-sets/*.json` and `evals/<SCOPE>/evaluators/*.json` (§1) and note the row count and what the rows expect.
+
+2. **Ask about the tests:**
+   - **Eval set has rows** → *"I found an existing eval set with N test case(s) [one line each: inputs → expectedOutput]. Should anything change — add, edit or remove cases — or use them as-is?"* Apply requested changes, else keep as-is.
+   - **Eval set is empty** (or the folder holds only the seeded evaluator) → *"There are no test cases yet — want me to add some? I'd suggest: [2–3 proposed `(inputs → expectedOutput)` cases derived from the request]."* If yes, add the rows (and the evaluator if missing) in the §1 shapes (raw output keys — §2).
+
+3. **Ask about loop mode — in the same turn, right after question 2:**
+   > "Do you want me to work in **loop mode** — run the tests and re-try (fix the workflow, re-run) until every case passes? Or author once and you verify manually?"
+
+   Then **end the turn**. Ask on the first authoring prompt, create OR edit; the workflow need not exist yet. If the user declines, author normally and don't re-ask every turn; a later "test this" / "run until it passes" re-enters here. Before the first run, make sure the workflow lives in an `init`-scaffolded project (rules 19–19a).
+
+4. **Author tests-first, then run the loop** once the user has answered. Order matters because `uip api-workflow init` scaffolds `input: null` / `output: null` — there is nothing to derive row keys from until you write it:
+   1. **Declare `input.schema` and `output.schema` in `Workflow.json`** — the property names and their exact casing. This is the contract both the rows and the Response follow (`grade`, not `Grade`).
+   2. **Write/update the eval set** (§1), deriving every `inputs` key and `expectedOutput` key from those schemas.
+   3. **Author the workflow** so the Response emits exactly the `output.schema` keys.
+   4. **Run** — in loop mode, which is also the consent for `--no-auth` runs (connector/authed runs still need their own "yes", §2) — iterate:
+   - **One iteration = one command.** Run and score every row in a single bash invocation with the comparator in §2 (`python3 score-evals.py <PROJECT>`); never one tool call per row plus one to read the output — a 5-row × 3-iteration loop is ~3 calls that way instead of ~30. Runs are cheap (≈1 s per row); tool calls are what cost.
+   - For each row the comparator prints `PASS` / `FAIL` / `ERROR` with the **raw** output and the expectation, scored by **the evaluator the project declares** (§1). Never substitute your own "the number looks right" judgment for its verdict.
+   - **All pass** → stop and report the green result (rows, inputs, actual outputs).
+   - **Any fail/error** → **first check for a key / casing / shape mismatch** between the raw output and `expectedOutput` (`sum` vs `Sum`, a missing wrapper object, a string where a number is expected). Decide which side is wrong: the workflow's output key must match its `output.schema` — fix the workflow; a row that contradicts the requested behavior — fix the row (§4). Otherwise triage the run (Structure > Expression > Activity Config > Logic — SKILL.md Core Principle 4), fix the workflow, re-run.
+   - **Report progress each iteration** — e.g. "iteration 2: 3/4 rows pass; fixing row 'unpaid invoice' (expected status `unpaid`, got `paid`)".
+   - **Stop conditions:** all green; OR no progress after a few iterations (cap it — see Infinite Loop Prevention in SKILL.md); OR the user interjects. Always end with a per-row summary of the final state.
+   - **Stay in the main thread.** The loop is seconds of compute; a background subagent only adds turns and hides progress. If a new user message changes the workflow or the intent, incorporate the change before the next iteration — never keep scoring against a workflow the user has just asked you to change.
+
+5. **Future edits — behavior changes can break the tests.** When a later request changes what the workflow *does* (a threshold, rounding, branch order, a new default) and an eval set exists, ask **before editing**: *"This change would make these expectations stale: [rows]. Update them to the new behavior, or keep them and flag the mismatch?"* Then edit, re-run the rows, and report which rows you updated and why (§4). A pure refactor or a schema-only rename that leaves behavior unchanged needs no question — just re-run the rows afterwards.
+
+---
+
+## 4. Notes & gotchas
+
+- **Consent is the loop's gate.** "Yes, loop until green" authorizes repeated `--no-auth` runs. For workflows with side effects (IntSvc/vendor, authed HTTP), say so and get explicit consent before looping — each iteration re-triggers the side effect.
+- **Keep the dataset in sync — with the schema AND the behavior.** Two distinct triggers:
+  - **Schema change** — renamed/added/removed input or output arguments: the rows' `inputs` / `expectedOutput` shapes may no longer fit. Offer to update them.
+  - **Logic change (easy to miss)** — a behavior change with an **unchanged** schema can still make existing `expectedOutput`s wrong: flip a threshold `>5` → `>=5`, change rounding, reorder branches, and a row that expected `pass` now correctly yields `fail`. **After any edit that changes behavior, re-derive the expected outputs — never "fix" the workflow to satisfy a now-stale test, and never silently rewrite a row the user did not ask to change.** Decide per row whether the expectation or the workflow is the source of truth, and say which rows you updated and why.
+- **The project's evaluator is authoritative.** Read `evals/<SCOPE>/evaluators/*.json` and score by its `evaluatorTypeId`; today that is always `uipath-exact-match` (strict deep-equal).
+- **"The agent said it passed" ≠ the panel passes.** An LLM eyeballing a run judges *meaning* (2+3=5 → looks right) and forgives key casing and shape; the evaluator does a byte-exact deep-equal and does not — and the CLI's PascalCased `Data` hides exactly that class of mismatch. When they disagree, the evaluator is right: fix the key/casing/shape.
+- **Same files, two front-ends.** The user may author or run these rows in Studio Web's Evaluations panel between your turns; your CLI runs and their UI runs share `evals/…`. Re-read the files before each loop iteration rather than trusting an in-memory copy.

package/skills/uipath-api-workflow/references/troubleshooting.md

@@ -559,19 +559,67 @@ These are issues that surface only when a workflow is opened or run in **StudioW
   - Use optional chaining: `$context?.outputs?.Javascript_1?.items`
   - Ensure object literals have unique keys
 
+### `"Script execution failed timed out"`
+
+- **Symptom:** A JavaScript activity that works on small inputs fails on larger ones with `Execution error: Script execution failed timed out: Script execution failed timed out`. The workflow validates; only the run fails.
+- **Cause:** The activity exceeded the runner's per-script budget. In the executor the CLI actually ships — `@uipath/api-workflow-executor` **12.10.2**, exact-pinned by `packages/api-workflow-tool/package.json` on `uipcli` main — the budget is a **flat 10 seconds**, passed as a bare literal:
+
+  ```js
+  // dist/handlers/script-task-handler.js
+  await this.expressionHandler.evaluateScript(code, taskName, 10000);
+  ```
+
+  Measured against that build: an 8-second script passes, a 12-second script fails.
+
+  **Check the pinned executor before trusting any number here** — it is a literal, not a documented contract, and it has already changed: executor 12.23.2 (newer, NOT pinned by the CLI as of 2026-08-20) replaces it with `SCRIPT_TIMEOUT_MS = 10000` plus a second budget of ~100s for scripts whose source contains `$helpers`, selected by a literal `code.includes('$helpers')` substring test. If your CLI pins 12.23.x or later, the 10s figure applies only to scripts with no `$helpers` call.
+
+  All of the above are **local** figures. The **cloud** cap is different and is documented: *"JavaScript code execution has a timeout of 30 seconds"* — [Script activity, Known limitations](https://docs.uipath.com/studio-web/automation-cloud/latest/user-guide/script).
+
+  So the local runner is **3x stricter than cloud**, and each side misleads on its own:
+  - A local `timed out` failure does **not** mean the workflow fails in cloud — anything under 30s runs there.
+  - Passing locally does **not** prove you clear the cloud cap. Local runs use small fixtures; a script that takes 3s over 10 test rows can exceed 30s over 10,000 production rows.
+
+- **Fix:**
+  - Move bulk work out of one script: page the data and process a batch per loop iteration, so each script invocation is short.
+  - Split one long script into several JavaScript activities chained by `export`.
+  - Never busy-wait inside a script (`while (Date.now() < end) {}`) — use a `Wait` activity, which is not charged against the script budget.
+  - If the work genuinely cannot be split, it does not belong in an API workflow; a connector call or a Coded Function is the right home.
+
 ### Failed cloud run after publish (job faulted in Orchestrator)
 
 - **Symptom:** The workflow passed `validate` and `run --no-auth` locally, packed, published, and deployed — but a triggered cloud run faults. Local re-runs still pass.
 - **Cause:** Faults that only surface in cloud — real vendor responses, connection auth/token state, trigger payload shape, tenant/folder scoping — none of which the local runtime exercises.
 - **Fix:** Diagnose from the deployed job, not the local file:
   ```bash
-  uip or jobs get <jobId> --output json                  # status + fault summary
-  uip or jobs logs <jobId> --output json                 # execution logs for the run
-  uip traces spans get --job-key <jobKey> --output json  # span-level execution trace (also accepts a <trace-id> positional)
+  uip or jobs get <jobId> --output json   # THE diagnostic: Data.State + Data.Info
   ```
-  (Folder scoping differs: `uip or jobs list` accepts `--folder-path`/`--folder-key`/`--all-folders`; `uip or triggers list` accepts only `--folder-path`/`--folder-key`; `uip or jobs start <process-key>` infers the folder. `uip or jobs traces` is Agent-type-process-only; use `traces spans get` for API-workflow jobs.)
+  `Data.State` reads `Faulted` and `Data.Info` carries the runtime message — for an API workflow that is usually the whole answer.
+
+  **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. Never read "completed" here as success. |
+  | `uip traces spans get --job-key <jobKey>` | Returned `"Error retrieving trace ID for job"` on every API-workflow job probed. The CLI emits that same message for any trace-ID lookup failure (a malformed GUID included), so read it as "no trace resolved for this job", not as proof the surface is absent. Either way it yields no fault detail — use `jobs get`. |
+
+  **Diagnose before you tear down:** after uninstalling the deployment, `uip or jobs get` on its jobs 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, read the fault before you uninstall.
+
+  (Folder scoping differs: `uip or jobs list` accepts `--folder-path`/`--folder-key`/`--all-folders`; `uip or triggers list` accepts only `--folder-path`/`--folder-key`; `uip or jobs start <process-key>` infers the folder.)
   Map the surfaced error back to a fix with the category order below (Structure > Expression > Activity Config > Logic). If the fault is a 401 / `ConnectionNotEnabled`, `uip is connections ping <uuid>` the bound connection first. Full operate + diagnose command map: [operating-published-workflows.md](operating-published-workflows.md). For deep, multi-signal root-cause (what changed, cross-run comparison, incident correlation), hand off to **uipath-troubleshoot**.
 
+### Outbound call to a third-party API works locally, times out or is refused in cloud
+
+- **Symptom:** An `HTTP Request` or connector call to a customer/vendor endpoint succeeds when the workflow is executed on your own machine and fails only from the deployed copy — connection refused, or a hang ending in a timeout. Same URL, same payload.
+- **Cause:** Local runs egress from your machine's IP; cloud runs egress from UiPath infrastructure. If the target sits behind an IP allowlist, the cloud source addresses have to be on it — and **which** addresses depends on how the call is made.
+
+  Per [About API workflows](https://docs.uipath.com/studio-web/automation-cloud/latest/user-guide/about-api-workflows): *"Which outbound path applies depends on how the external call is made"* — an HTTP Request with manual authentication egresses via **serverless robots**, a connector-based call via **Integration Service** — and allowlisting is required *"only when API workflows communicate externally"*, covering both **Serverless static IPs** and **Integration Service IPs**.
+
+  The two are not interchangeable, and the reason is structural. Per [Configuring the firewall for Automation Cloud](https://docs.uipath.com/automation-cloud/automation-cloud/latest/admin-guide/configuring-the-firewall-for-cloud), most services now share one **unified** set of outbound ranges per region — *"a single set of IP ranges covers Automation Cloud Portal, Orchestrator, Integration Service, Apps, Automation Ops, Test Manager, AI Trust Layer, and Notification Service simultaneously"* — but four services are carved out: *"Document Understanding, Insights, IXP, and Automation Cloud Robots - Serverless"* keep their own service-specific ranges.
+
+  So **Integration Service sits in the unified regional set and serverless robots do not.** A customer who allowlisted the unified ranges has covered your connector activities and *not* your manual-auth HTTP calls. Always read the current ranges off those pages before asking anyone to change firewall rules — they are per-region and they change.
+- **Fix:** Establish which path the call takes (connector activity → Integration Service; `UiPath.Http` with *connector-based* authentication → also Integration Service; `UiPath.Http` with *manual* authentication → serverless robot), then have the endpoint owner allowlist that service's published outbound ranges. This is a network-configuration fix, not a workflow fix — no edit to `Workflow.json` will resolve it, so stop editing and escalate once the symptom matches.
+- **Distinguishing it from an auth fault:** a 401/403 with a response body is an auth or connection problem (`uip is connections ping <uuid>` first). A refused connection or a timeout with no HTTP response at all points at the network path.
+
 ---
 
 ## Packaging Errors
@@ -628,6 +676,26 @@ These are issues that surface only when a workflow is opened or run in **StudioW
 - **Cause:** Skipped re-running the validators after applying a fix
 - **Fix:** ALWAYS re-run after every edit. Two validators: `uip api-workflow validate <Workflow.json>` (offline static — schema + semantic checks, autonomous) then `uip api-workflow run --no-auth` (runtime — catches expression/connection errors static analysis can't). See SKILL.md rules 20–21.
 
+### `Unknown activityType '<Name>'`
+
+- **Symptom:** `validate` rejects an activity — `Unknown activityType 'X'. Valid types: ...`
+- **Cause:** The authorable set is closed and mirrors the Studio Web palette. It is also versioned: `CustomLog` was added 2026-08-11, so older CLIs list 13 types and newer ones 14. **Take the list from the error message — never memorise one.**
+- **Fix:** Stay inside the list. Two task types the executor runs but `validate` refuses — do not author them:
+
+  | Instead of | Use |
+  |---|---|
+  | `raise` | `throw` inside a JavaScript activity, or `Response` with `markJobAsFailed: true` |
+  | `while` (pre-condition loop) | `DoWhile` + an `If` whose `#Else` exits via `Break` |
+
+  Both execute under `run` (verified on executor 12.10.2), so **a passing local run is not proof a workflow can ship.** `validate` is the gate.
+- **Error-count tell:** a small count naming the activityType — one error per offending task — → unknown **name**, caught by the allowlist. A large avalanche starting `Missing required property 'call'` → the schema could not match the task **shape**, which has two causes and you must check both:
+  1. **Unknown task key** — the schema models no such task (e.g. `raise`). Nothing about the fields will help.
+  2. **An unexpected field on a KNOWN task** — one stray key makes the whole task unmatchable, and the error text still says `Missing required property 'call'`. `set` on a `Break` is the documented instance: it produced **7797 errors** in this skill's own `nested-control-flow-example.json`, and deleting that one key made it Valid.
+
+  So read the avalanche as "the schema cannot match this task", not "the task key is wrong". Diff the task against the shape in [task-types.md](task-types.md) field by field before concluding the type is unsupported.
+- **Logging:** `console.log` / `console.warn` inside a JavaScript activity are captured and emitted as `[Script <TaskName>]: ...`. Whether they reach Orchestrator job logs in cloud is unverified — a probe showed the Orchestrator job-log surface carrying only lifecycle lines — so put anything you must read after a run in the `Response`. `CustomLog` is on the list but no executor ships a handler for it; do not author one yet.
+- **Do not** mislabel `metadata.activityType` to slip a type past the check — the validator cross-checks the label against the task's own keys (`has activityType 'DoWhile' but must contain 'for' with 'doWhile'`).
+
 ### Fixing in wrong order
 - **Symptom:** Fixing one error creates more errors; thrashing
 - **Cause:** Fixing logic errors before structure errors; lower-priority fixes destabilize higher-priority structure
@@ -638,6 +706,58 @@ These are issues that surface only when a workflow is opened or run in **StudioW
 - **Cause:** Edit's `old_string` did not exactly match file content (whitespace, escaping)
 - **Fix:** Always read the file before editing. After edit, re-run the workflow.
 
+## File & Base64 Pitfalls
+
+### Run refused: "This workflow uses the file helpers … cannot run with --no-auth"
+- **Symptom:** the local run in no-auth mode exits 1 before the engine starts, naming File to Base64 / Base64 to File
+- **Cause:** `$helpers.file.*` reads and writes Orchestrator blob storage; there is no local file store
+- **Fix:** run signed in (sign in first, drop `--no-auth`) — still only on the user's explicit "yes" (rule 21). Same for `--input-file` / `--output-dir`.
+
+### `$helpers.fileToBase64 is not a function` / validate: "does not call $helpers.file.fileToBase64("
+- **Symptom:** `validate` reports one error at `…/run/script/code`; or a signed-in run fails inside the task
+- **Cause:** the helper was written without the `.file.` namespace (or with another name). The activity is recognised by that exact call
+- **Fix:** `return { output: await $helpers.file.fileToBase64(<ref>) }` / `$helpers.file.base64ToFile({ base64: … })`; keep `metadata.activityType` `FileToBase64` / `Base64ToFile`
+
+### File to Base64 / Base64 to File script lost code after a Studio Web save (validate warned "rebuilds the script … and drops the rest", or did not warn at all)
+- **Symptom:** after a designer roundtrip the task's `run.script.code` is back to the bare `return { output: await $helpers.file.*(…) }` — a preceding `const`, a trailing statement, a second argument (`fileToBase64(ref, { extra: 1 })`) or an extra option key is gone; downstream logic that relied on it now fails or the wrong reference is converted
+- **Cause:** Studio Web parses only the `$helpers.file.*` call and rebuilds the script from the property panel on save. `validate` warns about extra statements but passes an extra argument / option key as `Valid`
+- **Fix:** keep the script to the single `return` expression with exactly one argument (see [files-and-base64.md §2](files-and-base64.md#2-the-two-activities)); move pre-processing into a JavaScript activity before the conversion and pass its output as the argument
+
+### File to Base64 output used as a string (`.length`, `+`, `JSON.stringify` shows an object)
+- **Symptom:** downstream expression gets `[object Object]`, `undefined`, or an `{ ID, FullName, MimeType }` object where base64 text was expected
+- **Cause:** the activity returns a base64 **file reference**, not the base64 string — bytes never enter `$context`
+- **Fix:** inline the content where it is sent: `"${{ content: $context.outputs.FileToBase64_1.output.serializeData() }}"` in the HTTP body / Response
+
+### `{ "__uipathFileRead": { "ref": … } }` shows up in a variable or the output
+- **Symptom:** a marker object instead of file content
+- **Cause:** `serializeData()` was stored in a variable / returned from a script instead of being called inline in a body or Response field
+- **Fix:** call it only inside the HTTP body or `response` expression
+
+### Decoded file has no extension (`hello` instead of `hello.txt`)
+- **Symptom:** Base64 to File returns `FullName: "hello"`, `MimeType: application/octet-stream`
+- **Cause:** for a *reference* input the engine strips `.base64` and sniffs the MIME type from the bytes; plain text has no signature, and `fileName` / `mimeType` are ignored for references
+- **Fix:** acceptable for opaque payloads; when the name matters, decode a raw base64 **string** with `fileName` / `mimeType` (e.g. `{ base64: $context.variables.payload, fileName: 'notes.txt', mimeType: 'text/plain' }`)
+
+### `The provided value is not a valid base64 string: base64ToFile`
+- **Symptom:** Base64 to File fails on a string input. The suffix is always the literal helper name `base64ToFile` — it does not name the failing task, so with several Base64 to File tasks locate the culprit by the failing task in the run output, not by the message
+- **Cause:** URL-safe alphabet (`-` / `_`), non-base64 characters, bad padding, or an empty string. A `data:…;base64,` prefix and whitespace are NOT the problem — the engine strips both before decoding
+- **Fix:** convert URL-safe base64 to the standard alphabet (`-`→`+`, `_`→`/`) in a JavaScript activity; make sure the field really holds the payload and is not empty
+
+### `Raw bytes cannot be embedded in JSON` / `A bare file reference cannot be embedded in a nested field`
+- **Symptom:** an HTTP Request fails at send time with one of these messages
+- **Cause:** a JSON body field holds `serializeData()` of a *binary* reference (e.g. `$workflow.input.document.serializeData()`), or a bare reference object. Only a base64 reference's marker can be inlined in a nested field
+- **Fix:** run File to Base64 first and inline `$context.outputs.FileToBase64_1.output.serializeData()`; or, to send the raw bytes, make the bare reference the *whole* request body
+
+### File too large
+- **Symptom:** the helper fails with a size error
+- **Cause:** the in-memory conversion path is capped at 50 MB — it applies only to raw base64 strings and to references with a small declared `Metadata.Size`; references above 1 MB or with no declared size stream instead, with no size cap
+- **Fix:** pass the file as a reference (streamed) rather than as an inline string; keep inline strings under the cap
+
+### Upload / download 403 or "folder" errors with `--input-file` / `--output-dir`
+- **Symptom:** `Failed to upload input file … 403` or an Attachments API folder error
+- **Cause:** the tenant's Attachments API requires a folder context
+- **Fix:** pass `--folder-key <guid>` (the Orchestrator folder's key, visible in the folder's settings or via the platform CLI's folder listing)
+
 ---
 
 ## Debugging Strategy

package/skills/uipath-coded-apps/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uipath-coded-apps
-description: "UiPath Coded Apps — scaffold, build, run, and deploy Coded Web Apps and Coded Action Apps: React/TypeScript apps that call UiPath Cloud APIs via the `@uipath/uipath-typescript` SDK and ship to Automation Cloud (push/pull to Studio Web, pack, publish, deploy, OAuth-PKCE). Also generates live analytics & governance dashboards from a plain-language request, wired to tenant data via the Insights real-time API, with edit and deploy flows. For RPA→uipath-rpa, Python agents→uipath-agents, Maestro flows→uipath-maestro-flow, solution packaging→uipath-solution."
+description: "UiPath Coded Apps — scaffold, build, run, and deploy Coded Web Apps and Coded Action Apps: React/TypeScript apps that call UiPath Cloud APIs via the `@uipath/uipath-typescript` SDK and ship to Automation Cloud (push/pull to Studio Web, pack, publish, deploy, OAuth-PKCE). Also generates live analytics & governance dashboards from a plain-language request, wired to tenant data via the Insights real-time API, with edit and deploy flows. For RPA→uipath-rpa, Python agents→uipath-agents, Maestro flows→uipath-maestro-flow, solution packaging→uipath-solution, JS/TS function backends (`defineFunction`, `uip function serve`)→uipath-functions."
 when_to_use: "User wants to scaffold, build, push/pull, pack, publish, or deploy a Coded Web App or Coded Action App, or use the `@uipath/uipath-typescript` SDK inside one. Also dashboard requests: 'build me a dashboard', 'show agent health / error rate / KPIs / governance violations', 'generate an analytics or observability dashboard', edit an existing one (add/remove/change a widget, change time range, deploy), or fix/diagnose a dashboard that won't build (a metric that fails to compile, a bad SDK call, a broken widget). For RPA→uipath-rpa; Python agents→uipath-agents; Maestro flows→uipath-maestro-flow."
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, Task
 ---
@@ -21,6 +21,8 @@ Build, debug, and deploy UiPath Coded Web Applications and Coded Action Apps usi
 - User wants to **generate an agent-monitoring / analytics dashboard** from a natural-language description — e.g. "show agent health, error rates, invocation volume, latency, active agents, KPIs, governance metrics, or consumption trends"
 - User says "build/create/generate a dashboard", describes metrics to visualize, or asks for an agent observability, operations, or cost view
 
+For the app's **JS/TS function backend** — authoring the `defineFunction` endpoint the app calls, tokens, CORS, the local two-server dev loop → `uipath-functions`.
+
 ## App Types
 
 | Type | Description | Key Difference |
@@ -178,7 +180,7 @@ To change any of these values, edit `uipath.json`.
 2. **Build** — `npm run build`. Verify `ls dist/`.
 3. **Pack** — `uip codedapp pack dist -n <name> --version <version>`. Produces `.uipath/<name>.<version>.nupkg`. Bump version if previously published.
 4. **Publish** — `uip codedapp publish` (add `-t Action` for action apps). Verify `cat .uipath/app.config.json`.
-5. **Deploy** — `uip codedapp deploy -n <name> --folder-key <GUID>`. Resolve the GUID from the chosen folder: a personal workspace (`Type == "Personal"`), a named existing folder, or a freshly `uip or folders create`d one — via `uip or folders list --output json`. Dashboards additionally choose a **deploy mode** (standalone / governance-pinned / governance) that sets `--tags`; see [dashboards deploy impl](references/dashboards/plugins/deploy/impl.md). Never let the command go interactive. Share the app URL with the user.
+5. **Deploy** — `uip codedapp deploy -n <name> --folder-key <GUID>`. Resolve the GUID from the chosen folder: a personal workspace (`Type == "Personal"`), a named existing folder, or a freshly `uip or folders create`d one — via `uip or folders list --output json`. Dashboards additionally choose a **deploy mode** (standalone / governance-pinned / governance) that sets `--tags`; see [dashboards deploy impl](references/dashboards/plugins/deploy/impl.md). Never let the command go interactive. Share the app URL with the user. **Deploy is done when the CLI reports success — do not poll or `curl` the app URL to confirm it.** Activation lags the deploy by minutes, so a fresh URL returning 404/503 is expected and proves nothing; waiting on it only burns time.
 
 ## SDK Module Imports
 

package/skills/uipath-coded-apps/assets/scripts/dashboards/build-dashboard.mjs

@@ -364,7 +364,7 @@ export function assertScaffoldExtracted(projectPath) {
     `Starter kit not extracted into: ${projectPath}`,
     `Extract it first with tar (built into Windows 10+, macOS, Linux).`,
     `Feed the archive on stdin (-f -) so GNU tar doesn't misread the C:\\ drive colon as a remote host:`,
-    `  mkdir -p "${projectPath}" && tar -xz -C "${projectPath}" -f - < "${FIXTURE_ARCHIVE_PATH}"`,
+    `  mkdir -p "${projectPath}" && tar --no-same-owner --no-same-permissions -xz -C "${projectPath}" -f - < "${FIXTURE_ARCHIVE_PATH}"`,
     `Then re-run the build.`,
   ].join('\n'))
 }

package/skills/uipath-coded-apps/references/dashboards/CAPABILITY.md

@@ -82,11 +82,21 @@ uip login status --output json
 Derive the routing name from the user's request now (e.g. `"agent health dashboard"` → `"agent-health-x7k2"`). The project lands at `<cwd>/<ROUTING_NAME>`. Pre-warm = **extract the starter kit there, then install deps** — both in the background. Extraction uses the OS `tar` (built into Windows 10+, macOS, Linux — identical on every platform, no hand-rolled code), feeding the archive on **stdin** (`-f -`) so GNU tar doesn't misread the `C:\…` drive colon as a remote host (see `plugins/build/impl.md § The starter-kit archive`). One background call (chain with `&&`):
 
 ```bash
-mkdir -p "<ROUTING_NAME>" && tar -xz -C "<ROUTING_NAME>" -f - < "<SKILL_BASE_DIR>/assets/fixtures/governance-dashboard-starter-kit.tar.gz" && node "<SKILL_BASE_DIR>/assets/scripts/dashboards/build-dashboard.mjs" --prewarm "<ROUTING_NAME>"
+mkdir -p "<ROUTING_NAME>" && tar --no-same-owner --no-same-permissions -xz -C "<ROUTING_NAME>" -f - < "<SKILL_BASE_DIR>/assets/fixtures/governance-dashboard-starter-kit.tar.gz" && node "<SKILL_BASE_DIR>/assets/scripts/dashboards/build-dashboard.mjs" --prewarm "<ROUTING_NAME>"
 ```
 
 The extract is fast; `--prewarm` then runs `npm ci` (the slow part) so it overlaps plan approval. ⚠️ `run_in_background: true` is a tool call parameter, not a shell flag. Without it, the call blocks before the plan appears.
 
+**If that command exits non-zero — repair `<ROUTING_NAME>` in place. Never scaffold into a second folder.**
+
+A partial extract (`Cannot mkdir`, `Cannot open: File exists`, `Permission denied`) leaves a half-populated project. Re-run the exact same command once — `tar` overwrites and the scaffold is idempotent, so a transient failure clears. If it fails again, delete and retry once:
+
+```bash
+rm -rf "<ROUTING_NAME>" && mkdir -p "<ROUTING_NAME>" && tar --no-same-owner --no-same-permissions -xz -C "<ROUTING_NAME>" -f - < "<SKILL_BASE_DIR>/assets/fixtures/governance-dashboard-starter-kit.tar.gz" && node "<SKILL_BASE_DIR>/assets/scripts/dashboards/build-dashboard.mjs" --prewarm "<ROUTING_NAME>"
+```
+
+If `rm -rf` itself is denied, the sandbox — not the kit — is at fault: **stop and report it.** Do NOT pick a new `<ROUTING_NAME>` to route around the error. An abandoned scaffold sitting beside the real one is indistinguishable from the real one to anything that later has to locate the project, and every downstream step then has a coin flip in it.
+
 > **What the user should see:** Only the plan text. Nothing else — not file reads, not login output, not pre-warm status, not bash results, and no question popup. If there is ANY output before the plan, or any tool call in the plan response, that is a bug.
 
 **After all reads:** output the plan as **pure text** and stop — zero tool calls in the plan response. The user replies with feedback or confirmation; setup questions (OAuth client ID, via the structured-choice tool) come only AFTER the plan is approved, and only for details the confirmation didn't already provide. See `plugins/build/impl.md` Phases 2–3.