@uipath/skills 1.195.0 → 1.196.0

package/skills/uipath-rpa/references/xaml/long-running-workflow-guide.md

@@ -0,0 +1,304 @@
+# Long Running Workflow (ProcessDiagram) Guide
+
+Package, node vocabulary, gateway patterns, and suspend/resume for Long Running Workflows. Related references: XAML anatomy → [xaml-basics-and-rules.md § Long Running Workflow](xaml-basics-and-rules.md); layout + ViewState → [canvas-layout-guide.md § 5](canvas-layout-guide.md); node registration → [common-pitfalls.md § x:Reference](common-pitfalls.md#xreference--__referenceid-naming).
+
+## When to Use LRW
+
+| Requirement | Workflow type |
+|-------------|---------------|
+| Linear steps, completes in one run | Sequence |
+| Branching/looping logic, in-memory, completes in one run | Flowchart |
+| Distinct states with transitions (e.g. REFramework) | State Machine |
+| Human tasks, long waits (hours–weeks), suspend/resume, parallel branch coordination, BPMN-style modeling | **Long Running Workflow** (`upa:ProcessDiagram`) |
+
+## Required Package
+
+LRW node types ship in **`UiPath.FlowchartBuilder.Activities`** (runtime assembly `UiPath.Process.Activities` — the `upa`/`upas` xmlns target). Mandatory dependency for any workflow containing `upa:ProcessDiagram`; the runtime pair `UiPath.FlowchartBuilder.Activities.Runtime` resolves automatically. Not supported on `targetFramework: "Legacy"`. Studio creates LRW projects with this package plus `UiPath.System.Activities`.
+
+Install per Common Rule 6 and SKILL.md § Resolving Packages before authoring:
+
+```bash
+uip rpa packages versions --package-id UiPath.FlowchartBuilder.Activities --include-prerelease --project-dir "<PROJECT_DIR>" --output json
+uip rpa packages install --packages '[{"id":"UiPath.FlowchartBuilder.Activities","version":"<LATEST_VERSION>"}]' --project-dir "<PROJECT_DIR>" --output json
+```
+
+BPMN import (`.bpmn` → ProcessDiagram, Studio wizard) requires version 1.0.4 or later.
+
+**Discovery commands do not see LRW nodes.** `upa:` node types are diagram nodes, not activities — `activities find` returns nothing for them and `activities get-default-xaml --activity-class-name "UiPath.Process.Activities.SplitNode"` fails with `TypeLoadException`. The package also ships no `.local/docs`. Author nodes structurally from this guide's vocabulary and patterns; do NOT burn calls on Rule 21 discovery for `upa:` types. Activities *inside* a TaskNode body (Sequence content) follow normal Rule 21 discovery.
+
+## Node Vocabulary
+
+Class names below live in namespace `UiPath.Process.Activities` (prefix `upa:`); `DesignerMetadata` in `UiPath.Process.Activities.Shared` (prefix `upas:`). Every node has `Behavior` (a `NodeBehavior` carrying `DesignerMetadata NodeType="<string>"` — controls the canvas shape/icon) and `DisplayName`.
+
+| Canvas name | XAML element | Behavior class | NodeType | Notes |
+|-------------|--------------|----------------|----------|-------|
+| Manual Trigger (start) | `upa:EventNode` | `upa:StartBehavior` | `StartEvent.Interrupting.None` | One start node required; `ProcessDiagram.StartNode` points to it |
+| On a Schedule (start) | `upa:EventNode` | `upa:StartBehavior` | `StartEvent.Interrupting.Timer` | |
+| On App Trigger (start) | `upa:EventNode` | `upa:StartBehavior` | `StartEvent.Interrupting.Message` | |
+| Sequence (task) | `upa:TaskNode` | `upa:NodeBehavior` | `Task.None` | Body = a `Sequence` activity (the node's `Action`); `Next` to following node |
+| Human Approval | `upa:TaskNode` | `upa:NodeBehavior` | `Task.User` | Body holds persistence activities — see § Suspend/Resume |
+| Process (agentic) | `upa:TaskNode` | `upa:NodeBehavior` | `Task.Agentic` | |
+| Business Rule | `upa:TaskNode` | `upa:NodeBehavior` | `Task.BusinessRule` | |
+| Wait for Trigger | `upa:TaskNode` | `upa:NodeBehavior` | `Task.Receive` | |
+| Activity (send) | `upa:TaskNode` | `upa:NodeBehavior` | `Task.Send` | |
+| Invoke Workflow | `upa:TaskNode` | `upa:NodeBehavior` | `Task.Service` | Body wraps `InvokeWorkflowFile` |
+| Subprocess | `upa:SubProcessNode` | `upa:NodeBehavior` | `Task.Subprocess` | |
+| Detached Error Handler | `upa:EventSubProcessNode` | `upa:NodeBehavior` on the node; `upa:StartOnParentErrorBehavior` (`ExceptionType`) on the inner diagram's start | `Task.EventSubprocess` | In `ProcessDiagram.EventSubProcesses`, not `Nodes`; `Action` = inner `ProcessDiagram` — see § Detached Error Handler |
+| Decision (gateway) | `upa:DecisionNode` | — | — | `Condition` (`Activity<Boolean>`), `True`/`False` branch properties |
+| Switch (gateway) | `upa:SwitchNode` (`x:TypeArguments`) | — | — | `Expression`, `Cases` (keyed children), `Default` — see § Gateway Patterns |
+| Split (gateway) | `upa:SplitNode` | — | — | `Branches` collection of parallel next nodes |
+| Merge (gateway) | `upa:MergeNode` | `upa:MergeAllBehavior` or `upa:MergeFirstBehavior` | — | All = wait for every incoming branch; First = continue on first, cancel others |
+| Event Placeholder | `upa:EventNode` | `upa:IntermediateBehavior` | `IntermediateEvent.Throw.None` | Intermediate marker; convert to a catch event below |
+| Resume after Delay | `upa:EventNode` | `upa:IntermediateBehavior` | `IntermediateEvent.Catch.Timer` | Body holds `Resume After Delay` persistence activity |
+| Wait for Message | `upa:EventNode` | `upa:IntermediateBehavior` | `IntermediateEvent.Catch.Message` | |
+| Error Handler (boundary) | `upa:BoundaryNode` | `upa:CatchMostSpecificErrorBehavior` (`ExceptionType`) | `BoundaryEvent.Interrupting.Error` | Attached via `upa:TaskNode.BoundaryNodes`; own `Next` chain |
+| End | `upa:EndNode` | `upa:EndBehavior` | `EndEvent.None` | |
+| Throw (end) | `upa:EndNode` | `upa:EndBehavior` | `EndEvent.Error` | Body (`Action`) holds a `Throw` |
+| Terminate (end) | `upa:EndNode` | `upa:EndBehavior` | `EndEvent.Terminate` | Body holds `upa:TerminateProcessDiagram` |
+
+`ProcessDiagram` root properties: `StartNode`, `Nodes` (content collection — registration target for `x:Reference`), `EventSubProcesses`, `Variables` (diagram-scoped variables), `ValidateUnconnectedNodes`.
+
+## Choosing Nodes
+
+NodeType drives the canvas icon and diagram readability — model intent, don't default everything to a plain sequence box.
+
+### Task steps — assigning a NodeType per step is MANDATORY, before authoring
+
+1. Before writing XAML, map every task step in the plan to a row of this table.
+2. `Task.None` is permitted ONLY for steps matching no other row — generic scripted logic. Checks, validations, sends, invokes, waits, approvals all have a specific row.
+3. After authoring, audit the file: for each `NodeType="Task.None"`, confirm no other row fits. A diagram where most tasks are `Task.None` is mis-modeled, not neutral — the canvas renders unreadable uniform boxes.
+
+| Step semantics | NodeType |
+|----------------|----------|
+| Human decision/input (Action Center task) | `Task.User` |
+| Body is `InvokeWorkflowFile` to another workflow | `Task.Service` |
+| Check / rule evaluation / classification / data validation | `Task.BusinessRule` |
+| Agent step | `Task.Agentic` |
+| Waits on an inbound trigger/message | `Task.Receive` |
+| Sends to an external system (notification, email, API call) | `Task.Send` |
+| Generic scripted logic matching no row above | `Task.None` |
+
+### Task body contents — regular activities or invokes
+
+The `Sequence` inside a TaskNode is a **normal activity container** — author its contents with the standard activity rules (common-activity-card fast path, Rule 21 discovery for everything else, IS connector activities, persistence activities). Two patterns:
+
+- **Inline** — few activities, specific to this step (log, assign, one connector call): put them directly in the body `Sequence`.
+- **Invoke** — multi-step or reusable business logic: put it in a separate `.xaml` and call it via `InvokeWorkflowFile` (`Task.Service`). Keeps the diagram readable; the invoked workflow is a normal Sequence/Flowchart authored per the standard XAML rules.
+
+### Gateways — exclusive vs parallel
+
+| Need | Gateway |
+|------|---------|
+| Two paths, boolean condition | `DecisionNode` (`Condition`, `True`/`False`) |
+| 3+ exclusive paths routed by one value | `SwitchNode<T>` (`Expression`, `Cases`, `Default`) |
+| Paths that ALL run, concurrently | `SplitNode` → branches → `MergeNode` |
+| Continue when every parallel branch finishes | `MergeNode` + `MergeAllBehavior` |
+| Continue on first finisher, cancel the rest (race/timeout patterns) | `MergeNode` + `MergeFirstBehavior` |
+
+Decision/Switch branches are exclusive — exactly one path executes. Split branches are parallel — all paths execute. Don't model an either/or with Split.
+
+### Error handling — three scopes plus end semantics
+
+| Scope | Mechanism | Use when |
+|-------|-----------|----------|
+| Inside one step | `TryCatch` in the task's body `Sequence` | Error is handled and the step continues/retries — flow unaffected |
+| One node | `upa:BoundaryNode` on `TaskNode.BoundaryNodes` (`CatchMostSpecificErrorBehavior`, `ExceptionType`) | A specific task's failure diverts flow to a recovery path (own `Next` chain) |
+| Whole diagram | `upa:EventSubProcessNode` (Detached Error Handler) in `ProcessDiagram.EventSubProcesses` — § Detached Error Handler | Any unhandled error anywhere triggers a shared handler (notify, compensate) |
+| End with failure | `EndNode` `EndEvent.Error` + `Throw` in body | Path reached a business/system failure — fail the job |
+| Hard stop | `EndNode` `EndEvent.Terminate` + `upa:TerminateProcessDiagram` in body | Abort everything immediately, including running parallel branches |
+
+A plain `EndNode` (`EndEvent.None`) ends only its own path; parallel branches keep running.
+
+### Events
+
+| Need | Node |
+|------|------|
+| Start manually / on schedule / on app message | `EventNode` + `StartBehavior` (`StartEvent.Interrupting.{None,Timer,Message}`) |
+| Pause mid-flow for a duration | `EventNode` + `IntermediateBehavior` `IntermediateEvent.Catch.Timer` (Resume after Delay) |
+| Pause mid-flow until an external signal | `EventNode` + `IntermediateBehavior` `IntermediateEvent.Catch.Message` (Wait for Message) |
+| Pause for a human task | `Task.User` TaskNode with persistence activities — § Suspend/Resume |
+| Group a reusable sub-flow inside the diagram | `upa:SubProcessNode` (`Task.Subprocess`) |
+
+## Gateway Patterns
+
+Skeletons below omit per-node ViewState (`ShapeLocation`/`ShapeSize`/`ConnectorLocation`) — generate it per [canvas-layout-guide.md § 5](canvas-layout-guide.md) (Rule 20). `SwitchNode` branch connectors reuse the FlowSwitch ViewState key convention (`Default`, `{caseKey}Connector`). Standard root xmlns per [xaml-basics-and-rules.md](xaml-basics-and-rules.md) plus:
+
+```xml
+xmlns:upa="clr-namespace:UiPath.Process.Activities;assembly=UiPath.Process.Activities"
+xmlns:upas="clr-namespace:UiPath.Process.Activities.Shared;assembly=UiPath.Process.Activities"
+```
+
+### Split / Merge (parallel branches)
+
+`SplitNode.Branches` holds the first node of each parallel path. Each branch chain ends by pointing `Next` at the shared `MergeNode` — define the merge inline in one branch, `x:Reference` it from the others. Inline-defined nodes need trailing `<x:Reference>` registration as direct children of `<upa:ProcessDiagram>` (same rule as Flowchart).
+
+**Branch nodes count as inline — register them.** A TaskNode defined inside `<upa:SplitNode.Branches>` MUST also appear as a trailing `<x:Reference>` direct child of the diagram. `validate` AND `build` pass without the registration; the Studio canvas then crashes opening the file (`Value cannot be null` in `FlowSplitBehavior.AddToDesigner`). Exempt collections that are a node's own home — `TaskNode.BoundaryNodes`, `ProcessDiagram.EventSubProcesses` — never get diagram-level registration.
+
+```xml
+<upa:SplitNode x:Name="__ReferenceID1" DisplayName="Split">
+  <upa:SplitNode.Branches>
+    <upa:TaskNode x:Name="__ReferenceID2" DisplayName="Branch A">
+      <upa:TaskNode.Behavior>
+        <upa:NodeBehavior>
+          <upa:NodeBehavior.DesignerMetadata>
+            <upas:DesignerMetadata NodeType="Task.None" />
+          </upa:NodeBehavior.DesignerMetadata>
+        </upa:NodeBehavior>
+      </upa:TaskNode.Behavior>
+      <Sequence DisplayName="Branch A Steps">
+        <!-- activities -->
+      </Sequence>
+      <upa:TaskNode.Next>
+        <upa:MergeNode x:Name="__ReferenceID4" DisplayName="Merge">
+          <upa:MergeNode.Behavior>
+            <upa:MergeAllBehavior />
+          </upa:MergeNode.Behavior>
+          <upa:MergeNode.Next>
+            <!-- next node after merge -->
+          </upa:MergeNode.Next>
+        </upa:MergeNode>
+      </upa:TaskNode.Next>
+    </upa:TaskNode>
+    <upa:TaskNode x:Name="__ReferenceID3" DisplayName="Branch B">
+      <!-- Behavior + body as above -->
+      <upa:TaskNode.Next>
+        <x:Reference>__ReferenceID4</x:Reference>
+      </upa:TaskNode.Next>
+    </upa:TaskNode>
+  </upa:SplitNode.Branches>
+</upa:SplitNode>
+<!-- trailing registration on ProcessDiagram: __ReferenceID2, __ReferenceID3, __ReferenceID4, ... -->
+```
+
+### Switch (multi-way routing)
+
+`x:TypeArguments` on the node; `Cases` entries are keyed child nodes (`x:Key`); `Default` is a separate branch property.
+
+```xml
+<!-- standard xmlns omitted -->
+<upa:SwitchNode x:TypeArguments="x:String" x:Name="__ReferenceID1" DisplayName="Route">
+  <upa:SwitchNode.Expression>
+    <mva:VisualBasicValue x:TypeArguments="x:String">[routeVar]</mva:VisualBasicValue>
+  </upa:SwitchNode.Expression>
+  <upa:SwitchNode.Cases>
+    <upa:TaskNode x:Key="approve" x:Name="__ReferenceID2" DisplayName="Approve Path">
+      <!-- Behavior + body + Next -->
+    </upa:TaskNode>
+  </upa:SwitchNode.Cases>
+  <upa:SwitchNode.Default>
+    <upa:TaskNode x:Name="__ReferenceID4" DisplayName="Default Path">
+      <!-- Behavior + body + Next -->
+    </upa:TaskNode>
+  </upa:SwitchNode.Default>
+</upa:SwitchNode>
+```
+
+`DecisionNode` is the boolean special case: `Condition` instead of `Expression`, `True`/`False` instead of `Cases`/`Default` — full snippet in [canvas-layout-guide.md § 5](canvas-layout-guide.md).
+
+### Detached Error Handler (event subprocess)
+
+A diagram-wide handler is an **event subprocess**: the node's `Action` is an inner `ProcessDiagram` whose start event carries the error trigger. Behavior placement is the trap — `StartOnParentErrorBehavior` derives `NodeBehavior<EventNode>`, so it goes on the **inner diagram's start EventNode**, never on the `EventSubProcessNode` itself (that cast-fails). The outer node takes plain `NodeBehavior`.
+
+```xml
+<!-- standard xmlns omitted; also: xmlns:s="clr-namespace:System;assembly=System.Private.CoreLib" -->
+<upa:ProcessDiagram.EventSubProcesses>
+  <upa:EventSubProcessNode x:Name="__ReferenceID16" DisplayName="Unhandled Error Handler">
+    <upa:EventSubProcessNode.Behavior>
+      <upa:NodeBehavior>
+        <upa:NodeBehavior.DesignerMetadata>
+          <upas:DesignerMetadata NodeType="Task.EventSubprocess" />
+        </upa:NodeBehavior.DesignerMetadata>
+      </upa:NodeBehavior>
+    </upa:EventSubProcessNode.Behavior>
+    <upa:EventSubProcessNode.Action>
+      <upa:ProcessDiagram DisplayName="Error Handler Sub">
+        <upa:ProcessDiagram.StartNode>
+          <x:Reference>__ReferenceID17</x:Reference>
+        </upa:ProcessDiagram.StartNode>
+        <upa:EventNode x:Name="__ReferenceID17" DisplayName="On Error">
+          <upa:EventNode.Behavior>
+            <upa:StartOnParentErrorBehavior ExceptionType="s:Exception">
+              <upa:StartOnParentErrorBehavior.DesignerMetadata>
+                <upas:DesignerMetadata NodeType="StartEvent.Interrupting.Error" />
+              </upa:StartOnParentErrorBehavior.DesignerMetadata>
+            </upa:StartOnParentErrorBehavior>
+          </upa:EventNode.Behavior>
+          <upa:EventNode.Next>
+            <upa:TaskNode x:Name="__ReferenceID18" DisplayName="Log Incident">
+              <!-- Behavior (Task.None) + body Sequence with handler activities -->
+            </upa:TaskNode>
+          </upa:EventNode.Next>
+        </upa:EventNode>
+        <x:Reference>__ReferenceID18</x:Reference>
+      </upa:ProcessDiagram>
+    </upa:EventSubProcessNode.Action>
+  </upa:EventSubProcessNode>
+</upa:ProcessDiagram.EventSubProcesses>
+```
+
+Validation errors that mean a placement mistake:
+
+| Error | Cause → fix |
+|-------|-------------|
+| `EventSubProcessNode.Action must be of type ProcessDiagram` | `Action` holds a `Sequence` → wrap handler in an inner `ProcessDiagram` |
+| `Unable to cast ... EventSubProcessNode to ... EventNode` | `StartOnParentErrorBehavior`/`StartSubProcessBehavior` set on the outer node → move to the inner start `EventNode`; outer takes plain `NodeBehavior` |
+| `SubProcess.StartNode must have a StartSubProcessBehavior behavior` | Inner start has `StartBehavior` → use `StartOnParentErrorBehavior` (error trigger) or `StartSubProcessBehavior` |
+| `Cannot set unknown member EventSubProcessNode.Next` | Event subprocesses are detached — no `Next`; flow never routes into them |
+
+`ProcessDiagram` has no `EventHandlers`/`ErrorHandler` property — `EventSubProcesses` is the only diagram-level hook.
+
+## Suspend/Resume (Persistence)
+
+Wait steps suspend the job, serialize state, and **release the robot** — the process resumes (possibly on another robot) when the awaited task completes, a message arrives, or the delay elapses. Waits can span hours to weeks. Activities ship in **`UiPath.Persistence.Activities`** (separate package — install like FlowchartBuilder above):
+
+| Activity | Purpose |
+|----------|---------|
+| `CreateFormTask` / `WaitForFormTaskAndResume` | Action Center form task (human approval/input) |
+| `CreateExternalTask` / `WaitForExternalTaskAndResume` | External system completes the task |
+| `ResumeAfterDelay` | Timer suspension |
+
+Place create+wait inside the body of a Human Approval TaskNode (`Task.User`). xmlns:
+
+```xml
+xmlns:upae="clr-namespace:UiPath.Persistence.Activities.ExternalTask;assembly=UiPath.Persistence.Activities"
+xmlns:upamt="clr-namespace:UiPath.Persistence.Activities.Model.Task;assembly=UiPath.Persistence.Activities"
+```
+
+```xml
+<!-- inside a Task.User TaskNode's Sequence; taskObj: ProcessDiagram.Variables, type upae:ExternalTaskData -->
+<upae:CreateExternalTask ExternalTag="{x:Null}" Labels="{x:Null}" TaskCatalog="{x:Null}" TimeoutMs="{x:Null}"
+                         DisplayName="Create External Task" TaskTitle="Approve order"
+                         TaskOutput="[taskObj]" TaskPriority="[TaskPriority.Medium]">
+  <upae:CreateExternalTask.TaskData>
+    <scg:Dictionary x:TypeArguments="x:String, Argument" />
+  </upae:CreateExternalTask.TaskData>
+</upae:CreateExternalTask>
+<upae:WaitForExternalTaskAndResume StatusMessage="{x:Null}" TaskAction="{x:Null}" TimeoutMs="{x:Null}" WaitItemDataObject="{x:Null}"
+                                   DisplayName="Wait For External Task and Resume"
+                                   TaskInput="[taskObj]" TaskOutput="[taskObj]" />
+```
+
+Rules:
+
+1. **VB variable bindings on persistence activities: bracket attribute form only** (`TaskOutput="[taskObj]"`). Element-form `<mva:VisualBasicReference>` inside `OutArgument` fails `validate` with `Failed to create a 'VisualBasicReference'`. Plain-enum attribute form is also valid where the starter emits it (`TaskPriority="Medium"`).
+2. **Discover the installed version's property surface with `activities find` + `activities get-default-xaml`** (persistence activities are normal activities, unlike `upa:` nodes) and prefer the returned starter — newer package versions add properties the snippet above omits (`Group`, `UserNameOrEmail`, an `AssignmentCriteria` block requiring `xmlns:upat="clr-namespace:UiPath.Persistence.Activities.Tasks;assembly=UiPath.Persistence.Activities"`). The package generates no `.local/docs` and has no bundled fallback under `references/activity-docs/`.
+3. Add `UiPath.Persistence.Activities` to `TextExpression.ReferencesForImplementation` and its namespaces to `NamespacesForImplementation` when expressions use its types (`ExternalTaskData`, `TaskPriority`).
+4. Suspension at runtime requires `runtimeOptions.supportsPersistence: true` in `project.json` (Studio's "Supports Persistence" project setting). `build` passes either way — the flag gates Orchestrator suspension, not compilation.
+5. **Register every file containing a Wait-and-Resume activity in `project.json` → `entryPoints`** — analyzer ST-DBP-024 (surfaces in `build` as `Unsupported usage of persistence activities`) allows suspension only in entry-point files. Same `entryPoints` array schema as [../../assets/json-template.md](../../assets/json-template.md); it applies to XAML files here, not only coded workflows.
+
+## Diagram Validation Rules
+
+The designer canvas enforces these; **CLI `validate` and `build` do NOT** — a dangling split branch compiles with only warnings. Author correctly by construction:
+
+1. Exactly one start node, referenced by `ProcessDiagram.StartNode`.
+2. Every node connected — no unreachable nodes (`ValidateUnconnectedNodes`).
+3. `DecisionNode` requires `Condition`; `SwitchNode` requires `Expression`.
+4. Every `SplitNode` pairs with exactly one `MergeNode`; every `MergeNode` has an upstream `SplitNode`; all split branches converge on the same merge.
+5. A node cannot be shared across branches (except the merge target).
+6. Boundary error handlers: no duplicate `ExceptionType` on one node; `ExceptionType` must be specified (attribute form: `ExceptionType="s:Exception"`).
+
+**Expected warning — do not "fix":** `build` emits `unreachable code` warnings for every node downstream of a `SplitNode`, including correctly converged split/merge wiring — static analysis does not trace `Branches`. The warning is noise for LRW diagrams, not a wiring defect.
+
+## BPMN Import
+
+Studio imports `.bpmn` files as ProcessDiagrams (Import Workflow wizard); unsupported BPMN elements get warning markers and must be replaced with supported node types. For authoring `.bpmn` directly, this skill does not apply.

package/skills/uipath-rpa/references/xaml/xaml-basics-and-rules.md

@@ -150,6 +150,8 @@ xmlns:upa="clr-namespace:UiPath.Process.Activities;assembly=UiPath.Process.Activ
 xmlns:upas="clr-namespace:UiPath.Process.Activities.Shared;assembly=UiPath.Process.Activities"
 ```
 
+These types ship in the **`UiPath.FlowchartBuilder.Activities`** package (runtime assembly `UiPath.Process.Activities`) — install before authoring (Common Rule 6). Not supported on `targetFramework: "Legacy"`. Package install, full node vocabulary, gateway patterns, suspend/resume: [long-running-workflow-guide.md](long-running-workflow-guide.md).
+
 ```xml
 <upa:ProcessDiagram DisplayName="Long Running Workflow" sap2010:WorkflowViewState.IdRef="ProcessDiagram_1">
   <upa:ProcessDiagram.StartNode>
@@ -188,6 +190,7 @@ xmlns:upas="clr-namespace:UiPath.Process.Activities.Shared;assembly=UiPath.Proce
 - `EventNode` = start/end circles, `TaskNode` = activity rectangles, `DecisionNode` = diamond (True/False branches), `EndNode` = end circle
 - `BoundaryNode` attaches to `TaskNode.BoundaryNodes` for error handling
 - Same `<x:Reference>` node registration rules as Flowchart — inline nodes need trailing registration
+- Gateway nodes (`SplitNode`/`MergeNode`/`SwitchNode<T>`), subprocesses, intermediate events, and persistence-based waits: [long-running-workflow-guide.md](long-running-workflow-guide.md)
 
 **ViewState is needed.** See [canvas-layout-guide.md § Long Running Workflow](canvas-layout-guide.md#5-long-running-workflow-processdiagram-layout) for horizontal layout recipes.
 

package/skills/uipath-solution/SKILL.md

@@ -1,30 +1,16 @@
 ---
 name: uipath-solution
-description: "Always invoke for `.uipx` files. UiPath Solution Design Document (SDD) authoring from PDDs and `uip solution` lifecycle. Covers `sdd.md`/`pdd.md`/`.uipx` files and `uip solution init/pack/publish/deploy/activate/upload/project add|import/resource refresh|add|remove|edit`. Selects scope (single product or multi-project Solution: RPA/Flow/Case/Agents/Apps/API Workflows), writes implementation-ready SDD, then packs and ships the `.uipx`. For task derivation across multiple skills→uipath-planner. For non-solution Orchestrator/IS/resources/auth/traces→uipath-platform. For .xaml/.cs→uipath-rpa. For .flow→uipath-maestro-flow. For .bpmn→uipath-maestro-bpmn. For agent.json and .py agents→uipath-agents. For caseplan.json→uipath-maestro-case."
-when_to_use: "User mentions sdd.md / pdd.md / Process Design Document / Solution Design Document / SDD / PDD / .uipx / 'uip solution' / 'pack the solution' / 'publish the solution' / 'deploy the solution' / 'activate' / multi-project / Solution scope / Solution Folder. Fires for 'design this automation', 'architect the solution', 'generate SDD', 'analyze this PDD', 'turn this PDD into code', 'create a new solution', 'add project/resource to solution', 'add a queue/asset/bucket/connection', 'import a cloud queue/asset', 'edit/remove a resource', 'change a queue/asset field', 'set an asset value'. Load BEFORE editing .uipx or running uip solution commands."
+description: "Always invoke for `.uipx` files. UiPath Solution lifecycle via the `uip solution` CLI: init/pack/publish/deploy/activate/upload, project add|import|remove, resource refresh|add|remove|edit. Bundles multiple automation projects (RPA/Flow/Case/Agents/API Workflows) into one deployable `.uipx`. For PDD→SDD design (sdd.md/pdd.md) & multi-skill task derivation→uipath-planner. For non-solution Orchestrator/IS/resources/auth/traces→uipath-platform. For .xaml/.cs→uipath-rpa. For .flow→uipath-maestro-flow. For .bpmn→uipath-maestro-bpmn. For agent.json and .py agents→uipath-agents. For coded-app deploy→uipath-coded-apps."
+when_to_use: "User mentions .uipx / 'uip solution' / 'pack the solution' / 'publish the solution' / 'deploy the solution' / 'activate' / multi-project / Solution scope / Solution Folder. Fires for 'create a new solution', 'add project/resource to solution', 'add a queue/asset/bucket/connection to the solution', 'import a cloud queue/asset', 'edit/remove a resource', 'change a queue/asset field', 'set an asset value in the solution'. Load BEFORE editing .uipx or running uip solution commands. For PDD→SDD design→uipath-planner; for an 'architect then deploy' two-phase request, run uipath-planner first, then return here to pack/deploy."
 ---
 
-# UiPath Solution — Design + Lifecycle
+# UiPath Solution — `uip solution` lifecycle
 
-> **Two entry points.** Use the **Design half** for PDD → SDD authoring; use the **Operate half** for `uip solution` lifecycle (init, pack, publish, deploy, activate). The two halves share no workflow — pick the right one from "When to Use" before applying any rule.
->
-> This skill nests Critical Rules and Workflow under each half — Design and Operate — rather than at the top level.
-
-## When to Use This Skill
-
-### Design entry — PDD → SDD
-
-- User provides a PDD (PDF, docx, markdown) and asks to design or build from it
-- User asks to design / architect / generate an SDD for a UiPath automation
-- User describes a complex automation involving multiple products (RPA + Agents, Flow + API Workflows, etc.) and wants architecture before code
-- A skill or main agent detected a PDD and redirected the user here
+Create, pack, publish, deploy, and manage UiPath Solution packages (`.uipx`) via the `uip solution` CLI surface. A Solution bundles multiple automation projects (processes, libraries, tests, agent projects, API workflows) into a single deployable unit.
 
-**Skip the Design half** when:
-- The request is a simple, well-defined single-skill task (e.g., "create a workflow that sends an email") — load the specialist (`uipath-rpa`, `uipath-agents`, etc.) directly.
-- An SDD already exists and the user wants the implementation task list — load `uipath-planner` directly with the SDD path.
-- The user's input is not a PDD (no process steps, application inventory, or exception handling) — clarify intent or redirect to `uipath-planner`.
+> **Use the CLI. Don't roll your own REST for solution ops.** Hand-rolling HTTP calls misses the `X-UIPATH-OrganizationUnitId` folder header, OData filter shape, pagination envelope, `pipelinesInstall` deploy semantics, retry behavior, and the `Result/Code/Data` output contract. The CLI is the source of truth.
 
-### Operate entry — `uip solution` lifecycle
+## When to Use This Skill
 
 - User has a `.uipx` solution and wants to pack / publish / deploy / activate / upload
 - User wants to create a new solution (`uip solution init`), add or remove projects, or refresh solution resources
@@ -32,54 +18,12 @@ when_to_use: "User mentions sdd.md / pdd.md / Process Design Document / Solution
 - User mentions deploy configs, environment promotion, or activating a deployed solution
 - A skill or main agent detected a `.uipx` file and redirected the user here
 
-**Skip the Operate half** when:
+**Skip this skill** when:
+- The task is PDD → SDD architecture/design (sdd.md / pdd.md) — load `uipath-planner`.
 - The deployable is a single non-solution package (e.g., a one-off RPA library or coded app) — those use `uip rpa publish` / `uip codedapp publish` and route through `uipath-platform` or the relevant specialist.
 - The task is non-solution Orchestrator work (folders, jobs, assets, queues, IS connections) — load `uipath-platform`.
 
----
-
-## Design — PDD → SDD
-
-Transform a Process Design Document (PDD) into an implementation-ready Solution Design Document (SDD). Select the right UiPath scope — either a single product (RPA Process/Library/Test Auto, Maestro Flow, Case Management, Agents, Coded Apps, or API Workflows) or a multi-project Solution composing several of them — based on PDD signals.
-
-After the SDD is written, hand off to `uipath-planner`. The planner reads the SDD, derives the per-skill task list, and routes execution to the correct specialists (including this skill's Operate half for solution-scope deploy).
-
-### Critical Rules
-
-1. **The SDD is implementation-oriented, not a PDD mirror.** Reorganize the PDD content into a structure a coding agent can execute against. Do not copy PDD sections verbatim.
-2. **Never invent selectors, UI targets, or element identifiers.** The SDD covers architecture only — selectors require application inspection at development time.
-3. **Follow the phased interaction model.** Read the full PDD first, recommend a product, present a summary with clarifying questions, get architecture approval, then generate the complete SDD. See [SDD Generation Guide](references/design/sdd-generation-guide.md).
-4. **Fill gaps with `[DEFAULT]` or `[SME REVIEW]`.** Use `[DEFAULT]` for industry-standard patterns (retry counts, timeouts). Use `[SME REVIEW]` for gaps requiring business knowledge. Never silently invent business rules.
-5. **The Project Structure section is the most important section.** It must list every workflow file (or node / stage / tool / page / step) with its responsibility, inputs, outputs, and which PDD steps it covers. Run Level 2.5 (Project Decomposition) BEFORE designing project structure — see Levels guide.
-6. **RPA data definitions follow the implementation mode.** For Coded C# or Hybrid mode: use C# `record` (immutable) or `class` (mutable). No inheritance. Max 15 properties per type. Default to `string` unless the PDD specifies numeric, date, or boolean operations. For XAML mode: use dictionary keys or DataTable columns.
-7. **Non-RPA products use their native type system.** For Agents, Coded Apps, Flow, Case Management, and API Workflows: use the JSON schema or type definition appropriate to that product's template.
-8. **Write the `## Planner Handoff` header AND the `<!-- planner-handoff:v1 -->` marker into every SDD.** This is a load-bearing contract — `uipath-planner` detects SDDs by either signal. The marker sits adjacent to the heading in every template; both must survive into the generated file so a hand-edit that renames the heading still leaves the marker for detection. Fields: Execution autonomy, SDD scope, Project list section, Tasks file, Generated by, Generation date.
-9. **Select the primary scope BEFORE designing architecture.** The scope (single product or Solution) determines the template(s) and project structure. Use the [Product Selection Guide](references/design/product-selection-guide.md) Level 1 → Level 1.5 (RPA sub-type) → Level 1.75 (Solution composition) → Level 2.5 (project decomposition). Present the recommended scope first with single-product alternatives and "Solution (customize)" below. The skill that builds the workflows/nodes/tasks owns the final detailed decisions.
-10. **Write the SDD to the current working directory AND honour the template's section structure as a hard superset contract.** For single-product scope, one file at `<PROCESS_NAME_KEBAB>-sdd.md`. For Solution scope, a `<SOLUTION_NAME_KEBAB>-solution-sdd.md` overview plus one `<PROJECT_NAME_KEBAB>-sdd.md` per project in the unified project list. If the user specifies a path, use that instead. **After writing, diff the generated SDD's H2/H3 headings against the template's Table of Contents — the generated set MUST be a superset of the template's TOC headings (you may add subsections, never drop one).** If any template-required H2 (e.g., `## 4. Business Rules`, `## 5. Data Definitions`, `## 7. Exception Handling`, `## 8. Error Handling`, `## 17. Testing Strategy`) is missing, regenerate that section before declaring done. A missing template section is an SDD defect, not an `[SME REVIEW]` item.
-11. **Do not generate an Implementation Plan inside the SDD.** Implementation tasks are owned by `uipath-planner`. The SDD ends with a `## Next Steps` section pointing at the planner. Architecture only — no task lists, no skill routing prompts, no *implementation* `TaskCreate` calls. (The Phase 1 Step 0.5 *progress-tracking* `TaskCreate` calls are explicitly allowed — they track SDD-generation progress, not implementation work, and are subject to Rule G-8.)
-12. **Always generate a thorough §17 Testing Strategy.** Cover happy path, edge cases, error scenarios, and (for Master Projects) end-to-end pipeline tests. Test depth is non-negotiable — never offer the user a "happy path only" option. Implementation specialists may scope down at execution time if needed.
-13. **Use AskUserQuestion for Agent/Coded App gaps.** If the primary product is Agents or Coded Apps and the PDD lacks required details (framework, tools, pages, flows), use `AskUserQuestion` to ask if the user wants to proceed with gap-filling or use a different product. Never auto-fallback.
-14. **All user questions use numbered-choice format by default; use `multiSelect: true` only for Solution composition and Tenant Library Discovery.** Every `AskUserQuestion` uses a blockquote with numbered options and a `*(recommended)*` tag on the default choice. This applies to execution mode, language, product gap-filling, fallback selection, SME review resolution, RPA sub-type, and scope confirmation. The exceptions are Level 1.75 Pass A (Solution composition) and Step 2.5 Tenant Library Discovery, which use `multiSelect: true` so the user can check every product / library that applies.
-15. **For "leverage / find shared libraries" requests (Step 2.5 or ad-hoc), search the tenant feed — not the local filesystem, project folder, NuGet.org, or keyword-permutation loops.** Run the auth preflight first (`uip resource libraries list --limit 1 --output json`); on `Result: Failure` with an auth message, take the manual fallback from the guide — do NOT retry silently. On success, run the keyword call `uip resource libraries list --limit 500 --output-filter "<JMESPath>" --output json`. On zero results from the filtered call, take the fallback branch — do not re-keyword. See [Tenant Library Search Guide](references/design/tenant-library-search-guide.md) for the full procedure.
-16. **The terminal artefact of an SDD-driven build is a packed `.uipx` solution.** When implementation reports complete, the SDD's §18 Next Steps points the user back to this skill's Operate half: `uip solution init` → `uip solution project add` (one per project in the unified list) → `uip solution resource refresh` → `uip solution pack`. A bare project folder is not the deliverable. The Operate half owns this; the Design half flags it as the final step.
-
-### Workflow
-
-The SDD generation has 3 phases. Detail in the [SDD Generation Guide](references/design/sdd-generation-guide.md). All user questions use numbered-choice format.
-
-1. **Phase 1 — PDD Analysis & Scope Selection.** Ask execution mode (Autonomous or Interactive). Read the full PDD, extract structured information, run Level 1 (primary scope) → Level 1.5 (RPA sub-type if applicable) → Level 1.75 (Solution composition if applicable) → Level 2.5 (project decomposition). In Interactive mode, present a summary with the recommended scope at the top and alternatives below. In Autonomous mode, proceed without pausing. For Agent/Coded App products with missing info, use `AskUserQuestion` for gap-filling or fallback (both modes).
-2. **Phase 2 — Architecture Review.** Load the product-specific template. Generate the architectural core sections (template-specific — see Phase 2 Step 2 of the generation guide). In Interactive mode, present for review. In Autonomous mode, proceed without pausing.
-3. **Phase 3 — Full SDD Generation.** Generate all remaining sections including the thorough §17 Testing Strategy. Resolve `[SME REVIEW]` items by asking the user before writing (both modes). Write the `## Planner Handoff` header. Write the SDD to disk. Tell the user to load `uipath-planner` next.
-
----
-
-## Operate — `uip solution` lifecycle
-
-Create, pack, publish, deploy, and manage UiPath Solution packages (`.uipx`) via the `uip solution` CLI surface. A Solution bundles multiple automation projects (processes, libraries, tests, agent projects, API workflows) into a single deployable unit.
-
-> **Use the CLI. Don't roll your own REST for solution ops.** Hand-rolling HTTP calls misses the `X-UIPATH-OrganizationUnitId` folder header, OData filter shape, pagination envelope, `pipelinesInstall` deploy semantics, retry behavior, and the `Result/Code/Data` output contract. The CLI is the source of truth.
-
-### CLI Surface Probe
+## CLI Surface Probe
 
 Before the first `uip solution …` command in a session, probe the `solution` surface to detect pre- vs post-rename CLI:
 
@@ -89,7 +33,7 @@ uip solution init --help --output json
 
 - Result `Success` → post-rename CLI (default). Use the commands and flags as documented in the references.
 - `unknown command` / non-zero exit → pre-rename CLI. Translate via the table below before each call. Re-probe on any later `unknown command` error.
-- `command not found` / `uip: not found` / `'uip' is not recognized` → CLI not installed. Tell the user to run `npm install -g @uipath/cli`, then `uip login`, and abort the Operate-half work until those succeed.
+- `command not found` / `uip: not found` / `'uip' is not recognized` → CLI not installed. Tell the user to run `npm install -g @uipath/cli`, then `uip login`, and abort the work until those succeed.
 
 | Post-rename (default) | Pre-rename equivalent |
 |---|---|
@@ -99,19 +43,19 @@ uip solution init --help --output json
 
 All other `solution` subcommands (`pack`, `publish`, `deploy activate/status/uninstall`, `upload`, `resource …`, `project add/import`) are unchanged on both surfaces.
 
-### Critical Rules
+## Critical Rules
 
 1. **Probe the CLI surface before the first `uip solution` command in a session.** Run `uip solution init --help --output json`. `Success` = post-rename CLI (default); `unknown command` = pre-rename CLI — translate via the fallback table above. Re-probe on any later `unknown command` error.
 2. **Always use `--output json`** for `uip solution` commands whose output you parse. JSON is compact and stable; the default for non-interactive runs.
 3. **Use the CLI, never roll your own REST for solution operations.** Hand-rolled HTTP calls miss the `X-UIPATH-OrganizationUnitId` header, OData filter shape, pagination envelope, and `pipelinesInstall` deploy semantics. Only fall through to REST after confirming no `uip solution` command covers the task.
-4. **Never hand-edit `resources/solution_folder/`.** It's auto-generated by `uip solution project add` / `import` and auto-cleaned by `project remove`. Manual edits desync from `.uipx` and produce silent failure modes. See [scenarios/manual-edits.md](references/operate/scenarios/manual-edits.md).
+4. **Never hand-edit `resources/solution_folder/`.** It's auto-generated by `uip solution project add` / `import` and auto-cleaned by `project remove`. Manual edits desync from `.uipx` and produce silent failure modes. See [scenarios/manual-edits.md](references/scenarios/manual-edits.md).
 5. **`.uipx` and `resources/solution_folder/` must always agree on the project set.** Diffing them is the fastest way to detect corrupted state. If they disagree, fix via `uip solution project add/remove` — never by editing either side directly.
-6. **Run `uip solution resource refresh` before `pack` or `upload`.** Bundled artefact files and `userProfile/<userId>/debug_overwrites.json` must reflect current cloud state. Skipping refresh ships stale bindings.
+6. **Run `uip solution resources refresh` before `pack` or `upload`.** Bundled artefact files and `userProfile/<userId>/debug_overwrites.json` must reflect current cloud state. Skipping refresh ships stale bindings.
 7. **Coded apps are NOT registered in `.uipx`.** `uip solution project add` does not apply to coded-app directories; they deploy independently via `uip codedapp publish / deploy`. A coded app folder can sit alongside a solution but is not part of its manifest.
-8. **Verify the artifact after every CLI mutation.** Read `project.json`, `.uipx`, or `uip solution deploy status` output — exit codes lie. This mirrors the Design half's "verify the SDD after write" discipline. Verification is additional; it does not replace requested read-only list commands. If the user asks to show or list registered projects, solution resources, packages, deployments, or statuses, run the matching `uip solution ... list/status --output json` command and then inspect files only as a secondary sanity check.
+8. **Verify the artifact after every CLI mutation.** Read `project.json`, `.uipx`, or `uip solution deploy status` output — exit codes lie. Verification is additional; it does not replace requested read-only list commands. If the user asks to show or list registered projects, solution resources, packages, deployments, or statuses, run the matching `uip solution ... list/status --output json` command and then inspect files only as a secondary sanity check.
 9. **For multi-environment promotion, the deploy config (`-c <CONFIG_KEY>`) is the environment selector.** Same `.uipx` deploys to dev/staging/prod via different config keys, not different packages.
 
-### Workflow
+## Workflow
 
 The typical lifecycle for a UiPath Solution:
 
@@ -131,71 +75,25 @@ Two distinct distribution paths from the same source:
 - **`pack` → `publish` → `deploy run`** — promotes a versioned package to Orchestrator.
 - **`upload`** — pushes the solution to Studio Web for browser-based debugging only. Does not produce a published package and cannot be deployed via `deploy run`.
 
-Authentication is a prerequisite. Run `uip login --output json` before any operate-half work; see `uipath-platform` for full auth options (interactive OAuth, client credentials, tenant switching).
+Authentication is a prerequisite. Check `uip login status --output json` before any work; if not logged in, ask the user to run `uip login` (interactive browser flow). See `uipath-platform` for full auth options (interactive OAuth, client credentials, tenant switching).
 
----
+This skill is the terminal step of an SDD-driven build: after `uipath-planner` produces the SDD and derives the task list, and implementation specialists build the projects, the `.uipx` is packed and shipped here.
 
 ## Reference Navigation
 
-### Design references
-
-| File | Purpose |
-|------|---------|
-| [SDD Generation Guide](references/design/sdd-generation-guide.md) | Phase orchestrator — Phase 1, 2, 3 step-by-step instructions |
-| [PDD Analysis Guide](references/design/pdd-analysis-guide.md) | How to extract structured data from PDDs in any format |
-| [Product Selection Guide](references/design/product-selection-guide.md) | Canonical home for **Level 1** (primary scope), **Level 1.75** (Solution composition), **Level 2.5 Part B** (cross-product project list merge), **Level 3** (capability add-ons), template mapping |
-| [RPA Product Guide](references/design/rpa-product-guide.md) | RPA-only canonical home for **Level 1.5** (sub-type), **Level 2** (authoring mode), **Level 2.5 Part A** (RPA decomposition), R-07 naming convention, REFramework guidance. Load when Level 1 = RPA or a Solution includes RPA. |
-| [Package Selection Guide](references/design/package-selection-guide.md) | NuGet package selection per Application Inventory; Integration Service vs NuGet decision rules; per-product dependency manager (RPA: NuGet, Coded Apps: npm, etc.). Load when filling §14 Packages or equivalent. |
-| [Tenant Library Search Guide](references/design/tenant-library-search-guide.md) | Step 2.5 procedure for discovering deployed libraries via `uip resource libraries list` + JMESPath filtering. Covers auth preflight, keyword extraction, ranking, zero-results branch, and the manual fallback when unauthenticated. |
-
-### Operate references
-
 | File | Purpose |
 |------|---------|
-| [Solution Overview](references/operate/solution-overview.md) | What a Solution is, `.uipx` manifest, file structure, lifecycle diagram, command tree |
-| [Develop a Solution](references/operate/develop-solution.md) | `uip solution init / project add / import / remove / resource refresh / resource add / resource remove / resource edit`; field-tested gotchas |
-| [Pack and Deploy](references/operate/pack-and-deploy.md) | `pack / publish / deploy run`, deploy configs, CI/CD pipeline patterns |
-| [Activate and Manage](references/operate/activate-and-manage.md) | `deploy activate / status / uninstall`, environment management |
-| [Scenarios Index](references/operate/scenarios.md) | Failure modes and edge cases — manual edits, shared resources, virtual resources, name collisions |
-
-### SDD templates
-
-| File | Purpose |
-|------|---------|
-| [RPA Template](assets/templates/rpa-sdd-template.md) | SDD template for RPA Process / Library / Test Automation |
-| [Flow Template](assets/templates/flow-sdd-template.md) | SDD template for Maestro Flow |
-| [Case Management Template](assets/templates/case-sdd-template.md) | SDD template for Case Management |
-| [Agent Template](assets/templates/agent-sdd-template.md) | SDD template for UiPath Agents |
-| [Coded App Template](assets/templates/coded-app-sdd-template.md) | SDD template for Coded Apps (web) |
-| [API Workflow Template](assets/templates/api-workflow-sdd-template.md) | SDD template for API Workflows |
-
----
+| [Solution Overview](references/solution-overview.md) | What a Solution is, `.uipx` manifest, file structure, lifecycle diagram, command tree |
+| [Develop a Solution](references/develop-solution.md) | `uip solution init / project add / import / remove / resource refresh / resource add / resource remove / resource edit`; field-tested gotchas |
+| [Pack and Deploy](references/pack-and-deploy.md) | `pack / publish / deploy run`, deploy configs, CI/CD pipeline patterns |
+| [Activate and Manage](references/activate-and-manage.md) | `deploy activate / status / uninstall`, environment management |
+| [Scenarios Index](references/scenarios.md) | Failure modes and edge cases — manual edits, shared resources, virtual resources, name collisions |
 
 ## Anti-patterns
 
-### Design anti-patterns
-
-1. **Copying the PDD structure into the SDD.** The SDD must reorganize content for implementation, not mirror the PDD's document flow.
-2. **Defaulting to RPA Process when the PDD describes something else.** Use the Product Selection Guide's decision tree. A PDD with AI reasoning signals should go to Agents; a PDD with stages/SLA/approval should go to Case Management.
-3. **Inventing selectors from screenshots.** Screenshots help understand the UI flow but cannot produce reliable selectors. Leave selector work for development time.
-4. **Generating the full SDD without user checkpoints.** Always present the product recommendation (end of Phase 1) AND the architecture (Phase 2) before generating the rest. The product choice and project structure are the hardest to fix later.
-5. **Asking the user about every gap.** Use `[DEFAULT]` for standard patterns. Only escalate with `[SME REVIEW]` for business-knowledge gaps. Use `AskUserQuestion` only for Agent/Coded App gap-filling.
-6. **Generating an Implementation Plan section inside the SDD.** Implementation tasks belong to `uipath-planner`. Every SDD ends with `## Next Steps` pointing at the planner. Do not include Task 1 / Task 2 / Task N task templates. Do not call `TaskCreate` for *implementation* tasks (the Phase 1 Step 0.5 progress-tracking tasks are a separate, allowed use). Architecture only.
-7. **Asking the user about test coverage depth.** §17 Testing Strategy is always thorough — happy path, edge cases, error scenarios, e2e for Master Projects. The implementation specialist scopes down at execution time if the user wants a quick MVP; the SDD does not.
-8. **Generating overly abstract workflow/node/task descriptions.** Each item in the inventory must have a concrete responsibility, specific PDD step references, and defined inputs/outputs.
-9. **Auto-falling-back from Agents/Coded Apps to another product without asking.** If the PDD is missing product-specific details, use `AskUserQuestion` — the user chooses whether to proceed with gap-filling or pick a different product.
-10. **Inlining HITL schema for Flow/Maestro/Agent products.** HITL for those products is owned by the `uipath-human-in-the-loop` skill. Flag touchpoints only. Case Management is the exception — it handles HITL tasks inline.
-11. **Putting everything in a single RPA project when the PDD has distinct processing stages.** If the PDD describes email ingestion + data extraction + output generation + reporting, these are separate projects connected by Orchestrator queues — not one monolithic process. Run Level 2.5 Part A from the RPA Product Guide.
-12. **Forcing a single-product scope when the PDD describes multiple coordinated projects.** If the PDD needs (for example) 2 RPA Libraries + 1 Test Automation project, or a Flow plus callable API Workflows, the correct scope is **Solution** — not a single-product SDD that buries the rest as "integrated components". Watch the Level 1 Solution Signals and offer Solution (customize) as an alternative on the recommendation screen.
-13. **Ignoring REFramework for queue-based transactional processing.** REFramework is the standard UiPath framework for Performer projects that consume from Orchestrator queues. Custom frameworks for this pattern lead to fragile, non-standard implementations.
-14. **Omitting NuGet package dependencies.** Developers need to know which packages to install. Infer packages from the Application Inventory and list them in §14 Packages — see the [Package Selection Guide](references/design/package-selection-guide.md).
-15. **Renaming the `## Planner Handoff` heading or stripping the `<!-- planner-handoff:v1 -->` marker.** Either signal alone is sufficient for `uipath-planner` to detect the SDD, but both should remain — they are redundant on purpose. Removing both breaks Lane A silently.
-
-### Operate anti-patterns
-
 1. **Hand-rolling REST calls for `pack`, `publish`, `deploy run`, or `activate`.** The `uip solution` CLI handles auth, folder headers, pipeline semantics, and pagination correctly. Reach for REST only after confirming no command covers the task.
 2. **Editing `resources/solution_folder/` directly.** It is auto-generated and auto-cleaned. Manual edits desync from `.uipx`. Use `uip solution project add/remove` instead.
-3. **Skipping `uip solution resource refresh` before `pack` or `upload`.** Ships stale bindings and debug-overwrite state.
+3. **Skipping `uip solution resources refresh` before `pack` or `upload`.** Ships stale bindings and debug-overwrite state.
 4. **Adding a coded-app directory via `uip solution project add`.** Coded apps have no `project.uiproj` / `project.json` and are not packed by `uip solution pack`. Deploy them independently via `uip codedapp publish / deploy`.
 5. **Creating a new `.uipx` per environment instead of using deploy configs.** One solution package promotes to dev/staging/prod via different `-c <CONFIG_KEY>` values. Different `.uipx` files per environment defeats version tracking.
 6. **Using `uip solution upload` (Studio Web) as a deployment path.** Upload is for browser-based debugging only — it does not produce a published package and cannot be promoted via `deploy run`. Use `pack` → `publish` → `deploy run` for real deploys. `upload` also lands the solution in Studio Web's **Cloud workspace** tab — not the Local tab; SW's Local tab is a separate registration not addressable by `uip solution`.

package/skills/uipath-solution/references/{operate/activate-and-manage.md → activate-and-manage.md}

@@ -13,7 +13,7 @@ Activate deployed solutions, uninstall deployments, and manage published solutio
 
 ## Prerequisites
 
-- Authenticated (`uip login`)
+- Authenticated — verify with `uip login status`; if not logged in, ask the user to run `uip login` (it opens an interactive browser flow)
 - Solution deployed (see [pack-and-deploy.md](pack-and-deploy.md))
 
 ## Flow