@uipath/skills 1.198.0-preview.21 → 1.199.0-preview.106

package/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md

@@ -16,6 +16,11 @@ Two types exist:
 
 This restriction is enforced as [../../critical-rules/conversational-critical-rules.md](../../critical-rules/conversational-critical-rules.md) Critical Rule 1.
 
+**Required completion gate:** after writing a conversational custom Tool
+guardrail, run `uip agent refresh "<AGENT_NAME>" --output json`, then execute
+`uip agent validate "<AGENT_NAME>" --output json`. Do not report the guardrail
+task complete before the validation command has been attempted.
+
 ## Guardrail Schema (Base Fields)
 
 Every guardrail object in the `guardrails` array shares these base fields:
@@ -241,6 +246,11 @@ Prefer `type: 3` (UserEmail) when adding manually — it requires no GUID or ass
 
 #### Adding an escalation guardrail — step-by-step
 
+**Scaffolding gate (MANDATORY):** when the request includes creating a solution
+or agent, run both `uip solution init` and `uip agent init` before app discovery.
+An incompatible or missing escalation app rejects only the guardrail; it does
+not cancel the requested local solution and agent scaffolding.
+
 **Step 0 — Discover available validators (MANDATORY — do not skip even when validator type is already known):**
 
 ```bash
@@ -282,8 +292,27 @@ Example entry:
 
 > **Important:** Do NOT use `--kind Process` with `Type: "webApp"` to find Action Center apps. Those entries are the code-behind processes — their `Key` values are process release GUIDs, not app deployment IDs. Using them as `app.id` will cause runtime resolution failures.
 
+**Step 1 completion gate — both branches MUST run `resources get`:**
+
+- Exact app row found: immediately run
+  `uip solution resources get "<Key from the row>" --output json`.
+- No exact app row/key found: immediately run
+  `uip solution resources get "<requested app name>" --output json` once and
+  treat its failure as `GET_ERROR`.
+
+Do not edit files, refresh, validate, or respond to the user between
+`resources list` and this required `resources get` attempt. A missing catalog
+row is not a completed schema check and is never permission to skip the
+command.
+
 **Step 2 — Verify the app exposes the guardrail action-schema contract** (do this **before** writing the guardrail JSON — an incompatible app must be rejected, not authored).
 
+**Required command gate:** execute
+`uip solution resources get "<Key from Step 1>" --output json` for the selected
+app before deciding whether it is compatible. The `resources list` row is not
+an action schema and cannot replace this command. Do not write or reject the
+guardrail until the returned action schema has been checked.
+
 A guardrail escalation app must expose a specific action-schema contract. If verification fails, stop and report to the user: `<APP_NAME> does not have the required action schema configuration for tool guardrails.` (replace `<APP_NAME>` with the app's `Name` from Step 1). Do NOT write the guardrail.
 
 `uip solution resources get` returns the app's action schema in one CLI-native call — no auth handling, no Apps API endpoints. Pipe its output into a verifier that confirms every required argument name. The CLI handles authentication, so Claude never touches the auth file or the token.
@@ -565,7 +594,10 @@ Built-in validators call the UiPath Guardrails API. They have a `validatorType`
 |-------------------|---------|-------------|
 | `"enum-list"` | Array parameters (e.g., `entities`, `harmfulContentEntities`, `ipEntities`) | string[] |
 | `"map-enum"` | Threshold maps (e.g., `entityThresholds`, `harmfulContentEntityThresholds`) | object (keys = entity names, values = numbers) |
-| `"number"` | Scalar numbers (e.g., `threshold` for prompt injection) | number |
+| `"number"` | Scalar numbers (e.g., `threshold`) | number |
+| `"enum"` | Scalar single-choice (e.g., `model` for `llm_as_judge`) | string |
+| `"text"` | Free text (e.g., `guardrailText` for `llm_as_judge`) | string |
+| `"text-list"` | Text arrays (e.g., `positiveExamples`, `negativeExamples` for `llm_as_judge`) | string[] |
 
 ### Validators Quick Reference
 
@@ -578,6 +610,9 @@ Built-in validators call the UiPath Guardrails API. They have a `validatorType`
 | `harmful_content` | Agent, Llm, Tool | **Not usable** (autonomous-only) | Pre + Post | Block, Log, Escalate |
 | `intellectual_property` | Llm, Agent | **Not usable** (autonomous-only) | Post only | Block, Log, Escalate |
 | `user_prompt_attacks` | Llm | **Not usable** (autonomous-only) | Pre only | Block, Log, Escalate |
+| `llm_as_judge` | Agent, Llm, Tool | **Not usable** (autonomous-only) | Pre + Post | Block, Log, Escalate |
+
+> **`llm_as_judge` needs an LLM Gateway model.** Its `model` parameter comes back with an **empty** `Options` list from `uip agent guardrails list` — the valid values live in LLM Gateway, not the catalog. Run `uip agent guardrails llm-as-judge-models --output json` and use a `ModelId` from the result for the `model` parameter (prefer a non-preview model; a small/fast model such as a Haiku / mini class is a sound judge default). If the command returns no models or fails (no LLM Gateway access), tell the user and ask them to configure a model in their LLM Gateway or supply a model ID. Its other parameters are `guardrailText` (`text`, required), `positiveExamples` / `negativeExamples` (`text-list`, optional), and `threshold` (`number`, optional).
 
 Run `uip agent guardrails list --output json` to get the authoritative list. Only use validators where `Status` is `"Available"`. Use the output to populate `validatorType`, `selector.scopes`, and `validatorParameters` fields. **These built-in validators are autonomous-only — do NOT author any of them on a conversational agent (they will not run at any scope). Conversational agents use Custom deterministic `Tool` guardrails only.**
 **How to map `uip agent guardrails list` output to guardrail JSON:**
@@ -1107,4 +1142,3 @@ Confirm the guardrails appear in the validated output without errors. Refresh re
 - [../../critical-rules/critical-rules.md](../../critical-rules/critical-rules.md) — canonical low-code rules and guardrail anti-patterns (discriminators, scope casing, populating `guardrail.policies` on tool resources, UUID reuse)
 - [../../project-lifecycle.md](../../project-lifecycle.md) § `uip agent guardrails list` — CLI reference for validator discovery
 - [../../agent-definition.md](../../agent-definition.md) § Guardrails — root-level placement in `agent.json`
-

package/skills/uipath-agents/references/lowcode/capabilities/process/process.md

@@ -155,7 +155,7 @@ Wrapper changes to `Code: "ResourceConfigurations"` with `Data.resources[]` cont
    - `resources/solution_folder/package/<PackageName>.json` (package declaration)
    - an entry in `userProfile/<userId>/debug_overwrites.json` with real `folderKey`, `folderFullyQualifiedName`, and `folderPath` so Studio Web can resolve the process at runtime. An entry missing `folderFullyQualifiedName` or `folderPath` will cause "Could not find process for tool '<name>'" — refresh from current uipcli populates both correctly.
 
-For in-solution agents already registered with the parent solution — auto-registered by `uip agent init` (when run from inside a solution directory; verify via `Data.SolutionRegistration.Status` = `Registered` / `AlreadyRegistered`) or via the `uip solution project add` fallback — the package + process declarations are pre-existing; refresh resolves the binding against them.
+For in-solution agents already registered with the parent solution — auto-registered by `uip agent init` (when run from inside a solution directory; verify via `Data.SolutionRegistration.Status` = `Registered` / `AlreadyRegistered`) or via the `uip solution projects add` fallback — the package + process declarations are pre-existing; refresh resolves the binding against them.
 
 **Type-to-directory mapping for process declarations:**
 
@@ -222,11 +222,11 @@ When two agent projects in the same solution call each other (parent-tool topolo
 # 2. Add a second agent. When run from inside the solution directory,
 #    `uip agent init` auto-registers the project with the parent `.uipx`
 #    (confirm via `Data.SolutionRegistration.Status` in the response).
-#    `uip solution project add` is the fallback when registration was
+#    `uip solution projects add` is the fallback when registration was
 #    `NotInSolution` / `Skipped` / `Failed` (not for `OptedOut`, which means
 #    `--skip-solution-registration` was passed and the skip was intentional).
 uip agent init "ToolAgent" --output json
-# (fallback) uip solution project add "ToolAgent" --output json
+# (fallback) uip solution projects add "ToolAgent" --output json
 # Either path creates resources/solution_folder/package/ToolAgent.json and
 # resources/solution_folder/process/agent/ToolAgent.json automatically.
 
@@ -244,7 +244,7 @@ uip agent refresh  ToolAgent --output json
 uip agent validate ToolAgent --output json
 ```
 
-UUID cross-references between `SolutionStorage.Projects[].ProjectId`, `package/<ToolAgent>.json.projectKey`, and `process/agent/<ToolAgent>.json.projectKey` are auto-managed by project registration (`uip agent init` auto-registration, or the `uip solution project add` fallback) and `uip agent refresh` — do not hand-edit. See [../../solution-resources.md](../../solution-resources.md) § UUID Cross-References.
+UUID cross-references between `SolutionStorage.Projects[].ProjectId`, `package/<ToolAgent>.json.projectKey`, and `process/agent/<ToolAgent>.json.projectKey` are auto-managed by project registration (`uip agent init` auto-registration, or the `uip solution projects add` fallback) and `uip agent refresh` — do not hand-edit. See [../../solution-resources.md](../../solution-resources.md) § UUID Cross-References.
 
 ## Gotchas
 

package/skills/uipath-agents/references/lowcode/capabilities/process/solution-files.md

@@ -4,7 +4,7 @@ When `uip solution resources refresh` cannot produce solution-level files (offli
 
 It also documents the Releases API + `GetPackageEntryPointsV2` + JWT decoding extraction path — used when `uip solution resources get` is unavailable (older `uip` builds, RCS unreachable, custom deployments). For the standard CLI-driven extraction, see [process.md § Discovery](process.md#discovery).
 
-> **`folders[].fullyQualifiedName` carries the literal `Folder`** (e.g., `"Shared"`, `"Shared/Sales"`) returned by `uip solution resources list` — the same value the agent-level `resource.json` writes into `properties.folderPath` and that `bindings_v2.json` propagates. Templates show `<Folder>` as the placeholder; examples show `"Shared"` as a concrete value. Auto-generated declarations for **solution-internal projects** (created when the agent project is registered with the solution — by `uip agent init` auto-registration or by the `uip solution project add` fallback) keep `"solution_folder"` instead — they have no fixed Orchestrator folder until deploy. See [../../critical-rules/critical-rules.md](../../critical-rules/critical-rules.md) Rule 11.
+> **`folders[].fullyQualifiedName` carries the literal `Folder`** (e.g., `"Shared"`, `"Shared/Sales"`) returned by `uip solution resources list` — the same value the agent-level `resource.json` writes into `properties.folderPath` and that `bindings_v2.json` propagates. Templates show `<Folder>` as the placeholder; examples show `"Shared"` as a concrete value. Auto-generated declarations for **solution-internal projects** (created when the agent project is registered with the solution — by `uip agent init` auto-registration or by the `uip solution projects add` fallback) keep `"solution_folder"` instead — they have no fixed Orchestrator folder until deploy. See [../../critical-rules/critical-rules.md](../../critical-rules/critical-rules.md) Rule 11.
 
 ## Directory Structure
 

package/skills/uipath-agents/references/lowcode/critical-rules/critical-rules.md

@@ -30,7 +30,7 @@ Some additional rules and anti-patterns may only be relevant for autonomous or c
 
 12. **Tools carry a `location` field.** Use `"solution"` when the row from `uip solution resources list` has `Source: "Local"` (resource is in the same solution); use `"external"` when `Source: "Remote"` (already deployed in Orchestrator). All other resource fields (`type`, `referenceKey`, `folderPath`, schemas, `exampleCalls`) follow the same rules in both cases. Connection (Integration Service) bindings are bound by `connection.id` and are exempt — no `folderPath` propagation.
 
-13. **Process tools require solution-level resource files and `debug_overwrites.json`.** Whether local or external, you need the agent-level `resources/{ToolName}/resource.json`, solution-level files under `resources/solution_folder/`, AND a `userProfile/<userId>/debug_overwrites.json` for folder resolution. `uip solution resources refresh` generates these from the bindings; for in-solution agents the package + process declarations are pre-created when the project is registered with the solution (auto-registered by `uip agent init` when run inside the solution directory; falls back to `uip solution project add` if registration was `NotInSolution` / `Skipped` / `Failed` — `OptedOut` means `--skip-solution-registration` was passed and the skip was intentional), and refresh resolves the binding against them. Without these, Studio Web will show "resource is missing in this environment". See [capabilities/process/solution-files.md](../capabilities/process/solution-files.md).
+13. **Process tools require solution-level resource files and `debug_overwrites.json`.** Whether local or external, you need the agent-level `resources/{ToolName}/resource.json`, solution-level files under `resources/solution_folder/`, AND a `userProfile/<userId>/debug_overwrites.json` for folder resolution. `uip solution resources refresh` generates these from the bindings; for in-solution agents the package + process declarations are pre-created when the project is registered with the solution (`uip agent init` registers with the parent `.uipx` inside a solution, or auto-scaffolds `<Name>Solution/` and registers when run outside one; falls back to `uip solution projects add` if registration was `Skipped` / `Failed` / `NotInSolution` — `OptedOut` means `--skip-solution-registration` was passed and both auto-scaffold and registration were skipped intentionally), and refresh resolves the binding against them. Without these, Studio Web will show "resource is missing in this environment". See [capabilities/process/solution-files.md](../capabilities/process/solution-files.md).
 
 14. **Never manually edit `storageVersion`.** It is managed by `uip agent refresh` (which writes the latest version on success) and by Studio Web on import. `uip agent validate` fails with `AgentValidationOutdated` if the version is behind — run `uip agent refresh` to migrate. If validate reports a `storageVersion` newer than supported, upgrade uipcli rather than editing the field by hand.
 

package/skills/uipath-agents/references/lowcode/project-lifecycle.md

@@ -23,6 +23,8 @@ uip agent init "<AGENT_NAME>" --output json
 
 The `<path>` argument is relative or absolute; the command can run from any directory. Creates agent.json, entry-points.json, project.uiproj, and default eval directories inside the target path. Run `uip agent refresh` after editing to regenerate `entry-points.json` and `bindings_v2.json`.
 
+**Solution placement** (standalone mode): inside a solution directory the project auto-registers with the parent `.uipx`; **outside any solution it auto-scaffolds one** — creates `<Name>Solution/<Name>Solution.uipx` and nests the project at `<Name>Solution/<Name>/` (response adds `Data.AutoCreatedSolution`). Pass `--skip-solution-registration` to opt out of both — the project then lands at the bare path with `SolutionRegistration.Status: OptedOut`. See [§ Register Project with Solution](#register-project-with-solution).
+
 **Options:**
 - `--conversational` - Pass to initialize a conversational agent. When not passed, an autonomous agent is initialized.
 - `--model <model>` — LLM model to use (default: `gpt-5.4` for autonomous, `anthropic.claude-sonnet-4-5-20250929-v1:0` for conversational). This default is stale; override it post-init — discover current tenant models with `uip agent model list` and select per [model-selection-guide.md](model-selection-guide.md). Pass `--model` at init or edit `settings.model` after.
@@ -172,17 +174,23 @@ uip solution init "<SOLUTION_NAME>" --output json
 
 ### Register Project with Solution
 
-`uip agent init` **auto-registers** the project with the parent `.uipx` when run from inside a solution directory (pass `--skip-solution-registration` to skip auto-registration). Verify via `Data.SolutionRegistration.Status` in the `agent init` response. The full set of statuses:
+`uip agent init` always lands the project inside a solution — no manual `solution init` needed:
+
+- **Inside a solution directory** — auto-registers the project with the parent `.uipx`.
+- **Outside any solution** — auto-scaffolds a parent solution: creates `<Name>Solution/<Name>Solution.uipx` and nests the project at `<Name>Solution/<Name>/`. The response adds `Data.AutoCreatedSolution` (`{ Name, Path, SolutionFile }`) and reports `SolutionRegistration.Status: Registered`. Idempotent — re-running reuses the existing `.uipx` (`AlreadyRegistered`). If a **non-empty** directory already exists at the path you typed, init warns and leaves it untouched — the project still lands in `<Name>Solution/<Name>/`, not the existing directory.
+- **`--skip-solution-registration`** — opts out of **both** auto-scaffold and registration. No discovery, no sibling solution dir; the project lands at the bare path with `Status: OptedOut`.
+
+Verify via `Data.SolutionRegistration.Status` in the `agent init` response. The full set of statuses:
 
 - `Registered` / `AlreadyRegistered` — registered (added now / already present). **You are done.**
-- `OptedOut` — `--skip-solution-registration` was passed; registration was intentionally skipped. No action needed (register later with the fallback if you change your mind).
-- `NotInSolution` — no parent `.uipx` was found (`init` ran outside a solution). Use the fallback if you want it in a solution.
+- `OptedOut` — `--skip-solution-registration` was passed; auto-scaffold and registration were intentionally skipped. No action needed (register later with the fallback if you change your mind).
 - `Skipped` — a candidate solution was found but registration wasn't safe (e.g. multiple `.uipx`, or project outside the solution dir). Resolve, then use the fallback.
 - `Failed` — registration was attempted but errored (`.uipx` read/parse/write). Use the fallback.
+- `NotInSolution` — no parent `.uipx` and auto-scaffold did not run (rare outside `--skip-solution-registration`). Use the fallback if you want it in a solution.
 
 ```bash
-# Fallback — when Status is NotInSolution / Skipped / Failed (not needed for OptedOut).
-uip solution project add "<AGENT_PROJECT_DIR>" [solutionFile] --output json
+# Fallback — when Status is Skipped / Failed / NotInSolution (not needed for OptedOut or Registered).
+uip solution projects add "<AGENT_PROJECT_DIR>" [solutionFile] --output json
 ```
 
 Run from the solution directory. The first argument is the path to the agent project folder (positional, not `--project-path`). The optional second argument is the path to the `.uipx` solution file — if omitted, the CLI searches up from the project path to find the nearest `.uipx` automatically.
@@ -329,10 +337,12 @@ uip solution init "<SOLUTION_NAME>" --output json
 uip agent init "<SOLUTION_NAME>/<AGENT_NAME>" --output json
 # (fallback only — run if Data.SolutionRegistration.Status is `NotInSolution` / `Skipped` / `Failed`;
 #  `OptedOut` means `--skip-solution-registration` was passed and registration was skipped on purpose)
-# uip solution project add "<SOLUTION_NAME>/<AGENT_NAME>" --output json
+# uip solution projects add "<SOLUTION_NAME>/<AGENT_NAME>" --output json
 ```
 
-When the fallback is needed, `uip solution project add` automatically finds the nearest `.uipx` by searching up from the agent path.
+The explicit `uip solution init` is optional: running `uip agent init "<AGENT_NAME>"` alone outside any solution auto-scaffolds `<AGENT_NAME>Solution/<AGENT_NAME>/` and registers the project (response carries `Data.AutoCreatedSolution`). Keep the explicit `solution init` when you want a solution name distinct from the agent name.
+
+When the fallback is needed, `uip solution projects add` automatically finds the nearest `.uipx` by searching up from the agent path.
 
 ### Step 3 — Configure agent.json
 
@@ -415,10 +425,10 @@ All solution lifecycle operations go through `uip solution` CLI. Never call Auto
 |------|---------|----------|-----------------|
 | Login check | `uip login status --output json` | Any directory | — |
 | Create solution | `uip solution init "<NAME>" --output json` | Any directory | — |
-| Scaffold agent | `uip agent init "<NAME>" --output json` | Solution directory | — |
+| Scaffold agent | `uip agent init "<NAME>" --output json` | Any directory (auto-scaffolds `<NAME>Solution/` if outside a solution) | — |
 | Scaffold inline agent | `uip agent init "<FLOW_PROJECT_DIR>" --inline-in-flow --output json` | Any directory | — |
 | Verify project registration | Check `Data.SolutionRegistration.Status` from `agent init` response (`Registered` / `AlreadyRegistered` = done; `OptedOut` = `--skip-solution-registration` passed) | Solution directory | — |
-| Register project (fallback) | `uip solution project add "<PATH>" --output json` — when `agent init` returned `NotInSolution` / `Skipped` / `Failed` | Solution directory | — |
+| Register project (fallback) | `uip solution projects add "<PATH>" --output json` — when `agent init` returned `Skipped` / `Failed` / `NotInSolution` | Solution directory | — |
 | Refresh + regenerate derived files | `uip agent refresh [path] --output json` | Agent dir or any with path | — |
 | Validate (strict read-only) | `uip agent validate [path] --output json` | Agent dir or any with path | — |
 | Debug / run end-to-end on Studio Web | `uip agent debug <AgentDir> --inputs '{...}' --output json` | Agent dir | `Successful`, `Faulted`, `Stopped` |

package/skills/uipath-agents/references/lowcode/solution-resources.md

@@ -27,7 +27,7 @@ The `resources/solution_folder/` directory contains JSON resource definitions. W
 
 **Path:** `resources/solution_folder/package/{AgentName}.json`
 
-Links an agent project to its deployable NuGet package. Auto-generated when the agent project is registered with its solution — by `uip agent init` (auto-registration when run from inside a solution directory) or by the `uip solution project add` fallback.
+Links an agent project to its deployable NuGet package. Auto-generated when the agent project is registered with its solution — by `uip agent init` (registers with the parent `.uipx` inside a solution, or auto-scaffolds `<Name>Solution/` and registers when run outside one) or by the `uip solution projects add` fallback.
 
 ```jsonc
 {
@@ -55,7 +55,7 @@ The package `name` becomes part of the package identifier: `{SolutionName}.agent
 
 **Path:** `resources/solution_folder/process/agent/{AgentName}.json`
 
-Makes the agent available as a runnable process in Orchestrator. One file per agent project. Auto-generated when the agent project is registered with its solution — by `uip agent init` (auto-registration when run from inside a solution directory) or by the `uip solution project add` fallback.
+Makes the agent available as a runnable process in Orchestrator. One file per agent project. Auto-generated when the agent project is registered with its solution — by `uip agent init` (registers with the parent `.uipx` inside a solution, or auto-scaffolds `<Name>Solution/` and registers when run outside one) or by the `uip solution projects add` fallback.
 
 ```jsonc
 {

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

@@ -1,6 +1,6 @@
 ---
 name: uipath-api-workflow
-description: "UiPath API Workflow assistant — author, run, package, publish JSON workflows executed by `uip api-workflow run`. Covers logical/hierarchical structure (Sequence, Assign, JavaScript, If with #Wrapper/#Then/#Else, ForEach, DoWhile, Break, TryCatch, Wait, Response — including nested patterns) AND HTTP / Integration Service connector activities (Gmail, Outlook, GitHub, Slack, etc.) authored via `uip api-workflow registry resolve` + `stub`. Triggers on prompts about UiPath API workflows, project type \"Api\", JSON workflow files containing `document.dsl`/`do[]`, any of those activity types, or fetching data from a public/vendor API. Uses `uip api-workflow run` for local execution and `uip solution pack`/`publish` for deployment. 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`. 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."
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 ---
 
@@ -19,7 +19,8 @@ Build, run, and publish UiPath API Workflows — JSON files conforming to the CN
 - 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
+- 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)
 
 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`).
 
@@ -56,13 +57,13 @@ Do NOT use for: `.flow` Maestro flows (→ `uipath-maestro-flow`), `.xaml` / cod
 15. **Response activity shape — STRICT for StudioWeb roundtrip:**
     - `markJobAsFailed` is a sibling of `response`, not nested inside it.
     - Always include `"then": "end"` — without it, the workflow does not terminate properly. `then: "end"` is for Response only; `then: "exit"` is for control-flow branches/loops.
-    - **Object-valued responses MUST use the single-expression form**, NOT the JSON-object-with-`${}`-fields form. StudioWeb's designer corrupts the latter on save (issue **SW-28452** / [UiPath/cli#1537](https://github.com/UiPath/cli/issues/1537)).
+    - **Object-valued responses MUST use the single-expression form**, NOT the JSON-object-with-`${}`-fields form. StudioWeb's designer corrupts the latter on save.
       - ✗ Wrong (CLI runs but StudioWeb corrupts): `"response": { "tier": "${$context.variables.tier}", "count": "${$context.variables.count}" }`
       - ✓ Correct: `"response": "${{ tier: $context.variables.tier, count: $context.variables.count }}"`
       Inside the outer `${{ ... }}` you are already in expression scope, so reference variables/outputs directly without an inner `${...}` wrapper. JS object literal keys can be unquoted identifiers (`tier:`, `count:`); literal string values use single quotes (`status: 'ok'`); numbers/booleans/references are bare. The designer leaves an already-wrapped single expression alone; the JSON-object form gets flattened to a stringified expression where inner `${...}` substitutions are inside JS double-quoted strings (which don't interpolate), turning each field into the literal text of its expression.
       - Either `"${ { ... } }"` (single-brace, expression-of-object-literal) or `"${{ ... }}"` (double-brace, object-literal-expression form) is valid — both evaluate to the same JS object. Pick one and stay consistent within a workflow.
     - For single-value responses (returning one variable or one expression), the simple form is fine: `"response": "${$context.outputs.Javascript_1}"` or `"response": "${'done'}"`.
-    - **On-disk is authoritative.** Even with the single-expression workaround, every StudioWeb designer save can re-trigger normalization passes that may corrupt the Response shape. After any designer roundtrip, re-validate with `uip api-workflow run --no-auth` and re-apply the workaround if needed. Until SW-28452 ships a fix, treat the file on disk as truth, not what the designer renders.
+    - **On-disk is authoritative.** Even with the single-expression workaround, every StudioWeb designer save can re-trigger normalization passes that may corrupt the Response shape. After any designer roundtrip, re-validate with `uip api-workflow run --no-auth` and re-apply the workaround if needed. Until the designer fix ships, treat the file on disk as truth, not what the designer renders.
 16. **Connector activities (HTTP + Integration Service) come from `uip api-workflow registry resolve` + `stub` — never hand-author or guess.** The stub computes `metadata.configuration`, the kind (`UiPath.Http` vs `UiPath.IntSvc`), the endpoint (with hub prefix), `SlotKey`, and `ExportBucketKey` (which can differ — HTTP slot `HttpRequest_1` vs bucket `http_request_1`). Use all of them verbatim; NEVER invent a `uiPathActivityTypeId`, hand-author `metadata.configuration`, or reconstruct a key from `objectName`. Non-negotiables (full step-by-step, field-shape rules, multipart, and worked examples in [references/connector-activity-discovery.md](references/connector-activity-discovery.md)):
     - **A keyword `resolve` miss is NOT proof no curated activity exists — verify connector-first before giving up.** `resolve` AND-matches every token, so a marketing phrase + guessed verb over-narrows (the product "UiPath Data Fabric" carries `connectorKey: uipath-uipath-dataservice` and activity names like "Create Entity Record" — `resolve "data fabric insert"` returns 0; fewer/truer tokens, not more). Before concluding none exists or falling back to a hand-built HTTP call (a Rule 0 fork): map the product/vendor → connector key with `uip is connectors list --filter "<product>"`, then enumerate with `uip is activities list <connector-key>`. Do NOT hardcode/guess the key — look it up. See the reference's Step 1 recovery.
     - **IntSvc/vendor activities require a *pinged* connection.** `uip is connections ping <uuid>` must succeed before authoring — listing-state ≠ runtime-state; an `Enabled` connection can still 401 in cloud. An empty listing is NOT proof no connection exists — `uip is connections list` is folder-scoped. On empty/failed listing, walk the fallbacks in order: unfiltered `uip is connections list`, then `uip is connections list --all-folders` (catches connections in other folders), re-pinging a different `Id` for that `ConnectorKey` each time.
@@ -82,9 +83,11 @@ Do NOT use for: `.flow` Maestro flows (→ `uipath-maestro-flow`), `.xaml` / cod
     ```
     It scaffolds `project.uiproj` + `Workflow.json` + `entry-points.json` + `bindings_v2.json` and, when run inside a solution, **auto-registers the project in the surrounding `.uipx`** (correct `ProjectRelativePath` + a fresh `Id`). Success → `Code: "ApiWorkflowInit"`. Then edit `Workflow.json` only.
 
+    **Which mode.** Default = `init` inside a solution (Studio Web-editable + deployable — what a shipped automation needs). Use `--skip-solution-registration` ONLY when the user explicitly wants a CLI-only/local workflow that never opens in Studio Web or ships in a solution; it still emits the full project folder (`<name>/Workflow.json` + siblings), just no `.uipx` wiring. Never emit a lone `Workflow.json` with no project files — even a throwaway local workflow gets a project.
+
     **Why it matters:** a legacy `project.json` + `workflows/WF_*.json` layout (no `.uiproj`) passes every runtime gate — `validate`, `run`, `pack`, `publish`, deploy — but Studio Web rejects it as `invalid_project_folder` and never shows it. `init` is the one step that can't produce the wrong shape. Full layout + field rules: [references/workflow-file-format.md](references/workflow-file-format.md#project-structure-studio-web-editable-contract).
 
-    To **convert a legacy `project.json` project**, `init` a fresh sibling and move the existing workflow content into its `Workflow.json` (cleanest), or convert in place — see [references/troubleshooting.md](references/troubleshooting.md). Never wire it with `uip solution project add/remove` (errors on an already-registered name; `remove`+`add` destroys the project `Id`).
+    To **convert a legacy `project.json` project**, `init` a fresh sibling and move the existing workflow content into its `Workflow.json` (cleanest), or convert in place — see [references/troubleshooting.md](references/troubleshooting.md). Never wire it with `uip solution projects add/remove` (errors on an already-registered name; `remove`+`add` destroys the project `Id`).
 
 20. **`uip api-workflow validate <Workflow.json>` is the autonomous closure step for every authoring or edit cycle.** Run it as the LAST command before asking the user anything about runtime. It's offline (no auth, no network, no side effects): JSON Schema + semantic checks on the static file. Output codes:
     - `Result: "Success"`, `Code: "ApiwfValidate"`, `Data.Status: "Valid"` (exit 0) — possibly with `Data.Warnings`. Proceed to rule 21 (ask the user whether to run).
@@ -182,7 +185,7 @@ State the consequence in the question (e.g. "running with auth WILL send a real
 
 Fix run failures in category order — **Structure > Expression > Activity Config > Logic** (higher categories often resolve lower ones). Full pitfall catalog: [references/troubleshooting.md](references/troubleshooting.md).
 
-### Phase 4: Package and Publish
+### 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.
 
@@ -205,6 +208,8 @@ uip solution publish <outputDir>/<package>.zip \
 
 Requires `uip login`.
 
+**Operate + diagnose the published workflow.** Once deployed, the workflow is an Orchestrator API process — the local `uip api-workflow` verbs no longer apply to it. Invoke it (HTTP/schedule/Integration Service event trigger), start/list/stop its jobs, manage the Integration Service connections it uses, and read cloud-run logs/traces via `uip or` / `uip is` / `uip traces`. Full command map: [references/operating-published-workflows.md](references/operating-published-workflows.md). These are sibling-skill surfaces (`uipath-platform`, `uipath-troubleshoot`) — delegate there for depth.
+
 ## Quick Start (CREATE from scratch)
 
 ```bash
@@ -245,6 +250,7 @@ uip solution publish ./build/MyApiSolution.zip --tenant MyTenant --output json
 | [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/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/troubleshooting.md](references/troubleshooting.md) | Failed runs, structure/expression/loop/nesting/response/validation pitfalls, packaging errors, publish errors, debugging strategy |
 
 ## Templates
@@ -269,7 +275,8 @@ The mistakes an agent makes most often (each maps to a Critical Rule above — s
 - **Do NOT** read workflow inputs as `$input.<name>` from a non-first activity — use `$workflow.input.<name>`. See rule 13.
 - **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** wire a project into the solution with `uip solution project 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** 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).
 
 ## Infinite Loop Prevention

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

@@ -410,9 +410,9 @@ uip solution init <solutionName> [--output json]
 
 Output: `{ "Result": "Success", "Code": "SolutionInit", "Data": { "Status": "Created successfully", ... } }`.
 
-## `uip solution project add` *(scope: solution-tool)*
+## `uip solution projects add` *(scope: solution-tool)*
 
-For **new** API workflow projects, prefer `uip api-workflow init <name>` run inside the solution directory — it scaffolds the correct `project.uiproj` shape AND auto-registers the project in the `.uipx`. `uip solution project add` errors (`Project name already exists`) on an already-registered project, and `remove`+`add` destroys the project `Id`. Reserve direct `.uipx` edits for converting a legacy `project.json` project in place (change only `ProjectRelativePath` → `<folder>/project.uiproj`, preserve `Id`/`Type`). A registerable project folder must contain `project.uiproj` (`ProjectType: "Api"`) + `Workflow.json` + `entry-points.json` — see [workflow-file-format.md](workflow-file-format.md#project-structure-studio-web-editable-contract) and SKILL.md rule 19a. See `uip solution project add --help` for current flags.
+For **new** API workflow projects, prefer `uip api-workflow init <name>` run inside the solution directory — it scaffolds the correct `project.uiproj` shape AND auto-registers the project in the `.uipx`. `uip solution projects add` errors (`Project name already exists`) on an already-registered project, and `remove`+`add` destroys the project `Id`. Reserve direct `.uipx` edits for converting a legacy `project.json` project in place (change only `ProjectRelativePath` → `<folder>/project.uiproj`, preserve `Id`/`Type`). A registerable project folder must contain `project.uiproj` (`ProjectType: "Api"`) + `Workflow.json` + `entry-points.json` — see [workflow-file-format.md](workflow-file-format.md#project-structure-studio-web-editable-contract) and SKILL.md rule 19a. See `uip solution projects add --help` for current flags.
 
 ## `uip solution pack`
 

package/skills/uipath-api-workflow/references/connector-activity-discovery.md

@@ -817,7 +817,7 @@ When the user asks to change a value, add a field, or copy a stubbed activity to
 
 2. **Stub doesn't validate `--inputs` against the IS schema.** Field names not in `requestFields` / `parameters` are silently dropped on the way through `pickFields`. Check `Data.ResponseFields` and the IS schema if a value goes missing.
 
-3. **Subsequent designer saves can re-introduce mangling** of the Response activity (issue **SW-28452** / [UiPath/cli#1537](https://github.com/UiPath/cli/issues/1537)). See [troubleshooting.md](troubleshooting.md#object-valued-response-gets-corrupted-fields-evaluate-to-literal-expression-text-sw-28452--cli1537) — defending against the Response corruption is independent of the connector-activity discovery flow.
+3. **Subsequent designer saves can re-introduce mangling** of the Response activity. See [troubleshooting.md](troubleshooting.md#object-valued-response-gets-corrupted-fields-evaluate-to-literal-expression-text) — defending against the Response corruption is independent of the connector-activity discovery flow.
 
 4. **Login is required for `resolve` and `stub`.** Both hit live tenant endpoints (TypeCache and IS Elements). `uip api-workflow run --no-auth` still works for the resulting workflow if it only uses Http kind with `ImplicitConnection`; IntSvc kind always needs auth at run time.
 

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

@@ -9,7 +9,7 @@ API workflows use **JavaScript** for all expressions (`evaluate.language: "javas
 | `$workflow.input` | The workflow's input arguments (from `--input-arguments` JSON or caller). Constant for the entire run. | Workflow run |
 | `$workflow` | Workflow runtime info: `{ id, definition, input, startedAt }`. Use `$workflow.input` to read inputs. | Workflow run |
 | `$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.<TaskName>` | Workflow run |
+| `$context` | Mutable shared state: `$context.variables.<name>`, `$context.outputs.<Activity>` | Workflow run |
 | `$output` | The current task's raw output. | This task only |
 | 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` |
@@ -263,7 +263,7 @@ Response_1          → reads any $context data, ends workflow
 
 - **Do NOT** use `$input.<name>` to read workflow inputs from non-first tasks — `$input` is the previous task's `$output`. Use `$workflow.input.<name>`.
 - **Do NOT** mutate `$context` directly inside a JS_Invoke script — return a new value and let `export.as` merge it.
-- **Do NOT** rely on `$output` two tasks later — it is overwritten by the next task. Always `export` to `$context.outputs.<TaskName>` if you need it.
+- **Do NOT** rely on `$output` two tasks later — it is overwritten by the next task. Always `export` to `$context.outputs.<Activity>` if you need it.
 - **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.

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

@@ -0,0 +1,74 @@
+# Operating & Diagnosing a Published API Workflow
+
+After `uip solution publish` + deploy, the workflow lives in Orchestrator as an **API process**. The local authoring verbs (`uip api-workflow init/validate/run/pack`) no longer apply to the deployed copy — operate and diagnose it through the platform surfaces below.
+
+**These commands belong to sibling skills** — `uip or` / `uip is` to `uipath-platform`, root-cause to `uipath-troubleshoot`. They are the correct owners for depth (flags, folder scoping, auth). Listed here so the operate + diagnose loop is discoverable and actionable from this skill; if a sibling skill is unavailable, the commands below still run standalone. All require `uip login`.
+
+## Invoke a published workflow (the three trigger types)
+
+A published API workflow is started three ways — the same three trigger types the product exposes:
+
+| Trigger | When it fires | Drive it with |
+|---------|---------------|---------------|
+| **HTTP** | A caller (app, agent, external system) POSTs a JSON payload matching the workflow's `input.schema`; runs synchronously, returns the `Response` output | Start a run as an Orchestrator job: `uip or jobs start <process-key> --output json` |
+| **Schedule** | Cron cadence managed in Orchestrator | `uip or triggers create` / `list` / `get` / `update` / `delete` |
+| **Integration Service event** | An upstream connector event/webhook (Salesforce opportunity closed, new Snowflake row, Slack message) starts it and passes the event payload as input | Configure the event subscription in Integration Service; inspect with `uip or triggers list --folder-path <path>` |
+
+All three deliver the payload as the workflow's input variables — the same body runs under any trigger if the input shape matches.
+
+> **`uip or` commands are folder-scoped — but the accepted selectors differ per command:**
+> - `jobs list` requires `--folder-path <path>`, `--folder-key <key>`, **or** `--all-folders` (searches every folder).
+> - `triggers list`/`create`/`get`/`update`/`delete` require `--folder-path <path>` or `--folder-key <key>` — they do **not** accept `--all-folders`.
+> - `jobs start <process-key>` takes the process key as a required positional; the folder is **optional** (inferred from the process if omitted).
+> - `jobs get`/`logs`/`stop` take a `<jobId>` directly — no folder selector.
+
+## Manage the Integration Service connections it consumes
+
+API workflows don't own connections — they bind named Integration Service connections at author time and reuse them at runtime.
+
+```bash
+uip is connections list --all-folders --output json   # enumerate (folder-scoped; --all-folders searches every folder)
+uip is connections ping <connection-uuid> --output json # health — Code: "ConnectionPing" = usable
+uip is connections edit <connection-uuid>               # re-authenticate (opens OAuth browser flow)
+```
+
+A workflow authored against a connection that does not `ping` 401s in cloud regardless of how correct the JSON is. See [connector-activity-discovery.md](connector-activity-discovery.md) for the author-time discovery+verify flow and [troubleshooting.md](troubleshooting.md) for the stale-listing / `ConnectionNotEnabled` failure modes.
+
+## Run / manage the deployed process
+
+```bash
+uip or processes list --output json                     # confirm the API process deployed
+uip or jobs start <process-key> --output json           # invoke a run (folder optional — inferred from the process)
+uip or jobs list --all-folders --output json            # runs + their states (needs a folder selector)
+uip or jobs get <jobId> --output json                   # one run's status / fault detail
+uip or jobs stop <jobId> --output json                  # cancel a running job
+```
+
+## Diagnose a failed cloud run
+
+The local diagnose loop catches structure/expression faults **before** publish — always run it first:
+
+```bash
+uip api-workflow validate ./Workflow.json --output json   # static: schema + semantic
+uip api-workflow run ./Workflow.json --no-auth --output json  # runtime: expression / logic
+```
+
+Faults that only surface in cloud (auth, connection state, real vendor responses, trigger wiring) are diagnosed from the deployed job:
+
+```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 traces` is documented Agent-type-process-only — for an API-workflow job use `uip traces spans get --job-key <jobKey>` instead.
+
+Map the surfaced error back to a fix using the category catalog in [troubleshooting.md](troubleshooting.md) (Structure > Expression > Activity Config > Logic). For deep, multi-signal root-cause investigations (what changed, cross-run comparison, incident correlation), hand off to **uipath-troubleshoot**.
+
+## Mode cheat-sheet
+
+| Mode | Local (this skill's CLI) | Post-publish (delegate) |
+|------|--------------------------|-------------------------|
+| **Build** | `init`, edit, `validate`, `registry resolve`/`stub`, `pack` | — |
+| **Operate** | `run` (local execution) | `uip or jobs start <process-key>`/`list`/`stop`, `uip or triggers` (need `--folder-path`/`--folder-key`), `uip is connections` |
+| **Diagnose** | `validate` → `run --no-auth` loop, `uip is connections ping` | `uip or jobs logs`/`get`, `uip traces spans get --job-key`, uipath-troubleshoot |

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

@@ -437,7 +437,7 @@ Returns a result and ends the workflow execution path.
 
 **Required fields:** `response` (single expression string), `markJobAsFailed` (boolean, sibling of `response`), `then: "end"`, `export.as`, `metadata`
 
-**Critical (StudioWeb roundtrip):** `response` MUST be a **single expression string**. For object-valued returns, use the `${{ ... }}` (double-brace) object-literal expression form, NOT a JSON object with `${...}` fields. The JSON-object form is corrupted by StudioWeb's designer on save (issue **SW-28452** / [UiPath/cli#1537](https://github.com/UiPath/cli/issues/1537)) — each field becomes the literal text of its expression instead of the evaluated value. See SKILL.md critical rule 15 and the [troubleshooting entry](troubleshooting.md#object-valued-response-gets-corrupted-fields-evaluate-to-literal-expression-text-sw-28452--cli1537).
+**Critical (StudioWeb roundtrip):** `response` MUST be a **single expression string**. For object-valued returns, use the `${{ ... }}` (double-brace) object-literal expression form, NOT a JSON object with `${...}` fields. The JSON-object form is corrupted by StudioWeb's designer on save — each field becomes the literal text of its expression instead of the evaluated value. See SKILL.md critical rule 15 and the [troubleshooting entry](troubleshooting.md#object-valued-response-gets-corrupted-fields-evaluate-to-literal-expression-text).
 
 **Export pattern:**
 ```
@@ -462,7 +462,7 @@ Inside the outer `${{ ... }}` you're already in JS expression scope. Reference r
 - Variables/outputs evaluate directly without inner `${...}`: `$context.variables.X`, `$context.outputs.Y`, `$workflow.input.Z`
 - String literals use single quotes: `status: 'ok'` (single quotes avoid JSON escaping)
 - Numbers/booleans are bare: `count: 0`, `flag: true`
-- The whole thing is one expression — adding inner `${...}` re-triggers the SW-28452 corruption
+- The whole thing is one expression — adding inner `${...}` re-triggers the designer corruption
 
 **Single-value response (one variable or one expression):**
 ```json
@@ -472,7 +472,7 @@ or
 ```json
 "response": "${'done'}"
 ```
-The simple single-expression form is fine; the SW-28452 issue only affects object payloads.
+The simple single-expression form is fine; the designer corruption only affects object payloads.
 
 **Common mistakes:**
 - **Object payload with `${...}` fields** (`"response": { "tier": "${$context.variables.tier}" }`) — runs locally, corrupted by StudioWeb on save. Use single-expression `${{ ... }}` instead.

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

@@ -186,7 +186,7 @@ Common failure modes when authoring, running, packaging, or publishing API workf
 
 ## StudioWeb Roundtrip Pitfalls
 
-These are issues that surface only when a workflow is opened or run in **StudioWeb** (alpha.uipath.com). Workflows that pass `uip api-workflow run --no-auth` may still fail in cloud for these reasons.
+These are issues that surface only when a workflow is opened or run in **StudioWeb** (cloud.uipath.com). Workflows that pass `uip api-workflow run --no-auth` may still fail in cloud for these reasons.
 
 ### `ReferenceError: <literal> is not defined` after opening in StudioWeb
 
@@ -205,7 +205,7 @@ These are issues that surface only when a workflow is opened or run in **StudioW
 - **What does NOT need wrapping:** numbers (`0`, `42`), booleans (`true`/`false`), values that already evaluate expressions (`"${$workflow.input.x}"`, `"${$context.variables.tier}"`), and the activity-control strings `then: "exit"` / `then: "end"`.
 - **Heuristic:** any time you'd write `"foo"` as a *literal value* you intend the workflow to use, wrap it as `"${'foo'}"`. The CLI evaluates the expression and gets the string `'foo'`; StudioWeb leaves the already-wrapped form alone.
 
-### Object-valued Response gets corrupted; fields evaluate to literal expression text (SW-28452 / cli#1537)
+### Object-valued Response gets corrupted; fields evaluate to literal expression text
 
 - **Symptom:** Workflow runs correctly under `uip api-workflow run` and Response returns the expected object (e.g. `{ tier: "GOLD", count: 3 }`). After opening + saving in StudioWeb, the same Response now returns each field's value as the **literal text of its expression** rather than the evaluated value — `tier` becomes the string `"${$context.variables.tier}"` (one long string, often 100+ chars), not `"GOLD"`. StudioWeb's own output-schema validator may flag the mismatch ("Output-ul nu corespunde schemei de output configurate").
 - **Cause:** StudioWeb's designer rewrites Response object payloads on save. Authored `{ "response": { "tier": "${...}", "count": "${...}" } }` is collapsed into a single stringified expression: `"response": "${{\"tier\":\"${...}\",\"count\":\"${...}\"}}"`. The outer `${{ ... }}` is a JS object-literal expression form, but inside it the keys/values are inside JS **double-quoted** strings (`"tier":"${...}"`) — and JS double-quoted strings don't interpolate `${...}`, only template literals do. So each field's value resolves to the literal characters `${...}`, not the evaluated expression.
@@ -237,8 +237,8 @@ These are issues that surface only when a workflow is opened or run in **StudioW
 - **Why it works:** Inside the outer `${{ ... }}` you're already in JS expression scope. The body is a JS object literal where unquoted keys are identifiers (`tier:`, `count:`), references like `$context.variables.tier` evaluate directly, string literals use single quotes (`status: 'ok'`), and numbers/booleans are bare (`count: 0`, `flag: true`). The designer recognizes the whole thing as a single expression and leaves it alone — it doesn't try to reinterpret each field.
 - **Either expression-form works:** `"${ { ... } }"` (single-brace expression containing a JS object literal) and `"${{ ... }}"` (double-brace object-literal-expression form) evaluate to the same value. Pick one convention; this skill standardizes on the double-brace form, but you may see single-brace in the wild and they are interchangeable.
 - **Single-value responses are fine as-is:** `"response": "${$context.outputs.Javascript_1}"` or `"response": "${'done'}"` — the designer only mangles object payloads, not single expressions.
-- **On-disk is authoritative — re-validate after every designer save.** Even with the single-expression workaround, every StudioWeb designer save may re-trigger normalization passes that corrupt the Response shape. Treat the file on disk as the source of truth: after any designer roundtrip, re-run `uip api-workflow run --no-auth --output json` and inspect the Response output. If a field has become the literal text of its expression (a long string instead of the evaluated value), the file was re-corrupted — re-apply the single-expression workaround in the file directly, and consider keeping CLI-authored workflows out of designer save cycles until SW-28452 ships.
-- **Upstream:** designer-side bug SW-28452. CLI issue with full pre/post diff and runtime evidence: [UiPath/cli#1537](https://github.com/UiPath/cli/issues/1537). Fix lives in the api-workflows translator for Response tasks (needs to preserve object payloads losslessly). Until that ships, the single-expression workaround is required and may need re-applying after each designer roundtrip.
+- **On-disk is authoritative — re-validate after every designer save.** Even with the single-expression workaround, every StudioWeb designer save may re-trigger normalization passes that corrupt the Response shape. Treat the file on disk as the source of truth: after any designer roundtrip, re-run `uip api-workflow run --no-auth --output json` and inspect the Response output. If a field has become the literal text of its expression (a long string instead of the evaluated value), the file was re-corrupted — re-apply the single-expression workaround in the file directly, and consider keeping CLI-authored workflows out of designer save cycles until the designer fix ships.
+- **Upstream:** designer-side StudioWeb bug. Fix lives in the api-workflows translator for Response tasks (needs to preserve object payloads losslessly). Until that ships, the single-expression workaround is required and may need re-applying after each designer roundtrip.
 
 ### Multi-key `Assign.set` silently drops all but one variable
 
@@ -514,7 +514,7 @@ These are issues that surface only when a workflow is opened or run in **StudioW
   - **Fix:** Switch to IntSvc kind (`call: "UiPath.IntSvc"`, `with.connector` = the vendor key, `with.endpoint` = `"/<curated-operation-name>"`). See [connector-activity-discovery.md — IntSvc kind](connector-activity-discovery.md#intsvc-kind--call-uipathintsvc-vendor-curated-activity) — IntSvc kind is for vendor activities, Http kind is only for the `uipath-uipath-http` HTTP Request activity.
 
   **Sub-case B — Connection is in a broken state.** The endpoint is right (e.g. `/getNewestEmail` on an Outlook connection), but the connection's upstream OAuth token is expired, never properly authorized, or the running identity doesn't have access to the connection.
-  - **Fix:** Run `uip is connections ping <connection-uuid> --output json`. If it returns `Code: "ConnectionNotEnabled"`, re-authenticate via `uip is connections edit <connection-uuid>` (opens browser for OAuth) or fix in the StudioWeb UI. If it returns `Code: "ConnectionPing"` (success) but the cloud still 401s, check that your CLI login (`uip login status`) is in the same org+tenant your browser is using at alpha.uipath.com — a tenant mismatch will reject the connection ID at the proxy layer.
+  - **Fix:** Run `uip is connections ping <connection-uuid> --output json`. If it returns `Code: "ConnectionNotEnabled"`, re-authenticate via `uip is connections edit <connection-uuid>` (opens browser for OAuth) or fix in the StudioWeb UI. If it returns `Code: "ConnectionPing"` (success) but the cloud still 401s, check that your CLI login (`uip login status`) is in the same org+tenant your browser is using at cloud.uipath.com — a tenant mismatch will reject the connection ID at the proxy layer.
 
 - **Prevention:** The discovery flow's Step 4b (`uip is connections ping`) is mandatory specifically to catch sub-case B before authoring. Don't author against a connection that doesn't ping — the workflow shape will look right and even run locally, but fail at deployment time.
 
@@ -544,12 +544,12 @@ These are issues that surface only when a workflow is opened or run in **StudioW
 ### `Workflow status is not "Successful"` (executor returns failure)
 - **Cause:** A task threw during execution
 - **Fix:** Read `Message` and `Instructions` in the failure output. Common patterns:
-  - JS_Invoke: missing `return` statement, runtime error in script body, undefined `$context.outputs.<TaskName>` (prior task did not run or did not `export`)
+  - JS_Invoke: missing `return` statement, runtime error in script body, undefined `$context.outputs.<Activity>` (prior activity did not run or did not `export`)
   - Assign expression: invalid `${...}` syntax, referencing an undefined variable in strict mode
   - Loop body: condition variable not updated (DoWhile infinite loop), missing `#Body` suffix, wrong export pattern
 
-### `$context.outputs.<TaskName>` is undefined
-- **Cause:** The prior task did not `export` its output back into context
+### `$context.outputs.<Activity>` is undefined
+- **Cause:** The prior activity did not `export` its output back into context
 - **Fix:** Add the standard export to the prior task — see [expressions-and-context.md](expressions-and-context.md)
 
 ### Strict-mode JS error inside a JS_Invoke
@@ -559,6 +559,19 @@ 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
 
+### 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)
+  ```
+  (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.)
+  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**.
+
 ---
 
 ## Packaging Errors
@@ -569,7 +582,7 @@ These are issues that surface only when a workflow is opened or run in **StudioW
 
 ### `Failed to parse <solution>.uipx`
 - **Cause:** Solution file is malformed JSON
-- **Fix:** Re-create with `uip solution init <name>` and re-add projects via `uip solution project add`
+- **Fix:** Re-create with `uip solution init <name>` and re-add projects via `uip solution projects add`
 
 ### Generated `operate.json` or `package-descriptor.json` mismatch
 - **Cause:** Stale files committed by hand or from an older CLI version
@@ -586,7 +599,7 @@ These are issues that surface only when a workflow is opened or run in **StudioW
 - **Fix (in-place conversion)** when you must keep the existing folder/`Id` (SKILL.md rule 19a, [workflow-file-format.md](workflow-file-format.md#project-structure-studio-web-editable-contract)):
   - Add `project.uiproj` (`ProjectType: "Api"`, `MainFile: "Workflow.json"`) and `entry-points.json` (`filePath: "content/Workflow.json"`, no leading slash, `type: "Api"`). Copy `bindings_v2.json` if present.
   - Rename the main workflow to `Workflow.json` at the project root.
-  - Edit the `.uipx` `ProjectRelativePath` from `<folder>/project.json` → `<folder>/project.uiproj`, **preserving the project `Id` and `Type`**. Do NOT use `uip solution project remove`+`add` — it mints a new `Id`.
+  - Edit the `.uipx` `ProjectRelativePath` from `<folder>/project.json` → `<folder>/project.uiproj`, **preserving the project `Id` and `Type`**. Do NOT use `uip solution projects remove`+`add` — it mints a new `Id`.
   - Remove the stray `project.json` / `workflows/` (a mismatched `project.json` triggers `ProjectMetadataMismatchError`).
   - Re-pack, then confirm the project opens in Studio Web (runtime/pack success alone does not prove it).