diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c2303891..cbbf2b1f 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 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-unsigned, skip]
 
 permissions:
   contents: write # create the tag and the release
@@ -204,6 +210,37 @@ 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, 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**."
+              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"
@@ -218,3 +255,181 @@ 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.
+  #
+  # 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:
+        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
+
+      # 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: |
+          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
+        with:
+          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/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
new file mode 100755
index 00000000..5bcd5278
--- /dev/null
+++ b/packaging/macos_app.sh
@@ -0,0 +1,145 @@
+#!/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.
+#
+# 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>}"
+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"
+
+# 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 "$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
new file mode 100644
index 00000000..218fcc81
--- /dev/null
+++ b/tests/test_desktop_packaging.py
@@ -0,0 +1,257 @@
+"""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_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()
+
+
+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 "gh release upload" in str(step.get("run", ""))
+        or "gh release create" in str(step.get("run", ""))
+    ]
+    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:
+    """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}"
+
+
+# -- 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