From b7f1784603fe33348b5c18ddb3a3d176ab5a4729 Mon Sep 17 00:00:00 2001 From: tmatup <51425734+tmatup@users.noreply.github.com> Date: Sun, 15 Nov 2026 08:54:36 -0800 Subject: [PATCH 1/4] docs(uipath-maestro-flow): move existing nodes from source .layout(); stale keys warn MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replayed onto the rebased #4724 (builder-sdk#2037), with the older-SDK fallback. 🤖 Generated with Claude Code Co-Authored-By: [Claude](mailto:noreply@anthropic.com) --- .../uipath-maestro-flow/references/brownfield.md | 4 ++++ skills/uipath-maestro-flow/references/brownfield.md | 12 ++++++++---- skills/uipath-maestro-flow/references/diagnose.md | 2 +- skills/uipath-maestro-flow/references/operate.md | 2 +- 4 files changed, 14 insertions(+), 6 deletions(-) diff --git a/skill-flavors/studioweb/uipath-maestro-flow/references/brownfield.md b/skill-flavors/studioweb/uipath-maestro-flow/references/brownfield.md index 732accba39..5d57c6e36f 100644 --- a/skill-flavors/studioweb/uipath-maestro-flow/references/brownfield.md +++ b/skill-flavors/studioweb/uipath-maestro-flow/references/brownfield.md @@ -113,3 +113,7 @@ In Studio Web the target `.flow` is the source: use the round trip in or tell the user this needs `@uipath/maestro-builder-sdk` 6.114.0 or later, since Studio Web owns the SDK copy). + + +tell the user, since Studio Web owns the SDK copy and the merged `.flow` is never edited by hand. + diff --git a/skills/uipath-maestro-flow/references/brownfield.md b/skills/uipath-maestro-flow/references/brownfield.md index 0875f0f221..866ff0ed7c 100644 --- a/skills/uipath-maestro-flow/references/brownfield.md +++ b/skills/uipath-maestro-flow/references/brownfield.md @@ -616,17 +616,21 @@ Do not run `uip maestro flow format` on the merged file; it discards the author' Decompiled source carries that layout as a `.layout({ nodes })` block, one long-hand entry per node. Keep it. -Only an added step's entry lands: a step the edit adds has none, so compile places it on its placeholder row and `merge` moves it next to its neighbours; to choose the spot yourself, add `: at(x, y)` beside the neighbouring entries (`import { at } from '@uipath/maestro-builder-sdk'`); `merge` keeps a step you placed and moves only the ones compile left unplaced (`@uipath/maestro-builder-sdk` 6.114.0 or later; an older SDK also moves an `at()` where (x − 256) is a multiple of 288 on y = 144 or 304, so avoid those spots, +A step the edit adds has no entry, so compile places it on its placeholder row and `merge` moves it next to its neighbours; to choose the spot yourself, add `: at(x, y)` beside the neighbouring entries (`import { at } from '@uipath/maestro-builder-sdk'`); `merge` keeps a step you placed and moves only the ones compile left unplaced (`@uipath/maestro-builder-sdk` 6.114.0 or later; an older SDK also moves an `at()` where (x − 256) is a multiple of 288 on y = 144 or 304, so avoid those spots, or upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`). A container the edit grows can still push that spot aside, so keep where it lands. -At the root, an existing node's position and size come from the original whatever the source says, except that `merge` shifts later nodes and grows a container to fit added steps; moving or resizing one in the source does nothing, so for any other change set `layout.nodes..position` or `.size` in the merged `.flow` instead, and only when the file has no `layout.nodes` map, the node's `ui`. -Inside a subflow the source's entries land only when the edit changed that subflow: `merge` then takes the subflow from the edited compile whole, and otherwise keeps the original subflow as it was (6.44.4 or later; an older SDK takes every subflow from the edited compile, +To move or resize an existing node, change its entry in the source and merge again: `merge` applies an entry whose position, size or collapsed state differs from the baseline to the original node, at the root and in subflows, and every other node keeps the original's geometry. For example, `review: at(640, 144)` changed to `at(640, 304)` moves only `review`. No hand edit of the merged `.flow` is needed. +This needs an SDK with builder-sdk#2037. An older SDK keeps the original's position and size whatever the source says; + +with it, set `layout.nodes..position` or `.size` in the merged `.flow` instead (the node's `ui` only when the file has no `layout.nodes` map), or upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`. + +`merge` still shifts later nodes and grows a container to fit added steps. A subflow the edit changed is taken from the edited compile whole; any other subflow keeps the original (6.44.4 or later; an older SDK takes every subflow from the edited compile, so upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`). -A step the edit removes must lose its entry, or compile fails on the unknown key. +Remove the entry of a step the edit removes. A leftover key does not fail compile: compile drops it and warns `LAYOUT_UNKNOWN_KEY`, and `check` reports the same warning (an SDK with builder-sdk#2037; an older SDK fails compile on it). Grid and rules: [`operate.md`](operate.md#lay-out-from-source-instead-layout-at-dim). ## A path without an End stays open diff --git a/skills/uipath-maestro-flow/references/diagnose.md b/skills/uipath-maestro-flow/references/diagnose.md index 9898f76d57..0a67b5630a 100644 --- a/skills/uipath-maestro-flow/references/diagnose.md +++ b/skills/uipath-maestro-flow/references/diagnose.md @@ -132,7 +132,7 @@ canvas. When the source sets `.layout()`, the misshapen node is the one with no entry, an entry at the wrong coordinates, or a container whose `dim()` no longer holds a body that grew. In a greenfield source: add or move its `at(x, y)`, resize with `dim(width, height)`, and recompile rather than running `format`, which would discard every other entry too. -In a merged brownfield file only an added node's entry lands; fix an existing node's position or size in the merged `.flow`'s `layout.nodes` ([`operate.md`](operate.md#lay-out-from-source-instead-layout-at-dim), [`brownfield.md`](brownfield.md#designer-shapes-decompile-keeps)). +In a brownfield edit, fix it the same way in the decompiled source and merge again; `merge` applies a changed entry to the original node ([`operate.md`](operate.md#lay-out-from-source-instead-layout-at-dim)). This needs an SDK with builder-sdk#2037; the older-SDK fallback is in [`brownfield.md`](brownfield.md#designer-shapes-decompile-keeps). **Green `validate`, faulted `debug`.** Structural correctness and runtime correctness are different claims. `validate` proves the emitted `.flow` is well diff --git a/skills/uipath-maestro-flow/references/operate.md b/skills/uipath-maestro-flow/references/operate.md index af12fdb4fe..9b46cdc887 100644 --- a/skills/uipath-maestro-flow/references/operate.md +++ b/skills/uipath-maestro-flow/references/operate.md @@ -78,7 +78,7 @@ Rules: Compile gives a node without `dim()` its canvas-shape size: an agent node (`inlineAgent`, `conversationalAgent`, `voiceAgent`) is 288 × 96, so the next column starts 384 px to its right; a container is 560 × 320 unless its `dim()` makes it larger (rule 2), and the row below it starts one row gap (64 px) under its bottom edge, not at the next 160 px row. 2. **A child's position is relative to its container.** A loop or do-while body starts at `at(144, 96)` inside the container's padding. The container's 560 × 320 holds a small body; give it a `dim()` only when the body needs more: the right edge of its rightmost child plus 144, by the bottom edge of its lowest child plus 96. For one row of 96 px nodes that is `dim(192 × bodyNodes + 192, 320)` from two body nodes on (two nodes: `dim(576, 320)`, as `eachInvoice` above); a body with an inline agent, a second row or a nested container is measured from its own entries, not from the node count. -3. **Name every node, or none.** A missing entry falls back to compile's one-row placeholder, which lands on top of your layout; an unknown key fails `compile`. +3. **Name every node, or none.** A missing entry falls back to compile's one-row placeholder, which lands on top of your layout. A key that names no node is dropped with a `LAYOUT_UNKNOWN_KEY` warning (an older SDK without builder-sdk#2037 fails `compile` on it); remove it. 4. **Never `format` a file whose source sets `.layout()`.** `format` re-lays out every node and discards the source's positions, exactly as it does to a merged brownfield file. 5. **`at` and `dim` need `@uipath/maestro-builder-sdk` 6.36.0 or later** — check that `dist/api-index.md` of the SDK copy in use lists them. If not, upgrade that copy: `npm install @uipath/maestro-builder-sdk@latest` in a workspace that has its own `node_modules` copy (it is used before the global one), else `npm install -g @uipath/maestro-builder-sdk@latest`; or write the entry long-hand, `{ position: { x, y } }` with an optional `size: { width, height }`. From 89658a0b55805a251a635144ac07918f4adf681e Mon Sep 17 00:00:00 2001 From: tmatup <51425734+tmatup@users.noreply.github.com> Date: Sun, 15 Nov 2026 08:54:52 -0800 Subject: [PATCH 2/4] docs(uipath-maestro-flow): a node compile placed may have no entry; a kept subflow takes your changed entries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review on #4725: decompile writes no .layout() entry for a node compile placed, so the move instruction says change or add the entry; and a subflow kept from the original still takes the entries you changed. 🤖 Generated with Claude Code Co-Authored-By: [Claude](mailto:noreply@anthropic.com) --- skills/uipath-maestro-flow/references/brownfield.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/uipath-maestro-flow/references/brownfield.md b/skills/uipath-maestro-flow/references/brownfield.md index 866ff0ed7c..d275bb6d86 100644 --- a/skills/uipath-maestro-flow/references/brownfield.md +++ b/skills/uipath-maestro-flow/references/brownfield.md @@ -621,12 +621,12 @@ A step the edit adds has no entry, so compile places it on its placeholder row a or upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`). A container the edit grows can still push that spot aside, so keep where it lands. -To move or resize an existing node, change its entry in the source and merge again: `merge` applies an entry whose position, size or collapsed state differs from the baseline to the original node, at the root and in subflows, and every other node keeps the original's geometry. For example, `review: at(640, 144)` changed to `at(640, 304)` moves only `review`. No hand edit of the merged `.flow` is needed. +To move or resize an existing node, change or add its entry in the source (decompile writes none for a node compile placed and nobody moved since) and merge again: `merge` applies an entry whose position, size or collapsed state differs from the baseline to the original node, at the root and in subflows, and every other node keeps the original's geometry. For example, `review: at(640, 144)` changed to `at(640, 304)` moves only `review`. No hand edit of the merged `.flow` is needed. This needs an SDK with builder-sdk#2037. An older SDK keeps the original's position and size whatever the source says; with it, set `layout.nodes..position` or `.size` in the merged `.flow` instead (the node's `ui` only when the file has no `layout.nodes` map), or upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`. -`merge` still shifts later nodes and grows a container to fit added steps. A subflow the edit changed is taken from the edited compile whole; any other subflow keeps the original (6.44.4 or later; an older SDK takes every subflow from the edited compile, +`merge` still shifts later nodes and grows a container to fit added steps. A subflow the edit changed is taken from the edited compile whole; any other subflow keeps the original, plus the entries you changed (6.44.4 or later; an older SDK takes every subflow from the edited compile, so upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`). From 3fa3e16a975aaff04ff0d66c7573953eb3875215 Mon Sep 17 00:00:00 2001 From: tmatup <51425734+tmatup@users.noreply.github.com> Date: Sun, 15 Nov 2026 12:51:25 -0800 Subject: [PATCH 3/4] docs(uipath-maestro-flow): decompile drops marked entries only while the whole scope is compile's MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Matches builder-sdk#2035 e7ef8e63e: once any node of a laid-out flow or subflow is moved, decompile writes every node's entry. 🤖 Generated with Claude Code Co-Authored-By: [Claude](mailto:noreply@anthropic.com) --- skills/uipath-maestro-flow/references/brownfield.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/uipath-maestro-flow/references/brownfield.md b/skills/uipath-maestro-flow/references/brownfield.md index d275bb6d86..8d097b298a 100644 --- a/skills/uipath-maestro-flow/references/brownfield.md +++ b/skills/uipath-maestro-flow/references/brownfield.md @@ -621,7 +621,7 @@ A step the edit adds has no entry, so compile places it on its placeholder row a or upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`). A container the edit grows can still push that spot aside, so keep where it lands. -To move or resize an existing node, change or add its entry in the source (decompile writes none for a node compile placed and nobody moved since) and merge again: `merge` applies an entry whose position, size or collapsed state differs from the baseline to the original node, at the root and in subflows, and every other node keeps the original's geometry. For example, `review: at(640, 144)` changed to `at(640, 304)` moves only `review`. No hand edit of the merged `.flow` is needed. +To move or resize an existing node, change or add its entry in the source (decompile writes none while every node of that flow or subflow is still where compile put it) and merge again: `merge` applies an entry whose position, size or collapsed state differs from the baseline to the original node, at the root and in subflows, and every other node keeps the original's geometry. For example, `review: at(640, 144)` changed to `at(640, 304)` moves only `review`. No hand edit of the merged `.flow` is needed. This needs an SDK with builder-sdk#2037. An older SDK keeps the original's position and size whatever the source says; with it, set `layout.nodes..position` or `.size` in the merged `.flow` instead (the node's `ui` only when the file has no `layout.nodes` map), or upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`. From 23255ecb5f504fb77ee10d0071ee77a445c6309f Mon Sep 17 00:00:00 2001 From: tmatup <51425734+tmatup@users.noreply.github.com> Date: Sun, 15 Nov 2026 14:30:43 -0800 Subject: [PATCH 4/4] docs(uipath-maestro-flow): name the SDK release that applies layout edits (6.115.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit builder-sdk#2037 shipped in @uipath/maestro-builder-sdk 6.115.0. The Studio Web override tells the user the version. 🤖 Generated with Claude Code Co-Authored-By: [Claude](mailto:noreply@anthropic.com) --- .../studioweb/uipath-maestro-flow/references/brownfield.md | 2 +- skills/uipath-maestro-flow/references/brownfield.md | 4 ++-- skills/uipath-maestro-flow/references/diagnose.md | 2 +- skills/uipath-maestro-flow/references/operate.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/skill-flavors/studioweb/uipath-maestro-flow/references/brownfield.md b/skill-flavors/studioweb/uipath-maestro-flow/references/brownfield.md index 5d57c6e36f..42400fa08e 100644 --- a/skill-flavors/studioweb/uipath-maestro-flow/references/brownfield.md +++ b/skill-flavors/studioweb/uipath-maestro-flow/references/brownfield.md @@ -115,5 +115,5 @@ or tell the user this needs `@uipath/maestro-builder-sdk` 6.114.0 or later, sinc -tell the user, since Studio Web owns the SDK copy and the merged `.flow` is never edited by hand. +tell the user this needs `@uipath/maestro-builder-sdk` 6.115.0 or later, since Studio Web owns the SDK copy and the merged `.flow` is never edited by hand. diff --git a/skills/uipath-maestro-flow/references/brownfield.md b/skills/uipath-maestro-flow/references/brownfield.md index 8d097b298a..e48799e2e4 100644 --- a/skills/uipath-maestro-flow/references/brownfield.md +++ b/skills/uipath-maestro-flow/references/brownfield.md @@ -622,7 +622,7 @@ or upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`). A container the edit grows can still push that spot aside, so keep where it lands. To move or resize an existing node, change or add its entry in the source (decompile writes none while every node of that flow or subflow is still where compile put it) and merge again: `merge` applies an entry whose position, size or collapsed state differs from the baseline to the original node, at the root and in subflows, and every other node keeps the original's geometry. For example, `review: at(640, 144)` changed to `at(640, 304)` moves only `review`. No hand edit of the merged `.flow` is needed. -This needs an SDK with builder-sdk#2037. An older SDK keeps the original's position and size whatever the source says; +This needs `@uipath/maestro-builder-sdk` 6.115.0 or later. An older SDK keeps the original's position and size whatever the source says; with it, set `layout.nodes..position` or `.size` in the merged `.flow` instead (the node's `ui` only when the file has no `layout.nodes` map), or upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`. @@ -630,7 +630,7 @@ with it, set `layout.nodes..position` or `.size` in the merged `.flow` inste so upgrade with `npm install -g @uipath/maestro-builder-sdk@latest`). -Remove the entry of a step the edit removes. A leftover key does not fail compile: compile drops it and warns `LAYOUT_UNKNOWN_KEY`, and `check` reports the same warning (an SDK with builder-sdk#2037; an older SDK fails compile on it). +Remove the entry of a step the edit removes. A leftover key does not fail compile: compile drops it and warns `LAYOUT_UNKNOWN_KEY`, and `check` reports the same warning (`@uipath/maestro-builder-sdk` 6.115.0 or later; an older SDK fails compile on it). Grid and rules: [`operate.md`](operate.md#lay-out-from-source-instead-layout-at-dim). ## A path without an End stays open diff --git a/skills/uipath-maestro-flow/references/diagnose.md b/skills/uipath-maestro-flow/references/diagnose.md index 0a67b5630a..c61fd5753b 100644 --- a/skills/uipath-maestro-flow/references/diagnose.md +++ b/skills/uipath-maestro-flow/references/diagnose.md @@ -132,7 +132,7 @@ canvas. When the source sets `.layout()`, the misshapen node is the one with no entry, an entry at the wrong coordinates, or a container whose `dim()` no longer holds a body that grew. In a greenfield source: add or move its `at(x, y)`, resize with `dim(width, height)`, and recompile rather than running `format`, which would discard every other entry too. -In a brownfield edit, fix it the same way in the decompiled source and merge again; `merge` applies a changed entry to the original node ([`operate.md`](operate.md#lay-out-from-source-instead-layout-at-dim)). This needs an SDK with builder-sdk#2037; the older-SDK fallback is in [`brownfield.md`](brownfield.md#designer-shapes-decompile-keeps). +In a brownfield edit, fix it the same way in the decompiled source and merge again; `merge` applies a changed entry to the original node ([`operate.md`](operate.md#lay-out-from-source-instead-layout-at-dim)). This needs `@uipath/maestro-builder-sdk` 6.115.0 or later; the older-SDK fallback is in [`brownfield.md`](brownfield.md#designer-shapes-decompile-keeps). **Green `validate`, faulted `debug`.** Structural correctness and runtime correctness are different claims. `validate` proves the emitted `.flow` is well diff --git a/skills/uipath-maestro-flow/references/operate.md b/skills/uipath-maestro-flow/references/operate.md index 9b46cdc887..10b599302f 100644 --- a/skills/uipath-maestro-flow/references/operate.md +++ b/skills/uipath-maestro-flow/references/operate.md @@ -78,7 +78,7 @@ Rules: Compile gives a node without `dim()` its canvas-shape size: an agent node (`inlineAgent`, `conversationalAgent`, `voiceAgent`) is 288 × 96, so the next column starts 384 px to its right; a container is 560 × 320 unless its `dim()` makes it larger (rule 2), and the row below it starts one row gap (64 px) under its bottom edge, not at the next 160 px row. 2. **A child's position is relative to its container.** A loop or do-while body starts at `at(144, 96)` inside the container's padding. The container's 560 × 320 holds a small body; give it a `dim()` only when the body needs more: the right edge of its rightmost child plus 144, by the bottom edge of its lowest child plus 96. For one row of 96 px nodes that is `dim(192 × bodyNodes + 192, 320)` from two body nodes on (two nodes: `dim(576, 320)`, as `eachInvoice` above); a body with an inline agent, a second row or a nested container is measured from its own entries, not from the node count. -3. **Name every node, or none.** A missing entry falls back to compile's one-row placeholder, which lands on top of your layout. A key that names no node is dropped with a `LAYOUT_UNKNOWN_KEY` warning (an older SDK without builder-sdk#2037 fails `compile` on it); remove it. +3. **Name every node, or none.** A missing entry falls back to compile's one-row placeholder, which lands on top of your layout. A key that names no node is dropped with a `LAYOUT_UNKNOWN_KEY` warning (an SDK older than 6.115.0 fails `compile` on it); remove it. 4. **Never `format` a file whose source sets `.layout()`.** `format` re-lays out every node and discards the source's positions, exactly as it does to a merged brownfield file. 5. **`at` and `dim` need `@uipath/maestro-builder-sdk` 6.36.0 or later** — check that `dist/api-index.md` of the SDK copy in use lists them. If not, upgrade that copy: `npm install @uipath/maestro-builder-sdk@latest` in a workspace that has its own `node_modules` copy (it is used before the global one), else `npm install -g @uipath/maestro-builder-sdk@latest`; or write the entry long-hand, `{ position: { x, y } }` with an optional `size: { width, height }`.