normalize builds

.github/workflows/build.yml

@@ -222,14 +222,34 @@ jobs:
   create-release:
     needs: [build-nrf, build-esp32-companions, build-esp32-repeaters, build-linux]
     runs-on: ubuntu-latest
+    # Needs write to create the release AND to delete/replace an existing one for
+    # the same version (see the "replace existing release" step below).
+    permissions:
+      contents: write
     outputs:
       release_tag: ${{ steps.tag.outputs.release_tag }}
 
     steps:
-    - name: generate release tag
+    - uses: actions/checkout@v6
+
+    # Tag the release with the firmware version string itself (the single source
+    # of truth in zephcore/CMakeLists.txt), NOT a build timestamp. The same value
+    # becomes the Mesh America catalog's version key, so the configurator can
+    # compare a running device's reported firmware against the catalog and know
+    # it's up to date. A timestamp tag could never match what the device reports.
+    #
+    # NOTE: the tag is only unique per version — pushing master again without
+    # bumping ZEPHCORE_FIRMWARE_VERSION updates the existing release in place
+    # rather than cutting a new one. Bump the version to cut a new release.
+    - name: derive release tag from firmware version
       id: tag
       run: |
-        version=v$(date +"%Y%m%d.%H%M%S")
+        version=$(sed -n 's/^set(ZEPHCORE_FIRMWARE_VERSION "\(.*\)")/\1/p' zephcore/CMakeLists.txt)
+        if [ -z "$version" ]; then
+          echo "::error::Could not read ZEPHCORE_FIRMWARE_VERSION from zephcore/CMakeLists.txt"
+          exit 1
+        fi
+        echo "Release tag / catalog version: $version"
         echo "release_tag=$version" >> $GITHUB_OUTPUT
 
     - uses: actions/cache/restore@v5
@@ -258,6 +278,44 @@ jobs:
         name: firmware-${{ steps.tag.outputs.release_tag }}
         path: firmware
 
+    # Publish releasenotes/RELEASE_NOTES_<version>.md as the release body. The
+    # filename matches the firmware version string exactly (= the release tag), so
+    # this is a direct lookup with no name munging. Write the notes for a version
+    # before bumping to it; a missing file only warns (empty body), never fails
+    # the release.
+    - name: resolve release notes
+      id: notes
+      run: |
+        notes="releasenotes/RELEASE_NOTES_${{ steps.tag.outputs.release_tag }}.md"
+        if [ -f "$notes" ]; then
+          echo "Using release notes: $notes"
+          echo "notes_path=$notes" >> $GITHUB_OUTPUT
+        else
+          echo "::warning::No release notes at $notes — publishing with an empty body"
+          : > "${RUNNER_TEMP}/empty_notes.md"
+          echo "notes_path=${RUNNER_TEMP}/empty_notes.md" >> $GITHUB_OUTPUT
+        fi
+
+    # Replace any existing release for this version instead of piling onto it.
+    # Since the tag is the firmware version, re-pushing master without a bump
+    # reuses the tag. action-gh-release only overwrites assets with the SAME
+    # name, but our firmware filenames embed the commit hash — so a rebuild would
+    # ADD ~100 new assets beside the old ones and leave the tag pinned to the old
+    # commit. Deleting first (with the tag) makes each build a clean replacement:
+    # current assets only, tag re-created on the building commit.
+    # `|| true` — the first release of a version has nothing to delete.
+    - name: replace existing release for this version
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        tag="${{ steps.tag.outputs.release_tag }}"
+        if gh release view "$tag" >/dev/null 2>&1; then
+          echo "Existing release $tag found — deleting it (and its tag) so this build replaces it"
+          gh release delete "$tag" --yes --cleanup-tag || true
+        else
+          echo "No existing release for $tag — creating a new one"
+        fi
+
     - name: create release
       uses: softprops/action-gh-release@v2
       env:
@@ -265,7 +323,8 @@ jobs:
       with:
         tag_name: ${{ steps.tag.outputs.release_tag }}
         name: Firmware ${{ steps.tag.outputs.release_tag }}
-        body: ""
+        body_path: ${{ steps.notes.outputs.notes_path }}
+        target_commitish: ${{ github.sha }}
         draft: false
         files: firmware/*
 

.gitignore

@@ -116,8 +116,14 @@ UI_AUDIT_INDEX.md
 RADIO2_AUDIT_INDEX.md
 MISC_AUDIT_INDEX.md
 HANDOVER_issue34_ble_esp32.md
-RELEASE_NOTES_v1.16.3.md
 PATH_HASH_AUDIT_INDEX.md
 MESHTIMESYNC_PLAN.md
 /meshtimesync-sim/
-releasenotes/RELEASE_NOTES_v1.16.4.md
+
+# Older release notes kept local-only. Renamed 2026-07-16 to the
+# RELEASE_NOTES_<version>-zephcore.md convention; these rules follow the rename.
+# NOTE: the notes file for the CURRENT version must stay TRACKED — the release
+# workflow publishes it as the GitHub release body (body_path). Only add a rule
+# here for versions that are already released.
+releasenotes/RELEASE_NOTES_1.16.3-zephcore.md
+releasenotes/RELEASE_NOTES_1.16.4-zephcore.md

releasenotes/RELEASE_NOTES_1.16.5-zephcore.md

@@ -1,4 +1,4 @@
-# ZephCore v1.16.5-zephyr
+# ZephCore 1.16.5-zephcore
 
 > [!IMPORTANT]
 > ## Before you upgrade

zephcore/CMakeLists.txt

@@ -459,7 +459,12 @@ add_definitions(-DFIRMWARE_BUILD_EPOCH=${ZEPHCORE_BUILD_EPOCH}u)
 # value; the per-app `#ifndef FIRMWARE_VERSION` fallbacks only apply to builds that
 # bypass this injection. NOTE: the BLE DIS value in boards/common/zephcore_common.conf
 # (CONFIG_BT_DIS_FW_REV_STR) is Kconfig, not C, so it must be bumped here AND there.
-set(ZEPHCORE_FIRMWARE_VERSION "v1.16.5-zephyr")
+# The single source of truth for the firmware version. This exact string is what
+# the device reports, what CONFIG_BT_DIS_FW_REV_STR advertises, what the GitHub
+# release is tagged/named, and what the Mesh America catalog uses as its version
+# key — so the configurator can match a running device against the catalog. Keep
+# all four identical; the release workflow reads this value directly.
+set(ZEPHCORE_FIRMWARE_VERSION "1.16.5-zephcore")
 add_definitions(-DFIRMWARE_VERSION="${ZEPHCORE_FIRMWARE_VERSION}")
 
 add_subdirectory(lib/monocypher)

zephcore/boards/common/zephcore_common.conf

@@ -151,7 +151,7 @@ CONFIG_BT_DIS_FW_REV=y
 # of truth for the C side, injected as -DFIRMWARE_VERSION). This Kconfig value can't
 # read a C macro, so it must be bumped here too. Phones that read DIS and phones
 # that query CMD_DEVICE_QUERY should see the same version.
-CONFIG_BT_DIS_FW_REV_STR="v1.16.5-zephyr"
+CONFIG_BT_DIS_FW_REV_STR="1.16.5-zephcore"
 CONFIG_BT_DIS_SW_REV=y
 CONFIG_BT_DIS_SW_REV_STR="Zephyr"
 CONFIG_BT_DIS_PNP=n