@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-agents/references/lowcode/prompting/conversational-agent-prompting-guide.md

@@ -0,0 +1,123 @@
+# Conversational Agents Prompting Guide
+
+This is the prompting guide for low-code conversational agents.
+
+## 1. System-prompt skeleton
+
+The nature of conversational agents means that they involve multi-turn interaction with the user with flexible response shapes. Thus, conversational system prompts are more flexible than autonomous prompts; the following system-prompt skeleton serves as a starting point, not a contract. Adapt this skeleton to the use case: slots can be dropped or extended based on requirements and domain-specific goal(s).
+
+```text
+You are <ROLE> for <DOMAIN>. <ONE-LINE PURPOSE>. <DESCRIBE TONE — e.g. warm, concise, professional>.
+
+Scope:
+- In scope: <topics or tasks you engage with>
+- Out of scope: <what to refuse, deflect, or hand off>
+
+Conversation behavior:
+- Goals: <desired outcome(s) of the conversation>.
+- Steps: <expected sequence; may not be needed for free-form chat>.
+- Clarifications: <when to ask before answering>.
+- Confirmations: <when to confirm before actions>.
+
+Tools:
+- <toolName>: call when <explicit condition>. Do not call when <condition>.
+- <toolName>: ...
+- After tool use, explain <what to summarize, recommend, or ask next>.
+
+Response style:
+- Default to <length — e.g. 2–4 sentences>; expand on request.
+- Use <format — markdown, bullets, JSON, prose> when helpful.
+
+Uncertainty:
+- If <context> is missing or ambiguous, <ask clarifications / run tools> — do not guess.
+```
+
+Slot rules (flexible):
+- **Role + tone** — name the role, set the voice.
+- **Scope** — bound what the agent engages with. Without it the agent answers off-task prompts.
+- **Conversation behavior** — desired conversational outcomes and steps for how the agent should drive the conversation. Slots can be omitted/modified based on use-case.
+- **Tools** — Define use-case-specific triggers and non-triggers.
+- **Response style** — Set default length and format.
+- **Grounding** — State what the agent must not invent and which sources are authoritative for the domain. Cuts hallucination.
+
+> For conversational agents, you may also template per-exchange `inputSchema` fields into the **system prompt** (not the user message, which stays blank for conversational agents). See [agent-definition.md § Input Schema](../agent-definition.md#input-schema). Only add `inputSchema` fields when the use case needs variable-based context from the chat-UI beyond the conversation history and the user's input messages (which are already captured in the implicit `messages` field for all conversational-agents). Reference them as `{{input.<field>}}` and mirror in `messages[0].contentTokens` per [agent-definition.md § contentTokens Construction](../agent-definition.md#contenttokens-construction).
+
+> For low-code conversational agents, the above defined system-prompt within the `agent.json` will be wrapped by more prompt details in the agent-runtime which describes citation generation behavior (e.g. for web-urls and context-grounding results). Do not define citation-generation format in the system-prompt.
+
+## 2. User-prompt
+
+Leave user-message contents blank for low-code conversational agents in the `agent.json`. See [agent-definition.md § User Message](../agent-definition.md#user-message).
+
+## 3. Worked example — customer support chat
+
+Realistic conversational agent: an order-status helpdesk with one tool. Note `inputSchema` carrying a per-exchange `currentOrderNumber` (the order the user currently has open in the host UI) and **empty `outputSchema`** (runtime streams conversation events).
+
+`agent.json` excerpt:
+
+```json
+"settings": { "model": "anthropic.claude-sonnet-4-6", "temperature": 0, "maxTokens": 64000, "engine": "conversational-v1", "mode": "standard" },
+"inputSchema": {
+  "type": "object",
+  "properties": {
+    "currentOrderNumber": { "type": "string", "description": "Order number currently open in the host UI; supplied by the client on every exchange" }
+  },
+  "required": ["currentOrderNumber"]
+},
+"outputSchema": { "type": "object", "properties": {} }
+```
+
+System prompt (filled skeleton):
+
+```text
+You are an company's customer support assistant for online retail. Help customers with order status, delivery, and returns. Tone: warm, concise, professional.
+
+The customer currently has the following order open: {{input.currentOrderNumber}}.
+
+Scope:
+- In scope: order status, delivery estimates, returns and refunds, basic product questions.
+- Out of scope: pricing negotiations, escalations requiring human review — hand off to a human agent.
+
+Conversation behavior:
+- Goals: resolve the customer's queries about the currently opened order in as few turns as possible.
+- Steps: greet on turn 1, reference the opened order, and explain capabilities. Then answer the queries and confirm resolution.
+- Clarifications: if the customer asks about a different order, ask once for that order number.
+- Confirmations: confirm with the customer before initiating a return.
+
+Tools:
+- lookupOrder: call with the currently opened order number unless the customer specifies a different one. Use for status, delivery, or item details.
+- initiateReturn: call only after the customer confirms in plain language they want to start a return.
+- After tool use, summarize the result in 1-2 sentences and ask whether anything else is needed.
+
+Response style:
+- Default to 2-4 sentences; expand only when the customer asks for detail.
+- Use plain prose; switch to bullets for multi-item summaries (e.g., multiple shipment events).
+
+Uncertainty:
+- If `lookupOrder` returns no record, ask the customer to verify the order number — do not guess details.
+```
+
+User message: `""` — left blank. The Conversational Service injects the user turn each exchange.
+
+## 4. Production checklist — adjacent `agent.json` quality fields
+
+| Field | Default | Change when |
+|-------|---------|-------------|
+| `inputSchema` | `{ "properties": {} }` | Add fields only when per-exchange, variable-based context beyond conversation history is genuinely needed. Reserved names: `messages`, `uipath__*` ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Anti-patterns 4 and 5). |
+| `outputSchema` | `{ "type": "object", "properties": {} }` | **Never populate** — runtime streams events, does not fill output ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Anti-pattern 1). |
+| `messages[1].content` | `""` | **Keep blank** — Conversational Service injects the user turn at runtime ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Anti-pattern 3). |
+| `settings.temperature` | `0` | Raise for open-ended brainstorming or casual chats. Keep `0` for factual support flows. |
+| `settings.maxTokens` | `64000` | Set ≤ the model's `MaxTokens` cap — see [model-selection-guide.md](../model-selection-guide.md#1-discover-primary-path). |
+| `settings.model` | `anthropic.claude-sonnet-4-5-20250929-v1:0` | **Always verify** — discover + select per [model-selection-guide.md](../model-selection-guide.md). |
+| `guardrails` | `[]` | Custom (deterministic) Tool guardrails only — no built-in validators; mirror in tool `resource.json`. See [capabilities/guardrails/guardrails.md](../capabilities/guardrails/guardrails.md) ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Critical Rule 1). |
+
+## Anti-patterns
+
+- **Vague role** — "You are a helpful agentic assistant." Name the role and bound the scope.
+- **No tool-call criteria** — agent over-calls or under-calls tools.
+- **Long tool-call loops** - agent runtime may stop and require the user to confirm continuation after a single agent run (turn) consists of a series of over 8 steps that each involve tool-call(s). Note that this is not a limitation on total parallel tool-calls on any individual step, so aim to parallelize tool-calls when possible and/or ask for user-confirmation to break up long loops of sequential steps.
+- **Populating `outputSchema`** — runtime streams events; populated schemas never get filled and confuse the agent ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Anti-pattern 1).
+- **Templating data into the user message** — the user message content stays blank; per-exchange context goes into the **system prompt** via `inputSchema` templating.
+- **Adding `messages` or `uipath__*` to `inputSchema`** — reserved names; runtime injects ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Anti-patterns 4 and 5).
+- **Using built-in validator guardrails (PII, harmful content, etc.) or `Agent`/`Llm` scopes** — built-in validators are autonomous-only and silently ignored; conversational agents support only Custom deterministic `Tool`-scoped guardrails ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Critical Rule 1).
+- **Defining citation-generation format in the system prompt** — agent runtime wraps citation formatting around the prompt; redefining it conflicts or confuses citation generation (see § 1 callout).
+- **Cargo-culted `temperature`** — copying a nonzero temperature into a deterministic, factual-based conversation task.

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

@@ -222,7 +222,7 @@ The `solutionsSupport: "true"` metadata flag signals to the deployment engine th
 
 > **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 refresh`; 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/critical-rules.md](critical-rules/critical-rules.md) Anti-pattern 19 and [critical-rules/autonomous-critical-rules.md](critical-rules/autonomous-critical-rules.md) Anti-pattern 2.
 
 ## Debug Overwrites
 

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

@@ -65,7 +65,7 @@ Do NOT use for: `.flow` Maestro flows (→ `uipath-maestro-flow`), `.xaml` / cod
     - **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 + 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`.
+    - **IntSvc/vendor activities require a *pinged* connection.** `uip is connections ping <uuid>` must succeed before authoring — listing-state ≠ runtime-state; an `Enabled` connection can still 401 in cloud. An empty listing is NOT proof no connection exists — `uip is connections list` is folder-scoped. On empty/failed listing, walk the fallbacks in order: unfiltered `uip is connections list`, then `uip is connections list --all-folders` (catches connections in other folders), re-pinging a different `Id` for that `ConnectorKey` each time.
     - **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.
@@ -74,7 +74,18 @@ Do NOT use for: `.flow` Maestro flows (→ `uipath-maestro-flow`), `.xaml` / cod
     - **(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`.
+19. **Scaffold with `uip api-workflow init`; publish goes through the solution packager.** Create every API workflow project with `uip api-workflow init <name>` (rule 19a) — never hand-assemble the project files. Project-level CLI commands also exist: `uip api-workflow build <projectDir>` (compile) and `uip api-workflow pack <projectDir> <outputDir>` (single-project `.nupkg`, useful to test one project in isolation). Solution-level build/publish go through `uip solution pack <solutionDir> <outputDir>` + `uip solution publish <package.zip>`. There is NO `uip api-workflow publish` command. Project type must be `"Api"` in the solution `.uipx`.
+
+19a. **Create projects with `uip api-workflow init <name>` — it produces the correct Studio Web editable shape and wires the solution.** Run it from inside the solution directory (the folder containing the `.uipx`):
+    ```bash
+    uip api-workflow init <name> --output json   # add --skip-solution-registration for a standalone (no .uipx) project
+    ```
+    It scaffolds `project.uiproj` + `Workflow.json` + `entry-points.json` + `bindings_v2.json` and, when run inside a solution, **auto-registers the project in the surrounding `.uipx`** (correct `ProjectRelativePath` + a fresh `Id`). Success → `Code: "ApiWorkflowInit"`. Then edit `Workflow.json` only.
+
+    **Why it matters:** a legacy `project.json` + `workflows/WF_*.json` layout (no `.uiproj`) passes every runtime gate — `validate`, `run`, `pack`, `publish`, deploy — but Studio Web rejects it as `invalid_project_folder` and never shows it. `init` is the one step that can't produce the wrong shape. Full layout + field rules: [references/workflow-file-format.md](references/workflow-file-format.md#project-structure-studio-web-editable-contract).
+
+    To **convert a legacy `project.json` project**, `init` a fresh sibling and move the existing workflow content into its `Workflow.json` (cleanest), or convert in place — see [references/troubleshooting.md](references/troubleshooting.md). Never wire it with `uip solution project add/remove` (errors on an already-registered name; `remove`+`add` destroys the project `Id`).
+
 20. **`uip api-workflow validate <Workflow.json>` is the autonomous closure step for every authoring or edit cycle.** Run it as the LAST command before asking the user anything about runtime. It's offline (no auth, no network, no side effects): JSON Schema + semantic checks on the static file. Output codes:
     - `Result: "Success"`, `Code: "ApiwfValidate"`, `Data.Status: "Valid"` (exit 0) — possibly with `Data.Warnings`. Proceed to rule 21 (ask the user whether to run).
     - `Result: "Failure"` (exit 1) — do NOT bother the user. Read `Instructions`, locate the offending activity by its JSON path (e.g. `/do/0/Sequence_1/do/2/Mystery_1/metadata/activityType`), edit `Workflow.json` to fix it, then re-validate. Loop until pass.
@@ -173,7 +184,7 @@ Fix run failures in category order — **Structure > Expression > Activity Confi
 
 ### Phase 4: Package and Publish
 
-Once the workflow runs locally, deploy via the solution packager.
+Once the workflow runs locally, deploy via the solution packager. If the project must open in Studio Web, confirm it uses the `init`-produced shape first (rule 19a) — runtime/pack success does not prove it.
 
 **Pack:**
 ```bash
@@ -197,20 +208,26 @@ Requires `uip login`.
 ## Quick Start (CREATE from scratch)
 
 ```bash
-# 1. Copy the empty template
-cp ./.claude/plugins/uipath/skills/uipath-api-workflow/assets/templates/api-workflow-template.json \
-   ./MyApiProject/main.json
+# 0. Create the solution (skip if one already exists). Creates ./MySolution/ with the .uipx.
+uip solution init MySolution --output json
+
+# 1. Scaffold the project — correct Studio Web shape + auto-registers in the .uipx (rule 19a).
+#    init's <name> arg takes no slashes, so cd into the solution dir first; it registers the
+#    project in the nearest parent .uipx. Creates MyApiProject/ with project.uiproj,
+#    Workflow.json, entry-points.json, bindings_v2.json.
+cd ./MySolution
+uip api-workflow init MyApiProject --output json
 
-# 2. Edit main.json to add user activities after WorkflowStart inside the root sequence
+# 2. Edit MyApiProject/Workflow.json to add user activities after WorkflowStart inside the root sequence
 
 # 3. Validate (offline, autonomous — fix + re-validate until Status: Valid)
-uip api-workflow validate ./MyApiProject/main.json --output json
+uip api-workflow validate ./MyApiProject/Workflow.json --output json
 
 # 4. Ask the user, then run (only on user "yes")
-uip api-workflow run ./MyApiProject/main.json --no-auth --output json
+uip api-workflow run ./MyApiProject/Workflow.json --no-auth --output json
 
-# 5. Package
-uip solution pack ./MySolution ./build --name MyApiSolution --version 1.0.0 --output json
+# 5. Package (cwd is the solution dir)
+uip solution pack . ./build --name MyApiSolution --version 1.0.0 --output json
 
 # 6. Publish
 uip login
@@ -227,7 +244,7 @@ uip solution publish ./build/MyApiSolution.zip --tenant MyTenant --output json
 | [references/control-flow-patterns.md](references/control-flow-patterns.md) | Combining activities into hierarchical structures — nested If, ForEach inside DoWhile, TryCatch around/inside loops, conditional Break, multi-way branching, key uniqueness rules |
 | [references/connector-activity-discovery.md](references/connector-activity-discovery.md) | Authoring HTTP Request / Gmail / Outlook / GitHub / Slack / etc. activities via `uip api-workflow registry resolve` + `stub` — three-step flow, sample stub output, field-shape rules, multipart subsection, worked examples |
 | [references/expressions-and-context.md](references/expressions-and-context.md) | Writing JS expressions, propagating outputs via `export.as`, accessing `$context` / `$input` / `$workflow`, JS_Invoke argument passing, strict-mode gotchas, key patterns |
-| [references/cli-reference.md](references/cli-reference.md) | All `uip` commands — `api-workflow run`, `solution pack`, `solution publish`, `solution new`, `login` |
+| [references/cli-reference.md](references/cli-reference.md) | All `uip` commands — `api-workflow init`, `run`, `build`, `pack`, `validate`, `solution init`, `solution pack`, `solution publish`, `login` |
 | [references/troubleshooting.md](references/troubleshooting.md) | Failed runs, structure/expression/loop/nesting/response/validation pitfalls, packaging errors, publish errors, debugging strategy |
 
 ## Templates
@@ -251,6 +268,9 @@ The mistakes an agent makes most often (each maps to a Critical Rule above — s
 - **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.
+- **Do NOT** hand-assemble a project (`project.json` + `main.json`/`workflows/WF_*.json`). Scaffold with `uip api-workflow init <name>` — it writes the correct `project.uiproj` shape and registers it in the `.uipx`. The legacy `project.json`-only shape runs and packs but Studio Web rejects it (`invalid_project_folder`) and never shows it. See rules 19–19a.
+- **Do NOT** wire a project into the solution with `uip solution project add/remove` — it errors on an already-registered name, and `remove`+`add` destroys the project `Id`. `init` registers it; for an already-built project, edit the `.uipx` `ProjectRelativePath` in place. See rule 19a.
+- **Do NOT** trust "it packed / published / ran" as proof a project opens in Studio Web — every runtime gate passes on the wrong shape. Scaffolding with `init` is what guarantees it (rule 19a).
 
 ## Infinite Loop Prevention
 

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

@@ -2,6 +2,88 @@
 
 All `uip` commands relevant to authoring, running, packaging, and publishing API workflows. The api-workflow-tool ships with `@uipath/cli` (no separate install).
 
+## `uip api-workflow init`
+
+Scaffold a new API workflow project in the **correct Studio Web editable shape**. This is the canonical way to create a project — do NOT hand-assemble the files.
+
+```bash
+uip api-workflow init <name> \
+  [--force] \
+  [--skip-solution-registration] \
+  [--output json]
+```
+
+| Argument / Flag | Required | Description |
+|-----------------|----------|-------------|
+| `<name>` | yes | Project name (and folder created under the cwd). Letters, numbers, spaces, `_`, `-` only. |
+| `--force` | no | Write files even if the target directory is non-empty (does not clear existing contents). |
+| `--skip-solution-registration` | no | Do NOT auto-register the project in the surrounding solution `.uipx`. Use for standalone (CLI-only) projects. |
+
+Run it from inside the solution directory (the folder containing the `.uipx`) so it auto-registers the project. It writes four files into `<name>/`:
+
+| File | Content |
+|------|---------|
+| `project.uiproj` | `{ "ProjectType": "Api", "Name": "<name>", "Description": null, "MainFile": "Workflow.json" }` |
+| `Workflow.json` | The `WorkflowStart` skeleton (same as the empty template) |
+| `entry-points.json` | `$schema`/`$id`, one entry: `filePath: "content/Workflow.json"`, fresh `uniqueId`, `type: "Api"`, `input`/`output` null |
+| `bindings_v2.json` | `{ "version": "2.0", "resources": [] }` |
+
+When run inside a solution, it also appends the project to the `.uipx` `Projects` array (`ProjectRelativePath: "<name>/project.uiproj"`, a fresh `Id`, `Type: "Api"`). It does NOT write `.local/ProjectSettings.json` — Studio Web creates that on first open; do not author it by hand.
+
+### Success output
+
+```json
+{
+  "Result": "Success",
+  "Code": "ApiWorkflowInit",
+  "Data": {
+    "Status": "Created successfully",
+    "Path": "<projectDir>",
+    "SolutionRegistration": { /* registration result; NextSteps when applicable */ }
+  }
+}
+```
+
+Failure (`Result: "Failure"`, exit 1) on an invalid name or a non-empty directory without `--force` (`Message: "Failed to create API Workflow project"`, details in `Instructions`).
+
+## `uip api-workflow build`
+
+Build (compile) a single API workflow project — a fast project-scoped check that does not touch unrelated projects in a solution.
+
+```bash
+uip api-workflow build <project-path> [--output json]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<project-path>` | yes | Path to the API workflow project directory or `.uip` file. |
+
+Output: `{ "Result": "Success", "Code": "ApiWorkflowBuild", "Data": { "Success": true } }`. Exit 1 on failure.
+
+## `uip api-workflow pack`
+
+Pack a single API workflow project into a `.nupkg`. Use to verify one project in isolation; full solution packaging still goes through `uip solution pack`.
+
+```bash
+uip api-workflow pack <project-path> <destinationPath> \
+  [--package-id <id>] \
+  [--package-version <version>] \
+  [--signing-certificate-path <path>] \
+  [--signing-certificate-password <password>] \
+  [--signing-timestamp-server <url>] \
+  [--output json]
+```
+
+| Argument / Flag | Required | Description |
+|-----------------|----------|-------------|
+| `<project-path>` | yes | API workflow project directory or `.uip` file. |
+| `<destinationPath>` | yes | Directory where the `.nupkg` is written. |
+| `--package-id <id>` | no | NuGet package ID. |
+| `--package-version <version>` | no | NuGet package version. |
+| `--signing-*` | no | Optional package signing (certificate path/password, timestamp server). |
+
+Output: `{ "Result": "Success", "Code": "ApiWorkflowPack", "Data": { "Success": true, "Packages": ["<path>.nupkg"] } }`. Exit 1 on failure.
+
 ## `uip api-workflow run`
 
 Execute an API workflow JSON file locally using the Serverless Workflow executor.
@@ -132,6 +214,7 @@ uip api-workflow registry stub <activity-type-id> \
 | `--instance <n>` | no | Suffix for slot/export bucket key. Default `1`. `--instance 2` produces `<Name>_2` keys. |
 | `--slot-key <PascalCase>` | no | Override the auto-derived PascalCase slot key. The export bucket key always derives from `objectName + "_<n>"` (both Curated and Generic) and is not affected by this flag. |
 | `-i, --inputs <json>` | no | JSON object mapping field names to values. Field names match the IS schema (flat dotted keys — `"message.subject"`, not `{message:{subject:…}}`). Pass bare strings for literals; `${...}` for expression references. |
+| `--resource-key <field>=<key>` | no (repeatable) | Bind a Solution-resource picker field (listed in `Data.SolutionResourceFields`) to a solution resource **key**, so StudioWeb's picker renders the selection. The key is the `key` field of the matching file under the solution's `resources/` tree (e.g. `resources/solution_folder/process/process/<Name>.json`). The field's *value* (the resource name) still goes via `--inputs`. Requires a StudioWeb build with `savedResourceSelections` support; older builds ignore the entry (runtime unaffected). |
 
 Success output:
 ```json
@@ -152,7 +235,7 @@ Success output:
 }
 ```
 
-`Data.Activity` drops directly into the root sequence's `do` array. `Data.ExportBucketKey` is what `$context.outputs.<X>` reads as downstream — bind expressions against this, NOT against `Data.SlotKey`. `Data.Parameters` (query/path/multipart) and `Data.RequestFields` (body) list the operation's inputs with `required` flags; `Data.ResponseFields` lists the fields the IS schema says will be present on the activity output (under `.content.<field>` for IntSvc kind).
+`Data.Activity` drops directly into the root sequence's `do` array. `Data.ExportBucketKey` is what `$context.outputs.<X>` reads as downstream — bind expressions against this, NOT against `Data.SlotKey`. `Data.Parameters` (query/path/multipart) and `Data.RequestFields` (body) list the operation's inputs with `required` flags; `Data.ResponseFields` lists the fields the IS schema says will be present on the activity output (under `.content.<field>` for IntSvc kind). `Data.SolutionResourceFields` (when present) lists fields StudioWeb renders as Solution-resource pickers — see [Solution resources as activity fields](connector-activity-discovery.md#solution-resources-as-activity-fields-run-job-add-queue-item-) for the authoring recipe.
 
 `Data.Warnings` (when present):
 - `"IS Elements metadata could not be fetched…"` → IS schema lookup failed; stub uses fallback path `/<objectName>` and ships no `requestFields`. Endpoint may be wrong (no hub prefix, no multipart declaration).
@@ -207,7 +290,7 @@ See [connector-activity-discovery.md](connector-activity-discovery.md) for the f
 
 ## `uip api-workflow bindings sync`
 
-Walk a `Workflow.json`, extract IntSvc-kind connector activities, and emit the canonical `bindings_v2.json` file next to it. Pure-local transformation — no auth, no API calls. This mirrors what StudioWeb computes in-memory via `computeBindings$` when a workflow is opened in the designer, and what `solution pack` writes at pack time. The output is the **required input** to `uip solution resources refresh`, which is what actually writes the Solution catalogue file AND per-user debug overwrites (the two artefacts StudioWeb's properties panel reads to resolve `connectionId` on activity click).
+Walk a `Workflow.json`, extract IntSvc-kind connector activities, and emit the canonical `bindings_v2.json` file next to it. Connection bindings are derived locally; **Solution-resource bindings** (process/queue/asset fields like Run Job's `ReleaseName`) are derived by querying IS metadata for each activity's object — when IS is unreachable, generation is skipped and any pre-existing entries of those kinds are preserved rather than dropped. This mirrors what StudioWeb computes in-memory via `computeBindings$` when a workflow is opened in the designer, and what `solution pack` writes at pack time. The output is the **required input** to `uip solution resources refresh`, which is what actually writes the Solution catalogue file AND per-user debug overwrites (the two artefacts StudioWeb's properties panel reads to resolve `connectionId` on activity click).
 
 **When to run.** After every `registry stub --connection-id <uuid>` that adds an IntSvc activity to a workflow inside a `Solution/` tree. Always paired with `uip solution resources refresh` (the next step in the typical sequence).
 
@@ -232,15 +315,17 @@ Success output:
   "Code": "BindingsSync",
   "Data": {
     "BindingsPath": "<dir>/bindings_v2.json",
-    "ResourceCount": 1,
+    "ResourceCount": 2,
     "ActivitiesVisited": 1,
     "IntSvcActivities": 1,
-    "DuplicatesCollapsed": 0
+    "DuplicatesCollapsed": 0,
+    "ResourceBindings": 1,
+    "PreservedResources": 0
   }
 }
 ```
 
-`ResourceCount` is the number of unique connections in the output (one binding per unique UUID). `DuplicatesCollapsed` reports activities that shared a connection — two Outlook activities reading the same mailbox count as 1 binding, with `DuplicatesCollapsed: 1`.
+`ResourceCount` is the total entries written (connections + resource bindings + preserved). `DuplicatesCollapsed` reports activities that shared a connection — two Outlook activities reading the same mailbox count as 1 binding, with `DuplicatesCollapsed: 1`. `ResourceBindings` counts Solution-resource entries generated from IS metadata (e.g. `process | RPA Workflow` for a Run Job activity); `PreservedResources` counts pre-existing non-connection entries carried over because this run did not regenerate them.
 
 Failure modes:
 - `"Workflow file not found: <path>"` — `--workflow` does not exist. Pass an existing path.
@@ -311,23 +396,23 @@ Sample output (Outlook `getNewestEmail`, `--operation List`):
 
 For every entry with `required: true`, confirm the stub's emitted activity has a value at `with.<location>Parameters.<name>`. Re-stub with `--inputs '{"<name>":"<value>"}'` or hand-edit. See [connector-activity-discovery.md — Required-field cross-check](connector-activity-discovery.md#required-field-cross-check--the-stub-drops-required-true-request-fields) and [troubleshooting.md](troubleshooting.md#required-request-field-dropped-by-registry-stub).
 
-## `uip solution new`
+## `uip solution init`
 
-Create an empty solution file. Required before adding API workflow projects.
+Initialize a new empty solution. Required before adding API workflow projects. (Formerly `uip solution new` — that verb was retired; `new` now errors `unknown command 'new'`.)
 
 ```bash
-uip solution new <solutionName> [--output json]
+uip solution init <solutionName> [--output json]
 ```
 
 | Argument | Description |
 |----------|-------------|
-| `<solutionName>` | Solution name or path. Appends `.uipx` if no extension. Creates a folder with the same base name. |
+| `<solutionName>` | Solution name or path. Creates a directory with this name containing a `.uipx` manifest (empty `Projects` array) plus `AGENTS.md`/`CLAUDE.md` briefing files. |
 
-Output: `{ "Result": "Success", "Code": "SolutionNew", "Data": { "Path": "<file>" } }`.
+Output: `{ "Result": "Success", "Code": "SolutionInit", "Data": { "Status": "Created successfully", ... } }`.
 
 ## `uip solution project add` *(scope: solution-tool)*
 
-Add an API workflow project (folder containing `project.json` with `Type: "Api"`) to a solution. See `uip solution project add --help` for current flags.
+For **new** API workflow projects, prefer `uip api-workflow init <name>` run inside the solution directory — it scaffolds the correct `project.uiproj` shape AND auto-registers the project in the `.uipx`. `uip solution project add` errors (`Project name already exists`) on an already-registered project, and `remove`+`add` destroys the project `Id`. Reserve direct `.uipx` edits for converting a legacy `project.json` project in place (change only `ProjectRelativePath` → `<folder>/project.uiproj`, preserve `Id`/`Type`). A registerable project folder must contain `project.uiproj` (`ProjectType: "Api"`) + `Workflow.json` + `entry-points.json` — see [workflow-file-format.md](workflow-file-format.md#project-structure-studio-web-editable-contract) and SKILL.md rule 19a. See `uip solution project add --help` for current flags.
 
 ## `uip solution pack`
 
@@ -353,7 +438,7 @@ uip solution pack <solutionPath> <outputPath> \
 
 For each `Type: "Api"` project:
 
-1. Validates project structure (must contain `project.json`)
+1. Reads the project file — `project.uiproj` (`ProjectType: "Api"`) for the Studio Web editable shape — and the entry point from `entry-points.json`
 2. Copies workflow JSON files to a clean output directory
 3. Generates `operate.json` — runtime configuration consumed by the executor
 4. Generates `package-descriptor.json` — manifest for the Cloud platform
@@ -398,22 +483,26 @@ Activate / configure / inspect a published solution. Subcommands: `deploy run`,
 ## End-to-End Example
 
 ```bash
-# 1. Author the workflow
-cp ./.claude/plugins/uipath/skills/uipath-api-workflow/assets/templates/api-workflow-template.json \
-   ./MyApiProject/main.json
-# ... edit main.json to add tasks ...
+# 0. (once) create the solution if you don't have one
+uip solution init MySolution --output json
+
+# 1. Scaffold the project in the correct Studio Web shape + register it in the .uipx (rule 19a).
+#    init's <name> takes no slashes — cd into the solution dir so it finds the parent .uipx.
+cd ./MySolution
+uip api-workflow init MyApiProject --output json
+# ... edit MyApiProject/Workflow.json to add tasks ...
 
 # 2. Local smoke test
-uip api-workflow run ./MyApiProject/main.json --no-auth --output json
+uip api-workflow run ./MyApiProject/Workflow.json --no-auth --output json
 
 # 3. Authenticate (only needed for publish / deploy)
 uip login
 
 # 4. Authenticated run
-uip api-workflow run ./MyApiProject/main.json --output json
+uip api-workflow run ./MyApiProject/Workflow.json --output json
 
 # 5. Pack the solution
-uip solution pack ./MySolution ./build \
+uip solution pack . ./build \
   --name MyApiSolution \
   --version 1.0.0 \
   --output json
@@ -428,8 +517,7 @@ uip solution publish ./build/MyApiSolution.zip \
 
 The agent should not invent these — they are NOT part of the api-workflow-tool surface:
 
-- `uip api-workflow publish` <!-- uip-check-skip -->
-- `uip api-workflow init` <!-- uip-check-skip -->
+- `uip api-workflow publish` <!-- uip-check-skip --> (publish goes through `uip solution publish`)
 - `uip apw <anything>` (no alias) <!-- uip-check-skip -->
 
-Build / publish go through `uip solution pack` / `uip solution publish`. Validation is done by running with `--no-auth`.
+These DO exist (don't route around them): `uip api-workflow init` (scaffold), `uip api-workflow build` (compile one project), `uip api-workflow pack` (one-project `.nupkg`). Solution-level packaging/publishing go through `uip solution pack` / `uip solution publish`. Offline validation is `uip api-workflow validate` (or running with `--no-auth`).

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

@@ -18,6 +18,8 @@ Without both, the designer renders the activity as a "block / forbidden" card an
 ```
 1. uip api-workflow registry resolve "<keyword>" --output json     → candidate GUIDs
 2. (IntSvc kind only) uip is connections list <connector-key>           → connection UUID
+     empty? → uip is connections list                              → fallback: unfiltered
+     still empty? → uip is connections list --all-folders          → fallback: other folders
    uip is connections ping <uuid>                                  → REQUIRED — verify it works
 3. uip api-workflow registry stub <activity-type-id> \             → ready-to-paste activity
      [--connection-id <uuid>] [--inputs '<json>'] --output json
@@ -92,7 +94,7 @@ Skip this step if `connectorKey === "uipath-uipath-http"` — the HTTP connector
 uip is connections list <connector-key> --output json
 ```
 
-Returns connections for that connector. Pick the `Id` of an `Enabled` connection (prefer `IsDefault: "Yes"` if multiple). If none exist, the user must create one in Integration Service before authoring can complete.
+Returns connections for that connector. Pick the `Id` of an `Enabled` connection (prefer `IsDefault: "Yes"` if multiple). If this returns empty, do NOT conclude none exist — the listing is folder-scoped; run the unfiltered and `--all-folders` fallbacks below first.
 
 ```bash
 uip is connections ping <connection-uuid> --output json
@@ -103,7 +105,7 @@ This is **not optional**. A connection that exists in the listing can still be i
 - `Code: "ConnectionPing"` (success) → connection is healthy, proceed to Step 3.
 - `Code: "ConnectionNotEnabled"` or 404 `"Connection [<uuid>] is invalid or you do not have access to it"` → **DO NOT proceed**. The connection is broken. Run the fallback below before aborting.
 
-**Fallback — unfiltered listing.** Filtered `uip is connections list <connector-key>` can return orphaned records that don't appear in the unfiltered list (and vice versa). When the filtered listing's UUID fails to ping, run:
+**Fallback 1 — unfiltered listing.** Filtered `uip is connections list <connector-key>` can return orphaned records that don't appear in the unfiltered list (and vice versa). When the filtered listing's UUID fails to ping, run:
 
 ```bash
 uip is connections list --output json
@@ -111,7 +113,15 @@ uip is connections list --output json
 
 (no connector argument) and search the result for entries whose `ConnectorKey` matches the one you need. If a different UUID exists for the same connector, ping that one. Often the working connection is only visible in the unfiltered listing.
 
-Only after both the filtered AND unfiltered listings have been exhausted (no UUID for that `ConnectorKey` pings cleanly) should you abort and tell the user to either re-authenticate (`uip is connections edit <connection-uuid>` opens a browser for OAuth) or create a fresh connection in the StudioWeb UI. **Do NOT author a workflow against a connection that hasn't pinged successfully** — it will 401 in cloud regardless of how correct the workflow JSON is.
+**Fallback 2 — all folders.** Both listings above are scoped to the current folder. A connection living in a *different* folder returns **empty from both** — `"No connections found"` does NOT mean the tenant has no connection. Before concluding none exists, search across every folder:
+
+```bash
+uip is connections list --all-folders --output json
+```
+
+Returns connections from all folders (each row carries a `Folder` / `FolderKey`). Pick an `Enabled` row whose `ConnectorKey` matches and ping its `Id`. `--all-folders` cannot be combined with `--folder`/`--folder-key`. This is the single most common reason a working connection appears "missing" — always run it before aborting.
+
+Only after the filtered, unfiltered, AND `--all-folders` listings have been exhausted (no UUID for that `ConnectorKey` pings cleanly) should you abort and tell the user to either re-authenticate (`uip is connections edit <connection-uuid>` opens a browser for OAuth) or create a fresh connection in the StudioWeb UI. **Do NOT author a workflow against a connection that hasn't pinged successfully** — it will 401 in cloud regardless of how correct the workflow JSON is.
 
 ### Step 3 — Stub the activity
 
@@ -279,7 +289,7 @@ uip api-workflow bindings sync --workflow Solution/<ProjectName>/Workflow.json -
 uip solution resources refresh --solution-folder Solution --output json
 ```
 
-`bindings sync` is pure-local (no auth, no API calls) — it walks `Workflow.json`, extracts IntSvc connector activities, and writes the canonical `bindings_v2.json` next to the workflow (one binding per unique connection UUID — two activities sharing a connection collapse to one entry). This file is what StudioWeb computes in-memory on workflow open; emitting it offline avoids the "open in StudioWeb once first" detour.
+`bindings sync` walks `Workflow.json` and extracts IntSvc connector activities into the canonical `bindings_v2.json` next to the workflow. **Connection** bindings are derived locally (one binding per unique connection UUID — two activities sharing a connection collapse to one entry). **Solution-resource** bindings (process/queue/asset picker fields like Run Job's `ReleaseName`) are derived by querying IS metadata for each activity's object, so this step reaches the network when such fields are present; when IS is unreachable, resource-binding generation is skipped and any pre-existing entries of those kinds are preserved rather than dropped. This mirrors what StudioWeb computes in-memory on workflow open; emitting it offline avoids the "open in StudioWeb once first" detour.
 
 `solution resources refresh` then reads every project's `bindings_v2.json`, calls `@uipath/resource-builder-sdk`'s `addOrUpdateResourceToSolutionAsync` to write the catalogue files, and `editOverwritesAsync` to write the per-user debug overwrites. Requires `uip login` (the SDK looks up folder keys via Resource Catalog Service). Idempotent — re-runs only import new resources.
 
@@ -426,6 +436,35 @@ Generic-specific behavior to know:
 - **Path-parameter value formats are connector-specific.** `Retrieve`/`Update`/`Delete` endpoints take an id path param (e.g. `/repos/{repo}`) and the expected value format (name vs full name vs numeric id) varies and is sometimes wrong in the connector's own metadata — `uip is resources describe` shows the parameter's description and lookup hints. If the run 404s, cross-check by executing the same operation via `uip is resources run get <connector-key> <object-name> --connection-id <uuid> --query <param>=<value>`; if that also 404s, the connector's auto-generated metadata is broken upstream — pick a Curated activity or the Http kind instead.
 - **Quality varies by connector.** Generic operations are auto-generated from vendor API specs and are not hand-verified the way Curated ones are. Prefer a Curated activity when one exists for the job.
 
+### Solution resources as activity fields (Run Job, Add Queue Item, …)
+
+Some activity fields don't take free text — their value names another **Solution resource** (a process, queue, asset…). Orchestrator's Run Job is the canonical case: its `ReleaseName` field is the process to start. The stub flags these in `Data.SolutionResourceFields` (`{ name, kind, location }`). Authoring recipe:
+
+```bash
+# 1. Get the resource's NAME and KEY from the solution tree (no API call):
+#    resources/solution_folder/process/process/<Name>.json → spec.name + key
+# 2. Stub: name as the value, key as the picker binding
+uip api-workflow registry stub <run-job-guid> \
+  --connection-id <orchestrator-conn-uuid> \
+  --inputs '{"ReleaseName":"RPA Workflow"}' \
+  --resource-key 'ReleaseName=87ec3255-8ea6-446e-8237-8ff429d86032' \
+  --output json
+```
+
+What each layer gets, and from where:
+
+| Layer | Carried by | Authored via |
+|--|--|--|
+| Runtime (which process starts) | `bodyParameters.ReleaseName` = resource **name** | `--inputs` |
+| Job-result waiting | `with.executionType: "async"` + callback header | automatic (mirrored from IS metadata) |
+| Deployment rewiring | `bindings_v2.json` process entry (`NameFieldPath`) | automatic (`bindings sync`) |
+| StudioWeb picker display | `savedResourceSelections` in `metadata.configuration` | `--resource-key` |
+
+Notes:
+- The activity only starts successfully once a process with that name is deployed and visible to the connection (pack/publish/deploy first, or pre-existing).
+- The picker display requires a StudioWeb build with `savedResourceSelections` support; on older builds the entry is ignored — the picker shows empty until selected once manually, while runtime and deployment remain correct.
+- Do NOT put the resource **key** in `--inputs` (runtime would send a GUID where the API expects a name) and do NOT put the **name** in `--resource-key` (the picker resolves by key).
+
 ## Vendor curated activity response shape — `content.X`, not `X`
 
 The output of a IntSvc kind (`UiPath.IntSvc`) call is wrapped: the actual vendor payload lives under `.content`, not at the root of the activity output. Reading the payload as `$context.outputs.<Activity>.X` returns `undefined`. Correct paths: `$context.outputs.<Activity>.content.<field>` for single-item operations, or `$context.outputs.<Activity>.content[<index>].<field>` for list ops. The IS proxy strips vendor-native list envelopes (e.g. M365 Graph's `{value: [...]}` → `.content: [...]` directly) — **never assume `.content.value[]`**. To know which shape applies: read the stub's `optionalConfiguration.fieldsContainer.outputJsonSchema` — `type: "object"` is single, `type: "array"` is list.