@uipath/skills 1.195.1 → 1.196.0

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

@@ -21,7 +21,7 @@ Scaffold a new agent project at the given path.
 uip agent init "<AGENT_NAME>" --output json
 ```
 
-The `<path>` argument is relative or absolute; the command can run from any directory. Creates agent.json, entry-points.json, project.uiproj, and default eval directories inside the target path. Does **not** create `.agent-builder/` — that is generated by `uip agent migrate`.
+The `<path>` argument is relative or absolute; the command can run from any directory. Creates agent.json, entry-points.json, project.uiproj, and default eval directories inside the target path. Run `uip agent refresh` after editing to regenerate `entry-points.json` and `bindings_v2.json`.
 
 **Options:**
 - `--model <model>` — LLM model to use (default: `gpt-4o-2024-11-20`). This default is stale; override it post-init — discover current tenant models with `uip agent model list` and select per [model-selection-guide.md](model-selection-guide.md). Pass `--model` at init or edit `settings.model` after.
@@ -78,16 +78,17 @@ uip agent validate [path] --output json
 1. Checks `agent.json` structure: `version === "1.1.0"`, type, UUID, settings (including `mode`), messages, contentTokens consistency.
 2. Verifies schema sync between `agent.json` and `entry-points.json` (properties + required[]).
 3. Validates `project.uiproj` (`ProjectType === "Agent"`).
-4. Runs pending migrations **in memory only** — reports `MigrationPending: true` if migration is needed, but never writes to disk.
-5. Validates `agent.json` against the latest schema, eval-sets, evaluators (category/type constraints), and counts resources.
+4. Storage-version gate — fails with `AgentValidationOutdated` if `storageVersion` is not at the latest. Run `uip agent refresh` to migrate.
+5. Validates `agent.json` against the latest Zod schema, eval-sets, evaluators (category/type constraints), and counts resources.
+6. Dry-run derived-files generation — compares generated `entry-points.json` and `bindings_v2.json` against on-disk files. Fails with `AgentValidationDrift` if they are out of sync. Run `uip agent refresh` to regenerate.
 
-**Does NOT write files or generate `.agent-builder/`.** Run `uip agent migrate` after validate to write migrated files and regenerate `.agent-builder/`.
+**Does NOT write files.** Strict read-only. Run `uip agent refresh` before validate to apply migrations and regenerate derived files.
 
-**With `--inline-in-flow`:** Steps 2 and 3 are skipped.
+**With `--inline-in-flow`:** Steps 2, 3, and entry-points drift check are skipped.
 
 **Success output:**
 ```json
-{ "Result": "Success", "Code": "AgentValidation", "Data": { "Status": "Valid", "Model": "...", "StorageVersion": "50.0.0", "MigrationPending": false, "Validated": { "agent": true, "resources": 2, "evalSets": 1, "evaluators": 2 } } }
+{ "Result": "Success", "Code": "AgentValidation", "Data": { "Status": "Valid", "Model": "...", "StorageVersion": "50.0.0", "Validated": { "agent": true, "resources": 2, "evalSets": 1, "evaluators": 2 } } }
 ```
 
 **Failure output:**
@@ -95,26 +96,27 @@ uip agent validate [path] --output json
 { "Result": "Failure", "Code": "AgentValidationFailed", "Message": "Validation failed with N error(s)", "Data": { "Errors": ["agent.json → settings.mode: missing — must be \"standard\" or \"advanced\""] } }
 ```
 
-### `uip agent migrate`
+### `uip agent refresh`
 
-Applies pending schema migrations and regenerates `.agent-builder/` files. Runs the same checks as `uip agent validate` before writing anything — files are only written if all checks pass.
+Applies pending schema migrations and regenerates derived files (`entry-points.json`, `bindings_v2.json`). Runs static validation before writing anything — files are only written if all checks pass.
 
 ```bash
-uip agent migrate [path] --output json
+uip agent refresh [path] --output json
 ```
 
 **What it does:**
-1. Runs all static validation checks (same as `uip agent validate`).
+1. Runs all static validation checks.
 2. Writes migrated `agent.json` (and related files) to disk if migration is needed.
-3. Regenerates `.agent-builder/` files (agent.json with inlined resources, entry-points.json, bindings.json) from each `resources/{ResourceName}/resource.json`.
+3. Regenerates `entry-points.json` from `agent.json` inputSchema/outputSchema (preserving the existing `uniqueId`).
+4. Regenerates `bindings_v2.json` from `resources/{ResourceName}/resource.json` files, features, and guardrail escalations.
 
-**With `--inline-in-flow`:** Skips `entry-points.json`/`project.uiproj` checks. `.agent-builder/agent.json` and `bindings.json` are still generated, and agent capability bindings are merged into the parent flow project's `bindings_v2.json`.
+**With `--inline-in-flow`:** Skips `entry-points.json`/`project.uiproj` checks. Agent capability bindings are merged into the parent flow project's `bindings_v2.json`.
 
-**Workflow:** run `uip agent validate` to check, then `uip agent migrate` to apply writes and regenerate `.agent-builder/`. For routine edits with no schema migration pending, `migrate` is still needed to keep `.agent-builder/` in sync.
+**Workflow:** run `uip agent refresh` to apply writes and regenerate derived files, then `uip agent validate` to verify the project is clean. For routine edits with no schema migration pending, refresh is still needed to keep `entry-points.json` and `bindings_v2.json` in sync.
 
 ### `uip agent memory`
 
-Manage low-code agent memory space features and seed items. These commands write `features/{FeatureName}/feature.json` and update `.agent-builder/agent.json`; run validate and migrate afterwards to regenerate bindings.
+Manage low-code agent memory space features and seed items. These commands write `features/{FeatureName}/feature.json`; run refresh and validate afterwards to regenerate bindings.
 
 ```bash
 uip agent memory add SupportRecall \
@@ -138,6 +140,16 @@ uip agent memory item remove SupportRecall customer-tier --path "<AGENT_PROJECT_
 
 For discovery, retrieval settings, memory item types, and troubleshooting, see [capabilities/memory/memory.md](capabilities/memory/memory.md).
 
+### `uip agent debug`
+
+Run the agent end-to-end on Studio Web and stream the result. **Uploads the enclosing solution** to Studio Web, then runs it — one step, no separate `uip solution upload`, so the debugged copy always matches local. **Executes the agent for real** — confirm with the user first (per [critical-rules.md](critical-rules.md) Rule 8: consent before upload/publish/deploy).
+
+```bash
+uip agent debug <AGENT_PROJECT_DIR> --inputs '{"input":"..."}' --output json
+```
+
+Returns `Code: "AgentDebug"` with `Data.State`, `Data.Output`, and `Data.TraceId`. A `Faulted` run returns `Result: "Failure"` (exit 1); inspect it with `uip traces spans get <TraceId> --output json`. Full options and reporting in [debug.md](debug.md).
+
 ## Solution Commands
 
 ### Create Solution
@@ -148,10 +160,16 @@ uip solution init "<SOLUTION_NAME>" --output json
 
 ### Register Project with Solution
 
-`uip agent init` **auto-registers** the project with the parent `.uipx` when run from inside a solution directory. Verify via `Data.SolutionRegistration.Status` in the `agent init` response — `Registered` or `AlreadyRegistered` means you are done. Use `uip solution project add` only as a fallback when `Status` is `Skipped` or `Failed` (e.g., `init` was run outside the solution dir, or the `.uipx` write failed).
+`uip agent init` **auto-registers** the project with the parent `.uipx` when run from inside a solution directory (pass `--skip-solution-registration` to skip auto-registration). Verify via `Data.SolutionRegistration.Status` in the `agent init` response. The full set of statuses:
+
+- `Registered` / `AlreadyRegistered` — registered (added now / already present). **You are done.**
+- `OptedOut` — `--skip-solution-registration` was passed; registration was intentionally skipped. No action needed (register later with the fallback if you change your mind).
+- `NotInSolution` — no parent `.uipx` was found (`init` ran outside a solution). Use the fallback if you want it in a solution.
+- `Skipped` — a candidate solution was found but registration wasn't safe (e.g. multiple `.uipx`, or project outside the solution dir). Resolve, then use the fallback.
+- `Failed` — registration was attempted but errored (`.uipx` read/parse/write). Use the fallback.
 
 ```bash
-# Fallback only — when agent init's Data.SolutionRegistration.Status is Skipped / Failed.
+# Fallback — when Status is NotInSolution / Skipped / Failed (not needed for OptedOut).
 uip solution project add "<AGENT_PROJECT_DIR>" [solutionFile] --output json
 ```
 
@@ -217,16 +235,16 @@ uip solution bundle . -d ./dist --output json
 
 ## Resource Discovery
 
-`uip solution resource list` queries the Resource Catalog Service for all resources visible to the tenant and returns a compact JSON list. Use it as the first step of any tool-authoring flow — it replaces `uip or folders list` and `uip or processes list`, and covers Action Center apps and Context Grounding indexes too.
+`uip solution resources list` queries the Resource Catalog Service for all resources visible to the tenant and returns a compact JSON list. Use it as the first step of any tool-authoring flow — it replaces `uip or folders list` and `uip or processes list`, and covers Action Center apps and Context Grounding indexes too.
 
 Two supported invocations:
 
 ```bash
 # Local (in-solution): --kind and --search not allowed.
-uip solution resource list [solutionPath] --source local --output json
+uip solution resources list --solution-folder <SOLUTION_DIR> --source local --output json
 
 # Remote (Orchestrator / RCS): --kind and --search supported.
-uip solution resource list [solutionPath] --source remote [--kind <kind>] [--search <term>] --output json
+uip solution resources list --solution-folder <SOLUTION_DIR> --source remote [--kind <kind>] [--search <term>] --output json
 ```
 
 **Flags:**
@@ -264,7 +282,7 @@ uip solution resource list [solutionPath] --source remote [--kind <kind>] [--sea
 | `Connection` | `uipath-<connector-key>` | Integration Service connection — the `Type` IS the connector key |
 | `Bucket` | `orchestratorBucket` | Orchestrator storage bucket |
 
-**What `resource list` does not return:** argument schemas, action schemas, data source types, authentication details, package versions, or feed ids. For `Process` and `Index` resources, follow up with `uip solution resource get <KEY> --output json` and read `Data.spec` for the full configuration. For other kinds (`App`, `Connection`, `Bucket`), see the kind-specific capability files. `resource list` is the identification step — it tells you *that* a resource exists and *where*.
+**What `resources list` does not return:** argument schemas, action schemas, data source types, authentication details, package versions, or feed ids. For `Process` and `Index` resources, follow up with `uip solution resources get <KEY> --output json` and read `Data.spec` for the full configuration. For other kinds (`App`, `Connection`, `Bucket`), see the kind-specific capability files. `resources list` is the identification step — it tells you *that* a resource exists and *where*.
 
 ## End-to-End Example — New Standalone Agent
 
@@ -297,7 +315,8 @@ uip solution init "<SOLUTION_NAME>" --output json
 # `Data.SolutionRegistration.Status` in the response (`Registered` or
 # `AlreadyRegistered`).
 uip agent init "<SOLUTION_NAME>/<AGENT_NAME>" --output json
-# (fallback only — run if Data.SolutionRegistration.Status is Skipped / Failed)
+# (fallback only — run if Data.SolutionRegistration.Status is `NotInSolution` / `Skipped` / `Failed`;
+#  `OptedOut` means `--skip-solution-registration` was passed and registration was skipped on purpose)
 # uip solution project add "<SOLUTION_NAME>/<AGENT_NAME>" --output json
 ```
 
@@ -316,8 +335,8 @@ Read [agent-definition.md](agent-definition.md) for the full schema.
 
 1. Add fields to `agent.json` → `inputSchema` and `outputSchema`
 2. Mirror in `entry-points.json`
-3. Validate: `uip agent validate "<SOLUTION_NAME>/<AGENT_NAME>" --output json`
-4. Migrate (writes files + regenerates `.agent-builder/`): `uip agent migrate "<SOLUTION_NAME>/<AGENT_NAME>" --output json`
+3. Refresh (writes migrated files + regenerates `entry-points.json` and `bindings_v2.json`): `uip agent refresh "<SOLUTION_NAME>/<AGENT_NAME>" --output json`
+4. Validate: `uip agent validate "<SOLUTION_NAME>/<AGENT_NAME>" --output json`
 
 ### Step 5 — Publish to Studio Web or deploy to Orchestrator
 
@@ -386,18 +405,19 @@ All solution lifecycle operations go through `uip solution` CLI. Never call Auto
 | Create solution | `uip solution init "<NAME>" --output json` | Any directory | — |
 | Scaffold agent | `uip agent init "<NAME>" --output json` | Solution directory | — |
 | Scaffold inline agent | `uip agent init "<FLOW_PROJECT_DIR>" --inline-in-flow --output json` | Any directory | — |
-| Verify project registration | Check `Data.SolutionRegistration.Status` from `agent init` response (`Registered` / `AlreadyRegistered` = done) | Solution directory | — |
-| Register project (fallback) | `uip solution project add "<PATH>" --output json` — only when `agent init` returned `Skipped` / `Failed` | Solution directory | — |
-| Validate (read-only) | `uip agent validate [path] --output json` | Agent dir or any with path | — |
-| Migrate + regenerate builder | `uip agent migrate [path] --output json` | Agent dir or any with path | — |
-| Add memory space feature | `uip agent memory add <FeatureName> --memory-space <Name> --folder-path <Folder> --path <AgentDir> --output json` | Any directory | Writes `features/<FeatureName>/feature.json`; run validate/migrate after |
+| Verify project registration | Check `Data.SolutionRegistration.Status` from `agent init` response (`Registered` / `AlreadyRegistered` = done; `OptedOut` = `--skip-solution-registration` passed) | Solution directory | — |
+| Register project (fallback) | `uip solution project add "<PATH>" --output json` — when `agent init` returned `NotInSolution` / `Skipped` / `Failed` | Solution directory | — |
+| Refresh + regenerate derived files | `uip agent refresh [path] --output json` | Agent dir or any with path | — |
+| Validate (strict read-only) | `uip agent validate [path] --output json` | Agent dir or any with path | — |
+| Debug / run end-to-end on Studio Web | `uip agent debug <AgentDir> --inputs '{...}' --output json` | Agent dir | `Successful`, `Faulted`, `Stopped` |
+| Add memory space feature | `uip agent memory add <FeatureName> --memory-space <Name> --folder-path <Folder> --path <AgentDir> --output json` | Any directory | Writes `features/<FeatureName>/feature.json`; run refresh/validate after |
 | Seed memory item | `uip agent memory item add <FeatureName> <key> <value> --memory-type episodic --feedback-id <FEEDBACK_ID> --path <AgentDir> --output json` | Any directory | Updates existing item with same key |
 | List guardrail validators | `uip agent guardrails list --output json` | Any directory | — |
-| Discover resources | `uip solution resource list --kind <Kind> --source remote [--search <term>] --output json` | Solution directory | — |
-| Refresh resources | `uip solution resource refresh --output json` | Solution directory | — |
-| Add one resource (local stub or remote import) | `uip solution resource add --source local\|remote --kind <Kind> --name <NAME> [--folder-path <FOLDER>] --output json` | Solution directory | Idempotent on `(kind, name, folder)` for local, on key for remote |
-| Remove one resource by key | `uip solution resource remove <KEY> --output json` | Solution directory | Offline; doesn't touch `bindings_v2.json` |
-| Edit one resource's spec | `uip solution resource edit <KEY> --patch '{...}' --output json` | Solution directory | Only command that mutates an existing resource; `refresh` never overwrites. Unknown/reference/read-only props silently ignored. JSON is the only input — types preserved verbatim |
+| Discover resources | `uip solution resources list --kind <Kind> --source remote [--search <term>] --output json` | Solution directory | — |
+| Refresh resources | `uip solution resources refresh --output json` | Solution directory | — |
+| Add one resource (local stub or remote import) | `uip solution resources add --source local\|remote --kind <Kind> --name <NAME> [--folder-path <FOLDER>] --output json` | Solution directory | Idempotent on `(kind, name, folder)` for local, on key for remote |
+| Remove one resource by key | `uip solution resources remove <KEY> --output json` | Solution directory | Offline; doesn't touch `bindings_v2.json` |
+| Edit one resource's spec | `uip solution resources edit <KEY> --patch '{...}' --output json` | Solution directory | Only command that mutates an existing resource; `refresh` never overwrites. Unknown/reference/read-only props silently ignored. JSON is the only input — types preserved verbatim |
 | Upload to Studio Web | `uip solution upload . --output json` | Solution directory | — |
 | Pack | `uip solution pack . ./dist -v "1.0.0" --output json` | Solution directory | — |
 | Publish | `uip solution publish ./dist/<PKG>.zip --output json` | Any directory | — |

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

@@ -1,6 +1,6 @@
 # Solution Resources Internals
 
-Solution architecture, UUID cross-references, bindings, debug_overwrites, and `uip solution resource refresh` mechanics. Capability-agnostic — every capability that produces solution-level files relies on the patterns documented here.
+Solution architecture, UUID cross-references, bindings, debug_overwrites, and `uip solution resources refresh` mechanics. Capability-agnostic — every capability that produces solution-level files relies on the patterns documented here.
 
 ## Solution Architecture
 
@@ -130,11 +130,11 @@ bucket/orchestratorBucket/...        │
 
 ## Bindings
 
-`uip agent migrate` reads each `resources/{Name}/resource.json` and `features/{Name}/feature.json`, then writes one binding entry per external dependency into `bindings_v2.json`. Every binding carries `name`; **Process, Index, App, and MemorySpace bindings also carry `folderPath`** propagated verbatim from the agent-level resource or feature. Connection bindings are exempt (bound by `connection.id`). `uip agent validate` performs the same read-only check without writing — it reports `MigrationPending` if the file is behind.
+`uip agent refresh` reads each `resources/{Name}/resource.json` and `features/{Name}/feature.json`, then writes one binding entry per external dependency into `bindings_v2.json`. Every binding carries `name`; **Process, Index, App, and MemorySpace bindings also carry `folderPath`** propagated verbatim from the agent-level resource or feature. Connection bindings are exempt (bound by `connection.id`). `uip agent validate` performs the same read-only check without writing — it fails with `AgentValidationOutdated` if the file is behind.
 
 | Binding kind | `name` source | `folderPath` source | Notes |
 |---|---|---|---|
-| `process` (local or external) | `properties.processName` | `properties.folderPath` (literal `Folder` from `uip solution resource list` — typically `"solution_folder"` for local, Orchestrator path for external) | One per process tool |
+| `process` (local or external) | `properties.processName` | `properties.folderPath` (literal `Folder` from `uip solution resources list` — typically `"solution_folder"` for local, Orchestrator path for external) | One per process tool |
 | `index` | `indexName` | top-level `folderPath` (literal `Folder`) | StorageBucket-backed only |
 | `app` (escalation) | `channel.properties.appName` | `channel.properties.folderName` (literal `Folder`, translated to binding `folderPath`) | One per Action Center channel |
 | `app` (guardrail escalation) | `action.app.name` | `action.app.folderName` (literal `Folder`, translated to binding `folderPath`) | One per `$actionType: "escalate"` guardrail action |
@@ -155,7 +155,7 @@ bucket/orchestratorBucket/...        │
 ```
 
 ```jsonc
-// External tool — literal Folder from `uip solution resource list`
+// External tool — literal Folder from `uip solution resources list`
 {
   "resource": "process",
   "key": "TestRPA",
@@ -220,9 +220,9 @@ bucket/orchestratorBucket/...        │
 
 The `solutionsSupport: "true"` metadata flag signals to the deployment engine that this resource participates in the solution deployment.
 
-> **Note 1: `solutionsSupport` is a stringified boolean** (`"true"`, not `true`). `uip agent migrate` and `uip solution resource refresh` emit the string form — preserve it verbatim when round-tripping. Re-typing it as a JSON boolean breaks downstream parsing.
+> **Note 1: `solutionsSupport` is a stringified boolean** (`"true"`, not `true`). `uip agent refresh` and `uip solution resources refresh` emit the string form — preserve it verbatim when round-tripping. Re-typing it as a JSON boolean breaks downstream parsing.
 >
-> **Note 2: do not hand-edit `bindings_v2.json`.** The binding's `folderPath` is generated from the agent-level `resource.json` or memory feature file. Edit the resource.json, or use `uip agent memory` for memory features, then re-run `uip agent migrate`; never patch the binding directly. See [critical-rules.md](critical-rules.md) Anti-pattern 20 and 24.
+> **Note 2: do not hand-edit `bindings_v2.json`.** The binding's `folderPath` is generated from the agent-level `resource.json` or memory feature file. Edit the resource.json, or use `uip agent memory` for memory features, then re-run `uip agent refresh`; never patch the binding directly. See [critical-rules.md](critical-rules.md) Anti-pattern 20 and 24.
 
 ## Debug Overwrites
 
@@ -263,14 +263,14 @@ For capability-specific debug_overwrites entries (process / connection / index /
 ## Refresh Mechanics
 
 ```bash
-uip solution resource refresh [solutionPath] --output json
+uip solution resources refresh [solutionPath] --output json
 ```
 
 Re-scans all projects in the solution and syncs resource declarations from their `bindings_v2.json` files. For each external binding, refresh uses the **joint key `(name, kind, folderPath)`** read from the binding to look up the matching resource in the appropriate catalog — Resource Catalog Service for `Process`, `App`, and `MemorySpace` bindings, ECS for `Index` bindings, the local IS connection cache for `Connection` bindings. The folder dimension disambiguates resources that share a name across folders. If no match is found, refresh creates a virtual placeholder in the solution and warns.
 
 Solution-internal bindings (`folderPath: "solution_folder"`) skip the RCS lookup — they are resolved at deploy time against the solution folder.
 
-**Run this after `uip agent migrate`** whenever external tools, memory spaces, index contexts, app escalations, or connections have been added or changed.
+**Run this after `uip agent refresh`** whenever external tools, memory spaces, index contexts, app escalations, or connections have been added or changed.
 
 Handled kinds and what refresh produces:
 

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

@@ -1,13 +1,11 @@
 ---
 name: uipath-api-workflow
-description: "[PREVIEW] UiPath API Workflow assistant — author, run, package, publish JSON workflows executed by `uip api-workflow run`. Covers logical/hierarchical structure (Sequence, Assign, JavaScript, If with #Wrapper/#Then/#Else, ForEach, DoWhile, Break, TryCatch, Wait, Response — including nested patterns) AND HTTP / Integration Service connector activities (Gmail, Outlook, GitHub, Slack, etc.) authored via `uip api-workflow registry resolve` + `stub`. Triggers on prompts about UiPath API workflows, project type \"Api\", JSON workflow files containing `document.dsl`/`do[]`, any of those activity types, or fetching data from a public/vendor API. Uses `uip api-workflow run` for local execution and `uip solution pack`/`publish` for deployment. For .flow Maestro→uipath-maestro-flow. For .xaml/coded RPA→uipath-rpa. For coded agents→uipath-agents. For Coded Apps→uipath-coded-apps."
+description: "UiPath API Workflow assistant — author, run, package, publish JSON workflows executed by `uip api-workflow run`. Covers logical/hierarchical structure (Sequence, Assign, JavaScript, If with #Wrapper/#Then/#Else, ForEach, DoWhile, Break, TryCatch, Wait, Response — including nested patterns) AND HTTP / Integration Service connector activities (Gmail, Outlook, GitHub, Slack, etc.) authored via `uip api-workflow registry resolve` + `stub`. Triggers on prompts about UiPath API workflows, project type \"Api\", JSON workflow files containing `document.dsl`/`do[]`, any of those activity types, or fetching data from a public/vendor API. Uses `uip api-workflow run` for local execution and `uip solution pack`/`publish` for deployment. For .flow Maestro→uipath-maestro-flow. For .xaml/coded RPA→uipath-rpa. For coded agents→uipath-agents. For Coded Apps→uipath-coded-apps."
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 ---
 
 # UiPath API Workflow Assistant
 
-> **Preview** — this skill is in preview. Behavior, file shapes, and rules may change as the underlying executor and StudioWeb roundtrip story evolve.
-
 Build, run, and publish UiPath API Workflows — JSON files conforming to the CNCF Serverless Workflow DSL 1.0.0 with UiPath activity-type extensions. Executed by `@uipath/api-workflow-executor` via `uip api-workflow run`. Packaged as `Type: "Api"` projects via `uip solution pack`.
 
 ## When to Use This Skill
@@ -25,17 +23,19 @@ Build, run, and publish UiPath API Workflows — JSON files conforming to the CN
 
 Do NOT use for: `.flow` Maestro flows (→ `uipath-maestro-flow`), `.xaml` / coded RPA (→ `uipath-rpa`), coded agents (→ `uipath-agents`), Coded Web Apps (→ `uipath-coded-apps`).
 
-**Connector activities come from the registry, not from guessing.** HTTP Request and Integration Service Connector activities (Gmail Send Email, Outlook Get Newest Email, etc.) need StudioWeb-side editor metadata (`metadata.uiPathActivityTypeId` + `metadata.configuration`) to render correctly in the designer. The data is NOT in `uip is activities list`. Use `uip api-workflow registry resolve` + `uip api-workflow registry stub`: `resolve` searches the StudioWeb TypeCache (`projectType=Api`) for candidate GUIDs; `stub` combines the TypeCache entry with the Integration Service Elements schema (full endpoint path, request/response fields, multipart signal) and emits a ready-to-paste activity object — picking Http kind (`UiPath.Http`) or IntSvc kind (`UiPath.IntSvc`) automatically, building `metadata.configuration`, computing the slot and export-bucket keys, and declaring `multipartParameters` when needed. Follow the flow in [references/connector-activity-discovery.md](references/connector-activity-discovery.md). **NEVER invent a `uiPathActivityTypeId` or hand-author the configuration blob** — both come from the stub output.
-
 ## Core Principles
 
 1. **Know before you write.** Read the existing workflow file before editing. Read an example template before creating from scratch.
 2. **Start minimal, iterate to correct.** Add one activity at a time. Run with `--no-auth --output json` after each addition. Fix what breaks. Repeat.
-3. **Validate before running.** `uip api-workflow validate <Workflow.json>` is the closure step for every authoring session. It performs static checks (JSON Schema + semantic) without touching the network — catching malformed JSON, unknown `activityType` values, missing per-activity required keys (e.g. `If` without `do`+`switch`, `Assign` without `set`, `Connector` without `metadata.configuration`/`essentialConfiguration`), bad `evaluate.language`/`evaluate.mode`, and duplicate/empty workflow variables. Use it as a fast pre-flight; `uip api-workflow run` is the runtime validator that catches what static analysis can't (live HTTP calls, expression evaluation, connection state).
+3. **Validate before running.** `uip api-workflow validate` is the offline static pre-flight (autonomous); `uip api-workflow run` is the runtime validator that catches what static analysis can't (live HTTP, expression evaluation, connection state) and needs user consent. See rules 20–21.
 4. **Fix errors by category.** Triage: Structure > Expression > Activity Config > Logic. Higher-category fixes often resolve lower-category errors automatically.
 
 ## Critical Rules
 
+> **Rule 0 — Escalate big design forks before you build (highest priority, read first).** When the happy path doesn't work out of the box and the resolution is a judgment call the user would reasonably want to own, STOP and ask before committing to a branch. Present the concrete options with their trade-offs and a recommended default; proceed only on the user's answer. Triggers (non-exhaustive): no valid connection for a required activity (rule 16); no curated activity exists and the choice is generic activity vs. raw Http kind vs. a different connector; the requested operation isn't exposed by any resolvable activity and the fallback is a hand-built HTTP call against an undocumented endpoint; an input the prompt assumed is missing and the alternatives are placeholder, hardcoded value, or new workflow input; the prompt is satisfiable by structurally different workflows (single connector call vs. ForEach over a list). This does NOT cover mechanical choices with an obvious answer (variable names, activity key suffixes, export-pattern selection) — decide those and move on. Reserve escalation for forks where guessing wrong wastes work or ships something the user didn't intend.
+>
+> **Ask the fork BEFORE branch-specific research, not after.** Once you spot a structural fork, do only the shared work needed to surface the options (the cheap `resolve` that proves no curated activity exists, the `connections list`/`ping` that proves no connection works), then ask. Do NOT pre-research every branch — stubbing each candidate activity, describing resources, drafting alternative workflow shapes — so the user can "pick from finished work." The user picks one branch; deep work on the others is thrown away. Sequence: detect fork → minimal shared discovery → ask → then research and build only the chosen branch.
+
 1. **Workflow file is JSON, not YAML.** Top-level keys: `document` (with `dsl: "1.0.0"`), `evaluate` (`language: "javascript"`, `mode: "strict"`), `do` (one root sequence — named `Sequence_1` in the template skeleton, but the literal key may differ in existing workflows; always read the actual key from the file before editing — containing `WorkflowStart` + user activities). See [references/workflow-file-format.md](references/workflow-file-format.md).
 2. **`WorkflowStart` is always the first activity** inside the root sequence's `do` array. It hydrates variable defaults into `$context.variables` and forwards inputs to `$input`. Never remove, rename, or modify it. `isTransparent: true` (only `WorkflowStart` uses `true`).
 3. **Every activity is a single-key object** wrapped in the `do` array: `{ "<ActivityKey>": { ...activity body... } }`. Activity keys must be **globally unique** across the whole workflow — including `#Wrapper`, `#Then`, `#Else`, `#Body` suffixes.
@@ -63,24 +63,15 @@ Do NOT use for: `.flow` Maestro flows (→ `uipath-maestro-flow`), `.xaml` / cod
       - Either `"${ { ... } }"` (single-brace, expression-of-object-literal) or `"${{ ... }}"` (double-brace, object-literal-expression form) is valid — both evaluate to the same JS object. Pick one and stay consistent within a workflow.
     - For single-value responses (returning one variable or one expression), the simple form is fine: `"response": "${$context.outputs.Javascript_1}"` or `"response": "${'done'}"`.
     - **On-disk is authoritative.** Even with the single-expression workaround, every StudioWeb designer save can re-trigger normalization passes that may corrupt the Response shape. After any designer roundtrip, re-validate with `uip api-workflow run --no-auth` and re-apply the workaround if needed. Until SW-28452 ships a fix, treat the file on disk as truth, not what the designer renders.
-16. **Connector activities (Http kind AND IntSvc kind) are produced by `uip api-workflow registry resolve` + `stub`, gated by a connection ping for vendor activities.** The `stub` command combines TypeCache lookup (GUID + `InstanceParameters`) with Integration Service Elements metadata (full path, request/response fields, multipart signal) and emits the activity object — with `unifiedTypesCompatible: true` and `savedJitInputFieldId` so StudioWeb renders the **unified activity card** (the one on the current activity picker). Discovery flow:
-    1. **Resolve** — `uip api-workflow registry resolve "<keyword>" --output json`. Returns candidates with `uiPathActivityTypeId`, `displayName`, `connectorKey`, `objectName`, `httpMethod`, `activityType`. Pick the right GUID by `displayName` / `connectorKey` (filter by connector name when the operation name is ambiguous — e.g. "gmail" vs "outlook" for "send email").
-    2. **(IntSvc kind / vendor only) Verify a working connection.** `uip is connections list <connector-key> --output json` → pick `Id`. `uip is connections ping <uuid>` is **REQUIRED** — listing-state and runtime-state diverge (orphaned upstream element, expired OAuth, wrong tenant). On `ConnectionNotEnabled` / 404 `"Connection […] is invalid or you do not have access to it"`, run the unfiltered fallback `uip is connections list --output json` and search for a different `Id` whose `ConnectorKey` matches. Re-ping. Abort only when no UUID for that connector pings cleanly. NEVER author against a connection that hasn't pinged — it WILL 401 in cloud.
-    3. **Stub** — `uip api-workflow registry stub <activity-type-id> [--connection-id <uuid>] [--inputs '<json>'] --output json`. Returns: `Activity` (single-key object — drop directly into the root sequence's `do` array), `Kind` (`"Http"` or `"IntSvc"`), `SlotKey` (the activity key in the `do` array, e.g. `GetNewestEmail_1`), `ExportBucketKey` (what `export.as` writes AND what `$context.outputs.<X>` reads as, e.g. `getNewestEmail_1`, `http_request_1`, `ListEmails_1`), `ResponseFields` (downstream binding targets), `Warnings`. The CLI builds `metadata.configuration`, picks Http kind vs IntSvc kind from `connectorKey`, computes both keys, hub-prefixes the endpoint when IS Elements requires it, and declares `multipartParameters` for multipart operations. NEVER hand-author `metadata.configuration`, invent a `uiPathActivityTypeId`, or reconstruct either key from `objectName` — use what the stub returned. `--inputs` values are passed through verbatim — pass bare strings for literals, `${...}` for references (see field-shape rule (b) below).
-    4. **Required-field cross-check — MANDATORY after every stub call.** The stub drops `required: true` request fields. Run `uip is resources describe <connector-key> <object-name> --operation <op> --connection-id <uuid> --output json` (or parse `metadata.configuration.optionalConfiguration.fieldsContainer.inputFields` from the stub's own output) and confirm every `required: true` field appears in the corresponding `queryParameters` / `pathParameters` / `bodyParameters` block. Verified case: Outlook `getNewestEmail` requires `parentFolderId` (`fieldLocation: "query"`); the stub returns `queryParameters: {}` unless that field was passed via `--inputs`. Re-stub with `--inputs '{"<field>":"<value>"}'` or hand-edit the activity. Skipping this check is the second-most-common cause of "renders fine, runs fine, fails in cloud" connector activities (see [troubleshooting.md](references/troubleshooting.md#required-request-field-dropped-by-registry-stub)).
-    5. **Kind-specific finalization.**
-       - **Http kind** (HTTP Request, `connectorKey === uipath-uipath-http`): the stub leaves `<REPLACE_WITH_TARGET_URL>` in `bodyParameters.url` (unless passed via `--inputs`). Replace with the target URL (literal or `${$workflow.input.<name>}`). `connectionId: "ImplicitConnection"` is fine for inline-credential calls. See the verified template at [assets/templates/connector-call-example.json](assets/templates/connector-call-example.json) (a real stub-generated workflow that fetches catfacts).
-       - **IntSvc kind** (vendor curated, `UiPath.IntSvc`): if `--connection-id` was omitted, the stub contains `<REPLACE_WITH_VENDOR_CONNECTION_UUID>` placeholders — replace before running. Output payload is wrapped: read `$context.outputs.<ExportBucketKey>.content.<field>`, NOT `.<field>`. NEVER use Http kind with a vendor connection UUID — that produces 401 "Invalid Element token" in cloud.
-    6. **NEVER ship a workflow with `<REPLACE_WITH_*>` placeholders in `with.connectionId` or `with.connectionResourceId`.** StudioWeb's properties panel renders the placeholder string as if it were a real connection name — the connection pill shows `<REPLACE_WITH_VENDOR_C...>` with a red error, and the workflow 401s in cloud. The placeholder is a sentinel for "you forgot to run `stub` with `--connection-id`," not a value the user fills in later. If you don't have a pinged UUID, STOP authoring and ask the user — do not emit the placeholder. Same for `<REPLACE_WITH_TARGET_URL>` in Http kind. The vendor template at [assets/templates/vendor-curated-call-example.json](assets/templates/vendor-curated-call-example.json) keeps the placeholder ONLY because it is a template; generated workflows MUST have real values.
-    7. **(Solutions-mode + IntSvc kind only) Sync the connection into the Solution catalogue.** When the project lives under a `Solution/` tree, every vendor connection used by an IntSvc kind activity MUST also be declared as a Solution resource (`Solution/resources/solution_folder/connection/<connector-key>/<name>.json`) AND registered in the per-user debug overwrites (`Solution/userProfile/<guid>/debug_overwrites.json`). Without both, StudioWeb's properties panel marks the activity with **"to debug this resource, select a connection for it from the resource definition page"**, and clicking the activity overwrites `with.connectionId` with `null` in `Workflow.json` (the runtime resolves from `Workflow.json`; the panel resolves from the Solution resource tree + debug overwrites, which is why "Run" works but the panel breaks). The two-step CLI flow: (a) `uip api-workflow bindings sync --workflow <Workflow.json>` — generates `bindings_v2.json` next to the workflow (the input StudioWeb normally produces in-memory on open). (b) `uip solution resource refresh --solution-folder <path>` — reads every project's `bindings_v2.json`, uses `@uipath/resource-builder-sdk` to write both the catalogue file and the per-user debug overwrites via `editOverwritesAsync`. Idempotent and additive: run after every Workflow.json edit that adds/changes a connection. **SKIP this step entirely for:** (a) Http kind activities (`call: "UiPath.Http"`, `connectionId: "ImplicitConnection"` — literal sentinel, not a real connection), (b) non-connector activities (Sequence/Assign/If/ForEach/TryCatch/Wait/Response — no connectionId at all), (c) standalone projects with a top-level `project.json` and no `Solution/` wrapper. See [connector-activity-discovery.md — Step 5](references/connector-activity-discovery.md#step-5--solutions-mode-intsvc-kind-sync-the-connection-into-the-solution-catalogue).
-
-    **Field-shape rules — must hold across edits, not just at stub time. Violating any silently drops data on the first StudioWeb save:**
-    - **(a) Flat dotted keys.** Connector field names like `message.toRecipients` are literal keys, NOT paths. `"message.toRecipients": "..."`, NOT `{ message: { toRecipients: "..." } }`. Nested objects are dropped.
-    - **(b) Literals are BARE in connector params.** Plain `"andrei@uipath.com"`, NOT `"${'andrei@uipath.com'}"`. The Assign / Response wrap rule (rule 5) is **inverted** here — `${'...'}` reads as a (broken) expression and the field clears on save. References (`${$context.variables.X}`) stay wrapped because they're real expressions.
-    - **(c) Use `Data.SlotKey` and `Data.ExportBucketKey` from the stub verbatim.** Connector activities are the only activity type where the slot key (in the `do` array) and the export-bucket key (what `$context.outputs.<X>` reads as) can differ. The stub computes both; never derive either by hand from `objectName`. The two are sometimes identical (e.g. Outlook `ListEmails` → both `ListEmails_1`) and sometimes different (e.g. HTTP → `HttpRequest_1` slot vs `http_request_1` bucket).
-    - **(d) Endpoint may include a hub prefix.** Outlook `send-mail-v2` → `/hubs/productivity/send-mail-v2`. The stub fills the full path from IS Elements; don't truncate.
-
-    See [references/connector-activity-discovery.md](references/connector-activity-discovery.md) for the full flow, sample `stub` output, and worked examples (Http kind HTTP Request, IntSvc kind GetNewestEmail, IntSvc kind multipart SendEmail).
+16. **Connector activities (HTTP + Integration Service) come from `uip api-workflow registry resolve` + `stub` — never hand-author or guess.** The stub computes `metadata.configuration`, the kind (`UiPath.Http` vs `UiPath.IntSvc`), the endpoint (with hub prefix), `SlotKey`, and `ExportBucketKey` (which can differ — HTTP slot `HttpRequest_1` vs bucket `http_request_1`). Use all of them verbatim; NEVER invent a `uiPathActivityTypeId`, hand-author `metadata.configuration`, or reconstruct a key from `objectName`. Non-negotiables (full step-by-step, field-shape rules, multipart, and worked examples in [references/connector-activity-discovery.md](references/connector-activity-discovery.md)):
+    - **A keyword `resolve` miss is NOT proof no curated activity exists — verify connector-first before giving up.** `resolve` AND-matches every token, so a marketing phrase + guessed verb over-narrows (the product "UiPath Data Fabric" carries `connectorKey: uipath-uipath-dataservice` and activity names like "Create Entity Record" — `resolve "data fabric insert"` returns 0; fewer/truer tokens, not more). Before concluding none exists or falling back to a hand-built HTTP call (a Rule 0 fork): map the product/vendor → connector key with `uip is connectors list --filter "<product>"`, then enumerate with `uip is activities list <connector-key>`. Do NOT hardcode/guess the key — look it up. See the reference's Step 1 recovery.
+    - **IntSvc/vendor activities require a *pinged* connection.** `uip is connections ping <uuid>` must succeed before authoring — listing-state ≠ runtime-state; an `Enabled` connection can still 401 in cloud. On failure, try the unfiltered `uip is connections list` fallback and re-ping a different `Id` for that `ConnectorKey`.
+    - **No connection pings cleanly → STOP and ask the user — do not decide alone.** Offer: **(a)** continue with a placeholder (stub without `--connection-id`, leaving the `<REPLACE_WITH_VENDOR_CONNECTION_UUID>` sentinel — workflow is structurally complete but 401s until replaced; only with explicit user consent), or **(b)** stop and wait for the user to create/fix the connection, then re-ping. Never silently emit the placeholder, never silently abort. (Instance of Rule 0 — escalate design forks.)
+    - **NEVER ship a `<REPLACE_WITH_*>` placeholder** in `with.connectionId` / `connectionResourceId` / Http `bodyParameters.url`. StudioWeb renders it as a broken connection and the workflow 401s. The placeholder is a sentinel for "re-stub with the real value," not a fill-in-later field.
+    - **After every stub, cross-check required fields** — the stub drops `required: true` request fields (e.g. Outlook `getNewestEmail` needs `parentFolderId`). Confirm via `uip is resources describe ... --operation <op>` or the stub's own `metadata.configuration` inputFields; re-stub with `--inputs` if missing.
+    - **Connector params use flat dotted keys and BARE literals.** `"message.toRecipients": "..."`, not nested objects; plain `"x@y.com"`, not `"${'x@y.com'}"` — rule 5's wrap is **inverted** here (`${'...'}` clears the field on save). Real references (`${$context...}`) stay wrapped.
+    - **NEVER use Http kind with a vendor connection UUID** (401 "Invalid Element token"). IntSvc output is wrapped: read `$context.outputs.<ExportBucketKey>.content.<field>`.
+    - **(Solutions-mode + IntSvc only)** sync the connection into the catalogue: `uip api-workflow bindings sync --workflow <Workflow.json>` then `uip solution resource refresh --solution-folder <path>`. Skip for Http kind, non-connector activities, and standalone (no `Solution/`) projects.
 17. **Pass input as a JSON string.** `--input-arguments '{"key":"value"}'`. Invalid JSON exits 1.
 18. **Always `--output json`** when parsing CLI output programmatically. Success → `{ "Result": "Success", "Code": "WorkflowRun", "Data": {...} }`. Failure → `{ "Result": "Failure", "Message": "...", "Instructions": "..." }` with exit 1.
 19. **Build & publish goes through the solution packager.** API workflows pack via `uip solution pack <solutionDir> <outputDir>` and publish via `uip solution publish <package.zip>`. There is no `uip api-workflow build` or `uip api-workflow publish` command. Project type must be `"Api"` in the solution `.uipx`.
@@ -132,8 +123,9 @@ Decide which activities to use and in what order.
 | Pause execution | **Wait** | `wait.seconds`/`minutes`/`milliseconds` |
 | Exit loop early | **Break (in If)** | Wrap Break in an If — there's no "break when" condition on Break itself. `break: "true"` (string!), `then: "exit"`, `set: "${$input}"` |
 | Exit nested loops | **Flag variable + Break twice** | Set a flag in inner loop, check + Break in outer — see [control-flow-patterns.md](references/control-flow-patterns.md#5-conditional-break-inside-a-loop) |
-| Call an arbitrary REST API (catfacts, stock prices, weather, any public/internal HTTP endpoint) | **Unified HTTP Request** (`call: "UiPath.Http"`, Http kind) | `uip api-workflow registry resolve "http request"` → pick the HTTP Request GUID → `registry stub <guid> --inputs '{"method":"GET","url":"<TARGET>"}' --output json`. The stub emits `call: "UiPath.Http"` with `unifiedTypesCompatible: true` so StudioWeb renders the unified HTTP card. **NEVER use `call: "http"`** (deprecated simple form — renders as block icon). See [connector-activity-discovery.md](references/connector-activity-discovery.md#http-kind--call-uipathhttp-http-request-curated-activity) and the verified template at [assets/templates/connector-call-example.json](assets/templates/connector-call-example.json). |
-| Call a vendor service via its UiPath connection (Gmail, Outlook, GitHub, Slack, etc.) | **Vendor curated activity** (`call: "UiPath.IntSvc"`, IntSvc kind) | `uip is connections list/ping` for the UUID → `uip api-workflow registry resolve "<keyword>"` → `registry stub <guid> --connection-id <uuid>`. Stub returns IntSvc kind with the full hub-prefixed endpoint. Never use `UiPath.Http` with a vendor connection UUID. See [connector-activity-discovery.md](references/connector-activity-discovery.md#intsvc-kind--call-uipathintsvc-vendor-curated-activity) |
+| Call an arbitrary REST API (catfacts, stock prices, weather, any public/internal endpoint) | **Unified HTTP Request** (`call: "UiPath.Http"`, Http kind) | `connectionId: "ImplicitConnection"`. NEVER `call: "http"` (block icon). Via rule 16's flow. |
+| Call a vendor service via its UiPath connection (Gmail, Outlook, GitHub, Slack, …) | **Vendor curated activity** (`call: "UiPath.IntSvc"`, IntSvc kind) | Needs a pinged connection UUID. Via rule 16's flow. |
+| CRUD a connector object that has no curated activity | **Generic activity** (`ActivityType: "Generic"` in resolve output — "List Records", "Get Record", …; IntSvc kind) | Add `--object-name <object>` (from `uip is resources list`) to the stub. Prefer a curated activity when one exists. Via rule 16's flow. |
 
 Before generating, determine:
 1. Which activities are needed and in what order
@@ -162,51 +154,22 @@ Workflow skeleton:
 
 ### Phase 3: Validate (static) then Run (with consent)
 
-After authoring or editing, **always validate first, autonomously** (Critical Rule 20):
+Validate autonomously (rule 20), fixing + re-validating until `Data.Status: "Valid"`:
 
 ```bash
 uip api-workflow validate ./my-workflow.json --output json
 ```
 
-- **Validate passes** (`Result: "Success"`, `Data.Status: "Valid"`) — the activity tree is structurally sound. Proceed to the run-confirmation step below.
-- **Validate fails** (`Result: "Failure"`, exit 1) — do NOT bother the user. Read the `Instructions` field, locate the offending activity by its JSON path, fix Workflow.json, re-validate. Loop until pass. Focus on the **semantic-tail errors** (prose messages like "Unknown activityType", "must contain a 'do' with inner 'switch'") — schema-level `oneOf` errors are noisy fanout; one semantic fix usually clears a dozen schema errors at once.
-
-Once validate is green, **ask the user before running anything** (Critical Rule 21). The choice has real consequences:
+Once green, **ask before running** (rule 21) — pick the mode from workflow content:
 
 | Mode | Flag | What happens | Use when |
 |--|--|--|--|
-| No-auth | `--no-auth` | Skips token loading. Structure / expressions / control flow validated. IntSvc kind vendor calls fail with a missing-token error. | Workflow contains only Sequence / Assign / JS / If / ForEach / DoWhile / Break / TryCatch / Wait / Response, OR Http kind HTTP with `connectionId: "ImplicitConnection"`. Default for most authoring iterations. |
-| With auth | (none) | Uses the user's `uip login` token. Real Integration Service calls — vendor APIs touched, side effects happen. | Workflow contains a IntSvc kind vendor activity AND the user has confirmed it's OK to send the real call (email actually sent, ticket actually created, file actually uploaded). |
-
-Phrase the question explicitly, with a recommended default. Examples:
-
-- Control-flow workflow: "Validate passed. Run with `--no-auth` to exercise the activity tree? (Y/n)"
-- IntSvc kind workflow: "Validate passed. The workflow contains a IntSvc kind Outlook send-mail-v2 call — running with auth WILL send a real email to `<recipient>`. Options: (1) skip run, (2) run `--no-auth` (fails at the connector call but exercises everything before it), (3) run with auth and send the email. Which?"
-
-Wait for the user's reply. Then run the chosen command:
+| No-auth | `--no-auth` | Skips token loading. Structure / expressions / control flow validated. IntSvc vendor calls fail with a missing-token error. | Control-flow-only, OR Http kind with `connectionId: "ImplicitConnection"`. Default for most iterations. |
+| With auth | (none) | Uses the `uip login` token. Real Integration Service calls — vendor side effects happen. | An IntSvc vendor activity AND the user confirmed the real call is OK (email sent, ticket created, file uploaded). |
 
-```bash
-# User picked --no-auth:
-uip api-workflow run ./my-workflow.json --no-auth --output json
-
-# User confirmed running with auth (uip login required):
-uip api-workflow run ./my-workflow.json --output json
-```
-
-If the user picks "skip," tell them the exact command to run themselves and stop.
+State the consequence in the question (e.g. "running with auth WILL send a real email to `<recipient>` — (1) skip, (2) `--no-auth`, (3) run with auth?"), wait for the reply, then run `uip api-workflow run ./my-workflow.json [--no-auth] --output json`. If the user skips, give them the exact command and stop.
 
-**Read the failure output:**
-- `Message` describes the error
-- `Instructions` often contains the fix
-- Exit code: `0` = success, `1` = failure
-
-**Fix in this order** (higher categories often resolve lower ones):
-1. **Structure** — missing `#Wrapper`/`#Body`, duplicate keys, malformed JSON, missing `WorkflowStart`
-2. **Expression** — missing `${...}`, unwrapped condition, undefined references
-3. **Activity Config** — wrong required fields, wrong export key casing, missing `then: "end"` on Response
-4. **Logic** — wrong behavior, infinite loops, unreachable code
-
-See [references/troubleshooting.md](references/troubleshooting.md) for the full pitfall catalog.
+Fix run failures in category order — **Structure > Expression > Activity Config > Logic** (higher categories often resolve lower ones). Full pitfall catalog: [references/troubleshooting.md](references/troubleshooting.md).
 
 ### Phase 4: Package and Publish
 
@@ -276,32 +239,18 @@ uip solution publish ./build/MyApiSolution.zip --tenant MyTenant --output json
 | [assets/templates/loop-aggregation-example.json](assets/templates/loop-aggregation-example.json) | DoWhile + ForEach + Assign accumulation — pure-compute aggregation pattern |
 | [assets/templates/nested-control-flow-example.json](assets/templates/nested-control-flow-example.json) | Heavy nesting demo — TryCatch around DoWhile around If with conditional Break |
 | [assets/templates/connector-call-example.json](assets/templates/connector-call-example.json) | **Http kind** — HTTP Request curated activity (`call: "UiPath.Http"`) for arbitrary REST calls. Generated by `registry stub` against the catfacts URL. Shows the canonical shape: `connectionId: "ImplicitConnection"`, `unifiedTypesCompatible: true`, `savedJitInputFieldId: "in_http-request"`, URL in `bodyParameters.url`. Verified end-to-end with `uip api-workflow run --no-auth`. |
-| [assets/templates/vendor-curated-call-example.json](assets/templates/vendor-curated-call-example.json) | **IntSvc kind** — vendor curated activity (`call: "UiPath.IntSvc"`) using Outlook GetNewestEmail as exemplar. The `<REPLACE_WITH_VENDOR_CONNECTION_UUID>` placeholder is a sentinel — replace it with a pinged UUID from `uip is connections list/ping` **before** writing the workflow to disk. StudioWeb renders the literal placeholder as a broken connection if it survives. See rule 16 step 6. |
+| [assets/templates/vendor-curated-call-example.json](assets/templates/vendor-curated-call-example.json) | **IntSvc kind** — vendor curated activity (`call: "UiPath.IntSvc"`) using Outlook GetNewestEmail as exemplar. The `<REPLACE_WITH_VENDOR_CONNECTION_UUID>` placeholder is a sentinel — replace it with a pinged UUID from `uip is connections list/ping` **before** writing the workflow to disk. StudioWeb renders the literal placeholder as a broken connection if it survives. See rule 16. |
 | [assets/templates/solution-connection-resource-template.json](assets/templates/solution-connection-resource-template.json) | **Solution connection resource** — declares a IntSvc kind connection as a Solution resource. Write to `Solution/resources/solution_folder/connection/<connector-key>/<connection-name>.json`. Required for Solutions-mode projects; without it the StudioWeb properties panel flags the activity as having an invalid connection. |
 
 ## Anti-patterns
 
-- **Do NOT** modify the `WorkflowStart` activity — it is system-generated. Add user activities AFTER it inside the root sequence.
-- **Do NOT** omit `export.as` on activities whose output later activities need. Without `export`, only `$output` (the most recent activity's result) is visible.
-- **Do NOT** use YAML — the runtime parses JSON only.
-- **Do NOT** invent a `uip api-workflow build`, `uip api-workflow validate`, or `uip api-workflow publish` command. Build/publish goes through `uip solution pack` / `uip solution publish`. Validation is `uip api-workflow run` (with or without `--no-auth` depending on the user's choice — see rule 20).
-- **Do NOT** treat activity keys as cosmetic — they are the keys downstream activities use to read outputs (`$context.outputs.<ActivityKey>`).
-- **Do NOT** use boolean `true` for Break — must be string `"true"`. Same for `then: "exit"` / `then: "end"` — these are control-flow keywords as strings.
-- **Do NOT** read workflow inputs as `$input.<name>` from any non-first activity — use `$workflow.input.<name>`.
-- **Do NOT** reuse activity keys across nested scopes. `If_1#Then` cannot appear in two Ifs even at different levels — increment to `If_2`. See [control-flow-patterns.md](references/control-flow-patterns.md#core-structural-rules).
-- **Do NOT** reuse iteration variable names across nested loops. Inner `currentItem` shadows outer `currentItem`. Use distinct names per nesting level.
-- **Do NOT** invent a `uiPathActivityTypeId` or hand-author the `metadata.configuration` blob for connector activities. Both must come from `uip api-workflow registry stub`. See [connector-activity-discovery.md](references/connector-activity-discovery.md).
-- **Do NOT** use `call: "http"` (the deprecated simple form) when asked to fetch data from a public REST API (catfacts, stock prices, weather, …). It is the model's default fallback from training data, but StudioWeb's `restoreFromTaskItem` rejects it — the activity renders as a "block" icon. The correct form is `call: "UiPath.Http"` (Http kind), generated by `uip api-workflow registry resolve` + `stub`. See [connector-activity-discovery.md](references/connector-activity-discovery.md) and the verified template at [assets/templates/connector-call-example.json](assets/templates/connector-call-example.json).
-- **Do NOT** nest `bodyParameters` fields for connector activities. `message.toRecipients` is a literal key, not a path. Nested `{ message: { toRecipients: ... } }` is wiped on save. See rule 16(a).
-- **Do NOT** wrap connector `bodyParameters` / `queryParameters` literals as `${'literal'}` — that's the Assign / Response rule. Connector params take bare literals. See rule 16(b).
-- **Do NOT** reconstruct the slot key or export-bucket key by hand on connector activities. Use `Data.SlotKey` and `Data.ExportBucketKey` from the stub output verbatim — they can differ (HTTP: slot `HttpRequest_1`, bucket `http_request_1`) or match (Outlook `ListEmails`: both `ListEmails_1`). See rule 16(c).
-- **Do NOT** skip `uip api-workflow registry stub`. It calls IS Elements internally to fetch the full endpoint path (with hub prefix) and the multipart signal — both of which the TypeCache alone misses. Hand-authoring the activity from the `resolve` output skips that enrichment.
-- **Do NOT** skip `uip is connections ping` for vendor (IntSvc kind) activities. A connection that lists as `Enabled` can still be broken. The ping is the only way to catch it before the workflow 401s in cloud. See rule 16.
-- **Do NOT** leave `<REPLACE_WITH_VENDOR_CONNECTION_UUID>` (or any `<REPLACE_WITH_*>` placeholder) in a generated workflow. StudioWeb's properties panel renders the literal placeholder string as if it were a real connection identifier — the connection pill displays the placeholder text with a red error. The placeholder is meaningful only inside the template file; once you copy the activity into the user's workflow, replace every placeholder with the value from `uip is connections ping` (UUID) or `--inputs` (URL). When you cannot find a pinged UUID, ask the user — do not paste the sentinel. See rule 16 step 6.
-- **Do NOT** invoke `uip api-workflow run` autonomously. Always ask the user first — and especially never run with auth without an explicit "yes." Vendor calls have real side effects (emails sent, tickets created). See rule 20.
-- **Do NOT** send `application/json` to a multipart endpoint. If `parameters` shows `"type": "multipart"`, declare `multipartParameters` on the activity. See rule 16.
-- **Do NOT** trust `registry stub`'s `queryParameters` / `pathParameters` / `bodyParameters` as complete. The stub drops `required: true` fields. Cross-check with `uip is resources describe --operation <op> --connection-id <uuid>` after every stub call. See rule 16 step 4.
-- **Do NOT** skip the Solution catalogue sync for Solutions-mode IntSvc kind activities. The properties-panel "invalid connection" / "resource definition page" error AND the connectionId nulling on activity click both stay until BOTH the catalogue file (`Solution/resources/solution_folder/connection/<connector-key>/<name>.json`) AND the per-user debug overwrites (`Solution/userProfile/<guid>/debug_overwrites.json`) exist. Run `uip api-workflow bindings sync --workflow <Workflow.json>` followed by `uip solution resource refresh --solution-folder <path>` after every `registry stub --connection-id` for Solutions-mode IntSvc kind activities. See rule 16 step 7.
+The mistakes an agent makes most often (each maps to a Critical Rule above — see it for the full reasoning):
+
+- **Do NOT** use `call: "http"` for a REST call — it's the training-data default, but StudioWeb rejects it (renders as a "block" icon). Use `call: "UiPath.Http"` from `registry stub`. See rule 16.
+- **Do NOT** wrap connector `bodyParameters` / `queryParameters` literals as `${'literal'}` — rule 5's wrap is **inverted** for connectors; bare literals only, or the field clears on save. See rule 16.
+- **Do NOT** ship a `<REPLACE_WITH_*>` placeholder in a workflow — StudioWeb renders it as a broken connection and it 401s. No pinged UUID → ask the user. See rule 16.
+- **Do NOT** read workflow inputs as `$input.<name>` from a non-first activity — use `$workflow.input.<name>`. See rule 13.
+- **Do NOT** invoke `uip api-workflow run` autonomously, and never with auth without an explicit "yes" — vendor calls have irreversible side effects (emails sent, tickets created). See rules 20–21.
 
 ## Infinite Loop Prevention