From d2b3458943e9118d5fcf31ac1fd2a4699696f52c Mon Sep 17 00:00:00 2001
From: Elmehdi Aitbrahim <eaitbrahim@gmail.com>
Date: Thu, 20 Aug 2026 16:25:21 -0400
Subject: [PATCH 1/3] feat(packaging): a double-clickable macOS app, and a
 release job that cannot ship it unsigned

The macOS half of #438, built and run rather than described.

`packaging/macos_app.sh` wraps a frozen bundle into a `.app` and a 20MB compressed `.dmg`. The
one design decision in it: **the app launches `keel serve`, not the CLI.** An app launched from
Finder has no controlling terminal at all -- the packaging research rates that the single biggest
technical risk in this milestone, above code signing -- so a bundle whose entry point were the CLI
would open, find no tty, refuse every gated action and exit with nothing on screen. The console
binary ships inside the same `.app`, so a terminal user still gets the full CLI from
`keel.app/Contents/Resources/keel/keel`. One artifact, both audiences, no second build.

The launcher deliberately does NOT set a working directory. Finder launches with cwd `/`, which
was the blocker D1 (#434) removed; `keel_core.paths` now resolves state to the OS app-data
directory, and a `cd` here would override that with a guess. It only ensures the state directory
exists and tees the server's output into `serve.log` beside it, so "why did it not start" is
answerable from the folder the operator already knows about.

VERIFIED THE WAY FINDER WOULD DO IT -- cwd `/`, stdin closed, no controlling terminal:

    200  /   200  /setup   200  /gates   200  /venues
    303  POST /setup/config   303  POST /setup/database   303  POST /setup/rules
    state created: config.yaml, keel.db, serve.log

That is the milestone's whole promise, demonstrated: a working paper deployment built from a
browser, on a machine with nothing on it, with no command typed and no terminal involved.

THE RELEASE JOB, AND WHY IT DEFAULTS TO NOT PUBLISHING.

An unsigned binary that then asks for exchange API keys is the shape of malware distribution --
the desktop PRD opens on a live example found while surveying this space. For a project whose
proposition is auditability, shipping that silhouette without OS-level verification would be worse
than shipping no installer. So `desktop: publish` FAILS while signing is unconfigured, rather than
quietly attaching an unsigned build to a release, and the default is `build`: the safe value is
the one you get by not thinking about it. Signing is left ABSENT rather than stubbed, because a
step that silently does nothing when a secret is missing is precisely how an unsigned artifact
comes to look signed.

The smoke step is the part that earns its keep. Three of the four ways a bundle breaks are silent
-- it starts cleanly and has no venues, or no version identity, or no templates (#458) -- so every
assertion there corresponds to one of them, including that the dev-only fake venue never reaches a
shipped artifact.

Windows ships a zip for now. Inno Setup is the intended installer and carries the install-path and
version-decision UX #438 specifies, but it cannot be tested anywhere in this repository today; an
installer nobody has run is a worse artifact than an archive everyone understands.

`tests/test_desktop_packaging.py` pins what cannot be run here: that publishing unsigned is
impossible by accident, that no second route to a release asset exists, that the job builds the
tag it released rather than whatever main drifted to, that stamping precedes freezing, and that
each of the four silent failures is still checked. The signing assertion excludes comment lines --
the script explains in prose which commands signing will need, and a test that forbade the words
would forbid documenting them -- and it was mutation-checked by adding a `codesign` call.

4030 passed, 3 skipped (12 new). ruff clean repo-wide; mypy clean over keel + packages.

Refs #438, #18.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/release.yml   | 147 ++++++++++++++++++++++++++++
 packaging/macos_app.sh          |  81 ++++++++++++++++
 tests/test_desktop_packaging.py | 164 ++++++++++++++++++++++++++++++++
 3 files changed, 392 insertions(+)
 create mode 100755 packaging/macos_app.sh
 create mode 100644 tests/test_desktop_packaging.py

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c2303891..aa275050 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -12,6 +12,12 @@ on:
         description: "Semver to release, without a leading v (e.g. 0.2.0). Must already match pyproject.toml."
         required: true
         type: string
+      desktop:
+        description: "Desktop artifacts. 'build' produces and smoke-tests them as workflow artifacts; 'publish' also attaches them to the release and REQUIRES signing to have succeeded; 'skip' does neither."
+        required: true
+        default: build
+        type: choice
+        options: [build, publish, skip]
 
 permissions:
   contents: write # create the tag and the release
@@ -218,3 +224,144 @@ jobs:
             --notes-file /tmp/release-notes.md
           echo "published v${{ inputs.version }}"
 
+  # -- desktop artifacts -------------------------------------------------------------------------
+  #
+  # Runs AFTER `release`, so the tag it checks out is the one that job created and published.
+  #
+  # WHY IT DEFAULTS TO `build` AND NOT `publish`. An unsigned binary that then asks for exchange
+  # API keys is the shape of malware distribution -- section 1 of the desktop PRD opens on a live
+  # example found while surveying this space. For a project whose proposition is auditability,
+  # shipping that silhouette without OS-level verification would be worse than shipping no
+  # installer at all. So the pipeline is built so that publishing an unsigned artifact is not
+  # something you can do by forgetting a flag: `publish` FAILS when the signing secrets are
+  # absent, rather than quietly attaching an unsigned build to a release.
+  desktop:
+    needs: release
+    if: ${{ inputs.desktop != 'skip' }}
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-14
+            arch: arm64
+          # Two DMGs rather than a universal2 build: `lipo`-merging a bundled-CPython-plus-
+          # native-extension tree is fragile in practice. Note this runner image is scheduled to
+          # sunset around Aug 2027.
+          - os: macos-15-intel
+            arch: x86_64
+          - os: windows-latest
+            arch: x86_64
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: v${{ inputs.version }}
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install the workspace
+        run: uv sync --all-packages
+
+      # The SAME stamp the release job writes. Without it a bundle reports `[checkout]`, and
+      # `keel/version.py` will not call an unstamped bundle a release -- correctly, which is why
+      # the smoke below can assert on it.
+      - name: Stamp build info
+        shell: bash
+        run: |
+          set -euo pipefail
+          COMMIT="$(git rev-parse --short=12 HEAD)"
+          cat > keel/_build_info.py <<EOF
+          """Generated by .github/workflows/release.yml. Do not edit or commit."""
+
+          VERSION = "${{ inputs.version }}"
+          COMMIT = "$COMMIT"
+          DIRTY = False
+          EOF
+          echo "stamped $COMMIT"
+
+      - name: Freeze
+        run: uv run --with pyinstaller pyinstaller packaging/keel.spec --noconfirm
+
+      # THE STEP THAT EARNS ITS KEEP. Three of the four ways a bundle breaks are SILENT: it
+      # starts cleanly, and it has no venues, or no version identity, or no templates. Every
+      # assertion here corresponds to one of those, found by building a bundle and running it.
+      - name: Smoke the bundle
+        shell: bash
+        run: |
+          set -euo pipefail
+          BIN="dist/keel/keel"
+          [ "${{ runner.os }}" = "Windows" ] && BIN="dist/keel/keel.exe"
+
+          OUT="$("$BIN" --version)"
+          echo "$OUT"
+          printf '%s' "$OUT" | grep -q "${{ inputs.version }}" || {
+            echo "::error::the bundle does not report the released version"; exit 1; }
+          printf '%s' "$OUT" | grep -q "release" || {
+            echo "::error::the bundle is not stamped as a release build"; exit 1; }
+          printf '%s' "$OUT" | grep -q "DIRTY" && {
+            echo "::error::the bundle reports a dirty tree"; exit 1; } || true
+
+          # Without collected metadata this answers "no keel distributions installed" -- the
+          # deploy check that exists to catch a partial upgrade, reporting success by having
+          # nothing to compare.
+          "$BIN" versions || { echo "::error::the bundle cannot see its own distributions"; exit 1; }
+
+          # Without the adapters as hidden imports this answers `0 adapter(s)`, and a packaged
+          # keel with no venues is not a trading tool at all.
+          ADAPTERS="$("$BIN" brokers list | head -1)"
+          echo "$ADAPTERS"
+          printf '%s' "$ADAPTERS" | grep -qE '^[1-9][0-9]* adapter' || {
+            echo "::error::the bundle discovered no broker adapters"; exit 1; }
+          # And the dev-only fake venue must never reach a shipped artifact: it would put a FAKE
+          # VENUE in the venue list of a signed install a real person downloaded.
+          "$BIN" brokers list | grep -qi 'fake' && {
+            echo "::error::the dev-only fake venue is in the bundle"; exit 1; } || true
+
+          # Without collected package data `init-config` cannot write a config, so a first run
+          # cannot start at all.
+          WORK="$(mktemp -d)"
+          (cd "$WORK" && "$OLDPWD/$BIN" init-config >/dev/null && test -s config.yaml) || {
+            echo "::error::the bundle cannot write a config from its templates"; exit 1; }
+          echo "smoke passed"
+
+      - name: Package (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          mkdir -p out
+          packaging/macos_app.sh dist/keel out "${{ inputs.version }}"
+
+      - name: Package (Windows)
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          # Inno Setup is the intended installer (per-user, no admin prompt, and the install-path
+          # and version-decision UX #438 specifies). Until that script is written and tested on a
+          # Windows runner, a zip is shipped rather than an untested installer -- an installer
+          # nobody has run is a worse artifact than an archive everyone understands.
+          mkdir -p out
+          7z a -tzip "out/keel-${{ inputs.version }}-windows-${{ matrix.arch }}.zip" ./dist/keel/* >/dev/null
+          ls -l out
+
+      # SIGNING GOES HERE. Deliberately absent rather than stubbed: a step that silently does
+      # nothing when a secret is missing is how an unsigned artifact ends up looking signed. The
+      # gate below fails the job instead, so the missing half is impossible to overlook.
+      #   macOS  -- Developer ID cert in an ephemeral keychain, `codesign --options runtime`,
+      #             `notarytool submit --wait`, `stapler staple`.
+      #   Windows -- Azure Trusted Signing or an OV cert, via a protected environment.
+      - name: Refuse to publish an unsigned artifact
+        if: inputs.desktop == 'publish'
+        run: |
+          echo "::error::'publish' was requested but no signing is configured in this workflow yet."
+          echo "::error::An unsigned binary that then asks for exchange API keys is the shape of"
+          echo "::error::malware distribution. Re-run with desktop=build, or wire signing first."
+          exit 1
+
+      - name: Upload the artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: keel-${{ inputs.version }}-${{ runner.os }}-${{ matrix.arch }}
+          path: out/*
+          if-no-files-found: error
diff --git a/packaging/macos_app.sh b/packaging/macos_app.sh
new file mode 100755
index 00000000..c309e6cf
--- /dev/null
+++ b/packaging/macos_app.sh
@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Wrap a built PyInstaller bundle into a double-clickable macOS .app, then a .dmg (#438).
+#
+# Usage:  packaging/macos_app.sh <dist/keel> <out-dir> <version>
+#
+# WHY THE .app LAUNCHES `keel serve` AND NOT THE CLI.
+# An app launched from Finder has **no controlling terminal at all** -- the packaging research
+# rates that the single biggest technical risk in this milestone, above code signing. A bundle
+# whose entry point were the CLI would open, find no tty, refuse every gated action and exit with
+# nothing on screen. So the entry point serves the local web UI and opens the user's browser,
+# which is the shape D2 exists to provide and the one every comparable project converged on.
+#
+# The console binary ships inside the same .app, so a terminal user can still run
+# `keel.app/Contents/Resources/keel/keel <command>` and get the full CLI. One artifact, both
+# audiences, no second build.
+#
+# SIGNING IS NOT DONE HERE. This script produces an UNSIGNED bundle on purpose: signing needs an
+# Apple Developer ID certificate in a keychain, which exists only in the release workflow's
+# protected environment. Gatekeeper will refuse this output on another machine, and that is the
+# correct outcome for an artifact nobody signed.
+set -euo pipefail
+
+BUNDLE_DIR="${1:?usage: macos_app.sh <dist/keel> <out-dir> <version>}"
+OUT_DIR="${2:?usage: macos_app.sh <dist/keel> <out-dir> <version>}"
+VERSION="${3:?usage: macos_app.sh <dist/keel> <out-dir> <version>}"
+
+APP="$OUT_DIR/keel.app"
+rm -rf "$APP"
+mkdir -p "$APP/Contents/MacOS" "$APP/Contents/Resources"
+
+cp -R "$BUNDLE_DIR" "$APP/Contents/Resources/keel"
+
+# `LSBackgroundOnly` keeps a Dock icon and a menu bar from appearing for what is really a local
+# server: the user's attention belongs in the browser window that opens, not on an empty app.
+cat > "$APP/Contents/Info.plist" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleName</key><string>keel</string>
+  <key>CFBundleDisplayName</key><string>keel</string>
+  <key>CFBundleIdentifier</key><string>com.codegatesoftware.keel</string>
+  <key>CFBundleVersion</key><string>$VERSION</string>
+  <key>CFBundleShortVersionString</key><string>$VERSION</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleExecutable</key><string>keel-launcher</string>
+  <key>LSMinimumSystemVersion</key><string>13.0</string>
+  <key>LSBackgroundOnly</key><true/>
+  <key>NSHighResolutionCapable</key><true/>
+</dict>
+</plist>
+PLIST
+
+# The launcher, and every line of it is load-bearing.
+cat > "$APP/Contents/MacOS/keel-launcher" <<'LAUNCHER'
+#!/bin/bash
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BIN="$HERE/../Resources/keel/keel"
+
+# Finder launches an app with cwd = "/". Every keel path used to resolve against cwd, which is
+# why `/keel.db` and `/config.yaml` were the blocker D1 (#434) existed to remove -- and why this
+# does NOT try to set one. `keel_core.paths` resolves state to the OS app-data directory when
+# there is no deployment folder, and `cd`-ing somewhere here would override that with a guess.
+cd /
+
+# Logs go beside the state, not to the system log: an operator asking "why did it not start" can
+# be pointed at one file in the folder they already know about.
+STATE="${KEEL_HOME:-$HOME/Library/Application Support/keel}"
+mkdir -p "$STATE"
+exec "$BIN" serve >>"$STATE/serve.log" 2>&1
+LAUNCHER
+chmod +x "$APP/Contents/MacOS/keel-launcher"
+
+echo "built $APP"
+
+# `hdiutil` with UDZO: compressed, read-only, and the format `notarytool` accepts for stapling.
+DMG="$OUT_DIR/keel-$VERSION-$(uname -m).dmg"
+rm -f "$DMG"
+hdiutil create -quiet -srcfolder "$APP" -volname "keel $VERSION" -format UDZO "$DMG"
+echo "built $DMG"
diff --git a/tests/test_desktop_packaging.py b/tests/test_desktop_packaging.py
new file mode 100644
index 00000000..58e3e9fd
--- /dev/null
+++ b/tests/test_desktop_packaging.py
@@ -0,0 +1,164 @@
+"""The desktop artifacts: what the workflow must never do, and what the bundle must always be.
+
+The build job cannot be run here -- it needs three OS runners -- so what is pinned is the set of
+claims that would be expensive to discover were false: that publishing an unsigned artifact is
+impossible by accident, and that the smoke step still checks each of the four ways a bundle breaks.
+Three of those four are SILENT (#458): the binary starts cleanly and has no venues, or no version
+identity, or no templates.
+"""
+
+from __future__ import annotations
+
+import stat
+from pathlib import Path
+
+import pytest
+import yaml
+
+_ROOT = Path(__file__).resolve().parents[1]
+_WORKFLOW = _ROOT / ".github" / "workflows" / "release.yml"
+_MACOS_SCRIPT = _ROOT / "packaging" / "macos_app.sh"
+
+
+@pytest.fixture(scope="module")
+def workflow() -> dict:
+    return yaml.safe_load(_WORKFLOW.read_text(encoding="utf-8"))
+
+
+@pytest.fixture(scope="module")
+def desktop_job(workflow: dict) -> dict:
+    return workflow["jobs"]["desktop"]
+
+
+def _steps_text(job: dict) -> str:
+    return "\n".join(str(step.get("run", "")) for step in job["steps"])
+
+
+# -- the thing that must not happen ------------------------------------------------------------
+
+
+def test_publishing_an_unsigned_artifact_fails_rather_than_succeeding_quietly(
+    desktop_job: dict,
+) -> None:
+    """An unsigned binary that then asks for exchange API keys is the shape of malware
+    distribution -- the desktop PRD opens on a live example found while surveying this space.
+
+    So `publish` must FAIL while signing is unconfigured. A step that silently did nothing when a
+    secret was missing is exactly how an unsigned artifact ends up attached to a release looking
+    like a signed one."""
+    guards = [
+        step
+        for step in desktop_job["steps"]
+        if str(step.get("if", "")).strip() == "inputs.desktop == 'publish'"
+    ]
+    assert guards, "nothing guards the publish path"
+    assert any("exit 1" in str(step.get("run", "")) for step in guards)
+
+
+def test_the_default_is_build_not_publish(workflow: dict) -> None:
+    """Publishing is opt-in. The safe value is the one you get by not thinking about it."""
+    desktop = workflow[True]["workflow_dispatch"]["inputs"]["desktop"]
+    assert desktop["default"] == "build"
+    assert set(desktop["options"]) == {"build", "publish", "skip"}
+
+
+def test_no_step_attaches_a_desktop_artifact_to_the_github_release(desktop_job: dict) -> None:
+    """The only route to a release asset is `gh release upload`/`create`. While signing is
+    unconfigured there must be no such call in this job at all -- the guard above is the
+    intended stop, and this is the one that catches a second route added around it."""
+    text = _steps_text(desktop_job)
+    assert "gh release upload" not in text
+    assert "gh release create" not in text
+
+
+def test_the_desktop_job_runs_after_the_release_and_builds_that_tag(desktop_job: dict) -> None:
+    """It must package the commit that was actually released, not whatever `main` drifted to."""
+    assert desktop_job["needs"] == "release"
+    checkout = next(
+        s for s in desktop_job["steps"] if str(s.get("uses", "")).startswith("actions/checkout")
+    )
+    assert checkout["with"]["ref"] == "v${{ inputs.version }}"
+
+
+# -- the four silent failures, still checked ---------------------------------------------------
+
+
+def test_the_smoke_step_asserts_the_bundle_identifies_itself(desktop_job: dict) -> None:
+    """Without the stamp a bundle reports `[checkout]`; without collected metadata
+    `keel versions` answers "no keel distributions installed" -- the deploy check that exists to
+    catch a partial upgrade, reporting success by having nothing to compare."""
+    text = _steps_text(desktop_job)
+    assert "--version" in text
+    assert "versions" in text
+    assert "DIRTY" in text
+
+
+def test_the_smoke_step_asserts_the_bundle_has_venues_and_not_the_fake_one(
+    desktop_job: dict,
+) -> None:
+    """`0 adapter(s)` was the real result of the first build that looked fine. And the dev-only
+    fake venue must never reach a shipped artifact: it would put a FAKE VENUE in the venue list
+    of a signed install a real person downloaded, which is worse than shipping nothing because it
+    looks like a supported option."""
+    text = _steps_text(desktop_job)
+    assert "brokers list" in text
+    assert "adapter" in text
+    assert "fake" in text.lower()
+
+
+def test_the_smoke_step_asserts_a_first_run_can_write_a_config(desktop_job: dict) -> None:
+    """The templates are package DATA. Without them `init-config` cannot write a config, so a
+    first run cannot start at all."""
+    assert "init-config" in _steps_text(desktop_job)
+
+
+def test_the_bundle_is_stamped_before_it_is_frozen(desktop_job: dict) -> None:
+    """Order matters: the stamp is a source file the freeze embeds. Stamping afterwards would
+    produce an unstamped bundle and a stamped working tree."""
+    names = [str(step.get("name", "")) for step in desktop_job["steps"]]
+    assert names.index("Stamp build info") < names.index("Freeze")
+    assert names.index("Freeze") < names.index("Smoke the bundle")
+
+
+# -- the macOS bundle --------------------------------------------------------------------------
+
+
+def test_the_macos_script_is_executable() -> None:
+    assert _MACOS_SCRIPT.exists()
+    assert _MACOS_SCRIPT.stat().st_mode & stat.S_IXUSR
+
+
+def test_the_app_launches_serve_and_not_the_cli() -> None:
+    """An app launched from Finder has NO controlling terminal. A bundle whose entry point were
+    the CLI would open, find no tty, refuse every gated action and exit with nothing on screen.
+    The packaging research rates this the single biggest technical risk in the milestone."""
+    text = _MACOS_SCRIPT.read_text(encoding="utf-8")
+    assert '"$BIN" serve' in text
+    assert "CFBundleExecutable" in text
+
+
+def test_the_launcher_does_not_invent_a_working_directory() -> None:
+    """Finder launches with cwd `/`, and every keel path used to resolve against cwd -- the
+    blocker D1 (#434) removed. `keel_core.paths` now resolves state to the OS app-data directory,
+    and a `cd` in the launcher would override that with a guess."""
+    text = _MACOS_SCRIPT.read_text(encoding="utf-8")
+    assert "cd /" in text
+    assert "cd $HOME" not in text and 'cd "$HOME"' not in text
+
+
+def test_the_script_runs_no_signing_command() -> None:
+    """It produces an UNSIGNED bundle on purpose -- signing needs a Developer ID certificate that
+    exists only in the release workflow's protected environment. A script that appeared to sign
+    would be worse than one that plainly does not.
+
+    Comment lines are excluded rather than the whole file searched: the script EXPLAINS in prose
+    which commands signing will need, and a test that forbade the words would forbid documenting
+    them."""
+    code = [
+        line
+        for line in _MACOS_SCRIPT.read_text(encoding="utf-8").splitlines()
+        if line.strip() and not line.lstrip().startswith("#")
+    ]
+    for command in ("codesign", "notarytool", "stapler", "productsign"):
+        offenders = [line for line in code if command in line]
+        assert not offenders, f"{command} is invoked: {offenders}"

From 6c6f5a1ad0fd6752ea127f933a7428f3f6077cc0 Mon Sep 17 00:00:00 2001
From: Elmehdi Aitbrahim <eaitbrahim@gmail.com>
Date: Thu, 20 Aug 2026 16:32:03 -0400
Subject: [PATCH 2/3] feat(packaging): ship the desktop builds unsigned, with
 provenance instead of a certificate

Apple signing is dropped as a budget decision, and the honest version of that decision is worth
writing down rather than leaving as an empty step.

There is no free path to a notarised macOS build. Notarisation requires a Developer ID
certificate, which requires the $99/yr Developer Program; a free Apple account signs only for
local development, and a self-signed certificate buys nothing at all, because Gatekeeper trusts
Apple-issued Developer IDs and nothing else. So an unsigned `.dmg` off the internet carries a
quarantine flag and macOS refuses the first open.

That cost is documented rather than hidden. The release notes now say plainly that the builds are
not code-signed, why, and what the user has to do once: System Settings -> Privacy & Security ->
Open Anyway, and More info -> Run anyway for SmartScreen. A download that trips Gatekeeper with no
explanation is indistinguishable from a broken one.

WHAT REPLACES OS-LEVEL TRUST, AT ZERO COST. Every artifact now carries a GitHub build attestation
binding it to this repository, this workflow and this commit, verifiable with

    gh attestation verify <file> --repo CodeGateSoftware/keel

plus a SHA256SUMS file attached to the same release. That does not move Gatekeeper -- nothing free
does -- but it answers "did this binary come from that source, built by that pipeline", which is
the question a certificate answers too, and arguably the one an auditable project should care
about most. A user who is told to click past a security warning with no way to check what they
have is being taught a bad habit while holding exchange API keys; this gives them the check.

The publish option is spelled `publish-unsigned`. `publish` would have been a value you could
select without thinking; this one cannot be chosen without reading the word, the default remains
`build` (which attaches nothing to a release), and a test pins both. Attestation is produced
BEFORE anything is attached, so a failed attestation cannot leave a published artifact behind
that nobody can verify -- also pinned.

The previous "refuse to publish while unsigned" guard is gone deliberately, replaced by the
naming and the provenance rather than silently deleted.

4032 passed, 3 skipped. ruff clean repo-wide; mypy clean over keel + packages. The `.app` and
`.dmg` were rebuilt and the app driven end-to-end after the change.

Refs #438, #18.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/release.yml   | 107 +++++++++++++++++++++++++-------
 packaging/macos_app.sh          |  16 +++--
 tests/test_desktop_packaging.py |  89 +++++++++++++++++---------
 3 files changed, 159 insertions(+), 53 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index aa275050..9e5ac4b1 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -13,11 +13,11 @@ on:
         required: true
         type: string
       desktop:
-        description: "Desktop artifacts. 'build' produces and smoke-tests them as workflow artifacts; 'publish' also attaches them to the release and REQUIRES signing to have succeeded; 'skip' does neither."
+        description: "Desktop artifacts. 'build' produces and smoke-tests them as workflow artifacts only. 'publish-unsigned' also attaches them to the release -- they are NOT code-signed, so macOS Gatekeeper and Windows SmartScreen will warn; the option is named for what it does so it cannot be chosen without reading it. 'skip' does neither."
         required: true
         default: build
         type: choice
-        options: [build, publish, skip]
+        options: [build, publish-unsigned, skip]
 
 permissions:
   contents: write # create the tag and the release
@@ -210,6 +210,34 @@ jobs:
             echo
             echo "Seeded rules start as \`candidate\` and trade nothing until you promote them."
             echo
+            if [ "${{ inputs.desktop }}" = "publish-unsigned" ]; then
+              echo "## Desktop app (macOS / Windows)"
+              echo
+              echo "⚠️ **These builds are not code-signed.** keel is open source on a small"
+              echo "budget, and Apple notarisation requires a paid Developer ID certificate."
+              echo "There is no free alternative: a self-signed certificate buys nothing, because"
+              echo "Gatekeeper trusts Apple-issued Developer IDs and nothing else."
+              echo
+              echo "**macOS** — the first open is refused. Open **System Settings → Privacy &"
+              echo "Security**, scroll to the message about \`keel\`, and choose **Open Anyway**."
+              echo "You will only do this once."
+              echo
+              echo "**Windows** — SmartScreen shows \"Windows protected your PC\". Choose **More"
+              echo "info → Run anyway**."
+              echo
+              echo "**Verify what you downloaded before you run it.** Every artifact carries a"
+              echo "GitHub build attestation binding it to this repository, this workflow and this"
+              echo "commit — which is the question a code-signing certificate answers too:"
+              echo
+              echo "    gh attestation verify <file> --repo ${{ github.repository }}"
+              echo
+              echo "\`SHA256SUMS.txt\` is attached as well. If either check fails, do not run it."
+              echo
+              echo "The app opens keel in your browser; there is no terminal involved. Your"
+              echo "config, database and credentials live in your user Application Support /"
+              echo "LocalAppData folder and are never touched by an update."
+              echo
+            fi
             echo "$GENERATED"
           } > /tmp/release-notes.md
           echo "composed $(wc -l < /tmp/release-notes.md) lines of notes"
@@ -228,17 +256,37 @@ jobs:
   #
   # Runs AFTER `release`, so the tag it checks out is the one that job created and published.
   #
-  # WHY IT DEFAULTS TO `build` AND NOT `publish`. An unsigned binary that then asks for exchange
-  # API keys is the shape of malware distribution -- section 1 of the desktop PRD opens on a live
-  # example found while surveying this space. For a project whose proposition is auditability,
-  # shipping that silhouette without OS-level verification would be worse than shipping no
-  # installer at all. So the pipeline is built so that publishing an unsigned artifact is not
-  # something you can do by forgetting a flag: `publish` FAILS when the signing secrets are
-  # absent, rather than quietly attaching an unsigned build to a release.
+  # THESE ARTIFACTS ARE NOT CODE-SIGNED, AND THAT IS A DECISION RATHER THAN AN OVERSIGHT.
+  #
+  # Apple notarisation requires a Developer ID certificate, which requires the $99/yr Developer
+  # Program. There is no free path: a free Apple account signs only for local development, and a
+  # self-signed certificate buys nothing because Gatekeeper trusts Apple-issued Developer IDs and
+  # nothing else. keel is open source on a small budget and has chosen not to pay it.
+  #
+  # What that costs the user is real and is documented rather than hidden: a `.dmg` downloaded
+  # from the internet carries a quarantine flag, so macOS refuses the first open until they go to
+  # System Settings -> Privacy & Security -> Open Anyway. Windows SmartScreen warns similarly.
+  #
+  # What replaces OS-level trust here is PROVENANCE, which is free and is arguably the more
+  # honest answer for an auditable project anyway: every artifact carries a GitHub build
+  # attestation tying it to this workflow, this repository and this commit, verifiable with
+  #
+  #     gh attestation verify <file> --repo CodeGateSoftware/keel
+  #
+  # plus a SHA256SUMS file in the release. That does not stop Gatekeeper -- nothing free does --
+  # but it does answer "did this binary come from that source", which a signature from a $99
+  # certificate answers no better.
+  #
+  # The publish option is spelled `publish-unsigned` deliberately: it cannot be selected without
+  # reading the word, and the default is `build`, which attaches nothing to a release.
   desktop:
     needs: release
     if: ${{ inputs.desktop != 'skip' }}
     timeout-minutes: 45
+    permissions:
+      contents: write # attach the artifacts to the release
+      id-token: write # OIDC token for the build attestation
+      attestations: write # write the attestation itself
     strategy:
       fail-fast: false
       matrix:
@@ -345,19 +393,24 @@ jobs:
           7z a -tzip "out/keel-${{ inputs.version }}-windows-${{ matrix.arch }}.zip" ./dist/keel/* >/dev/null
           ls -l out
 
-      # SIGNING GOES HERE. Deliberately absent rather than stubbed: a step that silently does
-      # nothing when a secret is missing is how an unsigned artifact ends up looking signed. The
-      # gate below fails the job instead, so the missing half is impossible to overlook.
-      #   macOS  -- Developer ID cert in an ephemeral keychain, `codesign --options runtime`,
-      #             `notarytool submit --wait`, `stapler staple`.
-      #   Windows -- Azure Trusted Signing or an OV cert, via a protected environment.
-      - name: Refuse to publish an unsigned artifact
-        if: inputs.desktop == 'publish'
+      # Checksums travel WITH the artifacts, in the same release, so a user who was handed a
+      # download link somewhere else has something local to compare against.
+      - name: Checksums
+        shell: bash
         run: |
-          echo "::error::'publish' was requested but no signing is configured in this workflow yet."
-          echo "::error::An unsigned binary that then asks for exchange API keys is the shape of"
-          echo "::error::malware distribution. Re-run with desktop=build, or wire signing first."
-          exit 1
+          set -euo pipefail
+          cd out
+          if command -v sha256sum >/dev/null; then sha256sum ./* > SHA256SUMS.txt
+          else shasum -a 256 ./* > SHA256SUMS.txt; fi
+          cat SHA256SUMS.txt
+
+      # The substitute for a code-signing certificate, and free. Ties each artifact to this
+      # workflow, this repository and this commit; a user verifies with
+      #   gh attestation verify <file> --repo ${{ github.repository }}
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: out/*
 
       - name: Upload the artifact
         uses: actions/upload-artifact@v4
@@ -365,3 +418,15 @@ jobs:
           name: keel-${{ inputs.version }}-${{ runner.os }}-${{ matrix.arch }}
           path: out/*
           if-no-files-found: error
+
+      - name: Attach to the release
+        if: inputs.desktop == 'publish-unsigned'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          # `--clobber` so a re-run of one matrix leg replaces its own asset rather than failing
+          # the whole publish on a name collision.
+          gh release upload "v${{ inputs.version }}" out/* --clobber
+          echo "attached $(ls out | wc -l) file(s) to v${{ inputs.version }}"
diff --git a/packaging/macos_app.sh b/packaging/macos_app.sh
index c309e6cf..e324d520 100755
--- a/packaging/macos_app.sh
+++ b/packaging/macos_app.sh
@@ -14,10 +14,18 @@
 # `keel.app/Contents/Resources/keel/keel <command>` and get the full CLI. One artifact, both
 # audiences, no second build.
 #
-# SIGNING IS NOT DONE HERE. This script produces an UNSIGNED bundle on purpose: signing needs an
-# Apple Developer ID certificate in a keychain, which exists only in the release workflow's
-# protected environment. Gatekeeper will refuse this output on another machine, and that is the
-# correct outcome for an artifact nobody signed.
+# THIS OUTPUT IS UNSIGNED, AND STAYS UNSIGNED. Apple notarisation requires a Developer ID
+# certificate, which requires the $99/yr Developer Program; a free Apple account signs only for
+# local development, and a self-signed certificate buys nothing because Gatekeeper trusts
+# Apple-issued Developer IDs and nothing else. keel is open source on a small budget and has
+# chosen not to pay it.
+#
+# So Gatekeeper WILL refuse the first open of a downloaded copy, and the release notes say so and
+# say what to do about it (System Settings -> Privacy & Security -> Open Anyway). What replaces
+# OS-level trust is provenance: the release workflow attaches a GitHub build attestation and a
+# SHA256SUMS file, which answer "did this come from that repository, built by that workflow" --
+# the same question a certificate answers, and the one an auditable project should care about
+# most.
 set -euo pipefail
 
 BUNDLE_DIR="${1:?usage: macos_app.sh <dist/keel> <out-dir> <version>}"
diff --git a/tests/test_desktop_packaging.py b/tests/test_desktop_packaging.py
index 58e3e9fd..4427e436 100644
--- a/tests/test_desktop_packaging.py
+++ b/tests/test_desktop_packaging.py
@@ -37,38 +37,71 @@ def _steps_text(job: dict) -> str:
 # -- the thing that must not happen ------------------------------------------------------------
 
 
-def test_publishing_an_unsigned_artifact_fails_rather_than_succeeding_quietly(
-    desktop_job: dict,
-) -> None:
-    """An unsigned binary that then asks for exchange API keys is the shape of malware
-    distribution -- the desktop PRD opens on a live example found while surveying this space.
+def test_the_publish_option_is_named_for_what_it_does(workflow: dict) -> None:
+    """These artifacts are not code-signed, by decision: Apple notarisation needs a paid
+    Developer ID and there is no free substitute -- a self-signed certificate buys nothing,
+    because Gatekeeper trusts Apple-issued IDs and nothing else.
+
+    Given that, the protection is that nobody can publish unsigned binaries without reading the
+    word "unsigned". `publish` would have been a value you could pick without thinking; this one
+    is not."""
+    desktop = workflow[True]["workflow_dispatch"]["inputs"]["desktop"]
+    assert set(desktop["options"]) == {"build", "publish-unsigned", "skip"}
+    assert "publish" not in desktop["options"]
+    assert "unsigned" in desktop["description"].lower()
 
-    So `publish` must FAIL while signing is unconfigured. A step that silently did nothing when a
-    secret was missing is exactly how an unsigned artifact ends up attached to a release looking
-    like a signed one."""
-    guards = [
+
+def test_the_default_attaches_nothing_to_a_release(workflow: dict, desktop_job: dict) -> None:
+    """The safe value is the one you get by not thinking about it."""
+    assert workflow[True]["workflow_dispatch"]["inputs"]["desktop"]["default"] == "build"
+    attaching = [
         step
         for step in desktop_job["steps"]
-        if str(step.get("if", "")).strip() == "inputs.desktop == 'publish'"
+        if "gh release upload" in str(step.get("run", ""))
+        or "gh release create" in str(step.get("run", ""))
     ]
-    assert guards, "nothing guards the publish path"
-    assert any("exit 1" in str(step.get("run", "")) for step in guards)
-
-
-def test_the_default_is_build_not_publish(workflow: dict) -> None:
-    """Publishing is opt-in. The safe value is the one you get by not thinking about it."""
-    desktop = workflow[True]["workflow_dispatch"]["inputs"]["desktop"]
-    assert desktop["default"] == "build"
-    assert set(desktop["options"]) == {"build", "publish", "skip"}
-
-
-def test_no_step_attaches_a_desktop_artifact_to_the_github_release(desktop_job: dict) -> None:
-    """The only route to a release asset is `gh release upload`/`create`. While signing is
-    unconfigured there must be no such call in this job at all -- the guard above is the
-    intended stop, and this is the one that catches a second route added around it."""
-    text = _steps_text(desktop_job)
-    assert "gh release upload" not in text
-    assert "gh release create" not in text
+    assert attaching, "nothing attaches artifacts, so this test proves nothing"
+    for step in attaching:
+        assert str(step.get("if", "")).strip() == "inputs.desktop == 'publish-unsigned'"
+
+
+def test_every_artifact_carries_provenance_and_checksums(desktop_job: dict) -> None:
+    """What replaces OS-level trust, and it is free. An attestation ties each artifact to this
+    repository, this workflow and this commit -- which is the question a code-signing certificate
+    answers too, and the one an auditable project should care about most."""
+    steps = desktop_job["steps"]
+    attest = [s for s in steps if "attest-build-provenance" in str(s.get("uses", ""))]
+    assert attest, "no build provenance attestation"
+    assert attest[0]["with"]["subject-path"] == "out/*"
+    assert "SHA256SUMS" in _steps_text(desktop_job)
+
+    # The attestation needs OIDC, and the job must ask for it explicitly rather than relying on
+    # a workflow-wide grant that would also widen the release job.
+    assert desktop_job["permissions"]["id-token"] == "write"
+    assert desktop_job["permissions"]["attestations"] == "write"
+
+
+def test_provenance_is_produced_before_anything_is_attached(desktop_job: dict) -> None:
+    """Attaching first would publish an artifact that is briefly unverifiable, and a failed
+    attestation afterwards would leave it published anyway."""
+    steps = desktop_job["steps"]
+    attest_at = next(
+        i for i, s in enumerate(steps) if "attest-build-provenance" in str(s.get("uses", ""))
+    )
+    attach_at = next(i for i, s in enumerate(steps) if "gh release upload" in str(s.get("run", "")))
+    assert attest_at < attach_at
+
+
+def test_the_release_notes_say_the_builds_are_unsigned_and_how_to_verify_them() -> None:
+    """A download that trips Gatekeeper with no explanation is indistinguishable from a broken
+    one, and a user who is told to click past a security warning with no way to check what they
+    have is being taught a bad habit while holding exchange API keys."""
+    text = _WORKFLOW.read_text(encoding="utf-8")
+    assert "not code-signed" in text
+    assert "Privacy & Security" in text
+    assert "Open Anyway" in text
+    assert "gh attestation verify" in text
+    assert "SHA256SUMS" in text
 
 
 def test_the_desktop_job_runs_after_the_release_and_builds_that_tag(desktop_job: dict) -> None:

From fb0b8e18523a4f5796141b6426c284a475c0419d Mon Sep 17 00:00:00 2001
From: Elmehdi Aitbrahim <eaitbrahim@gmail.com>
Date: Thu, 20 Aug 2026 16:39:04 -0400
Subject: [PATCH 3/3] docs(desktop): tell the person downloading it why their
 computer will warn them

The signing decision has been recorded for us (#438) and in the release notes. Neither reaches
the person actually staring at "keel cannot be opened because the developer cannot be verified".

Three places now do, in the order someone hits them:

**Inside the .dmg, beside the app.** `READ ME FIRST.txt` is where a Mac user looks the moment the
app refuses to open; a page in a repository is no use to them at that point. The disk image is
built from a staging directory rather than the .app alone, so the note is actually shipped
instead of merely written.

**`docs/desktop-install.md`**, linked from the README's documentation map and from the release
notes, in plain language for someone who has never opened a terminal.

**The release notes**, which now name the reason and link the full page rather than repeating it.

WHAT THEY SAY, AND WHY IN THOSE WORDS.

The reason is a budget, and saying so plainly is better than "not signed at this time". A user
told a build is unsigned with no reason assumes carelessness; a user told the certificate costs
$99/yr and the project cannot commit to it has been given a fact they can weigh. It is also
simply true.

It answers the obvious "why not just make your own certificate" -- because macOS trusts only
certificates Apple issued, so a self-signed one does nothing at all -- and the equally obvious
"is my download broken", because "damaged" is what macOS sometimes says and it is not what
happened. Leaving that uncorrected is how a working download gets deleted.

And it does not simply ask someone to click past a security warning on a program they may give
exchange API keys to. It gives them the check first: `gh attestation verify` and SHA256SUMS,
which answer the same question a certificate answers, and a plain instruction not to open the
file if either fails. The pip path is named too, for anyone who would rather avoid the whole
thing.

Every claim above is pinned by test, including that the note travels inside the image. Verified by
building the .dmg and mounting it: `keel.app` and `READ ME FIRST.txt`, as intended.

4038 passed, 3 skipped (6 new). ruff clean repo-wide.

Refs #438, #18.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/release.yml   | 11 +++--
 README.md                       |  4 ++
 docs/desktop-install.md         | 82 +++++++++++++++++++++++++++++++++
 packaging/macos_app.sh          | 60 +++++++++++++++++++++++-
 tests/test_desktop_packaging.py | 60 ++++++++++++++++++++++++
 5 files changed, 211 insertions(+), 6 deletions(-)
 create mode 100644 docs/desktop-install.md

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 9e5ac4b1..cbbf2b1f 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -213,10 +213,13 @@ jobs:
             if [ "${{ inputs.desktop }}" = "publish-unsigned" ]; then
               echo "## Desktop app (macOS / Windows)"
               echo
-              echo "⚠️ **These builds are not code-signed.** keel is open source on a small"
-              echo "budget, and Apple notarisation requires a paid Developer ID certificate."
-              echo "There is no free alternative: a self-signed certificate buys nothing, because"
-              echo "Gatekeeper trusts Apple-issued Developer IDs and nothing else."
+              echo "⚠️ **These builds are not code-signed, so your computer will warn you.**"
+              echo "Apple's certificate costs \$99/yr and keel cannot currently afford it. There"
+              echo "is no cheaper tier and no free option, and a certificate we made ourselves"
+              echo "would do nothing — macOS trusts only certificates Apple issued."
+              echo
+              echo "Full explanation, including how to check what you downloaded:"
+              echo "<https://github.com/${{ github.repository }}/blob/main/docs/desktop-install.md>"
               echo
               echo "**macOS** — the first open is refused. Open **System Settings → Privacy &"
               echo "Security**, scroll to the message about \`keel\`, and choose **Open Anyway**."
diff --git a/README.md b/README.md
index 0820d3d2..ff78cdbd 100644
--- a/README.md
+++ b/README.md
@@ -167,6 +167,10 @@ adapter, deliberately divergent, that the conformance suite runs against.
 - [`docs/launch.md`](docs/launch.md) — the pre-launch gate and the announcement plan:
   what must be true before anything is announced, where, in what order, and what the
   post says (the honest result included).
+- [`docs/desktop-install.md`](docs/desktop-install.md) — installing the macOS/Windows app,
+  and why your computer warns you about it: the builds are not code-signed, because Apple's
+  certificate costs $99/yr and keel cannot currently afford it. Says what to do, and how to
+  verify what you downloaded instead.
 - [`docs/RELEASING.md`](docs/RELEASING.md) — how a release is cut.
 
 ## Asking questions, and contributing
diff --git a/docs/desktop-install.md b/docs/desktop-install.md
new file mode 100644
index 00000000..c073e666
--- /dev/null
+++ b/docs/desktop-install.md
@@ -0,0 +1,82 @@
+# Installing the desktop app — and why your computer will warn you about it
+
+If you downloaded keel for macOS or Windows and your computer refused to open it, nothing is
+broken. This page explains exactly what happened, why, and what to do about it.
+
+## The short version
+
+**keel's desktop builds are not code-signed.** Code signing is a paid certificate from Apple or
+Microsoft that tells your operating system who built a program.
+
+**We cannot currently afford it.** Apple's certificate costs **$99 per year**, every year, and it
+is the only way to remove the warning — there is no cheaper tier, no free option for open-source
+projects, and a certificate we made ourselves would do nothing at all, because macOS only trusts
+certificates Apple issued. keel is an open-source project with essentially no budget, and that
+$99/yr is not something it can commit to today.
+
+So your computer sees a program from a developer it cannot identify, and it does the right thing:
+it stops and asks you.
+
+## What to do
+
+**macOS**
+
+1. Double-click keel. macOS refuses, saying it cannot verify the developer.
+2. Open **System Settings → Privacy & Security**.
+3. Scroll down. There is a message about keel being blocked, with an **Open Anyway** button.
+4. Click it, and confirm.
+
+You only do this once. keel opens normally afterwards.
+
+**Windows**
+
+1. Run the installer. SmartScreen says "Windows protected your PC".
+2. Click **More info**, then **Run anyway**.
+
+## Please check what you downloaded first
+
+We would rather not simply ask you to click past a security warning. That warning exists for a
+good reason, and keel is a program you may give exchange API keys to.
+
+So every keel release carries proof of where its files came from. This does not need the $99
+certificate, and it answers the same question a certificate answers: **was this file built from
+keel's own source, by keel's own release pipeline?**
+
+If you have [GitHub CLI](https://cli.github.com) installed:
+
+```
+gh attestation verify <the file you downloaded> --repo CodeGateSoftware/keel
+```
+
+A `SHA256SUMS.txt` file is attached to every release as well, if you prefer to compare checksums
+by hand.
+
+**If either check fails, do not open the file.** A failing check means the file is not the one we
+built, and no amount of clicking "Open Anyway" makes that safe.
+
+## What this does not mean
+
+- It does **not** mean the download is damaged.
+- It does **not** mean your computer found something wrong with keel. Nothing was scanned and
+  nothing was detected — your computer simply does not know who wrote it.
+- It does **not** mean the app behaves differently once open. A signed and an unsigned build of
+  the same release are the same program.
+
+## Would you rather avoid this entirely?
+
+Install keel the way developers do, from the release wheels, and no warning appears at all:
+
+```
+pip install --find-links . ./keel_trader-<version>-py3-none-any.whl
+keel versions
+```
+
+That path needs a terminal and a working Python. The desktop app exists precisely so that it does
+not have to be the only option.
+
+## If this changes
+
+If keel ever has the budget, signing is a small change on our side — the release pipeline is
+already built to accept it — and this page will be replaced by a sentence saying the builds are
+signed. Until then, we would rather tell you the truth about what you are downloading than say
+nothing and let your computer deliver the news.
diff --git a/packaging/macos_app.sh b/packaging/macos_app.sh
index e324d520..5bcd5278 100755
--- a/packaging/macos_app.sh
+++ b/packaging/macos_app.sh
@@ -82,8 +82,64 @@ chmod +x "$APP/Contents/MacOS/keel-launcher"
 
 echo "built $APP"
 
-# `hdiutil` with UDZO: compressed, read-only, and the format `notarytool` accepts for stapling.
+# The note goes INSIDE the disk image, beside the app. This is the one place a Mac user actually
+# looks at the moment the app refuses to open -- a page in the repository is no use to someone
+# staring at "keel cannot be opened because the developer cannot be verified".
+STAGE="$OUT_DIR/dmg-stage"
+rm -rf "$STAGE"
+mkdir -p "$STAGE"
+cp -R "$APP" "$STAGE/keel.app"
+cat > "$STAGE/READ ME FIRST.txt" <<NOTE
+keel $VERSION
+
+IF MACOS REFUSES TO OPEN THIS APP, NOTHING IS BROKEN.
+
+keel is not code-signed. Code signing is a paid certificate from Apple that tells macOS
+who built a program. It costs \$99 per year, there is no cheaper tier and no free option
+for open-source projects, and a certificate we made ourselves would do nothing at all --
+macOS trusts only certificates Apple issued.
+
+keel is an open-source project with essentially no budget, and that yearly cost is not
+something it can commit to today. So macOS sees a program from a developer it cannot
+identify, and does the right thing: it stops and asks you.
+
+TO OPEN IT
+
+  1. Drag keel.app to your Applications folder.
+  2. Double-click it. macOS refuses.
+  3. Open System Settings -> Privacy & Security.
+  4. Scroll down to the message about keel and click "Open Anyway".
+
+You only do this once.
+
+BEFORE YOU DO, PLEASE CHECK WHAT YOU DOWNLOADED
+
+We would rather not just ask you to click past a security warning -- keel is a program you
+may give exchange API keys to. Every release carries proof of where its files came from,
+which answers the same question a certificate does: was this built from keel's own source,
+by keel's own release pipeline?
+
+  gh attestation verify <the .dmg you downloaded> --repo CodeGateSoftware/keel
+
+A SHA256SUMS.txt file is attached to the release too. If either check fails, do not open
+this app.
+
+WHAT THIS DOES NOT MEAN
+
+  - It does not mean the download is damaged.
+  - It does not mean macOS found something wrong. Nothing was scanned and nothing was
+    detected; macOS simply does not know who wrote it.
+  - It does not mean the app behaves differently. A signed and an unsigned build of the
+    same release are the same program.
+
+Full explanation: https://github.com/CodeGateSoftware/keel/blob/main/docs/desktop-install.md
+
+keel is a personal tool. It is not financial advice and not religious (Shariah) advice.
+NOTE
+
+# `hdiutil` with UDZO: compressed and read-only.
 DMG="$OUT_DIR/keel-$VERSION-$(uname -m).dmg"
 rm -f "$DMG"
-hdiutil create -quiet -srcfolder "$APP" -volname "keel $VERSION" -format UDZO "$DMG"
+hdiutil create -quiet -srcfolder "$STAGE" -volname "keel $VERSION" -format UDZO "$DMG"
+rm -rf "$STAGE"
 echo "built $DMG"
diff --git a/tests/test_desktop_packaging.py b/tests/test_desktop_packaging.py
index 4427e436..218fcc81 100644
--- a/tests/test_desktop_packaging.py
+++ b/tests/test_desktop_packaging.py
@@ -195,3 +195,63 @@ def test_the_script_runs_no_signing_command() -> None:
     for command in ("codesign", "notarytool", "stapler", "productsign"):
         offenders = [line for line in code if command in line]
         assert not offenders, f"{command} is invoked: {offenders}"
+
+
+# -- what the person downloading it is told ----------------------------------------------------
+
+_INSTALL_DOC = _ROOT / "docs" / "desktop-install.md"
+
+
+def test_the_install_note_exists_and_states_the_actual_reason() -> None:
+    """The reason is a budget, and saying so is better than "not signed at this time".
+
+    A user who is told a build is unsigned with no reason assumes carelessness. A user who is
+    told the certificate costs $99/yr and the project cannot commit to it has been given a fact
+    they can weigh -- and it is the truth."""
+    text = _INSTALL_DOC.read_text(encoding="utf-8")
+    assert "$99" in text
+    assert "cannot currently afford" in text
+    assert "no cheaper tier" in text or "no free option" in text
+    # A self-signed certificate is the obvious "why not just..." and must be answered.
+    assert "made ourselves" in text or "self-signed" in text
+
+
+def test_the_install_note_tells_the_user_how_to_verify_before_bypassing() -> None:
+    """We are asking someone to click past a security warning on a program they may give exchange
+    API keys to. Asking that without offering a check would be the wrong trade."""
+    text = _INSTALL_DOC.read_text(encoding="utf-8")
+    assert "gh attestation verify" in text
+    assert "SHA256SUMS" in text
+    assert "do not open" in text.lower()
+
+
+def test_the_install_note_says_what_the_warning_does_not_mean() -> None:
+    """ "Damaged" is what macOS sometimes says, and it is not what happened. Leaving that
+    uncorrected is how a working download gets deleted."""
+    # Emphasis stripped: the doc bolds the "not", and a test that missed it because of two
+    # asterisks would be checking markdown rather than meaning.
+    text = _INSTALL_DOC.read_text(encoding="utf-8").lower().replace("*", "")
+    assert "does not mean the download is damaged" in text
+    assert "nothing was scanned" in text
+
+
+def test_the_readme_documentation_map_links_the_install_note() -> None:
+    text = (_ROOT / "README.md").read_text(encoding="utf-8")
+    assert "docs/desktop-install.md" in text
+
+
+def test_the_dmg_carries_the_note_beside_the_app() -> None:
+    """A page in the repository is no use to someone staring at "keel cannot be opened because
+    the developer cannot be verified". The disk image is where they are actually looking."""
+    text = _MACOS_SCRIPT.read_text(encoding="utf-8")
+    assert "READ ME FIRST.txt" in text
+    assert "$99" in text
+    # The image is built from a staging directory, not from the .app alone -- otherwise the note
+    # is written and then not shipped.
+    assert '-srcfolder "$STAGE"' in text
+
+
+def test_the_release_notes_point_at_the_full_explanation() -> None:
+    text = _WORKFLOW.read_text(encoding="utf-8")
+    assert "docs/desktop-install.md" in text
+    assert "cannot currently afford" in text