docs(birdnet-go-dev): document the first-daily-consensus setting (#3056)

* docs(birdnet-go-dev): document the first-daily-consensus setting

Adds a "Fork-only settings" section to the add-on README covering the
first-daily-detection consensus rule from alexbelgium/birdnet-go#63,
which this build compiles in because merge-prs.sh merges every open
non-draft PR on the fork.

The section leads with what the setting does NOT affect, because
"requires two models to confirm" reads as far more invasive than it is:
it is inert on a single-model install (the default), on bats and
non-bird sound classes, on species not known to every active bird model,
and when a dynamic threshold has already lowered the bar. Without that
list a user reasonably concludes the add-on will start dropping
detections.

Also qualifies the header's "everything below is identical to the
standard add-on" claim, which the new section would otherwise contradict.

Docs only; no add-on behaviour changes. Version bumped so Supervisor
offers the rebuild.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(birdnet-go-dev): correct the first-daily-consensus wording

Copilot, Codex and CodeRabbit each independently flagged the same three
inaccuracies on PR #3056. Verified each against merge-prs.sh and the
alexbelgium/birdnet-go implementation before fixing.

- The "disappears once merged upstream" claim was backwards.
  merge-prs.sh syncs the fork's main with upstream BEFORE applying open
  PRs, so a PR that merges upstream stays in every future build via that
  sync step - it only stops being fork-only. Only a PR closed without
  merging drops out.
- "Every later detection... behaves exactly as today" undersold the
  rule. Every attempt for a species is held to the two-model bar until
  one is accepted, not just the first attempt - confirmed by reading
  firstDailyGateApplies, which re-evaluates every detection against the
  same memo until acceptedToday is true.
- "known to every active bird model" is decided per audio source
  (speciesSharedByActiveBirdModels scopes to sourceModelIDs, which comes
  from AnalysisBuffers(sourceID)), not add-on-wide across every source.

Docs only. validate.sh passes, no new lint findings.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

birdnet-go-dev/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 20260909.7 (10-09-2026)
+- Correct the "first daily detection consensus" README section (review feedback on PR #3056): a merged-upstream setting stays in the build rather than disappearing, every attempt for a species is held back until one is accepted rather than only the first, and the "known to every active bird model" exemption is scoped per audio source, matching the implementation.
+## 20260909.6 (10-09-2026)
+- Document the fork-only "first daily detection consensus" setting (alexbelgium/birdnet-go#63): requires a second model to confirm each bird species' first detection of the day. Off by default; no behaviour change unless enabled.
 ## 20260909.5 (09-09-2026)
 - Minor bugs fixed
 ## 20260909.4 (09-09-2026)

birdnet-go-dev/README.md

@@ -1,6 +1,6 @@
 # Home assistant add-on: Birdnet-Go (from source)
 
-> **⚠️ Test build.** This is a special variant of the [standard birdnet-go add-on](https://github.com/alexbelgium/hassio-addons/tree/master/birdnet-go). Instead of pulling the prebuilt `ghcr.io/tphakala/birdnet-go` image, it **compiles BirdNET-Go from the [`alexbelgium/birdnet-go`](https://github.com/alexbelgium/birdnet-go) fork**. At build time it syncs the fork's `main` with the `tphakala/birdnet-go` upstream and **merges every open non-draft ("in review") pull request on the fly** (see [`merge-prs.sh`](./merge-prs.sh)), so the binary reflects upstream main plus all work currently under review. Everything below is identical to the standard add-on.
+> **⚠️ Test build.** This is a special variant of the [standard birdnet-go add-on](https://github.com/alexbelgium/hassio-addons/tree/master/birdnet-go). Instead of pulling the prebuilt `ghcr.io/tphakala/birdnet-go` image, it **compiles BirdNET-Go from the [`alexbelgium/birdnet-go`](https://github.com/alexbelgium/birdnet-go) fork**. At build time it syncs the fork's `main` with the `tphakala/birdnet-go` upstream and **merges every open non-draft ("in review") pull request on the fly** (see [`merge-prs.sh`](./merge-prs.sh)), so the binary reflects upstream main plus all work currently under review. Everything below is identical to the standard add-on, except the fork-only settings listed under [Fork-only settings](#fork-only-settings).
 
 
 
@@ -65,6 +65,38 @@ Additional variables can be configured using the config.yaml file found in /conf
 - Config_env.yaml
 Additional environment variables can be configured there
 
+### Fork-only settings
+
+These are currently fork-only settings from the [`alexbelgium/birdnet-go`](https://github.com/alexbelgium/birdnet-go) fork and are **not** in the standard add-on. [`merge-prs.sh`](./merge-prs.sh) syncs the fork's `main` with upstream before applying open PRs, so once a PR merges upstream the setting stays in this build — it just arrives via that sync instead of the PR-merge step, and stops being fork-only. Only a PR that is **closed without merging** drops its setting from later builds.
+
+#### First daily detection consensus
+
+Requires a second model to confirm the **first** detection of each bird species each day. Until one is accepted, every attempt for that species is held to the same two-model bar; only once a detection clears it does every later detection that day behave exactly as it does today, on a single model.
+
+The first detection of a species in a day is the weakest evidence the pipeline produces, and it is the one that creates a "new species today" entry. Asking two models to agree on just that one detection removes most spurious new-species entries without slowing anything else down.
+
+**Off by default.** Turn it on in the web UI under *Settings → Filters → First Daily Detection Consensus*, or in `config.yaml`:
+
+```yaml
+realtime:
+  firstdailyconsensus:
+    enabled: true
+```
+
+The setting is re-read on each detection cycle, so it takes effect without restarting the add-on.
+
+It deliberately does **nothing** in these cases, all of which keep today's single-model behaviour:
+
+- you run only one bird model (the default) — a second opinion does not exist, so the rule can never trigger
+- the species is not a bird — bats and the non-bird sound classes Perch reports (insects, amphibians, mammals, `power_tool`, and so on)
+- the species is not known to *every* active bird model analyzing that audio source — a species only one of them can name could never reach two confirmations. With several sources running different model combinations, this is decided per source, not add-on-wide
+- a dynamic threshold has actually lowered the bar for that species, meaning you asked for a more permissive gate
+- the taxonomy or the database cannot be consulted — it fails open and accepts the detection
+
+In practice it only bites when a single audio source has two or more bird models (for example BirdNET plus Perch) analyzing it, on species all of them can identify. The trade is fewer false new-species entries, at the cost of occasionally delaying a genuine first sighting until a second model agrees.
+
+Requires [alexbelgium/birdnet-go#63](https://github.com/alexbelgium/birdnet-go/pull/63).
+
 ### MQTT and MariaDB auto-configuration (opt-in)
 
 If the Home Assistant **MQTT** addon is installed and running and you set `mqtt_auto_config: true` in the addon options, the addon writes the HA Mosquitto credentials directly into BirdNET-Go's `config.yaml` on every startup: `realtime.mqtt.enabled`, `broker`, `username`, and `password` are populated, and the topic defaults to `birdnet`. In addition, it enables BirdNET-Go's **native Home Assistant MQTT auto-discovery** (`realtime.mqtt.homeassistant.enabled`), so the detection sensors show up in Home Assistant automatically — **no manual MQTT sensor YAML required** (the hand-written sensors in [HAINTEGRATION.md](./HAINTEGRATION.md) remain available if you prefer to build your own). Messages are also retained (`realtime.mqtt.retain: true`) so sensor states survive Home Assistant restarts. When the option is `false` (the default), the addon still logs the broker details and reminds you about the option whenever Mosquitto is detected — nothing is written.

birdnet-go-dev/config.yaml

@@ -127,5 +127,5 @@ slug: birdnet-go-dev
 udev: true
 url: https://github.com/alexbelgium/hassio-addons
 usb: true
-version: "20260909.5"
+version: "20260909.7"
 video: true