Technical docs

Home Dashboard (`/home`)

Public reference generated from tech docs/home.md.

Purpose

* Platform-level dashboard for org-wide workflow reporting plus a live workflow activity feed. * The page is not a long static report. It is a stack of `data-snap` sections inside `#main-content`, advanced one section at a time by `useScrollSnap`.

Current page structure

* `OrgReportsCard` renders the analytics section stack: * KPI row: `Credits`, `Total Runs`, `Success Rate`, `Active Time` * chart row: `Runs Over Time` + `Available Credits` * single-row card: `Costs` * breakdown row: `Success Rate` + `AI Teammates` * Final snap section: * `WorkflowActivityCard` * Older `Conversations*` cards still exist as components, but they are not mounted on `/home`. * On mobile, `/home` wraps the dashboard in a flattened mobile shell with `px-4 py-4` gutters and renders an install banner above the dashboard content. * Mobile portal navigation is the shared bottom bar, so Home content scrolls above the bar rather than inside the desktop sidebar shell.

Mobile install banner

* The install banner only renders on mobile `/home`. * Current mobile detection for that shell is: * viewport width below `700px`, or * viewport height below `500px` * Banner title: `Install to home screen`. * Banner subtitle: `for the best experience`. * Android behavior: * shows action `Install` * uses the browser's native install prompt when `beforeinstallprompt` is available * iOS Safari behavior: * shows action `How` * expands inline steps telling the user to tap Safari `Share`, choose `Add to Home Screen`, then tap `Add` * The banner is hidden when: * the app is already installed in standalone mode * the device is not touch-capable * the browser is a common iOS in-app browser rather than Safari * the user has dismissed the banner * Dismiss action label is exposed via the close button's accessible name: `Dismiss install banner`.

Reporting behavior

* Org reports lazy-load when the section approaches the viewport. * The current reporting window uses the last 7 completed days: * the fetch starts 7 days back * the filter excludes today by using the start of the current day as the upper bound * `Runs Over Time` charts completed vs failed runs by day. * `Success Rate` uses a line chart with `connectNulls={false}`, so days without runs stay blank instead of drawing `0%`. * `AI Teammates` shows the top 5 teammates by run volume, stacked by completed/other/failed. * If the current 7-day window has no runs, KPI tiles and credits still render. The runs chart shows `No runs yet — analytics will appear here`, and the deeper cost/success/teammate sections stay hidden until run data exists.

KPI details

* `Credits` * uses the current org's `available_tokens` * applies warning colors when credits are low: * red at `0` or below * yellow below `500` * `Total Runs` * shows the total count of org-wide runs in the current 7-day window * `Success Rate` * shows completed runs divided by total runs in the current window * subtitle: `Completed vs total` * description: `{completed} completed` * `Active Time` * replaced the previous `Wall Time` label * sums `durationSeconds` across runs in the current window * stale in-progress runs are capped at `updated_at` once they have not been updated for 5 or more minutes, so zombie runs do not keep inflating the total

Credits and cost cards

* `Available Credits` * balance comes from the current org's `available_tokens` * that balance is decremented only when a run uses Alloy/system provider credentials * burn chart uses `GET /api/organizations/{organization_id}/dashboard/burned-tokens-stat` * the burn chart is based on token-history decreases, so it can still show recent activity for runs that used org-saved provider keys * footer shows `avg/day · last 7 days` * `Costs` * data source: `GET /api/organizations/{organization_id}/tokens/stats` * filters: * teammate: `All` plus active AI teammates in the org * time range: `Last 7 days`, `Last 14 days`, `Last 30 days` * grouping: `By AI Teammate`, `By workflow`, `By model`, `By day` * defaults: * time range: `Last 30 days` * grouping: `By day` * teammate: `All` * subtitle summarizes USD cost, request count, and consumed credits for the current filter set * the card includes recorded usage for both system-key runs and org-saved provider-key runs * `By day` renders vertical bars; other groupings render horizontal bars * empty state: `No cost data for this period`

Workflow activity

* The activity card loads org-wide workflow runs with `pageSize: 30` and refreshes every `30` seconds. * Source mapping: * `web_chat` -> `Widget` * `employee_chat` and `ally_chat` -> `Internal` * if channel is missing but a conversation exists, the UI infers `Widget` when `runtimeContext.isAsync === true`, otherwise `Internal` * Internal-chat activity rows can reopen the related AI teammate conversation. * Inner scrolling stays disabled until the card is snapped near the top of the viewport.

PWA shell behavior

* The shared mobile bottom bar is `56px` in browser mode and `85px` in standalone/PWA mode, plus safe-area inset. * Mobile sheets and internal-chat panels use the same bottom-nav offset so they do not cover the bottom bar. * Desktop standalone/PWA mode removes the extra top shell padding while keeping bottom spacing, so the installed app title bar and content do not double-pad. * The app updates `theme-color` from the computed body background so browser/PWA chrome follows the selected theme.

Scroll behavior

* `useScrollSnap` listens for wheel events on `#main-content`. * It advances exactly one `[data-snap]` section per gesture. * Default cooldown is `1000ms`, with early unlock on `scrollend` after half the cooldown.

Start building your AI team