docs(recipes): document buildkite_annotate notifier

- docs/recipes/buildkite.md: replace the "annotation surface unused"
  gotcha with a positive `## Native Buildkite UI surfacing` section
  showing the new notifier. Update Escalation criteria gotcha count
  (3 → 2) and reframe the Tier-2 trigger as fulfilled.
- docs/configuration.md: new `### type: buildkite_annotate` section
  in the Notifiers chapter, between gitlab_artifact and webhook.
- ding.yaml.example: commented example block in the notifiers
  catalog after the gitlab_artifact entry.

Closes the documented gap from Wave 1 review (Buildkite recipe's
prior "annotation surface unused" trigger has fired). After this
commit, type: buildkite_annotate is a fully-documented built-in
notifier.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: zuchka

ding.yaml.example

@@ -93,6 +93,12 @@ notifiers:
   # alert-gitlab:
   #   type: gitlab_artifact
   #   # path: ding-alerts.md      # default; relative to CWD ($CI_PROJECT_DIR in GitLab CI)
+  #
+  # Buildkite annotation (publishes alerts as Buildkite build annotations via
+  # `buildkite-agent annotate`; visible at the top of the build UI):
+  # alert-buildkite:
+  #   type: buildkite_annotate
+  #   # style: error              # default; success | info | warning | error
 
 rules:
   # Event-per-event: fires on a single reading above threshold.

docs/configuration.md

@@ -215,6 +215,25 @@ notifiers:
 
 **No CI gate**: the notifier writes the file regardless of whether it's running in GitLab CI. Outside CI, it just produces a local `ding-alerts.md` — harmless. Combine with `.gitlab-ci.yml` `artifacts: { when: always, paths: [ding-alerts.md] }` to archive the file on every pipeline run (including failed jobs). See the [GitLab CI recipe](recipes/gitlab-ci.md#native-gitlab-ui-surfacing) for an end-to-end example.
 
+### `type: buildkite_annotate`
+
+Publishes alerts as Buildkite build annotations via `buildkite-agent annotate`. All alerts for a build land in a single rolling annotation (`--context ding --append`) shown at the top of the Buildkite job UI. Requires `buildkite-agent` on PATH (always set inside Buildkite jobs); outside Buildkite the notifier no-ops gracefully after a one-time warning.
+
+```yaml
+notifiers:
+  annotate:
+    type: buildkite_annotate
+    style: error    # success | info | warning | error; default error
+```
+
+| Field | Default | Notes |
+|-------|---------|-------|
+| `style` | `error` | Buildkite annotation style. Drives the colored badge in the build UI. |
+
+**Behavior**: sync, mutex-guarded. The first `Send()` writes a `# DING Alerts` H1 header; subsequent calls append `## <rule>` sections that Buildkite's `--append` concatenates into the existing annotation body. No async queue, no retry, no metrics — failures from `buildkite-agent` (agent disconnected, body too large, etc.) are returned from `Send()` with stderr captured.
+
+**No CI gate**: the notifier checks for `buildkite-agent` once at construction; outside Buildkite jobs it logs `ding: buildkite_annotate notifier: buildkite-agent not on PATH; alerts via this notifier will be no-ops` and Send becomes a no-op. See the [Buildkite recipe](recipes/buildkite.md#native-buildkite-ui-surfacing) for an end-to-end example.
+
 ### `type: webhook`
 
 Posts a flat JSON payload to any HTTP endpoint. Useful for generic integrations (PagerDuty, custom receivers, etc.).

docs/recipes/buildkite.md

@@ -66,19 +66,33 @@ Use these in `match.labels` or `message` templates. See [Configuration](../confi
 
 If the alert doesn't fire, check the Buildkite build log for `ding` output. Common issues: webhook URL not exposed (env hook scope, agent vs pipeline level), or `drain_timeout` shorter than the notifier retry window — see [Configuration](../configuration.md).
 
+## Native Buildkite UI surfacing
+
+If you want DING alerts to surface as Buildkite build annotations (visible at the top of the build UI) rather than (or alongside) external notifiers, DING ships a built-in `type: buildkite_annotate` notifier. See [`type: buildkite_annotate`](../configuration.md#type-buildkite_annotate) for the full reference.
+
+Add to `ding.yaml`:
+
+```yaml
+notifiers:
+  annotate:
+    type: buildkite_annotate
+    # style: error  # default; success | info | warning | error
+```
+
+No changes to `.buildkite/pipeline.yml` are needed — the `buildkite-agent` CLI is already on PATH inside Buildkite jobs. All DING alerts from a build land in a single rolling annotation (`--context ding --append`) so the UI stays uncluttered. Outside Buildkite (e.g. local dev), the notifier no-ops gracefully after a one-time warning.
+
 ## Tradeoffs / known limitations
 
 - **No `job` label by default.** runctx captures Buildkite's pipeline-level identifiers but not step-level (`BUILDKITE_STEP_KEY`). Add explicit `match.labels` if you need per-step rules.
 - **Binary download per step.** Bake DING into your agent image, or use a [`pre-command` hook](https://buildkite.com/docs/agent/v3/hooks#available-hooks) to install it once per agent.
-- **Annotation surface unused.** Buildkite has `buildkite-agent annotate`, the analogue of GHA's `$GITHUB_STEP_SUMMARY`. The minimal recipe doesn't use it; surfacing alerts back into the build UI would be a Tier-2 abstraction (`type: buildkite_annotate` notifier).
 
 ## Escalation criteria
 
 This recipe is **a Tier-2 candidate** by the program's standard rubric:
 
 - **Setup commands required:** 1 (`curl | tar`) — under threshold of 5
 - **Boilerplate lines:** ~24 — under threshold of 50
-- **"Gotcha" callouts:** 3 (no `job` label, binary download, no annotation surface) — over threshold of 2 → **Tier-2 candidate**
+- **"Gotcha" callouts:** 2 (no `job` label, binary download) — at threshold of 2
 - **End-to-end runnable:** yes (Buildkite has a free trial; the underlying agent is OSS and self-hostable indefinitely)
 
-**Tier-2 candidate.** The structural friction is "annotations not used" — Buildkite users expect alerts to land in the build UI, not just Slack. A `type: buildkite_annotate` notifier (calling `buildkite-agent annotate --style error --context ding`) is the natural Tier-2 abstraction. Sequence it after GitLab CI's artifact notifier (similar shape).
+Buildkite-native alert surfacing now ships as the built-in [`type: buildkite_annotate`](../configuration.md#type-buildkite_annotate) notifier (covered in the section above). The remaining gotchas (no `job` label, binary download per step) are environmental rather than implementation gaps; the recipe stays Tier 1.