@uipath/skills 1.204.0 → 1.204.1

package/skills/uipath-maestro-flow/references/shared/cli-commands.md

@@ -0,0 +1,269 @@
+# uip maestro flow — CLI Command Reference
+
+All commands output `{ "Result": "Success"|"Failure", "Code": "...", "Data": { ... } }`. Use `--output json` for programmatic use.
+
+> For node and edge commands (`node add/remove/list/configure`, `edge add/remove/list`), see the [Author CLI editing strategy](../author/editing-operations-cli.md). This file covers project setup, validation, registry, debug, and publishing commands.
+
+## uip maestro flow init
+
+Scaffold a new Flow project directory. Prefer creating the solution first so its name matches the project name (see the [Author greenfield journey — Step 2](../author/greenfield.md)):
+
+```bash
+uip solution init "<SolutionName>" --output json
+cd <directory>/<SolutionName> && uip maestro flow init <ProjectName> --output json
+```
+
+Add `--automate` to create a Maestro Automate project instead of a Flow. Nothing else changes — same scaffold, same authoring, same `pack` / `publish` / `debug` / `eval`; the flag writes `runtimeOptions.profile` into the packaged `operate.json` and a `.maestro_automate` marker into the project root.
+
+Confirm `Data.SolutionRegistration.Status`: `Registered`, `AlreadyRegistered`, `OptedOut`, `Skipped`, `Failed`, or `NotInSolution`. Inside a solution, `flow init` auto-registers the project with the parent `.uipx`. Outside one, it creates `<ProjectName>Solution/<ProjectName>Solution.uipx`, nests the project, and adds `Data.AutoCreatedSolution`. `--skip-solution-registration` opts out with status `OptedOut`; do not manually wire an intentionally opted-out project. Manually wire `Skipped`, `Failed`, or the rare `NotInSolution`:
+
+```bash
+uip solution projects add \
+  <directory>/<SolutionName>/<ProjectName> \
+  <directory>/<SolutionName>/<SolutionName>.uipx
+```
+
+Creates `<ProjectName>/` with `project.uiproj`, `<ProjectName>.flow`, `bindings_v2.json`, `entry-points.json`, `operate.json`, and `package-descriptor.json` inside the solution directory.
+
+## uip maestro flow validate
+
+Validate a `.flow` file locally—no auth or network. Run:
+
+```bash
+uip maestro flow validate <path/to/file.flow>
+uip maestro flow validate <path/to/file.flow> --output json
+uip maestro flow validate <path/to/file.flow> --verbose --output json
+uip maestro flow validate <path/to/file.flow> --governance --output json
+```
+
+Checks JSON parsing; required fields, including `targetPort` on edges; matching `type:typeVersion` entries in `definitions`; existing node `id` references for `sourceNodeId`/`targetNodeId`; and unique node and edge `id`s. Exit code 0 = valid, 1 = invalid.
+
+`--governance` checks agent nodes against organization policies fetched from the platform and requires `uip login`. If governance data cannot be fetched, the command fails. Omit it for local-only schema validation.
+
+## uip maestro flow format
+
+Run `uip maestro flow format` after validation and before publishing or debugging; stale or hand-written `layout` data can render as misshapen rectangles in Studio Web.
+
+```bash
+uip maestro flow format <path/to/file.flow>
+uip maestro flow format <path/to/file.flow> --output json
+```
+
+Format only layout: arrange nodes horizontally left-to-right while anchoring to the leftmost node's original position; set `size` to canvas shape (`shape: rectangle` inline agents: `{ "width": 288, "height": 96 }`; loops/groups: `{ "width": 560, "height": 320 }`; everything else, including referenced `uipath.core.agent.<guid>`: `{ "width": 96, "height": 96 }`); preserve sticky-note custom sizes; recurse into subflows and rewrite `subflows[<id>].layout`; and backfill missing `position`/`size`. Do not modify node logic, edges, definitions, or variables. JSON output reports `Data.NodesTotal`, `Data.EdgesTotal`, `Data.NodesRepositioned`, `Data.NodesResized`, and `Data.SubflowsTidied`.
+
+## uip maestro flow pack
+
+Pack a Flow project into a `.nupkg` for Orchestrator deployment:
+
+```bash
+uip maestro flow pack <project-path> <OutputDir>
+uip maestro flow pack <project-path> <OutputDir> --version 2.0.0
+uip maestro flow pack <project-path> <OutputDir> --output json
+```
+
+Require `content/package-descriptor.json` and `content/operate.json`. Output is `<Name>.flow.Flow.<version>.nupkg`.
+
+> **Note:** `pack` + `uip solution publish` deploys directly to Orchestrator — the user cannot visualize or edit the flow in Studio Web via this path. Only use this when the user explicitly asks to deploy to Orchestrator. The default publish path is `uip solution upload` (see below). See [uipath-solution](/uipath:uipath-solution) for `solution publish` commands.
+
+## uip solution resources refresh
+
+Always run `uip solution resources refresh` before `uip solution upload` or `uip maestro flow debug`. It re-scans solution projects and syncs resource declarations (connections, processes, queues, etc.) from `bindings_v2.json`, creating bindings not yet in the solution and importing matching Orchestrator resources.
+
+```bash
+uip solution resources refresh --solution-folder <SolutionDir> --output json
+```
+
+`<SolutionDir>` is the solution directory containing the `.uipx` file. The command has no positional solution argument; omit `--solution-folder` only from the solution root.
+
+## uip solution resources add / remove / edit
+
+Use atomic mutations when adding, deleting, or changing one resource without scanning every project's bindings:
+
+```bash
+uip solution resources add --source local --kind <Kind> --name <Name> --output json
+uip solution resources add --source remote --kind <Kind> --name <Name> --folder-path <FolderPath> --output json
+uip solution resources remove <KEY> --output json
+uip solution resources edit <KEY> --patch '{"maxNumberOfRetries":5}' --output json
+echo '{"slaInHours":"4"}' | uip solution resources edit <KEY> --patch - --output json
+```
+
+`add` is idempotent on `(kind, name, folder)` for local resources and on resource key for remote resources; retries return `Status: "Unchanged"`. `edit` alone mutates an existing resource spec; `refresh` never overwrites and skips resources already in the solution. When the change you want was made **in the cloud** after the import, `edit --source remote --force` pulls it in (without `--force` it only reports the drift). These commands do not modify `bindings_v2.json`; a later `refresh` re-imports a still-bound resource. See [uipath-solution Step 9–11](/uipath:uipath-solution).
+
+## uip solution upload
+
+Upload a solution directly to Studio Web; require `uip login`:
+
+```bash
+uip solution upload <SolutionDir> --output json
+```
+
+Pass the solution directory containing the `.uipx` file, or `.` from its root. From a nested project, pass the absolute solution root or `..`; do not pass the solution name again. This uploads to Studio Web for browser visualization, inspection, editing, and publishing.
+
+> **This is the default publish path.** When the user asks to "publish" without specifying where, run `uip solution upload <SolutionDir>` and share the resulting URL.
+
+## uip maestro flow debug
+
+Debug in the cloud through Studio Web + Orchestrator; require `uip login`. Always run `uip maestro flow validate` first, and run `uip solution resources refresh` before debugging:
+
+```bash
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json \
+  --inputs '{"numberA": 5, "numberB": 7}'
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json \
+  --attachment <variableId>=<localPath> \
+  --attachment <variableId>=<localPath>
+```
+
+Pass the project directory containing `project.uiproj` (`<ProjectName>/` from the solution root, or `.` inside it). Use `--inputs` for a JSON object of flow input arguments. Repeat `--attachment <variableId>=<localPath>` to upload files for file-typed inputs; a bare path is rejected.
+
+<a id="attachment-preflight"></a>
+
+#### Pre-flight: `--attachment` binding
+
+The CLI does not validate `<variableId>`; a mismatch can fault at runtime. Read `<flow>.flow`, inspect `variables.globals[]`, and use only entries with `direction:"in"` and `type:"file"`. If none exist, add `{ "id": "<variableId>", "direction": "in", "type": "file", "triggerNodeId": "<triggerId>" }`. In a Script node, read the uploaded name as `$vars.{triggerNodeId}.output.{id}.FullName`. See [variables-and-expressions.md — Runtime shape of a `file` variable](variables-and-expressions.md#file-input).
+
+Run `uip maestro flow debug --help` for other options.
+
+### Reporting the run back to the user
+
+Parse the Studio Web URL and `instanceId` from JSON output, typically `Data.studioWebUrl` and `Data.instanceId`, and report them as the first two lines:
+
+```text
+Studio Web URL: <url>
+Instance ID: <instanceId>
+
+<run status, node traces, errors, etc.>
+```
+
+If either is absent, output its label with `<not returned by CLI>`. Do not place these lines below the run summary.
+
+## uip maestro flow process
+
+Manage deployed Flow processes; require `uip login`:
+
+```bash
+uip maestro flow process list --output json
+uip maestro flow process run <process-key> <folder-key> --output json
+uip maestro flow process run <process-key> <folder-key> --output json \
+  --inputs '{"numberA": 5, "numberB": 7}'
+uip maestro flow process run <process-key> <folder-key> --output json \
+  --attachment <variableId>=<localPath>
+```
+
+`--attachment` must match a `variables.globals[]` entry with `direction:"in"` and `type:"file"`; repeat it for multiple files. If `--inputs` and `--attachment` collide, attachment wins and the CLI logs an override warning. `--validate` accepts pre-uploaded attachment references for file-typed slots although their nominal type is `string`. Run `uip maestro flow process --help` for other subcommands.
+
+## uip maestro flow job
+
+Monitor jobs; require `uip login`:
+
+```bash
+uip maestro flow job status <job-key> --output json
+uip maestro flow job traces <job-key> --output json
+```
+
+## uip maestro flow hitl add
+
+Add a Human-in-the-Loop QuickForm node to an existing `.flow`; the command writes node JSON, adds the definition once, and updates `variables.nodes`:
+
+```bash
+uip maestro flow hitl add <path/to/file.flow> --output json
+uip maestro flow hitl add <path/to/file.flow> --label "<label>" --priority High --output json
+uip maestro flow hitl add <path/to/file.flow> --assignee <email-or-group> --output json
+uip maestro flow hitl add <path/to/file.flow> --label "<label>" --priority High --assignee <email-or-group> \
+  --schema '{"inputs":[{"name":"invoiceId","binding":"fetchInvoice.output.invoiceId"}],"outputs":[{"name":"decision","required":true}],"outcomes":[{"name":"Approve"},{"name":"Reject"}]}' \
+  --position 474,144 --output json
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--label <text>` | Display label | `"Human in the Loop"` |
+| `--priority Low\|Medium\|High` | Action Center priority | `Low` |
+| `--assignee <email-or-group>` | User email (`staticEmail`) or group (`staticGroupName`) | group (unassigned) |
+| `--schema <json>` | Form fields and outcomes | empty form |
+| `--position <x,y>` | Canvas position | `0,0` |
+
+`--schema` supports:
+
+```json
+{
+  "inputs": [{ "name": "invoiceId", "binding": "fetchInvoice.output.invoiceId" }, { "name": "amount", "type": "number", "binding": "fetchInvoice.output.amount" }],
+  "outputs": [{ "name": "decision", "required": true }, { "name": "notes" }],
+  "inOuts": [{ "name": "emailBody" }],
+  "outcomes": [{ "name": "Approve" }, { "name": "Reject" }]
+}
+```
+
+`inputs` are read-only context fields and use the full `$vars` binding path; `outputs` are human-filled and default `variable` to the field name; `inOuts` are editable pre-filled fields; `outcomes` are button labels, with the first primary and later outcomes ending the flow unless rewired.
+
+Success output:
+
+```json
+{ "Result": "Success", "Code": "HitlNodeAdded", "Data": { "NodeId": "invoiceReview1", "NodeType": "uipath.human-in-the-loop.quick-form", "Label": "Invoice Review", "DefinitionAdded": true } }
+```
+
+After adding, wire one `outcome-<outcome.id>` port per outcome; any outcome left unwired blocks the flow on that branch. See the [Author HITL plugin reference](../author/plugins/hitl/impl.md).
+
+## uip maestro flow instance / uip maestro flow incident
+
+See the [Diagnose troubleshooting guide](../diagnose/troubleshooting-guide.md) for the diagnostic workflow and `instance`/`incident` command reference.
+
+## uip maestro flow node / uip maestro flow edge
+
+See the [Author CLI editing strategy](../author/editing-operations-cli.md) for `node add/remove/list/configure` and `edge add/remove/list` syntax, flags, and auto-managed behaviors.
+
+## uip maestro flow eval
+
+Evaluation surface: evaluator, eval-set, and data-point CRUD; Studio Web run start/status/results/list/compare. Local CRUD needs no login; `eval run *` requires `uip login` and a Flow solution already in Studio Web.
+**Never auto-run `uip solution upload` to satisfy the Studio Web prerequisite** — see [evaluate/upload-safety.md](../evaluate/upload-safety.md).
+
+```bash
+uip maestro flow eval add <name> --set <set> [flags] --output json
+uip maestro flow eval list --set <set> --path <flow_project> --output json
+uip maestro flow eval remove <id> --set <set> --path <flow_project> --output json
+uip maestro flow eval set add <name> [--evaluators <refs>] [--entry-point <id>] --path <flow_project> --output json
+uip maestro flow eval set list --path <flow_project> --output json
+uip maestro flow eval set remove <id> --path <flow_project> --output json
+uip maestro flow eval evaluator add <name> --type <type> [--model <m>] [--target-key <k>] [--prompt <p>] --path <flow_project> --output json
+uip maestro flow eval evaluator list --path <flow_project> --output json
+uip maestro flow eval evaluator remove <id> --path <flow_project> --output json
+uip maestro flow eval run start <name> --set <set> [--entry-point <e>] [--wait [--timeout <s>]] --path <flow_project> --output json
+uip maestro flow eval run status <run_id> --set <set> --path <flow_project> --output json
+uip maestro flow eval run results <run_id> --set <set> [--only-failed] [--verbose] [--export-format json|csv] --path <flow_project> --output json
+uip maestro flow eval run list --set <set> --path <flow_project> --output json
+uip maestro flow eval run compare <run_a> --compare-to <run_b> --set <set> --path <flow_project> --output json
+```
+
+Evaluators: `exact-match`, `json-similarity`, `contains`, `llm-judge-output`, `llm-judge-strict-json`, `llm-judge-trajectory`, `llm-judge-trajectory-simulation`. For full flag tables, evaluator details, eval-set JSON shape, and run-safety rule, see the [Evaluate capability](../evaluate/CAPABILITY.md).
+
+## uip maestro flow registry
+
+Manage the local node-type cache. No auth is required for OOTB nodes; login is required for tenant-specific connector nodes:
+
+```bash
+uip maestro flow registry pull
+uip maestro flow registry list --output json
+uip maestro flow registry search <keyword> --output json
+uip maestro flow registry get <node-type> --output json
+```
+
+The cache expires after 30 minutes. `registry search` returns a flat `Data` array with PascalCase fields. Use its `NodeType` with `registry get` and later `node add`.
+
+```json
+{ "Data": [{ "NodeType": "uipath.connector.uipath-salesforce-sfdc.list-records", "Category": "connector.196536", "DisplayName": "List Records", "Description": "(Salesforce) List records in Salesforce", "Version": "1.0.0", "Tags": "connector, activity", "AvailableOnTenant": true }] }
+```
+
+Treat `AvailableOnTenant` as a usability gate: `true` permits `registry get <NodeType>` or `node add <NodeType>`; `false` means the type is missing from the manifest this CLI pulled. Despite the name it is not a tenant entitlement — the CLI asks for a fixed set of node manifests decided by its own build, so `false` usually means this CLI does not carry the node rather than that an administrator withheld it.
+
+Do not use unsupported flags such as `--include-unavailable`, and do not loop on the upgrade: try `uip tools update` **once**, and if the type is still absent treat it as absent by design for this build — choose an available alternative, use `--local` for in-solution resources, or report it as unavailable. Around ten of the node families the manifest knows about are deliberately outside the set this CLI requests (`agent-memory`, `queue-operations`, `form-trigger`, `http-standalone`, `agent-tool-http-request`, `classify-document`, `do-while`, `hitl-document`, …), so no upgrade will ever surface them and each extra `tools update` + `registry pull` is wasted work.
+
+`registry get` returns `Data.Node` verbatim for the `.flow` `definitions` array. Preserve its manifest casing, predominantly camelCase (`nodeType`, `inputDefinition`, `supportsErrorHandling`, `form`); filter with `--output-filter "Node.inputDefinition"`, not `Node.InputDefinition`.
+
+Run `uip maestro flow registry <subcommand> --help` for additional options such as `--force`, `--filter`, and `--connection-id`.
+
+## Connector commands (binding and reference resolution)
+
+See the relevant guide in `nodes/` for connector CLI commands and configuration workflow.
+
+## Global options (all commands)
+
+All `uip` commands support `--output json|yaml|table` and `--help`. Run any command with `--help` to discover available options.

package/skills/uipath-maestro-flow/references/shared/cli-conventions.md

@@ -0,0 +1,178 @@
+# CLI Conventions
+
+Shared conventions for the `uip` CLI across Author, Operate, and Diagnose. Read this before invoking any `uip` command.
+
+## 1. Resolve `uip` and detect the command prefix
+
+Resolve the `uip` binary, which may be absent from PATH in nvm environments. If it is absent, stop and ask the user to run the official installer; do not auto-run an installer from this resolver.
+
+```bash
+UIP=$(command -v uip 2>/dev/null || true)
+if [ -z "$UIP" ] && command -v npm >/dev/null 2>&1; then
+  UIP="$(npm root -g 2>/dev/null | sed 's|/node_modules$||')/bin/uip"
+fi
+if [ -z "$UIP" ] || [ ! -x "$UIP" ]; then
+  echo "UiPath CLI not found. Ask the user to run the official installer, then rerun this step with PATH updated:" >&2
+  echo "  curl -fsSL https://download.uipath.com/uipath-cli/install.sh | bash" >&2
+  exit 2
+fi
+CURRENT=$($UIP --version 2>/dev/null | awk '{print $NF}')
+```
+
+If `uip` is not found, ask the user to run the official onboarding installer. It installs Node.js >= 20, `@uipath/cli`, UiPath skills for installed AI coding agents, .NET SDK 8.0, and Python 3.11-3.14.
+
+```bash
+curl -fsSL https://download.uipath.com/uipath-cli/install.sh | bash
+```
+
+On Windows PowerShell, run:
+
+```powershell
+irm https://download.uipath.com/uipath-cli/install.ps1 | iex
+```
+
+For CI or a minimal CLI setup, add `--skip-skills --skip-runtimes` on macOS/Linux or `-SkipSkills -SkipRuntimes` on Windows.
+
+Use `uip maestro flow` for CLI version **≥ 0.3.4** and `uip flow` for versions **< 0.3.4**: <!-- uip-check-skip -->
+
+| Installed version | Command prefix | Example |
+| --- | --- | --- |
+| **≥ 0.3.4** | `uip maestro flow` | `uip maestro flow init MyProject` |
+| **< 0.3.4** | `uip flow` | `uip flow init MyProject` <!-- uip-check-skip --> |
+
+
+```bash
+MIN_VERSION="0.3.4"
+if [ "$(printf '%s\n%s\n' "$MIN_VERSION" "$CURRENT" | sort -V | head -n1)" = "$MIN_VERSION" ]; then
+  FLOW_CMD="uip maestro flow"
+else
+  FLOW_CMD="uip flow" # <!-- uip-check-skip -->  legacy < 0.3.4 prefix
+fi
+echo "Using: $FLOW_CMD (CLI version $CURRENT)"
+```
+
+Run all commands below with `uip maestro flow ...`; if detection returns < 0.3.4, replace only that prefix with `uip flow`. Arguments and flags are identical. See UiPath/cli#841. <!-- uip-check-skip -->
+
+## 2. Use JSON output
+
+Run programmatically parsed commands with `--output json`:
+
+```bash
+uip maestro flow validate <ProjectName>.flow --output json
+uip maestro flow registry list --output json
+uip maestro flow instance incidents <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+Do not use `--format json`; it does not exist and produces `error: unknown option '--format'` with exit code 3 on every `uip` subcommand. Ignore the benign `--localstorage-file` warning when it appears.
+
+## 3. Prefer `--output-filter` for extraction
+
+Prefer `--output-filter '<jmespath>'` for field or projection extraction. It is a global flag on every subcommand, applies to the `Data` envelope before printing, and expressions start at `Data` (never `Data.`).
+
+Run broad discovery with:
+
+```bash
+uip maestro flow registry search slack --output json \
+  --output-filter "[*].{NodeType:NodeType,DisplayName:DisplayName,Description:Description,AvailableOnTenant:AvailableOnTenant}"
+```
+
+Run a narrowed connector query with:
+
+```bash
+uip maestro flow registry search slack --output json \
+  --output-filter "[?starts_with(NodeType,'uipath.connector.uipath-salesforce-slack.')].{NodeType:NodeType,DisplayName:DisplayName}"
+```
+
+Treat `registry search` as returning `Data` as a flat array of PascalCase objects: `NodeType`, `Category`, `DisplayName`, `Description`, `Version`, `Tags`, `AvailableOnTenant`. It does not return `Data.Nodes` or lowercase `type`/`category`.
+
+Do not use `head`, `tail`, `grep -m`, or a pager on discovery queries (`registry search`, `is connectors list`, or any `list`/`search`). Test existence with a predicate in `--output-filter` and return all matches:
+
+```bash
+uip … registry search slack --output json --output-filter "[?contains(NodeType,'get-channel-info')].NodeType"   # right: every match
+uip … registry search slack --output json --output-filter "[*].{…}" | head -100                                # wrong: hides matches past line 100
+```
+
+> **Exception — any command that fails.** The CLI applies `--output-filter` only on the success path; a `Result: "Failure"` envelope prints whole. This bites hardest on a faulted `flow debug` (200 KB and more) — redirect stdout to a file and extract from the file, see [diagnose/troubleshooting-guide.md — Step 0](../diagnose/troubleshooting-guide.md#step-0--read-the-cause-in-the-debug-output-you-already-have).
+
+Treat `Data: []` with exit 0 as a valid but mismatched expression, not proof of absence. Only invalid syntax or type errors fail with exit 3.
+
+Use `python3 -c` or `jq` only when JMESPath cannot perform a multi-step join across CLI calls, JSON-to-CSV or JSON-to-env-var conversion, or conditional output based on multiple fields. Verify the shape first:
+
+- Run `--output-filter "type(@)"`; it returns `"array"` or `"object"`.
+- For an object, run `--output-filter "keys(@)"`.
+- For an array, run `--output-filter "[0]"` or `--output-filter "[0] | keys(@)"`.
+- Do not run `keys(@)` directly on an array; it fails with `Filter 'keys(@)' failed to evaluate: Invalid type: keys() expected argument 1 to be of type (object) but received type array instead`.
+- If an expected value is `Data: []`, check field-name casing.
+
+`registry search` and `list` (and most `uip … --output json` commands) use PascalCase keys such as `[*].NodeType` and `[*].DisplayName`. `registry get` returns the node definition verbatim for pasting into `.flow`; its keys are predominantly camelCase: `Node.nodeType`, `Node.inputDefinition`, `Node.supportsErrorHandling`, and `Node.form.sections[…]`. Some nested runtime-output schemas are PascalCase, such as Summarize's `content.Text` and `content.Citations`. Match the manifest rather than assuming normalized casing. When uncertain, probe with `--output-filter "keys(@)"` for objects or `--output-filter "[0] | keys(@)"` for arrays.
+
+Verify the shape before parsing; most parsing retries result from an incorrect shape guess.
+
+### Cross-references
+
+Keep the broad-discovery recipe aligned with [author/plugins/connector/planning.md](../author/plugins/connector/planning.md) (§ Discovery) for connector discovery and [author/plugins/connector/impl.md](../author/plugins/connector/impl.md) for connection-resource lookup. Both files use the `--output-filter` preference and the `registry search` flat-array/PascalCase shape; each may use a task-specific projection.
+
+## 4. Check the JSON response shape
+
+Every `uip` command returns one of these shapes:
+
+```json
+{ "Result": "Success", "Code": "FlowValidate", "Data": { ... } }
+```
+
+```json
+{ "Result": "Failure", "Message": "...", "Instructions": "Found N error(s): ...", "Data": { ... } }
+```
+
+Always check `Result` first. On failure, use `Message` and `Instructions` for diagnostics. A failure envelope may still carry `Data` — `flow debug` returns the full run payload on a fault.
+
+## 5. Login state
+
+| Capability | Login required? |
+|---|---|
+| **Author** | No — `flow init`, `validate`, `format`, registry (OOTB nodes), `Edit` / `Write` edits, planning all work offline |
+| **Operate** | **Yes** — `solution upload`, `solution resources refresh`, `flow debug`, `flow pack`, `process run`, `job status`, `job traces` all require `uip login` |
+| **Diagnose** | **Yes** — `instance incidents`, `instance variables`, `instance asset`, `incident get`, `incident summary` all require `uip login` |
+
+Tenant-specific connector and resource nodes require login; without it, the registry shows OOTB nodes only. In-solution sibling projects are always available with `--local` without login.
+
+Check login by running:
+
+```bash
+uip login status --output json
+```
+
+Log in interactively by running:
+
+```bash
+uip login
+uip login --authority https://alpha.uipath.com    # non-production environments
+```
+
+## 6. `--folder-key` requirement
+
+Run all `uip maestro flow instance` and `uip maestro flow incident get` commands with `--folder-key <FOLDER_KEY>` (or `-f`). Without it, the request is rejected before reaching the API.
+
+Get the folder key by running:
+
+```bash
+uip or folders list --output json
+```
+
+Alternatively obtain it from job/process context, such as `Data.folderKey` in a job-status response or surrounding debug metadata.
+
+## 7. Use `UIP_LOG_LEVEL=info` for debug runs
+
+Run debug with `UIP_LOG_LEVEL=info`:
+
+```bash
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json
+```
+
+Capture stderr as well as stdout. At `info`, stderr reports the `jobKey`, `instanceId`, and Studio Web URL. If polling exceeds its budget, stdout may contain only `Debug polling timed out after <N>s`; stderr is then the only way to identify the instance and inspect it with `uip maestro flow debug-instance incidents <instanceId>`.
+
+Use `UIP_LOG_LEVEL`, not `UIPCLI_LOG_LEVEL`; the latter is silently ignored. `--log-level <level>` is the equivalent global flag. The setting applies to every `uip` command.
+
+## 8. Global options
+
+Run `uip maestro flow <subcommand> --help` to discover subcommand options. All `uip` commands support `--output json|yaml|table` and `--help`.