@uipath/skills 1.198.0-preview.21 → 1.199.0-preview.106

package/skills/uipath-coded-apps/SKILL.md

@@ -28,7 +28,7 @@ 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`.
+> **Coded apps are not registered in `.uipx` solutions.** They have no `project.uiproj` / `project.json`, so `uip solution projects 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
 
@@ -42,7 +42,7 @@ Build, debug, and deploy UiPath Coded Web Applications and Coded Action Apps usi
 8. **Base URL must use the API subdomain.** `https://api.uipath.com` not `https://cloud.uipath.com`. See the table below.
 9. **`vite.config.ts` must always set `base: './'`.** The platform handles URL routing — apps must use relative asset paths. Do not use a routing name or a sub-path here.
 10. **Use `getAppBase()` from `@uipath/uipath-typescript` for any absolute URL constructed at runtime** — router basename, image `src`, `fetch` paths. Deployed apps mount at a non-root prefix; `/`-rooted paths work locally but 404 after deploy. Vite's `base: './'` only fixes import-time references.
-11. **`uip codedapp deploy` must run non-interactively.** Pass the folder key as `--folder-key <GUID>` (or as `UIPATH_FOLDER_KEY=<GUID>` env-var prefix — either works). The interactive folder picker fails in non-TTY contexts (CI, agent shells). If the user provides a folder **name**, resolve it to a key with `uip or folders list --output json` and match on the `Name` field (output rows are `{ Key, Name, Path, Description, Type, ParentKey }`). The `uip or ...` commands require the Orchestrator tool — install once via `uip tools install @uipath/orchestrator-tool` (check first with `uip tools list`).
+11. **`uip codedapp deploy` must run non-interactively.** Pass the folder key as `--folder-key <GUID>` (or as `UIPATH_FOLDER_KEY=<GUID>` env-var prefix — either works). The interactive folder picker fails in non-TTY contexts (CI, agent shells). If the user provides a folder **name**, resolve it to a key with `uip or folders list --output json` and match on the `Name` field (output rows are `{ Key, Name, Path, Description, Type, ParentKey }`). A **personal workspace** is the row with `Type == "Personal"` — resolve its `Key` the same way. To deploy into a **new** folder, create it first with `uip or folders create "<NAME>" --output json` and read `Data.Key`. The `uip or ...` commands require the Orchestrator tool — install once via `uip tools install @uipath/orchestrator-tool` (check first with `uip tools list`).
 12. **Guard against text overflow in every UI.** See [patterns.md](references/patterns.md) "Preventing Text Overflow".
 13. **Inspect the DF schema before writing analytics, filters, or seeds.** Run `uip df entities get <ENTITY_ID> --output json` to inspect fields and types. At runtime, use `entities.getById(<id>)` from the app's authenticated session. DF doesn't behave like a typical RDBMS; see [sdk/data-fabric.md](references/sdk/data-fabric.md) "Anti-shapes & gotchas".
 14. **Every list call returns ONE page — even with no options. There is no "give me everything" path.** Applies to `getAll`, `getAllRecords`, `queryRecordsById`, `getFileMetaData`, etc. `getAll()` with no options does NOT return all rows; the SDK sends no `pageSize` and the **server** applies its own cap, wrapped in a misleadingly-named `NonPaginatedResponse`. To list every row from a source that may exceed the cap, you MUST loop the cursor: `while (page.hasNextPage) { page = await getAll({ cursor: page.nextCursor }) }` and accumulate `items`. Reading `result.items.length` after a single call is almost always a bug. See [sdk/pagination.md](references/sdk/pagination.md).
@@ -164,7 +164,7 @@ To change any of these values, edit `uipath.json`.
 2. **Build** — `npm run build`. Verify `ls dist/`.
 3. **Pack** — `uip codedapp pack dist -n <name> --version <version>`. Produces `.uipath/<name>.<version>.nupkg`. Bump version if previously published.
 4. **Publish** — `uip codedapp publish` (add `-t Action` for action apps). Verify `cat .uipath/app.config.json`.
-5. **Deploy** — `uip codedapp deploy -n <name> --folder-key <GUID>`. Resolve the GUID from a user-provided folder name via `uip or folders list --output json`. Never let the command go interactive. Share the app URL with the user.
+5. **Deploy** — `uip codedapp deploy -n <name> --folder-key <GUID>`. Resolve the GUID from the chosen folder: a personal workspace (`Type == "Personal"`), a named existing folder, or a freshly `uip or folders create`d one — via `uip or folders list --output json`. Dashboards additionally choose a **deploy mode** (standalone / governance-pinned / governance) that sets `--tags`; see [dashboards deploy impl](references/dashboards/plugins/deploy/impl.md). Never let the command go interactive. Share the app URL with the user.
 
 ## SDK Module Imports
 

package/skills/uipath-coded-apps/assets/scripts/dashboards/build-dashboard.mjs

@@ -121,8 +121,8 @@ const REGISTRY = JSON.parse(readFileSync(resolve(__dirname, 'capability-registry
  * @property {string}        routingName - Permanent URL slug (e.g. "agent-health-x7k2")
  * @property {string}        orgName
  * @property {string}        tenantName
- * @property {string}        cloudUrl    - e.g. https://alpha.uipath.com
- * @property {string}        apiUrl      - e.g. https://alpha.api.uipath.com
+ * @property {string}        cloudUrl    - e.g. https://cloud.uipath.com
+ * @property {string}        apiUrl      - e.g. https://api.uipath.com
  * @property {string}        [clientId]  - External OAuth app client ID
  */
 

package/skills/uipath-coded-apps/references/create-action-app.md

@@ -173,11 +173,19 @@ Ask:
 > It needs these scopes: `<deduced-scopes>`
 >
 > - If yes, paste it
-> - If no, say **"create one"** and I'll set it up via browser automation"
+> - If no, say **"create one"** and I'll create it via the `uip admin` CLI"
 
-**If the user says "create one":** Follow [oauth-client-setup.md Step 2 (Setup B)](oauth-client-setup.md#step-2-ensure-playwright-is-available) to install Playwright into `~/.uipath-skills/playwright/`. Do **not** install into the user's app (`npm install -D playwright` adds ~300MB to devDependencies for a tool that runs once or twice).
+**If the user says "create one":** Create it with the `uip admin external-apps` CLI — read [oauth-client-setup.md](oauth-client-setup.md) for prerequisites and full flags. Confirm `uip` is authenticated, then create with the scopes above, passing `<cloud-host>` as the redirect URI:
 
-Then read [oauth-client-setup.md](oauth-client-setup.md) and follow it to create the External Application with the scopes above — pass `<cloud-host>` as `--cloud-host` **and** as `--redirects <cloud-host>`. The portal's create form requires at least one redirect URI, so pass `<cloud-host>` to satisfy it; the value is harmless and unused — an action app runs inside Action Center's iframe with a host-injected session and never performs a browser OAuth redirect (Critical Rule 17). The External App is needed only for its client ID and scopes (written to `uipath.json`).
+```bash
+uip admin external-apps create "<app name>" \
+  --non-confidential \
+  --user-scope "<deduced-scopes>" \
+  --redirect-uri "<cloud-host>" \
+  --output json
+```
+
+`--redirect-uri` is required by the CLI, so pass `<cloud-host>` to satisfy it; the value is inert at runtime — an action app runs inside Action Center's iframe with a host-injected session and never performs a browser OAuth redirect (Critical Rule 17). The External App is needed only for its client ID and scopes (written to `uipath.json`). Parse `id` from the response as the client ID. On `403` / no auth, use the [Manual portal fallback](oauth-client-setup.md#manual-portal-fallback).
 
 Store the resulting client ID as `<client-id>`.
 

package/skills/uipath-coded-apps/references/create-web-app.md

@@ -43,7 +43,7 @@ Please answer these questions to continue:
 
 **5. Client ID** — do you have an existing OAuth External Application client ID with the scopes above?
    - If yes, paste it
-   - If no, say **"create one"** and I'll set it up via browser automation
+   - If no, say **"create one"** and I'll create it via the `uip admin` CLI
 
 **6. Default UI styling** — apply UiPath's Apollo Vertex design system (`@uipath/apollo-wind` components, semantic tokens, and a light/dark theme toggle out of the box)?
    - `yes` *(recommended)* — apollo-wind + `next-themes` on top of Tailwind: Apollo Vertex design system, light/dark theme toggle out of the box
@@ -53,17 +53,19 @@ Please answer these questions to continue:
 
 **Wait for the user's reply before proceeding.**
 
-### Step 2.5 — Ensure Playwright CLI is available (only if user said "create one")
+### Step 2.5 — Create the External Application (only if user said "create one")
 
-Before running browser automation, check if Playwright is installed:
+Create it with the `uip admin external-apps` CLI — read [oauth-client-setup.md](oauth-client-setup.md) for prerequisites and full flags. Confirm `uip` is authenticated (`uip login status --output json`), then:
 
 ```bash
-npx playwright --version 2>/dev/null
+uip admin external-apps create "<app name>" \
+  --non-confidential \
+  --user-scope "<scopes from Step 1>" \
+  --redirect-uri "http://localhost:5173,http://localhost:5173/" \
+  --output json
 ```
 
-If the command fails or returns no output, follow [oauth-client-setup.md Step 2 (Setup B)](oauth-client-setup.md#step-2-ensure-playwright-is-available) to install Playwright into `~/.uipath-skills/playwright/`. Do **not** install into the user's app.
-
-Once confirmed available, read [oauth-client-setup.md](oauth-client-setup.md) and follow it exactly to create the External Application with the scopes from Step 1 and redirect URI `http://localhost:5173`. That reference has all the browser automation details.
+Parse `id` from the response — that is the Client ID. If the CLI returns `403` (no admin permission) or can't authenticate, use the [Manual portal fallback](oauth-client-setup.md#manual-portal-fallback).
 
 ### Step 3 — Resolve org name (if not provided)
 

package/skills/uipath-coded-apps/references/dashboards/plugins/build/impl.md

@@ -9,6 +9,7 @@ By the time you read this you have already loaded all docs, checked state, and f
 3. **The build runs in a subagent when one is available, else inline (Phase 4).** After confirmation, the main thread prints one "Building…" line. **Best effort: if the host agent already provides a sub-task/subagent mechanism (the `Task` tool in Claude Code; the equivalent in Codex/Gemini/others), use it automatically** — spawn a build subagent so the build command, events, tsc/npm output, and retries stay hidden, then relay its returned milestone block. **If no such mechanism exists, fall back to running the same build steps inline in the main thread** — the build and its output are identical; only the noise-hiding is lost. Subagent use is an optimization, never a hard requirement.
 4. Never read `build-dashboard.mjs` — this file documents everything.
 5. Never run directory exploration via any shell — `ls`, `find`, `dir`, `Get-ChildItem`, `tree`.
+6. **A build is ALWAYS compiler-driven — never hand-roll.** Author `intent.json` (pure metadata) + one `metrics/<name>.ts` per metric, then run `build-dashboard.mjs intent.json`. NEVER hand-write `src/metrics/`, `src/dashboard/`, or a bespoke React app and `npm run build` it directly: a hand-rolled build authors no `intent.json`, so the compiler cannot edit/upgrade it and validation fails. This holds for EVERY build — including custom (T3) metrics, governance (`AgentTraces.getGovernance*`), job routing/classification (`ProcessType` filters), and detail-view / row-link dashboards. No metric is "too custom" for the compiler; express it as `intent.json` + a `metrics/*.ts` module. Hand-edited `src/` is valid ONLY in an already-**ejected** project (CAPABILITY.md § Regimes), never a fresh build.
 
 ---
 
@@ -240,7 +241,7 @@ Never re-ask for anything the user already provided. The same pattern applies to
 **Creating the OAuth app:** Run this single command. `--redirect-uri` takes **comma-separated** values — register BOTH the local dev server and the org portal base, so login works in dev and after deploy:
 
 - `http://localhost:25173` — local dev server
-- `<CLOUD_URL>/<ORG>/portal_` — deployed app base; `<CLOUD_URL>` and `<ORG>` are the `cloudUrl` (`Data.BaseUrl`) and `orgName` (`Data.Organization`) extracted in Phase 1, so they track the logged-in environment (e.g. `https://alpha.uipath.com/acme/portal_`)
+- `<CLOUD_URL>/<ORG>/portal_` — deployed app base; `<CLOUD_URL>` and `<ORG>` are the `cloudUrl` (`Data.BaseUrl`) and `orgName` (`Data.Organization`) extracted in Phase 1, so they track the logged-in environment (e.g. `https://cloud.uipath.com/acme/portal_`)
 
 ```bash
 uip admin external-apps create "UiPath Dashboard - <DASHBOARD_NAME>" \
@@ -348,6 +349,7 @@ Building **[Dashboard Name]**…
 The build subagent prompt:
 
 > You are the dashboard build executor. You NEVER surface raw output or file edits — your final message is the only thing shown.
+> 0. **Build ONLY via the compiler.** Author `intent.json` + `metrics/*.ts`, then run `build-dashboard.mjs intent.json`. NEVER hand-write `src/metrics/`/`src/dashboard/` or run your own bundler — even for custom (T3) metrics, governance, `ProcessType` routing, or detail-view/row-link features. A hand-rolled build authors no `intent.json` and fails validation.
 > 1. Read `<SKILL_BASE_DIR>/references/dashboards/plugins/build/impl.md` §§ "Phase 3.5" and "Build subagent — execution" and follow them exactly.
 > 2. All work happens inside the pre-warmed project folder `<ROUTING>`, which already exists in the current working directory. Reference it ONLY by this relative name — NEVER type an absolute `/tmp/…` path (a mistyped character silently builds a sibling project). Author `<ROUTING>/intent.json` (pure metadata — `schemaVersion: 2`, no `fnBody`, `"projectDir": "."`) and one `<ROUTING>/metrics/<name>.ts` per metric (`export const fetchData: MetricFn`), writing each module from the SDK references and applying the Phase 3.5 cross-check. Implement exactly this approved plan:
 >    - Project: dashboardName=`<NAME>`, routingName=`<ROUTING>`, projectDir=`"."`, orgName=`<ORG>`, tenantName=`<TENANT>`, cloudUrl=`<CLOUD_URL>`, apiUrl=`<API_URL>`, timeRange=`<RANGE>`, clientId=`<CLIENT_ID or empty>`

package/skills/uipath-coded-apps/references/dashboards/plugins/deploy/impl.md

@@ -4,7 +4,7 @@ Publishes a built dashboard to Automation Cloud as a Coded Web App.
 
 **Pipeline order:** Production build → Pack → Publish → Deploy.
 
-> **What the user should see:** The deploy plan (Step 4), progress ticks, and the final URL. All other steps are silent — run commands, read outputs in context, never echo raw JSON or bash output to the user.
+> **What the user should see:** The deploy plan (Step 3), the mode/folder choices (Step 4), progress ticks, and the final URL. All other steps are silent — run commands, read outputs in context, never echo raw JSON or bash output to the user.
 
 ---
 
@@ -18,128 +18,185 @@ uip login status --output json
 
 Check `Data.Status === "Logged in"`. If not, stop and ask the user to run `uip login`.
 
-Read current deployment state from `.dashboard/state.json` — extract `app.name`, `app.routingName`, `app.semver`, `deployment.systemName`, `deployment.folderKey`, `deployment.folderName`.
+Read current deployment state from `.dashboard/state.json` — extract `app.name`, `app.routingName`, `app.semver`, `deployment.systemName`, `deployment.folderKey`, `deployment.folderName`, `deployment.pinnedToGovernance`.
 
 If `routingName` is empty: tell the user to run the build first.
 
 ---
 
-## Step 0 — Determine the deployment target (governance vs standard)
+## Step 0 — Classify deploy type
 
-A dashboard deploys one of two ways — pick before anything else:
+- `deployment.systemName` is empty → **Fresh deploy**
+- `deployment.systemName` is set → **Upgrade** — keep the mode and folder from the prior deploy (`deployment.pinnedToGovernance` + `deployment.folderName`/`folderKey`); the plan re-confirms but Step 4 asks nothing.
 
-| Target | Where it goes | Tags | Elevated perms? |
-|--------|---------------|------|-----------------|
-| **Governance / admin dashboard** | the `AdminDashboards` folder, pinnable to the Governance section *(pinning is an Agentic Governance **preview** feature — see Step 4)* | `governance` (+ `dashboard` if pinned) | yes — Administrators get Folder Administrator on AdminDashboards |
-| **Standard dashboard app** | a regular Orchestrator folder the user chooses | `dashboard` | no |
+---
 
-**Infer the target from `.dashboard/state.json`, then let the user correct it in the plan (Step 4):**
-- **Governance** when any widget's metric is a governance / runtime-compliance metric — its name starts with or equals `violations-`, `agents-by-violations`, `agent-governance-violations`, `recent-violations`, `rule-evaluations-`, `rule-compliance`, `agent-compliance-report`, `policy-denials`, `governance-verdicts`.
-- **Standard** otherwise — a dashboard that happens to show agent health / jobs / KPIs is a normal app, not a governance dashboard.
+## Step 1 — Set the publish version
 
-If `deployment.folderKey` is already set in state.json (a prior deploy), keep that target — don't re-ask.
+The version used for pack + publish (Steps 7–8) is `NEXT_SEMVER`, derived by deploy type:
 
-When genuinely ambiguous (or the user's wording conflicts with the inference), ask ONE structured-choice question (SKILL.md Rule 18): *"Deploy as a governance/admin dashboard (Admin portal, elevated) or a standard dashboard app (a folder you pick)?"* A free-text reply takes precedence.
+- **Fresh deploy** (`deployment.systemName` empty): first publish — use `app.semver` as-is. `NEXT_SEMVER = <CURRENT_SEMVER>` (no bump; the version doesn't exist yet).
+- **Upgrade** (`deployment.systemName` set): the current version is **already published**, so you **MUST** bump before pack/publish — re-publishing the same version fails with "version already exists". This bump is mandatory, not optional; never pack/publish an upgrade at `<CURRENT_SEMVER>`. Compute the next patch:
 
-Everything below marked **(governance only)** runs solely for the governance target; the **(standard only)** notes give the regular-app path.
+  ```bash
+  node -e "
+  const [a,b,c] = process.argv[1].split('.').map(Number)
+  process.stdout.write([a, b, c + 1].join('.'))
+  " <CURRENT_SEMVER>
+  ```
 
----
+  This gives `NEXT_SEMVER`. Pack (Step 7) and Publish (Step 8) MUST pass `--version "<NEXT_SEMVER>"`.
 
-## Step 1 — Provision AdminDashboards folder *(governance only; skip if folderKey already set)*
+Step 8 (Publish) still auto-bumps and retries on a 409 / "already exists" as a backstop — but on an Upgrade you bump here first; do not skip the bump and rely on the retry alone.
 
-**Standard target:** skip this step. Resolve the user's chosen deploy folder to a key instead — ask which folder (or use one they named), then `uip or folders list --output json` and match on `Name` (per SKILL.md Rule 11). Persist it as `deployment.folderKey`/`folderName` in state.json. No folder is created and no roles are assigned.
+---
 
-If `deployment.folderKey` is already in state.json, skip this entire step.
+## Step 2 — Compute recommended mode and folder (no side effects)
 
-Run the provisioning script (silent — no output to user until "AdminDashboards folder is ready"):
+Two independent decisions drive the deploy: **mode** (governance treatment → tags) and **folder** (where it lands). Compute recommendations here; the user confirms/overrides in Steps 3–4.
 
-```bash
-node "<SKILL_BASE_DIR>/assets/scripts/dashboards/setup-admin-folder.mjs" "AdminDashboards" "<PROJECT_DIR>"
-```
+**Mode** — three end states:
 
-`<PROJECT_DIR>` is the dashboard project directory (e.g. `<cwd>/agent-health-x7k2`). The script reads `.dashboard/state.json` to check if already provisioned and exits immediately if so.
+| Mode | `--tags` | Elevated role provisioning |
+|------|----------|----------------------------|
+| Governance dashboard, pinned to Governance UI | `governance,dashboard` | yes, on the target **shared** folder |
+| Governance dashboard, not pinned | `governance` | yes, on the target **shared** folder |
+| Standalone coded app | `dashboard` | none |
 
-The script:
-1. Looks up the Folder Administrator role key, the Administrators group key, and the AdminDashboards folder in parallel.
-2. Creates the folder if it does not exist.
-3. Reads existing role assignments before assigning — `roles assign` replaces all roles, so the script builds the full union to avoid removing existing access.
-4. Persists `folderKey` and `folderName` into `.dashboard/state.json`.
+Recommend a mode from `.dashboard/state.json` `widgets`:
+- **Governance (pinned)** when any widget's metric starts with or equals `violations-`, `agents-by-violations`, `agent-governance-violations`, `recent-violations`, `rule-evaluations-`, `rule-compliance`, `agent-compliance-report`, `policy-denials`, `governance-verdicts`.
+- **Standalone** otherwise — a dashboard that happens to show agent health / jobs / KPIs is a normal app, not a governance dashboard.
 
-> ⚠️ The script's role assignment step grants elevated folder permissions. The coding agent will ask for explicit approval — this is expected.
+**Folder** — three options: **Personal workspace** · **Existing folder** (user names it) · **Create a new folder**. Recommend:
+- **Governance modes → `AdminDashboards`** (the governance home; provisioned in Step 5).
+- **Standalone → Personal workspace** (zero-config, private to the user).
 
-If the script fails with "Administrators group not found": run `uip or users list --username "Administrators" --output json` and show the user the available groups.
+**Upgrade short-circuit:** if `deployment.systemName` is set, keep the state-implied mode (`deployment.pinnedToGovernance` + the tags used before) and folder (`deployment.folderName`/`folderKey`). Step 4 asks nothing.
 
-Tell the user: "AdminDashboards folder is ready."
+**Capture user wording:** if the request already names a mode ("as a governance dashboard, pinned") and/or a folder ("in a new folder called X" / "to my personal workspace"), treat those as settled — the matching Step-4 question is skipped.
 
 ---
 
-## Step 2 — Classify deploy type
+## Step 3 — Show deploy plan
 
-- `deployment.systemName` is empty → **Fresh deploy**
-- `deployment.systemName` is set → **Upgrade**
+`<MODE_LABEL>` / `<FOLDER_LABEL>` are the recommended (or wording-settled) values from Step 2.
+
+```
+Your **<APP_NAME>** is ready to be deployed.
+
+📦  Version:    <SEMVER> → <NEXT_SEMVER>   (or "1.0.0 (first publish)" on a fresh deploy)
+🔗  URL path:   <ROUTING_NAME>
+🎯  Mode:       <MODE_LABEL>   (recommended — <why>, or "kept from last deploy" on upgrade)
+📁  Folder:     <FOLDER_LABEL>   (recommended — <why>)
+🔄  Type:       Fresh deploy  OR  Updating existing deployment
+```
+
+**Governance mode + fresh deploy + shared-folder target** — also show:
+```
+⚠️  Governance deploy provisions the <FOLDER_LABEL> folder and grants Administrators
+    Folder Administrator on it — an elevated permission the coding agent will ask you
+    to approve once.
+```
+**Governance + pinned** — append:
+```
+    Pinning surfaces the dashboard in the Governance section, an Agentic Governance
+    preview feature — effective only if your org is enrolled in the preview. Either
+    way the dashboard deploys and is reachable at its URL.
+```
+**Standalone, or ANY Personal-workspace target** — show no elevated-permissions warning (deploying there assigns no roles).
+
+End the deploy plan with: `Confirm to deploy, or tell me what to change.` — **pure text, no tool calls in this response. HALT.**
 
 ---
 
-## Step 3 — Set the publish version
+## Step 4 — On confirm: settle mode, then folder
 
-The version used for pack + publish (Steps 6–7) is `NEXT_SEMVER`, derived by deploy type:
+On the user's reply:
+- **Change request / cancel** → handle it; re-present the plan if changed.
+- **Upgrade** (`systemName` set) → skip both questions; go to Step 5 with the kept mode/folder.
 
-- **Fresh deploy** (`deployment.systemName` empty): first publish — use `app.semver` as-is. `NEXT_SEMVER = <CURRENT_SEMVER>` (no bump; the version doesn't exist yet).
-- **Upgrade** (`deployment.systemName` set): the current version is **already published**, so you **MUST** bump before pack/publish — re-publishing the same version fails with "version already exists". This bump is mandatory, not optional; never pack/publish an upgrade at `<CURRENT_SEMVER>`. Compute the next patch:
+Otherwise this is a **fresh deploy**: ask the two SHORT structured-choice questions below (SKILL.md Rule 18), recommended option first and suffixed "(Recommended)". **Never** put them in the same message as the plan — they fire on this later, short turn.
 
-  ```bash
-  node -e "
-  const [a,b,c] = process.argv[1].split('.').map(Number)
-  process.stdout.write([a, b, c + 1].join('.'))
-  " <CURRENT_SEMVER>
-  ```
+> **When an interactive user is present, ALWAYS present Question 1 (mode) on a fresh deploy.** The Step-2 inference only decides which option is pre-marked "(Recommended)" — with a human present it does **NOT** let you silently auto-pick a mode. Deploying as *standalone* without asking is a bug: an agent-health / jobs / KPI dashboard is merely *recommended* standalone, but the user may deliberately want it as a governance dashboard, so show all three and let them choose. A bare "deploy" / "confirm" / "yes" does **not** settle the mode — ask.
+>
+> **Skip Question 1 ONLY when:** (a) the user's wording already named the mode ("deploy as a governance dashboard, pinned" / "just deploy as a standalone app"); or (b) the user told you not to ask / to proceed without confirmation, or the run is non-interactive / automated (e.g. CI) — then use the **recommended** mode and proceed without asking (never block a headless deploy on a question). The **same two carve-outs** govern Question 2 (folder): ask when interactive, otherwise use the recommended folder.
+
+**Question 1 — mode** (ask when a human is present; skip per carve-outs (a)/(b) above):
+
+| Option | Meaning |
+|--------|---------|
+| **Governance dashboard, pinned to Governance UI** | governance access + surfaced in the Governance section (`governance,dashboard`) |
+| **Governance dashboard, not pinned** | governance access only (`governance`) |
+| **Standalone coded app** | a regular dashboard app (`dashboard`) |
+
+> ⚠️ **Pinning is a preview feature.** When offering a pinned option, state: *"Pinning surfaces the dashboard in the Governance section — an Agentic Governance preview feature, so it only takes effect if your org is enrolled in the preview. Either way the dashboard deploys and is reachable at its URL."* If the org isn't enrolled, the deploy still succeeds and the app is fully usable via its URL — only the Governance-UI pin has no visible effect until preview access is granted (contact your UiPath representative).
+
+**Question 2 — folder** (ask when a human is present; skip per carve-outs (a)/(b) above). Present these **three named options**, recommended first. **"Create a new folder" MUST appear as its own selectable option — do NOT fold it into the free-text / "type something" escape** (the escape is the separate 4th slot per Rule 18). The three are distinct *actions*, not just "type a name":
 
-  This gives `NEXT_SEMVER`. Pack (Step 6) and Publish (Step 7) MUST pass `--version "<NEXT_SEMVER>"`.
+| Option | Mechanism |
+|--------|-----------|
+| **An existing folder** | deploy into a folder that already exists; resolve its key by name. Offer a **concrete** default, not the generic word "existing": **`AdminDashboards`** for a governance mode, or a shared team folder (e.g. **`Shared`**) for standalone. The user may name a different existing folder in free text. |
+| **Create a new folder** | the user gives a name; you run `uip or folders create` (governance shared folder → provision via `setup-admin-folder.mjs`) and deploy into it |
+| **Personal workspace** | your own workspace, private to you |
 
-Step 7 (Publish) still auto-bumps and retries on a 409 / "already exists" as a backstop — but on an Upgrade you bump here first; do not skip the bump and rely on the retry alone.
+Recommended (first, suffixed "(Recommended)"): the existing-folder default — **`AdminDashboards`** for a governance mode; a shared team folder (e.g. `Shared`) for a standalone dashboard (a dashboard is usually team-facing; offer Personal workspace as the private alternative).
+
+Free-text replies (including a bare folder name) remain valid and take precedence.
 
 ---
 
-## Step 4 — Show deploy plan (and, governance only, ask about pinning)
+## Step 5 — Resolve and provision the chosen folder
 
-`<FOLDER_NAME>` is `AdminDashboards` for the governance target, or the user's chosen folder (state.json `deployment.folderName`) for the standard target.
+Resolve the chosen folder to `folderKey` and persist `deployment.folderKey`/`folderName` in `.dashboard/state.json`.
 
-```
-Your **<APP_NAME>** is ready to be deployed.
+**If `deployment.folderKey` is already set** (upgrade / prior run) — skip this entire step.
 
-📦  Version:    <SEMVER> → <NEXT_SEMVER>
-🔗  URL path:   <ROUTING_NAME>
-📁  Folder:     <FOLDER_NAME>
-🔄  Type:       Fresh deploy  OR  Updating existing deployment
-```
+**Governance mode targeting a SHARED folder** (AdminDashboards, or any user-named/newly-created shared folder — anything except Personal workspace) — provision via the script (silent — no output to user until "<FOLDER_NAME> folder is ready"):
 
-**(governance only)** If this is a fresh deploy, also show:
+```bash
+node "<SKILL_BASE_DIR>/assets/scripts/dashboards/setup-admin-folder.mjs" "<FOLDER_NAME>" "<PROJECT_DIR>"
 ```
-⚠️  I'll create the AdminDashboards folder and assign Administrators as Folder Administrators.
-    This requires elevated permissions — the coding agent will ask for your approval once.
+
+`<FOLDER_NAME>` is the chosen governance folder (`AdminDashboards` by default). `<PROJECT_DIR>` is the dashboard project directory (e.g. `<cwd>/agent-health-x7k2`). The script reads `.dashboard/state.json`, exits immediately if already provisioned, else:
+
+1. Looks up the Folder Administrator role key, the Administrators group key, and the folder in parallel.
+2. Creates the folder if it does not exist.
+3. Reads existing role assignments before assigning — `roles assign` replaces all roles, so the script builds the full union to avoid removing existing access.
+4. Persists `folderKey` and `folderName` into `.dashboard/state.json`.
+
+> ⚠️ The script's role assignment step grants elevated folder permissions. The coding agent will ask for explicit approval — this is expected.
+
+If the script fails with "Administrators group not found": run `uip or users list --username "Administrators" --output json` and show the user the available groups.
+
+Tell the user: "<FOLDER_NAME> folder is ready."
+
+**Personal workspace** (any mode) — resolve, no provisioning:
+
+```bash
+uip or folders list --output json
 ```
-**(standard only)** Show no elevated-permissions warning — deploying to a regular folder assigns no roles.
 
-End the deploy plan with: `Confirm to deploy, or tell me what to change.` — **pure text, no tool calls in this response. HALT.**
+Pick the `Data[]` row where `Type == "Personal"`, read its `Key`. Persist `folderKey`/`folderName`. No folder is created and no roles are assigned — a governance dashboard in a personal workspace needs no role provisioning, since the owner already has full access. If no `Personal` row is found, show the folder list and ask the user to pick another option.
 
-**On the user's reply:**
-- Change request / cancel → handle it; re-present if changed
-- **(standard target)** Any confirmation → proceed with `--tags "dashboard"`, ask nothing. There is no Governance pinning for a standard dashboard.
-- **(governance target)** Confirmation that already settles pinning (e.g. "deploy and pin" / "deploy without pinning") → proceed with the matching tags, ask nothing
-- **(governance target)** Bare confirmation → ask ONE short structured-choice question (SKILL.md Rule 18): *"Pin this dashboard to the Governance UI?"*
+**Existing folder by name** (standalone) — resolve per SKILL.md Rule 11:
 
-  | Option | Meaning |
-  |--------|---------|
-  | **Deploy and pin** | Visible in the Governance section (`--tags "governance,dashboard"`) |
-  | **Deploy without pinning** | Deploy only (`--tags "governance"`) |
+```bash
+uip or folders list --output json
+```
 
-  Free-text replies remain valid and take precedence.
+Match on `Name`, read `Key`. Persist.
+
+**Create a new folder** (standalone) —
+
+```bash
+uip or folders create "<FOLDER_NAME>" --output json
+```
 
-  > ⚠️ **Pinning is a preview feature.** Surfacing a dashboard in the Governance section depends on **Agentic Governance**, which is currently limited to organizations enrolled in the preview program. State this when offering the pin option: *"Pinning surfaces the dashboard in the Governance section — that's an Agentic Governance preview feature, so it only takes effect if your org is enrolled in the preview. Either way the dashboard deploys and is reachable at its URL."* If the org isn't enrolled, the deploy still succeeds and the app is fully usable via its URL — only the Governance-UI pin has no visible effect until preview access is granted (contact your UiPath representative).
+Capture `Data.Key`. If it fails "already exists," resolve the existing folder's key from `uip or folders list` instead. Persist.
 
 ---
 
-## Step 5 — Production build
+## Step 6 — Production build
 
 ```bash
 cd <PROJECT_DIR> && npm run build
@@ -159,11 +216,11 @@ process.stdout.write(html.includes('uipath:org-name') ? 'CONFIG_OK' : 'CONFIG_MI
 "
 ```
 
-If it prints `CONFIG_MISSING`, `uipath.json` lacked `orgName` at build time — re-run the build (the build script writes `uipath.json`) and re-check. **Never deploy a `CONFIG_MISSING` bundle** — it loads blank in the browser. **Skip this check for template builds** (Step 6b) — a tenant-neutral template intentionally omits the org name.
+If it prints `CONFIG_MISSING`, `uipath.json` lacked `orgName` at build time — re-run the build (the build script writes `uipath.json`) and re-check. **Never deploy a `CONFIG_MISSING` bundle** — it loads blank in the browser. **Skip this check for template builds** (Step 7b) — a tenant-neutral template intentionally omits the org name.
 
 ---
 
-## Step 6 — Pack (silent)
+## Step 7 — Pack (silent)
 
 `-n` is the **friendly Title Case display name** (state.json `app.name`, e.g. `"Jobs Health Dashboard"`) — **never the routing slug.** The CLI sanitizes it to a slug (`jobshealthdashboard`) internally for package matching, but uses the friendly name as the display name in the catalog and Governance UI. Passing the slug makes the dashboard show up as `jobshealthdashboard`; the friendly name reads "Jobs Health Dashboard". Use the **same** `-n` for pack, publish, and deploy.
 
@@ -173,7 +230,7 @@ cd <PROJECT_DIR> && uip codedapp pack dist -n "<APP_NAME>" --version "<NEXT_SEMV
 
 ---
 
-### Step 6b — Template packaging (only when shipping a reusable template)
+### Step 7b — Template packaging (only when shipping a reusable template)
 
 A **template** is a dashboard distributed in the ejected regime: one artifact carrying both the deploy face (`dist/`) and the agent-modifiable source. Before `pack`, stage the source + manifest into `dist/_source/`:
 
@@ -187,11 +244,11 @@ This stages a **tenant-neutral** modify-face (`intent.json`, `src/`, config file
 
 **Tenant-neutral runtime config.** A template build (`intent.template: true`) writes a scope-only `uipath.json` (no org/tenant/base-url/client-id), so the plugin injects only the `uipath:scope` meta tag — **no** tenant identity is baked into the bundle. At runtime the UiPath Apps host injects the remaining `<meta name="uipath:*">` config tags (org/tenant/base-url/client-id) and loads the app with `?host=embed`; the scaffold's `useAuth` calls `new UiPath()`, which reads that config and delegates the token to the host. So the same bundle is portable across tenants.
 
-> **Skip the CONFIG_OK check (Step 5) for template builds.** That check greps `dist/index.html` for the org-name meta tag, which a tenant-neutral template intentionally omits — it would false-fail. Config arrives from host-injected meta tags at runtime instead.
+> **Skip the CONFIG_OK check (Step 6) for template builds.** That check greps `dist/index.html` for the org-name meta tag, which a tenant-neutral template intentionally omits — it would false-fail. Config arrives from host-injected meta tags at runtime instead.
 
 ---
 
-## Step 7 — Publish (silent)
+## Step 8 — Publish (silent)
 
 ```bash
 cd <PROJECT_DIR> && uip codedapp publish -n "<APP_NAME>" --version "<NEXT_SEMVER>" --output json
@@ -205,12 +262,12 @@ Read the JSON output (silent — no output shown until success or error):
 
 ---
 
-## Step 8 — Deploy
+## Step 9 — Deploy
 
-Set tags based on the deployment target (and, for governance, the user's pinning choice):
-- **Standard target** → tags = `"dashboard"`
-- **Governance target**, "deploy and pin" → tags = `"governance,dashboard"`
-- **Governance target**, "deploy" (no pin) → tags = `"governance"`
+Set tags from the chosen **mode** (Step 2/4):
+- **Standalone** → tags = `"dashboard"`
+- **Governance, pinned** → tags = `"governance,dashboard"`
+- **Governance, not pinned** → tags = `"governance"`
 
 Two flags differ from pack/publish — getting these wrong is the most common deploy failure:
 
@@ -257,7 +314,7 @@ Use the new routing name in a fresh deploy call. Retry up to 3 times.
 
 ---
 
-## Step 9 — Update state.json
+## Step 10 — Update state.json
 
 ```bash
 node -e "
@@ -278,7 +335,7 @@ fs.renameSync(fp + '.tmp', fp)
 
 ---
 
-## Step 10 — Report
+## Step 11 — Report
 
 ```
 🎉 **<APP_NAME>** is live.
@@ -309,7 +366,7 @@ Always: "To update after making changes, say 'deploy this dashboard' again."
 | Deploy "not been published" but you passed `--version` | Remove `--version` from the deploy call — deploy resolves the latest version itself |
 | Deploy "routing name must be unique" on an upgrade | You passed `--path-name` on an upgrade — omit it; routing already exists |
 | Deploy path-name conflict (fresh deploy) | Generate new suffix, retry deploy only (pack/publish already done) |
-| "Agentic Governance is a preview feature and is not enabled for your organization" (on a pinned/governance deploy) | Not a deploy failure — the app IS deployed and reachable at its URL. Governance pinning is preview-gated: the pin just won't surface in the Governance section until the org is enrolled. Report success with the URL, add the preview note (Step 10), and tell the user to contact their UiPath representative for preview access. Do NOT retry or bump the version. |
+| "Agentic Governance is a preview feature and is not enabled for your organization" (on a pinned/governance deploy) | Not a deploy failure — the app IS deployed and reachable at its URL. Governance pinning is preview-gated: the pin just won't surface in the Governance section until the org is enrolled. Report success with the URL, add the preview note (Step 11), and tell the user to contact their UiPath representative for preview access. Do NOT retry or bump the version. |
 | state.json missing | Tell user to run the build first |
 
 ## Rules
@@ -318,5 +375,6 @@ Always: "To update after making changes, say 'deploy this dashboard' again."
 - `--version` goes on **pack and publish only — NOT deploy.** Deploy resolves the latest published version; passing `--version` causes a false "has not been published yet" error.
 - `--path-name` goes on **fresh deploy only** — it sets the URL slug. On an upgrade the routing already exists; re-passing it errors "routing name must be unique."
 - Routing name is permanent after the first successful deploy.
-- Always include `--tags`. Standard target → `dashboard`. Governance target → minimum `governance`, add `dashboard` if the user opted to pin.
-- Determine governance vs standard target first (Step 0). Only the governance target provisions `AdminDashboards`, assigns elevated roles, and offers Governance pinning; the standard target deploys to a user-chosen folder with no role assignment and no pin prompt.
+- Always include `--tags`, sourced from the chosen **mode**: standalone → `dashboard`; governance, not pinned → `governance`; governance, pinned → `governance,dashboard`.
+- Choose **mode** and **folder** as two independent decisions (Steps 2–4). Mode sets `--tags`; only a governance mode targeting a **shared** folder provisions `setup-admin-folder.mjs` and assigns elevated roles. A Personal-workspace target never provisions roles; standalone never provisions roles.
+- Recommend the mode from state.json metrics and the folder from the mode (governance→AdminDashboards, standalone→Personal workspace); the user overrides either via the Step-4 structured choice or free-text.

package/skills/uipath-coded-apps/references/dashboards/primitives/state-file.md

@@ -14,10 +14,10 @@ Per-project metadata. Read at every build start. Written by build script on succ
     "routingName": "operations-health-x7k2",
     "semver": "1.0.0"
   },
-  "env": "alpha",
+  "env": "cloud",
   "org": "appsdev",
   "tenant": "appsdevDefault",
-  "cloudUrl": "https://alpha.uipath.com",
+  "cloudUrl": "https://cloud.uipath.com",
   "timeRange": "30d",
   "widgets": {
     "MemoryCallsTrend": {