detectkit 0.14.0__tar.gz → 0.16.0__tar.gz

{detectkit-0.14.0/detectkit.egg-info → detectkit-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.14.0
+Version: 0.16.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/__init__.py

@@ -4,7 +4,7 @@ detectk - Anomaly Detection for Time-Series Metrics
 A Python library for data analysts and engineers to monitor metrics with automatic anomaly detection.
 """
 
-__version__ = "0.14.0"
+__version__ = "0.16.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/alerting/channels/base.py

@@ -9,6 +9,8 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import Any
 
+from detectkit.alerting.channels.branding import ALERT_GUIDE_LABEL
+
 
 @dataclass
 class AlertData:
@@ -32,10 +34,14 @@ class AlertData:
         consecutive_count: Number of consecutive anomalies
         is_recovery: True for recovery notifications
         is_no_data: True for missing-data alerts (no_data_alert)
-        project_name: Optional ``detectkit_project.yml`` name. Surfaces
-            as ``{project_name}`` in templates and as a ``[name] `` prefix
-            in the default error title. Lets multiple projects share the
-            same alert channel without ambiguity.
+        project_name: Optional ``detectkit_project.yml`` name. Surfaces as
+            ``{project_name}`` / ``{project_name_prefix}`` in templates and, by
+            default, as a ``[name] `` prefix on every alert title/headline
+            (anomaly, recovery, no-data, error) plus a brand-paired footer
+            ("detectkit · name" on webhook/email). The detectkit pipeline stamps
+            it from the project config; direct-API callers leave it ``None`` and
+            render unchanged. Lets multiple projects share one alert channel —
+            keeping the default brand bot name + avatar — without ambiguity.
 
     Alert-rule fields (``min_detectors``, ``direction_policy``,
     ``consecutive_required``, ``detector_count``) describe *why the alert
@@ -75,6 +81,12 @@ class AlertData:
     # callers and templates render unchanged.
     dashboard_url: str | None = None
     links: dict[str, str] = field(default_factory=dict)
+    # "How to read this alert" link surfaced on every default-rendered message so
+    # non-operator stakeholders can click through to a plain-language guide. The
+    # orchestrator resolves it from ``ProjectConfig.alert_help_url`` (defaulting to
+    # the official docs); direct-API callers leave it ``None`` and render unchanged.
+    # Exposed to templates as ``{help_url}`` / ``{help_line}``.
+    help_url: str | None = None
     # Alert rule (the parameters the alert fired with) — see class docstring.
     min_detectors: int | None = None
     direction_policy: str | None = None
@@ -296,6 +308,11 @@ class BaseAlertChannel(ABC):
         dashboard_url = alert_data.dashboard_url or ""
         dashboard_line = f"Dashboard: {dashboard_url}\n" if dashboard_url else ""
 
+        # "How to read this alert" link (same shape as dashboard): a raw
+        # placeholder plus a ready-to-drop line, both empty when unset.
+        help_url = alert_data.help_url or ""
+        help_line = f"{ALERT_GUIDE_LABEL}: {help_url}\n" if help_url else ""
+
         # Project name + synth prefix for templates. Prefix is empty when
         # project_name is None so default templates render cleanly for
         # callers that don't set it.
@@ -340,6 +357,9 @@ class BaseAlertChannel(ABC):
             "description_line": description_line,
             "dashboard_url": dashboard_url,
             "dashboard_line": dashboard_line,
+            "help_url": help_url,
+            "help_line": help_line,
+            "help_label": ALERT_GUIDE_LABEL,
             "mentions": mentions_str,
             "mentions_line": mentions_line,
         }
@@ -450,7 +470,7 @@ class BaseAlertChannel(ABC):
             Default template string
         """
         return (
-            "🔴 Alert: {metric_name}\n"
+            "🔴 {project_name_prefix}Alert: {metric_name}\n"
             "{description_line}"
             "Quorum {detector_count}/{min_detectors} · "
             "direction {direction} (policy {direction_policy}) · "
@@ -465,6 +485,7 @@ class BaseAlertChannel(ABC):
             "Detectors: {detector_name}\n"
             "Parameters: {detector_params}\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 
@@ -476,7 +497,7 @@ class BaseAlertChannel(ABC):
             Default recovery template string
         """
         return (
-            "🟢 Alert cleared: {metric_name}\n"
+            "🟢 {project_name_prefix}Alert cleared: {metric_name}\n"
             "{description_line}"
             "The alert condition no longer holds — "
             "the metric is back within expected bounds.\n"
@@ -488,6 +509,7 @@ class BaseAlertChannel(ABC):
             "· Value: {value_display} | Expected: {expected_range}\n"
             "Detectors: {detector_name}\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 
@@ -500,7 +522,7 @@ class BaseAlertChannel(ABC):
         Returns:
             Default title template string
         """
-        return "🔴 Alert: {metric_name}"
+        return "🔴 {project_name_prefix}Alert: {metric_name}"
 
     def get_default_recovery_title_template(self) -> str:
         """
@@ -509,7 +531,7 @@ class BaseAlertChannel(ABC):
         Returns:
             Default recovery title template string
         """
-        return "🟢 Alert cleared: {metric_name}"
+        return "🟢 {project_name_prefix}Alert cleared: {metric_name}"
 
     def get_default_no_data_template(self) -> str:
         """
@@ -519,26 +541,28 @@ class BaseAlertChannel(ABC):
         has no datapoint (no row OR row with NULL/NaN value).
         """
         return (
-            "🟡 No data for metric: {metric_name}\n"
+            "🟡 {project_name_prefix}No data for metric: {metric_name}\n"
             "{description_line}"
             "Time: {timestamp}\n"
             "Status: query returned no datapoint for the latest interval\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 
     def get_default_no_data_title_template(self) -> str:
         """Get default title template for no-data alerts."""
-        return "🟡 No data: {metric_name}"
+        return "🟡 {project_name_prefix}No data: {metric_name}"
 
     def get_default_error_template(self) -> str:
         """Default body template for project-level error alerts."""
         return (
-            "🔵 Pipeline failed for metric: {metric_name}\n"
+            "🔵 {project_name_prefix}Pipeline failed for metric: {metric_name}\n"
             "{description_line}"
             "Time: {timestamp}\n"
             "Error: {error_type}: {error_message}\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/alerting/channels/branding.py

@@ -18,3 +18,13 @@ BRAND_USERNAME = "detectkit"
 # or opt out of the avatar entirely with ``icon_emoji``. The PNG is generated by
 # ``website/scripts/make-bot-icon.mjs`` and served from ``website/public/``.
 BRAND_ICON_URL = "https://dtk.pipelab.dev/bot-icon.png"
+
+# Default "how to read this alert" link surfaced on every default-rendered alert,
+# so non-operator stakeholders (PMs, analysts, on-call) seeing a notification can
+# click through to a plain-language guide explaining what they're looking at. It
+# points at the official docs page by default; a project can redirect it to its
+# own runbook (or hide it) via ``ProjectConfig.alert_help_url`` — the resolved URL
+# is stamped onto ``AlertData.help_url`` by the orchestrator. ``ALERT_GUIDE_LABEL``
+# is the shared link text so every channel reads the same.
+BRAND_ALERT_GUIDE_URL = "https://dtk.pipelab.dev/guides/reading-alerts/"
+ALERT_GUIDE_LABEL = "How to read this alert"

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/alerting/channels/email.py

@@ -12,7 +12,11 @@ from email.utils import formataddr
 from typing import Any
 
 from detectkit.alerting.channels.base import AlertData, BaseAlertChannel
-from detectkit.alerting.channels.branding import BRAND_ICON_URL, BRAND_USERNAME
+from detectkit.alerting.channels.branding import (
+    ALERT_GUIDE_LABEL,
+    BRAND_ICON_URL,
+    BRAND_USERNAME,
+)
 
 # Brand palette as hex literals. Email clients (Outlook/Word engine) ignore CSS
 # custom properties, so the values from website/src/styles/brand.css are copied
@@ -74,7 +78,7 @@ class EmailChannel(BaseAlertChannel):
         smtp_username: str | None = None,
         smtp_password: str | None = None,
         use_tls: bool = True,
-        subject_template: str = "🔴 Alert: {metric_name}",
+        subject_template: str = "🔴 {project_name_prefix}Alert: {metric_name}",
         from_name: str = BRAND_USERNAME,
         template: str | None = None,
         **kwargs,
@@ -144,10 +148,18 @@ class EmailChannel(BaseAlertChannel):
         # of a bot display name. formataddr quotes the name when required.
         msg["From"] = formataddr((self.from_name, self.from_email))
         msg["To"] = ", ".join(self.to_emails)
-        # Strip CR/LF from the metric name before it reaches the Subject header
-        # so a metric name can never inject extra email headers.
+        # Strip CR/LF from the metric *and* project name before they reach the
+        # Subject header so neither can inject extra email headers. The project
+        # prefix ("[my_project] ") makes the inbox row distinguishable when
+        # several projects email the same address.
         subject_metric = alert_data.metric_name.replace("\r", " ").replace("\n", " ")
-        msg["Subject"] = self.subject_template.format(metric_name=subject_metric)
+        project_clean = (alert_data.project_name or "").replace("\r", " ").replace("\n", " ")
+        project_prefix = f"[{project_clean}] " if project_clean else ""
+        msg["Subject"] = self.subject_template.format(
+            metric_name=subject_metric,
+            project_name_prefix=project_prefix,
+            project_name=project_clean,
+        )
 
         # Attach both parts. In multipart/alternative the LAST part is the
         # preferred one, so HTML (the branded card) is shown when supported and
@@ -247,6 +259,8 @@ class EmailChannel(BaseAlertChannel):
             f'font-size:4px;background-color:{accent};">&nbsp;</td></tr>'
             # header: logo + wordmark + status pill
             f"{self._header_html(accent, pill)}"
+            # project eyebrow (small label above the metric, only when set)
+            f"{self._eyebrow_html(ctx['project_name'])}"
             # title
             f'<tr><td style="padding:6px 24px 2px 24px;font-family:{_SANS};font-size:22px;'
             f'font-weight:bold;color:{_INK};mso-line-height-rule:exactly;line-height:28px;">'
@@ -258,6 +272,17 @@ class EmailChannel(BaseAlertChannel):
             "</table></td></tr></table></body></html>"
         )
 
+    def _eyebrow_html(self, project_name: str) -> str:
+        """Small uppercase project label above the metric title (empty if unset)."""
+        if not project_name:
+            return ""
+        return (
+            f'<tr><td style="padding:10px 24px 0 24px;font-family:{_SANS};font-size:11px;'
+            f"font-weight:bold;letter-spacing:0.5px;color:{_FAINT};text-transform:uppercase;"
+            f'mso-line-height-rule:exactly;line-height:14px;">'
+            f"{html.escape(project_name)}</td></tr>"
+        )
+
     def _header_html(self, accent: str, pill: str) -> str:
         """Logo + wordmark (real text) + colored status pill row."""
         return (
@@ -432,11 +457,25 @@ class EmailChannel(BaseAlertChannel):
     def _footer_html(self, alert_data: AlertData) -> str:
         cc = self.format_mentions(alert_data.mentions)
         cc_html = f" &middot; {html.escape(cc)}" if cc else ""
+        # Pair the brand with the project name ("Sent by detectkit · my_project")
+        # so the source project is clear even past the subject/eyebrow.
+        project_html = (
+            f" &middot; {html.escape(alert_data.project_name)}" if alert_data.project_name else ""
+        )
+        # "How to read this alert" — a clay footer link to the interpretation
+        # guide (empty when opted out via alert_help_url: false).
+        help_html = ""
+        if alert_data.help_url:
+            href = html.escape(alert_data.help_url, quote=True)
+            help_html = (
+                f' &middot; <a href="{href}" style="color:{_CLAY};text-decoration:none;">'
+                f"{html.escape(ALERT_GUIDE_LABEL)} &rarr;</a>"
+            )
         return (
             f'<tr><td bgcolor="{_SURFACE}" style="background-color:{_SURFACE};'
             f"border-top:1px solid {_BORDER};padding:14px 24px;font-family:{_SANS};"
             f'font-size:12px;color:{_FAINT};mso-line-height-rule:exactly;line-height:16px;">'
-            f"Sent by detectkit{cc_html}</td></tr>"
+            f"Sent by detectkit{project_html}{cc_html}{help_html}</td></tr>"
         )
 
     def format_mentions(self, mentions: list[str]) -> str:

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/alerting/channels/telegram.py

@@ -148,7 +148,12 @@ class TelegramChannel(BaseAlertChannel):
             return html.escape(str(value))
 
         metric = esc(ctx["metric_name"])
-        lines: list[str] = [f"{dot} <b>{word} · {metric}</b>"]
+        # Lead the headline with the project name (when set) so multiple
+        # projects sharing one chat stay distinguishable — Telegram has no
+        # footer/avatar override, so this prefix is the only project cue.
+        proj = ctx["project_name"]
+        head_prefix = f"[{esc(proj)}] " if proj else ""
+        lines: list[str] = [f"{dot} <b>{head_prefix}{word} · {metric}</b>"]
 
         if ctx["description"]:
             lines.append(f"<i>{esc(self._cap(ctx['description'], _DESC_CAP))}</i>")
@@ -214,6 +219,11 @@ class TelegramChannel(BaseAlertChannel):
         for label, url in alert_data.links.items():
             href = html.escape(url, quote=True)
             link_parts.append(f'<a href="{href}">{esc(label)}</a>')
+        # "How to read this alert" — always present (unless opted out), so a
+        # stakeholder can click through to the interpretation guide.
+        if ctx["help_url"]:
+            href = html.escape(ctx["help_url"], quote=True)
+            link_parts.append(f'<a href="{href}">{esc(ctx["help_label"])}</a>')
         if link_parts:
             lines.append("")
             lines.append(" · ".join(link_parts))

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/alerting/channels/webhook.py

@@ -189,8 +189,13 @@ class WebhookChannel(BaseAlertChannel):
             attachment["title_link"] = alert_data.dashboard_url
 
         # Brand the attachment footer (reliable on Slack even when top-level
-        # username/icon are locked to the app install).
-        attachment["footer"] = self.username or BRAND_USERNAME
+        # username/icon are locked to the app install). Pair the brand name with
+        # the project name when set ("detectkit · my_project") so two projects
+        # posting to the same channel stay distinguishable even past the title.
+        footer = self.username or BRAND_USERNAME
+        if alert_data.project_name:
+            footer = f"{footer} · {alert_data.project_name}"
+        attachment["footer"] = footer
         if self.icon_url:
             attachment["footer_icon"] = self.icon_url
         # Slack-only sugar: a real timestamp under the footer. Mattermost
@@ -298,6 +303,11 @@ class WebhookChannel(BaseAlertChannel):
         if link_lines:
             full("Links", "\n".join(link_lines))
 
+        # "How to read this alert" — the last field, a bare URL (auto-linkified on
+        # both Slack and Mattermost) pointing readers at the interpretation guide.
+        if ctx["help_url"]:
+            full(ctx["help_label"], ctx["help_url"])
+
         # A plain-text one-liner for notification previews / unsupported clients.
         if kind == "no_data":
             fallback = f"{title} at {ctx['timestamp']}"
@@ -352,6 +362,7 @@ class WebhookChannel(BaseAlertChannel):
             "Detectors: {detector_name}\n"
             "Parameters: {detector_params}\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 
@@ -371,6 +382,7 @@ class WebhookChannel(BaseAlertChannel):
             "· Value: {value_display} | Expected: {expected_range}\n"
             "Detectors: {detector_name}\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 
@@ -381,6 +393,7 @@ class WebhookChannel(BaseAlertChannel):
             "Time: {timestamp}\n"
             "Status: query returned no datapoint for the latest interval\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 
@@ -391,6 +404,7 @@ class WebhookChannel(BaseAlertChannel):
             "Time: {timestamp}\n"
             "Error: {error_type}: {error_message}\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/alerting/orchestrator/_base.py

@@ -25,6 +25,8 @@ class _OrchestratorBase:
         mentions: list[str] | None = None,
         dashboard_url: str | None = None,
         links: dict[str, str] | None = None,
+        project_name: str | None = None,
+        help_url: str | None = None,
     ):
         self.metric_name = metric_name
         self.interval = interval
@@ -37,6 +39,15 @@ class _OrchestratorBase:
         self.mentions = mentions or []
         self.dashboard_url = dashboard_url
         self.links = links or {}
+        # Optional project name (``detectkit_project.yml`` ``name``). Stamped
+        # onto every AlertData so channels can label which project an alert
+        # came from — keeps multiple projects sharing one channel distinct
+        # while the bot keeps the default brand name + avatar.
+        self.project_name = project_name
+        # Resolved "how to read this alert" link (from ProjectConfig.alert_help_url,
+        # defaulting to the official docs; None when opted out). Stamped onto every
+        # AlertData so channels render a guide link for non-operator stakeholders.
+        self.help_url = help_url
 
     @staticmethod
     def _group_by_timestamp(

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/alerting/orchestrator/_decision.py

@@ -241,6 +241,8 @@ class _DecisionMixin(_OrchestratorBase):
             mentions=self.mentions,
             dashboard_url=self.dashboard_url,
             links=self.links,
+            project_name=self.project_name,
+            help_url=self.help_url,
             # Alert rule the message foregrounds: configured thresholds plus
             # the observed quorum size that satisfied them.
             min_detectors=self.conditions.min_detectors,
@@ -300,6 +302,8 @@ class _DecisionMixin(_OrchestratorBase):
             mentions=self.mentions,
             dashboard_url=self.dashboard_url,
             links=self.links,
+            project_name=self.project_name,
+            help_url=self.help_url,
         )
 
     def get_last_complete_point(self, now: datetime | None = None) -> datetime:

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/alerting/orchestrator/_recovery.py

@@ -178,6 +178,8 @@ class _RecoveryMixin(_OrchestratorBase):
             mentions=self.mentions,
             dashboard_url=self.dashboard_url,
             links=self.links,
+            project_name=self.project_name,
+            help_url=self.help_url,
             # Echo the rule that had fired so the recovery message names the
             # same alert condition that just cleared.
             min_detectors=self.conditions.min_detectors,

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/cli/assets/claude/rules/alerting.md

@@ -151,6 +151,34 @@ gets an inline "Open dashboard" link, and email gets an "Open dashboard" button.
 `links` adds extra `label: url` entries alongside it. Both are also exposed to
 custom templates — see `{dashboard_url}` / `{dashboard_line}` below.
 
+## "How to read this alert" link
+
+Every **default-rendered** alert (anomaly / recovery / no-data / error) on
+**every** channel carries a `How to read this alert` link pointing non-operator
+stakeholders to a plain-language interpretation guide. It defaults to the
+official detectkit guide (`https://dtk.pipelab.dev/guides/reading-alerts/`) — no
+config needed. Control it project-wide with `alert_help_url` in
+`detectkit_project.yml` (tri-state, see `project.md`):
+
+- **unset / null** → the official detectkit guide (default URL above)
+- **a URL string** → your own runbook/wiki page instead
+- **`false`** → hide the link entirely
+
+Per-channel rendering (defaults only; resolved by
+`ProjectConfig.resolve_alert_help_url`):
+
+- **Slack / Mattermost / generic webhook** — a bottom full-width attachment field
+  titled `How to read this alert` whose value is the bare URL (auto-linkified on
+  both platforms).
+- **Telegram** — appended to the links line (after the optional "Open dashboard"
+  link) as an `<a>` link reading `How to read this alert`.
+- **Email** — in the footer, after `Sent by detectkit · <project>` (and any CC),
+  a clay-colored `How to read this alert ->` link.
+
+Exposed to custom templates as `{help_url}` (raw URL, empty when unset/hidden)
+and `{help_line}` (`How to read this alert: <url>\n`, empty when unset/hidden) —
+mirrors `{dashboard_url}` / `{dashboard_line}`. See the template table below.
+
 ## How default messages render
 
 With no custom `template`, each channel renders a structured, branded message
@@ -158,7 +186,9 @@ With no custom `template`, each channel renders a structured, branded message
 shared value computation lives in one place (`BaseAlertChannel.build_context`),
 so templates and native rendering stay consistent. Every alert title/headline
 leads with a colored **status circle** — 🔴 anomaly, 🟢 recovery, 🟡 no-data,
-🔵 pipeline error — so the status reads from color alone.
+🔵 pipeline error — so the status reads from color alone. It also leads with the
+**project name** as a `[name] ` prefix (from `detectkit_project.yml`) — see
+[Project label](#project-label-multi-project-channels) below.
 
 - **Slack / Mattermost / generic webhook** — one message *attachment* with a
   status-colored accent bar, a clickable title (the metric; links to
@@ -181,6 +211,25 @@ leads with a colored **status circle** — 🔴 anomaly, 🟢 recovery, 🟡 no-
   table, a monospace params box, an optional "Open dashboard" button, and a
   footer. The plain-text body remains the multipart fallback.
 
+## Project label (multi-project channels)
+
+The bot keeps the **detectkit brand** name + avatar by default (so users rarely
+override them). To still tell apart two projects posting to the **same** channel,
+detectkit stamps the project name (`detectkit_project.yml` → `name`) onto every
+alert and shows it by default — no config needed:
+
+- **Title / headline / subject** lead with a `[name] ` prefix on every kind
+  (anomaly, recovery, no-data, error): `🔴 [payments] Alert: api_error_rate`.
+- **Webhook (Slack/Mattermost)** also pairs it in the footer: `detectkit · payments`.
+- **Telegram** carries it in the bold headline (no footer/avatar to override).
+- **Email** prefixes the subject, shows a small project eyebrow above the metric,
+  and pairs it in the footer (`Sent by detectkit · payments`).
+
+It is exposed to custom templates as `{project_name}` and `{project_name_prefix}`
+(`"[name] "` when set, else `""`). Direct library/API callers that don't set it
+render unchanged. The `name` is informational only (it does not key any `_dtk_*`
+table), so renaming it is safe — spaces are allowed for a prettier label.
+
 ## Multiple alert configs per metric
 
 `alerting:` may be a **list** of independent blocks, each with its own channels,
@@ -210,6 +259,7 @@ referenced by path). Key variables:
 | Variable | Meaning |
 |---|---|
 | `{metric_name}`, `{description}` / `{description_line}` | identity |
+| `{project_name}` / `{project_name_prefix}` | project label (`"[name] "` prefix, or `""`) |
 | `{timestamp}`, `{timezone}` | when (display tz via `alerting.timezone`, default UTC) |
 | `{value}` / `{value_display}` | metric value (`value_display` is NaN-safe) |
 | `{confidence_lower}` / `{confidence_upper}` / `{confidence_interval}` | bounds |
@@ -221,6 +271,8 @@ referenced by path). Key variables:
 | `{mentions}` / `{mentions_line}` | formatted mentions |
 | `{dashboard_url}` | raw `dashboard_url` (empty string when unset) |
 | `{dashboard_line}` | `Dashboard: <url>\n` when set, else empty (appended to default plain-text templates) |
+| `{help_url}` | raw "How to read this alert" URL (empty when unset/hidden via `alert_help_url`) |
+| `{help_line}` | `How to read this alert: <url>\n` when set, else empty (mirrors `{dashboard_line}`) |
 
 > For no-data/error alerts there is no numeric value — avoid `{value:.2f}` in
 > those templates (detectkit falls back to the default template rather than

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/cli/assets/claude/rules/project.md

@@ -9,7 +9,9 @@ errors (not empty strings).
 ## `detectkit_project.yml`
 
 ```yaml
-name: my_monitoring            # required — project identifier (logs, error-alert titles)
+name: my_monitoring            # required — project identifier; also labels every
+                               # alert ("[my_monitoring] Alert: …") so multiple
+                               # projects on one channel stay distinct (alerting.md)
 version: "1.0"                 # optional (default "1.0")
 default_profile: prod          # profile name from profiles.yml
 
@@ -28,10 +30,31 @@ timeouts:                      # per-step, seconds
   detect: 7200                 # detect step (default 7200)
   alert: 300                   # alert step (default 300)
 
+alert_help_url: null           # optional, see below — "How to read this alert" link
+
 error_alerting:                # optional, see below
   enabled: false
 ```
 
+### `alert_help_url` — "How to read this alert" link
+
+Every default-rendered alert on every channel carries a `How to read this alert`
+link for non-operator stakeholders. Tri-state, resolved by
+`ProjectConfig.resolve_alert_help_url`:
+
+- **unset / null** (default) → the official detectkit guide
+  (`https://dtk.pipelab.dev/guides/reading-alerts/`).
+- **a URL string** → your own runbook/wiki page instead.
+- **`false`** → hide the link entirely.
+
+```yaml
+alert_help_url: https://wiki.ops/how-to-read-alerts   # custom page
+# alert_help_url: false                               # hide the link
+```
+
+Per-channel rendering and the `{help_url}` / `{help_line}` template variables are
+covered in `alerting.md` → "How to read this alert" link.
+
 ### `error_alerting` — project-scoped failure alerts
 
 Catches any exception from a metric's pipeline (DB down, query timeout, lock
@@ -57,8 +80,10 @@ error_alerting:
   via cron cadence). Channel send failures are swallowed so a flaky webhook
   can't crash the run.
 - Extra template variables: `{error_type}`, `{error_message}`, `{status}`
-  (always `"ERROR"`), `{project_name}`, `{project_name_prefix}` (=
-  `"[<name>] "` when `name` set — keeps multi-project channels distinguishable).
+  (always `"ERROR"`). `{project_name}` / `{project_name_prefix}` (=
+  `"[<name>] "` when `name` set) are available here **and in every other alert
+  template** — and by default lead the title/headline on all channels, keeping
+  multi-project channels distinguishable (see `alerting.md` → Project label).
 
 ## `profiles.yml`
 

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/cli/commands/test_alert.py

@@ -22,6 +22,7 @@ def create_mock_alert_data(
     metric_config: MetricConfig,
     alerting_config,
     timezone_display: str = "UTC",
+    help_url: str | None = None,
 ) -> AlertData:
     """
     Create realistic mock AlertData for testing.
@@ -33,6 +34,8 @@ def create_mock_alert_data(
             ``metric_config.alerting`` is a list — the test command
             iterates it and passes one entry at a time.
         timezone_display: Timezone for display
+        help_url: Resolved "how to read this alert" link to preview (the
+            project's ``alert_help_url``); ``None`` renders no help link.
 
     Returns:
         AlertData with mock anomaly data
@@ -89,6 +92,7 @@ def create_mock_alert_data(
         mentions=mentions,
         dashboard_url=getattr(alerting_config, "dashboard_url", None),
         links=dict(getattr(alerting_config, "links", {}) or {}),
+        help_url=help_url,
         min_detectors=min_detectors,
         direction_policy=direction_policy,
         consecutive_required=consecutive_required,
@@ -121,6 +125,12 @@ def run_test_alert(metric_name: str, profile: str | None = None):
 
     metrics_dir_name = project_data.get("metrics_path", "metrics")
 
+    # Resolve the "how to read this alert" link so the preview matches what real
+    # alerts would carry (brand default, a custom URL, or hidden via false).
+    from detectkit.config.project_config import resolve_alert_help_url
+
+    help_url = resolve_alert_help_url(project_data.get("alert_help_url"))
+
     # Find metric config
     metrics_dir = project_root / metrics_dir_name
     metric_files = list(metrics_dir.glob("**/*.yml")) + list(metrics_dir.glob("**/*.yaml"))
@@ -176,7 +186,9 @@ def run_test_alert(metric_name: str, profile: str | None = None):
         print(f"   Timezone: {timezone_display}")
         print(f"   Channels: {', '.join(alerting_config.channels)}\n")
 
-        alert_data = create_mock_alert_data(metric_config, alerting_config, timezone_display)
+        alert_data = create_mock_alert_data(
+            metric_config, alerting_config, timezone_display, help_url=help_url
+        )
 
         success_count = 0
         for channel_name in alerting_config.channels:

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/config/project_config.py

@@ -9,6 +9,26 @@ from pathlib import Path
 from pydantic import BaseModel, Field, field_validator
 
 
+def resolve_alert_help_url(value: "str | bool | None") -> "str | None":
+    """Resolve a raw ``alert_help_url`` config value to a concrete URL or None.
+
+    Shared by :meth:`ProjectConfig.resolve_alert_help_url` and the ``dtk
+    test-alert`` preview (which reads the project YAML as a raw dict), so the
+    tri-state rule lives in one place:
+
+    - ``False`` → ``None`` (the link is hidden).
+    - a non-empty string → that URL (a custom runbook/wiki page).
+    - ``None`` / ``True`` / empty → the official detectkit guide.
+    """
+    from detectkit.alerting.channels.branding import BRAND_ALERT_GUIDE_URL
+
+    if value is False:
+        return None
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return BRAND_ALERT_GUIDE_URL
+
+
 class ProjectPathsConfig(BaseModel):
     """
     Project directory paths configuration.
@@ -161,6 +181,44 @@ class ProjectConfig(BaseModel):
         default=None,
         description="Project-level error alerting (DB outages, query failures, etc.)",
     )
+    # "How to read this alert" link surfaced on every default-rendered alert so
+    # stakeholders (PMs, analysts, on-call) can click through to a plain-language
+    # explanation of what they're seeing. Tri-state:
+    #   - unset / None  → the official detectkit guide (brand default)
+    #   - a URL string  → your own runbook/wiki page instead
+    #   - false         → hide the link entirely
+    # Resolved via ``resolve_alert_help_url()`` and stamped onto ``AlertData``.
+    alert_help_url: str | bool | None = Field(
+        default=None,
+        description=(
+            "Link to a guide explaining how to read an alert, shown on every "
+            "alert. Defaults to the official docs; set a URL for your own page, "
+            "or false to hide it."
+        ),
+    )
+
+    @field_validator("alert_help_url")
+    @classmethod
+    def validate_alert_help_url(cls, v: "str | bool | None") -> "str | bool | None":
+        """A string override must look like an http(s) URL; ``True`` means default."""
+        if isinstance(v, str):
+            v = v.strip()
+            if not v:
+                return None  # empty string behaves like "use the default"
+            if not (v.startswith("http://") or v.startswith("https://")):
+                raise ValueError(
+                    "alert_help_url must be an http(s) URL, false (to hide), "
+                    "or unset (to use the default)"
+                )
+        return v
+
+    def resolve_alert_help_url(self) -> str | None:
+        """Resolve the configured ``alert_help_url`` to a concrete URL or None.
+
+        Defaults to the official detectkit guide; a string redirects to your own
+        page; ``false`` hides the link. See :func:`resolve_alert_help_url`.
+        """
+        return resolve_alert_help_url(self.alert_help_url)
 
     @field_validator("name")
     @classmethod

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/orchestration/error_dispatch.py

@@ -74,6 +74,11 @@ def dispatch_project_error_alert(
             )
             return False
 
+        # Resolve the project-level "how to read this alert" link (brand default
+        # unless overridden / disabled); duck-typed for stub configs in tests.
+        help_resolver = getattr(project_config, "resolve_alert_help_url", None)
+        help_url = help_resolver() if callable(help_resolver) else None
+
         alert_data = AlertData(
             metric_name=metric_name,
             timestamp=np.datetime64(now_utc_naive(), "ms"),
@@ -93,6 +98,7 @@ def dispatch_project_error_alert(
             description=None,
             mentions=cfg.mentions,
             project_name=getattr(project_config, "name", None),
+            help_url=help_url,
         )
 
         click.echo(

{detectkit-0.14.0 → detectkit-0.16.0}/detectkit/orchestration/task_manager/_alert_step.py

@@ -48,6 +48,12 @@ class _AlertStepMixin(_TaskManagerBase):
             click.echo("  │ Checking alert conditions...")
             alert_config_id = make_alert_config_id(alerting_config)
 
+            # Resolve the project-level "how to read this alert" link once per
+            # alert config (brand default unless overridden / disabled). Duck-typed
+            # so a stub project_config in tests without the resolver stays safe.
+            help_resolver = getattr(self.project_config, "resolve_alert_help_url", None)
+            help_url = help_resolver() if callable(help_resolver) else None
+
             orchestrator = AlertOrchestrator(
                 metric_name=config.name,
                 interval=interval,
@@ -64,6 +70,8 @@ class _AlertStepMixin(_TaskManagerBase):
                 mentions=alerting_config.mentions,
                 dashboard_url=alerting_config.dashboard_url,
                 links=alerting_config.links,
+                project_name=getattr(self.project_config, "name", None),
+                help_url=help_url,
             )
 
             last_point = orchestrator.get_last_complete_point()

{detectkit-0.14.0 → detectkit-0.16.0/detectkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.14.0
+Version: 0.16.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT