@uipath/skills 1.195.0 → 1.196.0

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

@@ -4,9 +4,9 @@ These rules are the canonical source for low-code agent authoring. Capability fi
 
 ## Critical Rules (22)
 
-1. **Edit JSON files directly, except CLI-managed memory features** — the CLI supports `init` (scaffold), `validate` (read-only check), `migrate` (apply writes + regenerate `.agent-builder/`), and `memory` (writes memory feature files). Agent configuration (prompts, schemas, settings) is done by editing `agent.json` and `entry-points.json`. Resources (tools, contexts, escalations) are added as individual files in `resources/{ResourceName}/resource.json` inside the agent project directory — **not** inline in `agent.json`. Memory spaces are added with `uip agent memory` and live in `features/{FeatureName}/feature.json`. The root `agent.json` should not contain `resources` or manually-authored memory feature entries. The `migrate` command reads these files and generates `.agent-builder/agent.json` which inlines them.
+1. **Edit JSON files directly, except CLI-managed memory features** — the CLI supports `init` (scaffold), `refresh` (apply migrations + regenerate derived files), `validate` (strict read-only check), and `memory` (writes memory feature files). Agent configuration (prompts, schemas, settings) is done by editing `agent.json`. Resources (tools, contexts, escalations) are added as individual files in `resources/{ResourceName}/resource.json` inside the agent project directory — **not** inline in `agent.json`. Memory spaces are added with `uip agent memory` and live in `features/{FeatureName}/feature.json`. The root `agent.json` should not contain `resources` or manually-authored memory feature entries. The `refresh` command reads `agent.json` and these resource files to generate `entry-points.json` and `bindings_v2.json`.
 
-2. **Validate and migrate after every bulk of edits** — run `uip agent validate --output json` to check, then `uip agent migrate --output json` to write any pending migrations and regenerate `.agent-builder/`. Validate is read-only (never writes files); migrate applies writes only when all checks pass. Always run both in sequence after a cohesive set of related changes.
+2. **Refresh and validate after every bulk of edits** — run `uip agent refresh --output json` to apply pending migrations and regenerate derived files (`entry-points.json`, `bindings_v2.json`), then `uip agent validate --output json` to verify the project is clean. Refresh applies writes only when all checks pass; validate is strict read-only (never writes files, fails if migration is pending or derived files are out of sync). Always run both in sequence after a cohesive set of related changes.
 
 3. **Use `--output json`** on all `uip` commands when parsing output.
 
@@ -16,7 +16,7 @@ These rules are the canonical source for low-code agent authoring. Capability fi
 
 6. **Keep contentTokens in sync with content** — every message has both a `content` string and a `contentTokens` array. Update both when editing. See [agent-definition.md](agent-definition.md) § contentTokens Construction.
 
-7. **Do not manually create or edit `.agent-builder/`** — it is generated by `uip agent migrate` and managed by Studio Web. Never create or modify `.agent-builder/` files by hand.
+7. **Do not manually edit `entry-points.json` or `bindings_v2.json`** — they are generated by `uip agent refresh`. Edit `agent.json` and `resources/{Name}/resource.json`, then re-run refresh.
 
 8. **Do not publish or deploy without user consent** — ask before running `uip solution upload`, `uip solution publish`, or `uip solution deploy`.
 
@@ -24,13 +24,13 @@ These rules are the canonical source for low-code agent authoring. Capability fi
 
 10. **Solution must exist first** — create one with `uip solution init` before scaffolding an agent.
 
-11. **Set `folderPath` to the literal `Folder` returned by `uip solution resource list`.** Applies to both local (`Source: "Local"`) and external (`Source: "Remote"`) resources, and to tool `properties.folderPath`, context-index top-level `folderPath`, escalation `channel.properties.folderName`, and guardrail escalation `action.app.folderName`. Local resources typically carry `"solution_folder"` (their declared folder in the solution); external resources carry the human-readable, slash-separated Orchestrator folder (e.g., `"Shared"`, `"Shared/Sales/Region-EU"`). The author writes the value verbatim into `resource.json` (or into the guardrail action under `agent.json`); `uip agent migrate` propagates it into `bindings_v2.json` as `folderPath` (App resources translate `folderName` → binding `folderPath`). See [capabilities/process/process.md](capabilities/process/process.md) § Tool resource.json Shape.
+11. **Set `folderPath` to the literal `Folder` returned by `uip solution resources list`.** Applies to both local (`Source: "Local"`) and external (`Source: "Remote"`) resources, and to tool `properties.folderPath`, context-index top-level `folderPath`, escalation `channel.properties.folderName`, and guardrail escalation `action.app.folderName`. Local resources typically carry `"solution_folder"` (their declared folder in the solution); external resources carry the human-readable, slash-separated Orchestrator folder (e.g., `"Shared"`, `"Shared/Sales/Region-EU"`). The author writes the value verbatim into `resource.json` (or into the guardrail action under `agent.json`); `uip agent refresh` propagates it into `bindings_v2.json` as `folderPath` (App resources translate `folderName` → binding `folderPath`). See [capabilities/process/process.md](capabilities/process/process.md) § Tool resource.json Shape.
 
-12. **Tools carry a `location` field.** Use `"solution"` when the row from `uip solution resource 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.
+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 resource 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 `Skipped` or `Failed`), 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 (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).
 
-14. **Never manually edit `storageVersion`.** It is managed by `uip agent migrate` (which writes the latest version on success) and by Studio Web on import. `uip agent validate` reports `MigrationPending: true` if the file is behind, but does not write. If validate reports a `storageVersion` newer than supported, upgrade uipcli rather than editing the field by hand.
+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.
 
 15. **Inline agents in flows use `uipath.agent.autonomous` nodes.** The node's `inputs.source` references the inline agent's `projectId` UUID. Attached resource nodes (`uipath.agent.resource.tool.*`, `uipath.agent.resource.escalation`, `uipath.agent.resource.context.*`) use the same `inputs.source` convention to reference their `<RES_UUID>` subdirectory under `<projectId>/resources/`. The definition still declares `model.source: true`, but flow-core hoists the source identity onto `inputs.source` for the node instance; no node instance carries an instance `model` block. The agent definition lives in a subdirectory inside the flow project. See [capabilities/inline-in-flow/inline-in-flow.md](capabilities/inline-in-flow/inline-in-flow.md).
 
@@ -44,20 +44,20 @@ These rules are the canonical source for low-code agent authoring. Capability fi
 
 20. **Built-in tools require explicit configuration.** Tools like `analyze-attachments` are not implicitly available — add them as `resources/{Name}/resource.json` with `type: "internal"` and `properties.toolType: "<kebab-lowercase-id>"`. The `toolType` discriminator is fixed per tool — copy from the capability reference, do not invent. See [capabilities/built-in-tools/built-in-tools.md](capabilities/built-in-tools/built-in-tools.md).
 
-21. **Built-in tools need no solution-level files and no resource refresh.** Unlike external process tools, built-in tools (`type: "internal"`) are self-contained at the agent level. Do not run `uip solution resource refresh` for them; do not author solution-level resource files. Validate the agent and bundle.
+21. **Built-in tools need no solution-level files and no resource refresh.** Unlike external process tools, built-in tools (`type: "internal"`) are self-contained at the agent level. Do not run `uip solution resources refresh` for them; do not author solution-level resource files. Validate the agent and bundle.
 
-22. **Use `uip agent memory` for memory spaces and seed items.** The memory commands own `features/{FeatureName}/feature.json`, `.agent-builder/agent.json`, memory item type validation, and generated `memorySpace` bindings. Attach existing memory spaces by `--memory-space` plus literal `--folder-path`; seed items require `--memory-type episodic|escalation`, and episodic seed items require `--feedback-id`. Run `uip agent validate --output json`, `uip agent migrate --output json`, and then `uip solution resource refresh --output json` after memory changes in a solution. See [capabilities/memory/memory.md](capabilities/memory/memory.md).
+22. **Use `uip agent memory` for memory spaces and seed items.** The memory commands own `features/{FeatureName}/feature.json`, memory item type validation, and generated `memorySpace` bindings. Attach existing memory spaces by `--memory-space` plus literal `--folder-path`; seed items require `--memory-type episodic|escalation`, and episodic seed items require `--feedback-id`. Run `uip agent refresh --output json`, `uip agent validate --output json`, and then `uip solution resources refresh --output json` after memory changes in a solution. See [capabilities/memory/memory.md](capabilities/memory/memory.md).
 
 ## What NOT to Do (24)
 
-1. **Do not manually create or edit `.agent-builder/` files** — it is generated by `uip agent migrate` and managed by Studio Web. Never create or modify these files by hand.
+1. **Do not manually edit `entry-points.json` or `bindings_v2.json`** — they are generated by `uip agent refresh`. Edit source files (`agent.json`, `resources/{Name}/resource.json`) and re-run refresh.
 2. **Do not use `=js:` or `$vars` in agent messages** — use `{{input.fieldName}}` only
 3. **Do not skip schema sync** — agent.json and entry-points.json must match
 4. **Do not skip validation after a bulk of related edits** — validate after each cohesive set of changes (not after every line, but always before moving on to a new capability or publishing)
 5. **Do not publish/deploy without validating** — always validate first
 6. **Do not forget contentTokens** — editing `content` without updating `contentTokens` causes rendering issues
-7. **Do not forget `uip solution resource refresh` after adding a process tool** — applies to both local and external. Creating only the agent-level `resources/{ToolName}/resource.json` is not enough. After `uip agent migrate` generates `bindings_v2.json`, run `uip solution resource refresh` from the solution root to import the bindings into the solution. For `Connection` bindings refresh also generates `debug_overwrites.json`. For `Process`, `App`, and `Index` bindings refresh imports the resource but does not hand-write the rich solution-level files — check the output and hand-author missing files per [capabilities/process/solution-files.md](capabilities/process/solution-files.md).
-8. **`uip solution resource list` returns identity only (Source/Key/Name/Type/Folder/FolderKey)** — for the full configuration run `uip solution resource get <KEY> --output json` and read `Data.spec`. Applies to `--kind Process` (argument schemas, package keys, entry-point IDs — see [capabilities/process/process.md § Discovery](capabilities/process/process.md#discovery)) and `--kind Index` (data source type, storage bucket reference — see [capabilities/context/index.md § Discovery](capabilities/context/index.md#discovery)).
+7. **Do not forget `uip solution resources refresh` after adding a process tool** — applies to both local and external. Creating only the agent-level `resources/{ToolName}/resource.json` is not enough. After `uip agent refresh` generates `bindings_v2.json`, run `uip solution resources refresh` from the solution root to import the bindings into the solution. For `Connection` bindings refresh also generates `debug_overwrites.json`. For `Process`, `App`, and `Index` bindings refresh imports the resource but does not hand-write the rich solution-level files — check the output and hand-author missing files per [capabilities/process/solution-files.md](capabilities/process/solution-files.md).
+8. **`uip solution resources list` returns identity only (Source/Key/Name/Type/Folder/FolderKey)** — for the full configuration run `uip solution resources get <KEY> --output json` and read `Data.spec`. Applies to `--kind Process` (argument schemas, package keys, entry-point IDs — see [capabilities/process/process.md § Discovery](capabilities/process/process.md#discovery)) and `--kind Index` (data source type, storage bucket reference — see [capabilities/context/index.md § Discovery](capabilities/context/index.md#discovery)).
 9. **Do not copy-paste UUIDs from one resource to another** — every resource (including each guardrail) needs a unique UUID.
 10. **Do not bump `storageVersion` manually** — breaks packager compatibility.
 11. **Do not call raw Automation.Solutions REST APIs** — always use `uip solution` commands.
@@ -66,11 +66,11 @@ These rules are the canonical source for low-code agent authoring. Capability fi
 14. **Do not omit discriminator fields in guardrails** — every action needs `$actionType` (not `type`), every validator parameter needs `$parameterType` and `id` (not `name`), every custom rule needs `$ruleType`, every field selector needs `$selectorType`. Missing any discriminator causes `uip agent validate` to fail.
 15. **Do not use lowercase scope values in guardrails** — use `"Agent"`, `"Llm"`, `"Tool"` (PascalCase), not `"agent"`, `"llm"`, `"tool"`.
 16. **Always include `"guardrail": { "policies": [] }` in every tool resource.json, and never populate `policies` with entries** — the field must be present for backward-compatible solution loading; omitting it causes the runtime to fail. All guardrails are configured at the agent.json root `guardrails` array with `selector.scopes` and `selector.matchNames`.
-17. **Do not expect `uip solution resource refresh` to wire non-StorageBucket index data sources** — GoogleDrive/OneDrive/Dropbox/Confluence/Attachments indexes, `attachments` contexts, and `datafabricentityset` contexts are not auto-generated. Refresh warns + skips them; any solution-level files for these must be hand-authored. See [capabilities/context/index.md](capabilities/context/index.md).
+17. **Do not expect `uip solution resources refresh` to wire non-StorageBucket index data sources** — GoogleDrive/OneDrive/Dropbox/Confluence/Attachments indexes, `attachments` contexts, and `datafabricentityset` contexts are not auto-generated. Refresh warns + skips them; any solution-level files for these must be hand-authored. See [capabilities/context/index.md](capabilities/context/index.md).
 18. **Do not add a Tool-scoped guardrail before the tool exists** — run `uip agent tool list` first and confirm every name in `selector.matchNames` is present. `uip agent validate` will fail with an error if a guardrail targets a tool that has not been added to the agent.
-19. **Set `folderPath` on process tool resources to the literal `Folder` from `uip solution resource list`** — applies whether `Source` is `Local` or `Remote`. `uip agent validate` reads it from the agent-level `resource.json` during the schema check; `uip agent migrate` propagates it verbatim into `bindings_v2.json`. The same value goes into the matching solution-level process declaration's `folders[].fullyQualifiedName`.
-20. **Do not hand-edit `bindings_v2.json`** — the file is generated by `uip agent migrate` from the agent-level `resource.json` (including `folderPath`). Edit `resource.json` and re-run migrate; never patch the binding directly.
+19. **Set `folderPath` on process tool resources to the literal `Folder` from `uip solution resources list`** — applies whether `Source` is `Local` or `Remote`. `uip agent validate` reads it from the agent-level `resource.json` during the schema check; `uip agent refresh` propagates it verbatim into `bindings_v2.json`. The same value goes into the matching solution-level process declaration's `folders[].fullyQualifiedName`.
+20. **Do not hand-edit `bindings_v2.json`** — the file is generated by `uip agent refresh` from the agent-level `resource.json` (including `folderPath`). Edit `resource.json` and re-run refresh; never patch the binding directly.
 21. **Do not pass attachments via the `uip` CLI** — runtime file inputs are not supported by `uip agent run` or solution-level CLI run paths. Test attachment-aware agents from Studio Web or via Orchestrator job invocation.
 22. **Do not assume `{{input.<job-attachment>}}` lets the agent read the file** — it renders metadata only. Pair the file field with a file-handling built-in tool (e.g. `analyze-attachments`) so the agent has a way to read contents.
-23. **Do not run final inline-agent validation or migration before flow graph edits for inline-in-flow agents** — direct `.flow` authoring of the inline-agent node, capability-resource nodes, and edges is owned by the `uipath-maestro-flow` skill. Always run `uip agent validate --inline-in-flow` and then `uip agent migrate --inline-in-flow --bindings-target <FlowProjectDir>/bindings_v2.json` **after** those flow graph edits are complete. Migrate is what propagates the inline agent's bindings into the flow project's `bindings_v2.json`; without it, `uip solution resource refresh` cannot discover them. Never hand-edit `bindings_v2.json`. See [capabilities/inline-in-flow/inline-in-flow.md](capabilities/inline-in-flow/inline-in-flow.md).
-24. **Do not hand-edit memory feature files for routine changes** — use `uip agent memory add/list/remove` and `uip agent memory item add/list/remove`. Hand-writing `features/{Name}/feature.json`, `.agent-builder/agent.json`, or `bindings_v2.json` can desynchronize generated state and skip CLI validation for search mode, field weights, metadata JSON, and memory item type.
+23. **Do not run final inline-agent refresh or validation before flow graph edits for inline-in-flow agents** — direct `.flow` authoring of the inline-agent node, capability-resource nodes, and edges is owned by the `uipath-maestro-flow` skill. Always run `uip agent refresh --inline-in-flow --bindings-target <FlowProjectDir>/bindings_v2.json` and then `uip agent validate --inline-in-flow` **after** those flow graph edits are complete. Refresh is what propagates the inline agent's bindings into the flow project's `bindings_v2.json`; without it, `uip solution resources refresh` cannot discover them. Never hand-edit `bindings_v2.json`. See [capabilities/inline-in-flow/inline-in-flow.md](capabilities/inline-in-flow/inline-in-flow.md).
+24. **Do not hand-edit memory feature files for routine changes** — use `uip agent memory add/list/remove` and `uip agent memory item add/list/remove`. Hand-writing `features/{Name}/feature.json` or `bindings_v2.json` can desynchronize generated state and skip CLI validation for search mode, field weights, metadata JSON, and memory item type.

package/skills/uipath-agents/references/lowcode/debug.md

@@ -0,0 +1,55 @@
+# Debug a Low-Code Agent
+
+Run a low-code agent end-to-end on Studio Web and stream the result — without publishing it to Orchestrator. Use this to test an agent against real inputs during iteration. `uip agent debug` **uploads the agent's enclosing solution** to Studio Web, starts it on the serverless debug runtime, polls to completion, and returns the agent's output.
+
+## Pre-flight
+
+1. **Logged in.** `uip login status --output json` returns success.
+2. **Solution resources refreshed — only if the agent has solution-level bindings.** If it uses external process/IS tools, index contexts, memory spaces, or escalations, refresh first so those declarations stay in sync with its bindings. Agents with only built-in tools (or no resources) don't need this (see [critical-rules.md](critical-rules.md) Rule 21):
+
+   ```bash
+   uip solution resources refresh --solution-folder <SOLUTION_DIR> --output json
+   ```
+
+## Consent gate
+
+`uip agent debug` **executes the agent for real** — it calls its tools, escalations, and external APIs, and consumes model tokens. It also overwrites the agent's Studio Web solution. Per [critical-rules.md](critical-rules.md) Rule 8 (consent before upload/publish/deploy — debug uploads), confirm with the user before running it.
+
+## Debug — controlled end-to-end run
+
+```bash
+uip agent debug <AGENT_PROJECT_DIR> --inputs '<json>' --output json
+```
+
+The argument is the agent **project directory** (the folder with `agent.json` / `project.uiproj`), inside its solution. The command uploads the enclosing solution and runs it — there is **no separate `uip solution upload` step**.
+
+- `--inputs '<json>'` — the agent's input object, matching its `inputSchema` (e.g. `'{"input":"What is 2+2?"}'`). Omit for empty input.
+- `--timeout <seconds>` / `--poll-interval <ms>` — wait budget and polling cadence; the command polls until a terminal state.
+
+State changes (`Pending → Running → Successful`) stream to stderr while it waits.
+
+Every debug run re-uploads the local solution, so the debugged copy always reflects your local edits — there is no "debug the cloud version" mode (if you don't have it locally, `uip solution download` first).
+
+## Report the result
+
+On success the envelope is `Code: "AgentDebug"` with `Data`:
+
+| Field | Meaning |
+|---|---|
+| `State` | terminal job state (`Successful`) |
+| `Output` | the agent's output object |
+| `TraceId` | execution trace id — use to inspect the run |
+| `JobKey` | the debug job key |
+
+Show the user the `Output` and the `TraceId`.
+
+A run that ends `Faulted` / `Stopped` returns `Result: "Failure"` (exit 1). The terminal state alone often lacks a reason — inspect the trace:
+
+```bash
+uip traces spans get <TraceId> --output json
+```
+
+## Anti-patterns
+
+- **Never use `uip agent debug` as a validation step.** Use `uip agent validate` for correctness; debug is for end-to-end execution.
+- **Don't skip `uip solution resources refresh` before debug when the agent has solution-level bindings** (external tools, IS, indexes, memory spaces, escalations). Stale declarations cause runtime binding failures even when `agent.json` is correct. Agents with only built-in tools don't need it.

package/skills/uipath-agents/references/lowcode/evaluations/evaluate.md

@@ -20,7 +20,7 @@ uip agent eval run results <run_id> --set "Default Evaluation Set" --only-failed
 - Agent project initialized (`uip agent init <path>`)
 - `entry-points.json` present (defines `input`/`output` schema that test case `--inputs`/`--expected` must conform to)
 - `uip agent validate --output json` passes (validate also checks evals and evaluators)
-- Agent pushed to Studio Web (`uip agent push`) — required for running evals (the Agent Runtime executes test cases in the cloud)
+- Agent's solution uploaded to Studio Web (`uip solution upload`) — required for running evals (the Agent Runtime executes test cases in the cloud)
 
 Local operations (managing evaluators, eval sets, test cases) do **not** require authentication or a cloud connection. Only `uip agent eval run *` commands require cloud connectivity.
 
@@ -61,7 +61,7 @@ CLI-added evaluators are written as `evaluator-<uuid8>.json` (first 8 hex chars
 |--------|-------------------------------|------------------------------|
 | Execution | Local Python process | Cloud-based via Agent Runtime |
 | Auth required | Only for `--report` | Always (cloud execution) |
-| Prerequisite | `entry-points.json` | `uip agent push` |
+| Prerequisite | `entry-points.json` | `uip solution upload` |
 | Mocking | `@mockable()` decorator + declarative | Simulation instructions only |
 | CLI prefix | `uip codedagent eval` | `uip agent eval` |
 
@@ -69,7 +69,7 @@ CLI-added evaluators are written as `evaluator-<uuid8>.json` (first 8 hex chars
 
 | Error | Cause | Fix |
 |-------|-------|-----|
-| Solution ID could not be resolved | Agent not pushed to Studio Web | Run `uip agent push --output json`, or pass `--solution-id <id>` explicitly to `uip agent eval run start` |
+| Solution ID could not be resolved | Agent's solution not uploaded to Studio Web | Run `uip solution upload . --output json` (add `--force` to replace an existing cloud solution), or pass `--solution-id <id>` explicitly to `uip agent eval run start` |
 | `No evaluators found` | Empty `evals/evaluators/` directory | Run `uip agent eval evaluator add` or re-init with `uip agent init` |
 | `No test cases in eval set` | Eval set has no evaluations | Run `uip agent eval add` to add test cases |
 | `Unknown evaluator type "X"` | Wrong case on `--type` value | Use kebab-case only: `semantic-similarity`, `trajectory` |
@@ -79,12 +79,12 @@ CLI-added evaluators are written as `evaluator-<uuid8>.json` (first 8 hex chars
 | Eval run timeout (with `--wait`) | Agent taking too long or stuck | Increase `--timeout` or check agent health in Studio Web. Note: this only stops the local CLI from blocking; the run continues server-side — query with `uip agent eval run status <run_id>` |
 | Validate fails with eval errors | Eval set references an evaluator that no longer exists, OR evaluator JSON missing required field, OR `category`/`type` mismatch (see [evaluators.md](evaluators.md) § What `uip agent validate` Checks) | Re-run `uip agent eval evaluator list` and reconcile `evaluatorRefs`; fix per the validate error message |
 
-The two model-resolution errors above are **runtime checks in the cloud eval worker**, not validate-time checks — `uip agent validate` will not catch them. They surface only after `uip agent eval run start`. To pre-empt them, inspect each evaluator's `model` field locally before pushing.
+The two model-resolution errors above are **runtime checks in the cloud eval worker**, not validate-time checks — `uip agent validate` will not catch them. They surface only after `uip agent eval run start`. To pre-empt them, inspect each evaluator's `model` field locally before uploading.
 
 ## Anti-patterns
 
-- **Don't run `uip agent eval run start` before `uip agent push`.** The Agent Runtime executes against the pushed agent. Local edits to `agent.json` after the last push will not be reflected in the run.
-- **Don't skip `uip agent validate` before push.** Validate checks `evals/` and `evaluators/`; broken eval JSON will not block push but will surface as runtime errors.
+- **Don't run `uip agent eval run start` before `uip solution upload`.** The Agent Runtime executes against the uploaded agent. Local edits to `agent.json` after the last upload will not be reflected in the run.
+- **Don't skip `uip agent validate` before upload.** Validate checks `evals/` and `evaluators/`; broken eval JSON will not block upload but will surface as runtime errors.
 - **Don't hand-edit `id` or `evaluatorRefs` UUIDs.** Eval sets reference evaluators by UUID. Renaming an evaluator file or copy-pasting a UUID across evaluators silently breaks resolution.
 - **Don't expect filenames to match `<name>`.** CLI-generated evaluator files use `evaluator-<uuid8>.json`, not `<name>.json`. Look up evaluators by the `name` field inside the JSON, not by filename.
 - **Don't pass `--type` in PascalCase.** The CLI rejects `SemanticSimilarity`. Only kebab-case is accepted.

package/skills/uipath-agents/references/lowcode/evaluations/evaluation-sets.md

@@ -148,6 +148,6 @@ The `source` field indicates how the test case was created. CLI-added test cases
 ## Anti-patterns
 
 - **Don't hand-write `evalSetId` or test case `id` UUIDs.** Use `uip agent eval add` so the CLI keeps `evaluations[].evalSetId` consistent with the parent eval set's `id`.
-- **Don't add `--inputs` keys that are not in `entry-points.json`.** The runtime will reject the test case at execution time. Run `uip agent validate` to catch this before push.
+- **Don't add `--inputs` keys that are not in `entry-points.json`.** The runtime will reject the test case at execution time. Run `uip agent validate` to catch this before upload.
 - **Don't set `--expected '{}'` (empty) and `--expected-agent-behavior ""` together.** The semantic-similarity evaluator scores against an empty `{{ExpectedOutput}}`; the trajectory evaluator scores against an empty `{{ExpectedAgentBehavior}}`. Every run scores low for non-actionable reasons.
 - **Don't set the `source` field manually.** Owned by CLI and Studio Web; hand-edits may be overwritten on the next sync.

package/skills/uipath-agents/references/lowcode/evaluations/evaluators.md

@@ -17,7 +17,7 @@ How to add each type:
 
 - **Studio Web UI** — Evaluators tab → **Create New** → Add evaluator dialog → pick any of the four. UI is the canonical surface and supports all four with no special steps.
 - **CLI** — `uip agent eval evaluator add <name> --type <flag>` for `semantic-similarity` or `trajectory`. The CLI does not have a `--type` value for Exact match or JSON similarity; create those in the UI or hand-write the JSON.
-- **Hand-write JSON** — drop a file in `evals/evaluators/` matching the schema below; run `uip agent validate --output json` to confirm schema validity (then `uip agent migrate --output json` if validate reports `MigrationPending: true`); reference the new `id` from your eval set's `evaluatorRefs`. Useful when you want to pin a specific model and prompt for the LLM-based types, or when you're scaffolding eval files programmatically.
+- **Hand-write JSON** — drop a file in `evals/evaluators/` matching the schema below; run `uip agent refresh --output json` then `uip agent validate --output json` to confirm schema validity; reference the new `id` from your eval set's `evaluatorRefs`. Useful when you want to pin a specific model and prompt for the LLM-based types, or when you're scaffolding eval files programmatically.
 
 ### Why fewer than coded?
 
@@ -108,7 +108,7 @@ The CLI's `evaluator add --type semantic-similarity` writes a shorter prompt; ha
 }
 ```
 
-After hand-writing any evaluator, run `uip agent validate --output json` to confirm the file passes schema validation; if validate reports `MigrationPending: true`, run `uip agent migrate --output json` to apply it. Then reference the new evaluator's `id` from your eval set's `evaluatorRefs`. Watch for: `id` collisions with existing evaluators, missing required fields, and ISO-8601 formatting on the timestamps.
+After hand-writing any evaluator, run `uip agent refresh --output json` then `uip agent validate --output json` to confirm the file passes schema validation. Then reference the new evaluator's `id` from your eval set's `evaluatorRefs`. Watch for: `id` collisions with existing evaluators, missing required fields, and ISO-8601 formatting on the timestamps.
 
 ## Coded-only evaluators (NOT available on low-code)
 
@@ -261,7 +261,7 @@ These errors surface only after `uip agent eval run start` — `uip agent valida
 | `Evaluator '<id>' is an LLM-based evaluator but 'model' is not set in its evaluatorConfig. Specify a valid model name (e.g. 'claude-haiku-4-5-20251001').` | Evaluator JSON has empty/missing `model` (and is not `same-as-agent`). The worker fail-fasts before calling the LLM gateway. | Set `model` in the evaluator JSON to a model available in your tenant, or set `"model": "same-as-agent"` and ensure `agent.json` has a model. |
 | `'same-as-agent' model option requires agent settings. Ensure agent.json contains valid model settings.` | Evaluator uses `"same-as-agent"` but `agent.json` has no resolvable model. | Set `model` in `agent.json`, or override the evaluator with an explicit model. |
 
-**Pre-empt locally:** before push, run
+**Pre-empt locally:** before upload, run
 
 ```bash
 uip agent eval evaluator list --path ./my-agent --output json --output-filter '[?model==`""` || model==null]'

package/skills/uipath-agents/references/lowcode/evaluations/running-evaluations.md

@@ -2,7 +2,7 @@
 
 Execute evaluations against the Agent Runtime, check status, view results, and compare runs.
 
-All run commands require the agent to be pushed to Studio Web first (`uip agent push`). The Agent Runtime executes test cases in the cloud using the pushed agent definition.
+All run commands require the agent's solution to be uploaded to Studio Web first (`uip solution upload`). The Agent Runtime executes test cases in the cloud using the uploaded agent definition.
 
 ## Start an Eval Run
 
@@ -18,7 +18,7 @@ uip agent eval run start --set "<eval_set_name>" --path <agent_dir> --wait --out
 | `--path <path>` | No | Agent project directory | `.` |
 | `--wait` | No | Block until the run completes, then print results | `false` |
 | `--timeout <seconds>` | No | Maximum time to block when `--wait` is set | `600` (10 min) |
-| `--solution-id <id>` | No | Override solution ID for this run | Auto-resolved from the pushed-agent state |
+| `--solution-id <id>` | No | Override solution ID for this run | Auto-resolved from the uploaded solution state |
 
 Without `--wait`, the command returns immediately with `Code: AgentEvalRunStarted`:
 
@@ -174,8 +174,8 @@ uip agent eval add greeting-test \
 # 2. Validate (catches schema drift, missing evaluator refs, broken eval JSON)
 uip agent validate --path ./my-agent --output json
 
-# 3. Push agent to Studio Web (required before running evals)
-uip agent push --path ./my-agent --output json
+# 3. Upload the agent's solution to Studio Web (required before running evals)
+uip solution upload . --output json   # add --force to replace an existing cloud solution
 
 # 4. Run and wait
 uip agent eval run start \
@@ -189,9 +189,9 @@ uip agent eval run results <run_id> \
   --only-failed --verbose \
   --path ./my-agent --output json
 
-# 6. Make changes, validate, push, re-run, compare
+# 6. Make changes, validate, re-upload, re-run, compare
 uip agent validate --path ./my-agent --output json
-uip agent push --path ./my-agent --output json
+uip solution upload . --force --output json   # --force replaces the existing cloud solution in place
 uip agent eval run start --set "Default Evaluation Set" --path ./my-agent --wait --output json
 uip agent eval run compare <new_run_id> --compare-to <old_run_id> \
   --set "Default Evaluation Set" --path ./my-agent --output json
@@ -199,9 +199,9 @@ uip agent eval run compare <new_run_id> --compare-to <old_run_id> \
 
 ## Anti-patterns
 
-- **Don't run `eval run start` without `uip agent push` first.** The Agent Runtime executes against the pushed agent, not local files. Local edits made after the last push will not affect results.
+- **Don't run `eval run start` without `uip solution upload` first.** The Agent Runtime executes against the uploaded agent, not local files. Local edits made after the last upload will not affect results.
 - **Don't assume `--timeout` cancels the server-side run.** It only stops the local CLI from blocking. The run continues and can be inspected with `run status`.
-- **Don't skip `uip agent validate` between edits and push.** Validate catches eval-set / evaluator drift that push will accept silently and the runtime will reject.
+- **Don't skip `uip agent validate` between edits and upload.** Validate catches eval-set / evaluator drift that upload will accept silently and the runtime will reject.
 - **Don't compare runs from different eval sets.** `compare` aligns by test case `name` within the eval set; cross-set deltas are meaningless.
 - **Don't rely on `Score` alone — inspect `EvaluatorScores`.** A 0.86 aggregate can mask a faithful-but-wrong agent (high semantic, low trajectory). Use `--verbose` to read justifications when scores look surprising.
 - **Don't mix score scales across evaluators in the same eval set.** Defaults written by `uip agent init` use 0–100 prompts; defaults written by `evaluator add` use 0–1 prompts. The runtime DTO normalizes to 0–100, but mixed-scale prompts produce confusing per-evaluator scores. Decide on one scale per eval set and edit prompts to match.

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

@@ -6,22 +6,23 @@ Entry point for low-code agent work. Read this first after low-code mode is dete
 
 - Create a new low-code agent project (standalone or inline in a flow)
 - Edit `agent.json` — prompts, model, schemas, settings
-- Add tools, contexts, or escalations as files in `resources/{Name}/resource.json`
+- Add tools, contexts, escalations, or MCP servers as files in `resources/{Name}/resource.json`
 - Add memory spaces or seed memory items with `uip agent memory`
 - Wire agent-to-agent calls within a solution or to an external deployed agent
 - Design input/output schemas and sync with `entry-points.json`
 - Validate agent project structure
 - Publish agent to Studio Web, pack and deploy to Orchestrator
+- Debug / run a low-code agent end-to-end on Studio Web and inspect its output
 
 ## Critical Rules
 
 [critical-rules.md](critical-rules.md) is the canonical source for low-code agent rules and anti-patterns. Read it every session. The rules below are the operational must-knows; the rest live in the canonical file.
 
-1. **Edit JSON files directly, except CLI-managed memory features.** The CLI provides `init` (scaffold), `validate` (read-only check), `migrate` (apply writes + regenerate `.agent-builder/`), and `memory` (writes memory feature files). Resources live in `resources/{Name}/resource.json`; memory features live in `features/{Name}/feature.json`.
+1. **Edit JSON files directly, except CLI-managed memory features.** The CLI provides `init` (scaffold), `refresh` (apply migrations + regenerate derived files), `validate` (strict read-only check), and `memory` (writes memory feature files). Resources live in `resources/{Name}/resource.json`; memory features live in `features/{Name}/feature.json`.
 2. **Use `--output json`** on every `uip` command.
-3. **Validate and migrate after every bulk of related edits**, not after each line. Run `uip agent validate --output json` to check, then `uip agent migrate --output json` to apply pending migrations and regenerate `.agent-builder/`.
-4. **Keep `agent.json` ↔ `entry-points.json` schemas in sync.** `inputSchema`/`outputSchema` must mirror `input`/`output` field-for-field.
-5. **Never edit `.agent-builder/` by hand.** It is generated by `uip agent migrate` and managed by Studio Web.
+3. **Refresh and validate after every bulk of related edits**, not after each line. Run `uip agent refresh --output json` to apply pending migrations and regenerate `entry-points.json` and `bindings_v2.json`, then `uip agent validate --output json` to verify the project is clean.
+4. **Keep `agent.json` schemas correct** — `uip agent refresh` regenerates `entry-points.json` from `agent.json`'s `inputSchema`/`outputSchema` automatically.
+5. **Do not manually edit `entry-points.json` or `bindings_v2.json`** — they are generated by `uip agent refresh`. Edit source files and re-run refresh.
 6. **Do not publish or deploy without user consent.** Ask before `uip solution upload`, `publish`, or `deploy`.
 7. **Never invoke other skills automatically.** For Orchestrator setup, tell the user to use the `uipath-platform` skill; for flow wiring, tell them to use the `uipath-maestro-flow` skill.
 
@@ -32,10 +33,12 @@ Standard workflow for any low-code agent task:
 1. **Scaffold** — `uip solution init` (if no solution exists), then `uip agent init "<AgentName>" --output json`. Full walkthrough in [project-lifecycle.md](project-lifecycle.md) § End-to-End Example.
 2. **Edit** — open `agent.json` and `entry-points.json`. Schema reference in [agent-definition.md](agent-definition.md). **Override the scaffold model** (`gpt-4o-2024-11-20`) per [model-selection-guide.md](model-selection-guide.md) and write robust prompts per [agent-prompting-guide.md](agent-prompting-guide.md) — the scaffold ships a stale model and toy prompts.
 3. **Add capabilities** — pick from the Capability Registry below. Most add `resources/{Name}/resource.json`; memory uses `uip agent memory` and writes `features/{Name}/feature.json`.
-4. **Validate** — `uip agent validate --output json`. Confirm `MigrationPending`, `Validated`. Read-only — never writes.
-5. **Migrate** — `uip agent migrate --output json`. Applies pending writes and regenerates `.agent-builder/`. Confirm `MigrationApplied`, `StorageVersion`.
-6. **Refresh solution resources** — `uip solution resource refresh --output json` if any capability needs solution-level files (external tools, IS tools, index contexts, memory spaces, escalations).
-7. **Bundle and upload** — `uip solution bundle` then `uip solution upload --output json` (with user consent per Rule 6).
+4. **Refresh** — `uip agent refresh --output json`. Applies pending migrations and regenerates `entry-points.json` and `bindings_v2.json`. Confirm `MigrationApplied`, `StorageVersion`.
+5. **Validate** — `uip agent validate --output json`. Strict read-only. Confirm `Status: "Valid"`, `Validated` counts.
+6. **Refresh solution resources** — `uip solution resources refresh --output json` if any capability needs solution-level files (external tools, IS tools, index contexts, memory spaces, escalations).
+7. **Upload** — `uip solution upload . --output json` (bundles and uploads in one pass; with user consent per Rule 6).
+
+To **run the agent end-to-end** (test it live, not just upload), use `uip agent debug <AGENT_PROJECT_DIR> --inputs '<json>' --output json` — it uploads the enclosing solution and runs it on Studio Web in one step, so it's an alternative to the Upload step, not an addition. Executes the agent for real — confirm with the user first (Rule 6). See [debug.md](debug.md).
 
 Capabilities are **orthogonal**: there is no ordering requirement among them. Adding a tool and an escalation in parallel is safe — they do not interact at the file level. Validate and refresh once after all capability edits are complete, not after each one.
 
@@ -46,10 +49,11 @@ Capabilities are **orthogonal**: there is no ordering requirement among them. Ad
 | Read when... | File |
 |---|---|
 | Scaffolding, validating, or running solution lifecycle commands | [project-lifecycle.md](project-lifecycle.md) |
+| Debugging / running a low-code agent end-to-end to test it | [debug.md](debug.md) |
 | Editing `agent.json` (prompts, schemas, model, contentTokens) or `entry-points.json` | [agent-definition.md](agent-definition.md) |
 | Choosing the LLM (`settings.model`) — discover tenant models, override the scaffold default | [model-selection-guide.md](model-selection-guide.md) |
 | Writing a robust system/user prompt — skeleton, tool-call criteria, output contract, production checklist | [agent-prompting-guide.md](agent-prompting-guide.md) |
-| External tools / IS tools / index contexts / memory spaces / escalations behave unexpectedly after `uip solution resource refresh` | [solution-resources.md](solution-resources.md) |
+| External tools / IS tools / index contexts / memory spaces / escalations behave unexpectedly after `uip solution resources refresh` | [solution-resources.md](solution-resources.md) |
 | Running evaluations, adding test cases, managing evaluators | [evaluations/evaluate.md](evaluations/evaluate.md) |
 
 ### Capability Registry
@@ -62,11 +66,13 @@ Capabilities are **orthogonal**: there is no ordering requirement among them. Ad
 | Add/remove input or output fields | [agent-definition.md](agent-definition.md) § entry-points.json | |
 | Scaffold a new agent project | [project-lifecycle.md](project-lifecycle.md) § End-to-End Example | [agent-definition.md](agent-definition.md) |
 | Validate, upload, pack, publish, or deploy | [project-lifecycle.md](project-lifecycle.md) | |
+| Debug / run a low-code agent end-to-end | [debug.md](debug.md) | |
 | Discover solution resources (processes/apps/indexes/buckets/connections) | [project-lifecycle.md](project-lifecycle.md) § Resource Discovery | |
 | Add a tool — pick the right kind | [capabilities/process/process.md](capabilities/process/process.md) | applicable sibling |
 | Add a process tool (RPA / agent / API / agentic) — local or external | [capabilities/process/process.md](capabilities/process/process.md) | [capabilities/process/solution-files.md](capabilities/process/solution-files.md) |
 | Wire a multi-agent solution (parent + tool agents) | [capabilities/process/process.md](capabilities/process/process.md) § Multi-Agent Solution Example | |
 | Add an Integration Service tool | [capabilities/integration-service/integration-service.md](capabilities/integration-service/integration-service.md) | |
+| Add an MCP (Model Context Protocol) server tool | [capabilities/mcp/mcp.md](capabilities/mcp/mcp.md) | |
 | Add a built-in tool (Analyze Files) | [capabilities/built-in-tools/built-in-tools.md](capabilities/built-in-tools/built-in-tools.md) | [capabilities/built-in-tools/analyze-attachments.md](capabilities/built-in-tools/analyze-attachments.md) |
 | Accept a file as agent input or return a file as output | [agent-definition.md](agent-definition.md) § File Attachments | [capabilities/built-in-tools/built-in-tools.md](capabilities/built-in-tools/built-in-tools.md) |
 | Add a context (Context Grounding / attachments / DataFabric) | [capabilities/context/context.md](capabilities/context/context.md) | applicable sibling |
@@ -85,7 +91,7 @@ Capabilities are **orthogonal**: there is no ordering requirement among them. Ad
 See [critical-rules.md](critical-rules.md) § What NOT to Do for the canonical list. Most expensive to get wrong:
 
 - Editing `content` without updating `contentTokens` (causes silent rendering failures)
-- Skipping `uip solution resource refresh` after adding external tools (`bindings_v2.json` never reaches the solution)
+- Skipping `uip solution resources refresh` after adding external tools (`bindings_v2.json` never reaches the solution)
 - Hand-editing memory feature JSON instead of using `uip agent memory`
 - camelCasing `contextType` / `retrievalMode` enum values (validate accepts it, Studio Web silently drops the resource)
 - Copy-pasting UUIDs across resources (every resource needs its own)
@@ -96,6 +102,6 @@ After completing a task, report:
 
 1. **File paths** — which files were created or modified
 2. **What was configured** — summary of agent settings and schemas
-3. **Validation result** — output of `uip agent validate --output json` (`MigrationPending`, `Validated` counts) followed by `uip agent migrate --output json` (`MigrationApplied`, `StorageVersion`)
+3. **Validation result** — output of `uip agent refresh --output json` (`MigrationApplied`, `StorageVersion`) followed by `uip agent validate --output json` (`Status: "Valid"`, `Validated` counts)
 4. **Schema sync status** — confirm agent.json and entry-points.json match
 5. **Next steps** — suggest what the user should do next (publish, test in Studio Web, add resources)

package/skills/uipath-agents/references/lowcode/model-selection-guide.md

@@ -59,11 +59,11 @@ If `uip agent model list` fails (not logged in, offline, command unavailable), p
 
 ## 5. Apply the choice
 
-Edit `settings.model` (and `settings.maxTokens`) in `agent.json`, then validate and migrate:
+Edit `settings.model` (and `settings.maxTokens`) in `agent.json`, then refresh and validate:
 
 1. Set `settings.model` to the discovered `Name`.
 2. Set `settings.maxTokens` ≤ the model's `MaxTokens`.
-3. `uip agent validate --output json`
-4. `uip agent migrate --output json`
+3. `uip agent refresh --output json`
+4. `uip agent validate --output json`
 
 For inline-in-flow agents add `--inline-in-flow` to both commands. Full field reference: [agent-definition.md](agent-definition.md#change-model-settings).