diff --git a/skills/uipath-agents/references/coded/lifecycle/setup.md b/skills/uipath-agents/references/coded/lifecycle/setup.md index fa6549328..39c215606 100644 --- a/skills/uipath-agents/references/coded/lifecycle/setup.md +++ b/skills/uipath-agents/references/coded/lifecycle/setup.md @@ -90,6 +90,24 @@ Edit the scaffolded `main.py`'s `Input` / `Output` models and `async def main` t } ``` +**Key fields:** +- **`runtimeOptions.isConversational`** - Set `true` for conversational/chat agents +- **`packOptions`** - Control which files are included when packaging for deployment +- **`functions`** - Entrypoint mappings (format: `"file_path:function_name"`) + +### `packOptions.directoriesExcluded` for solution context + +When the agent project is registered in a solution and uploaded via `uip solution upload`, the agent directory is bundled into the solution archive. Set `directoriesExcluded` to keep Python build artifacts out of the archive: + +```json +"packOptions": { + "directoriesExcluded": [".venv", "__pycache__"], + "includeUvLock": true +} +``` + +`.venv/` is hundreds of MB of installed wheels and breaks uploads. `__pycache__/` is ephemeral bytecode. Both regenerate from `pyproject.toml` + `uv.lock` on the target side. Without these exclusions, `uip solution upload` produces an oversized archive that can be rejected by Studio Web. + - `isConversational: true` for chat-style agents. - `packOptions` controls `.nupkg` contents at deploy time. diff --git a/skills/uipath-coded-apps/SKILL.md b/skills/uipath-coded-apps/SKILL.md index a5bcffa77..f91dc75b6 100644 --- a/skills/uipath-coded-apps/SKILL.md +++ b/skills/uipath-coded-apps/SKILL.md @@ -26,6 +26,8 @@ Build, debug, and deploy UiPath Coded Web Applications and Coded Action Apps usi | **Coded Web App** | React/Vue/other frontend hosted on UiPath CDN | User-facing app accessed via a URL | | **Coded Action App** | React form wired to UiPath Action Center | Rendered inside human task reviews in Maestro/Agent workflows | +> **Coded apps are not registered in `.uipx` solutions.** They have no `project.uiproj` / `project.json`, so `uip solution project add` does not apply. A coded app can live alongside a solution directory but deploys independently via `uip codedapp publish` (and `uip codedapp deploy`), not via `uip solution pack` / `publish` / `deploy`. + ## Critical Rules 1. **Identify the app type before doing anything else.** Ask: *"Are you building a **Coded Web App** (custom frontend deployed to UiPath Cloud) or a **Coded Action App** (form for Action Center human task reviews)?"* The two paths diverge on scaffolding, redirect URI, and publish flag — do not guess. diff --git a/skills/uipath-maestro-case/references/case-commands.md b/skills/uipath-maestro-case/references/case-commands.md index cd8a3da34..4902b30c5 100644 --- a/skills/uipath-maestro-case/references/case-commands.md +++ b/skills/uipath-maestro-case/references/case-commands.md @@ -33,6 +33,22 @@ Creates `/` with `.uipx` inside. The `case` plugin's --- +## uip maestro case init + +Scaffold a basic Case project with the 5 boilerplate files and a starter `caseplan.json`. Use this for a blank case scaffold without an `sdd.md` (the SDD-driven JSON path writes the same files in a single plugin invocation — see [plugins/case/impl-json.md](plugins/case/impl-json.md)). + +```bash +cd && uip maestro case init +``` + +| Flag | Description | +|------|-------------| +| `` | **(required)** Project directory name. Created inside the current directory | + +Run from inside the solution directory so the resulting layout is `//`. Pair with `uip solution project add ./` to register it in `.uipx`. + +--- + ## uip solution project add Register a project with an existing solution. diff --git a/skills/uipath-planner/SKILL.md b/skills/uipath-planner/SKILL.md index ff27bb500..1d7b555ce 100644 --- a/skills/uipath-planner/SKILL.md +++ b/skills/uipath-planner/SKILL.md @@ -357,7 +357,7 @@ Fix issues before saving. Save as `YYYY-MM-DD-.md`: - **Project directory exists** (`project.json`, `flow_files/`, `.uipath/`, or `pyproject.toml`) → save to `docs/plans/` within the project. Create the directory if needed. -- **No project directory** → save to `~/Documents/UiPath/Plans/`. Create the directory if needed. +- **No project directory** → save to `./plans/` (relative to the current working directory). Create the directory if needed. ### 5e. Present the plan diff --git a/skills/uipath-platform/references/solution/develop-solution.md b/skills/uipath-platform/references/solution/develop-solution.md index b25598dda..04274c8fd 100644 --- a/skills/uipath-platform/references/solution/develop-solution.md +++ b/skills/uipath-platform/references/solution/develop-solution.md @@ -37,6 +37,8 @@ uip solution new "InvoiceAutomation" --output json Creates `InvoiceAutomation/InvoiceAutomation.uipx`. All projects must live inside this directory (or be imported into it). +> If the target folder already exists and is empty, `solution new` drops the `.uipx` inside without nesting or erroring. No need to pre-delete an empty target. + ## Step 2: Add Existing Projects Register a project that already lives inside the solution directory. @@ -48,7 +50,9 @@ uip solution project add ./InvoiceAutomation/Processor --output json uip solution project add ./InvoiceAutomation/Reporter ./InvoiceAutomation/InvoiceAutomation.uipx --output json ``` -The `.uipx` is auto-discovered by walking up from the project path if not specified. +The `.uipx` is auto-discovered by walking up from the project path if not specified. `Type` is auto-detected from `project.uiproj` / `project.json` — do not pass it. + +`add` is transactional: on success, both the `.uipx` entry and the matching `resources/solution_folder/{package,process}/.json` files are created together; on failure, nothing is mutated. ## Step 3: Import External Projects @@ -60,6 +64,8 @@ uip solution project import --source /path/to/ExternalProject --output json Unlike `add`, `import` copies source files into the solution directory first, then registers the copy. +> **Three names can diverge after `import`.** The destination folder name is the basename of `--source`. The `ProjectRelativePath` in `.uipx` matches the folder. The auto-generated package resource name is taken from the project metadata (e.g., `pyproject.toml [project].name` for Python coded agents) — which may differ from the folder. Rename the source directory to the intended project name **before** importing, or trace the relationship via the `projectKey` UUID inside the resource files. + ## Step 4: Remove a Project Unregister a project from the `.uipx` manifest. Does NOT delete files from disk. @@ -68,6 +74,8 @@ Unregister a project from the `.uipx` manifest. Does NOT delete files from disk. uip solution project remove ./InvoiceAutomation/OldProject --output json ``` +> **`project remove` leaves orphan package resources.** It removes the entry from `.uipx` Projects and deletes `resources/solution_folder/process//.json`, but leaves `resources/solution_folder/package/.json` behind. The orphan blocks any future `project add` of a project with the same name. **If you plan to re-add with the same name, manually delete `resources/solution_folder/package/.json` before re-adding.** + ## Step 5: List Projects Enumerate the projects registered in the local `.uipx` manifest. Reads only on-disk metadata — no backend call, so safe to use offline or in CI checks. @@ -125,6 +133,9 @@ uip solution resource refresh --solution-folder ./InvoiceAutomation --output jso ### What `refresh` actually does +> **`Result: Success` only means the CLI executed — not that the refresh service inside it succeeded.** The underlying service can fail (e.g., schema errors in `bindings_v2.json` logged to stderr as `ERROR [ResourceBuilder:BindingsMetadataSerializer] ...`) while the JSON still returns `Result: Success` with `Created: 0, Imported: 0, Skipped: 0`. Always inspect stderr for `ERROR` lines, and treat `Created==0 && Imported==0 && Skipped==0` while bindings exist on disk as a refresh failure. + +## Step 7: Upload to Studio Web 1. **Discover bindings** — reads `bindings_v2.json` from each project (solution root copy is also read for agent projects). 2. **Discover cloud GUIDs** — for agent projects, supplements bindings with `/resources//resource.json` files. These carry a `referenceKey` (GUID) for tools/escalations/contexts that the agent depends on; the GUID is the unambiguous cloud identity (binding names alone aren't unique across folders). 3. **Reconcile in-solution projects (`.uipx`)** — generates project artefact files (`process//`, `package/`) from SDK templates. Internal to the solution; no debug overwrite written. @@ -244,6 +255,46 @@ uip solution resource get --output json --- +## Field-tested gotchas + +Durable CLI behaviors that have caught agents in practice. Treat each as a hard rule. + +### Always verify state after every mutation + +`add`, `remove`, and `refresh` can succeed in stdout but fail (or partially fail) on disk. After every mutation: + +```bash +# 1. What does .uipx claim? +cat ./MySolution/MySolution.uipx | grep -A 2 ProjectRelativePath + +# 2. What resource files actually exist? +ls -1 ./MySolution/resources/solution_folder/package/ +ls -1 ./MySolution/resources/solution_folder/process/ + +# 3. The two sets MUST agree by name. If not, the solution is corrupt. +``` + +If `.uipx` and `resources/solution_folder/` disagree, follow the recovery procedure in the matching gotcha below. + +### `bindings.json` vs `bindings_v2.json` — different files, different schemas + +| File | Created by | Read by | +|---|---|---| +| `bindings.json` | `uipath init` (coded agent) | the agent at runtime | +| `bindings_v2.json` | `uip maestro flow new`, Maestro Case scaffold, Studio Web (mirrors agent bindings up to solution root) | `uip solution resource refresh` | + +Copying `bindings.json` → `bindings_v2.json` does **not** work — the schemas differ, and `resource refresh` will silently fail (see "false success" gotcha above). Naive hand-authoring or copy-paste from `bindings.json` produces the opaque error `TypeError: Cannot read properties of undefined (reading 'toLowerCase')`. When a project's tooling already manages `bindings_v2.json` (Flow / Case / agent solutions), edit through that product's commands rather than the file directly, then run `resource refresh` to reconcile. + +### `resource refresh` reports false success on schema errors + +See [Step 6](#step-6-refresh-resources). Always capture stderr and grep for `ERROR`. The `Warnings` field stays empty even when the underlying parser throws. + +### `project remove` leaves orphan package resources + +See [Step 4](#step-4-remove-a-project). After `remove`, manually delete `resources/solution_folder/package/.json` if you plan to re-add with the same name. To fully delete a project, also remove the project folder — `remove` does not touch source files. + +--- + ## Variations and Gotchas ### `add` vs `import` @@ -297,7 +348,7 @@ When `[solutionFile]` is omitted, the CLI walks up from the project path looking ### `--solution-folder` defaults to cwd -`resource list / refresh / get` default `--solution-folder` to the current working directory. Run them from inside the solution dir for the shortest invocation (`uip solution resource list`) or pass `--solution-folder ` explicitly. Older docs and examples that pass the path as a positional (`uip solution resource list ./InvoiceAutomation`) are out of date. +`resource list / refresh / get` default `--solution-folder` to the current working directory. Run them from inside the solution dir for the shortest invocation (`uip solution resource list`) or pass `--solution-folder ` explicitly. ### `resource get` for cross-folder inspection @@ -305,6 +356,20 @@ Because `get` falls back to RCS + FPS export when the key isn't local, it works --- +## Cheat sheet + +| Want to... | Command | Watch for | +|---|---|---| +| Create a fresh solution | `uip solution new ` | Accepts an existing empty directory; drops `.uipx` inside | +| Add a project already in the solution dir | `uip solution project add ./` | Transactional — `.uipx` and `resources/solution_folder/{package,process}/` agree on success | +| Pull in an external project | `uip solution project import --source ` | Rename source folder first to avoid 3-name divergence | +| Sync resource bindings | `uip solution resource refresh --solution-folder ` | **Check stderr for ERROR**; `Result: Success` with 0/0/0 counts is suspicious if `bindings_v2.json` exists | +| Remove a project | `uip solution project remove ./` | Manually delete `resources/.../package/.json` afterwards | +| List resources | `uip solution resource list --solution-folder --source local` | Good sanity check after any mutation | +| Pack | `uip solution pack ` | See [pack-and-deploy.md](pack-and-deploy.md) for full pack/publish/deploy flow | + +--- + ## Related - [Pack & Deploy](pack-and-deploy.md) -- Next step: pack, publish, and deploy the solution diff --git a/skills/uipath-platform/references/solution/pack-and-deploy.md b/skills/uipath-platform/references/solution/pack-and-deploy.md index 723a6afca..93f9e35a1 100644 --- a/skills/uipath-platform/references/solution/pack-and-deploy.md +++ b/skills/uipath-platform/references/solution/pack-and-deploy.md @@ -14,6 +14,7 @@ Pack a solution into a deployable package, publish to the feed, and deploy to Or - Authenticated (`uip login`) - Solution developed and ready to pack (see [develop-solution.md](develop-solution.md)) +- Solution state verified — `.uipx` and `resources/solution_folder/` agree on the project set (see [develop-solution.md - Always verify state after every mutation](develop-solution.md#always-verify-state-after-every-mutation)) ## Flow diff --git a/skills/uipath-platform/references/solution/solution.md b/skills/uipath-platform/references/solution/solution.md index 940125e06..048c9bebf 100644 --- a/skills/uipath-platform/references/solution/solution.md +++ b/skills/uipath-platform/references/solution/solution.md @@ -19,14 +19,29 @@ A UiPath Solution is a container that groups multiple automation projects (proce ``` MySolution/ -├── MySolution.uipx <- Solution manifest -├── ProjectA/ <- Automation project -│ ├── project.json / project.uiproj -│ └── *.cs / *.xaml -├── ProjectB/ -└── config.json <- Optional environment config +├── MySolution.uipx <- Manifest. Source of truth: project list + IDs + StudioMinVersion. +├── / +│ ├── project.uiproj OR project.json <- Required for add/import. Type auto-detected. +│ ├── bindings.json <- Agent runtime bindings. NOT scanned by refresh. +│ ├── bindings_v2.json <- Solution refresh reads this (if it exists). +│ └── ... +├── / <- A solution can host many projects side-by-side. +│ ├── project.uiproj OR project.json +│ ├── bindings_v2.json +│ └── ... +├── resources/ <- Auto-generated on add/import. NEVER hand-edit. +│ └── solution_folder/ +│ ├── package/.json <- Auto-created on add. NOT cleaned by `project remove`. +│ └── process/{process,flow}/.json <- Auto-created on add. Auto-cleaned on remove. +└── userProfile// <- Appears after first `project remove`. ``` +> `.uipx` and `resources/solution_folder/` must always agree on the set of projects. Diffing them is the fastest way to detect a corrupted state — see [develop-solution.md - Field-tested gotchas](develop-solution.md#field-tested-gotchas). +> +> The `.uipx` also carries a `StudioMinVersion` field (e.g. `2025.10.0`). If users hit a version-mismatch when opening the solution, that's the constraint to check. + +> **Coded apps are not registered in `.uipx`.** UiPath Coded Web Apps and Coded Action Apps have no `project.uiproj` / `project.json` — `uip solution project add` does not apply, and they are not packed by `uip solution pack`. They deploy independently via `uip codedapp publish` / `deploy`. A coded app directory can sit alongside a solution but is not part of its manifest. See [/uipath:uipath-coded-apps](/uipath:uipath-coded-apps). + --- ## Solution Lifecycle diff --git a/skills/uipath-rpa/references/coded-vs-xaml-guide.md b/skills/uipath-rpa/references/coded-vs-xaml-guide.md index 060581e6e..761650e80 100644 --- a/skills/uipath-rpa/references/coded-vs-xaml-guide.md +++ b/skills/uipath-rpa/references/coded-vs-xaml-guide.md @@ -2,6 +2,10 @@ When to use coded workflows (C#), XAML workflows (low-code), Coded Source Files, or InvokeCode — and how they interact in hybrid projects. +## Mode is a per-workflow choice, not a project setting + +`uip rpa create-project` produces a mode-agnostic project — both `project.uiproj` and `project.json` are scaffolded, and the project can host coded workflows (`.cs`), XAML workflows (`.xaml`), or both. The coded vs XAML decision happens when you add a workflow to the project (or when an existing project's dominant mode dictates the default — see step 1 below). + ## Decision Flowchart Follow top-down. Stop at the first match.