@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-aops/references/migration-guide.md

@@ -0,0 +1,146 @@
+# Migration — `uip sc` + `uip cicd` → `uip aops`  <!-- uip-check-skip -->
+
+`@uipath/sc-tool` (prefix `sc`) and `@uipath/cicd-tool` (prefix `cicd`) were unified into a single plugin, `@uipath/aops-tool` (prefix `aops`). `@uipath/cicd-tool` no longer exists on npm.
+
+The merge kept every subcommand name. The rewrite is mechanical: replace the tool prefix, keep the rest.
+
+```bash
+uip sc   connection list --output json     →  uip aops connection list --output json  <!-- uip-check-skip -->
+uip cicd pipeline create --file p.json     →  uip aops pipeline create --file p.json  <!-- uip-check-skip -->
+```
+
+## Install
+
+```bash
+uip tools install @uipath/aops-tool
+uip tools list --output json
+```
+
+Confirm an entry with `"commandPrefix": "aops"`.
+
+Known failure modes:
+
+| Symptom | Cause | Action |
+|---|---|---|
+| `Unknown tool '@uipath/aops-tool'` | The installed CLI's registry index predates the tool | Update the CLI first (`uip update`), then retry the install. Report the CLI version (`uip --version`) to the user if it still fails. |
+| `Unsupported URL Type "workspace:"` when installing `@uipath/sc-tool` | The last published `sc-tool` is a stale build with unresolved workspace dependencies | Do not install `sc-tool`. It is retired — install `aops-tool`. |
+
+Do not fall back to `uip sc` / `uip cicd` when `aops` is unavailable. Report the install failure to the user instead.  <!-- uip-check-skip -->
+
+## Verb map
+
+Both old trees merged without collision — no verb was renamed, dropped, or moved to a different subject. Swap the prefix and keep everything to its right.
+
+| Subject | Old prefix | New prefix | Verbs under it |
+|---|---|---|---|
+| `connection` | `sc` | `aops` | `list`, `state`, `sync`, `delete`, `repos`, `repos-bulk`, `projects`, `solutions`, `azure-projects` | <!-- uip-check-skip -->
+| `repo` | `sc` | `aops` | `branches`, `project-files` | <!-- uip-check-skip -->
+| `project` | `sc` | `aops` | `list`, `get`, `files`, `content`, `commits`, `commit` | <!-- uip-check-skip -->
+| `solution` | `sc` | `aops` | `get`, `commits` | <!-- uip-check-skip -->
+| `pipeline` | `cicd` | `aops` | `list`, `state`, `processes`, `process`, `repos`, `get`, `search`, `create`, `update`, `delete`, `run`, `save-and-run`, `executions`, `executions-bulk` | <!-- uip-check-skip -->
+| `execution` | `cicd` | `aops` | `get`, `logs`, `details`, `stop` | <!-- uip-check-skip -->
+
+## Behavior changes beyond the rename
+
+These are the differences that break a command that used to work. Everything else — the `PipelineDto` / `EditPipelineDto` shapes, `repositoryId` = `RemoteId`, `projectName: ""`, `repositoryType: "git"`, the `PipelineRunMode` values — is unchanged.
+
+### 1. Stdout `Data` keys are PascalCase
+
+Every key inside the success envelope's `Data` is PascalCased on output: `identifier` → `Identifier`, `remoteId` → `RemoteId`, `syncState` → `SyncState`, `projectRelativePath` → `ProjectRelativePath`.
+
+Input files are NOT transformed. A `--file` payload must use the DTO's own camelCase names. Capturing stdout and feeding it back is the single most common failure — `pipeline update` rejects it outright (see § 4).
+
+To get a raw DTO on disk, use the command's `--output-file` flag, which writes the untransformed payload:
+
+```bash
+uip aops pipeline get <pipeline-id> --for-update --output-file ./edit.json --output json
+```
+
+### 2. `ConnectionType` is `Azure`, not `AzureDevOps`
+
+`connection list` → `Type` is `"GitHub"` or `"Azure"`. Match on `"Azure"` when branching on provider.
+
+### 3. `pipeline delete` requires explicit confirmation
+
+```bash
+uip aops pipeline delete <pipeline-id> --yes --output json
+```
+
+Without `-y` / `--yes` the command exits 1 with `Confirmation required: …` and sends no request. The CLI never prompts.
+
+### 4. `pipeline update --file` rejects unrecognized keys
+
+`update` is an HTTP PUT — a full replace. The serializer sends exactly five keys: `identifier`, `name`, `runMode`, `description`, `arguments`. Any other key in the file — including one that differs only in case, e.g. `Name` — is a `ValidationError` (exit 3) and nothing is sent. A file whose only key is `identifier` is rejected too ("carries no EditPipelineDto field to apply").
+
+This gate exists because such a request used to succeed while silently clearing every field it failed to carry.
+
+The supported round-trip:
+
+```bash
+uip aops pipeline get <pipeline-id> --for-update --output-file ./edit.json --output json
+# edit ./edit.json — name / runMode / description / arguments only
+uip aops pipeline update <pipeline-id> --file ./edit.json --output json
+```
+
+### 5. `--take` / `--skip` are deprecated, and absent on `pipeline executions`
+
+`connection projects`, `connection solutions`, and `project list` still accept `--take` / `--skip` as hidden aliases and emit a deprecation warning. `pipeline list` and `pipeline executions` never had them — they take `--limit` / `--offset` only.
+
+`--offset` must be an exact multiple of `--limit` on every paginated verb; otherwise the command fails client-side before any request.
+
+| Verb | Default `--limit` |
+|---|---|
+| `connection projects`, `project list` | 10 |
+| `connection solutions`, `pipeline list`, `pipeline executions` | 20 |
+| `execution logs` | 200 (log-line page size) |
+
+### 6. `--output-filter` requires an explicit `--limit`
+
+`--output-filter` runs client-side over only the records the command fetched. When a filter is active and `--limit` resolved from its declared default, the CLI refuses to run rather than filter a silently capped page. Pass `--limit` explicitly:
+
+```bash
+uip aops pipeline list --search "my-pipeline" --limit 50 --output json --output-filter "Data[].PipelineId"
+```
+
+Commands with no declared `--limit` default — `pipeline create`, `pipeline save-and-run`, `pipeline get` — are unaffected:
+
+```bash
+uip aops pipeline save-and-run --file ./pipeline.json --output json --output-filter "Data.ExecutionId"
+```
+
+### 7. `repo project-files` closes the standalone `projectPath` gap
+
+Previously the project file's path inside the repo had to be probed with `project content` or asked of the user. `repo project-files <repo-id>` now returns it directly:
+
+```bash
+uip aops repo project-files <REPOSITORY_SC_UUID> --output json
+```
+
+`Data[]` rows are `{Name, Path, Type, BuildableUnitType}`. `Path` is `PipelineDto.projectPath`. Takes the repository's SourceControl UUID (`Identifier` from `connection repos`), NOT `RemoteId`. `--reference <branch|tag|sha>` targets a non-default branch.
+
+### 8. `--follow` / `--wait` timeout defaults
+
+| Command | `--timeout` default | `--poll-interval` default |
+|---|---|---|
+| `execution logs --follow` | 1800000 (30 min) | 2000 |
+| `execution stop --wait` | 300000 (5 min) | 2000 |
+| `connection sync --wait` | 300000 (5 min) | 2000 |
+
+Units live in the placeholder (`<ms>`) — there is no `--timeout-ms` flag.
+
+### 9. `execution logs --follow` streams to stderr
+
+With `--follow`, log lines are written to stderr as they arrive (shaped by `--output`), leaving stdout for the final envelope carrying the terminal state and line count. The stream is not subject to `--log-level` and is not captured by `--log-file`. Redirect stderr to keep it: `2> build.log`.
+
+`--follow` requires the `<execution-id>` positional; `--job-key` alone is not enough because state polling is executionId-keyed.
+
+## Do not confuse with `uip gov aops-policy`
+
+Two unrelated product surfaces share the "AOps" name:
+
+| Surface | Prefix | What it does | Skill |
+|---|---|---|---|
+| StudioAdmin AOps | `uip aops` | SourceControl connections, repos, projects, solutions; CICD pipelines and executions | this skill |
+| AOps governance policies | `uip gov aops-policy` | Restrict / enforce Studio, StudioX, Assistant, Robot, AI Trust Layer features | `uipath-governance` |
+
+If the request is about restricting what a product *can do*, it is a governance policy, not a pipeline.

package/skills/uipath-aops/references/pipeline-dto-guide.md

@@ -0,0 +1,276 @@
+# PipelineDto Guide
+
+Field-by-field reference for the JSON shape `uip aops pipeline create --file` and `pipeline save-and-run --file` consume.
+
+> **Casing.** Keys in a `--file` payload are the DTO's own **camelCase** names. Keys in CLI stdout are **PascalCase**. Never capture stdout into a file and pass it back — see [migration-guide.md § 1](migration-guide.md#1-stdout-data-keys-are-pascalcase).
+
+## PipelineDto vs EditPipelineDto
+
+Two distinct shapes — do NOT mix them.
+
+| Shape | Consumed by | Includes |
+|---|---|---|
+| **PipelineDto** | `pipeline create --file`, `pipeline save-and-run --file`; returned by `pipeline get <id>` | Full binding: connection + repository + project + process + run config |
+| **EditPipelineDto** | `pipeline update <id> --file`; returned by `pipeline get <id> --for-update` | Subset — only the editable surface: `identifier`, `name`, `runMode`, `description`, `arguments` |
+
+`pipeline update` is a full-replace (HTTP PUT). The narrower EditPipelineDto means binding fields are immutable for the life of a pipeline. To change the project or branch binding, delete and recreate.
+
+## PipelineDto fields
+
+Only `branch` is required by the SDK type system. The other fields are optional in TypeScript but the API rejects pipelines omitting the binding fields below — fill them.
+
+| Field | Required for create | Type | Source — Solution path | Source — Standalone-project path |
+|---|---|---|---|---|
+| `identifier` | No (server-assigned) | string (UUID) | Omit on create | Omit |
+| `name` | Recommended | string | User-supplied. Defaults to `<source-kebab>-<process-kebab>` if not given | Same |
+| `runMode` | Recommended | `"Manually"` \| `"AtSpecificTime"` \| `"ForEachCommit"` | Default `"Manually"` | Same |
+| `description` | No | string \| null | User-supplied | Same |
+| `connectionIdentifier` | Yes | string (UUID) | `connection list` → chosen `Identifier` | Same |
+| `repositoryId` | Yes | string | `connection repos` row whose `Identifier` matches `solution.Repository.Identifier` → **`RemoteId`** | `connection repos` row whose `Name` matches the project's `Repository` field → **`RemoteId`** |
+| `repositoryUrl` | Yes | string | `solution.Repository.CloneUrl` | Matched repo's `CloneUrl` |
+| `repositoryName` | Yes | string | `solution.Repository.Name` | Matched repo's `Name` |
+| `repositoryType` | Yes | string | `"git"` (server-normalized) | `"git"` |
+| `branch` | **Yes (hard-required)** | string | `solution.Repository.DefaultBranch` | Matched repo's `DefaultBranch` |
+| `projectName` | No | string | `""` (empty string — UI-created pipelines leave this blank) | `""` |
+| `projectPath` | Yes | string | `project.ProjectRelativePath` exactly | `repo project-files` row's `Path` |
+| `processIdentifier` | Yes | string (UUID) | `pipeline processes` → user-picked `ProcessId` | Same |
+| `arguments` | No | any \| null | Runtime overrides. Default `null`. See § arguments | Same |
+| `latestPipelineExecution` | Never on create | object | Server-populated read-only. Omit | Omit |
+
+## Field sourcing
+
+The discovery flow ([discovery-flow.md](discovery-flow.md)) returns every value listed above. Composition rules follow.
+
+### `name`
+
+The pipeline name shown in the StudioAdmin UI. Constraints:
+
+- Must be unique within the runtime environment — `pipeline create` returns a conflict error on duplicates
+- No format restriction beyond non-empty
+
+Default pattern when the user doesn't supply one: `<source-kebab>-<process-kebab>`. Verify uniqueness via:
+
+```bash
+uip aops pipeline list --search "<candidate>" --output json
+```
+
+Empty `Data: []` means the name is free. Prefer `pipeline list --search` over `pipeline search --name`: `search --name` exits 1 with `Pipeline '<name>' not found.` when nothing matches, which is awkward to distinguish from a real failure.
+
+### `runMode`
+
+| Value | When to use |
+|---|---|
+| `"Manually"` | Default. Pipeline only runs on explicit `pipeline run <id>` or `save-and-run`. Best for a first-create flow. |
+| `"AtSpecificTime"` | Pipeline runs on a server-side schedule. The schedule config itself is set in the StudioAdmin UI after creation — the CLI cannot author it. |
+| `"ForEachCommit"` | Pipeline runs on every commit to `branch`. Wire only when the user explicitly asks for continuous-build behavior. |
+
+### `branch`
+
+The branch the pipeline checks out for every run. The only hard-required field in the DTO.
+
+1. **User named a branch** → use it verbatim. Optionally verify via `uip aops repo branches <REPOSITORY_SC_UUID> --output json` (that verb takes the SourceControl UUID, not `RemoteId`).
+2. **No user input** → use the repository's `DefaultBranch`. Never assume `"main"` / `"master"`.
+
+### `repositoryType`
+
+The server normalizes this to `"git"` regardless of provider. Always send `"git"`. Sending `"GitHub"` / `"Azure"` is accepted but the round-trip returns `"git"`.
+
+### `repositoryId` — provider-native id, not SourceControl UUID
+
+The most common trap. The `RepositoryDto` carries two ids:
+
+| Field | What it is | Use for |
+|---|---|---|
+| `Identifier` | SourceControl service's internal UUID for the repo | `repo branches`, `repo project-files`, `pipeline list --repository-ids` |
+| `RemoteId` | The provider's native repo id — numeric for GitHub, UUID for Azure DevOps | **`PipelineDto.repositoryId`** |
+
+Sending `Identifier` makes `pipeline create` return `Success`, but the resulting pipeline can't resolve the repository at runtime. The StudioAdmin UI flags it "connection no longer valid" — misleading, since the connection is fine and only the repo binding is wrong. Always send `RemoteId`.
+
+Note the asymmetry: the DTO wants `RemoteId`, while every other CLI verb that addresses a repository wants `Identifier`.
+
+### `projectName`
+
+UI-created pipelines store `""` here. The binding resolves on `repositoryId` + `projectPath` + `branch`; `projectName` is metadata-only. Default to `""`.
+
+### `projectPath`
+
+The path of the project file (`project.json` / `project.uiproj`) within the repository, forward-slash separated.
+
+**Solution path:** `project.ProjectRelativePath` exactly. Example: `<project-dir>/project.json`.
+
+**Standalone-project path:** `repo project-files <REPOSITORY_SC_UUID>` → the matching row's `Path`. When several rows come back, disambiguate against the project the user named; ask if still ambiguous.
+
+Do NOT derive `projectName` from the last segment of `projectPath` — that segment is the project file, not the project.
+
+### `processIdentifier`
+
+The `ProcessId` of the already-published Orchestrator process the pipeline runs / updates. Picked **independently** of the source project — see [discovery-flow.md § Step 6](discovery-flow.md#step-6--pick-the-already-published-orchestrator-process).
+
+Source (project) and target (process) are decoupled. The pipeline builds whatever source the project carries and then operates on the bound process; the project does NOT need to be the one that originally published the process. Do not auto-derive — let the user pick, or confirm an inference.
+
+### `arguments`
+
+Override values the pipeline passes to the automation process when it runs. The schema is process-specific — every published process declares its own parameter set. Four related surfaces — do NOT conflate:
+
+| Field | Type | Where | What it carries |
+|---|---|---|---|
+| `Data.Arguments` | object | response from `pipeline process <process-id>` | Declared **input parameter schema** — names, types, defaults. Read-only metadata. |
+| `Data.InputArguments` | JSON string | same response | Orchestrator-style serialized **default values**. Parse with `JSON.parse`. |
+| `PipelineDto.arguments` | `any \| null` | **what you write** on create | **Override values** the pipeline passes at run time. `null` = use process defaults. |
+| `Data.InputArguments` | object | `execution get <id> --with-arguments` | **Actual runtime values** the execution ran with. The CLI parses the string into an object. Use to verify what the pipeline submitted. |
+
+#### Workflow — inspect, infer, ask
+
+1. **Inspect the schema:**
+
+   ```bash
+   uip aops pipeline process <PROCESS_ID> --output json
+   ```
+
+   Read `Data.Arguments` for the declared parameter list and parse `Data.InputArguments` for default values:
+
+   ```javascript
+   const defaults = JSON.parse(response.Data.InputArguments ?? "{}");
+   ```
+
+2. **For each declared parameter**, decide what value to use:
+
+   | Situation | Action |
+   |---|---|
+   | Conversation context implies a value (user named a file, date, count) | Record the inferred value as an override |
+   | No inference, but the parameter has a default in `InputArguments` | Skip — omit from the override object; the default fires at runtime |
+   | No inference, no default, parameter is required | Ask the user. Choice-style prompt for enum / boolean values; free-form for text / numbers / paths |
+   | No inference, no default, parameter is optional | Omit |
+
+3. **Build the override object** — Orchestrator-style key/value, only the parameters to change:
+
+   ```json
+   {
+     "BatchDate": "2026-05",
+     "DryRun": false
+   }
+   ```
+
+   Empty object `{}` and `null` both mean "use all defaults" — prefer `null` for readability.
+
+4. **Verify after the first run:**
+
+   ```bash
+   uip aops execution get <EXECUTION_ID> --with-arguments --output json
+   ```
+
+   `Data.InputArguments` shows what the pipeline actually submitted. If it diverges from the override set, the wire-shape caveat below applies.
+
+#### Inference examples
+
+| User says | Inferred override |
+|---|---|
+| "Create a pipeline that processes the May 2026 invoice batch" | `BatchDate: "2026-05"` (if `BatchDate` is declared) |
+| "Set it to dry-run mode for now" | `DryRun: true` (if `DryRun` is declared) |
+| "Use the file at /data/inputs/april.csv" | `InputFile: "/data/inputs/april.csv"` (if a path-like parameter is declared) |
+| Nothing about parameters mentioned | `arguments: null` — defaults apply |
+
+If a piece of conversation context could match multiple declared parameters, ask the user rather than guessing.
+
+#### Asking the user — phrasing
+
+For free-form values, ask in a regular chat reply, naming the parameter, its declared type, and the schema default if any:
+
+> "The `<my-process>` process declares an `InputFolder` parameter (type `String`, no default). What folder path should the pipeline use?"
+
+For choice-like values, present the declared enum options (or `true` / `false` for boolean parameters) and ask the user to pick.
+
+#### Wire-shape caveat
+
+The SDK types `PipelineDto.arguments` as `any`. The Orchestrator-style key/value shape is the conservative interpretation derived from how `execution get --with-arguments` parses runtime arguments. Some processes may expect a richer envelope (typed argument descriptors, qualified names). When `pipeline process <id>` surfaces a schema in `Arguments`, match that shape exactly. If `pipeline create` rejects the DTO with a parameter-shape error, re-fetch the process detail and align.
+
+After the first successful run, `execution get --with-arguments` is ground truth for what the pipeline submitted — treat any divergence as a defect in the override composition, not in the API.
+
+## Minimum useful PipelineDto
+
+```json
+{
+  "name": "<my-pipeline>",
+  "runMode": "Manually",
+  "description": null,
+  "connectionIdentifier": "<CONNECTION_ID>",
+  "repositoryId": "<REPOSITORY_REMOTE_ID>",
+  "repositoryUrl": "https://github.com/<my-org>/<my-repo>.git",
+  "repositoryName": "<my-repo>",
+  "repositoryType": "git",
+  "branch": "main",
+  "projectName": "",
+  "projectPath": "<project-dir>/project.json",
+  "processIdentifier": "<PROCESS_ID>",
+  "arguments": null
+}
+```
+
+Write to disk at e.g. `./pipeline-<my-pipeline>.json`, then:
+
+```bash
+uip aops pipeline create --file ./pipeline-<my-pipeline>.json --output json
+```
+
+Success returns:
+
+```json
+{
+  "Result": "Success",
+  "Code": "PipelineCreated",
+  "Data": { "Identifier": "<new-pipeline-id>", "Name": "<my-pipeline>", "Branch": "main" }
+}
+```
+
+`Data` is the full persisted PipelineDto. Capture `Data.Identifier`.
+
+Optional: `--telemetry-flow-id <id>` adds a server-side correlation id as a query parameter. Only pass it when the user supplies one.
+
+## Common create-time errors
+
+`--file` is read and parsed before any API client is built, so file errors surface without credentials and without a request.
+
+| Error | Cause | Fix |
+|---|---|---|
+| `File not found: <path>` | Wrong path passed to `--file` | Verify the file was actually written before invoking create |
+| `File '<path>' does not contain a JSON object.` | The file holds `null`, a number, a string, or an array | Write a single JSON object |
+| `required option '--file <path>' not specified` (exit 3) | Flag omitted | `create` and `save-and-run` both require `--file` |
+| `"already exists"` / 409 conflict | Pipeline name clashes within the runtime environment | Rename in the JSON file, retry |
+| `"branch '<x>' not found"` | The branch doesn't exist on the mirrored repository | Re-sync the connection, or use `DefaultBranch` |
+| `"process not found"` / 404 on process | Stale `processIdentifier` | Re-run `pipeline processes` — the process may have been removed |
+| `"repository … not found"` | Stale `repositoryId`, or `Identifier` sent where `RemoteId` was needed | Re-run `connection repos` and take `RemoteId` |
+| `Pipelines.Edit` permission error | Current user lacks `Pipelines.Edit` on the active runtime environment | Switch runtime environment via the StudioAdmin UI |
+
+## Round-trip editing an existing pipeline
+
+To modify a pipeline after create, use the EditPipelineDto round-trip — NOT a new `create`:
+
+```bash
+# 1. Fetch the editable shape as a raw camelCase DTO on disk
+uip aops pipeline get <pipeline-id> --for-update --output-file ./pipeline-edit.json --output json
+
+# 2. Edit ./pipeline-edit.json — name / runMode / description / arguments only
+
+# 3. Re-apply
+uip aops pipeline update <pipeline-id> --file ./pipeline-edit.json --output json
+```
+
+`--output-file` is what makes this work: it writes the untransformed DTO, while stdout is PascalCased. Capturing stdout instead produces a file `update` rejects.
+
+Rules `update` enforces:
+
+| Rule | Failure |
+|---|---|
+| Every key in the file must be one of `identifier`, `name`, `runMode`, `description`, `arguments` | `ValidationError`, exit 3, nothing sent. The message names the offending keys and flags case-only mismatches |
+| At least one editable field must be present | `ValidationError`, exit 3 — `carries no EditPipelineDto field to apply` |
+| The file's `identifier`, if set, must match the positional id | `Failure`, exit 1 — `Mismatch: --file declares pipeline '<x>' but the positional id is '<y>'` |
+
+Success returns `Code: "PipelineUpdated"` with `Data.Pipeline` — the serialized **request**, not the parsed file, so the envelope can only show what was actually sent.
+
+Binding fields (`connectionIdentifier`, `repositoryId`, `branch`, `projectName`, `projectPath`, `processIdentifier`) are NOT editable. To change them, delete and recreate:
+
+```bash
+uip aops pipeline delete <pipeline-id> --yes --output json
+```
+
+`--yes` is mandatory — the CLI never prompts. Confirm with the user first. Deletion is permanent and does not auto-stop in-flight executions.

package/skills/uipath-aops/references/save-and-run-guide.md

@@ -0,0 +1,156 @@
+# Save-and-Run Guide
+
+`uip aops pipeline save-and-run --file` persists a new pipeline AND immediately queues its first execution. One round-trip; returns the persisted pipeline plus the first execution's id.
+
+## When to use which verb
+
+| Goal | Verb |
+|---|---|
+| Author the pipeline now, run it later | `pipeline create --file` |
+| Author + smoke-run in one step (typical first-time flow) | `pipeline save-and-run --file` |
+| Re-run an existing pipeline | `pipeline run <pipeline-id>` (no file needed) |
+
+Both `create` and `save-and-run` need `Pipelines.Edit`; `save-and-run` and `run` additionally need `Pipelines.Run` on the active runtime environment.
+
+## Invocation
+
+The file is the same `PipelineDto` shape `pipeline create` consumes — camelCase keys. See [pipeline-dto-guide.md](pipeline-dto-guide.md).
+
+```bash
+uip aops pipeline save-and-run --file ./pipeline-<name-kebab>.json --output json
+```
+
+Success envelope:
+
+```json
+{
+  "Result": "Success",
+  "Code": "PipelineSavedAndRunStarted",
+  "Data": {
+    "Pipeline": { "Identifier": "<new-pipeline-id>", "Name": "…", "Branch": "main" },
+    "ExecutionId": "<execution-id-or-null>"
+  }
+}
+```
+
+Capture both:
+
+- `Data.Pipeline.Identifier` → future `pipeline run` / `update` / `delete` calls
+- `Data.ExecutionId` → `execution logs --follow` to watch
+
+Optional: `--telemetry-flow-id <id>` rides the URL as a correlation query parameter; the body is unchanged. Only pass it when the user supplies one.
+
+## Runs are asynchronous
+
+The service answers `202` with no body. Neither `run` nor `save-and-run` tells you whether the build succeeded — only that it was queued. `run` echoes back just the pipeline id (`Code: "PipelineRunStarted"`, `Data: {PipelineId}`); `save-and-run` additionally lifts the queued execution's id out of the persisted DTO's `latestPipelineExecution` so the caller can chain straight into `execution logs` without re-listing.
+
+Tracking a run to completion is `execution logs --follow`'s job.
+
+## Handling `ExecutionId: null`
+
+When `ExecutionId` is `null`, the run was queued server-side but the response didn't carry the execution row.
+
+Recovery:
+
+```bash
+uip aops pipeline executions <new-pipeline-id> --limit 1 --output json
+```
+
+Returns `Data[0].ExecutionId` for the freshly-queued run. Note `pipeline executions` takes `--limit` / `--offset` only — `--take` does not exist on this verb.
+
+## Follow the execution to terminal state
+
+```bash
+uip aops execution logs <execution-id> --follow --output json
+```
+
+`--follow` polls until the execution reaches a terminal state (`Successful`, `Faulted`, `Stopped`), then emits a final summary envelope on stdout carrying the terminal state and line count.
+
+Output routing with `--follow`:
+
+- Log lines stream to **stderr** as they arrive, shaped by `--output` (one `Message` object per line under `--output json`).
+- stdout carries only the final envelope.
+- The stream is command output, not a diagnostic — it ignores `--log-level` and is not captured by `--log-file`. Redirect stderr to keep it: `2> build.log`.
+
+Flags:
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--limit <n>` | 200 | Page size for each log fetch |
+| `--poll-interval <ms>` | 2000 | Interval between polls when `--follow` is set |
+| `--timeout <ms>` | 1800000 (30 min) | Maximum time to follow before giving up |
+| `--job-key <key>` | — | Use a JobKey directly, skipping the executionId lookup |
+
+`--follow` requires the `<execution-id>` positional — state polling is executionId-keyed, so `--job-key` alone is rejected. Without `--follow`, the verb drains the current log slice and exits, and `--job-key` alone is enough.
+
+Units always live in the placeholder (`<ms>`) — there is no `--timeout-ms` flag.
+
+## Inspect a single execution
+
+```bash
+uip aops execution get <execution-id> --output json
+```
+
+Returns the `PipelineExecutionDto` — state, run mode, `JobExecutionIdentifier`, commit info, timing. Reuse `JobExecutionIdentifier` as `--job-key` for `logs` / `details` / `stop` to skip the auto-lookup.
+
+```bash
+uip aops execution get <execution-id> --with-arguments --output json
+```
+
+`--with-arguments` does one extra round-trip and merges the parsed runtime input arguments into `Data.InputArguments`. Edge cases, none of which fail the verb:
+
+- Runner hasn't picked up the job yet → `InputArguments: null` + a warning
+- Job-details API throws → `InputArguments: null` + a warning
+- The stored value is malformed JSON → falls back to the raw string, no warning
+
+## Stop a running execution
+
+```bash
+uip aops execution stop <execution-id> --wait --output json
+```
+
+Idempotent — stopping an already-terminal execution returns the current state without erroring. `--wait` polls until the execution settles to terminal and reports the final state in `Data`. Defaults: `--poll-interval` 2000, `--timeout` 300000 (5 min). Without `--wait`, the verb returns as soon as the stop is queued.
+
+## Not-found detection
+
+`execution get` / `logs` / `details` / `stop` all surface `Execution <id> not found.` with actionable Instructions when the execution id is bogus — the CLI checks the response body rather than trusting a `200`. Re-list with `pipeline executions <pipeline-id>` rather than retrying.
+
+## Full save-and-run + follow chain
+
+```bash
+# 1. Save and run, capture the ids
+RESULT=$(uip aops pipeline save-and-run --file ./pipeline.json --output json)
+PIPELINE_ID=$(echo "$RESULT" | python3 -c "import json,sys;print(json.load(sys.stdin)['Data']['Pipeline']['Identifier'])")
+EXECUTION_ID=$(echo "$RESULT" | python3 -c "import json,sys;d=json.load(sys.stdin)['Data']['ExecutionId'];print(d if d else '')")
+
+# 2. Fall back if ExecutionId was null
+if [ -z "$EXECUTION_ID" ]; then
+  EXECUTION_ID=$(uip aops pipeline executions "$PIPELINE_ID" --limit 1 --output json \
+    | python3 -c "import json,sys;print(json.load(sys.stdin)['Data'][0]['ExecutionId'])")
+fi
+
+# 3. Follow to terminal state, keeping the streamed lines
+uip aops execution logs "$EXECUTION_ID" --follow --output json 2> build.log
+```
+
+`--output-filter` is a lighter alternative when only one field is needed — and `save-and-run` has no defaulted `--limit`, so no explicit `--limit` is required:
+
+```bash
+uip aops pipeline save-and-run --file ./pipeline.json --output json --output-filter "Data.ExecutionId"
+```
+
+The same shortcut on `pipeline executions` DOES need an explicit `--limit`, because that verb's `--limit` has a declared default:
+
+```bash
+uip aops pipeline executions "$PIPELINE_ID" --limit 1 --output json --output-filter "Data[0].ExecutionId"
+```
+
+## Stop conditions
+
+| Command | `--poll-interval` default | `--timeout` default |
+|---|---|---|
+| `execution logs --follow` | 2000 | 1800000 (30 min) |
+| `execution stop --wait` | 2000 | 300000 (5 min) |
+| `connection sync --wait` | 2000 | 300000 (5 min) |
+
+When a follow times out, report the last known state to the user and hand them the `execution get <id>` command — do not silently re-follow.