Dashboard

The Dashboard is the home screen. It answers one question — where does every number stand today — and it is the place KPIs get created. This page walks the screen top to bottom, then takes a single KPI card apart element by element.

Where the Dashboard sits

Pulsaria has six top-level screens: Dashboard, Projects, Daily Entry, Reports, Fetch Log and App Settings. On a window wider than 1024 px they sit in a fixed 260 px sidebar on the left, under the heading “Navigation”. The Pulsaria logo above it is a link back to the Dashboard, and the app version sits in the sidebar footer. On a narrower window the same six entries appear as a bottom tab bar.

The active entry is highlighted in cyan with a thin bar on its left edge. A KPI detail page (/kpi/<id>) matches no nav entry, so nothing is highlighted while you are on one.

The sidebar cannot be collapsed or hidden, and it has no responsive hide rule. The window minimum is 900 × 600, so between 900 px and 1024 px wide the sidebar overlays the content while the bottom bar is also visible. Keep the window at 1024 px or wider.

On macOS the menu bar carries Pulsaria → Settings… (Cmd+,), which jumps to App Settings. That is the only keyboard shortcut in the app. There is no Cmd+N, no refresh shortcut and no command palette.

The header

The heading reads “Dashboard” with today’s full date underneath — weekday, day, month and year, formatted in the app language. On the right sits the Refresh button.

Refresh

Refresh runs every automated KPI immediately, ignoring its schedule. It is the same code path the scheduler uses, so values, fetch-log rows and alerts are written exactly as they would be on a scheduled run.

The result arrives as a toast whose description counts outcomes, joined with · — for example 3 successful · 1 skipped:

Situation	Toast title	Action button
No automated KPIs exist	”No auto KPIs configured”	—
At least one KPI was skipped	”Auto KPIs updated”	Approve — opens the first skipped KPI’s edit dialog
Nothing skipped, something failed	”Auto KPIs had errors”	Details — opens the Fetch Log
Everything worked	”Auto KPIs updated”	—

The skipped case wins over the failed case: a run with both skipped and failed KPIs shows the neutral “Auto KPIs updated” toast, not the red one. Toasts carrying an action stay for 30 seconds, plain error toasts 8, success and info 5.

Two limits worth knowing. The button only exists on macOS — automated fetching is macOS-only, so on other builds it hides itself entirely. And it is disabled, with the tooltip “Requires a license or active trial”, while the trial has expired or a licence was revoked.

For what “skipped” means and how schedules work, see Schedules & refresh.

The summary pills

Under the header sits a row of pills counting the whole app, across all projects:

• Total number of KPIs.
• On track in green — always shown, even at zero.
• At risk in amber — only shown when the count is above zero.
• Off track in red — only shown when the count is above zero.

A KPI with no recorded value at all is internally graded off-track, but it is excluded from the red pill so the number never contradicts the neutral card next to it.

Groups

Cards are grouped. The order is fixed:

1. Company-wide — every KPI with no project.
2. One section per project, in the order the projects were created.
3. Other — only appears if a KPI points at a project that no longer exists.

Every project gets a section even when it has no KPIs yet, which makes the Dashboard the natural place to start filling a fresh project. An empty group shows the line “No KPIs here yet — use “+ KPI” to add one.”

Each group header shows the group name, its KPI count and coloured dot counters for on-track, at-risk and off-track. As with the pills, a counter is hidden when it would read zero, and KPIs with no data are left out of the red one.

Collapsing

Click a group header to collapse or expand it. The chevron rotates and the section animates closed over 250 ms. Collapsed groups are remembered across restarts — the state lives in Pulsaria’s config file, not just in memory.

There is no “collapse all”, and groups cannot be reordered or renamed from here.

+ KPI

Every group except Other carries a + KPI button that opens the new-KPI dialog with that group’s scope pre-selected. Other deliberately has none — it is not a real create target.

The button is disabled with a “Requires a license or active trial” tooltip in read-only mode. The full form is described in Anatomy of a KPI.

The KPI card, piece by piece

Every KPI is one card. From top to bottom:

Header row

• A coloured dot and the KPI name. The colour is positional, not meaningful: cards cycle through cyan, purple, emerald, amber, red and violet, and the cycle continues across group boundaries. The same colour is used for the sparkline.
• A source badge — CONNECTOR, BASH or HTTP — for KPIs that fetch themselves. Manual KPIs have no badge.
• A play button, next to the badge, on automated KPIs. It is always visible, no hover needed, and it is hidden for manual KPIs and on non-macOS builds.
• A status dot on the far right: green on track, amber at risk, red off track. A KPI with no recorded value shows a neutral grey dot instead.

Pressing the play button fetches that one KPI without leaving the Dashboard. Success toasts “KPI updated” with <name>: <value>; failure toasts “Auto-KPI failed” with a View details action that opens the Fetch log, where the full command output is kept.

In read-only mode the play button is not disabled. Clicking it produces a generic “Auto-KPI failed” toast whose description reads “Trial expired” or “License revoked”.

Value and gap badge

The current value is the large mono number, with the unit beside it in small type. “Current” means the newest value on record, not necessarily today’s — if you last entered something on Monday, Thursday’s card still shows Monday’s number.

When the value changes after a refresh, the number pulses once for about a second. That only happens on a change, never on first render.

Opposite the value sits the gap badge: the percentage distance between your value and today’s ideal, with an up or down arrow, labelled vs ideal — or vs target for a recurring-value (snapshot) KPI. Its colour follows how far off you are:

Situation	Colour
At or ahead of the ideal	Green
Behind by less than 10 %	Amber
Behind by 10 % or more	Red

“Ahead” depends on direction: for a higher-is-better KPI it means at or above the ideal, for lower-is-better at or below. The badge is only rendered when today’s ideal is greater than zero — very early in a period, or for a target of 0, there is nothing sensible to compare against.

A KPI with no history at all shows an em dash instead of a value and the badge slot reads Add today’s value.

The ideal itself is explained in Ideal line & status.

Week-over-week badge

Below the value, a small badge shows the change against the previous week, for example +12% vs. previous week. It compares the newest recorded value against the closest recorded point at or before seven days earlier — anchored on your newest entry, not on today.

It needs at least two recorded days and one point on each side of that seven-day window. When there isn’t enough history the badge simply isn’t there. Its colour follows the KPI’s direction: green when the change is good for you, red when it isn’t.

Sparkline with ideal line

The 120 px chart draws the whole goal period, one point per calendar day — 1 January to 31 December for a yearly KPI, the current month for a monthly one, the current quarter for a quarterly one, the configured range for a custom period.

• The filled line in the card’s accent colour is your actual values. Days without an entry are gaps, but the line is connected through them so it stays continuous.
• The grey dashed line is the ideal progression. It is drawn with straight-line interpolation on purpose — the underlying model is a straight line, and a curve would misrepresent it.
• Days after today are empty, because there is no future data.

Hovering shows a tooltip with the day, the actual value labelled Actual, and the ideal labelled Ideal — or Target for a recurring-value KPI. There are no axes, no legend and no zoom; that version of the chart lives on the KPI detail page.

The actual line animates in over 800 ms. The animation is skipped when the macOS “Reduce motion” setting is on. The ideal line is never animated.

Footer

A thin footer row carries two facts:

• Left, next to a target icon: the target with its unit and a period suffix — /yr, /mo or /qtr. A custom period shows a date range such as Mar 1 – Jun 30 instead.
• Right: today’s ideal value, labelled ideal: — or target: for a recurring-value KPI.

Clicking the card

Clicking anywhere on the card except the play button opens that KPI’s detail page. The card also lights up under the mouse pointer with a glow that follows the cursor.

There is no Edit and no Move to… on the card itself — those live on the KPI detail page.

When a card is red

If a KPI’s data cannot be read — a corrupt file, or a wrongly shaped one synced from another machine — its card is replaced by a red one showing the KPI name, the line “KPI could not be loaded”, the raw error message in monospace, and “Click to edit”. Clicking it opens that KPI’s detail page with the edit dialog already open.

One unreadable KPI never takes the whole Dashboard down: the failure is caught per KPI, and the rest of the grid renders normally. The card offers no repair action beyond the edit dialog.

Alerts

When a KPI moves into a worse state, a red-bordered box appears above the KPI grid, headed “2 alerts”. Each row reads <KPI name> went at risk (or “off track”) with the day, short month and time.

How alerts are made

An alert is written whenever saving a value changes the KPI’s status for the worse — into at-risk or off-track. That applies to values you type in and to values a fetch brings in; both go through the same check.

• Improvements never create an alert. Going from off-track back to on-track is good news, not a warning.
• The old status is computed from another entry on the same day if one exists, otherwise from the most recent earlier day.
• Alerts are stored in alerts.json next to your data. The newest 100 are kept.

Reading and dismissing

Click an alert row to jump to that KPI’s detail page. Hover a row and click the × to dismiss just that one, or use Dismiss all in the top right — that button only appears when there is more than one alert.

Dismissed alerts are flagged, not deleted, and are filtered out of the banner. There is no alert history screen and no way to bring a dismissed alert back. Alerts also never become system notifications; the only notification Pulsaria sends is the daily entry reminder configured in Settings.

The hint banner

A single cyan banner with a lightbulb icon can appear between the alerts and the KPI grid, suggesting something you haven’t set up yet. It has a title, one line of body text, an action button and an ×.

Five hints exist, checked in this priority order:

Hint	Appears when	The button goes to
”Group your KPIs into projects”	3 or more company-wide KPIs and no project exists	New project dialog
”Automate your KPI fetching”	macOS, 5 or more manual KPIs, no automated one	New KPI dialog on the Dashboard
”Never forget to check in”	Installed 3+ days, entries on 3+ days, reminder off	App Settings
”Launch Pulsaria at login”	macOS, installed 3+ days, autostart off	App Settings
”Sync across your Macs”	Installed 7+ days, no custom data directory	App Settings

Both the action button and the × count as dismissing it: the hint is recorded permanently and never comes back. At most one hint appears per app session — once one has been shown, no other appears until you restart Pulsaria. If nothing matched, the check simply runs again the next time the Dashboard mounts.

There is no list of hints and no way to re-enable a dismissed one.

The trial and licence banner

Above the alerts, a banner warns about the licence state:

State	Tone	Buttons
Trial, 4–10 days left	Amber	Buy Pulsaria
Trial, 3 days or fewer	Red	Buy Pulsaria
Trial expired	Red, blocking	Buy Pulsaria, License settings
Licence revoked	Red, blocking	License settings
Licence not verified for 30+ days	Amber	Re-check

Nothing is shown for an activated licence, or during a trial with more than 10 days left. License settings and Re-check are plain links to App Settings — the actual re-validation runs there, not from the banner. The banner cannot be dismissed. Details are on Trial & licence.

Empty states

There are two, and they look nothing alike.

Nothing at all — no KPIs and no projects. The Dashboard shows a welcome panel: “Welcome to Pulsaria”, a short explanation, and three buttons — Create project, Create KPI and Use a template. In this state there is no Refresh button, no summary pills and no banners of any kind, licence banner included.

Use a template creates a ready-made set of KPIs. It exists only here and on the last step of the welcome wizard; once you have a single KPI or project it disappears and there is no other way back to the template packs.

Projects but no KPIs. You get the normal grouped layout with empty groups, each carrying its hint line and its own + KPI button.

Getting from empty to a first number is covered in Your first KPI.

Loading and live updates

While data loads, the Dashboard shows a grey placeholder shaped like the real thing: a title bar, three pills and six cards. The pulsing stops when the macOS “Reduce motion” setting is on.

The screen re-reads its data whenever anything in the app writes — a saved value, a finished fetch, a new fetch-log row. A scheduled fetch that completes while you are looking at the Dashboard updates the card in place, without a reload.

If the screen itself crashes, it is replaced by “Something went wrong” with a Reload button and the note that your data is safe on disk. Navigating to another screen clears it too.

What the Dashboard does not do

Stated plainly:

• No search, filter or sort. No command palette.
• No card ordering. Cards appear in creation order inside each group, groups in the order described above.
• No drag and drop, anywhere.
• No editing from a card — values are entered on the KPI detail page or on Daily Entry.
• No date range for the whole board. Each card always shows its own full goal period.