@uipath/skills 1.201.0-preview.606 → 1.201.0-preview.614

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/skills",
-  "version": "1.201.0-preview.606",
+  "version": "1.201.0-preview.614",
   "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-ixp/SKILL.md

@@ -27,6 +27,8 @@ This skill covers standalone IXP-project work. STOP and invoke the `uipath-maest
 
 Do not answer these from this skill. Re-activate `uipath-maestro-flow` and follow the commands it documents. This overrides Critical Rule 1.
 
+**Exception — an inbound handoff from `uipath-maestro-flow`:** when that skill delegates because the user supplied documents and no published extractor covers them, the IXP work belongs here even though the surrounding context is a flow build. The handoff supplies the target Orchestrator folder — that is the caller's contract, not a question to re-ask. Create the project from the documents, deploy a trained version to that folder ([Deployment Guide](references/deployment-guide.md) — including the exit when no folder arrived), report the deployment, and hand control back — do not wire or edit the flow from this skill.
+
 ## Critical Rules
 
 1. **Verify `uip ixp` syntax before running a command** — use a targeted lookup in [CLI Reference](references/cli-reference.md) and copy the exact subcommand and options; never guess. If the request is not covered, report that the skill has no documented CLI path rather than improvising. Do NOT use curl, call REST APIs directly, or explore source code. (Exception: defer flow/Maestro registry questions to `uipath-maestro-flow` — see *When NOT to Use This Skill* above.)
@@ -64,6 +66,7 @@ Do not answer these from this skill. Re-activate `uipath-maestro-flow` and follo
 2. To create a new project: follow [Project Setup Guide](references/project-setup-guide.md)
 3. To improve an existing project: follow [Improve Prompts Guide](references/improve-prompts-guide.md)
 4. To label documents on an existing project: follow [Label Documents Guide](references/label-documents-guide.md)
+5. To deploy a model so an automation can call it from an Orchestrator folder (Maestro Flow, other folder-resolving callers): `projects create` → `list-models` → `deployments create --folder-key`. Neither labelling nor `publish` is required — see [Deployment Guide](references/deployment-guide.md).
 
 If the user provides a taxonomy file, use `--skip-taxonomy` and `import-taxonomy` (Option B in the Project Setup guide).
 
@@ -79,7 +82,7 @@ If the user provides a taxonomy file, use `--skip-taxonomy` and `import-taxonomy
 | "Roll back to a previous version" / "Restore version N" | `uip ixp projects publish <project-name> --model-version <N> --output json` — re-publishes an earlier version. Get available versions from `uip ixp projects list-models <project-name> --output json`. |
 | "Unpublish a model" / "Take a model out of production" | `uip ixp projects unpublish <project-name> --model-version <N> --output json` — removes a version from the published set (it stays trained/listable). `--model-version` is required; find published versions via `list-models` (`Pinned: true`). To change which version is live, `publish` a different one instead. |
 | "Remove the live/staging tag" / "Untag a version" | `uip ixp projects untag <project-name> --tag <live\|staging> --output json` — removes the named tag (the version it pointed at stays published). **`untag` is the only way to remove a tag** — do NOT `unpublish` or re-`publish` to clear it (`unpublish` removes publication, not the tag; `publish` without `--tag` leaves the existing tag untouched). To switch `live`→`staging`, `publish --tag staging` instead. |
-| "Deploy this model to a folder" / "make it callable at runtime" / "deploy version N" | `uip ixp deployments create <project-name> --version <N> --folder-key <guid> [--title <title>] --output json` — deploys a trained version to an Orchestrator folder, making it callable by activity packs and Maestro Flow. `--version` (from `projects list-models`) and `--folder-key` (from `uip or folders list --output json`) are both **required**; `--title` defaults to the project name minus `-ixp`. **`create` never repoints an existing deployment** — a title already deployed in that folder on a different version is a `409`; use `upgrade` (next row). Read `DeploymentName` off the response: it is slugged and suffixed, never the title or the project name. See [cli-reference § Deployments](references/cli-reference.md#deployments). |
+| "Deploy this model to a folder" / "make it callable at runtime" / "deploy version N" | `uip ixp deployments create <project-name> --version <N> --folder-key <guid> [--title <title>] --output json` — deploys a trained version to an Orchestrator folder, making it callable by activity packs and Maestro Flow. `--version` (from `projects list-models`) and `--folder-key` (from `uip or folders list --output json`) are both **required** — when the user names a folder instead of giving its key, resolve the name through that same `folders list`; ask only when no folder was identified at all. `--title` defaults to the project name minus `-ixp`. **`create` never repoints an existing deployment** — a title already deployed in that folder on a different version is a `409`; use `upgrade` (next row). Read `DeploymentName` off the response: it is slugged and suffixed, never the title or the project name. See [cli-reference § Deployments](references/cli-reference.md#deployments). |
 | "Move a deployment to another version" / "upgrade the deployed model" / "that folder is serving an old version" | `uip ixp deployments upgrade <project-name> <deployment-name> --version <N> --folder-key <guid> --output json` — `<deployment-name>` is the `DeploymentName` from `deployments list`, **not** the title (a title there is a `404`). Changes which version **every runtime caller of that folder and name** gets, so confirm intent on a shared folder. **Not a rollback path** — the target version must still appear in `projects list-models`. See [cli-reference § create vs upgrade](references/cli-reference.md#create-vs-upgrade). |
 | "Where is this model deployed?" / "list deployments" / "which folder or version is live at runtime" | `uip ixp deployments list <project-name> --output json` — array of `DeploymentName`, `DeploymentTitle`, `ModelVersion`, `FolderKey`, `DeployedAt`; `[]` for a never-deployed project. **The only reliable source of `DeploymentName`** — run it before any `upgrade`. |
 | "Show metrics" / "What are the scores?" | `uip ixp projects get-metrics <project-name> --model-version <N> --output json` — **always name the version.** Without `--model-version` the CLI returns the **latest trained** version, which is not necessarily the published/live one; get the live version from `list-models` first (see "How is this project performing?"). |
@@ -112,6 +115,8 @@ If the user provides a taxonomy file, use `--skip-taxonomy` and `import-taxonomy
 | Field instructions conflict with label_def instructions | `fields update-prompts` only edits per-field instructions, NOT the parent label_def instructions | Before iterating, read the label_def `instructions` and update them with `groups update-prompts` if they contradict the per-field prompts. |
 | A confirmed line item now reads back as the first row, or the other rows' `Occurrence` numbers shifted | Expected: the read returns annotation↔prediction matched pairs first, so confirmed rows sort ahead of unconfirmed ones | Nothing to fix — values and page locations are unchanged. Re-run `get-predictions` before the next per-occurrence call and target the row by its values (Critical Rule 18). |
 | A second `--occurrence` call landed on the wrong row, or `unconfirm --occurrence N` no-ops | Indices came from a read taken *before* an earlier confirm renumbered the group | Re-read `get-predictions` between per-occurrence writes, or issue them as one `--updates` call. |
+| `deployments create` returns `409` | That title is already deployed in that folder on a different version — `create` only ever ADDS | Use `deployments upgrade <project-name> <deployment-name>` instead, taking `<deployment-name>` from `deployments list` (Critical Rule #20). |
+| `deployments upgrade` returns `404` | A `DeploymentTitle` was passed where `DeploymentName` is expected — the name is slugged and suffixed (`invoices` → `invoices-08963f00-ixp`), so it cannot be derived from the title | Run `deployments list <project-name> --output json` and pass its `DeploymentName` verbatim. |
 
 ## Unsupported Capabilities
 
@@ -121,7 +126,11 @@ These requests fall outside the skill. Recognise the request, reply with the sta
 |--------------|-------------------|
 | "Create a model" / "create a project" | **Documents or a taxonomy supplied →** use the [Project Setup Guide](references/project-setup-guide.md) (this skill creates the project from them). **Otherwise →** "I work on existing IXP projects rather than creating them from scratch. Create one in-product: https://docs.uipath.com/ixp/automation-cloud/latest/user-guide/managing-projects — then I can label, review, and improve it." |
 | "Upload these files" / "add documents" | **Project named / already in context →** supported; upload it (see the "Upload a document" row in Task Navigation). **Otherwise →** "Name an existing project and I'll upload it — or upload in-product (e.g. for a new project): https://docs.uipath.com/ixp/automation-cloud/latest/user-guide/building-and-deploying-models." |
+<<<<<<< HEAD
 | "Deploy this model" / "push to staging / production / folder / environment / tenant" | **Folder deployment is supported** — deploy with `uip ixp deployments create` (see the "Deploy this model to a folder" row in [Task Navigation](#task-navigation)). If the user NAMES a folder rather than giving its key, resolve the name with `uip or folders list --output json` — ask only when no folder was identified at all. For anything that is not an Orchestrator folder: "I deploy model versions to Orchestrator **folders**. Binding to environments or another tenant is a product-side flow: https://docs.uipath.com/ixp/automation-cloud/latest/user-guide/building-and-deploying-models." Note `projects publish --tag staging\|live` moves the tag the DU framework (and DU activities calling through it) resolve — for those consumers that IS the staging/live switch; it creates no folder deployment. |
+=======
+| "Push to an environment / another tenant" / "deploy to staging or production" | **Names an Orchestrator folder (a folder literally called `Production`) →** supported; use the "Deploy this model to a folder" row in [Task Navigation](#task-navigation). **Otherwise →** "IXP has no environment or cross-tenant deploy target — a deployment is a (folder, version) pair inside one tenant." Note `projects publish --tag staging\|live` tags a version *inside* the project — it deploys nothing. |
+>>>>>>> 6788b15df (docs(uipath-ixp): stop documenting folder deploys as unsupported (#2794))
 | "Give X access" / "share this project" / "change roles or permissions" | "Access, roles, and permissions are managed in-product, not through this skill: https://docs.uipath.com/ixp/automation-cloud/latest/overview/managing-access." |
 | "Use this model in my automation / workflow / agent" / "call the extractor from a process" | "Consuming a published model inside an automation is an authoring task outside this skill. See https://docs.uipath.com/ixp/automation-cloud/latest/user-guide/building-and-consuming-a-workflow." |
 | "Mine these emails / communications" / "set up Communications Mining" | "Communications Mining is a separate IXP capability this skill doesn't cover (this skill is document extraction). See https://docs.uipath.com/ixp/automation-cloud/latest/cm-user-guide/introduction-to-uipath-communication-mining." |

package/skills/uipath-ixp/references/cli-reference.md

@@ -231,6 +231,12 @@ Distinct fields. Confusing them is the failure mode this command split exists to
 
 Required on both `create` and `upgrade`; passed in the body, never as a path. The same name can be deployed in several folders, so the folder is part of the deployment identity — there is no tenant-level or default-folder deploy. Get keys from `uip or folders list --output json`. There is no `--folder-path` form, and the key format is not validated client-side (the backend owns what a valid key is), so a malformed key fails server-side.
 
+When filtering the folder list, pass an explicit `--limit` — `--output-filter` without one is rejected on current CLIs (older builds silently filter a single page):
+
+```bash
+uip or folders list --limit 500 --output json --output-filter "[?Path=='Shared'].Key"
+```
+
 Omitting either required option fails locally with exit `3` / `Result: ValidationError` before any auth or backend call. `--version 0` is valid — versions are 0-based.
 
 ### Deployment errors

package/skills/uipath-ixp/references/deployment-guide.md

@@ -0,0 +1,24 @@
+# Deployment Guide
+
+The final step of a project's lifecycle: making a trained model version available beyond the labelling loop. Two distinct targets — pick from what the user needs, they are not interchangeable:
+
+| Target | Command | What it gives you |
+| --- | --- | --- |
+| **Project** ("publish") | `uip ixp projects publish <project-name> --output json` | Marks the version published and, with `--tag`, moves the `live`/`staging` tag — the tagged version is what the DU framework, and DU activities that call through it, resolve. Also the rollback mechanism. |
+| **Orchestrator folder** | `uip ixp deployments create <project-name> --version <N> --folder-key <guid> --output json` | Makes the model callable by folder-resolving runtime callers — Maestro Flow among them. Neither labelling nor `publish` is required first. |
+
+Runtime callers split by how they address the model: folder-resolving callers (Maestro Flow nodes; anything reading folder deployments) see only the **folder** target, and tag-resolving callers (the DU framework API and its activities) see only the **project** target's tags. Neither substitutes for the other — pick per consumer, or do both. See the "Publish the model" row in [SKILL.md Task Navigation](../SKILL.md#task-navigation) for tags, rollback, and unpublish.
+
+## Deploy to a folder
+
+Ask which folder when none was identified — the folder decides which folder-resolving callers see the model. Running non-interactively (CI/headless — no user available to answer) with no folder identified by the request or an inbound handoff: stop and report the missing folder key. Never guess one, and never create a folder to fill the gap.
+
+```bash
+uip ixp projects list-models <project-name> --output json
+uip ixp deployments create <project-name> --version <Version from list-models> \
+  --folder-key <guid> --output json
+```
+
+Read `--version` from `list-models` immediately before deploying: the trained version advances while the project trains, and right after `projects create` the list can be empty for ~30s until the first version trains (deploy fails; wait and retry once).
+
+Flags, `--folder-key` resolution, and moving an existing deployment to a newer version: [CLI Reference § Deployments](cli-reference.md#deployments) and [§ create vs upgrade](cli-reference.md#create-vs-upgrade).

package/skills/uipath-ixp/references/project-setup-guide.md

@@ -1,6 +1,6 @@
 # Project Setup Guide
 
-Complete workflow for creating a **new** IXP project, labelling all documents, and getting initial metrics. Run all steps end-to-end automatically.
+Complete workflow for creating a **new** IXP project, labelling all documents, and getting initial metrics. Run all steps end-to-end automatically. Deployment is a separate, optional final step — [Deployment Guide](deployment-guide.md).
 
 > **Wrong page if the project already exists.** Use `uip ixp documents upload <project-name> <file>` — see [CLI Reference § Uploading documents](cli-reference.md#uploading-documents-to-an-existing-project).
 
@@ -87,4 +87,11 @@ Skip this step if the user already provided a meaningful name in Step 1.
 
 ## Step 4 — Label All Documents
 
-Follow the [Label Documents Guide](label-documents-guide.md) to label every document in the project.
+**Default:** follow the [Label Documents Guide](label-documents-guide.md) to label every document in the project.
+
+Labelling is optional — it produces the **project score** (`get-metrics` reports nothing until documents are confirmed) and is not required for a callable model (a trained version appears on its own within seconds of `projects create`). Skip it only when:
+
+- **The model unblocks a larger build in this session** — the deliverable is something else (a flow, an automation) waiting on a callable model, and no score, metrics, or accuracy target was named. Deploy per the [Deployment Guide](deployment-guide.md) and resume the build. Canonical case: the inbound `uipath-maestro-flow` handoff (see *When NOT to Use This Skill* in [SKILL.md](../SKILL.md)).
+- **The user opts out** — says to skip labelling, or that somebody else will handle labelling. Stop after Step 3 and hand over the project name; labelling can happen later, in-product or via the [Label Documents Guide](label-documents-guide.md).
+
+Skipping is never silent: state that the model is unscored and that labelling is the fix if fields come back wrong.

package/skills/uipath-maestro-flow/SKILL.md

@@ -80,7 +80,7 @@ These rules apply across all three capabilities. Each capability index adds capa
 
    **Two tells that you skipped the search and took the brand-name shortcut — both are build defects, not valid manual-mode HTTP:** (a) you authored a manual-mode `core.action.http.v2` node whose `url` targets a well-known SaaS API domain that has a connector (`slack.com/api/*`, `api.github.com`, `*.salesforce.com`, `graph.microsoft.com`, …); (b) you declared an `in` variable to hold that service's API token or secret (e.g. a `slackToken` holding an `xoxb-…` bot token, an `apiKey`, a bearer token). A connector-backed flow never carries the raw credential — the IS connection does. If you find yourself writing either, **stop**: run `uip maestro flow registry search "<service>"` and `uip is connections list "<connector-key>" --all-folders`, then use the connector activity (or connector-mode HTTP: `authentication:"connector"` + `targetConnector` + a bound `connectionId`/`folderKey`). Manual mode is legitimate only for a service the search proves has no connector.
 
-4. **Never invoke other skills automatically** — when a flow needs an RPA process, agent, or app, identify the gap and provide handoff instructions. Let the user decide when to switch skills.
+4. **Never invoke other skills automatically** — when a flow needs an RPA process, agent, or app, identify the gap and provide handoff instructions. Let the user decide when to switch skills. **One exception — IXP extraction with documents in hand:** when the flow needs document extraction, the user supplied sample documents, and `registry search "uipath.ixp"` shows no extractor covering them, invoke the `uipath-ixp` skill to build and deploy the model, then resume the flow ([plugins/ixp/impl.md — If the Model Does Not Exist Yet](references/author/references/plugins/ixp/impl.md#if-the-model-does-not-exist-yet)). Resolve the target Orchestrator folder for the deployment before invoking — from the user's request when it names one, otherwise per rule #5 (its non-interactive fallback applies) — and pass it in the handoff; the sibling stops rather than guess a folder. There is deliberately no separate consent gate on the tenant writes this creates: the project and folder deployment fulfil the extraction request itself, and the one consequential choice — where the deployment lands (deployments have no delete API) — is exactly the folder decision rule #5 just routed. Do NOT drive `uip ixp` project or deployment commands from this skill instead of invoking it — the sibling's guides carry guardrails this skill does not. If `uipath-ixp` is unavailable in the session, fall back to `core.logic.mock` plus an Open Questions entry, exactly as when no documents were supplied.
 5. **Always present user questions as a dropdown with a "Something else" escape hatch** — Whenever this skill needs a decision from the user (which solution to use, publish vs debug vs deploy, which connector to pick, which trigger type, which resource to bind, etc.), ask the user a question with the enumerated choices as options AND include **"Something else"** as the last option so the user can supply free-form string input. Never ask open-ended questions in chat when a finite set of sensible defaults exists. If the user picks "Something else", parse their string answer and continue. No structured-question facility on the harness → ask in chat as a numbered list with "Something else" last. Running non-interactively (CI/headless — no user available to answer) → take the pre-selected/recommended option, proceed, and record the decision prominently in the final report; if no option is marked recommended, stop and report the open decision instead of guessing. Exception: consent gates (`flow debug`, destructive operations) are never auto-answered — in non-interactive mode, stop and report the blocked step instead. These fallbacks define "ask the user" / "confirm with the user" wherever this skill's references require it.
 6. **Discover the target solution before you scaffold — a Flow project MUST live inside a solution** (layout is **always** double-nested: `<Solution>/<Project>/<Project>.flow`). Before any `uip solution init` or `uip maestro flow init` for a NEW Flow, run `find . -maxdepth 2 -type f -name '*.uipx' -print`. **If it lists one or more solutions, STOP** — do not scaffold, initialize, delete, or repair anything. Ask which solution to use (dropdown per rule #5): one option per discovered solution, **"Create a new solution"**, then **"Something else"** last; continue only after the answer. This holds even when the user says they want a new solution or supplies only a Flow-project name — never silently adopt an existing solution, and when they pick "Create a new solution", **ask for its name** rather than defaulting to the Flow-project name. **If none are found, create one automatically** (default its name to the Flow name unless the user specifies otherwise). **Prefer solution-first** — it works on every CLI version and lets you set the two names independently: `uip solution init "<SolutionName>" --output json && cd "<SolutionName>" && uip maestro flow init "<FlowName>" --output json` → `<SolutionName>/<FlowName>/<FlowName>.flow`, with the project auto-registered in the parent `.uipx` (`Data.SolutionRegistration.Status: "Registered"`); `<SolutionName>` and `<FlowName>` are independent and need not match. On a current CLI, running `uip maestro flow init "<FlowName>"` **outside** any solution instead auto-scaffolds `<FlowName>Solution/<FlowName>Solution.uipx` with the project at `<FlowName>Solution/<FlowName>/` (response carries `Data.AutoCreatedSolution`) — convenient, but it forces the `<FlowName>Solution` name, so use it only when the solution name doesn't matter. `--skip-solution-registration` opts out of both auto-scaffold and registration, leaving a bare single-nested `<Flow>/<Flow>.flow` that fails Studio Web upload and packaging. If a **non-empty** directory already exists at the path you typed, init warns and leaves it untouched. **Never drop the `cd` between `solution init` and `flow init`** — `flow init` in the old directory auto-scaffolds a duplicate `<FlowName>Solution/`. One `project.uiproj` at finish; delete strays. See [author/greenfield.md](references/author/references/greenfield.md) Step 2.
 7. **Narrate progress in plain English only when the user has opted into verbosity — silent by default.** Engage when the user asks for narration / progress ("walk me through it", "show your steps", "verbose", "be detailed") or signals a verbosity preference; otherwise work quietly and surface only decisions, failures, consent gates, and the final result. When engaged: one short line per logical step, in user terms ("checking your tenant login", "adding the Slack node and wiring its inputs", "running validate") — no flag-level or JSON-structure-level detail, applied uniformly across `uip` CLI calls, shell builtins, file edits, and bulk searches. See [shared/ux-narration-and-todos.md](references/shared/ux-narration-and-todos.md) §When to engage.

package/skills/uipath-maestro-flow/references/author/references/plugins/ixp/impl.md

@@ -23,7 +23,7 @@ uip maestro flow registry pull --force
 uip maestro flow registry search "uipath.ixp" --output json
 ```
 
-Requires `uip login`. Only published IxP models from your tenant appear. Example returned `nodeType`: `uipath.ixp.idp-benchmark-invoices-c735405a-ixp.shared-idp-benchmark-invoices-c735405a-ixp` (for an `idp-benchmark---invoices-c735405a-ixp` model in the `Shared` folder).
+Requires `uip login`. Only models with a folder deployment on your tenant appear — publishing alone does not surface a model here. Example returned `nodeType`: `uipath.ixp.idp-benchmark-invoices-c735405a-ixp.shared-idp-benchmark-invoices-c735405a-ixp` (for an `idp-benchmark---invoices-c735405a-ixp` model in the `Shared` folder).
 
 ### Response shape
 
@@ -48,9 +48,9 @@ Requires `uip login`. Only published IxP models from your tenant appear. Example
 
 Read entries as `raw["Data"][i]["NodeType"]` (not `raw["Data"]["Nodes"]`).
 
-### If `Data` is empty → stop and use a mock
+### If `Data` is empty → stop searching, then branch on documents
 
-If `uip maestro flow registry search "uipath.ixp"` returns `Data: []`, **no IxP extraction model is published on this tenant**. Add a `core.logic.mock` placeholder node (see [If the Model Does Not Exist Yet](#if-the-model-does-not-exist-yet)) and surface the missing model in **Open Questions**.
+If `uip maestro flow registry search "uipath.ixp"` returns `Data: []`, **no IxP extraction model is published on this tenant**. Stop searching (see below) — but do NOT assume a mock. What to do next depends on whether the user supplied documents: with documents the extractor can be built, without them a `core.logic.mock` placeholder plus an **Open Questions** entry is the answer. Follow [If the Model Does Not Exist Yet](#if-the-model-does-not-exist-yet) for both branches.
 
 **Stop searching.** Do not run any of these as a fallback:
 
@@ -58,9 +58,9 @@ If `uip maestro flow registry search "uipath.ixp"` returns `Data: []`, **no IxP
 - `registry list` followed by client-side filtering for "ixp" / "extraction" — the strict `uipath.ixp` search is already authoritative.
 - Variant-prefix searches: `registry search "uipath.agent.resource.tool.ixp"`, `"core.ixp"`, etc.
 
-The fallback is `core.logic.mock`, full stop. At most run one broader `registry search "ixp"` to confirm there are no `uipath.ixp.*` hits hidden by stricter prefix matching, then mock.
+None of those will find an extraction node. At most run one broader `registry search "ixp"` to confirm there are no `uipath.ixp.*` hits hidden by stricter prefix matching, then mock.
 
-> A `uipath.agent.resource.tool.ixp.*` hit on the broader `"ixp"` search is the *agent-tool* variant — not a flow extraction node. Treat it as "no extraction model published" and fall back to mock.
+> A `uipath.agent.resource.tool.ixp.*` hit on the broader `"ixp"` search is the *agent-tool* variant — not a flow extraction node. Treat it as "no extraction model published" and branch on documents as above.
 
 ## Listing Published Models
 
@@ -345,13 +345,26 @@ If the command fails (no matching project, login expired, deployment not yet pub
 **The extraction step must ALWAYS land a node — never drop it because configuration is incomplete.** A greenfield/exploration turn, an unwired upstream, a "you don't need a working flow" instruction, or an unconfirmed model are NOT reasons to skip it. The common failure is landing the steps around extraction while the extraction node itself goes missing. Author it before the trigger and connector nodes — connector configuration branches open-endedly, and this is the node the request is about.
 
 - **Model published** (`registry search "uipath.ixp"` returns entries) → land the real `uipath.ixp.*` node. When you can't finish configuring it this turn, still build the instance from `registry get` (copy `inputs.model` and the fixed `outputs` literal — no user input needed), set `inputs.fileRef` to a placeholder expression, and defer the model choice, `fileRef` source, and taxonomy to **Open Questions**. Do NOT downgrade to `core.logic.mock` — a published model exists, so land the real node.
-- **No model published** (`Data: []`) → land a `core.logic.mock` placeholder per [If the Model Does Not Exist Yet](#if-the-model-does-not-exist-yet).
+- **No model published** (`Data: []`) → branch on whether the user supplied documents, per [If the Model Does Not Exist Yet](#if-the-model-does-not-exist-yet).
 
 ## If the Model Does Not Exist Yet
 
 Trigger: `uip maestro flow registry search "uipath.ixp"` returns `Data: []`, OR the only matches are `uipath.agent.resource.tool.ixp.*` (agent-tool variant — not a flow extraction node).
 
-Action: insert a `core.logic.mock` placeholder via Direct JSON edit and stop. Do not iterate on registry searches.
+**First: did the user supply documents?**
+
+- **Yes** — the extractor can be built, so do not mock. **Invoke the `uipath-ixp` Skill and hand it the documents, the extraction goal, and the target Orchestrator folder — do not drive `uip ixp` commands from this skill's context.** Resolve the folder before invoking: the user's request when it names one, otherwise SKILL.md rule #5 (whose non-interactive fallback applies) — the sibling skill stops rather than guess one. Building the extractor is its domain: project creation, model configuration, the labelling decision, and deployment each carry guardrails that live in that skill's guides, and improvising the commands from here skips all of them. The outcome to expect back is a **folder deployment**, which is what makes the model appear in this registry. Then come back and finish the flow:
+
+  ```bash
+  uip maestro flow registry pull --force
+  uip maestro flow registry search "uipath.ixp" --output json
+  ```
+
+  How fast the node reaches the flow registry after `deployments create` is **environment weather, not a constant**: measured at ~25 seconds on a healthy environment, and from immediate one day to minutes-or-hours three days later on another — with publish and labelling state making no difference. So: `pull --force` + search once; if it is missing, retry every ~30s for at most **3 minutes**, then STOP polling. A slow-indexing environment can take hours, and burning the session on it helps nobody — land the flow with the mock procedure below, and record the deployment's `DeploymentName` **inside the artifact, not only in your reply**: put it in the mock node's `display.label` parenthetical — e.g. `Extract Licence Fields (mock — swap for falconry-licence-extraction-b1cc08a0-ixp once the registry serves it)` — and repeat it in the **Open Questions** entry. A name that lives only in the conversation is gone when the next session opens the flow; the label makes the swap mechanical from the file alone. *Runtime* resolution of a brand-new deployment additionally lags by roughly 15s (see [uipath-ixp cli-reference § Deployment errors](../../../../../../uipath-ixp/references/cli-reference.md#deployment-errors)), which matters when debugging a flow straight after deploying, not when authoring one. Build the node from `registry get` as usual ([Build procedure](#build-procedure--copy-from-registry-get-do-not-construct-from-memory)); its `inputs.modelName` is the deployment's name, not the project's. If `uipath-ixp` is unavailable in this session, fall back to the mock path below and surface the project-creation step in **Open Questions**.
+
+- **No** — nothing to train on; do not iterate on registry searches. Follow the mock procedure below.
+
+Mock procedure:
 
 1. Fetch the definition: `uip maestro flow registry get core.logic.mock --output json`. Copy `Data.Node` verbatim into `definitions[]` if not already present.
 2. Add a node to `nodes[]` with a stable id (e.g. `extractContractFieldsMock`), `type: "core.logic.mock"`, and a `display.label` whose **leading phrase** describes the work in the user's domain (e.g. `Extract Contract Fields`) rather than the underlying technology (`IxP Extraction`, `Run IxP`). The parenthetical may name IxP — e.g. `Extract Contract Fields (mock — IxP model not yet published)`.
@@ -360,7 +373,7 @@ Action: insert a `core.logic.mock` placeholder via Direct JSON edit and stop. Do
 5. **Wire downstream consumers against the mock with `$vars` references, not static values.** Scripts, decisions, and end-node mappings that follow the mock MUST reference `$vars.{mockNodeId}.output` (the mock's only port) instead of hard-coded returns. Example: a script that summarises the (future) extraction writes `return { vendor: $vars.extractInvoiceFieldsMock.output.vendorName };`, not `return { ok: "OK" };`. This keeps the **node-graph** swap-ready — node IDs, edge shapes, and the `output` port name stay intact when the mock is replaced. **Field-access paths inside downstream scripts WILL need rewriting at swap time** — the real IxP `output` is shaped as `{ ExtractionResult: { ResultsDocument: { Fields: [...] } } }` (see [Accessing Output](#accessing-output)), so flat-field accessors against the mock become structured `Fields.find(f => f.FieldName === '<name>')?.Values?.[0]` lookups against the real node. Surface the post-swap rewrite as a follow-up under **Open Questions**.
 6. Run `uip maestro flow validate <ProjectName>.flow --output json` once after all edits complete.
 
-Surface the missing model in the **Open Questions** section of the architectural plan: the user must train and publish the IxP extraction model via the IxP product before the flow can run. After publishing, follow the [mock replacement procedure](../../editing-operations-json.md#replace-a-mock-with-a-real-resource-node) to swap the mock for the real IxP node.
+Surface the missing model in the **Open Questions** section of the architectural plan: the user must train the IxP extraction model and deploy it to an Orchestrator folder before the flow can run — the flow registry lists folder deployments only. After deploying, follow the [mock replacement procedure](../../editing-operations-json.md#replace-a-mock-with-a-real-resource-node) to swap the mock for the real IxP node.
 
 ## Classifier Variant
 
@@ -370,7 +383,7 @@ IxP also exposes classifier models (type `Classifier`) that label documents rath
 
 | Error | Cause | Fix |
 | --- | --- | --- |
-| Node type not found in registry | Model not published, or registry cache stale | Run `uip login` then `uip maestro flow registry pull --force` |
+| Node type not found in registry | Model not folder-deployed, or registry cache stale | Run `uip login` then `uip maestro flow registry pull --force` |
 | `model.context` rejected by runtime | `folderKey` or `modelName` missing from `inputs` (the context array is built from these) | Confirm `inputs.modelName` and `inputs.folderKey` are populated. |
 | Empty `$vars.{nodeId}.output` | Model's taxonomy doesn't match the document, or extraction silently returned no fields | Inspect the raw API response via `$vars.{nodeId}.error` first; if no error, run the extraction against the same document on the IxP product UI to compare |
 | `fileRef` not resolving | Expression references an upstream variable that isn't wired, or the upstream node didn't produce a file output | Verify the upstream node exports a file reference and that the `=js:$vars.{upstreamId}.output.<field>` expression matches |

package/skills/uipath-maestro-flow/references/author/references/plugins/ixp/planning.md

@@ -20,7 +20,7 @@ Use an IxP node when the flow needs to extract **named fields** (invoice totals,
 | --- | --- |
 | Source is a PDF, scanned document, photo, or email attachment | Source is already structured (CSV, JSON, database row) — use [Script](../script/planning.md) |
 | Fields have variable layout across documents (e.g. invoices from many vendors) | Layout is fixed and parseable by regex/XPath — use [Script](../script/planning.md) |
-| A trained IxP model exists for this document type | No model exists — flag as a prerequisite and use `core.logic.mock` until the model is trained |
+| A trained IxP model exists for this document type | No model exists AND no documents were supplied — flag as a prerequisite and use `core.logic.mock`. With documents in hand the model can be built instead (see [No published model](#no-published-model-branch-on-documents)) |
 | Need field-level extraction with per-field confidence scores for downstream HITL review | Need free-form summarization, classification, or reasoning over text — use [Agent](../agent/planning.md) |
 
 ### Anti-Pattern
@@ -29,7 +29,7 @@ Don't use IxP as a generic OCR. IxP is field-oriented — it extracts named fiel
 
 ### When NOT to Use
 
-- **Model not yet trained or published** — use `core.logic.mock` and surface in Open Questions that a model must be trained on the IxP product before the flow can run.
+- **Model not yet trained or published** — branch on documents: see [No published model](#no-published-model-branch-on-documents).
 - **Structured input (CSV/JSON/DB row)** — use [Script](../script/planning.md) or [Decision](../decision/planning.md). IxP adds latency and model-inference cost for no gain.
 - **Free-form summarization, classification, or reasoning** — use [Agent](../agent/planning.md). An IxP model trained for field extraction will not produce useful output for those tasks.
 - **Manual external API call** — use [Connector](../connector/planning.md) or [HTTP](../http/planning.md).
@@ -38,7 +38,7 @@ Don't use IxP as a generic OCR. IxP is field-oriented — it extracts named fiel
 
 - `uip login` — IxP nodes only appear in the registry after authentication.
 - `uip maestro flow registry pull --force` must be run to cache IxP model node types locally.
-- A trained, published IxP extraction model must exist on the tenant. If none exists, surface it in the **Open Questions** section of the architectural plan so the user can train one while reviewing.
+- A trained IxP model must be **deployed to an Orchestrator folder** — the flow registry lists folder deployments only. Create one via the `uipath-ixp` skill. If none exists, see [No published model](#no-published-model-branch-on-documents).
 
 ## Ports
 
@@ -58,11 +58,16 @@ uip maestro flow registry pull --force
 uip maestro flow registry search "uipath.ixp" --output json
 ```
 
-Requires `uip login`. Only published IxP models from your tenant appear. The returned node type uses a **two-segment tail** (`{modelName}.{fullyQualifiedName}`), unlike `uipath.core.*` siblings which use a single-segment tail. Both tail segments are sanitized: lowercase, then runs of any character outside `[a-z0-9]` → single `-`. So an FQN of `Shared/invoice-model` lands as `shared-invoice-model`. See [impl.md](impl.md) for the full rule and worked examples.
+Requires `uip login`. Only models with a folder deployment on your tenant appear — publishing alone does not surface a model here. The returned node type uses a **two-segment tail** (`{modelName}.{fullyQualifiedName}`), unlike `uipath.core.*` siblings which use a single-segment tail. Both tail segments are sanitized: lowercase, then runs of any character outside `[a-z0-9]` → single `-`. So an FQN of `Shared/invoice-model` lands as `shared-invoice-model`. See [impl.md](impl.md) for the full rule and worked examples.
 
-### If `Data: []` → plan for a mock + Open Question
+### No published model: branch on documents
 
-If the search returns no `uipath.ixp.*` nodes, no IxP extraction model is published on this tenant. Plan the architecture around a `core.logic.mock` placeholder for the extraction step, and surface the missing model in **Open Questions** so the user can train and publish it. Do not iterate on registry searches — the mock is the planning answer until the model exists. See [impl.md — If the Model Does Not Exist Yet](impl.md#if-the-model-does-not-exist-yet) for the implementer-side procedure.
+No `uipath.ixp.*` nodes means no IxP extraction model is published on this tenant. Either way, **stop searching** — do not iterate on registry searches.
+
+| Situation | Plan |
+| --- | --- |
+| **Documents supplied** (files in the workspace, an attached batch, a named folder of samples) | The extractor can be built. Plan a real `uipath.ixp.*` node and note that the project must be created and folder-deployed first — that work belongs to the `uipath-ixp` skill — invoke it rather than running `uip ixp` commands from here; it creates the project and folder-deploys it, which is what puts the model in this registry. See [impl.md — If the Model Does Not Exist Yet](impl.md#if-the-model-does-not-exist-yet). |
+| **No documents** | Plan a `core.logic.mock` placeholder for the extraction step and surface the missing model in **Open Questions** so the user can train one and deploy it to a folder. The mock is the planning answer until documents or a model exist. |
 
 ## Listing Available Models / Runtime Projects
 
@@ -87,4 +92,4 @@ If `Data: []`, answer directly that no IxP models are published on the tenant. D
 In the architectural plan:
 
 - If the model exists: note as `resource: <model-name> (ixp-extraction)` with the intended document type (e.g. "resource: vendor-invoices (ixp-extraction) — extract invoice header + line items")
-- If it does not exist: note as `[CREATE NEW] <description>` and flag in Open Questions that an IxP model must be trained before the flow can run
+- If it does not exist: note as `[CREATE NEW] <description>`. With documents supplied, the model can be built as part of this work (see [No published model](#no-published-model-branch-on-documents)); without them, flag in Open Questions that one must be trained before the flow can run

package/version-manifest.json

@@ -1,5 +1,5 @@
 {
   "schemaVersion": 2,
-  "skillsVersion": "1.201.0-preview.606",
+  "skillsVersion": "1.201.0-preview.614",
   "targetCli": "^1.201.0"
 }