Insights

The “what should the owner look at right now” widget at the top of the dashboard. A small, data-driven engine that runs a fixed set of rules over an org’s state, returns severity-ranked items, and links each one to its drilldown page.

What

GET /organizations/:orgId/insights returns an ordered array of Insight records. Each record carries an id (used by the frontend for i18n), severity, count, category, a drilldownHref, and an opaque meta payload with rule-specific detail.

The server returns data only — title and description text live in the web app’s i18n dictionary keyed by insight.<id>.title and insight.<id>.description.

Why

Owners log into a busy dashboard and miss the things that need their attention this morning: pending cancellation requests, accumulated debt, members in past-due billing, overdue tasks.
Without an insight widget, those metrics live behind several clicks each (Payments → Cancellations, Payments → Debt, Members → Filter, Tasks → My Tab).
A single ranked list at the top of the dashboard collapses the daily triage into one glance.

Who

Owner / admin — view-only access, gated server-side (requireMembership then role check).
Spotter agent — reads the same surface via analytics.org_insights so it can answer “anything I should look at?” with the same payload.

Persona impact

Persona	Impact
Owner	Surfaces the morning triage in one glance — saves multiple navigations per day.
Admin	Same.
Coach / member	No access (403 by role).

Capabilities

Four rules ship today (FIT-160):

`id`	Category	Triggers when	Severity rule
`finance.cancellation_requests`	finance	`pending` cancellation requests OR scheduled cancellations (`cancelAtPeriodEnd = true`) > 0	`pending > 0` → `warning`, else `info`
`finance.outstanding_debt`	finance	sum of `subscriptions.debtAmountInCents` > 0	always `warning`
`members.at_risk_billing`	members	members with `subscriptions.status = 'past_due'` > 0	`>= 10` → `urgent`, `>= 3` → `warning`, else `info`
`operations.tasks_overdue`	operations	tasks with `due_date < today` and not completed	tiered by count

Rules run in parallel; null returns (no insight) are dropped. Result is sorted by severity (urgent first), then by count descending.

analytics — the agent’s analytics.org_insights tool wraps this same service.
tasks — drives the operational overdue rule.
payments / subscriptions — drive the financial rules.
The dashboard’s drilldown pages must continue to honour the deep-link query params the rules emit (e.g. ?tab=cancellation-requests, ?status=past_due).

Status

Shipped under FIT-160. Live on the dashboard.

Gaps

Only four rules. Roadmap candidates: lapsed coaches (no recent assignments), under-utilized programs, missing compliance signatures, expiring memberships in next 7 days.
No per-org customization — every owner sees the same rule set, same thresholds.
No dismissal / snooze — insights stay until the underlying condition resolves. Useful behaviorally but cluttered when the owner can’t act this week.
No historical trend per insight (“debt was higher last month”) — each call is a point-in-time read.
No SSE / websockets — the widget polls when the dashboard mounts. Acceptable for a daily-triage tool.