docs(uipath-maestro-flow): add fast-path flow example

skills/uipath-maestro-flow/SKILL.md

@@ -40,6 +40,7 @@ Comprehensive guide for creating, editing, validating, debugging, publishing, an
 | I want to...                                                 | Read                                                                                             |
 | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
 | Create a new flow or edit an existing one                    | [references/author/CAPABILITY.md](references/author/CAPABILITY.md)                               |
+| Start from a known-good branching example                    | [references/examples/README.md](references/examples/README.md)                                   |
 | Publish, deploy, debug, or manage a flow's lifecycle         | [references/operate/CAPABILITY.md](references/operate/CAPABILITY.md)                             |
 | Diagnose a failed or misbehaving flow run                    | [references/diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md)                           |
 | Look up CLI command syntax                                   | [references/shared/cli-commands.md](references/shared/cli-commands.md)                                   |

skills/uipath-maestro-flow/references/author/references/editing-operations-cli.md

@@ -31,7 +31,11 @@ uip maestro flow node add <ProjectName>.flow <nodeType> --output json \
 | `--position` | No | `x,y` coordinates. Any value is fine (e.g. `0,0`) — `flow tidy` rewrites positions on save. |
 | `--output json` | Yes (for parsing) | Structured JSON response with the assigned node `id` |
 
-**Shell quoting tip:** If `--input` JSON contains special characters (quotes, braces, `$vars`), write it to a temp file:
+**Shell quoting tip:** There is no `--input-file` flag for `node add` in current
+CLI releases. If `--input` JSON contains special characters (quotes, braces,
+`$vars`), prefer the Direct JSON strategy. If the user explicitly requested CLI,
+write the input to a temp file and pass its contents through command
+substitution:
 
 ```bash
 cat > /tmp/input.json << 'ENDJSON'

skills/uipath-maestro-flow/references/author/references/editing-operations.md

@@ -6,6 +6,12 @@ Strategy selection and shared concepts for modifying `.flow` files. Two implemen
 
 > **Default to Direct JSON for all `.flow` edits.** Use CLI only when the user explicitly requests CLI, or for connector, connector-trigger, or inline-agent nodes (see carve-out rows in the matrix below).
 
+For common manual-trigger branching flows, use
+[examples/decision-branch.flow](examples/decision-branch.flow) as the starting
+template instead of adding each non-connector node through `node add`. It avoids
+inline JSON shell escaping for `$vars`, backticks, quotes, and multiline scripts
+while preserving a validator-clean topology that can be adapted in-place.
+
 | Strategy | Guide | When to use |
 |----------|-------|-------------|
 | **Direct JSON** (default) | [editing-operations-json.md](editing-operations-json.md) | Default for all `.flow` edits — node/edge CRUD, variables, subflows, output mapping, in-place input updates. |
@@ -73,6 +79,12 @@ These apply regardless of which strategy you use.
 - Do not validate after each individual edit — intermediate states are expected to be invalid
 - Validation checks: JSON schema, definitions coverage, edge references, unique IDs
 - Validation does NOT check: connector configuration, connection health, expression correctness, required field completeness
+- If a validation warning claims a required node input is missing, inspect the
+  actual node `inputs` and the registry definition before changing working JSON.
+  Older CLI versions have reported `REQUIRED_FIELD` warnings for fields that
+  were present, especially after complex inline `--input` values. Prefer direct
+  JSON edits when the input contains `$vars`, quotes, backticks, or multiline
+  script.
 
 ### Expression prefix rules
 

skills/uipath-maestro-flow/references/examples/README.md

@@ -0,0 +1,29 @@
+# Flow Examples
+
+This directory contains complete `.flow` files that can be copied into a
+scaffolded Flow project and validated locally. Use them as known-good baselines
+when building common patterns directly in JSON.
+
+## Decision Branch
+
+`decision-branch.flow` demonstrates:
+
+- manual trigger
+- script output captured in `$vars`
+- decision node with `true` and `false` branches
+- two branch-specific script nodes
+- separate End nodes with workflow output mappings
+- registry-derived definitions for every node type
+- horizontal layout entries for every node
+
+Validate the example before using it:
+
+```bash
+uip maestro flow validate skills/uipath-maestro-flow/references/examples/decision-branch.flow --output json
+```
+
+To use it as a starting point, scaffold a Flow project with
+`uip maestro flow init`, replace the generated `<ProjectName>.flow` contents
+with this file, then update the top-level `name` and any node labels or scripts.
+Keep the `.flow` file extension; `uip maestro flow validate` rejects copied
+examples that are renamed with a `.json` suffix.