:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
chore(devex): move today highlight sources into their products (#118394)
Julian Beze631807a4830
diff --git a/.agents/skills/adding-today-highlights/SKILL.md b/.agents/skills/adding-today-highlights/SKILL.mdnew file mode 100644index 000000000000..ad7aaaf01bfd--- /dev/null+++ b/.agents/skills/adding-today-highlights/SKILL.md@@ -0,0 +1,71 @@+---+name: adding-today-highlights+description: Add a "For you today" highlight source, the rule that turns a product's facts into items on the Today home page (firing alerts, flags that lose reach, ticket SLA breaches, workflow failures). Use when asked to "add a Today highlight", "show X in For you today", "surface X on the home page", or when changing an existing source's query, thresholds, copy or icon. Covers where the rule and its declaration live, the Today facade contract, scopes, caching, ranking inputs, tests, tach, and the frontend icon.+---++# Adding a Today highlight source++Today ranks facts that other products find and shows the best few in "For you today".+The product that owns the data owns its source: the query, the thresholds, and the copy.+Today owns the contract, the ranking, the shared helpers, and its own pulse (routine and key-metric tiles, pinned numbers, home dashboard).++**A source lives in its own product, never in `products/today/`.**+Today has no list of sources to edit. It finds each product's declaration by module name.++## Steps++1. Write the rule in the product's internals, for example `products/<x>/backend/today_highlights.py`, or a package of that name when the product has several sources.+ The rule takes a `HighlightContext` and returns `HighlightFindings`.+ Read the facts through the product's own code. Read other products only through their facades.+2. Declare it in `products/<x>/backend/facade/today_highlights.py`:++ ```python+ """<Product>'s sources for the "For you today" list. Today finds this module by name."""++ from products.today.backend.facade.contracts import HighlightSource++ from ..today_highlights import find_stale_things++ HIGHLIGHT_SOURCES = (HighlightSource(name="stale_things", find=find_stale_things, scopes=("thing:read",)),)+ ```++3. Add `"products.today"` to the product's `depends_on` in the root `tach.toml`, with a `# Facade-only:` comment like the other products have. Today gets no new dependency.+4. Test the rule in the product with `products.today.backend.facade.testing.highlight_context`.+ `products/alerts/backend/tests/test_alert_today_highlights.py` is a short example.+ A test folder without `__init__.py` needs a product-specific file name, so pytest does not collide on `test_today_highlights.py`.+5. The row icon comes from the product. If `PRODUCT_ICONS` in `frontend/src/scenes/project-homepage/today/todayRowIcons.tsx` has no entry for the product yet, add one. That file is Today's, so team-surfaces reviews it.++`products/feature_flags/backend/today_highlights.py` is a complete source with a reach drop and a cleanup item.++## Contract++Import only from Today's facade:++- `facade/contracts.py`: `HighlightCandidate`, `HighlightFindings`, `HighlightContext`, `HighlightSource`, `HighlightMetric`, `DailyValueNotReady`+- `facade/enums.py`: `HighlightLabel`, `HighlightUnit`, `HighlightInterval`+- `facade/highlight_helpers.py`: number and text formatting, `uses_product`, and trend detection++Rules that are easy to get wrong:++- **The source name is a stable key.** Today stores results and analytics under it, so a rename breaks them. The registry raises when two products use the same name.+- **`scopes`** lists the API scopes the viewer needs. Today skips the source when the viewer's scopes or access controls do not cover them.+- **`context.daily(name, compute)`** caches one value per team, property restrictions and day, and every viewer with the same restrictions shares it. Never compute a per-viewer value there. Prefix `name` with the source name.+- **`context.guard(name, provider, default)`** records a failure and returns the default instead of failing the whole list. Use it around each call that can fail on its own.+- Raise `DailyValueNotReady` when a value the source needs is still computing. Today retries the source soon.++## Ranking inputs++Each `HighlightCandidate` carries what Today ranks on:++- `label`: `risk` when something got worse or broke, `opportunity` when the person can act to gain.+- `importance` from 0 to 1, and `relevance` from 0 to 1 for how much this viewer cares. Compare with existing sources before you pick a number: suspended email sending is 0.95, a firing alert 0.85, a flag that lost reach 0.6, a cleanup suggestion 0.3.+- `family`: Today shows at most two items of one family.+- `ref`: items of different families that share a ref are about the same object, so Today shows one of them.+- `key`: stable for the same fact on the same day, for example `flag_reach_drop:<id>`.++Copy follows `/writing-user-facing-copy`: one sentence with numbers in `title`, the comparison and the next action in `detail`.++## Limits++- A row looks the same for every source. A source that needs its own row or preview still needs a change in Today's frontend.+- Only Today's own pulse tiles can be pinned.diff --git a/frontend/src/scenes/project-homepage/today/Today.stories.tsx b/frontend/src/scenes/project-homepage/today/Today.stories.tsxindex 980e0d8771a7..6d34ca6b9324 100644--- a/frontend/src/scenes/project-homepage/today/Today.stories.tsx+++ b/frontend/src/scenes/project-homepage/today/Today.stories.tsx@@ -660,6 +660,7 @@ const HIGHLIGHTS: HighlightsApi = {score: 0.85,priority: 'P1',source: 'alerts',+ product: 'alerts',},{key: 'new_error:0195a0b2-0000-0000-0000-000000000001',@@ -671,6 +672,7 @@ const HIGHLIGHTS: HighlightsApi = {score: 0.82,priority: 'P1',source: 'errors',+ product: 'error_tracking',},{key: 'home:rev01',@@ -682,6 +684,7 @@ const HIGHLIGHTS: HighlightsApi = {score: 0.6,priority: 'P2',source: 'home',+ product: 'today',},{key: 'key_metric:payment_event',@@ -693,6 +696,7 @@ const HIGHLIGHTS: HighlightsApi = {score: 0.57,priority: 'P2',source: 'key_metrics',+ product: 'today',},{key: 'experiment_ended:12',@@ -704,6 +708,7 @@ const HIGHLIGHTS: HighlightsApi = {score: 0.6,priority: 'P3',source: 'experiments',+ product: 'experiments',},{key: 'assigned_quiet',@@ -715,6 +720,7 @@ const HIGHLIGHTS: HighlightsApi = {score: 0.35,priority: 'P4',source: 'errors',+ product: 'error_tracking',},],}diff --git a/frontend/src/scenes/project-homepage/today/todayRowIcons.tsx b/frontend/src/scenes/project-homepage/today/todayRowIcons.tsxindex 65e01edabdf5..82250fed3949 100644--- a/frontend/src/scenes/project-homepage/today/todayRowIcons.tsx+++ b/frontend/src/scenes/project-homepage/today/todayRowIcons.tsx@@ -27,19 +27,23 @@ const ANALYTICS: TodayRowIcon = {glyph: <IconTrends />,}-const WORKFLOWS: TodayRowIcon = { color: 'var(--color-product-workflows-light)', glyph: <IconDecisionTree /> }+const REPLAY: TodayRowIcon = { color: 'var(--color-product-session-replay-light)', glyph: <IconRewindPlay /> }-const HIGHLIGHT_ICONS: Record<string, TodayRowIcon> = {+const PRODUCT_ICONS: Record<string, TodayRowIcon> = {alerts: { color: 'var(--color-product-alerts-light)', glyph: <IconBell /> },- errors: { color: 'var(--color-product-error-tracking-light)', glyph: <IconWarning /> },+ conversations: { color: 'var(--color-product-support-light)', glyph: <IconSupport /> },+ error_tracking: { color: 'var(--color-product-error-tracking-light)', glyph: <IconWarning /> },experiments: { color: 'var(--color-product-experiments-light)', glyph: <IconFlask /> },- flags: { color: 'var(--color-product-feature-flags-light)', glyph: <IconToggle /> },- rage: { color: 'var(--color-product-session-replay-light)', glyph: <IconRewindPlay /> },+ feature_flags: { color: 'var(--color-product-feature-flags-light)', glyph: <IconToggle /> },+ replay: REPLAY,surveys: { color: 'var(--color-product-surveys-light)', glyph: <IconMessage /> },- ticket_sla: { color: 'var(--color-product-support-light)', glyph: <IconSupport /> },- warehouse_syncs: { color: 'var(--color-product-data-warehouse-light)', glyph: <IconDatabase /> },- workflow_ideas: WORKFLOWS,- workflows: WORKFLOWS,+ warehouse_sources: { color: 'var(--color-product-data-warehouse-light)', glyph: <IconDatabase /> },+ workflows: { color: 'var(--color-product-workflows-light)', glyph: <IconDecisionTree /> },+}++// Rage clicks come from web analytics, but the row opens the recordings.+const SOURCE_ICONS: Record<string, TodayRowIcon> = {+ rage: REPLAY,}function sourceIcon(source: string | null | undefined): TodayRowIcon {@@ -52,6 +56,6 @@ export function reportIcon(report: Pick<SignalReport, 'source_products'>): Todayreturn sourceIcon(report.source_products?.[0])}-export function highlightIcon(item: Pick<HighlightItemApi, 'source'>): TodayRowIcon {- return HIGHLIGHT_ICONS[item.source] ?? ANALYTICS+export function highlightIcon(item: Pick<HighlightItemApi, 'source' | 'product'>): TodayRowIcon {+ return SOURCE_ICONS[item.source] ?? (item.product ? PRODUCT_ICONS[item.product] : undefined) ?? ANALYTICS}diff --git a/products/alerts/backend/facade/today_highlights.py b/products/alerts/backend/facade/today_highlights.pynew file mode 100644index 000000000000..aec7a59c9bb4--- /dev/null+++ b/products/alerts/backend/facade/today_highlights.py@@ -0,0 +1,7 @@+"""Alerts' sources for the "For you today" list. Today finds this module by name."""++from products.today.backend.facade.contracts import HighlightSource++from ..today_highlights import find_firing_alerts++HIGHLIGHT_SOURCES = (HighlightSource(name="alerts", find=find_firing_alerts, scopes=("alert:read",)),)diff --git a/products/today/backend/tests/test_highlight_alerts.py b/products/alerts/backend/tests/test_alert_today_highlights.pysimilarity index 70%rename from products/today/backend/tests/test_highlight_alerts.pyrename to products/alerts/backend/tests/test_alert_today_highlights.pyindex 354d7056ca7a..297a46d5d8dd 100644--- a/products/today/backend/tests/test_highlight_alerts.py+++ b/products/alerts/backend/tests/test_alert_today_highlights.py@@ -6,10 +6,10 @@ from unittest.mock import MagicMock, patchfrom parameterized import parameterized+from products.alerts.backend import today_highlightsfrom products.alerts.backend.facade.contracts import FiringAlert-from products.today.backend.logic.highlight_registry import load_sources-from products.today.backend.logic.highlight_sources import alerts-from products.today.backend.logic.highlight_types import Context+from products.alerts.backend.facade.today_highlights import HIGHLIGHT_SOURCES+from products.today.backend.facade.testing import highlight_contextclass TestAlerts(BaseTest):@@ -30,10 +30,10 @@ class TestAlerts(BaseTest):self, _name: str, alert_name: str, insight_name: str | None, title: str, detail: str) -> None:alert = FiringAlert(id=uuid.uuid4(), name=alert_name, insight_name=insight_name, insight_short_id="abc123")- registered = next(s for s in load_sources() if s.name == "alerts")+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "alerts")- with patch.object(alerts, "list_firing_alerts_created_by", return_value=[alert]):- found = registered.find(Context(self.team, self.user, date(2026, 10, 13)))+ with patch.object(today_highlights, "list_firing_alerts_created_by", return_value=[alert]):+ found = registered.find(highlight_context(team=self.team, user=self.user, today=date(2026, 10, 13)))self.assertEqual([(c.key, c.title, c.detail, c.url) for c in found.items],@@ -51,9 +51,9 @@ class TestAlerts(BaseTest):self, _name: str, scopes: frozenset[str] | None, include: bool) -> None:listed = MagicMock(return_value=[])- registered = next(s for s in load_sources() if s.name == "alerts")+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "alerts")- with patch.object(alerts, "list_firing_alerts_created_by", listed):- registered.find(Context(self.team, self.user, date(2026, 10, 13), scopes))+ with patch.object(today_highlights, "list_firing_alerts_created_by", listed):+ registered.find(highlight_context(team=self.team, user=self.user, today=date(2026, 10, 13), scopes=scopes))self.assertEqual(listed.call_args.kwargs["include_metrics_insights"], include)diff --git a/products/today/backend/logic/highlight_sources/alerts.py b/products/alerts/backend/today_highlights.pysimilarity index 65%rename from products/today/backend/logic/highlight_sources/alerts.pyrename to products/alerts/backend/today_highlights.pyindex 0ac4d9952510..bb325b3a6e08 100644--- a/products/today/backend/logic/highlight_sources/alerts.py+++ b/products/alerts/backend/today_highlights.py@@ -2,26 +2,18 @@ import refrom products.alerts.backend.facade.api import list_firing_alerts_created_byfrom products.alerts.backend.facade.contracts import FiringAlert--from ...facade.enums import HighlightLabel-from ..highlight_rules import short-from ..highlight_types import Candidate, Context, Found, Source+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings+from products.today.backend.facade.enums import HighlightLabel+from products.today.backend.facade.highlight_helpers import shortALERT_FIRING = "Alert ‘{alert}’ is firing"UNNAMED_ALERT_FIRING = "An alert is firing"ALERT_FIRING_DETAIL = "Insight ‘{insight}’"-def find(context: Context) -> Found:- alerts = list_firing_alerts_created_by(- context.team, context.user, include_metrics_insights=context.allows("metrics:read"), limit=10- )- return Found(items=tuple(_candidate(alert) for alert in alerts))---def _candidate(alert: FiringAlert) -> Candidate:+def _candidate(alert: FiringAlert) -> HighlightCandidate:name = re.sub(r"(?i)\s+alert$", "", short(alert.name))- return Candidate(+ return HighlightCandidate(key=f"alert:{alert.id}",label=HighlightLabel.RISK,family="alerts",@@ -34,4 +26,8 @@ def _candidate(alert: FiringAlert) -> Candidate:)-SOURCE = Source(name="alerts", find=find, scopes=("alert:read",))+def find_firing_alerts(context: HighlightContext) -> HighlightFindings:+ alerts = list_firing_alerts_created_by(+ context.team, context.user, include_metrics_insights=context.allows("metrics:read"), limit=10+ )+ return HighlightFindings(items=tuple(_candidate(alert) for alert in alerts))diff --git a/products/conversations/backend/facade/api.py b/products/conversations/backend/facade/api.pyindex b63e1b47e2e3..e27e96977511 100644--- a/products/conversations/backend/facade/api.py+++ b/products/conversations/backend/facade/api.py@@ -30,7 +30,6 @@ from posthog.models.team import Teamfrom posthog.slack.identity import resolve_slack_profile_by_emailfrom posthog.temporal.common.client import sync_connect-from products.conversations.backend import role_slafrom products.conversations.backend.channel_summary_ids import build_channel_summary_workflow_idfrom products.conversations.backend.facade.types import (AccountEmailThreadMessage as AccountEmailThreadMessage,@@ -43,7 +42,6 @@ from products.conversations.backend.facade.types import (EmailThreadParticipantSummary as EmailThreadParticipantSummary,PublicHumanReplies as PublicHumanReplies,ResolvedTicketRevision as ResolvedTicketRevision,- RoleSlaBreach as RoleSlaBreach,SupportChannel as SupportChannel,SupportSlackSender as SupportSlackSender,SupportTicketMessage as SupportTicketMessage,@@ -1103,12 +1101,6 @@ def _email_thread_addresses(value: object) -> list[EmailThreadAddress]:return addresses-def list_role_sla_breaches(- team_id: int, user_id: int, *, due_after: datetime, due_before: datetime-) -> list[RoleSlaBreach]:- return role_sla.list_role_sla_breaches(team_id, user_id, due_after=due_after, due_before=due_before)--def list_account_email_thread_messages(team_id: int,account_id: str,diff --git a/products/conversations/backend/facade/today_highlights.py b/products/conversations/backend/facade/today_highlights.pynew file mode 100644index 000000000000..b78053892e9f--- /dev/null+++ b/products/conversations/backend/facade/today_highlights.py@@ -0,0 +1,7 @@+"""Conversations' sources for the "For you today" list. Today finds this module by name."""++from products.today.backend.facade.contracts import HighlightSource++from ..today_highlights import find_ticket_sla++HIGHLIGHT_SOURCES = (HighlightSource(name="ticket_sla", find=find_ticket_sla, scopes=("ticket:read",)),)diff --git a/products/conversations/backend/tests/test_role_sla.py b/products/conversations/backend/tests/test_role_sla.pyindex ace2b1444011..7bdcd36cdb71 100644--- a/products/conversations/backend/tests/test_role_sla.py+++ b/products/conversations/backend/tests/test_role_sla.py@@ -6,9 +6,9 @@ from posthog.models import Organization, Team, Userfrom products.access_control.backend.models.access_control import AccessControlfrom products.access_control.backend.models.role import Role, RoleMembership-from products.conversations.backend.facade.api import list_role_sla_breachesfrom products.conversations.backend.models import Status, Ticket, TicketAssignmentfrom products.conversations.backend.models.constants import Channel+from products.conversations.backend.role_sla import list_role_sla_breachesNOW = datetime(2026, 10, 15, 12, 0, tzinfo=UTC)DUE_BEFORE = NOW + timedelta(hours=24)diff --git a/products/today/backend/tests/test_highlight_ticket_sla.py b/products/conversations/backend/tests/test_today_highlights.pysimilarity index 77%rename from products/today/backend/tests/test_highlight_ticket_sla.pyrename to products/conversations/backend/tests/test_today_highlights.pyindex 2f58c7d3b92b..fa9b02531da6 100644--- a/products/today/backend/tests/test_highlight_ticket_sla.py+++ b/products/conversations/backend/tests/test_today_highlights.py@@ -9,11 +9,11 @@ from parameterized import parameterizedfrom posthog.models import Team, User+from products.conversations.backend import today_highlights+from products.conversations.backend.facade.today_highlights import HIGHLIGHT_SOURCESfrom products.conversations.backend.facade.types import RoleSlaBreachfrom products.today.backend.facade.enums import HighlightLabel-from products.today.backend.logic.highlight_registry import load_sources-from products.today.backend.logic.highlight_sources import ticket_sla-from products.today.backend.logic.highlight_types import Context+from products.today.backend.facade.testing import highlight_contextROLE_ID = UUID("11111111-1111-1111-1111-111111111111")@@ -45,11 +45,10 @@ class TestTicketSlaHighlight(SimpleTestCase):soonest_ticket_number=12,soonest_due_at=datetime(2026, 10, 15, 14, 0, tzinfo=UTC),)- registered = next(source for source in load_sources() if source.name == "ticket_sla")- with patch("products.today.backend.logic.highlight_types.property_restrictions", return_value="0"):- context = Context(Team(id=1), User(id=2), date(2026, 10, 15))+ registered = next(source for source in HIGHLIGHT_SOURCES if source.name == "ticket_sla")+ context = highlight_context(team=Team(id=1), user=User(id=2), today=date(2026, 10, 15))- with patch.object(ticket_sla, "list_role_sla_breaches", return_value=[breach]):+ with patch.object(today_highlights, "list_role_sla_breaches", return_value=[breach]):found = registered.find(context)assert len(found.items) == 1diff --git a/products/today/backend/logic/highlight_sources/ticket_sla.py b/products/conversations/backend/today_highlights.pysimilarity index 75%rename from products/today/backend/logic/highlight_sources/ticket_sla.pyrename to products/conversations/backend/today_highlights.pyindex 55562f5b171b..3f0f351f54ee 100644--- a/products/today/backend/logic/highlight_sources/ticket_sla.py+++ b/products/conversations/backend/today_highlights.py@@ -2,11 +2,10 @@ from datetime import timedeltafrom django.utils import timezone-from products.conversations.backend.facade.api import list_role_sla_breachesfrom products.conversations.backend.facade.types import RoleSlaBreach--from ...facade.enums import HighlightLabel-from ..highlight_types import Candidate, Context, Found, Source+from products.conversations.backend.role_sla import list_role_sla_breaches+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings+from products.today.backend.facade.enums import HighlightLabelWINDOW = timedelta(hours=24)# Relevance is 1 because the ticket is assigned to the viewer's role, so the score@@ -20,18 +19,12 @@ MANY_DETAIL = "Ticket #{number} is the soonest."OPEN_STATUSES = ("new", "open", "pending", "on_hold")-def find(context: Context) -> Found:- now = timezone.now()- breaches = list_role_sla_breaches(context.team.id, context.user.id, due_after=now, due_before=now + WINDOW)- return Found(items=tuple(_candidate(breach) for breach in breaches))---def _candidate(breach: RoleSlaBreach) -> Candidate:+def _candidate(breach: RoleSlaBreach) -> HighlightCandidate:number = breach.soonest_ticket_numberrole = breach.role_nameone = breach.ticket_count == 1statuses = "&".join(f"status={status}" for status in OPEN_STATUSES)- return Candidate(+ return HighlightCandidate(key=f"ticket_sla:{breach.role_id}",label=HighlightLabel.RISK,family="support",@@ -48,4 +41,7 @@ def _candidate(breach: RoleSlaBreach) -> Candidate:)-SOURCE = Source(name="ticket_sla", find=find, scopes=("ticket:read",))+def find_ticket_sla(context: HighlightContext) -> HighlightFindings:+ now = timezone.now()+ breaches = list_role_sla_breaches(context.team.id, context.user.id, due_after=now, due_before=now + WINDOW)+ return HighlightFindings(items=tuple(_candidate(breach) for breach in breaches))diff --git a/products/data_catalog/backend/facade/today_highlights.py b/products/data_catalog/backend/facade/today_highlights.pynew file mode 100644index 000000000000..f3f6bef83a06--- /dev/null+++ b/products/data_catalog/backend/facade/today_highlights.py@@ -0,0 +1,13 @@+"""Data catalog's sources for the "For you today" list. Today finds this module by name."""++from products.today.backend.facade.contracts import HighlightSource++from ..today_highlights import find_pending_approvals++HIGHLIGHT_SOURCES = (+ HighlightSource(+ name="data_catalog_approvals",+ find=find_pending_approvals,+ scopes=("data_catalog:read", "data_catalog_approval:write"),+ ),+)diff --git a/products/today/backend/tests/test_highlight_data_catalog_approvals.py b/products/data_catalog/backend/tests/test_today_highlights.pysimilarity index 69%rename from products/today/backend/tests/test_highlight_data_catalog_approvals.pyrename to products/data_catalog/backend/tests/test_today_highlights.pyindex 3f695b6d2e95..cb1019a45ca7 100644--- a/products/today/backend/tests/test_highlight_data_catalog_approvals.py+++ b/products/data_catalog/backend/tests/test_today_highlights.py@@ -1,3 +1,4 @@+from collections.abc import Callablefrom types import SimpleNamespacefrom typing import cast@@ -7,11 +8,11 @@ from django.test import SimpleTestCasefrom parameterized import parameterized+from products.data_catalog.backend import today_highlightsfrom products.data_catalog.backend.facade.api import PendingGroup, PendingKind, TeamPendingReview+from products.data_catalog.backend.facade.today_highlights import HIGHLIGHT_SOURCES+from products.today.backend.facade.contracts import HighlightContext, HighlightFindingsfrom products.today.backend.facade.enums import HighlightLabel-from products.today.backend.logic.highlight_registry import load_sources-from products.today.backend.logic.highlight_sources import data_catalog_approvals-from products.today.backend.logic.highlight_types import ContextMETRICS = PendingGroup(kind=PendingKind.METRICS, noun="metric", count=3, sample_names=[])RELATIONSHIPS = PendingGroup(kind=PendingKind.RELATIONSHIPS, noun="relationship", count=2, sample_names=[])@@ -43,10 +44,10 @@ class TestDataCatalogApprovalsHighlight(SimpleTestCase):review = TeamPendingReview(team_id=1, team_name="Team", groups=groups, total=sum(group.count for group in groups))- registered = next(source for source in load_sources() if source.name == "data_catalog_approvals")+ registered = next(source for source in HIGHLIGHT_SOURCES if source.name == "data_catalog_approvals")- with patch.object(data_catalog_approvals, "build_team_pending_review", return_value=review):- found = registered.find(self._context(can_approve=True))+ with patch.object(today_highlights, "build_team_pending_review", return_value=review):+ found = self._find(registered.find, can_approve=True)assert len(found.items) == 1item = found.items[0]@@ -58,14 +59,16 @@ class TestDataCatalogApprovalsHighlight(SimpleTestCase):def test_a_user_who_cannot_approve_gets_no_item(self) -> None:review = TeamPendingReview(team_id=1, team_name="Team", groups=[METRICS], total=3)- with patch.object(data_catalog_approvals, "build_team_pending_review", return_value=review):- found = data_catalog_approvals.find(self._context(can_approve=False))+ with patch.object(today_highlights, "build_team_pending_review", return_value=review):+ found = self._find(today_highlights.find_pending_approvals, can_approve=False)assert found.items == ()- def _context(self, *, can_approve: bool) -> Context:+ def _find(self, find: Callable[[HighlightContext], HighlightFindings], *, can_approve: bool) -> HighlightFindings:access = MagicMock()access.check_access_level_for_resource.side_effect = lambda resource, level: (can_approve and (resource, level) == ("data_catalog", "editor"))- return cast(Context, SimpleNamespace(team=SimpleNamespace(id=1), access=access))+ context = cast(HighlightContext, SimpleNamespace(team=SimpleNamespace(id=1), user=SimpleNamespace(id=2)))+ with patch.object(today_highlights, "UserAccessControl", return_value=access):+ return find(context)diff --git a/products/today/backend/logic/highlight_sources/data_catalog_approvals.py b/products/data_catalog/backend/today_highlights.pysimilarity index 67%rename from products/today/backend/logic/highlight_sources/data_catalog_approvals.pyrename to products/data_catalog/backend/today_highlights.pyindex 82889c7ac519..52eb73f5520d 100644--- a/products/today/backend/logic/highlight_sources/data_catalog_approvals.py+++ b/products/data_catalog/backend/today_highlights.py@@ -1,8 +1,7 @@-from products.access_control.backend.facade.user_access_control import AccessControlLevel+from products.access_control.backend.facade.user_access_control import AccessControlLevel, UserAccessControlfrom products.data_catalog.backend.facade.api import PendingGroup, build_team_pending_review--from ...facade.enums import HighlightLabel-from ..highlight_types import Candidate, Context, Found, Source+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings+from products.today.backend.facade.enums import HighlightLabelAPPROVER_ACCESS_LEVEL: AccessControlLevel = "editor"IMPORTANCE = 0.5@@ -13,16 +12,22 @@ ONE_DETAIL = "Review it in the data catalog."MANY_DETAIL = "Review them in the data catalog."-def find(context: Context) -> Found:- if not context.access.check_access_level_for_resource("data_catalog", APPROVER_ACCESS_LEVEL):- return Found()+def _join(groups: list[PendingGroup]) -> str:+ counts = [f"{group.count} {group.noun}{'' if group.count == 1 else 's'}" for group in groups]+ return counts[0] if len(counts) == 1 else f"{', '.join(counts[:-1])} and {counts[-1]}"+++def find_pending_approvals(context: HighlightContext) -> HighlightFindings:+ access = UserAccessControl(user=context.user, team=context.team)+ if not access.check_access_level_for_resource("data_catalog", APPROVER_ACCESS_LEVEL):+ return HighlightFindings()review = build_team_pending_review(context.team, sample_size=0)if review is None:- return Found()+ return HighlightFindings()one = review.total == 1- return Found(+ return HighlightFindings(items=(- Candidate(+ HighlightCandidate(key="data_catalog_approvals",label=HighlightLabel.OPPORTUNITY,family="data_catalog",@@ -34,15 +39,3 @@ def find(context: Context) -> Found:),))---def _join(groups: list[PendingGroup]) -> str:- counts = [f"{group.count} {group.noun}{'' if group.count == 1 else 's'}" for group in groups]- return counts[0] if len(counts) == 1 else f"{', '.join(counts[:-1])} and {counts[-1]}"---SOURCE = Source(- name="data_catalog_approvals",- find=find,- scopes=("data_catalog:read", "data_catalog_approval:write"),-)diff --git a/products/experiments/backend/facade/today_highlights.py b/products/experiments/backend/facade/today_highlights.pynew file mode 100644index 000000000000..68b559577ba5--- /dev/null+++ b/products/experiments/backend/facade/today_highlights.py@@ -0,0 +1,7 @@+"""Experiments' sources for the "For you today" list. Today finds this module by name."""++from products.today.backend.facade.contracts import HighlightSource++from ..today_highlights import find_experiment_highlights++HIGHLIGHT_SOURCES = (HighlightSource(name="experiments", find=find_experiment_highlights, scopes=("experiment:read",)),)diff --git a/products/today/backend/tests/test_highlight_experiments.py b/products/experiments/backend/test/test_today_highlights.pysimilarity index 70%rename from products/today/backend/tests/test_highlight_experiments.pyrename to products/experiments/backend/test/test_today_highlights.pyindex 6cdb615791e1..138e709cddc2 100644--- a/products/today/backend/tests/test_highlight_experiments.py+++ b/products/experiments/backend/test/test_today_highlights.py@@ -6,10 +6,11 @@ from unittest.mock import MagicMock, patchfrom parameterized import parameterized+from products.experiments.backend import today_highlightsfrom products.experiments.backend.facade.contracts import EndedExperiment, RunningExperiment-from products.today.backend.logic.highlight_registry import load_sources-from products.today.backend.logic.highlight_sources import experiments-from products.today.backend.logic.highlight_types import Context, Found+from products.experiments.backend.facade.today_highlights import HIGHLIGHT_SOURCES+from products.today.backend.facade.contracts import HighlightFindings+from products.today.backend.facade.testing import highlight_contextMONDAY = date(2026, 10, 12)TUESDAY = date(2026, 10, 13)@@ -22,18 +23,18 @@ RUNNING = RunningExperiment(@time_machine.travel(NOW, tick=False)class TestExperiments(BaseTest):- def _find(self, today: date, running: MagicMock, enrolled: MagicMock) -> tuple[Found, Context]:- registered = next(s for s in load_sources() if s.name == "experiments")- context = Context(self.team, self.user, today)+ def _find(self, today: date, running: MagicMock, enrolled: MagicMock) -> HighlightFindings:+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "experiments")+ context = highlight_context(team=self.team, user=self.user, today=today)with (- patch.object(experiments, "list_ended_experiments_without_conclusion", return_value=[ENDED]),- patch.object(experiments, "list_running_experiments", running),- patch.object(experiments, "count_enrolled_people", enrolled),+ patch.object(today_highlights, "list_ended_experiments_without_conclusion", return_value=[ENDED]),+ patch.object(today_highlights, "list_running_experiments", running),+ patch.object(today_highlights, "count_enrolled_people", enrolled),):- return registered.find(context), context+ return registered.find(context)def test_an_ended_experiment_without_a_decision_is_an_opportunity(self) -> None:- found, _ = self._find(TUESDAY, MagicMock(return_value=[]), MagicMock(return_value={}))+ found = self._find(TUESDAY, MagicMock(return_value=[]), MagicMock(return_value={}))self.assertEqual([(c.title, c.detail, c.url) for c in found.items],@@ -70,17 +71,13 @@ class TestExperiments(BaseTest):def test_a_long_running_experiment_with_few_users_is_a_risk(self, _name: str, enrolled: int, title: str | None) -> None:- found, _ = self._find(+ found = self._find(TUESDAY, MagicMock(return_value=[RUNNING]), MagicMock(return_value={"onboarding-tips": enrolled}))self.assertEqual([c.title for c in found.items][1:], [title] if title else [])def test_a_failed_count_keeps_the_ended_reminders(self) -> None:- found, context = self._find(- TUESDAY, MagicMock(return_value=[RUNNING]), MagicMock(side_effect=TimeoutError("slow"))- )+ found = self._find(TUESDAY, MagicMock(return_value=[RUNNING]), MagicMock(side_effect=TimeoutError("slow")))- self.assertEqual(- ([c.key for c in found.items], context.failures), (["experiment_ended:7"], ["experiments_enrolled"])- )+ self.assertEqual([c.key for c in found.items], ["experiment_ended:7"])diff --git a/products/today/backend/logic/highlight_sources/experiments.py b/products/experiments/backend/today_highlights.pysimilarity index 83%rename from products/today/backend/logic/highlight_sources/experiments.pyrename to products/experiments/backend/today_highlights.pyindex e343b01e6798..5f35b6d6b710 100644--- a/products/today/backend/logic/highlight_sources/experiments.py+++ b/products/experiments/backend/today_highlights.py@@ -9,10 +9,9 @@ from products.experiments.backend.facade.api import (list_running_experiments,)from products.experiments.backend.facade.contracts import EndedExperiment, RunningExperiment--from ...facade.enums import HighlightLabel-from ..highlight_rules import short, users-from ..highlight_types import Candidate, Context, Found, Source+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings+from products.today.backend.facade.enums import HighlightLabel+from products.today.backend.facade.highlight_helpers import short, usersENDED = "Experiment ‘{experiment}’ ended {when}"ENDED_DETAIL = "Read the results and decide whether to release the change"@@ -25,35 +24,7 @@ JUST_CROSSED_DAYS = 67MIN_PEOPLE = 100-def find(context: Context) -> Found:- now = timezone.now()- ended = list_ended_experiments_without_conclusion(- team_id=context.team.id, user_id=context.user.id, since=now - timedelta(days=ENDED_WINDOW_DAYS), limit=20- )- running = list_running_experiments(- team_id=context.team.id,- user_id=context.user.id,- started_after=None if context.today.weekday() == 0 else now - timedelta(days=JUST_CROSSED_DAYS),- started_before=now - timedelta(days=LONG_RUNNING_DAYS),- limit=100,- )- enrolled = context.guard(- "experiments_enrolled",- lambda: count_enrolled_people(- team=context.team, user=context.user, flag_keys=[experiment.flag_key for experiment in running]- ),- None,- )- counted = [] if enrolled is None else [(experiment, enrolled.get(experiment.flag_key, 0)) for experiment in running]- return Found(- items=(- *(_ended(context, experiment) for experiment in ended),- *(_few_users(experiment, people) for experiment, people in counted if people < MIN_PEOPLE),- )- )---def _days_since(context: Context, moment: datetime) -> int:+def _days_since(context: HighlightContext, moment: datetime) -> int:return (context.today - timezone.localtime(moment, context.team.timezone_info).date()).days@@ -65,8 +36,8 @@ def _name(name: str, limit: int) -> str:return short(re.sub(r"(?i)\s+experiment$", "", name) or name, limit)-def _ended(context: Context, experiment: EndedExperiment) -> Candidate:- return Candidate(+def _ended(context: HighlightContext, experiment: EndedExperiment) -> HighlightCandidate:+ return HighlightCandidate(key=f"experiment_ended:{experiment.id}",label=HighlightLabel.OPPORTUNITY,family="experiments",@@ -80,8 +51,8 @@ def _ended(context: Context, experiment: EndedExperiment) -> Candidate:)-def _few_users(experiment: RunningExperiment, enrolled: int) -> Candidate:- return Candidate(+def _few_users(experiment: RunningExperiment, enrolled: int) -> HighlightCandidate:+ return HighlightCandidate(key=f"experiment_stale:{experiment.id}",label=HighlightLabel.RISK,family="experiments",@@ -95,4 +66,29 @@ def _few_users(experiment: RunningExperiment, enrolled: int) -> Candidate:)-SOURCE = Source(name="experiments", find=find, scopes=("experiment:read",))+def find_experiment_highlights(context: HighlightContext) -> HighlightFindings:+ now = timezone.now()+ ended = list_ended_experiments_without_conclusion(+ team_id=context.team.id, user_id=context.user.id, since=now - timedelta(days=ENDED_WINDOW_DAYS), limit=20+ )+ running = list_running_experiments(+ team_id=context.team.id,+ user_id=context.user.id,+ started_after=None if context.today.weekday() == 0 else now - timedelta(days=JUST_CROSSED_DAYS),+ started_before=now - timedelta(days=LONG_RUNNING_DAYS),+ limit=100,+ )+ enrolled = context.guard(+ "experiments_enrolled",+ lambda: count_enrolled_people(+ team=context.team, user=context.user, flag_keys=[experiment.flag_key for experiment in running]+ ),+ None,+ )+ counted = [] if enrolled is None else [(experiment, enrolled.get(experiment.flag_key, 0)) for experiment in running]+ return HighlightFindings(+ items=(+ *(_ended(context, experiment) for experiment in ended),+ *(_few_users(experiment, people) for experiment, people in counted if people < MIN_PEOPLE),+ )+ )diff --git a/products/feature_flags/backend/facade/today_highlights.py b/products/feature_flags/backend/facade/today_highlights.pynew file mode 100644index 000000000000..7bdbac970b3e--- /dev/null+++ b/products/feature_flags/backend/facade/today_highlights.py@@ -0,0 +1,7 @@+"""Feature flags' sources for the "For you today" list. Today finds this module by name."""++from products.today.backend.facade.contracts import HighlightSource++from ..today_highlights import find_flag_highlights++HIGHLIGHT_SOURCES = (HighlightSource(name="flags", find=find_flag_highlights, scopes=("feature_flag:read",)),)diff --git a/products/today/backend/tests/test_highlight_flags.py b/products/feature_flags/backend/test/test_today_highlights.pysimilarity index 91%rename from products/today/backend/tests/test_highlight_flags.pyrename to products/feature_flags/backend/test/test_today_highlights.pyindex b466d2476900..c997ac850fca 100644--- a/products/today/backend/tests/test_highlight_flags.py+++ b/products/feature_flags/backend/test/test_today_highlights.py@@ -9,10 +9,10 @@ from django.test import SimpleTestCasefrom parameterized import parameterized+from products.feature_flags.backend import today_highlights+from products.feature_flags.backend.facade.today_highlights import HIGHLIGHT_SOURCESfrom products.feature_flags.backend.facade.usage import CreatedFlag, FlagCalls, FlagCallSummary-from products.today.backend.logic.highlight_registry import load_sources-from products.today.backend.logic.highlight_sources import flags-from products.today.backend.logic.highlight_types import Context+from products.today.backend.facade.contracts import HighlightContextMONDAY = date(2026, 10, 12)TUESDAY = date(2026, 10, 13)@@ -55,7 +55,7 @@ class TestFlags(SimpleTestCase):covers_all_environments: bool = True,) -> list[tuple[str, str, str | None]]:context = cast(- Context,+ HighlightContext,SimpleNamespace(team=SimpleNamespace(id=1, timezone_info=ZoneInfo("UTC")),user=SimpleNamespace(id=2),@@ -63,11 +63,11 @@ class TestFlags(SimpleTestCase):daily=lambda _name, compute: compute(),),)- registered = next(s for s in load_sources() if s.name == "flags")+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "flags")summary = FlagCallSummary(by_key=by_key, complete=complete, covers_all_environments=covers_all_environments)with (- patch.object(flags, "list_flags_created_by", return_value=created_flags),- patch.object(flags, "summarize_flag_calls", return_value=summary),+ patch.object(today_highlights, "list_flags_created_by", return_value=created_flags),+ patch.object(today_highlights, "summarize_flag_calls", return_value=summary),):return [(c.title, c.detail, c.url) for c in registered.find(context).items]diff --git a/products/today/backend/logic/highlight_sources/flags.py b/products/feature_flags/backend/today_highlights.pysimilarity index 85%rename from products/today/backend/logic/highlight_sources/flags.pyrename to products/feature_flags/backend/today_highlights.pyindex 6b269b42c9a2..4eea8ad714c9 100644--- a/products/today/backend/logic/highlight_sources/flags.py+++ b/products/feature_flags/backend/today_highlights.py@@ -11,10 +11,9 @@ from products.feature_flags.backend.facade.usage import (list_flags_created_by,summarize_flag_calls,)--from ...facade.enums import HighlightLabel-from ..highlight_rules import exact, human-from ..highlight_types import Candidate, Context, Found, Source+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings+from products.today.backend.facade.enums import HighlightLabel+from products.today.backend.facade.highlight_helpers import exact, humanREACH_DROP = "Flag ‘{flag}’ reached {pct}% fewer users in the last 7 days"REACH_DROP_DETAIL = "{before} → {now} · Check the code that calls it"@@ -37,37 +36,8 @@ NO_CALLS = FlagCalls()-def find(context: Context) -> Found:- flags = [- flag- for flag in list_flags_created_by(context.team.id, context.user.id, limit=500)- if not flag.remote_configuration and not flag.key.startswith(INTERNAL_FLAG_PREFIXES)- ]- if not flags:- return Found()- summary = context.daily("flag_calls", lambda: summarize_flag_calls(context.team, context.user))- items: list[Candidate] = []- removable: list[CreatedFlag] = []- same: list[tuple[CreatedFlag, FlagCalls]] = []- for flag in flags:- calls = summary.by_key.get(flag.key, NO_CALLS)- if calls.people_last_week >= MIN_REACH and calls.people_this_week <= calls.people_last_week / 2:- items.append(_reach_drop(flag, calls))- if flag.removal_blocked or RISKY_FLAGS.search(flag.key) or not summary.covers_all_environments:- continue- age = (context.today - timezone.localtime(flag.created_at, context.team.timezone_info).date()).days- if age >= SAME_VALUE_MIN_AGE_DAYS and calls.people_this_week >= MIN_REACH and calls.values_this_week == 1:- removable.append(flag)- same.append((flag, calls))- elif age >= FLAG_CALL_DAYS and calls.calls == 0 and summary.complete:- removable.append(flag)- if cleanup := _cleanup(context, removable, same):- items.append(cleanup)- return Found(items=tuple(items))---def _reach_drop(flag: CreatedFlag, calls: FlagCalls) -> Candidate:- return Candidate(+def _reach_drop(flag: CreatedFlag, calls: FlagCalls) -> HighlightCandidate:+ return HighlightCandidate(key=f"flag_reach_drop:{flag.id}",label=HighlightLabel.RISK,family="flags",@@ -87,8 +57,8 @@ def _listing(keys: list[str]) -> str:def _cleanup(- context: Context, removable: list[CreatedFlag], same: list[tuple[CreatedFlag, FlagCalls]]-) -> Candidate | None:+ context: HighlightContext, removable: list[CreatedFlag], same: list[tuple[CreatedFlag, FlagCalls]]+) -> HighlightCandidate | None:if context.today.weekday() == 0 and removable:keys = [flag.key for flag in sorted(removable, key=lambda flag: flag.created_at)]if len(keys) > 1:@@ -104,7 +74,7 @@ def _cleanup(return Nonetitle = CLEANUP_COST.format(n=len(same), cost=human(cost))detail = CLEANUP_COST_DETAIL.format(names=_listing([flag.key for flag, _ in same]))- return Candidate(+ return HighlightCandidate(key="flag_cleanup",label=HighlightLabel.OPPORTUNITY,family="flag_cleanup",@@ -116,4 +86,30 @@ def _cleanup()-SOURCE = Source(name="flags", find=find, scopes=("feature_flag:read",))+def find_flag_highlights(context: HighlightContext) -> HighlightFindings:+ flags = [+ flag+ for flag in list_flags_created_by(context.team.id, context.user.id, limit=500)+ if not flag.remote_configuration and not flag.key.startswith(INTERNAL_FLAG_PREFIXES)+ ]+ if not flags:+ return HighlightFindings()+ summary = context.daily("flag_calls", lambda: summarize_flag_calls(context.team, context.user))+ items: list[HighlightCandidate] = []+ removable: list[CreatedFlag] = []+ same: list[tuple[CreatedFlag, FlagCalls]] = []+ for flag in flags:+ calls = summary.by_key.get(flag.key, NO_CALLS)+ if calls.people_last_week >= MIN_REACH and calls.people_this_week <= calls.people_last_week / 2:+ items.append(_reach_drop(flag, calls))+ if flag.removal_blocked or RISKY_FLAGS.search(flag.key) or not summary.covers_all_environments:+ continue+ age = (context.today - timezone.localtime(flag.created_at, context.team.timezone_info).date()).days+ if age >= SAME_VALUE_MIN_AGE_DAYS and calls.people_this_week >= MIN_REACH and calls.values_this_week == 1:+ removable.append(flag)+ same.append((flag, calls))+ elif age >= FLAG_CALL_DAYS and calls.calls == 0 and summary.complete:+ removable.append(flag)+ if cleanup := _cleanup(context, removable, same):+ items.append(cleanup)+ return HighlightFindings(items=tuple(items))diff --git a/products/today/AGENTS.md b/products/today/AGENTS.mdindex 26939790f899..9b8201606f83 100644--- a/products/today/AGENTS.md+++ b/products/today/AGENTS.md@@ -5,36 +5,18 @@Today ranks facts that other products find and shows the best few.The product that owns the data owns its source: the query, the thresholds, and the copy.Today owns the contract, the ranking, and the shared helpers.+Today also owns the pulse: the routine and key-metric tiles, pinned numbers, and the home dashboard source.+These live in `backend/logic/today_highlights/` and Today declares them in `backend/facade/today_highlights.py`.-**A new source lives in its own product, never in `products/today/`.**+**A source that another team owns lives in that team's product, never in `products/today/`.**+The how-to for a product team is the `adding-today-highlights` skill (`.agents/skills/adding-today-highlights/SKILL.md`), because a producer works in its own product and never loads this file.-1. Put the rule in the product's internals, for example `products/<x>/backend/today_highlights.py`.- It takes a `HighlightContext` and returns `HighlightFindings`.-2. Declare it in `products/<x>/backend/facade/today_highlights.py`:-- ```python- from products.today.backend.facade.contracts import HighlightSource-- from ..today_highlights import find_stale_things-- HIGHLIGHT_SOURCES = (HighlightSource(name="stale_things", find=find_stale_things, scopes=("thing:read",)),)- ```--3. Add `"products.today"` to the product's `depends_on` in `tach.toml`. Today gets no new dependency.-4. Test the rule in the product, with `products.today.backend.facade.testing.highlight_context`.--Today finds the declaration through `posthog.products.load_product_modules`, so a new source changes no file in Today.+Today finds every declaration through `posthog.products.load_product_modules`, so a new source changes no backend file in Today.The registry raises on a missing declaration, an unusable entry, or a source name that another product already uses.+It also records the product that declares each source, and the row icon comes from that product (`PRODUCT_ICONS` in `frontend/src/scenes/project-homepage/today/todayRowIcons.tsx`).-Import only from Today's facade:--- `facade/contracts.py`: `HighlightCandidate`, `HighlightFindings`, `HighlightContext`, `HighlightSource`, `HighlightMetric`, `DailyValueNotReady`-- `facade/enums.py`: `HighlightLabel`, `HighlightUnit`, `HighlightInterval`-- `facade/highlight_helpers.py`: number and text formatting, `uses_product`, and trend detection--`HighlightContext.daily()` caches one value per team, property restrictions and day, so every viewer with the same restrictions shares it.-Never compute a per-viewer value there without the user id in its name.+The facade (`contracts.py`, `enums.py`, `highlight_helpers.py`, `testing.py`) is a contract with every producing product.+Change it only in a backward-compatible way: an added field gets a default, because Today validates stored results against these types.-**Status:** `backend/logic/highlight_sources/` is deprecated.-The sources in it still load, through legacy aliases in `logic/highlight_types.py`, until each one moves into its product.-Do not add a file there and do not copy those files as an example.+**Status:** every other team's source lives in its own product.+`backend/logic/highlight_sources/` and its `SOURCE` lookup are gone, so a file there no longer loads.diff --git a/products/today/backend/facade/contracts.py b/products/today/backend/facade/contracts.pyindex e9f26052b63e..46cac6e6a5c0 100644--- a/products/today/backend/facade/contracts.py+++ b/products/today/backend/facade/contracts.py@@ -205,6 +205,8 @@ class HighlightItem:url: str | Noneseries: list[float] | Nonescore: float+ # Results stored before this field existed have no product.+ product: str | None = None@dataclass(frozen=True)@@ -304,7 +306,7 @@ class HighlightSource:Today finds that module by name, so a new source changes no file in Today."""- # Unique across products. Today keys stored results and the frontend icon by it.+ # Unique across products and stable: Today keys stored results and analytics by it, so a rename breaks them.name: strfind: Callable[[HighlightContext], HighlightFindings]# Today skips the source when the viewer's API scopes or access controls do not cover these.diff --git a/products/today/backend/facade/today_highlights.py b/products/today/backend/facade/today_highlights.pynew file mode 100644index 000000000000..a7bc9cb41951--- /dev/null+++ b/products/today/backend/facade/today_highlights.py@@ -0,0 +1,5 @@+"""Today's own sources for the "For you today" list: the pulse and the home dashboard. Today finds this module by name."""++from ..logic.today_highlights import home, key_metrics, routine++HIGHLIGHT_SOURCES = (home.SOURCE, key_metrics.SOURCE, routine.SOURCE)diff --git a/products/today/backend/logic/highlight_registry.py b/products/today/backend/logic/highlight_registry.pyindex 8ae68c148339..de3976473d4c 100644--- a/products/today/backend/logic/highlight_registry.py+++ b/products/today/backend/logic/highlight_registry.py@@ -1,13 +1,10 @@-import pkgutil-import importlib-from collections.abc import Iterator+from collections.abc import Mappingfrom functools import cache-from types import ModuleType+from posthog.dataclasses import frozenfrom posthog.products import load_product_modulesfrom ..facade.contracts import HighlightSource-from . import highlight_sourcesSOURCES_MODULE = "facade.today_highlights"SOURCES_ATTRIBUTE = "HIGHLIGHT_SOURCES"@@ -17,30 +14,28 @@ class HighlightRegistryError(Exception):pass-def _legacy_modules() -> Iterator[ModuleType]:- for name in sorted(module.name for module in pkgutil.iter_modules(highlight_sources.__path__)):- yield importlib.import_module(f"{highlight_sources.__name__}.{name}")+@frozen+class HighlightRegistry:+ sources: tuple[HighlightSource, ...]+ products: Mapping[str, str]-def _declared(module: ModuleType) -> object:- if module.__name__.startswith(f"{highlight_sources.__name__}."):- source = getattr(module, "SOURCE", None)- return None if source is None else (source,)- return getattr(module, SOURCES_ATTRIBUTE, None)+def _product(module_name: str) -> str:+ # Product apps are named `products.<product>.backend`.+ return module_name.split(".")[1]@cache-def load_sources() -> tuple[HighlightSource, ...]:+def load_registry() -> HighlightRegistry:"""Every source that a product declares in `backend/facade/today_highlights.py`, sorted by name.- A product depends on Today's facade to declare a source, so Today needs no import of that product.- Sources still in the legacy `highlight_sources/` package declare a module-level `SOURCE` and load too.+ Today imports no product by name, so the dependency points from the product to Today's facade.A broken declaration raises instead of dropping the source without a trace."""sources: dict[str, HighlightSource] = {}owners: dict[str, str] = {}- for module in [*load_product_modules(SOURCES_MODULE), *_legacy_modules()]:- declared = _declared(module)+ for module in load_product_modules(SOURCES_MODULE):+ declared = getattr(module, SOURCES_ATTRIBUTE, None)if not isinstance(declared, tuple | list):raise HighlightRegistryError(f"{module.__name__}.{SOURCES_ATTRIBUTE} must be a tuple of HighlightSource")for source in declared:@@ -54,4 +49,16 @@ def load_sources() -> tuple[HighlightSource, ...]:)sources[source.name] = sourceowners[source.name] = module.__name__- return tuple(sources[name] for name in sorted(sources))+ return HighlightRegistry(+ sources=tuple(sources[name] for name in sorted(sources)),+ products={name: _product(module_name) for name, module_name in owners.items()},+ )+++def load_sources() -> tuple[HighlightSource, ...]:+ return load_registry().sources+++def source_product(name: str) -> str | None:+ """None for a name that no product declares, such as a source removed after a result was stored."""+ return load_registry().products.get(name)diff --git a/products/today/backend/logic/highlight_sources/__init__.py b/products/today/backend/logic/highlight_sources/__init__.pydeleted file mode 100644index 2135e1b95106..000000000000--- a/products/today/backend/logic/highlight_sources/__init__.py+++ /dev/null@@ -1,5 +0,0 @@-"""Deprecated: sources that still live inside Today.--New sources belong in their own product: `HIGHLIGHT_SOURCES` in `products/<x>/backend/facade/today_highlights.py`.-The modules here move out into their products, after which this package goes away.-"""diff --git a/products/today/backend/logic/highlight_types.py b/products/today/backend/logic/highlight_types.pyindex ab2924f46dfe..06acfd95c1a9 100644--- a/products/today/backend/logic/highlight_types.py+++ b/products/today/backend/logic/highlight_types.py@@ -29,7 +29,7 @@ from ..facade.contracts import (HighlightSource,)-# Legacy names for the sources still in highlight_sources/. New sources use the facade contract.+# Short names for Today's own sources in today_highlights/. Other products use the facade contract.Candidate = HighlightCandidateFound = HighlightFindings@@ -113,10 +113,10 @@ class Context:return default-def Source( # noqa: N802 - keeps the legacy name the sources in highlight_sources/ call+def Source( # noqa: N802 - reads like the HighlightSource it builds*, name: str, find: Callable[[Context], HighlightFindings], scopes: tuple[str, ...] = (), pulse_order: int = 0) -> HighlightSource:- # A legacy source reads Today's own Context. Today always calls it with one, so the cast holds.+ # Today's own sources read Today's full Context. Today always calls them with one, so the cast holds.return HighlightSource(name=name,find=cast(Callable[[HighlightContext], HighlightFindings], find),diff --git a/products/today/backend/logic/highlights.py b/products/today/backend/logic/highlights.pyindex 19f435289262..a1e789f4795c 100644--- a/products/today/backend/logic/highlights.py+++ b/products/today/backend/logic/highlights.py@@ -37,7 +37,7 @@ from ..temporal.inputs import (highlights_workflow_id,)from . import pulse_pins-from .highlight_registry import load_sources+from .highlight_registry import load_sources, source_productfrom .highlight_types import CACHE_SECONDS, Context, property_restrictionsfrom .pinned import PINNED_METRICS@@ -259,6 +259,7 @@ def _item(candidate: HighlightCandidate) -> contracts.HighlightItem:url=candidate.url,series=candidate.series,score=score,+ product=source_product(candidate.source),)diff --git a/products/today/backend/logic/pinned.py b/products/today/backend/logic/pinned.pyindex 3a8cce00011f..969d84d912e7 100644--- a/products/today/backend/logic/pinned.py+++ b/products/today/backend/logic/pinned.py@@ -11,10 +11,10 @@ from products.customer_analytics.backend.facade.api import get_key_metricsfrom ..facade import contractsfrom ..temporal.inputs import PinnedNumber, ResolvePinsInputs, ResolvePinsResult-from .highlight_sources.key_metrics import tile-from .highlight_sources.routine import dashboard_tile_metric, insight_metricfrom .highlight_types import Contextfrom .pulse_pins import INSIGHT_PREFIX, required_scopes+from .today_highlights.key_metrics import tile+from .today_highlights.routine import dashboard_tile_metric, insight_metricPINNED_METRICS = TypeAdapter(list[contracts.HighlightMetric])diff --git a/products/today/backend/logic/today_highlights/__init__.py b/products/today/backend/logic/today_highlights/__init__.pynew file mode 100644index 000000000000..e69de29bb2d1diff --git a/products/today/backend/logic/highlight_sources/home.py b/products/today/backend/logic/today_highlights/home.pysimilarity index 100%rename from products/today/backend/logic/highlight_sources/home.pyrename to products/today/backend/logic/today_highlights/home.pydiff --git a/products/today/backend/logic/highlight_sources/key_metrics.py b/products/today/backend/logic/today_highlights/key_metrics.pysimilarity index 100%rename from products/today/backend/logic/highlight_sources/key_metrics.pyrename to products/today/backend/logic/today_highlights/key_metrics.pydiff --git a/products/today/backend/logic/highlight_sources/routine.py b/products/today/backend/logic/today_highlights/routine.pysimilarity index 100%rename from products/today/backend/logic/highlight_sources/routine.pyrename to products/today/backend/logic/today_highlights/routine.pydiff --git a/products/today/backend/presentation/serializers.py b/products/today/backend/presentation/serializers.pyindex 08ae3007ddfb..f6e0280d48a5 100644--- a/products/today/backend/presentation/serializers.py+++ b/products/today/backend/presentation/serializers.py@@ -422,6 +422,9 @@ class HighlightItemSerializer(DataclassSerializer):dataclass = HighlightItemextra_kwargs = {"source": {"help_text": "Name of the highlight source that found the item, for example alerts."},+ "product": {+ "help_text": "Product that declares the source, for example feature_flags. Null for items stored before this field existed and for sources that no product declares any more."+ },}diff --git a/products/today/backend/tests/test_api.py b/products/today/backend/tests/test_api.pyindex 602b320ef11d..7b43ac9f2567 100644--- a/products/today/backend/tests/test_api.py+++ b/products/today/backend/tests/test_api.py@@ -27,8 +27,8 @@ from posthog.models.personal_api_key import hash_key_valuefrom products.access_control.backend.models.access_control import AccessControlfrom products.signals.backend.facade import api as signalsfrom products.signals.backend.models import SignalReport+from products.today.backend.facade.contracts import HighlightFindings, HighlightSourcefrom products.today.backend.logic import highlights, pinned-from products.today.backend.logic.highlight_types import Found, Sourcefrom products.today.backend.logic.jev import JevPickfrom products.today.backend.temporal.inputs import (ComputeHighlightsInputs,@@ -355,9 +355,9 @@ def _temporal() -> MagicMock:class TestTodayHighlightsAPI(TodayTeamScopedTestMixin, APIBaseTest):def _get(self, connect: MagicMock, flag: bool = True, pulse: tuple[str, ...] = ("k1",)) -> "_MonkeyPatchedResponse":- source = Source(+ source = HighlightSource(name="alerts",- find=lambda _c: Found(+ find=lambda _c: HighlightFindings(items=(candidate("alert:1", "alerts", 0.8),), pulse=tuple(metric(key) for key in pulse)),)diff --git a/products/today/backend/tests/test_highlight_insights.py b/products/today/backend/tests/test_highlight_insights.pyindex bebf82e89ff6..c6e44e4eede8 100644--- a/products/today/backend/tests/test_highlight_insights.py+++ b/products/today/backend/tests/test_highlight_insights.py@@ -16,9 +16,9 @@ from posthog.models import FileSystemViewLogfrom products.dashboards.backend.facade.api import DashboardInsights, DashboardInsightTilefrom products.product_analytics.backend.facade.contracts import InsightDashboardContext, InsightSeriesfrom products.today.backend.logic.highlight_rules import human, short-from products.today.backend.logic.highlight_sources import home, routinefrom products.today.backend.logic.highlight_trends import BAD_METRIC, MONEY, UNCLEAR_LABEL, UNKNOWN_DIRECTIONfrom products.today.backend.logic.highlight_types import Context+from products.today.backend.logic.today_highlights import home, routineTODAY = date(2026, 10, 13)diff --git a/products/today/backend/tests/test_highlight_key_metrics.py b/products/today/backend/tests/test_highlight_key_metrics.pyindex 2ec2ac1dc9da..ec92961b04a2 100644--- a/products/today/backend/tests/test_highlight_key_metrics.py+++ b/products/today/backend/tests/test_highlight_key_metrics.py@@ -10,8 +10,8 @@ from django.test import SimpleTestCasefrom products.customer_analytics.backend.facade.contracts import KeyMetricfrom products.today.backend.logic.highlight_registry import load_sources-from products.today.backend.logic.highlight_sources import key_metricsfrom products.today.backend.logic.highlight_types import Context, DailyValueNotReady+from products.today.backend.logic.today_highlights import key_metricsTODAY = date(2026, 10, 13)diff --git a/products/today/backend/tests/test_highlights.py b/products/today/backend/tests/test_highlights.pyindex 89587a653433..8d5e2925beb0 100644--- a/products/today/backend/tests/test_highlights.py+++ b/products/today/backend/tests/test_highlights.py@@ -490,4 +490,19 @@ class TestLoadSources(SimpleTestCase):def test_a_broken_declaration_raises(self, _name: str, module: SimpleNamespace) -> None:with patch.object(highlight_registry, "load_product_modules", return_value=[module]):with self.assertRaises(highlight_registry.HighlightRegistryError):- highlight_registry.load_sources.__wrapped__()+ highlight_registry.load_registry.__wrapped__()++ def test_each_source_belongs_to_the_product_that_declares_it(self) -> None:+ flags = SimpleNamespace(+ __name__="products.feature_flags.backend.facade.today_highlights",+ HIGHLIGHT_SOURCES=(HighlightSource(name="flags", find=lambda _c: HighlightFindings()),),+ )+ pulse = SimpleNamespace(+ __name__="products.today.backend.facade.today_highlights",+ HIGHLIGHT_SOURCES=(HighlightSource(name="routine", find=lambda _c: HighlightFindings()),),+ )++ with patch.object(highlight_registry, "load_product_modules", return_value=[flags, pulse]):+ registry = highlight_registry.load_registry.__wrapped__()++ self.assertEqual(dict(registry.products), {"flags": "feature_flags", "routine": "today"})diff --git a/products/today/backend/tests/test_pinned.py b/products/today/backend/tests/test_pinned.pyindex 2909bbd7d01c..3c9cf62f219d 100644--- a/products/today/backend/tests/test_pinned.py+++ b/products/today/backend/tests/test_pinned.py@@ -15,7 +15,7 @@ from products.product_analytics.backend.facade.contracts import InsightSeriesfrom products.today.backend.facade import contractsfrom products.today.backend.facade.contracts import PulsePinfrom products.today.backend.logic import pinned, pulse_pins-from products.today.backend.logic.highlight_sources import routine+from products.today.backend.logic.today_highlights import routinefrom products.today.backend.temporal.inputs import PinnedNumber, ResolvePinsInputsTODAY = date(2026, 10, 13)diff --git a/products/today/frontend/generated/api.schemas.ts b/products/today/frontend/generated/api.schemas.tsindex 859cbdc0e6fe..0e33722c4c35 100644--- a/products/today/frontend/generated/api.schemas.ts+++ b/products/today/frontend/generated/api.schemas.ts@@ -247,6 +247,11 @@ export interface HighlightItemApi {score: number/** Name of the highlight source that found the item, for example alerts. */source: string+ /**+ * Product that declares the source, for example feature_flags. Null for items stored before this field existed and for sources that no product declares any more.+ * @nullable+ */+ product?: string | null}/**diff --git a/products/web_analytics/backend/facade/today_highlights.py b/products/web_analytics/backend/facade/today_highlights.pynew file mode 100644index 000000000000..024f118309c3--- /dev/null+++ b/products/web_analytics/backend/facade/today_highlights.py@@ -0,0 +1,7 @@+"""Web analytics' sources for the "For you today" list. Today finds this module by name."""++from products.today.backend.facade.contracts import HighlightSource++from ..today_highlights import find_rage_page++HIGHLIGHT_SOURCES = (HighlightSource(name="rage", find=find_rage_page),)diff --git a/products/today/backend/tests/test_highlight_rage.py b/products/web_analytics/backend/test/test_today_highlights.pysimilarity index 83%rename from products/today/backend/tests/test_highlight_rage.pyrename to products/web_analytics/backend/test/test_today_highlights.pyindex 5e45451ffc78..5197ed9090a3 100644--- a/products/today/backend/tests/test_highlight_rage.py+++ b/products/web_analytics/backend/test/test_today_highlights.py@@ -10,10 +10,10 @@ from django.test import SimpleTestCasefrom parameterized import parameterizedfrom products.error_tracking.backend.facade.contracts import ErrorTrackingIssueBasics-from products.today.backend.logic.highlight_registry import load_sources-from products.today.backend.logic.highlight_sources import rage-from products.today.backend.logic.highlight_types import Context+from products.today.backend.facade.contracts import HighlightContext+from products.web_analytics.backend import today_highlightsfrom products.web_analytics.backend.facade.rage_pages import ErrorsBeforeRage, RagePage+from products.web_analytics.backend.facade.today_highlights import HIGHLIGHT_SOURCESISSUE_ID = uuid.UUID("01890000-0000-7000-8000-000000000002")PAGE = RagePage(path="/checkout/…", people=12, clicks=340)@@ -100,7 +100,7 @@ class TestRage(SimpleTestCase):expected: list[tuple[str, str, str]],) -> None:context = cast(- Context,+ HighlightContext,SimpleNamespace(team=SimpleNamespace(id=1),user=SimpleNamespace(id=2),@@ -120,14 +120,14 @@ class TestRage(SimpleTestCase):created_at=datetime(2026, 10, 1, tzinfo=UTC),first_seen=None,)- registered = next(s for s in load_sources() if s.name == "rage")+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "rage")with (- patch.object(rage, "uses_product", return_value=relevant),- patch.object(rage, "find_top_rage_page", return_value=page),- patch.object(rage, "find_top_rage_element", return_value=element),- patch.object(rage, "find_errors_before_rage", return_value=errors),- patch.object(rage, "get_issue_basics", return_value=issue),+ patch.object(today_highlights, "uses_product", return_value=relevant),+ patch.object(today_highlights, "find_top_rage_page", return_value=page),+ patch.object(today_highlights, "find_top_rage_element", return_value=element),+ patch.object(today_highlights, "find_errors_before_rage", return_value=errors),+ patch.object(today_highlights, "get_issue_basics", return_value=issue),):found = registered.find(context)diff --git a/products/today/backend/logic/highlight_sources/rage.py b/products/web_analytics/backend/today_highlights.pysimilarity index 81%rename from products/today/backend/logic/highlight_sources/rage.pyrename to products/web_analytics/backend/today_highlights.pyindex 1d10fca3092c..5c9ece4fbeea 100644--- a/products/today/backend/logic/highlight_sources/rage.py+++ b/products/web_analytics/backend/today_highlights.py@@ -1,6 +1,9 @@import hashlibfrom products.error_tracking.backend.facade.api import get_issue_basics+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings+from products.today.backend.facade.enums import HighlightLabel+from products.today.backend.facade.highlight_helpers import human, short, users, uses_productfrom products.web_analytics.backend.facade.rage_pages import (ErrorsBeforeRage,RagePage,@@ -9,10 +12,6 @@ from products.web_analytics.backend.facade.rage_pages import (find_top_rage_page,)-from ...facade.enums import HighlightLabel-from ..highlight_rules import human, short, users, uses_product-from ..highlight_types import Candidate, Context, Found, Source-RAGE_PAGE = "{people} rage-clicked on {page} in the last 7 days"RAGE_PAGE_DETAIL = "{clicks} rage clicks · Top element: ‘{element}’"RAGE_PAGE_NO_ELEMENT_DETAIL = "{clicks} rage clicks"@@ -24,12 +23,36 @@ MIN_ERROR_SHARE = 0.3NO_ERRORS = ErrorsBeforeRage(sessions=0, issue_id=None, issue_sessions=0)-def find(context: Context) -> Found:+def _error_item(+ context: HighlightContext, page: RagePage, errors: ErrorsBeforeRage, title: str+) -> HighlightCandidate | None:+ issue_id = errors.issue_id+ share = errors.issue_sessions / errors.sessions if errors.sessions else 0+ if issue_id is None or errors.issue_sessions < MIN_ERROR_SESSIONS or share < MIN_ERROR_SHARE:+ return None+ issue = context.guard("rage_issue", lambda: get_issue_basics(context.team.id, issue_id), None)+ if issue is None:+ return None+ name = f"{issue.name or 'Issue'}: {issue.description}" if issue.description else issue.name or "Issue"+ return HighlightCandidate(+ key=f"rage:{page.path}",+ label=HighlightLabel.RISK,+ family="replay",+ importance=0.6,+ relevance=1.0,+ title=title,+ detail=RAGE_PAGE_ERROR_DETAIL.format(pct=f"{share * 100:.0f}", issue=short(name, 50)),+ url=f"/error_tracking/{issue_id}",+ ref=issue_id,+ )+++def find_rage_page(context: HighlightContext) -> HighlightFindings:if not uses_product(context, *RAGE_PRODUCTS):- return Found()+ return HighlightFindings()page = context.daily("rage_page", lambda: find_top_rage_page(context.team, context.user))if page is None:- return Found()+ return HighlightFindings()path_key = hashlib.sha256(page.path.encode()).hexdigest()[:16]title = RAGE_PAGE.format(people=users(page.people), page=(page.path or "/")[:40])if context.allows("error_tracking:read"):@@ -42,7 +65,7 @@ def find(context: Context) -> Found:)error = _error_item(context, page, errors, title)if error is not None:- return Found(items=(error,))+ return HighlightFindings(items=(error,))top_element = context.guard("rage_element",lambda: context.daily(@@ -52,9 +75,9 @@ def find(context: Context) -> Found:)element = short(top_element or "", 30)clicks = human(page.clicks)- return Found(+ return HighlightFindings(items=(- Candidate(+ HighlightCandidate(key=f"rage:{page.path}",label=HighlightLabel.RISK,family="replay",@@ -68,28 +91,3 @@ def find(context: Context) -> Found:),))---def _error_item(context: Context, page: RagePage, errors: ErrorsBeforeRage, title: str) -> Candidate | None:- issue_id = errors.issue_id- share = errors.issue_sessions / errors.sessions if errors.sessions else 0- if issue_id is None or errors.issue_sessions < MIN_ERROR_SESSIONS or share < MIN_ERROR_SHARE:- return None- issue = context.guard("rage_issue", lambda: get_issue_basics(context.team.id, issue_id), None)- if issue is None:- return None- name = f"{issue.name or 'Issue'}: {issue.description}" if issue.description else issue.name or "Issue"- return Candidate(- key=f"rage:{page.path}",- label=HighlightLabel.RISK,- family="replay",- importance=0.6,- relevance=1.0,- title=title,- detail=RAGE_PAGE_ERROR_DETAIL.format(pct=f"{share * 100:.0f}", issue=short(name, 50)),- url=f"/error_tracking/{issue_id}",- ref=issue_id,- )---SOURCE = Source(name="rage", find=find)diff --git a/products/workflows/backend/facade/today_highlights.py b/products/workflows/backend/facade/today_highlights.pynew file mode 100644index 000000000000..4f59ed3fcdfb--- /dev/null+++ b/products/workflows/backend/facade/today_highlights.py@@ -0,0 +1,11 @@+"""Workflows' sources for the "For you today" list. Today finds this module by name."""++from products.today.backend.facade.contracts import HighlightSource++from ..today_highlights.health import find_workflow_health+from ..today_highlights.ideas import find_workflow_ideas++HIGHLIGHT_SOURCES = (+ HighlightSource(name="workflows", find=find_workflow_health, scopes=("hog_flow:read",)),+ HighlightSource(name="workflow_ideas", find=find_workflow_ideas, scopes=("hog_flow:read",)),+)diff --git a/products/today/backend/tests/test_highlight_workflows.py b/products/workflows/backend/tests/test_workflow_today_highlights.pysimilarity index 82%rename from products/today/backend/tests/test_highlight_workflows.pyrename to products/workflows/backend/tests/test_workflow_today_highlights.pyindex ab7812e5ffa7..04701126e0ce 100644--- a/products/today/backend/tests/test_highlight_workflows.py+++ b/products/workflows/backend/tests/test_workflow_today_highlights.py@@ -9,14 +9,14 @@ from django.test import SimpleTestCasefrom parameterized import parameterized+from products.today.backend.facade.contracts import HighlightContextfrom products.today.backend.facade.enums import HighlightLabel-from products.today.backend.logic.highlight_registry import load_sources-from products.today.backend.logic.highlight_sources import workflow_ideas, workflows-from products.today.backend.logic.highlight_types import Contextfrom products.workflows.backend.facade.contracts import EmailSendingState, OwnedWorkflowHealth+from products.workflows.backend.facade.today_highlights import HIGHLIGHT_SOURCES+from products.workflows.backend.today_highlights import health, ideasWORKFLOW_ID = uuid.UUID("00000000-0000-4000-8000-000000000001")-CONTEXT = cast(Context, SimpleNamespace(team=SimpleNamespace(id=1), user=None))+CONTEXT = cast(HighlightContext, SimpleNamespace(team=SimpleNamespace(id=1), user=None))def _workflow(**fields: Any) -> OwnedWorkflowHealth:@@ -92,11 +92,11 @@ class TestWorkflows(SimpleTestCase):def test_a_workflow_shows_what_needs_its_owner(self, _name: str, workflow: OwnedWorkflowHealth, expected: list[tuple[HighlightLabel, str, str, str]]) -> None:- registered = next(s for s in load_sources() if s.name == "workflows")+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "workflows")with (- patch.object(workflows, "list_owned_workflow_health", return_value=[workflow]),- patch.object(workflows, "get_email_sending_state", return_value=None),+ patch.object(health, "list_owned_workflow_health", return_value=[workflow]),+ patch.object(health, "get_email_sending_state", return_value=None),):found = registered.find(CONTEXT)@@ -112,7 +112,7 @@ class TestWorkflows(SimpleTestCase):def test_a_suspended_project_shows_to_workflow_owners(self, _name: str, owned: list[OwnedWorkflowHealth], suspended: bool, expected: list[str]) -> None:- registered = next(s for s in load_sources() if s.name == "workflows")+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "workflows")state = EmailSendingState(suspended_at=datetime(2026, 10, 1, tzinfo=UTC) if suspended else None,suspension_reason="",@@ -122,8 +122,8 @@ class TestWorkflows(SimpleTestCase):)with (- patch.object(workflows, "list_owned_workflow_health", return_value=owned),- patch.object(workflows, "get_email_sending_state", return_value=state),+ patch.object(health, "list_owned_workflow_health", return_value=owned),+ patch.object(health, "get_email_sending_state", return_value=state),):found = registered.find(CONTEXT)@@ -137,9 +137,9 @@ class TestWorkflows(SimpleTestCase):])def test_waiting_workflow_ideas_show_once(self, _name: str, count: int, expected: list[str]) -> None:- registered = next(s for s in load_sources() if s.name == "workflow_ideas")+ registered = next(s for s in HIGHLIGHT_SOURCES if s.name == "workflow_ideas")- with patch.object(workflow_ideas, "count_waiting_data_suggestions", return_value=count):+ with patch.object(ideas, "count_waiting_data_suggestions", return_value=count):found = registered.find(CONTEXT)self.assertEqual([(c.title, c.url) for c in found.items], [(title, "/workflows") for title in expected])diff --git a/products/workflows/backend/today_highlights/__init__.py b/products/workflows/backend/today_highlights/__init__.pynew file mode 100644index 000000000000..e69de29bb2d1diff --git a/products/today/backend/logic/highlight_sources/workflows.py b/products/workflows/backend/today_highlights/health.pysimilarity index 85%rename from products/today/backend/logic/highlight_sources/workflows.pyrename to products/workflows/backend/today_highlights/health.pyindex d0140076601d..11b156d869c7 100644--- a/products/today/backend/logic/highlight_sources/workflows.py+++ b/products/workflows/backend/today_highlights/health.py@@ -1,10 +1,9 @@+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings+from products.today.backend.facade.enums import HighlightLabel+from products.today.backend.facade.highlight_helpers import exact, shortfrom products.workflows.backend.facade.api import get_email_sending_state, list_owned_workflow_healthfrom products.workflows.backend.facade.contracts import OwnedWorkflowHealth-from ...facade.enums import HighlightLabel-from ..highlight_rules import exact, short-from ..highlight_types import Candidate, Context, Found, Source-SENDING_SUSPENDED = "Email sending is suspended for this project"SENDING_SUSPENDED_DETAIL = "Workflow and broadcast emails are not delivered. Contact support to turn sending back on"EMAILS_PAUSED = "Emails are paused for workflow ‘{workflow}’"@@ -19,20 +18,9 @@ MIN_FAILED = 10MIN_FAILED_SHARE = 0.1-def find(context: Context) -> Found:- workflows = list_owned_workflow_health(team=context.team, user=context.user, limit=20)- if not workflows:- return Found()- candidates = [candidate for workflow in workflows for candidate in _candidates(workflow)]- state = get_email_sending_state(context.team.id)- if state is not None and state.suspended_at is not None:- candidates.insert(0, _sending_suspended())- return Found(items=tuple(candidates))---def _sending_suspended() -> Candidate:+def _sending_suspended() -> HighlightCandidate:# Suspension stops every email step in the project, so it outranks any one workflow's problem.- return Candidate(+ return HighlightCandidate(key="workflows:email-sending-suspended",label=HighlightLabel.RISK,family="workflows",@@ -44,7 +32,7 @@ def _sending_suspended() -> Candidate:)-def _candidates(workflow: OwnedWorkflowHealth) -> list[Candidate]:+def _candidates(workflow: OwnedWorkflowHealth) -> list[HighlightCandidate]:name = short(workflow.name)candidates = []if workflow.email_sending_paused:@@ -100,8 +88,8 @@ def _candidate(title: str,detail: str,tab: str,-) -> Candidate:- return Candidate(+) -> HighlightCandidate:+ return HighlightCandidate(key=f"workflow:{workflow.workflow_id}:{kind}",label=label,family="workflows",@@ -113,4 +101,12 @@ def _candidate()-SOURCE = Source(name="workflows", find=find, scopes=("hog_flow:read",))+def find_workflow_health(context: HighlightContext) -> HighlightFindings:+ workflows = list_owned_workflow_health(team=context.team, user=context.user, limit=20)+ if not workflows:+ return HighlightFindings()+ candidates = [candidate for workflow in workflows for candidate in _candidates(workflow)]+ state = get_email_sending_state(context.team.id)+ if state is not None and state.suspended_at is not None:+ candidates.insert(0, _sending_suspended())+ return HighlightFindings(items=tuple(candidates))diff --git a/products/today/backend/logic/highlight_sources/workflow_ideas.py b/products/workflows/backend/today_highlights/ideas.pysimilarity index 64%rename from products/today/backend/logic/highlight_sources/workflow_ideas.pyrename to products/workflows/backend/today_highlights/ideas.pyindex d18c35604110..d80a6b02c89e 100644--- a/products/today/backend/logic/highlight_sources/workflow_ideas.py+++ b/products/workflows/backend/today_highlights/ideas.py@@ -1,21 +1,20 @@+from products.today.backend.facade.contracts import HighlightCandidate, HighlightContext, HighlightFindings+from products.today.backend.facade.enums import HighlightLabel+from products.today.backend.facade.highlight_helpers import exactfrom products.workflows.backend.facade.data_suggestions import count_waiting_data_suggestions-from ...facade.enums import HighlightLabel-from ..highlight_rules import exact-from ..highlight_types import Candidate, Context, Found, Source-IDEAS = "{count} workflow ideas based on your events are ready"IDEA = "1 workflow idea based on your events is ready"IDEAS_DETAIL = "Pick one to build it as a draft workflow"-def find(context: Context) -> Found:+def find_workflow_ideas(context: HighlightContext) -> HighlightFindings:count = count_waiting_data_suggestions(team=context.team)if not count:- return Found()- return Found(+ return HighlightFindings()+ return HighlightFindings(items=(- Candidate(+ HighlightCandidate(key="workflow-ideas",label=HighlightLabel.OPPORTUNITY,family="workflows",@@ -27,6 +26,3 @@ def find(context: Context) -> Found:),))---SOURCE = Source(name="workflow_ideas", find=find, scopes=("hog_flow:read",))diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex dbc9815580c3..78a95291c5b9 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -58362,6 +58362,11 @@ export namespace Schemas {score: number;/** Name of the highlight source that found the item, for example alerts. */source: string;+ /**+ * Product that declares the source, for example feature_flags. Null for items stored before this field existed and for sources that no product declares any more.+ * @nullable+ */+ product?: string | null;}/**diff --git a/tach.toml b/tach.tomlindex c3b1464303ac..9169ea139cff 100644--- a/tach.toml+++ b/tach.toml@@ -194,6 +194,8 @@ depends_on = ["posthog","products.cdp","products.product_analytics", "products.access_control",+ # Facade-only: alerts declares its Today highlight sources against the Today facade contract.+ "products.today",]layer = "modules"@@ -283,6 +285,8 @@ depends_on = [# Facade-only: the deleted-ticket purge retracts the ticket's signal embeddings. products.signals# depends on products.conversations in turn, so keep this direction on the facade."products.signals",+ # Facade-only: conversations declares its Today highlight sources against the Today facade contract.+ "products.today",]layer = "modules"@@ -522,6 +526,8 @@ depends_on = ["products.surveys","products.tasks","products.warehouse_sources",+ # Facade-only: experiments declares its Today highlight sources against the Today facade contract.+ "products.today",]layer = "modules"@@ -541,6 +547,8 @@ depends_on = ["products.product_tours","products.surveys", "products.access_control","products.notifications",+ # Facade-only: feature flags declares its Today highlight sources against the Today facade contract.+ "products.today",]layer = "modules"@@ -1132,6 +1140,10 @@ depends_on = [# The web trends, web vitals and calendar heatmap runners subclass product analytics' trends runners."products.product_analytics","products.replay_vision",+ # Facade-only: the rage-click highlight names the error people saw before rage-clicking.+ "products.error_tracking",+ # Facade-only: web analytics declares its Today highlight sources against the Today facade contract.+ "products.today",]layer = "modules"@@ -1161,6 +1173,8 @@ depends_on = [# Facade-only: the Replay Vision step's endpoint starts a scan through# products.replay_vision.backend.facade.api."products.replay_vision",+ # Facade-only: workflows declares its Today highlight sources against the Today facade contract.+ "products.today",]layer = "modules"@@ -1584,6 +1598,8 @@ depends_on = ["products.product_analytics","products.warehouse_sources","products.data_modeling", "products.access_control",+ # Facade-only: data catalog declares its Today highlight sources against the Today facade contract.+ "products.today",]layer = "modules"@@ -1680,19 +1696,11 @@ depends_on = ["ee","posthog","products.access_control",- "products.alerts",- "products.conversations","products.customer_analytics","products.dashboards",- "products.data_catalog",- "products.error_tracking",- "products.experiments",- "products.feature_flags","products.product_analytics","products.signals","products.tasks",- "products.web_analytics",- "products.workflows",]layer = "modules"