detectkit 0.40.0__tar.gz → 0.42.0__tar.gz

{detectkit-0.40.0/detectkit.egg-info → detectkit-0.42.0}/PKG-INFO

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

{detectkit-0.40.0 → detectkit-0.42.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.40.0"
+__version__ = "0.42.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.40.0 → detectkit-0.42.0}/detectkit/alerting/channels/webhook.py

@@ -25,16 +25,22 @@ class WebhookChannel(BaseAlertChannel):
     - Slack incoming webhooks
     - Custom webhook endpoints
 
-    Rendering: the default (no custom ``template``) payload is a single
-    **Slack/Mattermost message attachment** — a colored accent bar, a title,
-    a short markdown lead (how long the anomaly has been running) with the
-    **Rule** chip beneath it, and a compact **fields grid** (Value / Expected /
-    Quorum / Severity / Started / Latest — Started / Cleared on recovery — then
-    full-width Detectors / Parameters), branded with a ``footer`` +
-    ``footer_icon``. This renders richly on both
-    Slack and Mattermost from one payload. A custom ``template`` degrades to a
-    plain text-only attachment (the template is one opaque string that can't be
-    sliced into fields), keeping the color, title and branding.
+    Rendering: the default (no custom ``template``) anomaly/recovery payload is
+    **two stacked Slack/Mattermost attachments** — a colored **base card** that
+    is always visible (the title, a short markdown lead with the **Rule** chip,
+    the Value / Expected fields and an always-visible compact **Links** field)
+    and a neutral **detail card** carrying the verbose tail (Quorum / Severity /
+    the anomalous span / Detectors / Parameters) as one markdown ``text`` block.
+    Slack and Mattermost natively collapse only an attachment's ``text`` (Slack
+    above 700 characters / 5 line breaks, Mattermost above ~200px of rendered
+    height) and **never** collapse the ``fields`` grid — so routing the bulk
+    into the detail card's ``text`` lets the platform fold it behind a
+    "Show more" toggle while the base (value, expected and links) stays in view.
+    Short kinds (no-data / error) render as a single base card. A custom
+    ``template`` degrades to a plain text-only attachment (one opaque string
+    that can't be sliced into fields), keeping the color, title and branding.
+    Branding (``footer`` + ``footer_icon``) rides on the **last** attachment so
+    it sits at the bottom of the whole message, below the folded detail card.
 
     Mentions ride in the **top-level** ``text`` (mentions inside attachments do
     not reliably notify on Slack). A ``dashboard_url`` makes the attachment
@@ -48,7 +54,12 @@ class WebhookChannel(BaseAlertChannel):
             "icon_url": "https://.../bot-icon.png",   # or "icon_emoji"
             "text": "<!here> ...",                      # mentions (top level)
             "channel": "#channel",                      # optional (Slack)
-            "attachments": [{"color": ..., "title": ..., "fields": [...], ...}]
+            "attachments": [
+                # base card — always visible (never folds; fields don't collapse)
+                {"color": ..., "title": ..., "fields": [Value, Expected, Links], ...},
+                # detail card — neutral, foldable text (anomaly/recovery only)
+                {"text": "<verbose tail>", "mrkdwn_in": ["text"]},
+            ]
         }
 
     Branding: the bot defaults to the **detectkit brand avatar** (``icon_url``)
@@ -177,39 +188,42 @@ class WebhookChannel(BaseAlertChannel):
         if template is not None:
             # Custom template → opaque text-only attachment (can't be sliced
             # into fields), but keep the color, title, branding and mrkdwn.
-            attachment: dict[str, Any] = {
-                "color": color,
-                "title": title,
-                "text": self.format_message(alert_data, template),
-                "mrkdwn_in": ["text"],
-            }
+            attachments: list[dict[str, Any]] = [
+                {
+                    "color": color,
+                    "title": title,
+                    "text": self.format_message(alert_data, template),
+                    "mrkdwn_in": ["text"],
+                }
+            ]
         else:
-            attachment = self._build_rich_attachment(alert_data, ctx, color, title)
+            attachments = self._build_rich_attachments(alert_data, ctx, color, title)
 
-        # Dashboard link → clickable attachment title (native on both platforms).
+        # Dashboard link → clickable title on the base (first) attachment.
         if alert_data.dashboard_url:
-            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). 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.
+            attachments[0]["title_link"] = alert_data.dashboard_url
+
+        # Brand the LAST attachment's footer (reliable on Slack even when
+        # top-level username/icon are locked to the app install) so the brand
+        # line sits at the bottom of the whole message — below the folded detail
+        # card when one is present. 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
+        attachments[-1]["footer"] = footer
         if self.icon_url:
-            attachment["footer_icon"] = self.icon_url
+            attachments[-1]["footer_icon"] = self.icon_url
         # Slack-only sugar: a real timestamp under the footer. Mattermost
-        # ignores it; the human-readable "Detected at" field carries the time
-        # on both.
+        # ignores it; the human-readable timestamp rides in the cards on both.
         ts_unix = self._unix_ts(alert_data.timestamp)
         if ts_unix is not None:
-            attachment["ts"] = ts_unix
+            attachments[-1]["ts"] = ts_unix
 
         payload: dict[str, Any] = {
             "username": self.username,
-            "attachments": [attachment],
+            "attachments": attachments,
         }
 
         # Mentions ride in TOP-LEVEL text — placed inside an attachment they
@@ -231,29 +245,43 @@ class WebhookChannel(BaseAlertChannel):
 
         return payload
 
-    def _build_rich_attachment(
+    def _build_rich_attachments(
         self,
         alert_data: AlertData,
         ctx: dict[str, Any],
         color: str,
         title: str,
-    ) -> dict[str, Any]:
-        """Build the default fields-based attachment for *alert_data*.
-
-        The lead text and which fields render depend on the alert kind
-        (anomaly / recovery / no-data / error); long values (params, detectors,
-        error message) use full-width fields, short stats use the 2-col grid.
+    ) -> list[dict[str, Any]]:
+        """Build the default attachment(s) for *alert_data*.
+
+        Returns a **base card** (always visible) and, for anomaly/recovery, a
+        neutral **detail card** whose long ``text`` block the chat client folds
+        behind "Show more". Slack and Mattermost collapse only an attachment's
+        ``text`` (never the ``fields`` grid), so the base keeps the value, the
+        expected band and the links permanently in view while the verbose tail
+        (quorum, severity, the anomalous span, detectors, parameters) rides in
+        the foldable detail card. No-data / error are short, so they render as a
+        single base card. Both cards render from one payload on Slack and
+        Mattermost.
         """
         kind = self.status_kind(alert_data)
-        fields: list[dict[str, Any]] = []
+        base_fields: list[dict[str, Any]] = []
+        detail_lines: list[str] = []
 
         def short(name: str, value: str) -> None:
+            """Add a 2-col field to the always-visible base card."""
             if value:
-                fields.append({"title": name, "value": value, "short": True})
+                base_fields.append({"title": name, "value": value, "short": True})
 
         def full(name: str, value: str) -> None:
+            """Add a full-width field to the always-visible base card."""
             if value:
-                fields.append({"title": name, "value": value, "short": False})
+                base_fields.append({"title": name, "value": value, "short": False})
+
+        def detail(name: str, value: str) -> None:
+            """Add one line to the foldable detail card: bold label + value."""
+            if value:
+                detail_lines.append(f"{self._bold(name)} {value}")
 
         def code(s: str) -> str:
             return f"`{s}`" if s else ""
@@ -261,7 +289,8 @@ class WebhookChannel(BaseAlertChannel):
         # The configured firing rule, set apart as a bold "Rule" label + an
         # inline-code chip so it reads as "this is the config that fired" at a
         # glance. Backticks render identically on Slack and Mattermost; the bold
-        # label is platform-aware (see ``_bold``).
+        # label is platform-aware (see ``_bold``). Stays in the always-visible
+        # base lead.
         rule_chip = f"{self._bold('Rule')} " + code(
             f"min_detectors={ctx['min_detectors']} · "
             f"direction={ctx['direction_policy']} · "
@@ -269,35 +298,42 @@ class WebhookChannel(BaseAlertChannel):
         )
 
         if kind == "anomaly":
-            # Description (how long it's been going on) leads; the Rule chip sits
-            # right above the value/expected fields it explains.
+            # Base (always visible): the lead (how long it's been going on), the
+            # Rule chip, and the value vs the expected band.
             lead = f"{ctx['anomaly_lead']}\n{rule_chip}"
             short("Value", code(ctx["value_display"]))
             short("Expected", code(ctx["expected_range"]))
-            short("Quorum", f"{ctx['detector_count']}/{ctx['min_detectors']} · {ctx['direction']}")
-            short("Severity", f"{alert_data.severity:.2f}")
-            # The problematic span: when the anomaly began and its latest point.
+            # Detail (folds): quorum, severity, the span, detectors + params.
+            detail(
+                "Quorum",
+                f"{ctx['detector_count']}/{ctx['min_detectors']} · {ctx['direction']}",
+            )
+            detail("Severity", f"{alert_data.severity:.2f}")
             if ctx["started_display"]:
-                short("Anomaly began", ctx["started_display"])
-                short("Latest reading", ctx["timestamp"])
+                detail("Anomaly began", ctx["started_display"])
+                detail("Latest reading", ctx["timestamp"])
             else:
-                full("Detected at", ctx["timestamp"])
-            full("Detectors", code(ctx["detector_name"]))
+                detail("Detected at", ctx["timestamp"])
+            detail("Detectors", code(ctx["detector_name"]))
             if ctx["detector_params"]:
-                full("Parameters", f"```{ctx['detector_params']}```")
+                # Fenced block on its own lines so it renders as a code block (and
+                # adds line breaks that help trip the platform's fold).
+                detail_lines.append(
+                    f"{self._bold('Parameters')}\n```\n{ctx['detector_params']}\n```"
+                )
         elif kind == "recovery":
             lead = f"{ctx['recovery_lead']}\n{rule_chip}"
             short("Value", code(ctx["value_display"]))
             short("Expected", code(ctx["expected_range"]))
-            # The incident timeline: anomaly onset → when the alert fired →
-            # when it recovered. ``short`` skips the fired field when unknown.
+            # Detail (folds): the incident timeline (onset → fired → recovered)
+            # and the detectors. ``detail`` skips the fired line when unknown.
             if ctx["started_display"]:
-                short("Anomaly began", ctx["started_display"])
-                short("Alert fired", ctx["fired_display"])
-                short("Recovered", ctx["timestamp"])
+                detail("Anomaly began", ctx["started_display"])
+                detail("Alert fired", ctx["fired_display"])
+                detail("Recovered", ctx["timestamp"])
             else:
-                full("Cleared at", ctx["timestamp"])
-            full("Detectors", code(ctx["detector_name"]))
+                detail("Cleared at", ctx["timestamp"])
+            detail("Detectors", code(ctx["detector_name"]))
         elif kind == "no_data":
             lead = "Query returned no datapoint for the latest expected interval."
             full("Expected at", ctx["timestamp"])
@@ -308,12 +344,13 @@ class WebhookChannel(BaseAlertChannel):
             err = f"{ctx['error_type']}: {ctx['error_message']}".strip(": ")
             full("Error", code(err))
 
-        # Links block — kept as its own flexible field, but every entry is a
-        # compact clickable label, never a raw URL string. A Grafana dashboard
-        # URL can be a paragraph long once it carries variables; nobody should
-        # read that in an alert, so we hide it behind the label and render in the
-        # platform's link syntax. Holds dashboard + any extra links + the "how to
-        # read this alert" guide, joined by " · ".
+        # Links — always visible in the base card. The dashboard / "how to read
+        # this alert" links are actionable, so they never fold. Every entry is a
+        # compact clickable label, never a raw URL string (a Grafana URL can be a
+        # paragraph long once it carries variables; nobody should read that in an
+        # alert), rendered in the platform's link syntax and joined by " · " on a
+        # single line to stay compact. (The title is also a clickable dashboard
+        # link.)
         link_parts = []
         if alert_data.dashboard_url:
             link_parts.append(self._link_markup(alert_data.dashboard_url, "Dashboard"))
@@ -335,14 +372,26 @@ class WebhookChannel(BaseAlertChannel):
                 f"(expected {ctx['expected_range']}) at {ctx['timestamp']}"
             )
 
-        return {
+        base: dict[str, Any] = {
             "fallback": fallback,
             "color": color,
             "title": title,
             "text": lead,
-            "fields": fields,
+            "fields": base_fields,
             "mrkdwn_in": ["text", "fields"],
         }
+        attachments: list[dict[str, Any]] = [base]
+        # Detail card: neutral (no color bar) so it reads as a continuation of
+        # the base rather than a second alert, with the verbose tail in one
+        # foldable ``text`` block.
+        if detail_lines:
+            attachments.append(
+                {
+                    "text": "\n".join(detail_lines),
+                    "mrkdwn_in": ["text"],
+                }
+            )
+        return attachments
 
     def _bold(self, text: str) -> str:
         """Render *text* bold in the target platform's markdown.

{detectkit-0.40.0 → detectkit-0.42.0}/detectkit/autotune/__init__.py

@@ -15,7 +15,6 @@ from detectkit.autotune._base import AutoTuneError, _AutoTuneBase
 from detectkit.autotune._types import ScoringMetric, TuneMode
 from detectkit.autotune.autotuner import AutoTuner, run_autotune_engine
 from detectkit.autotune.config_emitter import compute_run_id, emit_tuned_config
-from detectkit.autotune.html_labeler import render_labeler_html
 from detectkit.autotune.labels import (
     GroundTruth,
     IncidentLabels,
@@ -39,6 +38,5 @@ __all__ = [
     "emit_tuned_config",
     "parse_incident_labels",
     "parse_labels_file",
-    "render_labeler_html",
     "run_autotune_engine",
 ]

{detectkit-0.40.0 → detectkit-0.42.0}/detectkit/cli/assets/claude/CLAUDE.section.md

@@ -17,10 +17,12 @@ run. But you assist far better with **read access to the same database** (e.g. a
 database MCP for the project's ClickHouse / PostgreSQL / MySQL): you can inspect
 a metric's series, find real incidents to label for `dtk autotune`, sanity-check
 a metric query before running it, and confirm detections — instead of asking the
-user to run every query by hand. Without it, fall back to
-`dtk autotune --select <metric> --label` (a visual labeler) and to asking the
-user. This access is optional and separate from the `profiles.yml` connection
-detectkit uses for the pipeline.
+user to run every query by hand. Without it, fall back to marking incidents
+visually in `dtk tune --select <metric>` (**Label** mode to drag spans / Threshold
+capture / Lasso the anomaly cloud, or **Review** mode to confirm fired alerts as
+incidents), then **Save incidents** — which `dtk autotune` auto-discovers in
+`incidents/<metric>/` — and to asking the user. This access is optional and
+separate from the `profiles.yml` connection detectkit uses for the pipeline.
 
 ### Where to look (read the matching file before answering)
 

{detectkit-0.40.0 → detectkit-0.42.0}/detectkit/cli/assets/claude/rules/alerting.md

@@ -192,15 +192,25 @@ leads with a colored **status circle** — 🔴 anomaly, 🟢 recovery, 🟡 no-
 **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
-  `dashboard_url` when set), a short markdown lead (the duration sentence — see
-  "Incident timing" below) with the **Rule** chip beneath it, and a compact
-  fields grid: short fields Value / Expected / Quorum / Severity / Anomaly began /
-  Latest reading (Anomaly began / Alert fired / Recovered on recovery), then full-width Detectors / Parameters,
-  plus a branded footer + footer icon. @mentions ride in the **top-level**
-  message text so they notify. A custom `template` instead renders as a plain
-  text-only attachment (color/title/ branding kept, no fields grid).
+- **Slack / Mattermost / generic webhook** — an anomaly/recovery renders as
+  **two stacked attachments** so long alerts fold in the channel. Both platforms
+  collapse only an attachment's `text` block behind a "Show more" toggle (Slack
+  above 700 chars / 5 line breaks; Mattermost above ~200px) and never collapse
+  the `fields` grid, so the message splits into:
+  - an always-visible **base card** — status-colored accent bar, a clickable
+    title (the metric; links to `dashboard_url` when set), a short markdown lead
+    (the duration sentence — see "Incident timing" below) with the **Rule** chip
+    beneath it, and a compact fields grid kept to **Value / Expected** plus an
+    always-visible compact **Links** field (dashboard + extra links + the "how to
+    read this alert" guide as clickable labels);
+  - a neutral, foldable **detail card** — the verbose tail as one markdown
+    `text` block: Quorum / Severity / the anomalous span (Anomaly began → Latest
+    reading; began → fired → recovered on recovery) / Detectors / Parameters.
+
+  No-data / error stay a single base card. The branded footer + footer icon ride
+  on the **last** attachment. @mentions ride in the **top-level** message text so
+  they notify. A custom `template` instead renders as a single plain text-only
+  attachment (color/title/branding kept, no fields grid, no fold split).
 - **Telegram** — default `parse_mode` is now **HTML**. The default message is
   structured and HTML-escaped: a colored status dot (red anomaly / green
   recovery / yellow no-data / blue error), a bold headline, the lead + rule, then

{detectkit-0.40.0 → detectkit-0.42.0}/detectkit/cli/assets/claude/rules/autotune.md

@@ -64,28 +64,24 @@ ratios to choose.
 ## Command
 
 ```bash
-dtk autotune --select <sel> [--incidents FILE] [--label] [--scoring METRIC] \
+dtk autotune --select <sel> [--incidents FILE] [--scoring METRIC] \
              [--from DATE] [--to DATE] [--profile NAME] [--force] [--dry-run] [--report]
 ```
 
 - `--incidents FILE|DIR` — a labels file (below) → **supervised** tuning. May be a
   **directory** (e.g. `incidents/<name>/`): interactive runs prompt to pick a
-  version (default newest), non-interactive use the newest. With nothing given, an
+  version (default newest), non-interactive use the newest. **Omit it and `dtk
+  autotune` auto-discovers the newest labels in `incidents/<metric>/`** (the store
+  `dtk tune`'s **Save incidents** writes) — so after labeling in `dtk tune` you run
+  `dtk autotune --select <metric>` with no flag. With no labels anywhere, an
   interactive terminal prompts to enter incidents inline; declining (or running
   non-interactively) tunes **unsupervised**.
-- `--label` — open the interactive labeler (zoom/pan, edit incident edges,
-  per-incident descriptions, named sets). **Default:** a local 127.0.0.1 server +
-  browser; **Save & tune** writes `incidents/<metric>/<metric>[-<set>]-<UTC>.yml`
-  (named after the metric, optional set name as a suffix) and the run
-  **continues into tuning on it**. It **seeds from the metric's newest saved set**
-  (or from `--incidents FILE|DIR` when given), so re-running `--label` continues
-  editing in place. Beyond click-drag marking it offers **Threshold capture**
-  (grab every span above/below a horizontal line in one gesture), **Lasso capture**
-  (loop around a cloud of points; each grid-adjacent run, gaps bridged, becomes one
-  incident span), **on-chart delete** (each band's ✕, or select + Delete key), and
-  **Import file…** (load a labels file you pick). `--no-serve` writes a static
-  `metrics/<name>__labeler.html` (Export downloads the file) and exits; `--no-open`
-  prints the URL instead of launching a browser.
+- **To label incidents**, use `dtk tune --select <metric>`: switch to **Label**
+  mode (drag spans, **Threshold capture** every span past a horizontal line,
+  **Lasso** the anomaly cloud) or **Review** mode (confirm fired alerts as
+  incidents), then **Save incidents**. That writes versioned files into
+  `incidents/<metric>/` — the **same store this command reads** — so the labels feed
+  the next supervised tune with no `--incidents` flag (see `cli.md`).
 - `--scoring` — `mcc` (default), `f1`, `f_beta`, `balanced_accuracy`, `roc_auc`,
   `pr_auc`. MCC uses the whole confusion matrix and suits rare anomalies.
 - `--dry-run` — run the search but persist nothing and write no config.
@@ -115,45 +111,35 @@ incidents:
   - {at: "2026-05-11 09:05:00"}                                  # point
 ```
 
-### Getting labels — offer the interactive labeler first
+### Getting labels — label in `dtk tune` first
 
-When labels would help, **offer the interactive HTML labeler before asking the
+When labels would help, **offer to mark incidents in `dtk tune` before asking the
 user to recall timestamps** — it is the easiest, most reliable path:
 
-1. Run `dtk autotune --select <name> --label`. It starts a local labeler server
-   and opens the browser (use `--no-open` on a remote box and share the printed
-   127.0.0.1 URL; the user port-forwards or runs it locally).
-2. The user marks incidents on the chart (scroll to zoom, drag the navigator to
-   move, click-drag to mark, drag an incident's edges to adjust, add a
-   description, optionally name the set), then clicks **Save & tune**. For many
-   clear outliers, **Threshold capture** grabs every span past a horizontal line
-   at once (above/below, with an optional gap-bridge); it captures within the
-   current view by default, and dragging across the chart limits it to a time
-   window (different boundary per period) — the painted window is **saved with the
-   set and restored on reopen** (a `capture_windows:` block; metadata only). For an
-   irregular cloud, **Lasso capture** loops around the points freehand and turns
-   each grid-adjacent run (small gaps bridged) into one incident span. Each
-   band's ✕ (or select + Delete)
-   removes one, and **focus** on a list row jumps the chart to it.
-3. That writes `incidents/<metric>/<metric>[-<set>]-<UTC>.yml` automatically
-   (named after the metric, optional set name as a suffix; versioned —
-   re-labeling never overwrites) and the **same command continues into the tuning
-   run** on it. No manual file moving.
-4. **Editing over time:** re-running `--label` seeds the page from the metric's
-   newest saved set, so labeling can grow across sessions. To re-tune later on
-   saved sets, point `--incidents` at the folder (`incidents/<name>/`) —
-   interactive runs let the user pick a version, and `--label --incidents <file>`
-   opens that exact set for editing. The static `--no-serve` path still exists
-   (Export downloads a file you move into `incidents/<name>/`; its **Import
-   file…** button loads one back in).
+1. Run `dtk tune --select <name>`. It opens a localhost browser view of the real
+   series (use `--no-open` on a remote box and share the printed 127.0.0.1 URL).
+2. Mark the real incidents one of two ways:
+   - **Label** mode — drag a span over each incident, or **Threshold capture**
+     every span past a horizontal line in one gesture, or **Lasso anomalies** to
+     loop a cloud of anomaly dots into per-streak incident spans.
+   - **Review** mode — the fired alerts lead; click each alert marker to confirm it
+     **valid** (which marks it as a ground-truth incident) or **false alarm**.
+     **Confirm all unreviewed valid** does the lot — a clean metric whose alerts
+     are all good is validated in a few clicks without hand-drawing spans.
+3. Click **Save incidents**. It writes a versioned
+   `incidents/<metric>/<…>.yml` automatically.
+4. Run `dtk autotune --select <name>` with **no `--incidents` flag** — it
+   auto-discovers the newest file in `incidents/<metric>/` and tunes supervised on
+   it. (You can still pass `--incidents <file-or-dir>` to pick a specific set.)
 
 Prefer this whenever the user can *recognise* incidents on a chart but doesn't
 have exact times. If they already know the times (or you found them via a DB
 MCP), write the labels file / inline `incidents:` directly instead. If there are
 no known incidents, run unsupervised — the baseline below is good on its own.
 
-With no labels (no `--incidents`, no config `labels_file`, no interactive
-entry), tuning falls back to an **unsupervised** objective that blends three
+With no labels (no `--incidents`, no config `labels_file`, none auto-discovered
+in `incidents/<metric>/`, no interactive entry), tuning falls back to an
+**unsupervised** objective that blends three
 band-fit / flag-budget terms — `0.4·budget + 0.3·sharpness + 0.3·separation`: a
 smooth one-sided flag-rate budget (no hard cliff), sharpness (a tight,
 well-calibrated confidence interval), and separation (flagged points sitting
@@ -192,8 +178,10 @@ differs from `seasonality_candidates`, which only narrows the *set of columns*
 the search may consider but still runs the search and may choose none.
 
 Label precedence (highest first): `--incidents` flag → `labels_file` → inline
-`incidents` → interactive prompt → none. `labels_file` and `incidents` are
-mutually exclusive. `--scoring` likewise overrides `scoring_metric`.
+`incidents` → auto-discovered `incidents/<metric>/` (the newest file, e.g. from
+`dtk tune`'s **Save incidents**) → interactive prompt → none (unsupervised).
+`labels_file` and `incidents` are mutually exclusive. `--scoring` likewise
+overrides `scoring_metric`.
 
 ## The annotated config
 

{detectkit-0.40.0 → detectkit-0.42.0}/detectkit/cli/assets/claude/rules/cli.md

@@ -67,8 +67,11 @@ Automatically chooses a metric's seasonality, detector type, hyperparameters and
 history window, then writes an annotated `metrics/<name>__tuned_<id>.yml`. Reads
 the metric's loaded datapoints (run `dtk run --steps load` first if empty), never
 edits the original, never alerts. `--incidents FILE` enables supervised tuning
-against labeled incidents; without it, an unsupervised objective is used.
-`--dry-run` searches without writing. `--report [PATH]` writes the same
+against labeled incidents; omit it and autotune **auto-discovers** the newest
+labels in `incidents/<metric>/` (the store `dtk tune`'s **Save incidents** writes
+— label there in Label/Review mode, then just run `dtk autotune`); with no labels
+anywhere, an unsupervised objective is used. `--dry-run` searches without writing.
+`--report [PATH]` writes the same
 self-contained HTML report as `dtk run` for the tuned winner (default
 `reports/<metric>__tuned_<id>.html`; `<dir>` or a `.html` file also accepted).
 Full reference: `autotune.md`.

{detectkit-0.40.0 → detectkit-0.42.0}/detectkit/cli/assets/claude/skills/dtk-autotune/SKILL.md

@@ -79,44 +79,39 @@ generalize is rejected.
 Labels turn tuning from a good unsupervised default into a config optimised
 against *your* real incidents (it then optimises MCC and also tunes the alert
 window `consecutive_anomalies`). **The easiest, most reliable way to produce them
-is the interactive HTML labeler — offer this first**, before asking the user to
+is to mark incidents in `dtk tune` — offer this first**, before asking the user to
 recall timestamps:
 
 ```bash
-dtk autotune --select <name> --label
+dtk tune --select <name>
 ```
 
-By default this starts a **local labeler server** (127.0.0.1) and opens the
-browser; on a remote machine add `--no-open` and share the printed URL. Walk the
-user through it:
+This opens a localhost browser view of the metric's **real** series; on a remote
+machine add `--no-open` and share the printed URL. Walk the user through it:
 
 1. Navigate a long/dense series: **scroll to zoom**, double-click to reset, drag
-   the **navigator strip** to move the view (window = pan, edges = stretch).
-2. **Click-drag across the chart** to mark each incident (red band + a row below
-   with an optional **description**). Adjust one by dragging its **edges**, or its
-   **middle** to move it; optionally **name the set**. Remove one by clicking its
-   **✕** on the chart (or selecting it and pressing **Delete**) — no hunting in
-   the list; **focus** on a list row jumps the chart to that incident; *Clear all*
-   resets.
-3. When many outliers are obvious, use **Threshold capture**: set a horizontal
-   line (hover the chart or type a value), pick **above/below**, optionally bridge
-   small gaps, and **Add N spans** marks them all at once — then tidy with the ✕.
-   It captures within the current view by default; **drag across the chart** to
-   limit it to a time window (so a metric that behaves differently across periods
-   can take a different boundary in each). **↺ whole view** clears the window.
-4. Click **Save & tune**. The server writes `incidents/<metric>/<metric>[-<set>]-<UTC>.yml`
-   automatically (named after the metric, with the optional set name as a suffix;
-   versioned — re-labeling never overwrites) and the **same command
-   continues into the tuning run on it**. No manual file moving.
-
-**Editing an existing set:** re-running `--label` **seeds the page from the
-metric's newest saved set** (or from `--label --incidents <file-or-dir>`), so
-labeling can grow across sessions — mark a few more, save a new version. (`--no-serve`
-is the offline fallback: it writes a static `metrics/<name>__labeler.html` whose
-Export downloads a versioned file you then move into `incidents/<name>/` and pass
-via `--incidents`; its **Import file…** button loads a saved set back in.) To
-re-tune later on a saved set, point `--incidents` at `incidents/<name>/`
-(interactive runs let the user pick a version).
+   the **navigator strip** to move the view.
+2. Mark the real incidents in one of two modes:
+   - **Label** mode — **drag a span** over each incident (edges to resize, middle
+     to move, ✕/Delete to remove). When many outliers are obvious, **Threshold
+     capture** grabs every span past a horizontal line in one gesture (set the
+     line, pick the side, optionally bridge gaps); **Lasso anomalies** loops a
+     freeform cloud of anomaly dots into one incident span per grid-adjacent run.
+   - **Review** mode — the fired alerts lead; **click each alert marker** to cycle
+     its verdict un-reviewed → **valid** (green) → **false alarm** (slate).
+     **Confirming an alert valid marks it as a ground-truth incident**, and
+     **Confirm all unreviewed valid** does the lot — so a clean metric whose alerts
+     are all good is validated in a few clicks without hand-drawing spans.
+3. Click **Save incidents**. It writes `incidents/<metric>/<…>.yml` automatically
+   (versioned — saving never overwrites). Saving doesn't end the session, so you
+   can keep tuning; you can also click **Apply** to write the detector config back.
+
+**Then run autotune with no `--incidents` flag** — `dtk autotune --select <name>`
+**auto-discovers the newest file in `incidents/<metric>/`** (the same store
+`dtk tune` saves to) and tunes supervised on it. To re-tune on a specific set,
+pass `--incidents <file-or-dir>` (point it at `incidents/<name>/` and interactive
+runs let the user pick a version). Labeling grows across sessions — reopen
+`dtk tune`, mark a few more, **Save incidents** again, re-run autotune.
 
 Prefer this whenever the user can *recognise* incidents on a chart but doesn't
 have exact timestamps — it is far easier than dictating times, and they label
@@ -158,10 +153,14 @@ is good on its own; it just can't learn *which* spikes you specifically care abo
 ## Step 3 — Run autotune
 
 ```bash
-# Supervised (recommended when you have incidents):
+# Supervised — labeled in `dtk tune`: just run it, autotune auto-discovers
+# the newest file in incidents/<name>/ (no --incidents flag needed):
+dtk autotune --select <name>
+
+# Supervised — point at a specific labels file or set explicitly:
 dtk autotune --select <name> --incidents incidents/<name>.yml
 
-# Unsupervised (no labels — tunes on data statistics):
+# Unsupervised (no labels anywhere — tunes on data statistics):
 dtk autotune --select <name>
 ```