@uipath/skills 1.204.0 → 1.204.1-preview.1370

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "uipath",
       "source": "./",
       "description": "UiPath plugin for Claude Code — custom skills, agents, hooks, and MCP servers for UiPath workflows, UI automation, UI testing and UiPath troubleshoot",
-      "version": "1.204.0",
+      "version": "1.204.1",
       "author": {
         "name": "UiPath"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "uipath",
-  "version": "1.204.0",
+  "version": "1.204.1",
   "description": "UiPath plugin for Claude Code — custom skills, agents, hooks, and MCP servers for UiPath RPA workflows, UI automation, UI testing, Python coded agents and UiPath troubleshoot",
   "author": {
     "name": "UiPath"

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "uipath",
   "displayName": "UiPath",
-  "version": "1.204.0",
+  "version": "1.204.1",
   "description": "UiPath plugin for Cursor — skills for building, running, testing, and deploying UiPath automations, agents, coded apps, and platform operations.",
   "author": {
     "name": "UiPath",

package/CODEOWNERS

@@ -21,6 +21,7 @@
 /skill-flavors/studioweb/ @astridstaicu
 
 # preview skills
+/preview/skills/uipath-maestro-flow/ @UiPath/maestro-cli-team
 /preview/skills/uipath-maestro-case/ @dmetzgar @tmatup
 /preview/skills/uipath-maestro-bpmn/ @UiPath/maestro-cli-team
 
@@ -117,15 +118,12 @@
 
 # Flow skill
 /skills/uipath-maestro-flow/ @chandusailella @mukundbayyaram @UiPath/maestro-cli-team
-# Previous Flow generation (JSON authoring), kept only because the Studio Web
-# flavor pins it (skill-flavors/studioweb/uipath-maestro-flow/.canonical).
-/classic/skills/uipath-maestro-flow/ @chandusailella @mukundbayyaram @UiPath/maestro-cli-team @astridstaicu
 # Flow test tasks (general) — more specific subfolder rules below override this
 /tests/tasks/uipath-maestro-flow/ @UiPath/maestro-cli-team
 
 # Context grounding team — flow plugins (Summarize/Batch Transform) + tasks
-/skills/uipath-maestro-flow/references/summarize.md @gcuip @JeremyReist2 @cfauchere @CalebMartinUiPath @jordan-uipath @eteodorovici @pateljay43 @swathiJayav @UiPath/maestro-cli-team
-/skills/uipath-maestro-flow/references/batch-transform.md @gcuip @JeremyReist2 @cfauchere @CalebMartinUiPath @jordan-uipath @eteodorovici @pateljay43 @swathiJayav @UiPath/maestro-cli-team
+/skills/uipath-maestro-flow/references/author/plugins/summarize/ @gcuip @JeremyReist2 @cfauchere @CalebMartinUiPath @jordan-uipath @eteodorovici @pateljay43 @swathiJayav @UiPath/maestro-cli-team
+/skills/uipath-maestro-flow/references/author/plugins/batch-transform/ @gcuip @JeremyReist2 @cfauchere @CalebMartinUiPath @jordan-uipath @eteodorovici @pateljay43 @swathiJayav @UiPath/maestro-cli-team
 /tests/tasks/uipath-maestro-flow/context-grounding/ @gcuip @JeremyReist2 @cfauchere @CalebMartinUiPath @jordan-uipath @eteodorovici @pateljay43 @swathiJayav @UiPath/maestro-cli-team
 
 # Maestro BPMN skill
@@ -157,13 +155,13 @@
 /tests/tasks/uipath-connector-builder/ @mukeshkumar-uipath @chandusailella @apoosarla-uipath
 /tests/tasks/activation/uipath-connector-builder.jsonl @mukeshkumar-uipath @chandusailella @apoosarla-uipath
 
-# Flow skill — node guides (away team owned)
+# Flow skill — plugin guides (away team owned)
 # Add your team here when contributing a new plugin category
-/skills/uipath-maestro-flow/references/connector-params.md @chandusailella @UiPath/maestro-cli-team
-/skills/uipath-maestro-flow/references/event-trigger.md @chandusailella @UiPath/maestro-cli-team
-/skills/uipath-maestro-flow/references/agent.md @UiPath/team-coded-agents @AlexandruCGhimisi @andreibalas-uipath @al3xanndru @UiPath/maestro-cli-team
-/skills/uipath-maestro-flow/references/inline-agent.md @AlexandruCGhimisi @andreibalas-uipath @al3xanndru @UiPath/maestro-cli-team
-/skills/uipath-maestro-flow/references/data-fabric.md @UiPath/DatafabricCodingAgent @UiPath/maestro-cli-team
+/skills/uipath-maestro-flow/references/author/plugins/connector/ @chandusailella @UiPath/maestro-cli-team
+/skills/uipath-maestro-flow/references/author/plugins/connector-trigger/ @chandusailella @UiPath/maestro-cli-team
+/skills/uipath-maestro-flow/references/author/plugins/agent/ @UiPath/team-coded-agents @AlexandruCGhimisi @andreibalas-uipath @al3xanndru @UiPath/maestro-cli-team
+/skills/uipath-maestro-flow/references/author/plugins/inline-agent/ @AlexandruCGhimisi @andreibalas-uipath @al3xanndru @UiPath/maestro-cli-team
+/skills/uipath-maestro-flow/references/author/plugins/data-fabric/ @UiPath/DatafabricCodingAgent @UiPath/maestro-cli-team
 /tests/tasks/uipath-maestro-flow/connector_features/ @chandusailella @mukundbayyaram @UiPath/maestro-cli-team
 /tests/tasks/uipath-maestro-flow/connector_features/datafabric_connector @UiPath/DatafabricCodingAgent @UiPath/maestro-cli-team
 # Checkers relocated to _shared/ during the host-path-removal migration (test: d61fa9d52) —
@@ -172,15 +170,15 @@
 /tests/tasks/uipath-maestro-flow/_shared/check_generic_dynamic_node.py @chandusailella @mukundbayyaram @UiPath/maestro-cli-team
 
 # IXP
-/skills/uipath-maestro-flow/references/ixp.md @UiPath/communications-mining @constantinmuraru @vlad-crisan @UiPath/maestro-cli-team
+/skills/uipath-maestro-flow/references/author/plugins/ixp/ @UiPath/communications-mining @constantinmuraru @vlad-crisan @UiPath/maestro-cli-team
 /tests/tasks/uipath-maestro-flow/ixp/ @UiPath/communications-mining @constantinmuraru @vlad-crisan @UiPath/maestro-cli-team
 
 # Chat — inline conversational agent node + the conversation trigger and message nodes
-/skills/uipath-maestro-flow/references/conversational.md @UiPath/jarvis @UiPath/maestro-cli-team
+/skills/uipath-maestro-flow/references/author/plugins/conversational-agent/ @UiPath/jarvis @UiPath/maestro-cli-team
 /tests/tasks/uipath-maestro-flow/conversational/ @UiPath/jarvis @UiPath/maestro-cli-team
 
 # Voice — inline voice agent node + the trigger, dial, and end-call nodes
-/skills/uipath-maestro-flow/references/voice.md @UiPath/jarvis @UiPath/maestro-cli-team
+/skills/uipath-maestro-flow/references/author/plugins/inline-voice-agent/ @UiPath/jarvis @UiPath/maestro-cli-team
 /tests/tasks/uipath-maestro-flow/voice/ @UiPath/jarvis @UiPath/maestro-cli-team
 
 # Review skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/skills",
-  "version": "1.204.0",
+  "version": "1.204.1-preview.1370",
   "description": "UiPath agent skills for Claude Code, Codex, Cursor, Copilot, Gemini and OpenCode — RPA, UI automation, UI testing, coded agents/apps/workflows, and troubleshooting. Distributed as the UiPath Claude Code plugin.",
   "author": {
     "name": "UiPath"

package/skills/uipath-agents/references/coded/embedding-in-flows.md

@@ -4,8 +4,6 @@ A coded agent can live as a sibling folder to a flow project inside the same sol
 
 For the published-agent path (deployed standalone via `uip codedagent deploy`), see [coded/flow-integration.md § Pattern 2](flow-integration.md#pattern-2-published-coded-agent).
 
-**Builder-SDK Flow projects (`.flow.ts`) — the default:** call the coded agent with an `agent({...})` step in `<Name>.flow.ts` — see [agent.md](../../../uipath-maestro-flow/references/agent.md). `compile` emits the node, definition and bindings; the JSON in this file applies to a JSON-authored `.flow`.
-
 ## Sibling Folder Structure
 
 The `<resourceKey>` is the local UUID minted by `uip solution projects add` — stable the moment the agent joins the solution.
@@ -116,4 +114,4 @@ One `inputs.<field>` entry per property in the agent's input schema (`entry-poin
 
 NEVER a plain `"=js:..."` string value — it ships as a literal string to the agent activity and fails at runtime with `Cannot find name '<identifier>'`. Complete worked example (trigger → agent → end): uipath-maestro-flow skill, agent-plugin reference § Wiring Inputs.
 
-Input-only rule. In a builder-SDK (`.flow.ts`) project you never write that mapping: `.return({ <output>: out('<agentStep>', '<field>') })` makes the builder emit it — see [return.md](../../../uipath-maestro-flow/references/return.md).
+Input-only rule. Mapping the agent's output back to a flow-level global on an End node DOES use `=js:` — see [variables-and-expressions.md § Variable Updates](../../../uipath-maestro-flow/references/shared/variables-and-expressions.md#variable-updates-variableupdates).

package/skills/uipath-agents/references/coded/quickstart.md

@@ -298,8 +298,6 @@ Execute the following in order, end-to-end, in one pass — do not pause for con
 
    The second command's `Data.Node` object is what gets pasted verbatim into the flow's top-level `definitions[]` array.
 
-   **Builder-SDK Flow projects (`.flow.ts`) — the default:** replace step 7 with one `agent({ key, name, ... })` step in `<Name>.flow.ts` and a `compile` — see [agent.md](../../../uipath-maestro-flow/references/agent.md). Step 7's JSON edits apply to a JSON-authored `.flow`.
-
 7. **Wire the agent node into the `.flow` file.** Edit `<FlowName>.flow` directly:
    - Add a `uipath.core.agent.<resourceKey>` node to `nodes[]` with one `inputs.<field>` entry per property in the agent's input schema (see step 6's `Data.Node.inputDefinition`) and `model.section: "In this solution"`.
    - For input field values, see [embedding-in-flows.md § Wiring the Agent's Inputs](embedding-in-flows.md#wiring-the-agents-inputs).

package/skills/uipath-agents/references/lowcode/capabilities/inline-in-flow/inline-in-flow.md

@@ -4,8 +4,6 @@ Walkthrough for embedding a low-code autonomous agent directly inside a flow pro
 
 Flow authoring itself is the responsibility of the `uipath-maestro-flow` skill — this file covers only the inline-agent side (creating the agent subdirectory, configuring it, and the shape of the `uipath.agent.autonomous` flow node that references it).
 
-**Builder-SDK Flow projects (`.flow.ts`) — the default:** the agent is one `inlineAgent({...})` step in `<Name>.flow.ts`, and `compile` emits the flow node and the `<source>/agent.json` sidecar — see [inline-agent.md](../../../../../uipath-maestro-flow/references/inline-agent.md). The directory, `agent.json` and node JSON steps below apply to a JSON-authored `.flow`.
-
 ## When to Use
 
 - Agent is tightly coupled to this specific flow
@@ -144,7 +142,7 @@ This skill authors the **`agent.json` side** (flatten rule: `$vars.<trigger>.out
   "content": "Write a billing resolution email for this dispute:\n{{input.start__output__disputeSummary}}" }]
 ```
 
-The **flow side** is authored through the `uipath-maestro-flow` skill. In a builder-SDK (`.flow.ts`) project it is one `inlineAgent({ ..., userPrompt: '… {{input.<name>}} …', inputs: { <name>: <flow expression> } })` step: `compile` emits the node, its input bindings and the `agent.json` sidecar, so none of that is written by hand — see [inline-agent.md](../../../../../uipath-maestro-flow/references/inline-agent.md).
+The **flow side** — the trigger global and the node `agentInputVariables[]` binding (the only thing the converter turns into `JobArguments`) — is authored through the `uipath-maestro-flow` skill (Critical Rule 15). The full four-piece contract, the converter behavior, and the `content`↔`contentTokens` invariant + validator errors all live there: [inline-agent prompt-wiring guide § Wiring Flow Variables into Agent Prompts](../../../../../uipath-maestro-flow/references/author/plugins/inline-agent/impl.md#wiring-flow-variables-into-agent-prompts).
 
 ## Refresh and Validate Inline Agent
 
@@ -155,7 +153,7 @@ uip agent validate "<FlowProjectDir>/<projectId>" --inline-in-flow --output json
 
 `--inline-in-flow` skips the `entry-points.json` / `project.uiproj` checks. In inline mode `refresh` regenerates `messages[].contentTokens` (from `content`) and `bindings_v2.json` — **not** `entry-points.json` (standalone only). `validate` is read-only (it flags `contentTokens` drift but doesn't repair it — fix by re-running `refresh`).
 
-**Verify with a real run:** the end-to-end check (run `uip maestro flow debug` and confirm the agent resolves its input rather than echoing the literal `{{input.<name>}}` token) is owned by the `uipath-maestro-flow` skill — see [operate.md](../../../../../uipath-maestro-flow/references/operate.md).
+**Verify at `flow debug`, not after refresh:** `refresh` never fills `inputSchema` — it is non-empty only because you authored it (`DerivedFiles: 0` is normal and does **not** mean input is missing). The end-to-end check (run `uip maestro flow debug` and confirm the agent resolves the input rather than echoing the literal `input.<key>` token) is owned by the `uipath-maestro-flow` skill — see its [inline-agent guide § Debug](../../../../../uipath-maestro-flow/references/author/plugins/inline-agent/impl.md#debug).
 
 For inline agents with external capabilities (tools, contexts, memory spaces, or escalations), pass `--bindings-target` to **`refresh`** after all flow graph edits:
 
@@ -166,13 +164,17 @@ uip agent refresh "<FlowProjectDir>/<projectId>" --inline-in-flow \
 
 `--bindings-target` propagates the inline agent's bindings (process, connection, index, memorySpace, app, etc.) into the flow project's `bindings_v2.json`. This is required for `uip solution resources refresh` to discover the bindings and create solution-level resource files. Never hand-edit `bindings_v2.json`.
 
-> **Builder-SDK Flow projects (`.flow.ts`):** the `inlineAgent({...})` step in `<Name>.flow.ts` IS the flow node, and `compile` emits it, its edges and the `<source>/agent.json` sidecar — see [inline-agent.md](../../../../../uipath-maestro-flow/references/inline-agent.md). Nothing is added to the compiled `.flow` by hand; the ordering rule below applies to a JSON-authored `.flow`.
+> **Ordering constraint:** run the final `uip agent refresh --inline-in-flow --bindings-target …` after all flow graph edits are complete. The `uipath-maestro-flow` skill owns direct `.flow` authoring for the inline-agent node, capability-resource nodes, and edges; refresh last so the generated bindings land in the flow project's `bindings_v2.json` before `uip solution resources refresh`. See the [Walkthrough](#walkthrough--end-to-end) for the correct sequence.
 
 ## Flow Wiring
 
-In a builder-SDK (`.flow.ts`) project, hand the agent's intent to the `uipath-maestro-flow` skill: it authors one `inlineAgent({...})` step and compiles, and that emits the `uipath.agent.autonomous` node and its edges. See [inline-agent.md](../../../../../uipath-maestro-flow/references/inline-agent.md).
+After creating the inline agent, the flow needs a `uipath.agent.autonomous` node whose `inputs.source` is the inline agent's `projectId` UUID, plus edges connecting it to the rest of the flow.
+
+**Hand off to the `uipath-maestro-flow` skill for the actual node and edge authoring.** Per Critical Rule 15, this skill does not invoke flow operations directly. Tell the user:
+
+> The inline agent has been scaffolded at `<FlowProjectDir>/<projectId>/`. To wire it into the flow, use the `uipath-maestro-flow` skill — pass it `projectId = <uuid>` so it can add a `uipath.agent.autonomous` node with `inputs.source = <uuid>` and connect the input/success edges via direct `.flow` authoring. **After all flow graph edits are complete**, run `uip agent refresh --inline-in-flow`, then `uip agent validate --inline-in-flow`; for inline agents with external capabilities, include `--bindings-target <FlowProjectDir>/bindings_v2.json` on the refresh call.
 
-The node JSON in § Flow Node Structure below is the compiled shape — for reading an emitted `.flow`, never for writing one.
+The node JSON shape that the flow skill must produce is documented in § Flow Node Structure below — keep it as a reference, not as a CLI walkthrough.
 
 ## Inline-in-Flow Resource Paths
 
@@ -236,7 +238,7 @@ Resource body shape is identical to the standalone-agent docs — only the folde
 
 **Critical fields:**
 - `inputs.source` — The inline agent's `projectId` UUID. Must match the subdirectory name and `agent.json.projectId` inside the flow project. The definition still declares `model.source: true`, but flow-core hoists that identity field onto `inputs.source` for the `uipath.agent.autonomous` node instance.
-- `inputs.systemPrompt` / `inputs.userPrompt` — in a builder-SDK project, set the prompts with `inlineAgent({ systemPrompt, userPrompt })`; `compile` emits the node and its `agent.json` sidecar from them, so edit neither by hand. See [inline-agent.md](../../../../../uipath-maestro-flow/references/inline-agent.md).
+- `inputs.systemPrompt` / `inputs.userPrompt` — **do not write these keys.** A prompt string on the node makes the flow converter drop every `agentInputVariables[]` entry the prompt text does not reference. Empty strings fail `uip maestro flow validate`. The canonical prompts live in `agent.json.messages[]`. Validator behavior and the older-CLI fallback: [inline-agent guide § Refresh and Validate](../../../../../uipath-maestro-flow/references/author/plugins/inline-agent/impl.md#refresh-and-validate).
 - `definitions[]` — The `uipath.agent.autonomous` definition copied from the flow registry supplies `model.serviceType: "Orchestrator.StartInlineAgentJob"`, BPMN type, version, and context. Do not copy those fields into the node instance.
 - No node instance `model` block — the inline-agent source lives at `inputs.source`.
 

package/skills/uipath-agents/references/lowcode/prompting/autonomous-agent-prompting-guide.md

@@ -53,7 +53,7 @@ The user message carries the task and the data — not the role.
 
 Token form depends on context:
 
-- **Inline-in-flow agents** in a builder-SDK (`.flow.ts`) project name flow values as `{{input.<name>}}` and bind each name with `inlineAgent({ inputs: { <name>: out('<step>', '<field>') } })`. See [inline-agent.md](../../../../uipath-maestro-flow/references/inline-agent.md).
+- **Inline-in-flow agents** reference upstream flow nodes: `{{ $vars.<flowNodeId>.output[.<field>] }}`. See the [uipath-maestro-flow inline-agent prompt-wiring guide](../../../../uipath-maestro-flow/references/author/plugins/inline-agent/impl.md#wiring-flow-variables-into-agent-prompts).
 - **Standalone agents** reference declared inputs: `{{input.<field>}}`.
 
 Mirror every `{{ ... }}` in `contentTokens[]` per [agent-definition.md § contentTokens Construction](../agent-definition.md#contenttokens-construction).

package/skills/uipath-human-in-the-loop/SKILL.md

@@ -86,13 +86,11 @@ find . -name "*.bpmn" -maxdepth 4 | head -3
 
 | Found | Surface | How HITL is added |
 |---|---|---|
-| `.flow.ts` or `.flow` file | **Flow** | Author with `hitl(...)` in `<Name>.flow.ts` through the `uipath-maestro-flow` skill ([hitl.md](../uipath-maestro-flow/references/hitl.md)); never write node JSON into the compiled `.flow` — `compile` overwrites it |
+| `.flow` file | **Flow** | Write node JSON directly — see reference docs |
 | `caseplan.json` (any `*.json` whose `nodes[]` carry `data.parentElement.type: "case-management:root"` — the marker is per-node; there is no `root` node on disk) | **Case** | Write `action` task into stage — see [hitl-casetask-action.md](references/hitl-casetask-action.md) |
 | `agent.json` | **Low Code Agent** | Escalation CLI in-flight — guide manually for now |
 | `.bpmn` (Maestro) | **Maestro** | Write the `UserTask` XML directly — see Step 5 Surface: Maestro |
 
-**Flow surface (a `.flow.ts`, a `.flow`, or a new flow) — the default: stop here.** Hand the HITL request to the `uipath-maestro-flow` skill: it authors `hitl(...)` in `<Name>.flow.ts` — decompiling an existing `.flow` first — and compiles ([hitl.md](../uipath-maestro-flow/references/hitl.md)). Never read or hand-edit the compiled `.flow`; the next `compile` overwrites it. Steps 2–6 below cover the Case, Low-Code Agent and Maestro surfaces.
-
 **If the user mentioned a specific file path**, use that directly.
 
 **If no `.flow` file exists and surface is Flow**, scaffold solution-first — Flow projects MUST live inside a solution:

package/skills/uipath-human-in-the-loop/references/hitl-node-apptask.md

@@ -4,8 +4,6 @@ The AppTask variant uses a deployed coded app (Studio Web) as the task form. Nod
 
 ---
 
-**Builder-SDK Flow projects (`.flow.ts`) — the default:** author a human task with `hitl({...})` in `<Name>.flow.ts` through the `uipath-maestro-flow` skill — see [hitl.md](../../uipath-maestro-flow/references/hitl.md). `compile` emits the node and overwrites the compiled `.flow`, so never write the JSON below into it by hand; it applies to a JSON-authored `.flow`.
-
 ## App Lookup and Solution Registration
 
 Before writing the node JSON, resolve the app and register it with the solution. All API calls use auth from the stored login session (`uip login`).

package/skills/uipath-human-in-the-loop/references/hitl-node-coded-action-app.md

@@ -6,8 +6,6 @@ Use this path when the user selects **New Coded Action App** in Step 3.
 
 ---
 
-**Builder-SDK Flow projects (`.flow.ts`) — the default:** author the action-app task with `hitl({ variant: 'action-app', ... })` in `<Name>.flow.ts` through the `uipath-maestro-flow` skill — see [hitl.md](../../uipath-maestro-flow/references/hitl.md). `compile` emits the node and overwrites the compiled `.flow`, so skip the "write the node into the `.flow`" step below; it applies to a JSON-authored `.flow`.
-
 ## Overview
 
 | Step | Action |

package/skills/uipath-human-in-the-loop/references/hitl-node-quickform.md

@@ -1,6 +1,6 @@
 # HITL QuickForm Node — Direct JSON Reference
 
-In a builder-SDK (`.flow.ts`) project, author the quick form with `hitl({ variant: 'quick-form', ... })` through the `uipath-maestro-flow` skill — see [hitl.md](../../uipath-maestro-flow/references/hitl.md). `compile` emits the node; never write it into the compiled `.flow`, because the next `compile` overwrites the file. The JSON below describes that compiled node, and is how a JSON-authored `.flow` is built.
+The agent writes the `uipath.human-in-the-loop.quick-form` node directly into the `.flow` file as JSON. **Direct JSON is the default.** A CLI opt-in is available when the user explicitly requests it, or as a fallback if direct JSON writing fails — see [CLI reference: uip maestro flow hitl add](../../uipath-maestro-flow/references/shared/cli-commands.md#uip-maestro-flow-hitl-add).
 
 ---
 
@@ -71,7 +71,7 @@ Also read `workflow.variables.globals`. Each entry has an `id` that maps directl
 
 > **`binding` vs `variable` prefix rule:** `binding` (input/inOut fields) uses the full path starting with `vars.` because it references an existing variable path. `variable` (output/inOut fields) uses `vars.<name>` — the `vars.` prefix is required; it declares the global variable name.
 
-For the full variable system in a builder-SDK project, see the expression table in [uipath-maestro-flow SKILL.md § Builder frame](../../uipath-maestro-flow/SKILL.md#builder-frame)
+For the full variable system, see → [How $vars paths are constructed in Flow](../../uipath-maestro-flow/references/shared/variables-and-expressions.md)
 
 ---
 

package/skills/uipath-maestro-flow/.maintenance/README.md

@@ -0,0 +1,265 @@
+# Skill Maintenance
+
+Internal tooling and conventions for maintaining the `uipath-maestro-flow` skill structure. Not loaded by agents during normal use.
+
+## Structure
+
+The skill is organized into four peer capabilities:
+
+```text
+SKILL.md                                ← capability router (universal rules + 4-bucket intent)
+references/
+├── shared/                             ← cross-capability primitives
+│   ├── cli-commands.md                 ← flat CLI lookup
+│   ├── cli-conventions.md              ← --output json, login, FOLDER_KEY, etc.
+│   ├── file-format.md                  ← .flow JSON schema
+│   ├── variables-and-expressions.md    ← =js: Jint expressions
+│   ├── node-output-wiring.md           ← canonical $vars wiring rule
+│   ├── action-nodes.md                 ← action-node boilerplate shared by plugin impl.md's
+│   └── ux-narration-and-todos.md       ← progress narration + todo engage rules
+├── author/
+│   ├── CAPABILITY.md                   ← capability index
+│   ├── greenfield.md                   ← create-new-flow journey
+│   ├── brownfield.md                   ← edit-existing-flow journey
+│   ├── editing-operations.md           ← strategy selection
+│   ├── editing-operations-json.md      ← Edit / Write recipes (default)
+│   ├── editing-operations-cli.md       ← CLI carve-outs
+│   ├── planning-arch.md                ← topology/plugin index
+│   ├── planning-impl.md                ← registry/binding/wiring
+│   └── plugins/                        ← per-node-type planning + impl
+├── operate/
+│   ├── CAPABILITY.md                   ← capability index
+│   ├── ship.md                         ← Studio Web upload + Orchestrator deploy
+│   ├── run.md                          ← debug + process run + job status/traces
+│   └── manage.md                       ← instance lifecycle (pause/resume/cancel/retry)
+├── diagnose/
+│   ├── CAPABILITY.md                   ← capability index
+│   ├── troubleshooting-guide.md        ← diagnostic priority ladder
+│   └── failure-modes.md                ← pattern catalog (missing `=js:`, misshapen nodes, etc.)
+└── evaluate/
+    ├── CAPABILITY.md                   ← capability index
+    ├── commands-reference.md           ← `uip maestro flow eval` surface
+    ├── eval-sets-guide.md              ← eval set + data point design
+    ├── evaluators-guide.md             ← evaluator selection and config
+    ├── running-guide.md                ← Studio Web run start/status/results
+    └── upload-safety.md                ← never auto-upload to satisfy a prerequisite
+```
+
+**Recursive pattern.** Skill = `SKILL.md` + `references/`. Capability = `CAPABILITY.md` + its sibling docs in the same folder. The same "index next to its references" shape at two scales. Future capabilities (e.g., `governance/`) get the template for free.
+
+**Convention:** each capability is a self-contained folder. Every file in `<capability>/` is implicitly that-capability-scoped — path = provenance. The `CAPABILITY.md` index is always at `<capability>/CAPABILITY.md` (uniform shape across all four).
+
+### Capability boundary
+
+- **Author** = on disk, locally, **without `uip login`** (`flow init`, `validate`, `format`, registry, JSON edits)
+- **Operate** = touches the cloud, **requires `uip login`** (`solution upload`, `flow debug`, `flow pack`, `process run`, `instance ...`)
+- **Diagnose** = postmortem on a failed run, **requires `uip login`** (`instance incidents`, `instance variables`, `instance asset`, `incident get`, `job traces`)
+- **Evaluate** = evaluations against a flow already in Studio Web; local eval-set/evaluator CRUD needs no login, **`eval run *` requires `uip login`** (`eval set`, `eval evaluator`, `eval run`)
+
+Author terminates at `validate` + `format` and hands off to Operate. Operate hands off to Diagnose when a run faults. Diagnose hands off back to Author for the underlying fix. Evaluate attaches to a flow Operate has already uploaded.
+
+### Capability-index template
+
+Every `<capability>/CAPABILITY.md` follows the same 6-section structure:
+
+1. `# <Capability> — <one-line purpose>`
+2. `## When to use this capability`
+3. `## Critical rules`
+4. `## Workflow`
+5. `## Common tasks`
+6. `## Anti-patterns`
+7. `## References`
+
+## Markdown anchor slugs (`[link](file.md#section-name)`)
+
+Anchor links are computed exactly as GitHub does — getting them wrong silently produces a dead link that markdown lint won't catch.
+
+### Slug rule
+
+1. Lowercase the heading
+2. Strip these characters entirely: `` ` ``, `*`, `_`, and any non-alphanumeric/non-space/non-dash character
+3. Replace each remaining space with `-`
+4. **Separator characters do not collapse** — each space (or em-dash that became a space-pair) becomes its own dash
+
+### Common gotchas
+
+| Heading | Wrong slug | Correct slug | Why |
+| --- | --- | --- | --- |
+| `## 5. \`--folder-key\` requirement` | `#5--folder-key-requirement` | `#5---folder-key-requirement` | After `.` strips and backticks strip: `5 --folder-key requirement`. The space between `5` and `--` becomes a dash, joining the two literal dashes from `--folder-key` → 3 dashes |
+| `## Reused reference ID — cross-connection ID leakage` | `#reused-reference-id-cross-connection-id-leakage` | `#reused-reference-id--cross-connection-id-leakage` | The em-dash (`—`) is stripped (non-alphanumeric/space/dash), but the spaces on either side of it survive and both become dashes → 2 dashes |
+| `## \`variables.nodes[]\` missing → \`$vars.X.output\` resolves to undefined` | `#variablesnodes-missing-varsxoutput-resolves-to-undefined` | `#variablesnodes-missing--varsxoutput-resolves-to-undefined` | Backticks, `.`, `[`, `]`, `$` and the `→` all strip (non-alphanumeric/space/dash). The space before and after the arrow both survive → 2 consecutive dashes between `missing` and `varsxoutput` |
+
+### Verifying anchor links
+
+Run the anchor-checker script before committing changes that add or edit anchor links:
+
+```bash
+bash .maintenance/check-anchors.sh
+```
+
+Returns `anchors_checked=N anchors_bad=0` on success. Exits non-zero on any bad anchor. Any non-zero `anchors_bad` lists which file → which target slug failed to resolve. An anchor resolves against either a heading slug or an explicit `<a id="...">` / `<a name="...">` tag in the target file — GitHub honors both.
+
+## Verifying file-path links
+
+Run the link-checker script to catch broken `[text](path)` links:
+
+```bash
+bash .maintenance/check-links.sh
+```
+
+Returns `checked=N broken=M`. Exits non-zero on any broken link. Both checkers skip links inside fenced code blocks and inline code spans, so example links in this README don't trigger false positives.
+
+## Verifying link text agrees with link URL
+
+Run the link-text checker to catch links whose **text looks like a file** but whose **URL points elsewhere**:
+
+```bash
+bash .maintenance/check-link-text.sh
+```
+
+Returns `checked=N broken=M`. Exits non-zero on any mismatch. Three failure modes, all hard failures:
+
+- **basename-mismatch** — text basename ≠ URL basename (e.g., text `AUTHOR.md`, URL `../CAPABILITY.md`).
+- **prefix-mismatch** — basenames agree but the directory hint in the text contradicts the URL's directory (e.g., text `operate/manage.md`, URL `references/manage.md`). Tolerated when the text directory is a suffix of the URL directory (e.g., text `author/greenfield.md`, URL `references/author/greenfield.md`).
+- **folder-url-but-text-is-file** — URL ends with `/` but text claims a file.
+
+Only links whose text contains a file-like token (extension `.md`, `.sh`, `.json`, `.js`, `.ts`, `.py`, `.cs`, `.xaml`, `.flow`, `.yaml`, `.yml`) are evaluated; descriptive text like `[Edit/Write: Variable Operations](...)` is skipped. Same skip rules as `check-links.sh` (fenced code, inline code, http(s), slash commands, anchor-only).
+
+## Verifying reachability depth
+
+Run the depth-checker script to verify every file under `references/` is reachable from `SKILL.md` within the configured max hops (default 2):
+
+```bash
+bash .maintenance/check-depth.sh
+```
+
+Pass a custom max-hops value as the first argument:
+
+```bash
+bash .maintenance/check-depth.sh 3
+```
+
+Returns `total_files=N reachable_within=R unreachable=U exceeds_depth=E`. Folder links count as reachability for every file in the folder (per the agent-navigation convention below). Exits non-zero if any file is unreachable or exceeds the configured depth.
+
+## Verifying capability-index template conformance
+
+Run the template-checker script to verify each `CAPABILITY.md` follows the canonical 6-section structure (When to use / Critical rules / Workflow / Common tasks / Anti-patterns / References):
+
+```bash
+bash .maintenance/check-template.sh
+```
+
+Returns `capabilities_checked=N missing_sections=M`. Exits non-zero if any `CAPABILITY.md` is missing a required section. Catches drift if a future edit removes or renames a canonical section.
+
+## Verifying no orphaned files
+
+Run the orphan-checker script to find `.md` files under `references/` that no other `.md` file links to:
+
+```bash
+bash .maintenance/check-orphans.sh
+```
+
+Returns `files_checked=N orphans=M`. Exits non-zero if any orphans are found. `CAPABILITY.md` files are excluded (they are entry points linked from SKILL.md and peer indexes; SKILL.md itself is excluded as the root entry point).
+
+Orphans typically appear after a refactor that removed inbound links but didn't delete the now-unreferenced file. Folder links count as inbound for every `.md` inside the folder, matching the agent-navigation convention used by `check-depth.sh`.
+
+## Verifying plugin folder pairs
+
+Run the plugin-pairs checker to verify every plugin folder has both `planning.md` and `impl.md` (the per-plugin convention):
+
+```bash
+bash .maintenance/check-plugin-pairs.sh
+```
+
+Returns `plugins_checked=N missing_files=M`. Exits non-zero if any plugin folder is missing a required file. Catches half-deleted plugins or new plugin folders that haven't been completed.
+
+## Verifying `uip` command references
+
+Run the uip-command checker to verify every `uip ...` invocation resolves to a real command in the installed CLI:
+
+```bash
+bash .maintenance/check-uip-commands.sh
+```
+
+Returns `commands_checked=N unknown=M`. Exits non-zero if any referenced command path is unknown to `uip`. Verification is **help-only** — the checker walks each command path with `uip <prefix> --help`, confirms the requested segment appears in the parent's `Subcommands` list, and never executes the command for real. Help responses are cached per prefix.
+
+The checker:
+
+- Scans `SKILL.md` and `references/**/*.md`. Skips `.maintenance/` and root-level scratch files (`PLAN.md`, `PR_BODY.md`).
+- Scans both **fenced code blocks** tagged `bash`, `sh`, `shell`, `zsh`, `console`, or unlabelled, **and inline backtick spans** like `` `uip maestro flow init` ``. Inline scanning catches doc-narrative drift that fenced-only scanning misses.
+- Stops the path at the first flag, placeholder (`<...>`), shell metachar, comment (`#`), path-literal, or non-kebab-case token — so positional args like `uip maestro flow registry search outlook` don't get mistreated as subcommands.
+- Treats trailing tokens after a leaf-with-positional-args (e.g. `uip maestro flow registry search <keyword>`) as arguments, not missing subcommands.
+- Falls back gracefully if `uip` is not installed: warns and exits 0. Pass `--strict` to fail in CI.
+
+Pass specific files to scan only those (e.g. for pre-commit on staged files):
+
+```bash
+bash .maintenance/check-uip-commands.sh references/shared/cli-commands.md
+```
+
+### Skipping intentional historical references
+
+Some docs reference removed commands on purpose — for example, a CLI version-comparison table that documents a pre-restructure prefix. Add `<!-- uip-check-skip -->` anywhere on the line to suppress checking for that line:
+
+```markdown
+> Replace `uip maestro flow` with `uip flow` if version < 0.3.4. <!-- uip-check-skip -->
+```
+
+For table rows, place the marker **inside a cell** so it doesn't break table structure (HTML comments render as nothing):
+
+```markdown
+| **< 0.3.4** | `uip flow` | `uip flow init MyProject` <!-- uip-check-skip --> |
+```
+
+## Verifying no hardcoded versions
+
+Run the version checker to catch docs that pin a `.flow` version as authoritative instead of deferring to the live CLI:
+
+```bash
+bash .maintenance/check-versions.sh
+```
+
+Returns `lines_checked=N violations=M`. Exits non-zero on any violation. The `.flow` top-level `version` and node `typeVersion` are owned by `uip maestro flow init` / `uip maestro flow registry get`; hardcoding them rots silently when the CLI advances (e.g. `core.action.http.v2` `2.0`→`2.1`, `core.trigger.scheduled` `1.0`→`1.1`, top-level `1.1`→`1.2`). Two violation classes:
+
+- **PROSE-PIN** — prose stating a version as current/required: `currently "1.1"`, `the registry currently emits "1.0"`, `must be "2.0"`, or an inline assignment `typeVersion: "2.0"` / `version: "1.1"`. Only fires outside fenced code blocks.
+- **TOPLEVEL** — a hardcoded top-level `.flow` `"version": "x.y"` literal in a JSON example. Identified by sibling `"nodes"`/`"edges"` keys within the same fenced block; `definitions[].version` (has `"nodeType"`), `bindings_v2.json` `version` (has `"resources"`), and eval-file `version` (has `"evaluatorRefs"`/`"evaluations"`) are NOT flagged.
+
+Deliberately NOT flagged: `"typeVersion": "x.y"` literals in node JSON examples — legitimate when paired with an adjacent registry-sourcing note, and too many true-illustrative cases to flag without noise.
+
+Add `<!-- version-check-skip -->` anywhere on a line to suppress it — for intentional references such as an anti-pattern example (`typeVersion: "1.0.0"` shown as the *wrong* value) or a fixed non-`.flow` schema version (eval-set files). Same marker convention as `check-uip-commands.sh`; for table rows, place it inside a cell.
+
+Pass specific files to scan only those:
+
+```bash
+bash .maintenance/check-versions.sh references/shared/file-format.md
+```
+
+## Running the full suite
+
+Run all nine checkers in one invocation:
+
+```bash
+bash .maintenance/check-all.sh
+```
+
+Continues running all checkers even when one fails — the goal is to surface every issue in a single pass. Exits non-zero if any checker fails.
+
+## When to run these checkers
+
+- Before committing changes that move files or rewrite link paths — `check-all.sh` covers everything in one pass
+- Before merging a PR that touches `references/`
+- After a refactoring phase
+- After deleting a doc — run `check-orphans.sh` to confirm nothing else became orphaned
+- Before adding a new capability — run `check-template.sh` against the new `CAPABILITY.md`
+- After adding a new plugin — run `check-plugin-pairs.sh` to confirm both `planning.md` and `impl.md` are present
+- After a `uip` CLI version bump — run `check-uip-commands.sh` to catch any commands that were renamed or removed, and `check-versions.sh` to catch docs that pinned a now-stale `.flow`/node version
+
+The checkers are not currently wired into CI or pre-commit hooks. They are kept as lightweight tooling in this directory so future maintainers can run them on demand.
+
+## Reachability convention
+
+Plugin docs (`references/author/plugins/<name>/{planning,impl}.md`) are linked from `author/CAPABILITY.md` via **folder links** (e.g., `[connector](references/plugins/connector/)`), not individual file links. Agents navigating to the folder discover both `planning.md` and `impl.md` there. This satisfies practical 2-hop reachability from `SKILL.md`.
+
+The depth checker (`check-depth.sh`) treats folder links as reachability for every `.md` file inside the folder, matching this agent-navigation model. A strict file-link-only reachability check would flag plugin docs as "unreachable" — that's a false negative.
+
+If a future change requires explicit file links (e.g., a task table needs a specific `impl.md` anchor), add the file link inline rather than relying on folder discovery.

package/skills/uipath-maestro-flow/.maintenance/check-all.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Run the full audit suite for this skill.
+# Usage: bash .maintenance/check-all.sh
+#
+# Runs each checker in turn and prints its summary line.
+# Exits non-zero if any checker fails. Continues running all checkers
+# even when one fails — the goal is to surface every issue in a single pass.
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT" || exit 1
+
+CHECKERS=(
+  "check-links.sh"
+  "check-link-text.sh"
+  "check-anchors.sh"
+  "check-depth.sh"
+  "check-template.sh"
+  "check-orphans.sh"
+  "check-plugin-pairs.sh"
+  "check-uip-commands.sh"
+  "check-versions.sh"
+)
+
+overall=0
+
+for checker in "${CHECKERS[@]}"; do
+  echo "=== $checker ==="
+  if ! /bin/bash ".maintenance/$checker"; then
+    overall=1
+  fi
+  echo ""
+done
+
+if [ "$overall" -eq 0 ]; then
+  echo "All checks passed."
+else
+  echo "One or more checks failed. See output above for details."
+fi
+
+exit "$overall"