feat(install): why your computer will warn you about the download — and how to skip it

[eaitbrahim]

Companion to CodeGateSoftware/keel#463, which ships the first macOS/Windows builds unsigned.

The engine repo explains the unsigned builds in three places — the .dmg itself, docs/desktop-install.md, and the release notes. None of them is where someone actually decides to click Download. This is that place.

Shown only when there is something to warn about

Gated on macAsset || winAsset. The wheels are not signed either, but pip does not warn about them — a Gatekeeper explanation beside a wheels-only release would be a warning about nothing.

Verified in both states: absent on today's v0.10.0, present in all three locales once a .dmg and a .zip appear in the release data.

What it says, and why in those words

It names the cost. Apple's certificate is $99/yr, there is no cheaper tier and no free open-source tier, and a certificate we made ourselves would do nothing because macOS trusts only Apple-issued ones. A visitor told a build is unsigned with no reason assumes carelessness; a visitor told what it costs and that the project cannot commit to it has been given a fact they can weigh — and it happens to be true.

It refuses to end on "click Open Anyway." keel is a program a visitor may hand exchange API keys to, so gh attestation verify and SHA256SUMS are part of the note rather than a footnote to it, with a plain instruction not to open the file if either check fails.

It corrects what the warning is not. "Damaged" is what macOS sometimes says, and it is not what happened — nothing was scanned and nothing was detected. Leaving that uncorrected is how a working download gets deleted.

And it offers the way out, at the moment the decision is being made. The five-minute source path was already further down the page; the note now points at it and anchors straight to it. Honest about the trade rather than selling it: that path needs a terminal and Python 3.11+, which is precisely the friction the desktop app exists to remove — but if you already have both, it is the shorter road, and nothing is downloaded as an application so nothing warns.

Presentation

Notice palette, not an alarm one. The message is "your computer will stop you, here is why, here is how to check what you have" — a red box would say "something is wrong".

Verification

• astro check: 0 errors (77 files).
• Build clean, 41 pages.
• Rendered and inspected in en / fr / ar with bundles present; anchor target confirmed in all three.
• All three revs moved together, so no locale is left stale.

Links to docs/desktop-install.md in the engine repo rather than duplicating it, so the two cannot drift.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate failed

Failed conditions
57.6% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud