@uipath/skills 1.196.0 → 1.197.0

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

@@ -0,0 +1,322 @@
+# Dashboard Deploy Plugin
+
+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.
+
+---
+
+## Pre-flight
+
+Verify login and read state.json:
+
+```bash
+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`.
+
+If `routingName` is empty: tell the user to run the build first.
+
+---
+
+## Step 0 — Determine the deployment target (governance vs standard)
+
+A dashboard deploys one of two ways — pick before anything else:
+
+| 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.
+
+If `deployment.folderKey` is already set in state.json (a prior deploy), keep that target — don't re-ask.
+
+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.
+
+Everything below marked **(governance only)** runs solely for the governance target; the **(standard only)** notes give the regular-app path.
+
+---
+
+## Step 1 — Provision AdminDashboards folder *(governance only; skip if folderKey already set)*
+
+**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.
+
+Run the provisioning script (silent — no output to user until "AdminDashboards folder is ready"):
+
+```bash
+node "<SKILL_BASE_DIR>/assets/scripts/dashboards/setup-admin-folder.mjs" "AdminDashboards" "<PROJECT_DIR>"
+```
+
+`<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.
+
+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`.
+
+> ⚠️ 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: "AdminDashboards folder is ready."
+
+---
+
+## Step 2 — Classify deploy type
+
+- `deployment.systemName` is empty → **Fresh deploy**
+- `deployment.systemName` is set → **Upgrade**
+
+---
+
+## Step 3 — Set the publish version
+
+The version used for pack + publish (Steps 6–7) is `NEXT_SEMVER`, derived by deploy type:
+
+- **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:
+
+  ```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 6) and Publish (Step 7) MUST pass `--version "<NEXT_SEMVER>"`.
+
+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.
+
+---
+
+## Step 4 — Show deploy plan (and, governance only, ask about pinning)
+
+`<FOLDER_NAME>` is `AdminDashboards` for the governance target, or the user's chosen folder (state.json `deployment.folderName`) for the standard target.
+
+```
+Your **<APP_NAME>** is ready to be deployed.
+
+📦  Version:    <SEMVER> → <NEXT_SEMVER>
+🔗  URL path:   <ROUTING_NAME>
+📁  Folder:     <FOLDER_NAME>
+🔄  Type:       Fresh deploy  OR  Updating existing deployment
+```
+
+**(governance only)** If this is a fresh deploy, also show:
+```
+⚠️  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.
+```
+**(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.**
+
+**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?"*
+
+  | Option | Meaning |
+  |--------|---------|
+  | **Deploy and pin** | Visible in the Governance section (`--tags "governance,dashboard"`) |
+  | **Deploy without pinning** | Deploy only (`--tags "governance"`) |
+
+  Free-text replies remain valid and take precedence.
+
+  > ⚠️ **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).
+
+---
+
+## Step 5 — Production build
+
+```bash
+cd <PROJECT_DIR> && npm run build
+```
+
+If build fails: show the error.
+
+No `.env` dance — the SDK config lives in `uipath.json`. The `uipathCodedApps()` Vite plugin reads it and injects `<meta name="uipath:*">` tags into `dist/index.html` at build time; the SDK (`new UiPath()`) reads its config from those tags at runtime. No tokens are baked into the bundle.
+
+**Verify the SDK config is injected into the built `index.html`** — turns the silent "UiPath SDK configuration not found" runtime crash into a build-time stop. The org-name meta tag must appear:
+
+```bash
+cd <PROJECT_DIR> && node -e "
+const fs=require('fs')
+const html = fs.existsSync('dist/index.html') ? fs.readFileSync('dist/index.html','utf8') : ''
+process.stdout.write(html.includes('uipath:org-name') ? 'CONFIG_OK' : 'CONFIG_MISSING')
+"
+```
+
+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.
+
+---
+
+## Step 6 — 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.
+
+```bash
+cd <PROJECT_DIR> && uip codedapp pack dist -n "<APP_NAME>" --version "<NEXT_SEMVER>" --output json
+```
+
+---
+
+### Step 6b — 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/`:
+
+```bash
+cd <PROJECT_DIR> && node "${SKILL_BASE_DIR}/assets/scripts/dashboards/build-dashboard.mjs" --pack-template <PROJECT_DIR>
+```
+
+This stages a **tenant-neutral** modify-face (`intent.json`, `src/`, config files, `uipath.json` with tenant identity blanked — only `scope` retained) plus `template.json` (scaffoldVersion, sdkFloor, requiredScopes, routingName, `ejected: true`) into `dist/_source/`, then emits `TEMPLATE_PACKED` with the `pack` command. It never stages `.dashboard/`, `node_modules`, or `dist`. Run the normal `pack` (above) afterward.
+
+> **Caveat — `dist/_source/*` is web-served.** The platform serves `dist`, so embedded source is publicly fetchable at the app URL. Ship it ONLY for shareable, tenant-neutral templates — never a customer's private dashboard.
+
+**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.
+
+---
+
+## Step 7 — Publish (silent)
+
+```bash
+cd <PROJECT_DIR> && uip codedapp publish -n "<APP_NAME>" --version "<NEXT_SEMVER>" --output json
+```
+
+Read the JSON output (silent — no output shown until success or error):
+- **Success** (`Result === "Success"`)→ extract `DeploymentVersion`, continue
+- **Contains "409" or "already exists"** → bump version once more, re-pack, retry publish (up to 4 attempts total)
+- **Contains "5xx" or HTML** → this is a transient gateway error; wait 10 seconds and retry (up to 4 attempts)
+- **Other error** → surface it to the user, stop
+
+---
+
+## Step 8 — 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"`
+
+Two flags differ from pack/publish — getting these wrong is the most common deploy failure:
+
+- **No `--version` on deploy.** The CLI resolves the latest published version itself. Passing `--version` triggers a false `"...has not been published yet"` error.
+- **`--path-name` only on a FRESH deploy.** It sets the URL slug the first time. On an **upgrade** the routing name already exists — re-passing `--path-name` errors with `"routing name must be unique"`.
+
+**Fresh deploy** (`deployment.systemName` was empty):
+
+```bash
+cd <PROJECT_DIR> && uip codedapp deploy \
+  -n "<APP_NAME>" \
+  --path-name "<ROUTING_NAME>" \
+  --folder-key "<FOLDER_KEY>" \
+  --tags "<TAGS>" \
+  --output json
+```
+
+**Upgrade** (`deployment.systemName` is set — omit `--path-name`):
+
+```bash
+cd <PROJECT_DIR> && uip codedapp deploy \
+  -n "<APP_NAME>" \
+  --folder-key "<FOLDER_KEY>" \
+  --tags "<TAGS>" \
+  --output json
+```
+
+Read the JSON output:
+- **Success** → extract `SystemName` and `AppUrl`, continue
+- **Contains "indexing" or "not been published"** → platform propagation delay after publish. Show `↻ App is indexing — retrying in 10 seconds (attempt N/3)…`. Wait 10 seconds and retry (up to 3 times). If all 3 fail, surface the error and stop.
+- **(Fresh deploy only) Contains "conflict", "already exist", or "name must be unique"** → the routing slug is taken; generate a new suffix and retry the fresh deploy (keep `--path-name`):
+
+```bash
+node -e "
+const base   = process.argv[1].replace(/-[a-z0-9]{4}$/, '')
+const suffix = Math.random().toString(36).slice(2, 6)
+process.stdout.write(base + '-' + suffix)
+" <ROUTING_NAME>
+```
+
+Use the new routing name in a fresh deploy call. Retry up to 3 times.
+
+- **Other error** → surface it to the user, stop
+
+---
+
+## Step 9 — Update state.json
+
+```bash
+node -e "
+const fs = require('fs')
+const fp = '.dashboard/state.json'
+const s  = JSON.parse(fs.readFileSync(fp, 'utf8'))
+s.app.semver                    = process.argv[1]
+s.app.routingName               = process.argv[2]
+s.deployment.systemName         = process.argv[3] || s.deployment.systemName
+s.deployment.deployVersion      = process.argv[4] || s.deployment.deployVersion
+s.deployment.appUrl             = process.argv[5] || s.deployment.appUrl
+s.deployment.pinnedToGovernance = process.argv[6] === 'true'
+s.deployment.lastDeployedAt     = new Date().toISOString()
+fs.writeFileSync(fp + '.tmp', JSON.stringify(s, null, 2))
+fs.renameSync(fp + '.tmp', fp)
+" <NEXT_SEMVER> <ROUTING_NAME> <SYSTEM_NAME> <DEPLOY_VERSION> <APP_URL> <PIN_TO_GOVERNANCE>
+```
+
+---
+
+## Step 10 — Report
+
+```
+🎉 **<APP_NAME>** is live.
+
+<APP_URL>
+
+Version <NEXT_SEMVER> · <FOLDER_NAME>
+```
+
+**(governance only)**
+- If pinned: "Your dashboard is pinned to the Governance section. Note: the Governance section is an **Agentic Governance preview** feature — if your org isn't enrolled in the preview, the pin won't appear there yet (contact your UiPath representative for access). The dashboard is live and fully usable at the URL above regardless."
+- If not: "To pin it later, say 'redeploy and pin to governance'."
+
+Always: "To update after making changes, say 'deploy this dashboard' again."
+
+---
+
+## Error reference
+
+| Situation | What to do |
+|-----------|-----------|
+| "Folder Administrator" role not found | Run `uip or roles list --output json` and show the user the available roles |
+| Administrators group not found | List groups from the response, ask user which to use |
+| Build fails | Show the error — dev credentials are always restored |
+| Publish 409 | Auto-bump version and retry (up to 4 times) |
+| Publish 5xx / HTML | Wait 10s and retry (up to 4 times) |
+| Deploy "indexing" / "not been published" (with NO `--version` passed) | Propagation delay — show retry ticker, wait 10s, retry up to 3 times |
+| 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. |
+| state.json missing | Tell user to run the build first |
+
+## Rules
+
+- `-n` is the **friendly Title Case display name** (state.json `app.name`, e.g. "Jobs Health Dashboard") — same across pack, publish, deploy. Never the routing slug: the CLI slugifies it for package matching but shows the friendly name in the catalog/Governance UI.
+- `--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.

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

@@ -0,0 +1,66 @@
+# Customization & Ownership — hand-edited dashboards
+
+The generated project is a **standard Vite + React + Tailwind + Recharts app with no skill dependency**. The skill's job is the first draft; the user owns the result. This file tells you how to act when the user customizes it — the build script does NOT handle this, you do.
+
+## Regimes: compiler-managed vs ejected
+
+Every dashboard is in one of two regimes, recorded as `regime` in `.dashboard/state.json`:
+
+| Regime | Source of truth | How you edit it | Compiler regen / `UPGRADE`? |
+|--------|-----------------|-----------------|------------------------------|
+| **`compiler-managed`** (default) | `intent.json` + `metrics/*.ts` | structured `edit-intent.json` + `build-dashboard.mjs` (the Ownership map + Rules below apply) | Yes |
+| **`ejected`** | the full project `src/` | edit source files directly per the request, then `npm run build` — **never the edit-script** | No |
+
+**Read `state.regime` at entry and route on it:**
+- `compiler-managed` (or absent/legacy) → the structured edit path is available; follow the Ownership map + Rules below.
+- `ejected` → free-form source editing only. The edit-script **refuses** to run (emits `EJECTED_PROJECT` and exits non-zero) so it can't clobber hand work. A **template** is shipped ejected from day one.
+
+### When to eject
+
+Eject when an edit request exceeds the declarative surface — look-and-feel, cross-widget interactivity, structural composition — or when `HAND_EDIT_DETECTED` fires and the user wants to keep editing freely. Do NOT cram a custom request through the compiler. State the eject to the user: it's a **one-way door** away from compiler regen / `UPGRADE`.
+
+### How to eject
+
+Write an edit-intent and run the build script:
+
+```json
+{ "op": "EJECT", "projectDir": "<ABS_PROJECT_DIR>" }
+```
+
+```bash
+node <skill>/assets/scripts/dashboards/build-dashboard.mjs eject-intent.json
+```
+
+It flips `regime` to `"ejected"` in `state.json` and emits `EJECTED` — no files are regenerated. From then on the dashboard behaves exactly like a template's modify face: edit `src/` per NLP → `npm run build` → deploy. Deploy is unaffected (it only reads `state.json`).
+
+> **Ejected metric modules live in `src/metrics/`, not the root `metrics/`.** In the compiler-managed regime the build copies root `metrics/*.ts` → `src/metrics/*.ts` each run. After eject it no longer copies — `src/metrics/*.ts` is canonical. Edit the data fetch there; editing the root copy has no effect on the running app.
+
+## Ownership map — what the build script overwrites
+
+| File | Regenerated when | Safe to hand-edit? |
+|------|------------------|--------------------|
+| `src/dashboard/Dashboard.tsx` | **Every** build and incremental op (ADD/REMOVE/CHANGE/REBUILD) | Only if you re-apply edits after (see protocol) |
+| `src/dashboard/widgets/index.ts` | Every build and incremental op | No — regenerated from state.json widgets only |
+| `src/dashboard/widgets/<Widget>.tsx` | CHANGE/REBUILD of that widget | Hash-guarded on CHANGE/REMOVE (`HAND_EDIT_DETECTED`); **REBUILD overwrites silently** |
+| `src/dashboard/views/<Widget>View.tsx` | ADD/CHANGE of its chart widget | Same caveat |
+| `src/App.tsx` | Only inside `GENERATED_IMPORTS/ROUTES` markers | Yes, outside the markers |
+| `src/index.css`, `tailwind.config.*`, `src/dashboard/chrome/*`, `src/hooks/*`, `src/lib/*` | Never | **Yes — fully safe** |
+| Any new file the user adds | Never touched, but `index.ts` regen drops its export | Yes (see custom-widget rule) |
+
+## Rules
+
+1. **Look-and-feel requests → edit the project directly. Never run the build script for presentation-only changes.** Restyle via `index.css` CSS variables (`--chart-1..5`, `--background`, …), Tailwind config, `chrome/` components, or by editing `Dashboard.tsx` yourself with file-edit tools. You are a coding agent — the script is for data/widget generation, not the only way to change the app.
+2. **Before running ANY edit-intent on a customized project, protect `Dashboard.tsx`:** read it first; run the script; if the user had customized it, re-apply their layout afterwards and merge the change in by hand (e.g. add the new widget's import + JSX where it fits their design). The script always rewrites `Dashboard.tsx` + `widgets/index.ts` from state. **If the hand customization to `Dashboard.tsx`/widgets is sustained (not a one-off), eject instead** — the read-run-re-apply dance is fragile and lossy; once ejected the script never touches the project again.
+3. **Detect customization before assuming.** Signals: the user says they edited; `HAND_EDIT_DETECTED` fires; `Dashboard.tsx` clearly diverges from the generated shape (custom sections, different grid). When detected, prefer hand-editing over the script for the whole change.
+4. **Never run REBUILD on a customized project without explicit consent** — it regenerates every widget from stored intent and silently overwrites hand-edited widget files.
+5. **`HAND_EDIT_DETECTED` means stop.** Never overwrite. Show the user what would be lost and offer three paths: **(a) eject** — if they intend to keep hand-editing this dashboard, flip it to the ejected regime (see *When to eject*) so the script stops regenerating over their work; **(b) keep** their version and apply the requested change by hand; **(c) discard** their edits and regenerate. Eject is the durable answer when the hand-editing is ongoing rather than a one-off.
+6. **Custom (user-written) widgets: import them directly in `Dashboard.tsx`** (`import { Foo } from './widgets/Foo'`), NOT via `./widgets` index — `index.ts` regeneration drops unknown exports. If the user already routes through the index, re-add the export line after any script run.
+7. **Custom routes/views go outside the `GENERATED_*` markers in `App.tsx`** — content inside the markers is regenerated.
+8. **Full takeover is legitimate — mark it by ejecting.** A pro user can stop using build/edit entirely and develop the app by hand; everything keeps working (`npm run dev/build`), and the deploy flow still works — it only reads `.dashboard/state.json`. Tell them this when they ask "can I extend this myself?": yes, it's their app. Record the takeover by **ejecting** (regime → `ejected`) so a later edit-intent won't regenerate over their work.
+
+## Anti-patterns
+
+- Running `edit-intent` (or a fresh build) over a customized `Dashboard.tsx` without re-applying the user's layout — their design is wiped
+- Telling the user a styling request "isn't supported" because `displayAs`/registry has no option for it — edit the code instead
+- Re-running the build script to change a title, color, or spacing
+- Regenerating a hand-edited widget after `HAND_EDIT_DETECTED` without asking

package/skills/uipath-coded-apps/references/dashboards/primitives/detail-views.md

@@ -0,0 +1,64 @@
+# Detail Views
+
+A chart widget drills down to a detail view at `/<foo>`. The view shows **individual records** — the rows *behind* the chart — not the chart's aggregated buckets. It uses `DetailViewShell` + `RecordsTable`.
+
+## What gets generated
+
+For each chart widget `Foo`, the build generates `src/dashboard/views/FooView.tsx` and registers its route in `App.tsx`.
+
+Detail views are generated for:
+
+- **Chart widgets** (`line-chart`, `area-chart`, `bar-chart`, `donut-chart`, `multi-line-chart`, `rate-chart`) — any tier — at `/<foo>`. Every chart module **must** export `fetchDetail` (the build hard-fails with `CHART_DETAIL_MISSING` otherwise) **unless** its registry entry sets `"noDetail": true`. A `noDetail` chart (endpoint returns only pre-aggregated data) gets no view and renders a non-clickable card.
+- **KPI cards with `detail: true`** — at `/<foo>`. The card becomes clickable (cursor-pointer + a "View all" link) and the module must export `fetchDetail`. A plain KPI (no `detail`) links nowhere.
+- **Tables with a `rowLink`** (see below). A plain table (no `rowLink`) links nowhere and shows its rows in place.
+
+> **Contract:** every widget that emits a navigation link must have a generated view + route, and vice-versa — `widgetGetsDetailView()` in the build is the single decision. Never emit `navigate()` / `ViewAllLink` / `onRowClick` without the build generating the matching view.
+
+## Row-click drill-down (tables)
+
+A `data-table`/`ranked-table` metric with `rowLink: { key: "<rowField>" }` becomes clickable: clicking a row navigates to `/<widget>/:key` (the clicked row's `<rowField>` is the `:key`). The build generates `views/<Widget>DetailView.tsx`, which reads the route param and calls the module's **`fetchDetailByKey(sdk, key, getToken)`** (type `MetricDetailByKeyFn`). Use it to show the entity behind the row — e.g. click an agent → that agent's most-recent trace's spans (recipe in `sdk/orchestrator.md`).
+
+- The module exports BOTH `fetchData` (the table rows) and `fetchDetailByKey` (the per-key drill-down).
+- `detailColumns` (optional) styles the detail table; without it columns auto-detect.
+- The detail page has a back link via `DetailViewShell`.
+
+## Record grain — the detail must add information
+
+The chart's `fetchData` returns **aggregated buckets** (e.g. `{ date, count }`). A detail view that re-tables those buckets adds nothing. So the module supplies a separate record-grain query:
+
+- **`fetchDetail: MetricFn`** (in the same module) — fetches the individual records (e.g. each faulted job: `{ processName, state, createdTime, ... }`). The view runs this, not the chart's aggregate. It is **required** for every chart (and `detail: true` KPI); the build hard-fails with `CHART_DETAIL_MISSING` if it is missing and the registry isn't `noDetail`. For cataloged metrics the registry entry's `detailRecipe` gives the exact SDK call.
+- **`detailColumns`** — `{ key, label, align?, format?, color? }[]`. `format`: `number` | `percent` | `duration` | `timeAgo` | `text`; `color`: `goodHigh` | `goodLow`. The build compiles these into formatted/coloured `render` functions. Set on the metric, or inherit the registry entry's `defaults.detailColumns` (cataloged charts ship them). If neither is present, columns are auto-detected from the first row at runtime (`autoColumns`) — workable but generic.
+- **`detailSortKey`** — the raw field to sort on (e.g. ISO `createdTime`). Render a friendly label in the column but sort on the raw value so chronological order is correct.
+
+## toRows() — safe array extraction
+
+The generated view calls `toRows(data)` before `RecordsTable`, handling `{ items: [...] }`, `{ data: [...] }`, a nested `data` object, or a top-level array. Defined inside every view file — no import needed.
+
+## Rich detail views (charts)
+
+A detail view can render multiple sub-widgets via an optional `detailView: { widgets: [...] }` on the metric. Each sub-widget declares:
+
+- `displayAs` — `donut-chart` | `bar-chart` | `area-chart` | `line-chart` | `multi-line-chart` | `data-table` | `ranked-table`
+- `title` — sub-widget heading
+- `source` — key into the named-source map returned by the detail fetch
+- Chart sub-widgets: `xKey` + `yKey`; multi-line uses `xKey` + `series[]` (`[{key,color,label?}]`)
+- Table sub-widgets: optional `columns` (`{ key, label, align?, format?, color? }[]`)
+
+> Sub-widgets are NOT limited to donuts. `bar-chart`, `area-chart`, `line-chart`, and `multi-line-chart`
+> (with `series`) are fully wired — see the `agent-compliance-report` detailView in
+> `assets/scripts/dashboards/capability-registry.json` for a `multi-line-chart` (Pass vs Matched by hook) + `donut-chart`
+> + `ranked-table` + `data-table` in one view.
+
+The detail fetch (`fetchDetailByKey` for `rowLink`, `fetchDetail` for a `detail: true` chart/KPI) must return a **named-source map** `{ rows, byHook, byRule, … }` whose keys match each sub-widget's `source`. A bare array = legacy single-table behaviour (the view normalizes `array → { rows }`).
+
+Charts render via presentational components in `@/dashboard/charts` (`Donut` / `Bars` / `TrendArea` / `MultiLine`); tables via `RecordsTable`. Each sub-widget renders its own EmptyState when its `source` is empty.
+
+The RICH multi-widget `detailView` is valid only on a metric with `rowLink.key` (table) or `detail: true` (chart/KPI). A **basic** chart drill-down (single records table) needs only `fetchDetail` — no `detailView` and no `detail` flag.
+
+## Anti-patterns
+
+- **Never** ship a chart detail view backed by the chart's aggregate `fetchData` — export `fetchDetail` so the drill-down shows records. The build hard-fails (`CHART_DETAIL_MISSING`) if you forget; the only opt-out is a registry `noDetail` chart.
+- **Never** sort a time column on its rendered label — key the sort on the raw ISO field via `detailSortKey`.
+- **Never** emit `navigate()` / `ViewAllLink` from a widget the build won't generate a view for.
+- **Never** declare the rich `detailView` on a metric without `rowLink.key` or `detail:true` — the build rejects it.
+- **Never** return an aggregate-only array when `detailView` declares chart sources — return the named-source map so each sub-widget has data.

package/skills/uipath-coded-apps/references/dashboards/primitives/incremental-editor.md

@@ -0,0 +1,92 @@
+# Incremental Editor
+
+Handles ADD / REMOVE / CHANGE / REBUILD / UPGRADE / EJECT requests on existing dashboards.
+
+## Trigger
+
+Detects `.dashboard/state.json` at session start or after `BUILD_RESULT`. State schema: [state-file.md](state-file.md).
+
+> **Regime gate (check first).** Read `state.regime`. If it is `"ejected"`, the structured edit-script is **disabled** — it emits `EJECTED_PROJECT` and exits non-zero rather than regenerate over hand work. Edit the project's `src/` directly per the request, then `npm run build`. Only `compiler-managed` (or absent/legacy) dashboards use the ops below. See [customization.md](customization.md#regimes-compiler-managed-vs-ejected).
+
+> **Precondition:** the project must still contain the extracted starter kit, including `_gen/widgets/` (the widget generator templates the build reads). It's there from the initial build; if the project dir was wiped, the build fails loud with the extract command — re-extract the kit (or run a fresh build) before editing. See `plugins/build/impl.md § The starter-kit archive`.
+
+## edit-intent.json schema
+
+Write `edit-intent.json` **inside the project directory** (the dir that holds `.dashboard/state.json`). **Multiple changes = ONE `ops` batch — never run the script once per change.** The whole batch is validated up front (nothing is written if any op would fail), applied in order, and Dashboard.tsx/index.ts + tsc run once at the end.
+
+> **Path safety — never reconstruct the project's absolute path.** Reuse the directory the build already created (where `.dashboard/state.json` lives) and work with **relative** paths: `cd` into the project, set `"projectDir": "."`, and pass a relative `edit-intent.json` to the script. Do NOT retype or rebuild a `/tmp/…` sandbox path — the sandbox hash can differ by a single character (e.g. `_` vs `-`), and a mistyped absolute path silently writes the edit to a sibling directory the build never created, so the change appears to succeed but lands nowhere the project (or the graders) can see it.
+
+`edit-intent.json` carries **metadata only** — no `fnBody` fields. Data-fetch code ships as `metrics/<name>.ts` modules sibling to `edit-intent.json`.
+
+```json
+{
+  "projectDir": ".",
+  "ops": [
+    { "op": "CHANGE", "target": "MemoryCallsTrend", "delta": { "displayAs": "bar-chart" } },
+    { "op": "REMOVE", "target": "AgentConsumption" },
+    { "op": "ADD", "metric": { "name": "agent-health", "tier": "T1", "title": "Agent Health" } }
+  ]
+}
+```
+
+Op shapes:
+- **ADD** — `metric` is a full intent.json metric entry (metadata only, no `fnBody`). Also write `metrics/<name>.ts` module alongside `edit-intent.json` — the build copies it in.
+- **REMOVE** — `target` is the widget component name from state.json. Also delete the corresponding `metrics/<name>.ts` module.
+- **CHANGE** — `delta` merges over the widget's persisted `intentMetric`. Metadata-only changes (e.g. `displayAs`, `title`) leave the existing module in place. Changing query logic requires shipping a new `metrics/<name>.ts` module alongside the op.
+- **REBUILD** — no fields; regenerates every widget from persisted `intentMetric` + the on-disk `metrics/*.ts` modules (e.g. after template updates). No module changes needed unless also updating queries. **Stop the dev server before REBUILD on Windows** — a running Vite holds every widget file open, so the rewrite hits `EPERM`/`EBUSY`. The build retries the rename and falls back to an in-place overwrite, but to avoid the race entirely, stop the dev server first and prefer scoped `CHANGE` ops for single-widget edits.
+- **UPGRADE** — `{ "projectDir": "...", "op": "UPGRADE" }` (no target/metric; run it as a lone op, never batched). Refreshes the disposable scaffold framework to the current version, migrates `intent.json`, regenerates all widgets/views from persisted metadata + on-disk modules, re-validates (Stage A + full tsc), and re-stamps `state.versions`. Preserves `intent.json`, `src/metrics/*.ts`, and `uipath.json` (the SDK config incl. deploy `clientId`). See "Offer-on-detect upgrade" below. If Stage A fails after the kit refresh because a module imports a lib the current scaffold doesn't ship, rewrite that module against the current SDK references — never hand-restore a lib into the scaffold.
+- **EJECT** — `{ "projectDir": "...", "op": "EJECT" }` (lone op, never batched). Flips `state.regime` to `"ejected"` and emits `EJECTED` — no files regenerated. One-way: after this the edit-script refuses (`EJECTED_PROJECT`) and you edit `src/` directly + `npm run build`. Use when a request exceeds the declarative surface. See [customization.md](customization.md#regimes-compiler-managed-vs-ejected).
+
+A single-op shorthand (`{ "op": "ADD", "projectDir": "...", "metric": ... }`) is also accepted.
+
+## Run command
+
+Run from **inside the project directory** (the one holding `.dashboard/state.json` — reference it relatively, e.g. `cd <ROUTING_NAME>`, never a retyped `/tmp/…` path), with `edit-intent.json` written there and `"projectDir": "."`:
+
+```bash
+cd "<PROJECT_DIR>" && node "${SKILL_BASE_DIR}/assets/scripts/dashboards/build-dashboard.mjs" edit-intent.json
+```
+
+The script resolves both `projectDir` (`.`) and the relative `edit-intent.json` against this directory, so there is no absolute sandbox path to mistype. (`${SKILL_BASE_DIR}` is the skill's own install dir — unrelated to the project — and is safe to use as-is.)
+
+## CHANGE semantics
+
+Each widget's full intent metric (title, display hints) is persisted in `state.json` at build time. CHANGE merges your `delta` over it, so a delta only needs the fields that change. The data-fetch code lives in the on-disk `src/metrics/<name>.ts` module.
+
+1. **Changing the time window requires a new module.** The module imports time constants by name (e.g. `THIRTY_DAYS_AGO`) from `@/lib/time` — a `timeRange` delta alone updates the subtitle but not the query window. Ship an updated `metrics/<name>.ts` using the matching constant (`SEVEN_DAYS_AGO` for 7d, etc.) alongside the delta.
+2. Changing `displayAs` between chart ↔ table/kpi is supported — the build regenerates or removes the detail view accordingly.
+3. **Legacy dashboards** (built before intent persistence) have no stored `intentMetric` — the build fails with a clear message; include the full metric (title, display hints) in `delta` and ship a fresh module, or re-run a fresh build.
+
+## Stage A type-check
+
+Before applying any op, the build type-checks all affected `metrics/*.ts` modules in isolation (Stage A).
+- `METRICS_PASS` — silent; batch proceeds.
+- `METRICS_RETRY:{ files: [...], errors: [...] }` — fix the named `src/metrics/<name>.ts` files and re-run. Max 2 attempts; if still failing, drop the metric.
+
+## Events to watch
+
+- `HAND_EDIT_DETECTED:{"widget":"X"}` — file was hand-edited; the whole batch is rejected before any write. Ask the user (see [customization.md](customization.md)).
+- `METRICS_PASS` — silent; proceed
+- `METRICS_RETRY:{"files":[...],"errors":[...]}` — fix named module files and re-run
+- `TSC_PASS` — edit validated clean
+- `TSC_FAIL:{"errors":"..."}` — surface to user
+- `INCREMENTAL_READY:{"count":N,"ops":[{"op":"ADD","widget":"X"},…]}` — done; the running dev server hot-reloads automatically. If no dev-server background job is running, start one per `plugins/build/impl.md` Phase 4 Step 3 (the script never starts servers).
+- `UPGRADE_AVAILABLE:{"from":"1.0.0","to":"1.1.0"}` — the shipped scaffold is newer than this dashboard's. Offer to upgrade (below) — never auto-upgrade.
+- `UPGRADE_DONE:{"to":"1.1.0","widgets":[...]}` — upgrade complete; the dev server hot-reloads.
+- `EJECTED:{"projectDir":"..."}` — eject succeeded; dashboard is now full-source/agent-edited. Stop using the edit-script; edit `src/` + `npm run build`.
+- `EJECTED_PROJECT:{"projectDir":"..."}` — you ran the edit-script on an already-ejected project; it refused. Edit source directly instead.
+
+## Offer-on-detect upgrade
+
+Any build or edit against an existing project emits `UPGRADE_AVAILABLE:{from,to}` when its stamped `scaffold` version differs from the one now shipped. Tell the user a newer dashboard scaffold is available and offer to upgrade — same plan→confirm ethos, **never automatic**. On confirm, run a lone `UPGRADE` op. It preserves their metrics (`intent.json` + `src/metrics`) and regenerates the app framework against the current scaffold.
+
+## Rules
+
+0. **Customized project?** If the user hand-edited files (or asks for look-and-feel changes), read [customization.md](customization.md) BEFORE running any edit-intent — the build regenerates `Dashboard.tsx` + `widgets/index.ts` on every op and would wipe their changes.
+1. Only regenerate affected widget files — never the full scaffold.
+1b. **Batch every multi-widget request into one `ops` array** ("convert everything to charts" = one run with N CHANGE ops, not N runs). One layout regen, one tsc.
+2. Routing name never changes on edit.
+3. After REMOVE or CHANGE: always regenerate Dashboard.tsx and widgets/index.ts (the build does this automatically).
+4. Chart widgets get their detail view regenerated on ADD/CHANGE/REBUILD automatically — never hand-create views.
+5. Do not touch `uipath.json` unless user explicitly requests a config change.
+6. **Never reconstruct the project's absolute path.** Run the edit from inside the project (`cd <ROUTING_NAME>`, `"projectDir": "."`, relative `edit-intent.json`). A retyped `/tmp/…` sandbox path — off by even one character (`_`↔`-`) — writes the edit to a sibling directory, so it silently no-ops. See § edit-intent.json schema (Path safety).

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

@@ -0,0 +1,64 @@
+# State File — .dashboard/state.json
+
+Per-project metadata. Read at every build start. Written by build script on success.
+
+## Schema
+
+```json
+{
+  "schemaVersion": 2,
+  "versions": { "skill": "2.0.0", "scaffold": "1.0.0", "intentSchema": 2, "sdk": "1.5.0" },
+  "regime": "compiler-managed",
+  "app": {
+    "name": "Operations Health Dashboard",
+    "routingName": "operations-health-x7k2",
+    "semver": "1.0.0"
+  },
+  "env": "alpha",
+  "org": "appsdev",
+  "tenant": "appsdevDefault",
+  "cloudUrl": "https://alpha.uipath.com",
+  "timeRange": "30d",
+  "widgets": {
+    "MemoryCallsTrend": {
+      "hash": "a3f7b2c1",
+      "tier": "T1",
+      "metric": "memory-calls-trend",
+      "template": "area-chart",
+      "module": "metrics/memory-calls-trend.ts",
+      "intentMetric": { "name": "memory-calls-trend", "tier": "T1", "title": "Memory Calls" }
+    },
+    "AgentHealth": {
+      "hash": "c9e1d4f2",
+      "tier": "T1",
+      "metric": "agent-health",
+      "template": "ranked-table",
+      "module": "metrics/agent-health.ts",
+      "intentMetric": { "name": "agent-health", "tier": "T1", "title": "Agent Health" }
+    }
+  },
+  "deployment": {
+    "systemName": null,
+    "folderKey": null,
+    "folderName": null,
+    "appUrl": null,
+    "deployVersion": null,
+    "pinnedToGovernance": false,
+    "lastDeployedAt": null
+  },
+  "buildStatus": "complete"
+}
+```
+
+## Key rules
+
+1. `schemaVersion` is `2`. The `versions` block (`skill`/`scaffold`/`intentSchema`/`sdk`) records what the dashboard was built against; a `scaffold` mismatch with the shipped version drives the offer-on-detect upgrade.
+2. `widgets` is a map of `{ hash, tier, metric, template, module, intentMetric }` — not a string array.
+   - `intentMetric` is pure metadata (no `fnBody`) — title, display hints, tier, name. Used by CHANGE/REBUILD to regenerate without the original `intent.json`.
+   - `module` is the relative path to the durable data-fetch code (e.g. `"metrics/agent-health.ts"`). The live source lives at `src/metrics/<name>.ts` in the project.
+3. `routingName` never changes once set. Not even on upgrades.
+4. `hash` used for hand-edit detection — compare to current file before CHANGE/REMOVE.
+5. `deployment.systemName` set by deploy plugin on first deploy.
+6. `buildStatus` is `"in-progress"` from early in the build (so deploy can find app metadata even after a failed build) and `"complete"` on success.
+7. `timeRange` is the dashboard default window — incremental edits fall back to it when a CHANGE delta has no `timeRange`.
+8. `regime` is `"compiler-managed"` (default — declarative, edited via the structured edit-script) or `"ejected"` (full-source, edited free-form by the agent). The edit-script **refuses** to run on an ejected project (emits `EJECTED_PROJECT`). Eject is one-way: the `EJECT` op flips it and it never reverts. A template builds straight to `"ejected"`. Absent/legacy state with no `regime` is treated as `"compiler-managed"`. See [customization.md](customization.md#regimes-compiler-managed-vs-ejected).