@uipath/skills 1.196.0 → 1.197.0

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

@@ -26,7 +26,7 @@ Here's what your app needs:
 
 **OAuth scopes:** `<scopes>`
 
-**Redirect URI:** `http://localhost:5173` (computed automatically at runtime — works in both local dev and production)
+**Redirect URI:** `http://localhost:5173` (the local dev URL — stored as `redirectUri` in `uipath.json` and injected as the `uipath:redirect-uri` meta tag; the platform injects the production URI automatically at deploy)
 
 Please answer these questions to continue:
 
@@ -45,6 +45,10 @@ Please answer these questions to continue:
    - If yes, paste it
    - If no, say **"create one"** and I'll set it up via browser automation
 
+**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
+   - `no` — Tailwind only; bring your own component library
+
 ---
 
 **Wait for the user's reply before proceeding.**
@@ -87,51 +91,83 @@ Then `cd` into `<app-name>`. Every subsequent step runs from this directory.
 
 ### 4.3 — Install dependencies
 
-Run these as **two separate commands** in order. The `--@uipath:registry` flag binds only to the first command (the SDK install) — do not apply it to the second, and do not run a bare `npm install` with the flag.
+Run these as **separate commands** in order. The `--@uipath:registry` flag binds only to commands installing `@uipath/*` packages — do not apply it to the others, and do not run a bare `npm install` with the flag.
+
+**Common (always run):** both Q6 paths use `new UiPath()` (no config) — the SDK reads `clientId`, `scope`, `orgName`, `tenantName`, `baseUrl`, and `redirectUri` from `<meta name="uipath:*">` tags injected by `@uipath/coded-apps-dev` (locally) or by the platform (in production). Tailwind is shared too.
 
 ```bash
-# 1. UiPath SDK (registry flag forces public npm to bypass GitHub Packages auth)
+# UiPath SDK (registry flag forces public npm to bypass GitHub Packages auth)
 npm install @uipath/uipath-typescript --@uipath:registry=https://registry.npmjs.org
 
-# 2. Remaining runtime + Tailwind dependencies
-npm install path-browserify tailwindcss@3 postcss autoprefixer
+# coded-apps-dev Vite plugin — injects <meta name="uipath:*"> tags from
+# uipath.json so `new UiPath()` (no config) works in local dev
+npm install -D @uipath/coded-apps-dev --@uipath:registry=https://registry.npmjs.org
+
+# Tailwind — shared across both Q6 paths
+npm install -D tailwindcss@4 @tailwindcss/postcss postcss autoprefixer
 ```
 
-> **Why the registry flag?** Users may have `@uipath` scoped to GitHub Packages in their `.npmrc`, which requires authentication and causes a 401. The flag forces `@uipath/uipath-typescript` to install from the public npm registry.
+> **Why the registry flag?** Users may have `@uipath` scoped to GitHub Packages in their `.npmrc`, which requires authentication and causes a 401. The flag forces `@uipath/*` packages to install from the public npm registry.
+
+**Then branch on the Q6 styling answer for the component layer only:**
+
+- **If `default styling = yes`** *(recommended)* — apollo-wind brings Apollo Vertex tokens, dark-mode toggle, and React components:
+
+  ```bash
+  # apollo-wind + apollo-core (UiPath design system, public on npm)
+  npm install @uipath/apollo-wind @uipath/apollo-core --@uipath:registry=https://registry.npmjs.org
+
+  # Theme toggle deps
+  npm install next-themes lucide-react
+  ```
+
+- **If `default styling = no`** — keep the SDK + Tailwind baseline above and bring your own component library. No extra dependencies needed.
 
 ### 4.4 — Remove Vite defaults that will be overwritten
 
-`npx create-vite` ships default versions of three files we replace in Step 4.5. Delete them first so the Write tool can create them fresh — otherwise each Write requires a Read-first round-trip and produces a benign-but-noisy "Error writing file" message.
+`npx create-vite` ships default versions of files we replace in Step 4.5. Delete them first so the Write tool can create them fresh — otherwise each Write requires a Read-first round-trip and produces a benign-but-noisy "Error writing file" message.
 
-```bash
-rm vite.config.ts src/App.tsx src/index.css
-```
+- **`default styling = yes`** — also overwrites `src/main.tsx` to wrap `<App>` in the theme provider:
+
+  ```bash
+  rm vite.config.ts src/App.tsx src/index.css src/main.tsx
+  ```
+
+- **`default styling = no`**:
+
+  ```bash
+  rm vite.config.ts src/App.tsx src/index.css
+  ```
 
 ### 4.5 — Write project files from templates
 
 All file content lives in [../assets/templates/web-app-template.md](../assets/templates/web-app-template.md). For each row below, copy the named section from that file verbatim into the path shown, applying the listed substitutions. Create `src/hooks/` first; the rest of the directories already exist from `create-vite`.
 
-| Path | Template section | Substitutions |
-|------|------------------|---------------|
-| `vite.config.ts` | `## vite.config.ts` | none |
-| `uipath.json` | `## uipath.json` | `{{SCOPES}}`, `{{CLIENT_ID}}` |
-| `.env` | `## .env` | `{{CLIENT_ID}}`, `{{SCOPES}}`, `{{ORG_NAME}}`, `{{TENANT_NAME}}`, `{{BASE_URL}}` |
-| `.env.example` | `## .env.example` | none |
-| `src/hooks/useAuth.tsx` | `## src/hooks/useAuth.tsx` | none |
-| `src/App.tsx` | `## src/App.tsx` | none |
-| `tailwind.config.js` | `## tailwind.config.js` | none |
-| `postcss.config.js` | `## postcss.config.js` | none |
-| `src/index.css` | `## src/index.css` | none |
+**Pick the template-section column based on the Q6 styling answer.** When the column says `—`, skip that row entirely (the file isn't needed on that path). `uipath.json` and `useAuth.tsx` are shared verbatim — the same SDK init (`new UiPath()` no config) runs on both paths.
 
-### 4.6 — Append `.env` to `.gitignore`
+| Path | Template section — `default styling = yes` | Template section — `default styling = no` | Substitutions |
+|------|---|---|---|
+| `vite.config.ts` | `## vite.config.ts` | `## vite.config.ts` | none |
+| `uipath.json` | `## uipath.json` | `## uipath.json` | `{{CLIENT_ID}}`, `{{SCOPES}}`, `{{ORG_NAME}}`, `{{TENANT_NAME}}`, `{{BASE_URL}}` |
+| `src/hooks/useAuth.tsx` | `## src/hooks/useAuth.tsx` | `## src/hooks/useAuth.tsx` | none |
+| `src/components/Theme.tsx` | `## src/components/Theme.tsx (Q6 = yes only)` | — | none |
+| `src/main.tsx` | `## src/main.tsx (Q6 = yes only)` | — | none |
+| `src/App.tsx` | `## src/App.tsx` → `### Q6 = yes (apollo-wind)` | `## src/App.tsx` → `### Q6 = no (bare Tailwind)` | none |
+| `postcss.config.js` | `## postcss.config.js` → `### Q6 = yes (apollo-wind)` | `## postcss.config.js` → `### Q6 = no (bare Tailwind)` | none |
+| `src/index.css` | `## src/index.css` → `### Q6 = yes (apollo-wind)` | `## src/index.css` → `### Q6 = no (bare Tailwind)` | none |
 
-```bash
-echo ".env" >> .gitignore
-```
+> **No `tailwind.config.js` on either path** — Tailwind configuration lives directly in `src/index.css`. No `.env` file either — `uipath.json` (committed) is the single config source for the SDK.
+
+### 4.6 — `.gitignore`
+
+Neither path writes a `.env`, and `uipath.json` is committed (it holds the SDK config — a public OAuth client ID plus org/tenant/base-URL/redirect-URI, no secrets), so no `.gitignore` change is needed for OAuth config. The project `.uipath/` directory created by `codedapp` commands must stay gitignored — it is covered by `npx create-vite`'s default plus `uip codedapp`'s conventions. Verify with `cat .gitignore | grep -i uipath` and add `.uipath/` if missing.
 
 ### 4.7 — Verify the scaffold
 
-First, confirm all files exist: `vite.config.ts`, `uipath.json`, `.env`, `.env.example`, `tailwind.config.js`, `postcss.config.js`, `src/hooks/useAuth.tsx`, `src/App.tsx`, `src/index.css`. If any are missing, re-run the corresponding row from Step 4.5.
+First, confirm all expected files for your Q6 branch exist. If any are missing, re-run the corresponding row from Step 4.5.
+
+- **`default styling = yes`:** `vite.config.ts`, `uipath.json`, `postcss.config.js`, `src/index.css`, `src/hooks/useAuth.tsx`, `src/components/Theme.tsx`, `src/main.tsx`, `src/App.tsx`
+- **`default styling = no`:** `vite.config.ts`, `uipath.json`, `postcss.config.js`, `src/index.css`, `src/hooks/useAuth.tsx`, `src/App.tsx`
 
 Then run `npm run build` to verify the scaffold compiles and SDK imports resolve:
 
@@ -175,6 +211,8 @@ const records = await entities.getAllRecords('<entity-id>'); // entity ID is a U
 
 See [oauth-scopes.md](oauth-scopes.md) for the full list of methods and their required scopes.
 
+If the user wants a **Document Understanding validation UI** (review/correct extraction results), embed the Validation Station widget — see [widgets/validation-station.md](widgets/validation-station.md). Required scope: `OR.Buckets` (plus `OR.Tasks` if the widget completes an Action Center task on save). Add to the `scope` field in `uipath.json` during scaffold (Step 1).
+
 When implementing specific SDK services, read the corresponding reference:
 
 | Service | Reference |

package/skills/uipath-coded-apps/references/dashboards/CAPABILITY.md

@@ -0,0 +1,179 @@
+# Dashboard Capability
+
+Build, edit, or deploy UiPath dashboards powered by Insights RTM and the TypeScript SDK.
+
+---
+
+## Step 0 — Detect intent BEFORE loading anything
+
+Read the user's message and classify it as one of three intents. **Do not load any files yet.**
+
+| User says | Intent | What to do next |
+|-----------|--------|-----------------|
+| "build me a dashboard", "show me X metrics", "create a dashboard for…" | **BUILD** | Follow the Build path below |
+| "add/remove/change a widget", "update the chart", "make it 7 days" | **EDIT** | Follow the Edit path below |
+| "deploy this", "publish it", "make it live", "ship it to the team", "deploy the dashboard" | **DEPLOY** | Follow the Deploy path below |
+
+If the intent is unclear, ask one question — "What do you want to do with the dashboard?" — as a **structured choice** (SKILL.md Critical Rule 18: native question tool with selectable options when the host agent has one, else a numbered list):
+
+| Option | Description |
+|--------|-------------|
+| **Build a new dashboard** | Describe metrics in plain language, get a live dashboard |
+| **Edit the existing one** | Add/remove/change widgets or time ranges |
+| **Deploy it** | Publish to Automation Cloud |
+
+---
+
+## Path A — BUILD (new dashboard)
+
+## Turn 2 output — Show the plan (zero tool calls, zero intermediate output)
+
+After the blocking file reads + state check complete (login status and pre-warm run in the background — don't wait on them), output the plan as the first and only text.
+
+**The user should see nothing between their request and the plan.** No "Reading files…", no "Checking login…", no "Starting pre-warm…". Pure silence then the plan.
+
+If you need to show something, show only the plan.
+
+### Turn 2 — Everything in ONE parallel message
+
+Fire all of these simultaneously. Use multiple tool calls in one response — do not wait for one before starting another.
+
+> **Path note:** All file paths are relative to `SKILL_BASE_DIR` — the directory where `SKILL.md` lives. Not relative to this file's location.
+
+**File reads (parallel) — fire all in one message:**
+
+| File | Purpose |
+|------|---------|
+| `references/dashboards/plugins/build/impl.md` *(from skill root)* | Build instructions, plan format, intent.json schema |
+| `references/dashboards/primitives/tier-resolution.md` *(from skill root)* | Metric classification and SDK validation rules |
+| `references/dashboards/aesthetic/layout-patterns.md` *(from skill root)* | Layout rules |
+| `references/dashboards/aesthetic/charting.md` *(from skill root)* | Chart-type selection, colour tokens, delta polarity |
+| `assets/scripts/dashboards/capability-registry.json` *(from skill root)* | Metric catalog (T1/T2 display hints) |
+| `references/sdk/agents.md` *(from skill root)* | Agents + Agent Memory (Insights RTM, SDK ≥ 1.4.1) — validate agent/memory metrics |
+| `references/sdk/orchestrator.md` *(from skill root)* | Jobs/Queues/Processes methods — validate job/process metrics |
+
+**Conditional reads (add to the same parallel message if the request mentions these):**
+
+| If user mentions | Also read |
+|-----------------|-----------|
+| tasks, action items | `references/sdk/action-center.md` *(from skill root)* |
+| cases, process instances, Maestro, SLA, top/slowest/failing processes or cases, element stats | `references/sdk/maestro.md` *(from skill root)* |
+| traces, spans, trace-level errors/latency/units | `references/sdk/traces.md` *(from skill root)* |
+| governance, policy, compliance, denials, blocked actions, allow/deny, enforcement | `references/sdk/governance.md` *(from skill root)* — Insights-API governance (`policy-denials`, `governance-verdicts`) |
+| **EXPLICIT runtime compliance / a standard or pack / ISO clause / "rule(s) violated"** (agent runs checked against standards) | `references/sdk/governance-traces.md` *(from skill root)* — gated, org-admin (`AgentTraces` governance decisions, SDK ≥ 1.5.1). Generic "governance/policy" stays on the row above |
+
+**1 blocking command (instant, local — routes build vs edit, so the plan needs it):**
+
+```bash
+node -e "
+const fs = require('fs')
+fs.existsSync('.dashboard/state.json') ? process.exit(0) : process.exit(1)
+" && echo INCREMENTAL || echo FRESH
+```
+
+**Login status — `run_in_background: true` (do NOT block the plan on it):** `uip login status` is only needed when building starts (the project's cloudUrl/org/apiUrl and to create the OAuth client) — never to present the plan. Fire it in the background alongside pre-warm; read its result in Phase 1 when you build.
+
+```bash
+uip login status --output json
+```
+
+**Pre-warm (same message — `run_in_background: true` on the Bash tool call):**
+
+Derive the routing name from the user's request now (e.g. `"agent health dashboard"` → `"agent-health-x7k2"`). The project lands at `<cwd>/<ROUTING_NAME>`. Pre-warm = **extract the starter kit there, then install deps** — both in the background. Extraction uses the OS `tar` (built into Windows 10+, macOS, Linux — identical on every platform, no hand-rolled code), feeding the archive on **stdin** (`-f -`) so GNU tar doesn't misread the `C:\…` drive colon as a remote host (see `plugins/build/impl.md § The starter-kit archive`). One background call (chain with `&&`):
+
+```bash
+mkdir -p "<ROUTING_NAME>" && tar -xz -C "<ROUTING_NAME>" -f - < "<SKILL_BASE_DIR>/assets/fixtures/governance-dashboard-starter-kit.tar.gz" && node "<SKILL_BASE_DIR>/assets/scripts/dashboards/build-dashboard.mjs" --prewarm "<ROUTING_NAME>"
+```
+
+The extract is fast; `--prewarm` then runs `npm ci` (the slow part) so it overlaps plan approval. ⚠️ `run_in_background: true` is a tool call parameter, not a shell flag. Without it, the call blocks before the plan appears.
+
+> **What the user should see:** Only the plan text. Nothing else — not file reads, not login output, not pre-warm status, not bash results, and no question popup. If there is ANY output before the plan, or any tool call in the plan response, that is a bug.
+
+**After all reads:** output the plan as **pure text** and stop — zero tool calls in the plan response. The user replies with feedback or confirmation; setup questions (OAuth client ID, via the structured-choice tool) come only AFTER the plan is approved, and only for details the confirmation didn't already provide. See `plugins/build/impl.md` Phases 2–3.
+
+**Routing:**
+- `INCREMENTAL` → read `primitives/incremental-editor.md`, then follow it
+- `FRESH` → follow `plugins/build/impl.md`
+
+---
+
+## Path B — EDIT (change existing dashboard)
+
+**Check `regime` in `.dashboard/state.json` first.** If `regime` is `"ejected"` (or the project is a template — full source, no compiler state), do NOT use the edit-script: edit the `src/` files directly per the request, then `npm run build`. The structured ops below apply only to `compiler-managed` (or absent/legacy) dashboards. See `primitives/customization.md` (Regimes).
+
+For a compiler-managed dashboard, read `primitives/incremental-editor.md` in the same message as `uip login status --output json`. Follow it.
+
+**Also read `primitives/customization.md` first** when the user asks for look-and-feel changes (theme, layout, styling, "make it look…") or the project shows hand edits — it defines what the build script overwrites, when to **eject** (one-way switch to full-source editing), and when to edit the project directly instead of running the script.
+
+---
+
+## Path C — DEPLOY
+
+### Step 1 — Read the deploy plugin FIRST (before any CLI commands)
+
+```
+Read: references/dashboards/plugins/deploy/impl.md  *(from skill root)*
+```
+
+Read this file in parallel with:
+
+```bash
+uip login status --output json
+```
+
+**Do not run any other commands until you have read the deploy plugin and presented the plan to the user.**
+
+### Step 2 — Present the deploy plan (pure text, zero CLI calls)
+
+Read `.dashboard/state.json` in memory to get the app name, version, and routing name. First determine the deployment target — **governance/admin dashboard** vs **standard dashboard app** — per `plugins/deploy/impl.md` Step 0. The folder line and the pin question depend on it.
+
+```
+Your **[Dashboard Name]** is ready to be deployed.
+
+📦  Version:    [current] → [bumped]
+🔗  URL path:   [routing-name]
+📁  Folder:     [AdminDashboards (governance) | user-chosen folder (standard)]
+🔄  Type:       Fresh deploy  OR  Updating existing deployment
+
+📌  (governance only) Do you want to pin this dashboard to the Governance UI?
+   → "deploy and pin" — visible in the Governance section
+   → "deploy" — deploy without pinning
+```
+
+A standard dashboard deploys to a user-chosen folder with no pin question — see impl.md Step 4.
+
+> ⚠️ Pinning surfaces the dashboard in the Governance section, which is an **Agentic Governance preview** feature — it only takes effect if the org is enrolled in the preview. When offering the pin, say so; either way the dashboard deploys and is reachable at its URL. See `plugins/deploy/impl.md` Step 4 / Step 10.
+
+**HALT. Do not run any CLI command until the user confirms.**
+
+### Step 3 — Follow plugins/deploy/impl.md
+
+After user confirms, follow every step in `plugins/deploy/impl.md` exactly as written. Do not invent steps, do not run `uip tools list`, do not run `npm run build` before the plan is confirmed.
+
+---
+
+## Scope
+
+This skill only handles dashboard building, editing, and deploying. For anything else, respond:
+
+> "This skill is for UiPath dashboard generation only. For [what they asked], please use the appropriate skill."
+
+---
+
+## Hard stops
+
+- **Never** show raw tool call outputs to the user — read results in context, surface only meaningful information
+- **Never** echo raw event names (WIDGET_READY, TSC_PASS, BUILD_RESULT, etc.) — translate them to clean progress lines
+- **Never** show intermediate bash command outputs between the user's request and the plan — the plan is the first visible output
+- **Never** call any tool — including the question/option tool — in the same response as the plan. The plan is pure text; the user replies to it; structured setup questions (OAuth, deploy pin) fire only after approval and only for details the user hasn't already given
+- **Never** run ANY CLI command before presenting the plan and getting user confirmation
+- **Never** improvise deploy steps — always read `plugins/deploy/impl.md` first
+- **Never** run `uip tools list`, `npm run build`, or any command not in the relevant impl.md
+- **Never** use `"agent-health-dashboard"` (routing slug) as the `-n` flag — always use the human-readable display name from state.json
+- **Never** run `uip codedapp publish` without `-n` and `--version` flags
+- **Never** fetch the live SDK docs URL — it takes 60–90s
+- **Never** read `build-dashboard.mjs` — documented in impl.md
+- **Never** run directory exploration via ANY shell — `ls`, `find`, `dir`, `Get-ChildItem`, `tree`, glob loops. Memory or prior-session hints are not a reason to explore; the state.json check is the only existing-work probe
+- **Never** read files one at a time
+- **Never** commit generated dashboard files
+- **Never** auto-deploy without explicit user confirmation

package/skills/uipath-coded-apps/references/dashboards/aesthetic/charting.md

@@ -0,0 +1,138 @@
+# Charting Guide
+
+How to pick chart types, configure colors, and avoid common mistakes.
+
+---
+
+## Chart Type Selection
+
+Valid `displayAs` values (the build accepts only these): `kpi-card`, `ranked-table`, `data-table`, `area-chart`, `line-chart`, `bar-chart`, `donut-chart`, `multi-line-chart`, `rate-chart`.
+
+| User's metric | Use this | Why |
+|---|---|---|
+| Single number at a point in time | `kpi-card` | No trend needed |
+| One metric over time (count, sum) | `area-chart` | Shows volume and trend |
+| One metric over time (already a value series) | `line-chart` | Trend without fill weight |
+| Ratio/percentage over time (numerator ÷ denominator) | `rate-chart` | Computes per-bucket %, % axis, pp delta |
+| Comparing categories (bars) | `bar-chart` | Items to compare |
+| Ranked list with a score | `ranked-table` | 5+ items, sortable |
+| Part-of-whole proportions (≤5 categories) | `donut-chart` | Parts sum to 100% |
+| Part-of-whole proportions (5+ categories) | `bar-chart` | Donut with 5+ slices is unreadable |
+| Two metrics on the same time axis | `multi-line-chart` | Comparison over time |
+| Raw records, drill-down detail | `data-table` | Operational view |
+
+---
+
+## Color Rules
+
+### Always use CSS variable tokens
+
+```tsx
+// Correct
+fill="hsl(var(--chart-1))"
+stroke="hsl(var(--chart-2))"
+
+// Wrong — hardcoded hex
+fill="#FA4616"
+stroke="#0066CC"
+```
+
+### Chart color series meaning
+
+| Token | Color | Semantic use |
+|---|---|---|
+| `--chart-1` | UiPath orange | Primary data series, main metric |
+| `--chart-2` | UiPath blue | Secondary series (e.g., P95 alongside P50) |
+| `--chart-3` | Success green | "Up is good" deltas, completion rates |
+| `--chart-4` | Warning amber | Approaching threshold, mid-risk |
+| `--chart-5` | Error red | Errors, failures, "down is good" |
+
+For multi-line charts (P50/P95):
+- P50 → `--chart-1` (orange, primary)
+- P95 → `--chart-2` (blue, secondary)
+
+---
+
+## Area vs Line
+
+- **Area chart** (`area-chart`) → for volume metrics (count, invocations, AGU consumed)
+  - Always use `fillOpacity={0.2}` to keep the area subtle
+  - Fill and stroke use `--chart-1`
+
+- **Line chart** (`line-chart`) → for rate/percentage metrics (error rate %, P95 latency)
+  - No fill area — rates don't accumulate visually
+  - `dot={false}` for smooth trend reading
+  - `strokeWidth={2}` minimum
+
+---
+
+## Delta polarity guide
+
+Deltas are **computed at runtime** — never hand-write delta text. You set one intent field per chart metric, `deltaPolarity`, which answers: is an increase good for this metric?
+
+| Metric | `deltaPolarity` |
+|---|---|
+| Success rate, health score | `up-good` |
+| Error count, failure rate | `up-bad` |
+| AGU consumed (cost) | `up-bad` |
+| Run volume (activity proxy) | `up-good` |
+| Agent count (fleet growing) | `up-good` |
+| Incidents, denials | `up-bad` |
+| Memory counts (no inherent good direction) | `neutral` |
+
+The build computes the % change (or `pp` for `rate-chart`) between the last two buckets and colours the badge from the polarity. The badge is hidden automatically when there's not enough data.
+
+---
+
+## Recharts Configuration Standards
+
+```tsx
+// XAxis — always small font
+<XAxis dataKey="date" tick={{ fontSize: 11 }} />
+
+// YAxis — always small font, no label
+<YAxis tick={{ fontSize: 11 }} />
+
+// Tooltip — default, no custom content unless specific need
+<Tooltip />
+
+// ResponsiveContainer — standard heights
+// KPI sparkline: height={48}
+// Chart row widget: height={180}
+// Full-width chart: height={240}
+```
+
+---
+
+## Anti-patterns
+
+- Donut chart with >5 slices → use `bar-chart` instead
+- Line chart with <4 data points → use `bar-chart` instead (clearer)
+- Stacked bar unless values are genuinely parts-of-whole
+- Sparkline without a primary number above it
+- Hardcoded hex colors anywhere in chart config
+- `fillOpacity={1}` on area charts — too heavy
+- `dot={true}` on line charts with >30 data points — too noisy
+- XAxis with long date strings — format with `tickFormatter`
+
+---
+
+## Axis Date Formatting
+
+When x-axis is a date/time:
+
+```tsx
+// For hourly data (24h):
+<XAxis
+  dataKey="timeSlice"
+  tick={{ fontSize: 11 }}
+  tickFormatter={(v: string) => new Date(v).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}
+/>
+
+// For daily data (7d, 30d):
+<XAxis
+  dataKey="date"
+  tick={{ fontSize: 11 }}
+  tickFormatter={(v: string) => new Date(v).toLocaleDateString([], { month: 'short', day: 'numeric' })}
+/>
+```

package/skills/uipath-coded-apps/references/dashboards/aesthetic/layout-patterns.md

@@ -0,0 +1,152 @@
+# Layout Patterns
+
+Ten rules for dashboard layout. Follow them every time. Do not improvise.
+
+---
+
+## The 10 Rules
+
+### Rule 1 — Dashboard header is mandatory
+
+Every dashboard starts with a `<Header>` component:
+```tsx
+<Header
+  title="Agent Health Dashboard"
+  description="Agent invocation volume, error rates, and performance across your fleet."
+/>
+```
+
+The description must answer "what does this dashboard help you do?" in one sentence.
+Never leave it empty.
+
+### Rule 2 — KPI tiles come first
+
+KPI tiles (1–4 tiles) occupy the first row, always. Use a responsive grid:
+```tsx
+<div className="mt-6 grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+  {/* KPI widgets */}
+</div>
+```
+
+- 1 KPI → `lg:grid-cols-1`
+- 2 KPIs → `lg:grid-cols-2`
+- 3 KPIs → `lg:grid-cols-3`
+- 4 KPIs → `lg:grid-cols-4`
+
+Never put a chart in the KPI row.
+
+### Rule 3 — Charts come second, in a 2-up grid
+
+Charts (area, line, bar, donut, multi-line, rate) go in a 2-column grid:
+```tsx
+<div className="mt-6 grid grid-cols-1 lg:grid-cols-2 gap-4">
+  {/* Chart widgets */}
+</div>
+```
+
+If there are 3+ charts, they wrap to a second row — still `grid-cols-2`.
+If there is only 1 chart, it takes full width: `grid-cols-1`.
+
+### Rule 4 — Tables come last, full width
+
+Tables (data-table, ranked-table) always go at the bottom:
+```tsx
+<div className="mt-6">
+  <WidgetBoundary label="Top Agents">
+    <TopAgentsRankedTable />
+  </WidgetBoundary>
+</div>
+```
+
+Tables are `col-span-full` by default. Never put a table in a 2-up grid.
+
+### Rule 5 — Every widget is wrapped in WidgetBoundary
+
+```tsx
+<WidgetBoundary label="Active Agents">
+  <ActiveAgentsKPI />
+</WidgetBoundary>
+```
+
+The `label` is the human name of the widget — it shows in the error card if the widget throws.
+Never render a widget without WidgetBoundary.
+
+### Rule 6 — Gaps are always gap-4
+
+Use `gap-4` (16px) between ALL widgets on ALL rows. No exceptions, no per-widget overrides.
+
+### Rule 7 — Page padding is responsive
+
+```tsx
+<div className="min-h-screen bg-background text-foreground p-4 lg:p-8">
+```
+
+- Mobile: `p-4` (16px)
+- Desktop (lg+): `p-8` (32px)
+
+### Rule 8 — Rows are separated with mt-6
+
+Each row has `mt-6` (24px) top margin. The header has no margin below it.
+
+### Rule 9 — Never more than 4 widgets in the KPI row
+
+If the user requests 5+ KPIs, split into two rows. Never shrink tiles to fit more than 4.
+
+### Rule 10 — Card-level `cursor-pointer` only when the card navigates
+
+A card is `cursor-pointer` only when clicking the whole card opens a detail view:
+- **Chart cards** are clickable (unless the metric is a registry `noDetail` chart, which renders inert).
+- **KPI cards** are clickable only with `detail: true` (a record-grain drill-down); a plain KPI is not.
+- **Tables** are NOT `cursor-pointer` — individual rows can be clickable via `rowLink`, but the card wrapper is not.
+
+The build wires this automatically (empty detail route → non-clickable). Never hand-add `cursor-pointer` to a card that has no detail view.
+
+---
+
+## Dashboard.tsx Skeleton
+
+```tsx
+import { Header } from '@/dashboard/chrome/Header'
+import { WidgetBoundary } from '@/dashboard/chrome/WidgetBoundary'
+// WIDGET_IMPORTS
+
+export function Dashboard() {
+  return (
+    <div className="min-h-screen bg-background text-foreground p-4 lg:p-8">
+      <Header
+        title="<Dashboard Title>"
+        description="<One sentence describing what this dashboard helps you do.>"
+      />
+
+      {/* Row 1: KPIs (1–4 tiles) */}
+      <div className="mt-6 grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-<N> gap-4">
+        <WidgetBoundary label="<KPI 1 label>"><KPI1 /></WidgetBoundary>
+        {/* ... */}
+      </div>
+
+      {/* Row 2: Charts (2-up grid, wraps automatically) */}
+      <div className="mt-6 grid grid-cols-1 lg:grid-cols-2 gap-4">
+        <WidgetBoundary label="<Chart 1 label>"><Chart1 /></WidgetBoundary>
+        <WidgetBoundary label="<Chart 2 label>"><Chart2 /></WidgetBoundary>
+      </div>
+
+      {/* Row 3: Tables (full width) */}
+      <div className="mt-6">
+        <WidgetBoundary label="<Table label>"><Table1 /></WidgetBoundary>
+      </div>
+    </div>
+  )
+}
+```
+
+---
+
+## Anti-patterns
+
+- Chart in KPI row
+- Table in 2-up grid
+- Widget without WidgetBoundary
+- `gap-6` or any gap other than `gap-4`
+- More than 4 KPIs in one row
+- Header with empty description
+- `cursor-pointer` on table card wrapper