@uipath/skills 1.195.0 → 1.196.0

package/skills/uipath-maestro-flow/references/author/references/plugins/http/impl.md

@@ -1,87 +1,85 @@
 # HTTP Request Node — Implementation
 
+This page is the entry point for implementing a managed HTTP node. Pick your auth mode below, then follow the matching walkthrough end-to-end. The "Shared Reference" section is an appendix — the mode walkthroughs already inline what you need to act, and link here only for full rationale and extended examples.
+
 ## Node Type
 
 `core.action.http.v2` (Managed HTTP Request)
 
 > **Always use `core.action.http.v2`** for all HTTP requests. The older `core.action.http` (v1) is deprecated.
 
-## Registry validation
+## Pick a Mode
 
-```bash
-uip maestro flow registry get core.action.http.v2 --output json
-```
+| Mode | Use when | Walkthrough |
+| --- | --- | --- |
+| **Connector** | Target system has an IS connector — auth via an existing IS connection (OAuth/API key) | [impl-connector.md](impl-connector.md) |
+| **Manual** | No connector exists, public/no-auth API, or quick prototyping | [impl-manual.md](impl-manual.md) |
 
-Confirm in `Data.Node.handleConfiguration`: target port `input`, source ports `branch-{item.id}` (dynamic, `repeat: inputs.branches`) and `default`. Also confirm `Data.Node.supportsErrorHandling: true` — HTTP v2 participates in the implicit `error` port pattern shared by every action node (see [Action Node Structure](../../../../shared/action-nodes.md)). Model `serviceType` is `Intsvc.UnifiedHttpRequest`.
+> **Mode fallback — auto-try, then confirm.** Prefer a curated connector activity first; if none, use connector mode; if connector mode cannot be configured (connector lacks HTTP request support — `HasHttpRequest` false — or no usable IS connection), fall through to manual mode automatically. Manual changes the auth model (you supply auth yourself), so confirm the switched mode with the user before finalizing. See [impl-connector.md — Step 2](impl-connector.md#step-2--identify-target-connection).
+
+The `--detail` payload differs in two places between modes: `authentication` (`"connector"` vs `"manual"`), and the connector-binding fields `targetConnector` / `connectionId` / `folderKey` (connector mode only; `url` is then relative to the connector base, vs. an absolute URL in manual mode). Everything else (node add, dynamic values, branches, edges, debug) is shared.
 
 ## Critical: Use `node configure`
 
 > **Do not hand-write `inputs.detail`, `bindings_v2.json`, or connection resource files.** Run `uip maestro flow node configure` — it builds everything from a simple `--detail` JSON. Hand-written configurations miss the `essentialConfiguration` block and fail at runtime. `core.action.http.v2` is CLI-owned per [Author capability — Node ownership](../../../CAPABILITY.md#node-ownership--who-authors-the-node) (same envelope rules as connector activities).
 
-## Configuration Workflow
+## Registry validation
 
-### Step 1 — Add the node
+```bash
+uip maestro flow registry get core.action.http.v2 --output json
+```
 
-Use `Edit` / `Write` to add the `core.action.http.v2` node directly to the `.flow` file. Follow [Edit/Write: Add a node](../../editing-operations-json.md#add-a-node): copy the registry definition into `definitions[]`, add the node instance to `nodes[]`, add `variables.nodes`, and add a placeholder `layout.nodes` entry. Save the node ID for Step 3.
+Confirm in `Data.Node.handleConfiguration`: target port `input`, source ports `branch-{item.id}` (dynamic, `repeat: inputs.branches`) and `default`. Also confirm `Data.Node.supportsErrorHandling: true` — HTTP v2 participates in the implicit `error` port pattern shared by every action node (see [Action Node Structure](../../../../shared/action-nodes.md)). Model `serviceType` is `Intsvc.UnifiedHttpRequest`.
 
-For the node instance shape, follow the [Action Node Structure — Standard JSON skeleton](../../../../shared/action-nodes.md#standard-json-skeleton) with `type: "core.action.http.v2"` and `typeVersion` set to the `version` field from the `registry get core.action.http.v2` response above (do not hardcode it — this node has advanced past `2.0`). Leave `inputs` empty at this stage — Step 3 populates `inputs.detail` via `uip maestro flow node configure`.
+---
 
-### Step 2 — Identify target connector and connection (connector mode only)
+## Shared Reference (appendix)
 
-Skip this step for manual mode.
+The mode walkthroughs link into the sections below for full rationale and extended examples. You do not need to read this section in order — jump directly from the walkthrough link that brought you here.
 
-Discovery call is **always**:
+### Add the node
 
 ```bash
-uip is connections list "<target-connector-key>" --all-folders --output json
+uip maestro flow node add <ProjectName>.flow core.action.http.v2 \
+  --label "<HTTP node label>" --output json
 ```
 
-`--all-folders` is mandatory. Without it the CLI returns the active folder only and hides connections in other folders the user can see. Plain `uip is connections list "<target-connector-key>"` is forbidden for discovery.
-
-> **MUST READ before any `uip is connections ...` call:** [/uipath:uipath-platform — connections.md](../../../../../../uipath-platform/references/integration-service/connections.md). Single source of truth for selection rules, empty-result recovery, ping verification.
-
-Record the chosen connection's `Id` and `FolderKey` for Step 3.
-
-> **HTTP-specific recovery — no usable connection.** If platform-skill recovery yields nothing (empty after `--all-folders` + `--refresh`, user declines to create one), the HTTP node has unique fallback options. **STOP** and use `AskUserQuestion`: **Create a new connection now** (`uip is connections create "<target-connector-key>"` starts the OAuth flow — user completes browser auth, then re-run list) / **Switch this node to manual mode** / **Skip this node** / **Something else**. Do not fall back to manual mode silently, do not invent a placeholder ID, do not skip the node without explicit user selection. See the AskUserQuestion dropdown rule in [SKILL.md](../../../../../SKILL.md).
+The CLI copies the manifest into `definitions[]`, adds the node instance to `nodes[]`, registers the `variables.nodes` entries, and inserts a placeholder in `layout.nodes` — all in code, byte-for-byte from the registry (including `typeVersion`, which the CLI pulls from the manifest's `version` field; do not hardcode it). Save the returned node ID — both walkthroughs reuse it.
 
-### Step 3 — Configure the node
+The CLI initializes `inputs` from the manifest's `inputDefaults`:
 
-> **Find missing values first.** Before composing `url` / `query` / `body`, resolve any values the agent doesn't have (IDs from names, required body fields, response shape, …). See [/uipath:uipath-platform — http-request.md](../../../../../../uipath-platform/references/integration-service/http-request.md).
-
-**Connector mode** (IS connection auth):
-
-```bash
-uip maestro flow node configure <ProjectName>.flow <nodeId> \
-  --detail '{
-    "authentication": "connector",
-    "targetConnector": "<target-connector-key>",
-    "connectionId": "<target-connection-id>",
-    "folderKey": "<folder-key>",
-    "method": "GET",
-    "url": "/api/endpoint",
-    "query": {"param1": "value1"}
-  }' --output json
+```json
+"inputs": {
+  "branches": [],
+  "timeout": "PT15M",
+  "retryCount": 0,
+  "swaggerDefinition": null,
+  "detail": {}
+}
 ```
 
-**Manual mode** (no connector auth):
+`inputs.detail` is populated by the configure step (next). The inputs-level siblings — `branches`, `timeout`, `retryCount` — are set at `node add` time via `--input`:
 
 ```bash
-uip maestro flow node configure <ProjectName>.flow <nodeId> \
-  --detail '{
-    "authentication": "manual",
-    "method": "GET",
-    "url": "https://api.example.com/endpoint",
-    "query": {"param1": "value1"}
+uip maestro flow node add <ProjectName>.flow core.action.http.v2 \
+  --label "<HTTP node label>" \
+  --input '{
+    "timeout": "PT30M",
+    "retryCount": 3,
+    "branches": [
+      { "id": "hasItems", "name": "Has Items", "conditionExpression": "$self.output.body.items.length > 0" },
+      { "id": "empty",    "name": "Empty",    "conditionExpression": "$self.output.body.items.length == 0" }
+    ]
   }' --output json
 ```
 
-**What the CLI handles automatically:**
+- `timeout` — ISO 8601 duration (e.g. `PT15M`, `PT1H`, `P1D`). Default `PT15M`.
+- `retryCount` — integer. Default `0`.
+- `branches` — see [Conditional branches](#conditional-branches) below.
 
-- Builds the full `inputs.detail` structure (connector, connectionId, bodyParameters, essentialConfiguration)
-- For connector mode: generates `bindings_v2.json` and creates a connection resource file under `resources/solution_folder/connection/`
-- For manual mode: uses `ImplicitConnection` (no bindings needed)
+> **Do not hand-author the `core.action.http.v2` definition, and do not `Edit` `inputs.*` after the fact.** Use `uip maestro flow node add` (with `--input` for branches/timeout/retryCount) and `uip maestro flow node configure` (for `inputs.detail`). These are the only supported authoring paths.
 
-### Step 3b — Dynamic values in URL / headers / body / query
+### Dynamic values in URL / headers / body / query
 
 **IS activity input fields do not resolve `{$vars.x}` brace-templates.** The flow runtime's `{...}` template interpolation only applies to native flow fields (end-node output `source`, variable updates, decision `expression`, script body, etc.) — **not** to fields under `inputs.detail.bodyParameters` on HTTP v2 or on any `uipath.connector.*` activity. Evidence: `"url": "https://.../user/{$vars.article}/..."` ships to the service as literal `{vars.article}` (the `$` is stripped, braces remain), producing a 400 Bad Request.
 
@@ -113,31 +111,34 @@ uip maestro flow node configure <Project>.flow <nodeId> \
   }' --output json
 ```
 
-### Step 4 — (Optional) Configure response branches for content-based routing
+### Conditional branches
 
-Skip this step unless you need to route downstream paths based on the *response content* (e.g., `items.length > 0` vs empty). Do **not** use `branches` just to handle call failures — for that, use the `error` port (Step 5).
+Skip this section unless you need to route downstream paths based on the *response content* (e.g., `items.length > 0` vs empty). Do **not** use `branches` just to handle call failures — for that, use the `error` port (see [Wire edges](#wire-edges)).
 
 Each branch entry creates a `branch-{id}` source port. `$self` refers to the current HTTP node's output inside the condition.
 
+Set `branches` at `node add` time via `--input` (see [Add the node](#add-the-node)) — `branches` lives at `inputs.branches`, not `inputs.detail.branches`, and `node configure --detail` does not accept it.
+
 ```bash
-uip maestro flow node configure <ProjectName>.flow <nodeId> \
-  --detail '{
+uip maestro flow node add <ProjectName>.flow core.action.http.v2 \
+  --label "<HTTP node label>" \
+  --input '{
     "branches": [
-      { "id": "hasItems",  "name": "Has Items",  "conditionExpression": "$self.output.body.items.length > 0" },
-      { "id": "empty",     "name": "Empty",      "conditionExpression": "$self.output.body.items.length == 0" }
+      { "id": "hasItems", "name": "Has Items", "conditionExpression": "$self.output.body.items.length > 0" },
+      { "id": "empty",    "name": "Empty",    "conditionExpression": "$self.output.body.items.length == 0" }
     ]
   }' --output json
 ```
 
 > **Do not prefix `conditionExpression` with `=js:`** — HTTP branch conditions are auto-evaluated as JS (same rule as decision/switch expressions).
 
-### Step 5 — Wire edges
+### Wire edges
 
 The managed HTTP node's target port is `input`. Its source ports are:
 
 - `default` — primary success output (or fallback when configured branches don't match)
 - `error` — fires when the HTTP call fails (network error, timeout, non-2xx not caught by a branch); wire this to an error handler to keep the flow from faulting
-- `branch-{id}` — one per entry in `inputs.branches` (Step 4); use the exact `id` you set
+- `branch-{id}` — one per entry in `inputs.branches` ([Conditional branches](#conditional-branches)); use the exact `id` you set
 
 Use `Edit` to add edge objects to `edges[]`; do not use `uip maestro flow edge add` for this structural wiring. Examples:
 
@@ -183,12 +184,13 @@ When an HTTP node has an outgoing `error` edge, the HTTP node instance must also
 }
 ```
 
-## Debug
+### Debug
 
 | Error | Cause | Fix |
 | --- | --- | --- |
 | `not_authed` or 401/403 | Wrong node type (v1 instead of v2), missing bindings, or expired connection | Verify node type is `core.action.http.v2`, check `bindings_v2.json` exists, ping the connection |
 | `configuration` field missing | Node not configured via CLI | Run `uip maestro flow node configure` — do not hand-write `inputs.detail` |
+| `flow validate` errors with `uiPathActivityTypeId` missing on `core.action.http.v2` | Node was hand-authored in `definitions[]` instead of via `uip maestro flow node add` | Remove the node, re-add it via `uip maestro flow node add <file> core.action.http.v2 ...`, then re-run `node configure`. |
 | Connection not found | Wrong connection ID or connector key | Re-run `uip is connections list` for the target connector |
 | Wrong API response | Incorrect `url` or `query` | Check the target service's API documentation |
 | `ImplicitConnection` errors | Manual mode misconfigured | Verify `authentication: "manual"` and `url` is a full URL |

package/skills/uipath-maestro-flow/references/author/references/plugins/http/planning.md

@@ -1,6 +1,6 @@
 # HTTP Request Node — Planning
 
-> **MUST READ FIRST:** [/uipath:uipath-platform — http-request.md](../../../../../../uipath-platform/references/integration-service/http-request.md). This file is the flow-specific authoring layer on top.
+> **MUST READ FIRST — confirm Managed HTTP Request fits your use case before authoring:** [/uipath:uipath-platform — http-request.md](../../../../../../uipath-platform/references/integration-service/http-request.md). This planning doc is the flow-specific layer on top of it.
 
 ## Node Type
 
@@ -12,9 +12,9 @@
 
 | Situation | Use Managed HTTP? |
 | --- | --- |
-| Connector exists but lacks the specific curated activity | Yes — connector mode with target connector's connection |
-| No connector exists, but service has a REST API | Yes — manual mode with full URL |
-| Quick prototyping against any REST API | Yes — manual mode |
+| Connector exists but lacks the specific curated activity | Yes — connector mode ([impl-connector.md](impl-connector.md)), **if the connector supports HTTP request activity** (verify `HasHttpRequest` — see [Prerequisites](#prerequisites)) |
+| No connector exists, but service has a REST API | Yes — manual mode ([impl-manual.md](impl-manual.md)) |
+| Quick prototyping against any REST API | Yes — manual mode ([impl-manual.md](impl-manual.md)) |
 | Connector exists and covers the use case | No — use [Connector Activity](../connector/planning.md) |
 | Target system has no API (desktop app) | No — use [RPA Workflow](../rpa/planning.md) |
 
@@ -58,7 +58,7 @@ Wire `branch-hasItems` / `branch-empty` as source ports on outgoing edges. `defa
 
 ## Dynamic values
 
-IS activity input fields (`url`, `headers`, `body`, `query` under `bodyParameters`) do **not** resolve `{$vars.x}` brace-templates — the template runner only applies to native flow fields. Use `=js:` expressions for any dynamic value; template literals with `${...}` interpolation or string concatenation both work. See [Step 3b — Dynamic values](impl.md#step-3b--dynamic-values-in-url--headers--body--query) for the full rationale and examples.
+IS activity input fields (`url`, `headers`, `body`, `query` under `bodyParameters`) do **not** resolve `{$vars.x}` brace-templates — the template runner only applies to native flow fields. Use `=js:` expressions for any dynamic value; template literals with `${...}` interpolation or string concatenation both work. See [Dynamic values](impl.md#dynamic-values-in-url--headers--body--query) for the full rationale and examples.
 
 ## Key Inputs (`--detail` for `node configure`)
 
@@ -76,7 +76,7 @@ Run `uip maestro flow node configure` with a `--detail` JSON. The CLI builds the
 | `url` | No | API endpoint URL/path (e.g., `"/conversations.replies"`). Auto-fills both `bodyParameters.path` and `bodyParameters.url`. |
 | `query` | No | Query parameters as key-value object |
 | `headers` | No | Additional headers as key-value object |
-| `body` | No | Request body (for POST/PUT/PATCH) |
+| `body` | No | Request body (for POST/PUT/PATCH). Connector mode is **`application/json` only** (request and response) — no other content type. |
 
 **Manual mode** (no connector auth):
 
@@ -92,7 +92,8 @@ Run `uip maestro flow node configure` with a `--detail` JSON. The CLI builds the
 ## Prerequisites
 
 - `uip login` required (for both modes — node type comes from registry)
-- For connector mode: a healthy IS connection must exist for the **target connector**. **If none exists, STOP** — surface in **Open Questions**. See [impl.md Step 2](impl.md#step-2--identify-target-connector-and-connection-connector-mode-only) for connection recovery.
+- For connector mode: connector must support the HTTP request activity — verify the `HasHttpRequest` flag via `uip is connectors get "<connector-key>"`. If false, fall back to manual mode — confirm the switch with the user before finalizing. See [impl-connector.md Step 2](impl-connector.md#step-2--identify-target-connection).
+- For connector mode: a healthy IS connection must exist for the **target connector**. If none exists, auto-fall-through to manual mode is the recommended fallback — but confirm the mode switch with the user before finalizing. See [impl-connector.md Step 2 — HTTP-specific recovery](impl-connector.md#step-2--identify-target-connection) for the user-confirmation flow (switch-to-manual / create-now / skip).
 - `uip maestro flow registry pull` to cache the `core.action.http.v2` definition
 
 ## Planning Annotation

package/skills/uipath-maestro-flow/references/author/references/plugins/inline-agent/impl.md

@@ -116,7 +116,7 @@ The system prompt here is a real one (bounded role, output contract, grounding,
 Some upstream nodes (notably connector triggers like email-received) only expose their full output shape after a real run — `subject`, `from`, `body` are not knowable from the registry definition alone. In that case:
 
 1. Write the prompt against your **best guess** of the upstream node's output paths based on the connector's documented output schema (e.g., `{{ $vars.emailReceived1.output.subject }}`).
-2. Surface the assumption to the user with `AskUserQuestion` — list the referenced paths and ask the user to correct any wrong fields before they run or upload the flow. Do not invent field names silently.
+2. Surface the assumption by asking the user — list the referenced paths and ask them to correct any wrong fields before they run or upload the flow. Do not invent field names silently.
 3. After the first real run, the author can verify the actual output paths and update the prompt tokens (and matching `contentTokens[].rawString` mirrors).
 
 ### Anti-patterns
@@ -277,24 +277,24 @@ Also add:
 
 After adding the tool node, you must also:
 
-- Hand-write the per-tool `resource.json` at `<FlowProjectDir>/<inlineAgentProjectId>/resources/<RES_UUID>/resource.json`. **Use the exact `resource.json` shape documented in the `uipath-agents` skill: `lowcode/capabilities/process/process.md` § Tool resource.json Shape.** Read that section before writing the file — it defines all required fields. The subtype is selected by the `type` field (`process` | `agent` | `api` | `processOrchestration`) — see § Subtypes in `process.md`. For RPA the schema uses raw .NET arrays (Template A in `solution-files.md`); for Agent / API / Process Orchestration it uses JSON Schema V2 (Template B). Run `uip solution resource list` + `uip solution resource get` to populate `referenceKey`, `folderPath`, `inputSchema`, and `outputSchema` with real values. Key inline-in-flow notes:
+- Hand-write the per-tool `resource.json` at `<FlowProjectDir>/<inlineAgentProjectId>/resources/<RES_UUID>/resource.json`. **Use the exact `resource.json` shape documented in the `uipath-agents` skill: `lowcode/capabilities/process/process.md` § Tool resource.json Shape.** Read that section before writing the file — it defines all required fields. The subtype is selected by the `type` field (`process` | `agent` | `api` | `processOrchestration`) — see § Subtypes in `process.md`. For RPA the schema uses raw .NET arrays (Template A in `solution-files.md`); for Agent / API / Process Orchestration it uses JSON Schema V2 (Template B). Run `uip solution resources list` + `uip solution resources get` to populate `referenceKey`, `folderPath`, `inputSchema`, and `outputSchema` with real values. Key inline-in-flow notes:
   - Set `id` to `<RES_UUID>` (same value used as the tool node's `inputs.source` and as the resource directory name).
   - Set `location` based on the discovery `Source` field: `"solution"` when `Source: "Local"`, `"external"` when `Source: "Remote"` (same rule as standalone agents).
   - Set `properties.folderPath` to the **literal folder path from discovery** (e.g., `"Shared/TestRPA"`) — do **not** leave it empty.
   - `inputSchema.properties` must include `"guardrails": { "type": "array" }` alongside the process arguments.
-  - A `resource.json` missing `$resourceType: "tool"` or other required fields will not be recognized by `uip agent validate` (it reports `"resources": 0`); the subsequent `uip agent migrate` will then write an empty `bindings_v2.json`.
+  - A `resource.json` missing `$resourceType: "tool"` or other required fields will not be recognized by `uip agent validate` (it reports `"resources": 0`); the subsequent `uip agent refresh` will then write an empty `bindings_v2.json`.
 - Set prompts in `agent.json` (system + user messages with `contentTokens` of `type: "simpleText"` and `rawString`)
-- Run `uip agent validate --inline-in-flow` after the flow graph edits to check the agent schema. Then run `uip agent migrate --inline-in-flow` to apply the migration and regenerate `.agent-builder/`; for tool-bearing inline agents, pass `--bindings-target <FlowProjectDir>/bindings_v2.json` on the migrate call to propagate tool bindings to the flow project level:
+- Run `uip agent refresh --inline-in-flow` after the flow graph edits to regenerate derived files (`entry-points.json`, `bindings_v2.json`); for tool-bearing inline agents, pass `--bindings-target <FlowProjectDir>/bindings_v2.json` on the refresh call to propagate tool bindings to the flow project level. Then run `uip agent validate --inline-in-flow` to check the agent schema:
 
   ```bash
-  uip agent validate "<FlowProjectDir>/<projectId>" --inline-in-flow --output json
-  uip agent migrate "<FlowProjectDir>/<projectId>" --inline-in-flow \
+  uip agent refresh "<FlowProjectDir>/<projectId>" --inline-in-flow \
     --bindings-target "<FlowProjectDir>/bindings_v2.json" --output json
+  uip agent validate "<FlowProjectDir>/<projectId>" --inline-in-flow --output json
   ```
 
-  Do not hand-edit `bindings_v2.json` — it is regenerated by `uip agent migrate`.
-  **Verify both validate and migrate report `"resources": N` where N > 0.** If either shows `"resources": 0`, the `resource.json` is malformed or missing required fields — fix it and re-run before proceeding.
-- Run `uip solution resource refresh` before upload
+  Do not hand-edit `bindings_v2.json` — it is regenerated by `uip agent refresh`.
+  **Verify both refresh and validate report `"resources": N` where N > 0.** If either shows `"resources": 0`, the `resource.json` is malformed or missing required fields — fix it and re-run before proceeding.
+- Run `uip solution resources refresh` before upload
 
 For agent.json prompt configuration and solution resource mechanics, see the `uipath-agents` skill (`lowcode/capabilities/inline-in-flow/inline-in-flow.md`).
 
@@ -352,21 +352,21 @@ return { classification: response };
 - `$vars.{nodeId}.output.content` — the agent's text response
 - `$vars.{nodeId}.error` — error details if the agent fails
 
-## Validate and Migrate
+## Refresh and Validate
 
-Validate the inline agent (read-only check), migrate it (writes `.agent-builder/` and, for tool-bearing agents, propagates bindings into the flow project's `bindings_v2.json`), then validate the flow:
+Refresh the inline agent (writes `entry-points.json` and `bindings_v2.json`, and for tool-bearing agents, propagates bindings into the flow project's `bindings_v2.json`), then validate (read-only check), then validate the flow:
 
 ```bash
-# 1. Validate the inline agent (read-only schema check)
-uip agent validate "<FlowProjectDir>/<projectId>" --inline-in-flow --output json
+# 1. Refresh the inline agent (writes entry-points.json and bindings_v2.json)
+uip agent refresh "<FlowProjectDir>/<projectId>" --inline-in-flow --output json
 
-# 2. Migrate the inline agent (writes .agent-builder/ and applies migrations)
-uip agent migrate "<FlowProjectDir>/<projectId>" --inline-in-flow --output json
-
-# 2b. For tool-bearing inline agents, migrate with --bindings-target to propagate tool bindings:
-uip agent migrate "<FlowProjectDir>/<projectId>" --inline-in-flow \
+# 1b. For tool-bearing inline agents, refresh with --bindings-target to propagate tool bindings:
+uip agent refresh "<FlowProjectDir>/<projectId>" --inline-in-flow \
   --bindings-target "<FlowProjectDir>/bindings_v2.json" --output json
 
+# 2. Validate the inline agent (read-only schema check)
+uip agent validate "<FlowProjectDir>/<projectId>" --inline-in-flow --output json
+
 # 3. Validate the flow
 uip maestro flow validate <FlowName>.flow --output json
 ```
@@ -381,10 +381,10 @@ uip maestro flow validate <FlowName>.flow --output json
 | `inputs.source` UUID does not match any subdirectory | Wrong source value, or folder renamed | Set `inputs.source` to the exact UUID of the inline agent directory |
 | Flow runs a different agent than expected | `inputs.source` points to a stale/leftover inline agent dir | Check subdirectory names — only one inline agent dir should correspond to each agent node |
 | `Orchestrator.StartAgentJob` error at runtime | Stale instance `model` fields override the inherited inline-agent definition | Remove the inline-agent node's instance `model` block and keep the registry definition's `model.serviceType: "Orchestrator.StartInlineAgentJob"` in `definitions[]` |
-| Studio Web reports "System prompt is required" | Inline agent's `agent.json.messages[]` has empty `content`, OR `.agent-builder/agent.json` is stale | Set prompts in `agent.json`, re-run `uip agent validate --inline-in-flow` to check, then `uip agent migrate --inline-in-flow` to regenerate `.agent-builder/agent.json` — see `uipath-agents` skill |
-| Studio Web debug: "Could not find process for tool" | Flow project's `bindings_v2.json` is missing the tool's process binding, so `uip solution resource refresh` never created the solution-level resource | Re-run `uip agent validate --inline-in-flow` to check schema, then `uip agent migrate --inline-in-flow --bindings-target <FlowProjectDir>/bindings_v2.json` to propagate bindings, then `uip solution resource refresh`, then re-upload |
-| `bindings_v2.json` is empty or missing tool bindings | Tool bindings were not propagated to the flow project level, or a later tool overwrote the file | Re-run `uip agent migrate --inline-in-flow --bindings-target <FlowProjectDir>/bindings_v2.json` after all flow node and edge edits are complete. Migrate is the verb that writes the file — do not hand-edit it |
-| Agent tool (process / agent / api / processOrchestration) cannot resolve at runtime | Missing top-level `bindings[]` entries, mismatched tool-node `inputs.source` / `resource.json` id, stale solution resources, or missing project-level `bindings_v2.json` | Add the resource bindings from the tool definition, keep the tool node's `inputs.source` equal to the resource UUID, run `uip agent validate --inline-in-flow` to check, then `uip agent migrate --inline-in-flow --bindings-target <FlowProjectDir>/bindings_v2.json` to write bindings, then run `uip solution resource refresh` |
+| Studio Web reports "System prompt is required" | Inline agent's `agent.json.messages[]` has empty `content`, OR derived files (`entry-points.json`, `bindings_v2.json`) are stale | Set prompts in `agent.json`, re-run `uip agent refresh --inline-in-flow` to regenerate derived files, then `uip agent validate --inline-in-flow` to check — see `uipath-agents` skill |
+| Studio Web debug: "Could not find process for tool" | Flow project's `bindings_v2.json` is missing the tool's process binding, so `uip solution resources refresh` never created the solution-level resource | Re-run `uip agent refresh --inline-in-flow --bindings-target <FlowProjectDir>/bindings_v2.json` to propagate bindings, then `uip agent validate --inline-in-flow` to check schema, then `uip solution resources refresh`, then re-upload |
+| `bindings_v2.json` is empty or missing tool bindings | Tool bindings were not propagated to the flow project level, or a later tool overwrote the file | Re-run `uip agent refresh --inline-in-flow --bindings-target <FlowProjectDir>/bindings_v2.json` after all flow node and edge edits are complete. Refresh is the verb that writes the file — do not hand-edit it |
+| Agent tool (process / agent / api / processOrchestration) cannot resolve at runtime | Missing top-level `bindings[]` entries, mismatched tool-node `inputs.source` / `resource.json` id, stale solution resources, or missing project-level `bindings_v2.json` | Add the resource bindings from the tool definition, keep the tool node's `inputs.source` equal to the resource UUID, run `uip agent refresh --inline-in-flow --bindings-target <FlowProjectDir>/bindings_v2.json` to write bindings, then `uip agent validate --inline-in-flow` to check, then run `uip solution resources refresh` |
 | `inputs.agentProjectId` unrecognized | Wrong field name | Use `inputs.source` — `agentProjectId` is not valid for inline agents |
 | Inline agent rejected by `uip agent validate` | `entry-points.json` or `project.uiproj` present inside the inline agent dir | Delete those files — they belong only to standalone agent projects |
 | Folder name is human-readable instead of UUID | Folder renamed after scaffolding | Rename to the original `projectId` UUID — the folder name must match `inputs.source` and the `projectId` field inside `agent.json` |
@@ -476,4 +476,4 @@ Current flow validation requires non-empty placeholder prompts on the flow node
 - **Do not create `entry-points.json` or `project.uiproj` inside the inline agent directory** — those belong only to standalone agent projects.
 - **Do not name the inline agent folder with a human-readable name** — the folder name must be the `projectId` UUID.
 - **Do not use `uip agent tool add`** for inline-in-flow agents — hand-author the tool's `resource.json` instead.
-- **Do not skip `uip agent validate --inline-in-flow` followed by `uip agent migrate --inline-in-flow`** after editing `agent.json` or any `resources/*/resource.json`; for tool-bearing inline agents, pass `--bindings-target <FlowProjectDir>/bindings_v2.json` on the migrate call to propagate tool bindings.
+- **Do not skip `uip agent refresh --inline-in-flow` followed by `uip agent validate --inline-in-flow`** after editing `agent.json` or any `resources/*/resource.json`; for tool-bearing inline agents, pass `--bindings-target <FlowProjectDir>/bindings_v2.json` on the refresh call to propagate tool bindings.

package/skills/uipath-maestro-flow/references/author/references/plugins/inline-agent/planning.md

@@ -88,11 +88,11 @@ Filter rows where `NodeType` starts with `<prefix>.` and `DisplayName` matches.
 uip maestro flow registry get "<NodeType>" --output json
 ```
 
-For the tool's `resource.json` format and solution-level resource setup, see the `uipath-agents` skill (`lowcode/capabilities/process/`). All four subtypes share discovery, `resource.json` shape, and refresh — only the `type` field and the schema flavor differ (see § Subtypes in `process.md`). Set `location` based on the discovery `Source` field: `"solution"` when `Source: "Local"`, `"external"` when `Source: "Remote"` (same rule as standalone agents — see `critical-rules.md` Rule 12). Set `properties.folderPath` to the **literal folder path from discovery** — parse it from the registry `Description` field (e.g., `(Shared/Sales)` → `"Shared/Sales"`) or from `uip solution resource get`. Do **not** leave `folderPath` empty — an empty `folderPath` prevents `uip solution resource refresh` from resolving the tool at runtime.
+For the tool's `resource.json` format and solution-level resource setup, see the `uipath-agents` skill (`lowcode/capabilities/process/`). All four subtypes share discovery, `resource.json` shape, and refresh — only the `type` field and the schema flavor differ (see § Subtypes in `process.md`). Set `location` based on the discovery `Source` field: `"solution"` when `Source: "Local"`, `"external"` when `Source: "Remote"` (same rule as standalone agents — see `critical-rules.md` Rule 12). Set `properties.folderPath` to the **literal folder path from discovery** — parse it from the registry `Description` field (e.g., `(Shared/Sales)` → `"Shared/Sales"`) or from `uip solution resources get`. Do **not** leave `folderPath` empty — an empty `folderPath` prevents `uip solution resources refresh` from resolving the tool at runtime.
 
 ### Anti-pattern
 
-Do not use `uip agent tool add` to attach the tool to an inline-in-flow agent. That command is designed for standalone agent projects. For inline-in-flow agents, hand-author the tool's `resource.json` and let `uip solution resource refresh` materialize the solution-level files.
+Do not use `uip agent tool add` to attach the tool to an inline-in-flow agent. That command is designed for standalone agent projects. For inline-in-flow agents, hand-author the tool's `resource.json` and let `uip solution resources refresh` materialize the solution-level files.
 
 ## Planning Annotation
 

package/skills/uipath-maestro-flow/references/diagnose/CAPABILITY.md

@@ -4,7 +4,7 @@ Capability index for postmortem on a failed `flow debug` or deployed process run
 
 > **Where you came from / where to go next.** Diagnose is downstream of Operate (run faulted → diagnose) and points back to Author for the underlying fix (diagnose → re-author → re-ship). Re-running and lifecycle live in [operate/CAPABILITY.md](../operate/CAPABILITY.md); building/editing the `.flow` file lives in [author/CAPABILITY.md](../author/CAPABILITY.md).
 >
-> **Inherits universal rules from [SKILL.md](../../SKILL.md)** — `--output json` + prefer `--output-filter` for extraction, no `flow debug` without consent, never invoke other skills automatically, AskUserQuestion dropdown pattern, **plain-English narration + granular `TodoWrite` (opt-in — silent by default; engage when the user asks for verbosity)**. The rules below are diagnose-scoped and apply on top.
+> **Inherits universal rules from [SKILL.md](../../SKILL.md)** — `--output json` + prefer `--output-filter` for extraction, no `flow debug` without consent, never invoke other skills automatically, dropdown question pattern, **plain-English narration + granular progress list (opt-in — silent by default; engage when the user asks for verbosity)**. The rules below are diagnose-scoped and apply on top.
 
 ## When to use this capability
 

package/skills/uipath-maestro-flow/references/diagnose/references/failure-modes.md

@@ -10,7 +10,7 @@ Lookup table for known recurring failure modes in Maestro Flow projects. Each en
 |---|---|---|
 | [MST-9107](#mst-9107--js-prefix-missing) | Activity input bound to literal string `"vars.X.output.Y"` | Missing `=js:` prefix on a `$vars` reference. `flow validate` catches this — pre-`expression-prefix-validator` cli still ships the literal at runtime. |
 | [MST-9972](#mst-9972--variablesnodes-missing-vars-resolves-to-undefined) | `Cannot read property 'output' of undefined` on a downstream node | Direct-authored `.flow` skipped `variables.nodes[]`; `flow validate` accepts it but the BPMN has no process-level variable declaration for the upstream node. |
-| [MST-9061](#mst-9061--misshapen-rectangle-nodes-in-studio-web) | Nodes render as oblong rectangles, not squares | `flow format` not run before publish |
+| [MST-9061](#mst-9061--misshapen-rectangle-nodes-in-studio-web) | Nodes render at the wrong size for their shape | `flow format` not run before publish |
 | [HITL `completed` port unwired](#hitl-completed-port-unwired) | Flow hangs indefinitely after a HITL node | No outgoing edge from the node's `completed` source port |
 | [Reused reference ID](#reused-reference-id--cross-connection-id-leakage) | Connector node faults silently at runtime | Reference ID copied from a prior flow's connection |
 | [Single-nested layout](#single-nested-layout) | Studio Web upload fails; `flow init` auto-registration is skipped | `uip maestro flow init` was run outside a solution directory |
@@ -99,11 +99,11 @@ One entry per declared output (trigger nodes: `output` only; action nodes: `outp
 
 ### Symptom
 
-After publish or debug upload, Studio Web renders nodes as oblong rectangles (e.g., 200×80) instead of square tiles. Layout looks visually broken even though the flow runs correctly.
+After publish or debug upload, Studio Web renders nodes at the wrong dimensions for their shape — a square/circle node stretched into an oblong (e.g., 200×80), or an inline agent squashed to a 96×96 square instead of its 288×96 rectangle. Layout looks visually broken even though the flow runs correctly.
 
 ### Cause
 
-`uip maestro flow format` was not run before publishing or debugging. Hand-written or stale `layout` data with non-96 dimensions remains in the `.flow` file and Studio Web renders it as-is.
+`uip maestro flow format` was not run before publishing or debugging. Hand-written or stale `layout` data with dimensions that don't match each node's shape remains in the `.flow` file and Studio Web renders it as-is.
 
 ### Fix
 
@@ -115,7 +115,7 @@ uip maestro flow format <ProjectName>.flow --output json
 
 Format:
 
-- Sets every non-`stickyNote` node's `size` to `{ "width": 96, "height": 96 }`
+- Sets each node's `size` by its canvas shape (inline agents → 288×96, containers → 560×320, everything else → 96×96)
 - Arranges nodes horizontally with ELK at `nodeSpacing: 96`
 - Recurses into subflows and rewrites `subflows[<id>].layout`
 - Preserves sticky note custom sizes
@@ -181,7 +181,7 @@ uip is resources run list <connector-key> <objectName> --connection-id <CURRENT_
 
 ### Symptom
 
-`uip solution upload` rejects the project. `flow init` returned without a `Data.SolutionRegistration` block (auto-registration walks up looking for the nearest `.uipx`; when the project is created outside the solution, it finds none and skips silently). Studio Web upload fails with structural errors. Packaging fails.
+`uip solution upload` rejects the project. `flow init` returned `Data.SolutionRegistration.Status: "NotInSolution"` (auto-registration walks up looking for the nearest `.uipx`; when the project is created outside the solution, it finds none, so the project was created standalone). Studio Web upload fails with structural errors. Packaging fails.
 
 The `.flow` file lives at `<Project>/<Project>.flow` (single-nested) instead of the required `<Solution>/<Project>/<Project>.flow` (double-nested).
 
@@ -198,7 +198,7 @@ uip solution init "<SolutionName>" --output json
 cd <SolutionName>
 uip maestro flow init <ProjectName> --output json
 # Confirm Data.SolutionRegistration.Status is "Registered" in the JSON response.
-# Only if Status is "Skipped" / "Failed" do you need:
+# Only if Status is "NotInSolution" / "Skipped" / "Failed" do you need:
 #   uip solution project add <SolutionName>/<ProjectName> <SolutionName>/<SolutionName>.uipx
 ```
 

package/skills/uipath-maestro-flow/references/evaluate/CAPABILITY.md

@@ -4,7 +4,7 @@ Capability index for `uip maestro flow eval` — evaluator CRUD (7 types), eval
 
 > **Where you came from / where to go next.** Evaluate is downstream of Operate (ship the flow → evaluate it on Studio Web) and feeds back into Author (failing eval → fix the `.flow` → re-ship → re-evaluate). Build/edit lives in [author/CAPABILITY.md](../author/CAPABILITY.md); publish/deploy lives in [operate/CAPABILITY.md](../operate/CAPABILITY.md); fault triage on a debug or process run lives in [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md).
 >
-> **Inherits universal rules from [SKILL.md](../../SKILL.md)** — `--output json` + prefer `--output-filter` for extraction, no `flow debug` without consent, never invoke other skills automatically, AskUserQuestion dropdown pattern, **plain-English narration + granular `TodoWrite` (opt-in — silent by default; engage when the user asks for verbosity)**. The rules below are evaluate-scoped and apply on top.
+> **Inherits universal rules from [SKILL.md](../../SKILL.md)** — `--output json` + prefer `--output-filter` for extraction, no `flow debug` without consent, never invoke other skills automatically, dropdown question pattern, **plain-English narration + granular progress list (opt-in — silent by default; engage when the user asks for verbosity)**. The rules below are evaluate-scoped and apply on top.
 
 ## When to use this capability
 
@@ -20,7 +20,7 @@ For agent (`agent.json`) evaluations read the `uipath-agents` skill. For BPMN ev
 ## Critical rules
 
 1. **Check Flow eval CLI availability once.** Run `uip maestro flow eval --help --output json` before using eval commands. If it returns `unknown command 'eval'`, the installed CLI does not expose Flow eval yet. Stop, report that the user needs a CLI/tool version with Flow eval support, and do not spend turns searching npm packages or source bundles.
-2. **Never run `uip solution upload` automatically as part of an eval workflow.** The eval run requires the Flow solution to already exist in Studio Web, but uploading from the local working tree clobbers whatever is on Studio Web. If the project was pulled from Studio Web (`uip agent pull`), edited locally in VS Code, or scaffolded on disk and never uploaded, an unprompted upload will overwrite or push unintended state. Ask the user explicitly before any `uip solution upload` — see [upload-safety.md](references/upload-safety.md).
+2. **Never run `uip solution upload` automatically as part of an eval workflow.** The eval run requires the Flow solution to already exist in Studio Web, but uploading from the local working tree clobbers whatever is on Studio Web. If the project was pulled from Studio Web (`uip solution download`), edited locally in VS Code, or scaffolded on disk and never uploaded, an unprompted upload will overwrite or push unintended state. Ask the user explicitly before any `uip solution upload` — see [upload-safety.md](references/upload-safety.md).
 3. **`--path` accepts a Flow project directory OR a solution directory containing exactly one Flow project.** If the solution holds multiple Flow projects, point `--path` at the specific project directory.
 4. **Local CRUD does not require login.** `add`, `remove`, `list` (data points / eval sets / evaluators) edit JSON on disk. Only `uip maestro flow eval run *` requires `uip login` and an existing Studio Web solution.
 5. **Pin a model on every LLM-judge evaluator.** Empty/missing `model` produces a cryptic 500 from the LLM gateway after retries. Pass `--model <name>` on `evaluator add` or set `model` in the JSON.

package/skills/uipath-maestro-flow/references/evaluate/references/upload-safety.md

@@ -9,7 +9,7 @@ The eval run requires the Flow solution to exist in Studio Web. The temptation,
 This applies regardless of whether:
 
 - The local project was created via `uip maestro flow init` and never uploaded.
-- The local project was downloaded from Studio Web via `uip agent pull` and edited locally.
+- The local project was downloaded from Studio Web via `uip solution download` and edited locally.
 - The user is working in a VS Code-authored solution / personal workspace and the project may not match what is on Studio Web.
 - The CLI errors with `solution-id could not be resolved` or any variant.
 

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

@@ -1,10 +1,10 @@
 # Operate — Ship, run, and manage deployed flows
 
-Capability index for the lifecycle of a flow as a deployed asset. Operate owns everything that touches the cloud — `solution resource refresh`, Studio Web upload, Orchestrator deploy, `flow debug`, `process run`, `job status/traces`, and `instance` lifecycle (pause, resume, cancel, retry). Requires `uip login`.
+Capability index for the lifecycle of a flow as a deployed asset. Operate owns everything that touches the cloud — `solution resources refresh`, Studio Web upload, Orchestrator deploy, `flow debug`, `process run`, `job status/traces`, and `instance` lifecycle (pause, resume, cancel, retry). Requires `uip login`.
 
 > **Where you came from / where to go next.** Operate is downstream of Author (build the flow → ship it) and upstream of Diagnose (run faults → diagnose). Build/edit lives in [author/CAPABILITY.md](../author/CAPABILITY.md); fault triage lives in [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md).
 >
-> **Inherits universal rules from [SKILL.md](../../SKILL.md)** — `--output json` + prefer `--output-filter` for extraction, no `flow debug` without consent, never invoke other skills automatically, AskUserQuestion dropdown pattern, solution layout, **plain-English narration + granular `TodoWrite` (opt-in — silent by default; engage when the user asks for verbosity)**. The rules below are operate-scoped and apply on top.
+> **Inherits universal rules from [SKILL.md](../../SKILL.md)** — `--output json` + prefer `--output-filter` for extraction, no `flow debug` without consent, never invoke other skills automatically, dropdown question pattern, solution layout, **plain-English narration + granular progress list (opt-in — silent by default; engage when the user asks for verbosity)**. The rules below are operate-scoped and apply on top.
 
 ## When to use this capability
 
@@ -14,12 +14,12 @@ Capability index for the lifecycle of a flow as a deployed asset. Operate owns e
 - Trigger a deployed process via `uip maestro flow process run`
 - Check job status or stream traces with `uip maestro flow job status` / `job traces`
 - Manage a running instance — pause, resume, cancel, or retry
-- Refresh solution resources after binding changes (`uip solution resource refresh`)
+- Refresh solution resources after binding changes (`uip solution resources refresh`)
 
 ## Critical rules
 
-1. **Always run `uip solution resource refresh <SolutionDir>` before `solution upload` or `flow debug`.** Stale resource declarations cause runtime binding failures even when the local `.flow` is correct. The refresh syncs connection and process resource declarations from the project's `bindings_v2.json` files into the solution.
-2. **Default to Studio Web when the user says "publish" without specifier.** "Publish" → `uip solution upload <SolutionDir>`. Only run `uip maestro flow pack` + `uip solution publish` when the user explicitly asks to deploy to Orchestrator. The Orchestrator path bypasses Studio Web — the user cannot visualize or edit the flow there.
+1. **Always run `uip solution resources refresh --solution-folder <SolutionDir>` before `solution upload` or `flow debug`.** Stale resource declarations cause runtime binding failures even when the local `.flow` is correct. The refresh syncs connection and process resource declarations from the project's `bindings_v2.json` files into the solution. `refresh` has no positional solution argument; omit `--solution-folder` only when the current directory is already the solution root.
+2. **Default to Studio Web when the user says "publish" without specifier.** "Publish" → `uip solution upload <SolutionDir>`. Only run `uip maestro flow pack` + `uip solution publish` when the user explicitly asks to deploy to Orchestrator. Pass the exact solution root path (the directory containing the `.uipx` file), or `.` when already in that directory; do not pass the solution name while the shell is inside a nested project folder. The Orchestrator path bypasses Studio Web — the user cannot visualize or edit the flow there.
 3. **Always include `--folder-key <FOLDER_KEY>` (`-f` shorthand) on `instance` commands.** Without it the command rejects the request before reaching the API. Get the folder key from `uip or folders list --output json` or from the job/process context. See [shared/cli-conventions.md](../shared/cli-conventions.md#6---folder-key-requirement).
 4. **Always report Studio Web URL and Instance ID as the first two lines of any debug summary.** Parse `Data.studioWebUrl` and `Data.instanceId` from the JSON output. Use `<not returned by CLI>` if missing — never omit the line. Users need these immediately, not buried below status text.
 
@@ -37,7 +37,7 @@ Capability index for the lifecycle of a flow as a deployed asset. Operate owns e
 | --- | --- |
 | **Publish a flow to Studio Web** | [ship.md — Path 1](references/ship.md#path-1--studio-web-upload-default) |
 | **Deploy a flow to Orchestrator** (only if explicitly requested) | [ship.md — Path 2](references/ship.md#path-2--orchestrator-deploy-explicit-only) + [/uipath:uipath-solution](/uipath:uipath-solution) |
-| **Sync solution resource declarations** | [ship.md — Pre-flight](references/ship.md#pre-flight) (the `uip solution resource refresh` step) |
+| **Sync solution resource declarations** | [ship.md — Pre-flight](references/ship.md#pre-flight) (the `uip solution resources refresh` step) |
 | **Debug a flow end-to-end** | [run.md — Debug](references/run.md#debug--controlled-end-to-end-run) |
 | **Pass input arguments to `flow debug`** | [run.md — Debug](references/run.md#debug--controlled-end-to-end-run) (the `--inputs` flag) |
 | **Bind local files to file-typed inputs** | [run.md — Debug](references/run.md#debug--controlled-end-to-end-run) and [run.md — Process run](references/run.md#process-run--trigger-a-deployed-process) (same `--attachment <variableId>=<localPath>` flag on both, repeatable; `--attachment` overrides `--inputs` on key collisions) |
@@ -53,7 +53,7 @@ Capability index for the lifecycle of a flow as a deployed asset. Operate owns e
 
 ## Anti-patterns
 
-- **Never run `solution upload` without `solution resource refresh` first.** Stale resource declarations cause runtime binding failures.
+- **Never run `solution upload` without `solution resources refresh` first.** Stale resource declarations cause runtime binding failures.
 - **Never default to Orchestrator deploy when the user said "publish".** "Publish" → Studio Web upload. Confirm explicitly before running `flow pack` + `solution publish`.
 - **Never run `flow debug` as a validation step.** Use `uip maestro flow validate` for correctness checking; debug is for end-to-end execution against real systems.
 - **Never `retry` a faulted instance without diagnosing the root cause first.** Triage via [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) — read incidents, runtime variables, and the deployed asset. Then decide whether to retry, cancel, or re-author.
@@ -69,7 +69,7 @@ Capability index for the lifecycle of a flow as a deployed asset. Operate owns e
 
 ### Cross-capability (shared)
 
-- [shared/cli-commands.md](../shared/cli-commands.md) — flat CLI lookup including `solution upload`, `solution resource refresh`, `flow pack`, `flow debug`, `flow process`, `flow job`, `flow instance`
+- [shared/cli-commands.md](../shared/cli-commands.md) — flat CLI lookup including `solution upload`, `solution resources refresh`, `flow pack`, `flow debug`, `flow process`, `flow job`, `flow instance`
 - [shared/cli-conventions.md](../shared/cli-conventions.md) — login states, FOLDER_KEY, UIPCLI_LOG_LEVEL, JSON output shape
 - [shared/variables-and-expressions.md](../shared/variables-and-expressions.md) — `--inputs` JSON shape for `flow debug`
 

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

@@ -8,7 +8,7 @@ Execute a flow on demand and monitor progress. Three modes: **debug** (controlle
 2. **For debug runs: solution resources refreshed.** Always run before `flow debug` so connection and process resource declarations are in sync with project bindings:
 
    ```bash
-   uip solution resource refresh <SolutionDir> --output json
+   uip solution resources refresh --solution-folder <SolutionDir> --output json
    ```
 
 ## Debug — controlled end-to-end run
@@ -95,5 +95,5 @@ uip maestro flow job traces <job-key> --output json   # stream the verbose execu
 ## Anti-patterns
 
 - **Never run `flow debug` as a validation step.** Use `uip maestro flow validate` for correctness checking; debug is for end-to-end execution.
-- **Never skip `solution resource refresh` before debug.** Stale resource declarations cause runtime binding failures even when the local `.flow` is correct.
+- **Never skip `solution resources refresh` before debug.** Stale resource declarations cause runtime binding failures even when the local `.flow` is correct.
 - **Never start diagnosis from `job traces`.** Traces are last-resort — see [diagnose/CAPABILITY.md](../../diagnose/CAPABILITY.md) for the priority ladder.

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

@@ -13,20 +13,20 @@ Before either publish path, ensure:
 3. **Solution resources are refreshed.** Always run this before `solution upload` or `solution publish` so that connection and process resource declarations are in sync with the project bindings:
 
    ```bash
-   uip solution resource refresh <SolutionDir> --output json
+   uip solution resources refresh --solution-folder <SolutionDir> --output json
    ```
 
-   The argument is the solution directory (containing the `.uipx` file). Defaults to the current directory if omitted.
+   `<SolutionDir>` is the solution directory (containing the `.uipx` file). The command has no positional solution argument; omit `--solution-folder` only when the current directory is already the solution root.
 
 ## Path 1 — Studio Web upload (default)
 
-After `solution resource refresh`, upload the solution to Studio Web:
+After `solution resources refresh`, upload the solution to Studio Web:
 
 ```bash
 uip solution upload <SolutionDir> --output json
 ```
 
-`uip solution upload` accepts the solution directory directly — no intermediate bundling step required. If the project was created with `uip maestro flow init`, it already lives inside a solution directory. The command pushes it to Studio Web where the user can visualize, inspect, edit, and publish from the browser.
+`uip solution upload` accepts the solution directory directly — no intermediate bundling step required. Use the exact solution root path (or `.` from inside the solution root). If your shell is inside the nested flow project folder, pass the absolute solution root path or `..`; do not pass the solution name again, because that resolves to a child path that does not exist. If the project was created with `uip maestro flow init`, it already lives inside a solution directory. The command pushes it to Studio Web where the user can visualize, inspect, edit, and publish from the browser.
 
 **Share the Studio Web URL with the user** when the upload succeeds.
 
@@ -38,7 +38,7 @@ Pack the flow project into a `.nupkg` then publish via the platform skill:
 
 ```bash
 # 1. Refresh solution resources
-uip solution resource refresh <SolutionDir> --output json
+uip solution resources refresh --solution-folder <SolutionDir> --output json
 
 # 2. Pack
 uip maestro flow pack <project-path> <OutputDir>
@@ -48,8 +48,8 @@ For `uip solution publish` and the rest of the deployment workflow, see [/uipath
 
 ## Anti-patterns
 
-- **Never run `solution upload` without `solution resource refresh` first.** Stale resource declarations cause runtime binding failures (the deployed flow can't find its connections).
-- **Never default to Orchestrator deploy when the user said "publish".** "Publish" without specifier means Studio Web. When the target is ambiguous, confirm via `AskUserQuestion` with **Studio Web upload** / **Orchestrator deploy** / **Something else** as options before running `flow pack` + `solution publish`. See the AskUserQuestion dropdown rule in [SKILL.md](../../../SKILL.md).
+- **Never run `solution upload` without `solution resources refresh` first.** Stale resource declarations cause runtime binding failures (the deployed flow can't find its connections).
+- **Never default to Orchestrator deploy when the user said "publish".** "Publish" without specifier means Studio Web. When the target is ambiguous, ask the user with **Studio Web upload** / **Orchestrator deploy** / **Something else** as options before running `flow pack` + `solution publish`. See the dropdown question rule in [SKILL.md](../../../SKILL.md).
 - **Never publish a flow that hasn't been validated and formatted.** `flow validate` catches schema errors; `flow format` ensures Studio Web renders nodes correctly. Both are author-side gates — see [author/CAPABILITY.md](../../author/CAPABILITY.md).
 
 ## What's next