@uipath/skills 1.195.0 → 1.196.0

package/skills/uipath-rpa/references/coded/coding-guidelines.md

@@ -232,7 +232,7 @@ C) <user-driven approach>
 | **No Studio instances found** | Only relevant for `diff` / `focus-activity` — they need Studio Desktop. Every other command runs headless and doesn't need a Desktop instance. | Run `uip rpa studio start --project-dir "<PROJECT_DIR>"` if you actually need Studio Desktop; otherwise re-run the command — headless Studio relaunches automatically |
 | **Stale pipe / ENOENT** | Studio instance crashed or was closed | The tool retries automatically; if persistent, re-run the command (headless) or restart Studio Desktop |
 | **Workflow cannot be found** | Entrypoint not in project.json | Verify project.json entrypoint has the file listed (Process projects only — Tests and Library projects do not use `entryPoints`) |
-| **Service property not available** | Missing package dependency | Install the required package via `uip rpa packages install --project-dir "<PROJECT_DIR>" --packages '[{"id":"<PACKAGE_ID>"}]' --output json` (no `add-dependency` command exists; do not hand-edit `project.json`) |
+| **Service property not available** | Missing package dependency | Install the required package via `uip rpa packages install --project-dir "<PROJECT_DIR>" --packages id=<PACKAGE_ID> --output json` (no `add-dependency` command exists; do not hand-edit `project.json`) |
 | **Timeout** | Studio took too long to start. First headless call on a cold NuGet cache can take 30–90 s. | Increase timeout: `--timeout 600` |
 | **"Target name 'X' is not part of the current screen"** | Element descriptor used on wrong screen handle | Use the `UiTargetApp` handle from `Open`/`Attach` for the screen that owns the element |
 | **"Cannot select item. It was not found among existing items"** | `SelectItem` fails on web dropdowns | Use `TypeInto` instead of `SelectItem` for web `<select>` elements |

package/skills/uipath-rpa/references/coded/operations-guide.md

@@ -392,15 +392,15 @@ namespace MyProjectName
 
 ## Add a Dependency
 
-Canonical CLI: `uip rpa packages install`. Do NOT hand-edit `project.json` `dependencies`. **There is no `uip rpa add-dependency` command** — agents that try it get `Unknown command: add-dependency`. See [cli-reference.md § packages install](../cli-reference.md).
+Canonical CLI: `uip rpa packages install`. Do NOT hand-edit `project.json` `dependencies`. **There is no `uip rpa add-dependency` command** — agents that try it get `error: unknown command 'add-dependency'`. See [cli-reference.md § packages install](../cli-reference.md).
 
 **Steps:**
 1. Read `project.json` to check existing dependencies — skip packages already at the desired version.
 2. Run:
    ```bash
-   uip rpa packages install --project-dir "<PROJECT_DIR>" --packages '[{"id":"<PACKAGE_ID>","version":"<VERSION>"}]' --output json
+   uip rpa packages install --project-dir "<PROJECT_DIR>" --packages 'id=<PACKAGE_ID>,version=<VERSION>' --output json
    ```
-   Omit `version` to resolve the latest compatible. Pin a version only when there is a known compatibility constraint (see pinned versions below). The CLI writes `project.json` and runs restore — re-read `project.json` afterward if subsequent steps need it.
+   Omit `,version=<VERSION>` to resolve the latest compatible. Pin a version only when there is a known compatibility constraint (see pinned versions below). The CLI writes `project.json` and runs restore — re-read `project.json` afterward if subsequent steps need it.
 3. Only install packages the project actually needs.
 
 **Pinned versions for UiPath activity packages (current v25.x):**

package/skills/uipath-rpa/references/coded/third-party-packages-guide.md

@@ -7,7 +7,7 @@ When a user needs functionality that **no UiPath built-in activity provides** (e
 1. **Consider whether a built-in activity or plain .NET is the better fit** — prefer activities for Orchestrator integration, UI automation, and document handling; prefer .NET for data transforms, HTTP to external APIs, parsing, etc.
 2. **If no built-in activity fits** — search for a well-known .NET NuGet package that provides the capability
 3. **Inspect the package** — run the `uip rpa packages inspect` command with the appropriate flags in order to get exact API signatures before writing code
-4. **Install it** — run `uip rpa packages install --project-dir "<PROJECT_DIR>" --packages '[{"id":"<PACKAGE_ID>","version":"<VERSION>"}]' --output json`. Omit `version` to resolve the latest compatible. Do NOT hand-edit `project.json` `dependencies`. **There is no `uip rpa add-dependency` command.**
+4. **Install it** — run `uip rpa packages install --project-dir "<PROJECT_DIR>" --packages 'id=<PACKAGE_ID>,version=<VERSION>' --output json`. Omit `,version=<VERSION>` to resolve the latest compatible. Do NOT hand-edit `project.json` `dependencies`. **There is no `uip rpa add-dependency` command.**
 5. **Write C# code using the package** — use the package's API directly in the `Execute` method (no service proxy needed — just `using` + direct API calls)
 
 ## How Third-Party Packages Differ from UiPath Activity Packages

package/skills/uipath-rpa/references/connector-capabilities.md

@@ -26,8 +26,9 @@ uip is activities list <connector-key> --output json
 # What data objects/resources does it expose?
 uip is resources list <connector-key> --output json
 
-# Describe a specific operation's schema (fields, types, required flags, enum values):
-uip is resources describe <connector-key> <operation-name> --operation Create --output json
+# Describe an object's schema for an operation (fields, types, required flags, enum values).
+# Second positional is the object/resource name (from `resources list`); the operation goes in --operation:
+uip is resources describe <connector-key> <object-name> --operation Create --output json
 ```
 
 `resources describe` is the authoritative field schema — **never guess field names**. The response includes a `metadataFile` path like `~/.uipath/cache/integrationservice/<connector>/_static/<operation>.Create.json`. Read that JSON directly for the full `parameters` / `requestFields` / `responseFields` list.

package/skills/uipath-rpa/references/debugging.md

@@ -25,15 +25,15 @@ Before invoking any of the above, run `uip rpa studio start --project-dir "<PROJ
 `run` and `debug start` take a file path and optional inputs:
 
 ```bash
-uip rpa run         --file-path <relative-path> [--input-arguments '<json>'] [--log-level <level>] [--skip-build] [--output json]
-uip rpa debug start --file-path <relative-path> [--input-arguments '<json>'] [--log-level <level>] [--skip-build] [--output json]
+uip rpa run         --file-path <relative-path> [--input-arguments key=value]... [--log-level <level>] [--skip-build] [--output json]
+uip rpa debug start --file-path <relative-path> [--input-arguments key=value]... [--log-level <level>] [--skip-build] [--output json]
 ```
 
 `debug test-activity` and `debug start-from-here` operate on the currently focused activity (no `--file-path`):
 
 ```bash
-uip rpa debug test-activity     [--input-arguments '<json>'] [--input-variables '<json>'] [--log-level <level>] [--output json]
-uip rpa debug start-from-here   [--input-arguments '<json>'] [--input-variables '<json>'] [--log-level <level>] [--output json]
+uip rpa debug test-activity     [--input-arguments key=value]... [--input-variables key=value]... [--log-level <level>] [--output json]
+uip rpa debug start-from-here   [--input-arguments key=value]... [--input-variables key=value]... [--log-level <level>] [--output json]
 ```
 
 All other `debug` verbs (`break`, `continue`, `resume`, `continue-retry`, `continue-ignore`, `step-into`, `step-over`, `step-out`, `toggle-breakpoint`, `restart-from-top`) take no parameters — they operate on the active debug session.
@@ -41,9 +41,9 @@ All other `debug` verbs (`break`, `continue`, `resume`, `continue-retry`, `conti
 | Parameter | Description |
 |-----------|-------------|
 | `--file-path` | Workflow file to run (relative to project root). Applies to `run` and `debug start` only |
-| `--input-arguments` | JSON object with project-level input arguments. Only for `run`, `debug start`, `debug test-activity`, and `debug start-from-here` (see [Input Variables vs Input Arguments](#input-variables-vs-input-arguments)) |
-| `--input-variables` | JSON object with workflow-level variable values. Only for `debug test-activity` and `debug start-from-here` (see [Input Variables vs Input Arguments](#input-variables-vs-input-arguments)) |
-| `--log-level` | Minimum log level: `Verbose`, `Trace`, `Information` (default), `Warning`, `Error`, `Critical` |
+| `--input-arguments` | Project-level input arguments as repeatable `key=value` pairs (`=` string, `:=` raw JSON; see [cli-reference.md § Passing structured inputs](cli-reference.md#passing-structured-inputs)). Only for `run`, `debug start`, `debug test-activity`, and `debug start-from-here` (see [Input Variables vs Input Arguments](#input-variables-vs-input-arguments)) |
+| `--input-variables` | Workflow-level variable values as repeatable `key=value` pairs (values are VB/C# expressions — always `=`). Only for `debug test-activity` and `debug start-from-here` (see [Input Variables vs Input Arguments](#input-variables-vs-input-arguments)) |
+| `--log-level` | Minimum log level: `Verbose`, `Trace` (default), `Information`, `Warning`, `Error`, `Critical` |
 | `--skip-build` | Skip the pre-run build step (use only when you've just built) |
 | `--output` | Output format: `json` (recommended), `table`, `yaml`, `plain` |
 | `--profiling` | Collect per-activity timings and runtime screenshots — verifies UI automation correctness and workflow performance. Only effective on start verbs (`run`, `debug start`, `debug test-activity`, `debug start-from-here`); ignored on stepping / breakpoint verbs. Boolean flag (no value needed). See [Profiling Workflow Performance](#profiling-workflow-performance). |
@@ -83,50 +83,52 @@ These serve different purposes and apply to different scopes:
 | **What they are** | Project-level parameters (In/Out/InOut) | Workflow-internal variables scoped to activities |
 | **Where defined** | Project argument list (visible in Studio's Arguments panel) | Inside the workflow (visible in Studio's Variables panel) |
 | **Applicable verbs** | `run`, `debug start`, `debug test-activity`, `debug start-from-here` | `debug test-activity`, `debug start-from-here` only |
-| **Value format (`run` / `debug start`)** | Plain JSON values: `{"name":"John","age":30}` | N/A |
-| **Value format (`debug test-activity` / `debug start-from-here`)** | VB.NET or C# expressions | VB.NET or C# expressions |
+| **Value format (`run` / `debug start`)** | `key=value` pairs (`=` string, `:=` raw JSON): `name=John`, `age:=30` | N/A |
+| **Value format (`debug test-activity` / `debug start-from-here`)** | VB.NET or C# expressions — always `=` | VB.NET or C# expressions — always `=` |
 
 ### Expression Value Examples
 
-For `debug test-activity` and `debug start-from-here`, both `--input-arguments` and `--input-variables` values must be **VB.NET or C# expressions** matching the project language.
+For `debug test-activity` and `debug start-from-here`, both `--input-arguments` and `--input-variables` values must be **VB.NET or C# expressions** matching the project language. Always use `=` pairs (the expression is a string — `:=` would corrupt it), one variable per flag occurrence. Expressions containing double quotes (string literals) cannot be passed inline on Windows PowerShell 5.1 — write them to a UTF-8 file and use `key=@file`.
 
 **VB.NET projects:**
 ```bash
-# String variable — VB string literal with escaped quotes
---input-variables '{"greeting": "\"Hello World\""}'
-
-# Integer variable
---input-variables '{"count": "42"}'
+# Integer variable — the expression 42
+--input-variables count=42
 
 # Boolean variable (VB uses True/False, capitalized)
---input-variables '{"isActive": "True"}'
+--input-variables isActive=True
 
 # Null / unset (VB keyword)
---input-variables '{"result": "Nothing"}'
+--input-variables result=Nothing
+
+# New object — single-quote tokens containing spaces
+--input-variables 'config=New Dictionary(Of String, Object)'
 
-# New object
---input-variables '{"config": "New Dictionary(Of String, Object)"}'
+# String variable — the expression needs quotes, so pass it from a file.
+#   PowerShell: Set-Content -Encoding UTF8 greeting.txt '"Hello World"'
+#   bash:       printf '"Hello World"' > greeting.txt
+--input-variables greeting=@greeting.txt
 
-# Multiple variables at once
---input-variables '{"name": "\"John\"", "age": "30", "isActive": "True"}'
+# Multiple variables at once — repeat the flag
+--input-variables name=@name-expr.txt --input-variables age=30 --input-variables isActive=True
 ```
 
 **C# projects:**
 ```bash
-# String variable
---input-variables '{"greeting": "\"Hello World\""}'
-
 # Boolean variable (C# uses true/false, lowercase)
---input-variables '{"isActive": "true"}'
+--input-variables isActive=true
 
 # Null / unset (C# keyword)
---input-variables '{"result": "null"}'
+--input-variables result=null
+
+# New object — single-quote tokens containing spaces
+--input-variables 'config=new Dictionary<string, object>()'
 
-# New object
---input-variables '{"config": "new Dictionary<string, object>()"}'
+# String variable — quoted literal goes through a file
+--input-variables greeting=@greeting.txt
 ```
 
-> **Important:** String values require the VB/C# string literal quotes *inside* the JSON value. A JSON string `"200"` becomes the expression `200` (an integer literal), not the string `"200"`. To pass the string `"200"`, use `"\"200\""`.
+> **Important:** values are committed as expression text. `count=42` yields the expression `42` (an integer literal). To pass the *string* `"200"`, the expression must contain the quotes — `"200"` — which survives only via the file form: `temperature=@expr.txt` with the file containing `"200"`. Whole payloads can also be loaded from a JSON file: `--input-variables '@vars.json'` (single-quote the `@` token in PowerShell) or `--input-variables-file vars.json`.
 
 ---
 
@@ -221,9 +223,11 @@ Use `debug test-activity` to run just the currently focused activity without exe
 # 1. Focus the activity to test (Studio Desktop required)
 uip rpa focus-activity --activity-id "DeserializeJson_1"
 
-# 2. Run it in isolation, pre-setting any variables it reads from
+# 2. Run it in isolation, pre-setting any variables it reads from.
+#    temperature is a String — its expression needs quotes, so pass it from a file:
+#    PowerShell: Set-Content -Encoding UTF8 temp-expr.txt '"200"'   bash: printf '"200"' > temp-expr.txt
 uip rpa debug test-activity \
-  --input-variables '{"temperature": "\"200\""}' \
+  --input-variables temperature=@temp-expr.txt \
   --output json
 
 # 3. Check the output:
@@ -242,9 +246,11 @@ Use `debug start-from-here` to skip straight to the activity you care about, avo
 # 1. Focus the activity to start from (Studio Desktop required)
 uip rpa focus-activity --activity-id "HttpRequest_1"
 
-# 2. Start debugging from that point, pre-setting variables
+# 2. Start debugging from that point, pre-setting variables.
+#    apiUrl is a String — its expression needs quotes, so pass it from a file:
+#    PowerShell: Set-Content -Encoding UTF8 api-url.txt '"https://api.example.com/weather"'
 uip rpa debug start-from-here \
-  --input-variables '{"apiUrl": "\"https://api.example.com/weather\""}' \
+  --input-variables apiUrl=@api-url.txt \
   --output json
 
 # 3. The debugger runs from the focused activity — step through or continue
@@ -309,13 +315,14 @@ uip rpa execution cancel --output json
 Pass input arguments when the workflow has In arguments that need values:
 
 ```bash
-# Start debugging with input arguments (plain JSON values)
+# Start debugging with input arguments — one key=value pair per flag occurrence
 uip rpa debug start --file-path "ProcessOrder.xaml" \
-  --input-arguments '{"orderId": "ORD-12345", "customerEmail": "test@example.com"}' \
+  --input-arguments orderId=ORD-12345 \
+  --input-arguments customerEmail=test@example.com \
   --output json
 ```
 
-`--input-arguments` is valid with `run`, `debug start`, `debug test-activity`, and `debug start-from-here`. For `run` / `debug start`, values are plain JSON. For `debug test-activity` / `debug start-from-here`, values must be VB/C# expressions.
+`--input-arguments` is valid with `run`, `debug start`, `debug test-activity`, and `debug start-from-here`. For `run` / `debug start`, `=` keeps the value a string and `:=` passes raw JSON (`retries:=3`, `enabled:=true`). For `debug test-activity` / `debug start-from-here`, values must be VB/C# expressions — always `=`. Full grammar (file payloads, quoting rules): [cli-reference.md § Passing structured inputs](cli-reference.md#passing-structured-inputs).
 
 ---
 

package/skills/uipath-rpa/references/environment-setup.md

@@ -4,7 +4,7 @@
 
 ## Studio Desktop vs headless Studio
 
-`uip rpa` runs against a **headless Studio** by default (codename Helm — ships as the `UiPath.Studio.Helm.{Platform}` NuGet package, auto-launched the first time a command needs it). **Studio Desktop is not required** for the standard authoring loop — `init`, `run`, `debug start`, `validate`, `build`, `activities find`, `packages install`, `indicate-application`/`indicate-element`, the `uia` group, etc. all work headless.
+`uip rpa` runs against a **headless Studio** by default (codename Helm — ships as the `UiPath.Studio.Helm.{Platform}` NuGet package, auto-launched the first time a command needs it). **Studio Desktop is not required** for the standard authoring loop — `init`, `run`, `debug start`, `validate`, `build`, `activities find`, `packages install`, the `uia` group (indication, capture, interaction), etc. all work headless.
 
 Studio Desktop is only required for two interactive UI tools:
 - `uip rpa files diff` — opens an interactive diff window in Studio's UI.
@@ -14,7 +14,7 @@ For these two, see [§ Edge case: requiring Studio Desktop](#edge-case-requiring
 
 > **Coded UI automation caveat.** One non-interactive task also needs Studio Desktop: regenerating `ObjectRepository.cs` — the `Descriptors.*` class consumed by coded `uiAutomation.*` workflows. `uip rpa build` alone does NOT produce it; Studio Desktop reconciles the coded workflow against the Object Repository to generate it. A headless flow can author and validate coded UIA, but populating `Descriptors.*` requires a Studio Desktop pass. See [ui-automation-guide.md](ui-automation-guide.md) § Finding Descriptors.
 
-> **First call is slow.** On a cold NuGet cache, the very first `uip rpa` invocation triggers a silent `dotnet restore` of the headless Studio package and may sit near-silent for 30–90 seconds (longer behind a slow feed). A heartbeat line every 15s confirms it's still working. Bump the per-call timeout to ≥ 180s for the first invocation.
+> **First call is slow.** On a cold NuGet cache, the very first `uip rpa` invocation triggers a silent `dotnet restore` of the headless Studio package and may sit near-silent for 30–90 seconds (longer behind a slow feed). A heartbeat line every 15s confirms it's still working. The default shell timeout covers this; bump `timeoutSeconds` only behind a slow feed.
 
 ## Step 0.1: Establish Project Root
 
@@ -181,7 +181,7 @@ Two `uip rpa` commands need a running Studio Desktop instance — they have UI s
 
 | Command | Why it needs Studio |
 |---------|---------------------|
-| `uip rpa diff` | Opens an interactive diff window in Studio's UI; finishes when the user closes the window. |
+| `uip rpa files diff` | Opens an interactive diff window in Studio's UI; finishes when the user closes the window. |
 | `uip rpa focus-activity` | Selects/highlights an activity in Studio's active workflow designer. |
 
 When (and only when) you need to run one of these, ensure Studio Desktop is up:

package/skills/uipath-rpa/references/is-connector-xaml-guide.md

@@ -56,7 +56,7 @@ Required for the `isactr:ConnectorActivity` type.
 
 ```bash
 uip rpa packages versions --package-id UiPath.IntegrationService.Activities --project-dir "<PROJECT_DIR>" --output json
-uip rpa packages install --packages '[{"id":"UiPath.IntegrationService.Activities"}]' --project-dir "<PROJECT_DIR>" --output json
+uip rpa packages install --packages id=UiPath.IntegrationService.Activities --project-dir "<PROJECT_DIR>" --output json
 ```
 
 ### Step 2 — Find the operation's `activityTypeId`
@@ -109,10 +109,10 @@ The response contains the complete `ConnectorActivity` element with:
 For each field you want to bind, you need its declared `name` and `dataType`. Read the schema from Integration Service:
 
 ```bash
-uip is resources describe <connector-key> <operation-name> --operation Create --output json
+uip is resources describe <connector-key> <object-name> --operation Create --output json
 ```
 
-Note: it's `resources describe` (not `activities describe`). `activities` only has `list`.
+The second positional is the **object/resource name** (from `uip is resources list`), not the operation; the operation goes in `--operation`. Note: it's `resources describe` (not `activities describe`). `activities` only has `list`.
 
 The response includes a `metadataFile` path like:
 ```

package/skills/uipath-rpa/references/library-authoring-guide.md

@@ -0,0 +1,226 @@
+# Library Authoring Guide
+
+How to produce a reusable library: a NuGet package whose public workflows surface as activities in every consuming project's panel. For finding and consuming libraries that already exist, see [tenant-library-search-guide.md](tenant-library-search-guide.md).
+
+## When to Build a Library
+
+Good fit:
+
+- **Complex reusable actions** shared by multiple processes — login flows, paginate-and-extract, shared validators, notification senders
+- **Standard practices** the organization wants enforced once — logging wrappers, error handlers
+- **Interactions with a shared corporate system** (ERP, CRM) that many automations touch
+
+Not a fit:
+
+- **Process-specific logic** — used once, belongs in the project
+- **Unstable code** — frequent changes create versioning overhead for every consumer
+- **Tightly coupled workflows** — only make sense inside one process
+- **Single activities** — wrapping one `Click` as a library activity adds no value. Extract macro-actions (`DownloadInvoices`), not micro-primitives
+
+Boundaries:
+
+| Need | Go to |
+|------|-------|
+| Start new projects from a standard baseline | Project templates — [environment-setup.md § Template Selection](environment-setup.md) |
+| Share UI selectors across projects | UI Libraries — [ui-automation-guide.md § Object Repository as a Published UI Library](ui-automation-guide.md) |
+| Reuse logic inside one project | Separate workflow file — [project-structure-guide.md § Designing for Reuse](project-structure-guide.md) |
+
+## Creating and Structuring
+
+```bash
+uip rpa init \
+  --name "<LIBRARY_NAME>" \
+  --location "<PARENT_DIR>" \
+  --template-id "LibraryProcessTemplate" \
+  --expression-language <VisualBasic|CSharp> \
+  --target-framework <Windows|Portable> \
+  --description "<DESCRIPTION>" \
+  --output json
+```
+
+- `<LIBRARY_NAME>`: descriptive and scoped, dotted segments accepted — `Company.Email.Utilities`, not `Helpers`. The name becomes the package ID.
+- **Default `--target-framework Portable` (Cross-platform) for libraries.** Cross-platform libraries (packed to `lib/net8.0`) install into both Cross-platform and Windows consumer projects; Windows libraries (`lib/net8.0-windows7.0`) install only into Windows projects. Choose Windows only when the library needs Windows-only activities or dependencies — every Windows-only pick shrinks the consumer base.
+- `<DESCRIPTION>` (`project.json` → `description`) becomes the package description shown in the feed — write it for consumers.
+- The template scaffolds `NewActivity.xaml`; replace it — delete the file and point `project.json` → `main` at a real workflow, then add one workflow file per activity.
+- Library `project.json` differs from a process: `designOptions.outputType` is `"Library"`, and there is no `entryPoints` (SKILL.md Rule 15) — do not add one.
+
+### Public vs private workflows
+
+Every workflow file is **public** by default — packed as an activity. To keep a helper internal, add its filename to `project.json`:
+
+```json
+"designOptions": {
+  "libraryOptions": {
+    "privateWorkflows": [
+      "ValidateEmailFormat.xaml"
+    ]
+  }
+}
+```
+
+Private workflows compile into the package and stay invocable from the library's own workflows, but no activity is generated for consumers.
+
+### Activity identity
+
+- Activity name and class = workflow file name (`SendInvoiceNotification.xaml` → activity `SendInvoiceNotification`)
+- Activity namespace = library name with dots and hyphens sanitized to underscores (`Company.Email.Utilities` → namespace `Company_Email_Utilities`); the package ID and assembly keep the dotted name. Read the real namespace from `uip rpa packages inspect` on the packed `.nupkg` — never derive it
+- Property tooltip = the argument's description annotation in XAML: `sap2010:Annotation.AnnotationText` on the `x:Property`
+
+### Activity Layout — the sidecar file
+
+Each public workflow can ship as a rich activity: custom display name, tooltip, color, SVG icon, and per-property display names, placeholders, input widgets, required flags, and category grouping. All of it is authored in a sidecar JSON next to the workflow — `<WORKFLOW_NAME>.xaml.json`:
+
+```json
+{
+  "DisplayName": "Send Invoice Notification",
+  "Tooltip": "Sends an invoice notification email and returns a delivery summary",
+  "Color": "#1F8FFF",
+  "OriginalIconFileName": "SendInvoiceNotification.xaml.svg",
+  "Arguments": [
+    {
+      "Name": "RecipientEmail",
+      "DisplayName": "Recipient email",
+      "Category": "Input",
+      "Tooltip": "Email address that receives the notification",
+      "Placeholder": "someone@company.com",
+      "Widget": "TextComposer",
+      "IsRequired": true,
+      "IsPrincipal": true,
+      "ArgumentType": 0
+    },
+    {
+      "Name": "UrgentDelivery",
+      "DisplayName": "Urgent delivery",
+      "Category": "Options",
+      "Tooltip": "Send with high priority",
+      "Widget": "Toggle",
+      "IsRequired": false,
+      "IsPrincipal": false,
+      "ArgumentType": 0
+    }
+  ]
+}
+```
+
+Rules:
+
+1. **`Arguments[].Name` must match the XAML argument name exactly** — the sidecar decorates arguments, it does not declare them.
+2. **The sidecar wins over XAML annotations.** Without a sidecar, the argument annotation is the tooltip and the file name is the display name; the sidecar overrides both and adds everything else.
+3. **Icon**: place an SVG next to the workflow as `<WORKFLOW_NAME>.xaml.svg` and reference it in `OriginalIconFileName`. `pack` embeds it as a package resource.
+4. **`Widget` is the property's input type** (Studio: "Input type"). Valid values depend on the argument's type — omit `Widget` for the type's default editor:
+
+| Argument type | `Widget` values |
+|---------------|-----------------|
+| `String` | `TextComposer` (default), `RichTextComposer`, `Dropdown`, `AutocompleteForExpression`, `RadioGroup` |
+| `Boolean` / `bool?` | `Toggle` (default), `ConditionBuilder`, `NullableBoolean` |
+| Numeric | `Number` (default), `Dropdown` |
+| `DateTime` | `Datetime` |
+| `TimeSpan` | `Timespan` |
+| `String[]` | `StringArray` |
+| `Dictionary` | `Dictionary` |
+
+   `DataSourceItems` (string array of choices) applies only to `Dropdown`, `RadioGroup`, and `AutocompleteForExpression`.
+5. **`Category`** groups properties in the activity's body, in sidecar argument order; `IsPrincipal: true` surfaces the property on the activity card, `IsRequired: true` marks it mandatory.
+6. **`HelpLink`** is a valid sidecar field but stays design-time only — it does not ship in the compiled activity metadata.
+7. **`ArgumentType` is `0`** for plain arguments.
+
+`pack` compiles the sidecar into the activity metadata embedded in the library assembly — consumers see the layout in their Activities panel with no extra steps.
+
+## The Public-Workflow Contract — MANDATORY
+
+Each public workflow is an API surface. Apply every rule:
+
+1. **Name workflows verb-noun PascalCase, no spaces** — `SendNotificationEmail.xaml`, `DownloadInvoices.xaml`. The file name becomes the activity name in the consumer's panel.
+2. **Public arguments: PascalCase, NO `in_`/`out_`/`io_` prefixes** — `InvoiceId`, `RecipientEmail`, `NotificationResult`. Argument names become activity property names; prefixes become noise on the property grid. This inverts the process-workflow convention: workflows invoked via Invoke Workflow File keep directional prefixes ([project-structure-guide.md § Designing for Reuse](project-structure-guide.md)); library public workflows drop them.
+3. **Describe every public argument** via its `sap2010:Annotation.AnnotationText` — descriptions ship as property tooltips. For display names, placeholders, widgets, and grouping, add the layout sidecar ([§ Activity Layout](#activity-layout--the-sidecar-file)).
+4. **Expect — and keep — the analyzer naming warnings.** `build`/`pack` emit `Argument <Name> does not respect the set pattern ^in_...` for prefix-free library arguments. The warning is non-blocking. Do NOT rename arguments to silence it.
+5. **Return application handles.** A workflow that opens or attaches to an app outputs the window/browser object; downstream public workflows accept it as an input argument instead of reopening.
+6. **Post-authoring audit:** before packing, re-check every public workflow against rules 1-3 — name form, argument naming, argument descriptions.
+
+## Error Contract
+
+- **Throw meaningful exceptions** — `BusinessRuleException` for input validation failures, with the offending value in the message. Let system exceptions propagate to the consumer.
+- **Never swallow errors**: no empty `Catch` blocks, no `out` boolean success flags in place of exceptions. A swallowed error returns control to a consumer whose target app is in an unknown state.
+- **Never set `ContinueOnError` inside a library** — the consumer decides failure policy.
+- **No hardcoded paths** — accept paths as arguments, or build from `UiPath.Constants.Project.Location` for files packed with the library.
+- **No embedded config or secrets** — read Orchestrator assets and credentials at the consumer level and pass them in as arguments.
+
+## Versioning
+
+`projectVersion` in `project.json` is the package version (override at pack time with `--package-version`). Follow SemVer:
+
+| Bump | When | Consumer impact |
+|------|------|-----------------|
+| Patch `x.x.1` | Bug fix, no interface change | Safe drop-in |
+| Minor `x.1.x` | New workflow or new optional argument, backward compatible | Safe upgrade |
+| Major `1.x.x` | Renamed/removed workflow or argument, changed behavior | Code changes required |
+
+1. Renaming a public workflow or argument is a **breaking change** — major bump. To change an argument compatibly, add a new one and keep the old.
+2. **Never delete published versions from the feed** — consumers pin them. `libraries delete` is for mistaken uploads only.
+3. Consumers pin exact versions in production.
+
+## Pack & Publish
+
+```bash
+uip rpa pack "<PROJECT_DIR>" "<OUTPUT_DIR>" --output json
+uip or libraries upload --file "<OUTPUT_DIR>/<LIBRARY_NAME>.<VERSION>.nupkg" --output json
+```
+
+- Libraries upload to the tenant-scoped **libraries feed** — not the per-folder processes feed that [publishing-guide.md](publishing-guide.md) covers with `uip or packages upload`. There is no `uip rpa publish`.
+- `--feed-id <FEED_ID>` targets a non-default feed.
+- Verify the publish:
+
+```bash
+uip or libraries list --search "<LIBRARY_NAME>" --output json
+```
+
+Returns the library with `key` = `<PackageId>:<Version>` and `projectType: "ProcessLibrary"`.
+
+## Consumption Loop
+
+1. **Discover** existing libraries before building new ones — [tenant-library-search-guide.md](tenant-library-search-guide.md) (SKILL.md Rule 9).
+2. **Install** into the consumer as a dependency — SKILL.md § Resolving Packages & Activity Docs. The install records the dependency in the consumer's `project.json`; the library's activities become available.
+3. **Build-time resolution:** the tenant libraries feed is not among the default build NuGet sources. If `build`/`pack` of the consumer fails with `Unable to find package <LIBRARY_NAME>`, download the package and add its folder as a source:
+
+```bash
+uip or libraries download "<PackageId>:<Version>" --destination "<LOCAL_DIR>/<LIBRARY_NAME>.<VERSION>.nupkg" --output json
+uip rpa build "<CONSUMER_PROJECT_DIR>" --nuget-sources-config-path "<SOURCES_JSON>" --output json
+```
+
+`<SOURCES_JSON>` content:
+
+```json
+[{"Url": "<LOCAL_DIR>"}]
+```
+
+4. **Author against the library in consumer XAML.** Library activities are not in the `activities find` catalog and `activities get-default-xaml` does not load library types — get the activity surface from the package itself:
+
+```bash
+uip rpa packages inspect --nupkg-path "<LOCAL_DIR>/<LIBRARY_NAME>.<VERSION>.nupkg" --output json
+```
+
+Declare the namespace and use each public workflow as an element — property names = the library's argument names:
+
+```xml
+<Activity ... xmlns:lib="clr-namespace:<SANITIZED_NAMESPACE>;assembly=<LIBRARY_NAME>">
+  <lib:SendInvoiceNotification RecipientEmail="..." InvoiceId="..." />
+```
+
+`<SANITIZED_NAMESPACE>` is the underscore form from [§ Activity identity](#activity-identity). Bind non-literal properties per the project's expression language rules ([xaml/xaml-basics-and-rules.md](xaml/xaml-basics-and-rules.md)).
+
+5. **Stale design session after the dependency becomes resolvable:** `build` compiles the consumer but `validate` keeps failing with `Cannot create unknown type` for the library activity. Kill the `UiPath.Studio.Helm` process (it relaunches on the next command) and re-run `validate`.
+
+## Library Patterns
+
+| Pattern | Shape | Example |
+|---------|-------|---------|
+| Wrapper | Bundle related operations into one higher-level activity | `OpenExcelAndReadSheet` instead of Open Workbook + Read Range |
+| Connector | One library per corporate system — single source of auth, selectors, business rules | `CompanyERP.Library` owns all ERP interactions |
+| Framework | Scaffolding consumers extend (REFramework-style) | State machine with extension points |
+| Data access | Centralize database/API access behind typed activities | `GetCustomerById` returns a row from any backend |
+
+## Pitfalls
+
+- **Never name a library project `lib`** — collides with the NuGet package folder layout; consumers fail to compile.
+- **A workflow file and one of its arguments must not share the same name** — publishing crashes on the name collision.
+- **Never set `ImplementationVersion`** on the XAML `ActivityBuilder` — a framework bug silently drops the library's argument mappings.

package/skills/uipath-rpa/references/project-structure-guide.md

@@ -13,6 +13,49 @@ For the coded vs XAML decision, see [coded-vs-xaml-guide.md](coded-vs-xaml-guide
 - **Test project** — one test case per scenario. Coded test projects optionally use `partial class CodedWorkflow : IBeforeAfterRun` in `CodedWorkflowHooks.cs` for shared setup. XAML test projects use Test Activities for shared setup
 - **Complex domain logic** — isolate business rules so they can be unit-tested and reused (Coded Source File for typed logic, or a separate workflow for activity-driven logic)
 
+## Designing for Reuse
+
+Structure decisions that keep components extractable later.
+
+### Single responsibility
+
+One workflow file = one meaningful action, named for it (`ProcessInvoice.xaml`, `LoginToApplication.xaml`). Split a workflow when it exceeds ~20-30 activities.
+
+### Standard folder shape
+
+For multi-step processes, organize by layer:
+
+```
+Project/
+├── Main.xaml              # High-level orchestration only
+├── Framework/             # Init, cleanup, error handling, app open/close
+├── BusinessLogic/         # Process-specific rules and transactions
+├── Utilities/             # Process-agnostic helpers (formatters, screenshots)
+└── Data/                  # Config files, templates
+```
+
+### Separate business logic from UI components
+
+UI workflows interact with applications and carry zero business rules; business-logic workflows decide and never touch the UI. Make read and write distinct invocable components — `GetCustomerInfo.xaml` and `ChangeCustomerInfo.xaml`, not one `HandleCustomer.xaml`. When the target application's UI changes, only the UI workflows need fixing; when a business rule changes, the UI workflows are untouched. Process-agnostic UI components are also the ones worth promoting to a shared library later.
+
+### Composition and argument naming
+
+Compose via `Invoke Workflow File` (coded: `workflows.StepName()`). Process workflow arguments use directional prefixes — `in_InvoiceId`, `out_Result`, `io_Browser` — so data flow is visible at every invocation site. Exception: library public workflows drop the prefixes ([library-authoring-guide.md § The Public-Workflow Contract](library-authoring-guide.md)).
+
+### Layout and scale-out
+
+- Sequence vs Flowchart vs State Machine per workflow: Workflow Types table in SKILL.md § XAML Workflows Quick Reference
+- High-volume transactional work: dispatcher/performer split via queues — [reframework-guide.md § Execution Mode: Queue-Driven](reframework-guide.md)
+
+### Promotion ladder
+
+Promote logic only as reuse materializes:
+
+1. **Inline** — used once in one workflow
+2. **Separate workflow file** — reused within the project
+3. **Shared library** — reused across projects ([library-authoring-guide.md](library-authoring-guide.md))
+4. **UI Library** — selectors shared across projects ([ui-automation-guide.md § Object Repository as a Published UI Library](ui-automation-guide.md))
+
 ## Example — Invoice Processing Project (XAML)
 
 ```

package/skills/uipath-rpa/references/publishing-guide.md

@@ -8,7 +8,7 @@ How to take a built `.nupkg` from `uip rpa pack` and get it onto Orchestrator or
 |---|---|---|
 | Run the project as an Orchestrator process / link as a Test Manager automation | **Pack → Orchestrator package upload** | This file § Pack → Upload |
 | Edit / visualize in Studio Web | **Solution upload** | [uipath-solution](../../uipath-solution/SKILL.md) (solution upload) |
-| Deploy a packed solution (`.uipx`) to Orchestrator with the deployment lifecycle | **Solution publish** | [uipath-solution](../../uipath-solution/references/operate/pack-and-deploy.md) |
+| Deploy a packed solution (`.uipx`) to Orchestrator with the deployment lifecycle | **Solution publish** | [uipath-solution](../../uipath-solution/references/pack-and-deploy.md) |
 
 This file documents the first row only — the legacy Orchestrator package feed flow that `uip tm testcases link-automation` requires.
 
@@ -46,9 +46,9 @@ uip or packages upload "<NUPKG_PATH>" --output json
 |---|---|---|
 | `<NUPKG_PATH>` | Yes (positional) | Path to the `.nupkg` produced by `pack`. |
 | `--feed-id <UUID>` | No | Target a non-default feed. Defaults to the tenant feed. |
-| `-t, --tenant <NAME>` | No | Override the authenticated tenant. |
+| `--folder-path <PATH>` / `--folder-key <UUID>` | No | Target a specific folder feed. |
 
-Output JSON includes the package `Id` (the package name Orchestrator stores) and `Version`. Hold on to the `Id` — it is the `--package-name` value that `uip tm testcases link-automation` and `uip or processes create` need.
+Output JSON includes the package `Id` (the package name Orchestrator stores) and `Version`. Hold on to the `Id` — `uip tm testcases link-automation` takes it as `--package-name`; `uip or processes create` takes it as `--package-key` (with `--package-version` separately).
 
 > **There is no `uip or packages publish` or `uip rpa publish`.** Agents that try those names get "unknown command". Pack writes a file; upload pushes that file. Two commands, two domains (`rpa`, `or`).
 
@@ -57,7 +57,7 @@ Output JSON includes the package `Id` (the package name Orchestrator stores) and
 Folder key (UUID — required by `processes create`, `link-automation`, etc.):
 
 ```bash
-uip or folders list-current-user --output json
+uip or folders list --output json
 ```
 
 The returned `Key` is the UUID; the `FullyQualifiedName` is the human path. Either is accepted by `--folder-path` / `--folder-key` — most other CLI calls require the UUID.
@@ -77,4 +77,4 @@ For the full Pack → Upload → Link → Execute pipeline targeted at Test Mana
 - **`uip solution publish` expects a packed `.zip`, not a project directory.** Solutions: run `uip solution pack` first, then `uip solution publish "<ZIP_PATH>"`. Single projects: use `uip or packages upload` instead.
 - **Confusing `solution upload` and `solution publish`.** `upload` pushes to Studio Web (browser editing). `publish` pushes a packed solution `.zip` to the Orchestrator solution feed for `solution deploy`. They are NOT interchangeable. See [uipath-solution](../../uipath-solution/SKILL.md) for the decision tree.
 - **Re-uploading the same version.** Orchestrator rejects duplicate `<id>:<version>` uploads. Bump `--package-version` (or `project.json` `projectVersion`) before re-packing.
-- **`pack` succeeds but `analyze` ran with errors.** A successful pack with errors in the analyzer log usually means warnings only. Re-run `uip rpa analyze --project-dir "<PROJECT_DIR>"` if you need a clean failure / pass signal.
+- **`pack` succeeds but `analyze` ran with errors.** A successful pack with errors in the analyzer log usually means warnings only. Re-run `uip rpa analyze "<PROJECT_DIR>"` (project dir is positional) if you need a clean failure / pass signal.