@uipath/skills 1.195.0

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

@@ -0,0 +1,91 @@
+# Diagnose - Investigate failed BPMN runs
+
+Capability index for post-run investigation.
+Diagnose owns the diagnostic priority ladder for BPMN Process Orchestration runs: incidents, runtime variables,
+deployed BPMN asset correlation, element executions, cursors, generated package metadata, and traces.
+
+> **Where you came from / where to go next.** Diagnose is downstream of Operate (a debug or deployed run failed, hung,
+> or behaved unexpectedly) and points back to Author for source fixes.
+> Running and lifecycle live in [operate/CAPABILITY.md](../operate/CAPABILITY.md);
+> source fixes live in [author/CAPABILITY.md](../author/CAPABILITY.md).
+>
+> **Inherits universal rules from [SKILL.md](../../SKILL.md).** BPMN source is model-authored; generated package files
+> and Integration Service enrichment are CLI-owned.
+> Use `uip maestro bpmn ... --output json` for diagnostic reads and redact private runtime data in summaries.
+
+## When to use this capability
+
+- Triage a failed debug or deployed process run.
+- Read incidents and faulting element IDs.
+- Inspect runtime variables and element executions.
+- Fetch the deployed BPMN asset when local files may differ.
+- Map runtime failures back to BPMN source and generated package metadata.
+- Identify failures caused by unresolved Integration Service enrichment, bad bindings, missing diagrams, invalid mappings,
+  or stale package files.
+- Decide whether the safe next action is retry, cancel, migrate, cursor movement, re-authoring, package regeneration,
+  or cloud configuration repair.
+
+## Critical rules
+
+1. **Investigate in priority order** - context, incidents, runtime variables, deployed BPMN asset,
+   element executions/cursors, generated package files, then traces.
+2. **Always include folder context on instance and incident reads** - `instance` commands require `--folder-key` or `-f`,
+   and `incident get` requires `--folder-key`.
+3. **Use the CLI as the diagnostic interface** - run `uip maestro bpmn ... --output json` reads. When mock or fixture
+   files are present in a test harness, treat them as CLI backing data and do not read those files directly unless you
+   are explicitly debugging the mock harness.
+4. **Fetch deployed BPMN when local source may differ** - do not assume the working tree matches what ran.
+5. **Map failures to BPMN element IDs** - use IDs to identify the source node, gateway, event, sequence flow,
+   or extension that needs Author work.
+6. **Separate runtime symptoms from ownership of the fix** - BPMN structure and mappings belong in Author;
+   Integration Service enrichment and generated JSON come from CLI generation;
+   folder/process/release choices belong to cloud configuration.
+7. **Do not expose private runtime data** - redact tenant, user, connection, folder, URL, payload,
+   and secret values in summaries.
+8. **Do not mutate while diagnosing** - retry, cancel, migrate, and cursor movement are Operate actions and require
+   explicit user consent after root cause analysis.
+
+## Workflow
+
+| Journey | Read |
+| --- | --- |
+| Triage a failed run | [references/troubleshooting-guide.md](references/troubleshooting-guide.md) |
+| Recognize recurring failure patterns | [references/failure-modes.md](references/failure-modes.md) |
+
+## Common tasks
+
+| I need to... | Read these |
+| --- | --- |
+| Find the faulting element | [references/troubleshooting-guide.md](references/troubleshooting-guide.md) |
+| Compare local and deployed BPMN | [references/troubleshooting-guide.md](references/troubleshooting-guide.md) |
+| Inspect runtime variables, cursors, or element executions | [references/troubleshooting-guide.md](references/troubleshooting-guide.md) |
+| Diagnose binding or generated JSON issues | [failure modes](references/failure-modes.md), [project layout](../shared/project-layout.md) |
+| Diagnose Integration Service runtime issues | [failure modes](references/failure-modes.md) |
+| Decide whether retry is safe | [troubleshooting guide](references/troubleshooting-guide.md), [manage guide](../operate/references/manage.md) |
+| Fix the source | [author/CAPABILITY.md](../author/CAPABILITY.md) |
+
+For Integration Service enrichment details, read
+[author/references/plugins/integration-service/impl.md](../author/references/plugins/integration-service/impl.md).
+
+## Anti-patterns
+
+- **Never start with verbose traces when incidents are available.**
+- **Never call runtime lifecycle commands while diagnosing.** Diagnose reads; Operate mutates after explicit consent.
+- **Never assume local BPMN is the deployed asset.**
+- **Never retry before root cause is known.**
+- **Never paste private incident payloads or connection details into docs, commits, or issue comments.**
+- **Never patch generated package files as the only fix for a BPMN source defect.**
+
+## References
+
+### Diagnose-scoped
+
+- [troubleshooting-guide.md](references/troubleshooting-guide.md) - diagnostic priority ladder
+- [failure-modes.md](references/failure-modes.md) - recurring failure patterns
+
+### Cross-capability
+
+- [shared/bpmn-xml-contract.md](../shared/bpmn-xml-contract.md) - XML authoring and validation boundaries
+- [shared/project-layout.md](../shared/project-layout.md) - generated files and package shape
+- [shared/variables-bindings-expressions.md](../shared/variables-bindings-expressions.md) - mappings and binding expressions
+- [shared/public-safety.md](../shared/public-safety.md) - redaction and sanitization

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

@@ -0,0 +1,129 @@
+# Failure Modes
+
+## Missing diagram
+
+Studio Web import rejects BPMN without a valid diagram and plane.
+Add `bpmndi:BPMNDiagram`, `bpmndi:BPMNPlane`, shapes for nodes, and edges for sequence flows.
+
+## Orphaned diagram plane
+
+A diagram plane references a process, collaboration, or subprocess that no longer exists.
+Point the plane to a valid element or remove the orphaned diagram.
+
+## Missing shape or waypoint
+
+Rendered elements without BPMN DI may parse but fail to render correctly. Add bounds for nodes and waypoints for edges.
+
+## Entry point mismatch
+
+Entry point inputs reference a start event through `elementId`, but the start event lacks the matching
+`uipath:entryPointId` or the ID is duplicated.
+Fix root start event extensions and variable scoping.
+
+## Binding reference missing
+
+A node context value refers to `=bindings.<id>` but no matching root binding or generated binding resource exists.
+Fix the BPMN binding source or rerun CLI enrichment/generation.
+
+## Integration Service draft executed
+
+An Integration Service activity or trigger was left as model-authored draft intent and reached upload/debug/run without
+CLI enrichment.
+Enrich connector metadata, connection binding, dynamic schemas, and generated resources before operating.
+
+Signs:
+
+- Incident points at a connector activity/event.
+- Runtime variables show missing or malformed connector output.
+- Deployed BPMN still contains draft intent rather than registry-backed `uipath:activity` or `uipath:event` metadata.
+- `bindings_v2.json` lacks the corresponding generated binding resource.
+
+Fix ownership: CLI enrichment/generation owns connector metadata, connection binding, dynamic schemas,
+and generated package resources.
+The model may adjust BPMN structure around the connector but must not invent connection IDs or private connector payloads.
+
+## Stale generated package files
+
+Generated JSON no longer reflects the BPMN source.
+Regenerate package metadata and verify package descriptor content before upload or deploy.
+
+Signs:
+
+- `entry-points.json` references an old start event ID or BPMN file.
+- `package-descriptor.json` omits the current BPMN or generated JSON files under `content/`.
+- `operate.json` points at the wrong main file or runtime metadata.
+- `bindings_v2.json` does not match executable binding references in the BPMN.
+
+Fix ownership: change `.bpmn` only when the source is wrong; otherwise rerun the supported CLI package/enrichment path.
+
+## Invalid gateway defaults
+
+Exclusive or inclusive gateways have ambiguous conditions, missing defaults, or a default flow that points to the wrong
+sequence flow.
+Fix outgoing conditions and default references.
+
+Runtime symptom: the instance stalls or takes an unexpected branch.
+Diagnose with variables at the gateway, element executions, and cursors before changing conditions.
+
+## Boundary error mismatch
+
+A boundary error event references a missing or duplicate error definition, or is attached to an invalid activity.
+Reconcile the error definition within the correct scope.
+
+## Multi-instance variable mismatch
+
+A multi-instance activity references an input collection or item variable that is not declared in the expected scope.
+The process may parse, then fail or stall when the loop starts because the runtime cannot bind per-item state.
+
+Signs:
+
+- `uipath:loopCharacteristics` uses an `inputCollection` expression that does not match a declared variable.
+- `inputElement` points at an undeclared item variable or a variable that is reused for unrelated state.
+- A completion condition mutates state instead of evaluating state.
+- Per-item output mappings target variables that are not declared in the subprocess or root scope.
+
+Fix ownership: declare collection and item variables in `.bpmn`, keep item and aggregate outputs distinct,
+and model retry/error behavior as visible BPMN paths rather than hidden loop metadata.
+
+## Message reference mismatch
+
+A catch, throw, or receive event references a message ID that is missing, renamed, or no longer matches the runtime
+message contract.
+
+Runtime symptom: the instance waits indefinitely at a message event or faults during event subscription.
+Diagnose with cursors and element executions, then reconcile the `bpmn:message`, `messageRef`, and any
+`uipath:event` message context in BPMN source.
+
+## Expression treated as literal
+
+An expression field is authored as a plain literal string.
+Use expression form where Maestro expects evaluation, and avoid assignment operators in fields where
+validation forbids assignment.
+
+## Deployed asset differs from local BPMN
+
+The local `.bpmn` does not match the deployed asset fetched from the faulted instance.
+This happens after republish, branch switching, package reuse, or local edits made after deployment.
+
+Diagnose what actually ran:
+
+```bash
+uip maestro bpmn instance asset <INSTANCE_ID> -f <FOLDER_KEY> --output json
+```
+
+Fix ownership: correlate the incident to deployed BPMN first.
+Then decide whether to re-author local BPMN, republish, or operate the existing instance.
+
+## Runtime state stuck at event or gateway
+
+The instance has no active fault but is not progressing.
+Inspect cursors and element executions before using lifecycle actions:
+
+```bash
+uip maestro bpmn instance cursors <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance element-executions <INSTANCE_ID> -f <FOLDER_KEY> --output json
+```
+
+Common causes include a message/event wait without the expected signal, a timer configuration mismatch,
+gateway conditions that never evaluate true, or a subprocess dependency waiting externally.
+Cursor movement is an Operate action and requires explicit user consent.

package/skills/uipath-maestro-bpmn/references/diagnose/references/troubleshooting-guide.md

@@ -0,0 +1,159 @@
+# Troubleshooting Guide
+
+Use this priority ladder for failed or misbehaving BPMN runs.
+
+> **Read-only boundary:** this guide diagnoses.
+> Retry, cancel, migrate, and cursor movement are Operate actions and require explicit user consent after root cause is known.
+>
+> **Folder context:** `uip maestro bpmn instance ...` commands require `--folder-key <FOLDER_KEY>` or
+> `-f <FOLDER_KEY>`.
+> `uip maestro bpmn incident get` requires `--folder-key <FOLDER_KEY>`.
+
+## Step 1 - Confirm context
+
+Collect public-safe identifiers:
+
+- Process or package name.
+- Instance/job ID.
+- Folder/context label.
+- Approximate run time.
+- Local commit or package version, if known.
+- Whether the run came from `uip maestro bpmn debug` or `uip maestro bpmn process run`.
+
+Do not record secrets, tenant URLs, connection IDs, or payload data in public notes.
+
+If you only have a deployed-process job key, start with:
+
+```bash
+uip maestro bpmn job status <JOB_KEY> --folder-key <FOLDER_KEY> --output json
+```
+
+Parse the instance ID, folder context, process key, final status, and any trace/run identifiers from the JSON output.
+For debug runs, prefer the `instanceId` returned by
+`uip maestro bpmn debug` and inspect it with `debug-instance` commands. Keep
+deployed-instance status reads and debug-session inspection separate.
+
+## Step 2 - Read incidents
+
+Find the incident category, message, and faulting BPMN element ID.
+If multiple incidents exist, start with the first root fault and avoid chasing downstream cancellation noise.
+
+```bash
+uip maestro bpmn instance incidents <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn incident get <INCIDENT_ID> --folder-key <FOLDER_KEY> --output json
+uip maestro bpmn incident summary --output json
+```
+
+For process-level incident overview:
+
+```bash
+uip maestro bpmn processes incidents <PROCESS_KEY> --output json
+```
+
+## Step 3 - Inspect runtime variables
+
+Inspect variables around the faulting element.
+Redact private payloads.
+Check whether expected outputs were missing, malformed, or literal strings instead of evaluated expressions.
+If the user reports a behavioral mismatch, inspect variables even when the final
+run status is `Completed`; a completed run only proves control-flow completion,
+not semantic correctness.
+
+```bash
+uip maestro bpmn instance variables <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance variables <INSTANCE_ID> -f <FOLDER_KEY> --parent-element-id <ELEMENT_ID> --output json
+```
+
+For affected elements, confirm runtime inputs and outputs match the modeled
+contract before changing source.
+
+## Step 4 - Correlate deployed BPMN
+
+Fetch the deployed BPMN asset when local source may differ. Compare:
+
+- Faulting element ID.
+- Root variables and mappings.
+- Binding expressions.
+- Integration Service extension content.
+- Diagram and sequence-flow structure when the failure is import or package related.
+
+```bash
+uip maestro bpmn instance asset <INSTANCE_ID> -f <FOLDER_KEY> --output json
+```
+
+Use the incident's faulting element ID to locate the BPMN element in the deployed asset first, then compare to local
+`.bpmn`.
+If they differ, diagnose what actually ran and treat local edits as a future fix, not as the executed definition.
+
+## Step 5 - Inspect element executions and cursors
+
+Element executions and cursors show where the runtime moved before it faulted or hung:
+
+```bash
+uip maestro bpmn instance element-executions <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance cursors <INSTANCE_ID> -f <FOLDER_KEY> --output json
+```
+
+Use these to distinguish a modeling problem from a runtime-state problem:
+
+- Activity fault: inspect the activity's inputs, mappings, extension payload, and upstream variables.
+- Gateway stall: inspect outgoing sequence-flow conditions, default flow, and variable values.
+- Event wait: inspect message/timer configuration, subscriptions, and whether the expected external signal exists.
+- Subprocess or call activity fault: identify the child dependency, but do not invoke sibling skills automatically.
+
+## Step 6 - Check generated package files
+
+If the failure is binding, entry point, package, or runtime metadata related, inspect generated JSON:
+
+- `bindings_v2.json`
+- `entry-points.json`
+- `operate.json`
+- `package-descriptor.json`
+
+Generated-file mismatch usually means Author should fix BPMN or rerun CLI generation/enrichment.
+
+Correlate package files to the deployed BPMN:
+
+- `entry-points.json` should reference the intended BPMN file and start event.
+- `bindings_v2.json` should contain generated resources required by executable resource and connector elements.
+- `operate.json` should identify the intended main file/runtime metadata.
+- `package-descriptor.json` should include BPMN and generated JSON files under `content/`.
+
+## Step 7 - Pull traces last
+
+Use verbose traces only when incidents, variables, deployed asset, and package files do not explain the issue.
+
+```bash
+uip maestro bpmn job traces <JOB_KEY> --output json
+```
+
+## Output
+
+Return a concise diagnosis:
+
+- Faulting element ID.
+- User-visible symptom.
+- Likely root cause.
+- Whether the fix belongs in BPMN source, CLI enrichment, generated package files, or cloud configuration.
+- Safe next action.
+
+## CLI command reference
+
+```bash
+uip maestro bpmn job status <JOB_KEY> --output json
+uip maestro bpmn job traces <JOB_KEY> --output json
+uip maestro bpmn instance get <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance incidents <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance variables <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance variables <INSTANCE_ID> -f <FOLDER_KEY> --parent-element-id <ELEMENT_ID> --output json
+uip maestro bpmn instance asset <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance element-executions <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance cursors <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn incident get <INCIDENT_ID> --folder-key <FOLDER_KEY> --output json
+uip maestro bpmn incident summary --output json
+uip maestro bpmn processes incidents <PROCESS_KEY> --output json
+```
+
+Lifecycle commands are intentionally absent from this diagnostic command list.
+Use [operate/references/manage.md](../../operate/references/manage.md) only after the diagnosis supports a
+side-effecting action and the user consents.

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

@@ -0,0 +1,91 @@
+# Operate - Package, ship, run, and manage BPMN processes
+
+Capability index for BPMN Process Orchestration lifecycle work. Operate owns the steps that prepare a BPMN project
+for the cloud and the steps that touch the cloud: package generation, Studio Web upload, Orchestrator publish/deploy,
+debug/run, job inspection, and instance lifecycle.
+These actions may contact UiPath services or external systems.
+
+> **Where you came from / where to go next.** Operate is downstream of Author (model-authored BPMN plus CLI
+> validation/enrichment) and upstream of Diagnose (runtime faults and state inspection).
+> BPMN source work lives in [author/CAPABILITY.md](../author/CAPABILITY.md);
+> post-run investigation lives in [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md).
+>
+> **Inherits universal rules from [SKILL.md](../../SKILL.md).** In particular: BPMN XML is source, generated package
+> files and Integration Service enrichment are CLI-owned, parsed CLI output uses `--output json`, and
+> upload/publish/deploy/debug/run/lifecycle actions require explicit user consent.
+
+## When to use this capability
+
+- Package a Maestro BPMN Process Orchestration project.
+- Upload a project to Studio Web.
+- Publish or deploy a packaged process when explicitly requested.
+- Debug or run a process instance after explicit consent.
+- Inspect jobs, processes, process versions, instances, variables, incidents, and traces.
+- Pause, resume, cancel, retry, migrate, or move a running instance when explicitly requested.
+- Refresh or regenerate CLI-owned package metadata before a cloud action.
+
+## Critical rules
+
+1. **Never debug or run without explicit consent** - execution can call connectors, start child processes, create Action
+   Center work, mutate queues, send messages, or update external systems.
+2. **Ask before every cloud-side mutation** - upload, publish, deploy, debug, process run, pause, resume, cancel, retry,
+   migrate, and cursor movement require a clear user decision for that action.
+3. **Validate before operate** - do not upload, publish, debug, or run until Author validation is complete or the user
+   explicitly accepts known draft warnings.
+4. **Refresh or regenerate package metadata before cloud actions** - stale `bindings_v2.json`, `entry-points.json`,
+   `operate.json`, or `package-descriptor.json` can break import or runtime even when the BPMN source is correct.
+5. **Keep source and package ownership clear** - fix process structure, variables, mappings, events, and documented non-IS
+   extensions in `.bpmn`; rerun CLI generation/enrichment for generated package JSON and Integration Service metadata.
+6. **Default publish wording to Studio Web upload unless the user explicitly asks for Orchestrator deployment** - keep deploy semantics explicit.
+7. **Always include folder context on runtime commands that require it** - `process run` takes `<FOLDER_KEY>` and
+   `instance`/`incident get` commands require `--folder-key` or `-f`.
+8. **Report identifiers plainly** - summarize returned Studio Web URLs, package paths, solution IDs, process keys,
+   job keys, instance IDs, run IDs, final status, and folder context when available.
+9. **Do not retry before diagnosis** - identify root cause first, then decide whether retry, cancel, migrate,
+   cursor movement, or source repair is appropriate.
+
+## Workflow
+
+| Journey | Read |
+| --- | --- |
+| Package and upload or publish | [references/ship.md](references/ship.md) |
+| Debug/run and inspect execution | [references/run.md](references/run.md) |
+| Manage a running instance | [references/manage.md](references/manage.md) |
+
+## Common tasks
+
+| I need to... | Read these |
+| --- | --- |
+| Prepare for Studio Web upload | [references/ship.md](references/ship.md), [shared/project-layout.md](../shared/project-layout.md) |
+| Deploy to Orchestrator | [references/ship.md](references/ship.md) |
+| Run/debug a BPMN process | [references/run.md](references/run.md) |
+| Inspect job or instance status | [references/run.md](references/run.md) |
+| Pause/resume/cancel/retry | [references/manage.md](references/manage.md) |
+| Migrate or move an instance cursor | [references/manage.md](references/manage.md) |
+| Correlate a running instance to deployed BPMN | [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) |
+| Diagnose a failed run | [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) |
+
+## Anti-patterns
+
+- **Never treat package generation as source authoring** - generated files reflect BPMN plus enrichment.
+- **Never upload a draft with unresolved Integration Service enrichment unless the user explicitly wants a non-executable
+  draft review.**
+- **Never run lifecycle commands just to validate XML.**
+- **Never default to Orchestrator deploy when the user says "publish."** Use Studio Web upload unless the target is explicit.
+- **Never use `debug` as a substitute for validation.** Debug executes the process against real services.
+- **Never retry a faulted instance without checking incidents and deployed asset correlation.**
+
+## References
+
+### Operate-scoped
+
+- [ship.md](references/ship.md) - package, upload, publish, deploy
+- [run.md](references/run.md) - debug, run, status, traces
+- [manage.md](references/manage.md) - pause, resume, cancel, retry, migrate, cursor movement
+
+### Cross-capability
+
+- [shared/project-layout.md](../shared/project-layout.md) - package files and content
+- [shared/cli-conventions.md](../shared/cli-conventions.md) - side effects, login, JSON output
+- [author/validation.md](../author/references/validation.md) - pre-operate validation
+- [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) - failure investigation

package/skills/uipath-maestro-bpmn/references/operate/references/manage.md

@@ -0,0 +1,71 @@
+# Manage - Instance lifecycle
+
+Use this journey to intervene in a running or faulted BPMN process instance.
+Lifecycle actions are cloud-side mutations and require explicit user consent for the specific action.
+
+## Supported decisions
+
+- Pause.
+- Resume.
+- Cancel.
+- Retry after diagnosis.
+- Migrate version.
+- Move cursor/goto when the runtime supports it and the user explicitly requests it.
+
+## Pre-flight
+
+1. Confirm login:
+
+   ```bash
+   uip login status --output json
+   ```
+
+2. Resolve the target instance ID and folder key from debug output, process run output, job status, or instance listing.
+3. Confirm the target instance and folder/context with the user before acting.
+4. Explain the expected side effects of the lifecycle action.
+5. For retry, migrate, or cursor movement, diagnose the fault and correlate the deployed asset first.
+
+## Commands
+
+```bash
+uip maestro bpmn instance list --output json
+uip maestro bpmn instance get <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance pause <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance resume <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance cancel <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance retry <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance migrate <INSTANCE_ID> <NEW_VERSION> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance goto <INSTANCE_ID> '[{"sourceElementId":"A","targetElementId":"B"}]' -f <FOLDER_KEY> --output json
+```
+
+Use `goto` only when the user provides or approves explicit source and target BPMN element IDs.
+Prefer a JSON file or carefully quoted JSON for non-trivial transition sets.
+
+## Decision notes
+
+| Action | Use when |
+| --- | --- |
+| `pause` | The instance is running and the user needs to halt progress while preserving state. |
+| `resume` | The instance is paused and the user wants normal execution to continue. |
+| `cancel` | The instance should stop and not continue from current state. |
+| `retry` | Root cause is understood and retrying the same deployed definition is expected to succeed. |
+| `migrate` | The user explicitly chooses a different package version for an existing instance. |
+| `goto` | The user explicitly chooses cursor movement between known BPMN element IDs. |
+
+After every lifecycle command, fetch the instance again and report the resulting status:
+
+```bash
+uip maestro bpmn instance get <INSTANCE_ID> -f <FOLDER_KEY> --output json
+```
+
+## Handoff
+
+If the action reveals a modeling or binding problem, return to Author with the BPMN element ID, incident summary,
+and generated file mismatch if relevant.
+
+## Anti-patterns
+
+- **Never retry before diagnosis.** Fetch incidents, runtime variables, and the deployed BPMN asset first.
+- **Never migrate or move a cursor as a generic fix.** These actions change runtime state and need an explicit user decision.
+- **Never omit `--folder-key` or `-f` on instance commands.**
+- **Never paste private runtime variables, tenant URLs, folder keys, connection IDs, or payloads into public notes.**

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

@@ -0,0 +1,122 @@
+# Run - Debug, process run, and status inspection
+
+Use this journey to debug or run a BPMN Process Orchestration project and inspect execution status.
+Debug and deployed process runs are side-effecting operations.
+Status, incidents, variables, and deployed-asset reads are inspection operations.
+
+## Consent gate
+
+Before any debug or process run:
+
+- Explain that execution can call connectors, start child processes, create human tasks, mutate queues, send messages,
+  or update external systems.
+- Confirm input arguments and target folder/context.
+- Confirm the project has passed validation and required CLI-owned enrichment.
+- Ask for explicit consent for this run. Prior consent for upload, validation, or packaging is not consent to execute.
+
+## Debug - controlled Studio Web run
+
+Use debug when the user wants to upload a local BPMN project to Studio Web and run a debug session with full Studio Web
+visibility.
+
+For local project debug, prefer a solution context so generated resources,
+bindings, and debug metadata are available. Initialize a solution, import the
+BPMN project, refresh resources, and run debug from the solution directory:
+
+```bash
+uip solution init <SolutionName> --output json
+uip solution project import --source <ProjectDir> --solutionFile <SolutionName>/<SolutionName>.uipx --output json
+uip solution resource refresh --solution-folder <SolutionName> --output json
+cd <SolutionName> && uip maestro bpmn debug <ProjectDirName> --output json
+```
+
+```bash
+uip maestro bpmn debug [project-path] --output json
+```
+
+Pass input arguments only after confirming the values and redacting secrets from summaries:
+
+```bash
+uip maestro bpmn debug [project-path] --inputs @inputs.json --output json
+```
+
+If a target folder is needed, provide the folder ID exposed by the CLI:
+
+```bash
+uip maestro bpmn debug [project-path] --folder-id <FOLDER_ID> --output json
+```
+
+Parse and report returned identifiers such as `Data.jobKey`, `Data.instanceId`, `Data.runId`, `Data.solutionId`,
+and `Data.finalStatus`.
+If Studio Web URL is not returned, print `Studio Web URL: <not returned by CLI>`.
+
+## Process run - deployed process
+
+Use process run only for a process already deployed to Orchestrator.
+
+```bash
+uip maestro bpmn process list --output json
+uip maestro bpmn process get <PROCESS_KEY> <FEED_ID> --output json
+uip maestro bpmn process run <PROCESS_KEY> <FOLDER_KEY> --inputs @inputs.json --validate --output json
+```
+
+`process run` requires the folder key as a positional argument.
+Use `--release-key`, `--feed-id`, or `--robot-ids` only when the user provides those deployment-specific choices
+or the process discovery output clearly identifies them.
+
+## Job and instance inspection
+
+Use status first, then incidents and variables if the status is faulted or ambiguous:
+
+```bash
+uip maestro bpmn job status <JOB_KEY> --folder-key <FOLDER_KEY> --output json
+uip maestro bpmn instance get <INSTANCE_ID> -f <FOLDER_KEY> --output json
+uip maestro bpmn instance incidents <INSTANCE_ID> -f <FOLDER_KEY> --output json
+```
+
+Use traces only when status, incidents, variables, and deployed BPMN correlation are insufficient:
+
+```bash
+uip maestro bpmn job traces <JOB_KEY> --output json
+```
+
+For debug instances, prefer the `debug-instance` inspection commands when
+standard deployed-instance commands do not have debug-session context. Use the
+identifiers returned by the debug command as the source of truth.
+
+```bash
+uip maestro bpmn debug-instance incidents <INSTANCE_ID> --output json
+uip maestro bpmn debug-instance variables <INSTANCE_ID> --output json
+uip maestro bpmn debug-instance variables-all <INSTANCE_ID> --output json
+```
+
+## Execution summary
+
+When a run starts, report:
+
+- Studio Web URL, if returned.
+- Process key, job key, run ID, solution ID, or instance ID, if returned.
+- Folder/context, if known.
+- Input summary, with secrets redacted.
+- Final status if the command waited for completion.
+- Next inspection command or status path.
+
+When the user cares about a business result, final status alone is insufficient.
+Also report the relevant output variable or the reason it could not be
+inspected.
+
+## Status and traces
+
+Start with status and incidents before verbose traces.
+Traces can be large and should be pulled only when incidents and variables are insufficient.
+
+If execution faults, hand off to [diagnose/CAPABILITY.md](../../diagnose/CAPABILITY.md).
+
+## Anti-patterns
+
+- **Never run `uip maestro bpmn debug` as validation.** Use Author validation and packaging checks for correctness;
+  debug executes the process.
+- **Never reuse stale inputs silently.** Confirm every side-effecting run's input set and redact secrets from summaries.
+- **Never skip folder context for deployed runs.** `process run` requires `<FOLDER_KEY>` and instance inspection commands
+  require `--folder-key` or `-f`.
+- **Never start diagnosis from traces.** Use incidents, variables, deployed BPMN asset, and element executions first.