UiPath · gabrielavaduva · May 5, 2026 · Apr 30, 2026 · May 4, 2026 · May 4, 2026
@@ -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.
 

@@ -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.

@@ -33,6 +33,22 @@ Creates `<SolutionName>/` with `<SolutionName>.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 <SolutionDir> && uip maestro case init <ProjectName>
+```
+
+| Flag | Description |
+|------|-------------|
+| `<ProjectName>` | **(required)** Project directory name. Created inside the current directory |
+
+Run from inside the solution directory so the resulting layout is `<SolutionDir>/<ProjectName>/`. Pair with `uip solution project add ./<ProjectName>` to register it in `.uipx`.
+
+---
+
 ## uip solution project add
 
 Register a project with an existing solution.

@@ -357,7 +357,7 @@ Fix issues before saving.
 Save as `YYYY-MM-DD-<feature-name>.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
 

@@ -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}/<name>.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/<kind>/<name>.json`, but leaves `resources/solution_folder/package/<name>.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/<name>.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 `<project>/resources/<X>/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/<type>/`, `package/`) from SDK templates. Internal to the solution; no debug overwrite written.
@@ -244,6 +255,46 @@ uip solution resource get <resource-key> --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/<name>.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,14 +348,28 @@ 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 <path>` 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 <path>` explicitly.
 
 ### `resource get` for cross-folder inspection
 
 Because `get` falls back to RCS + FPS export when the key isn't local, it works as a quick way to fetch the full server spec for any resource your tenant exposes — even ones that aren't yet bound to this solution. Pair with `solution resource list --source remote` to discover keys.
 
 ---
 
+## Cheat sheet
+
+| Want to... | Command | Watch for |
+|---|---|---|
+| Create a fresh solution | `uip solution new <name>` | Accepts an existing empty directory; drops `.uipx` inside |
+| Add a project already in the solution dir | `uip solution project add ./<dir>` | Transactional — `.uipx` and `resources/solution_folder/{package,process}/` agree on success |
+| Pull in an external project | `uip solution project import --source <path>` | Rename source folder first to avoid 3-name divergence |
+| Sync resource bindings | `uip solution resource refresh --solution-folder <solution-dir>` | **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 ./<dir>` | Manually delete `resources/.../package/<name>.json` afterwards |
+| List resources | `uip solution resource list --solution-folder <solution-dir> --source local` | Good sanity check after any mutation |
+| Pack | `uip solution pack <solution-dir> <output-dir>` | 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

@@ -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
 

@@ -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.
+├── <ProjectName>/
+│   ├── 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).
+│   └── ...
+├── <AnotherProjectName>/                 <- 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/<name>.json           <- Auto-created on add. NOT cleaned by `project remove`.
+│       └── process/{process,flow}/<name>.json   <- Auto-created on add. Auto-cleaned on remove.
+└── userProfile/<user-uuid>/              <- 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

@@ -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.
-Original file line number
+Diff line change
@@ Expand Up @@
     - 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
@@ Expand Down @@