Tracked publish wrapper to wire release Slack alerts

.gitignore

@@ -11,3 +11,6 @@ out/
 !packages/*/build/
 # populace.build is a real namespace package, not a build-artifact dir
 !packages/populace-build/src/populace/build/
+
+# Release alert webhooks (real file is machine-local; .example is tracked)
+tools/release.env

README.md

@@ -53,3 +53,30 @@ final candidate diagnostics under `runs/<run_id>/` without updating production
 See [SYSTEM_REQUIREMENTS.md](SYSTEM_REQUIREMENTS.md) for the measured memory,
 disk, and CPU footprint of developing and building locally (and what to budget
 on a build machine — RAM is the binding constraint).
+
+## Releasing & alerts
+
+Publishing uploads the locally built `releases/<id>/` artifacts to the Hugging
+Face dataset, tags the release, and updates `latest.json`. It runs on the build
+machine (it needs the freshly built H5), so it isn't a CI step:
+
+```bash
+tools/publish_release.sh releases/<id> --repo-id policyengine/populace-us
+```
+
+`tools/publish_release.sh` is a thin wrapper around `populace-publish-release`
+(all arguments pass straight through). The moment `latest.json` goes live, the
+publish CLI posts a release alert to Slack — `#populace-us` or `#populace-uk`,
+chosen from the repo id.
+
+The alert is a **no-op unless the channel's incoming-webhook URL is set**, so
+configure it once on the build machine:
+
+```bash
+cp tools/release.env.example tools/release.env   # then paste the webhook URLs
+```
+
+`tools/release.env` is gitignored; the wrapper loads it (or you can just export
+`SLACK_WEBHOOK_POPULACE_US` / `SLACK_WEBHOOK_POPULACE_UK` in your shell) and
+warns if neither is set. After that, every release publishes with an automatic
+Slack alert.

tools/publish_release.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# Publish a Populace release and fire its Slack alert, in one tracked path.
+#
+# Thin wrapper around `populace-publish-release` so that every ship goes
+# through the same command and the release alert is guaranteed to be wired.
+# The alert itself lives in the publish CLI (populace.data.slack.notify_release)
+# and is a no-op unless the channel webhook env var is set — this wrapper just
+# loads those from an optional gitignored env file and warns if they're missing.
+#
+# Usage:
+#   tools/publish_release.sh <release_dir> [--repo-id …] [--artifact-root …] …
+# All arguments are passed straight through to `populace-publish-release`.
+#
+# One-time setup on the build machine (see README "Release alerts"):
+#   cp tools/release.env.example tools/release.env   # then fill in the URLs
+# or just export SLACK_WEBHOOK_POPULACE_US / _UK in your shell.
+
+set -euo pipefail
+
+ENV_FILE="${POPULACE_RELEASE_ENV:-$(dirname "$0")/release.env}"
+if [[ -f "$ENV_FILE" ]]; then
+  set -a
+  # shellcheck disable=SC1090
+  source "$ENV_FILE"
+  set +a
+fi
+
+if [[ -z "${SLACK_WEBHOOK_POPULACE_US:-}" && -z "${SLACK_WEBHOOK_POPULACE_UK:-}" ]]; then
+  echo "warning: no SLACK_WEBHOOK_POPULACE_US/_UK set — this release will" >&2
+  echo "         publish WITHOUT a Slack alert. Set them in your shell or in" >&2
+  echo "         $ENV_FILE (see README 'Release alerts')." >&2
+fi
+
+exec populace-publish-release "$@"

tools/release.env.example

@@ -0,0 +1,13 @@
+# Release alert configuration for tools/publish_release.sh.
+#
+# Copy this file to tools/release.env (gitignored) on the build machine and
+# paste the Slack *incoming webhook* URLs for #populace-us and #populace-uk.
+# Once set, every `tools/publish_release.sh …` (and any direct
+# `populace-publish-release`) posts a release alert to the matching channel.
+#
+#   cp tools/release.env.example tools/release.env
+#
+# Leave a line blank to skip alerts for that country.
+
+export SLACK_WEBHOOK_POPULACE_US=
+export SLACK_WEBHOOK_POPULACE_UK=