diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md
index acf0111..efb05f2 100644
--- a/docs/advanced-usage.md
+++ b/docs/advanced-usage.md
@@ -169,7 +169,7 @@ For repositories whose build scripts need a selected Rust toolchain inside Cross
`--stop-after` can stop at `inspect`, `metadata`, `verify`, `build`, `package`, `release`, `upload`, or `binstall`. `verify` runs host `cargo check` and `cargo test`; `--skip-tests` skips only tests. A successful Cross build from a clean checkout records its Git commit, package, targets, profile, lock mode, container engine, active Rust toolchain, and binary list. A later run with the same inputs reuses those regular binary files from Cargo's target directory; dirty checkouts, changed inputs, missing files, and invalid cache records build in a fresh target directory instead. `--recompile` explicitly bypasses a matching completed build. `release` creates or reuses the Gitea release; `upload` uploads archives and checksums. The final stage downloads assets anonymously for public repositories or with Gitea authentication for private repositories, checks their checksums and archive layout, and runs isolated `cargo-binstall` installs for public targets. `--skip-binstall-test` skips that install check, while retaining download verification.
-`--draft --stop-after upload` is useful when a release must stay private for review. Private repositories require `--skip-binstall-test`; cargo-binstall cannot fetch their attachment URLs, even when Gitea authentication is configured. `--prerelease` and `--draft` set properties when a release is created; reusing a release preserves its existing settings. `-m/--message TEXT` sets release notes, while `--message-file PATH` reads them from a UTF-8 file; they are mutually exclusive. Notes are included when creating a release and replace the body of an existing tagged release when explicitly supplied. Asset replacement is not transactional: if an upload fails after a matching asset is deleted, retry the publication explicitly.
+`--draft --stop-after upload` is useful when a release must stay private for review. Private repositories require `--skip-binstall-test`; cargo-binstall cannot fetch their attachment URLs, even when Gitea authentication is configured. `--prerelease` and `--draft` set properties when a release is created; reusing a release preserves its existing settings. `-m/--message TEXT` sets release notes, while `--message-file PATH` reads them from a UTF-8 file; they are mutually exclusive. Notes are included when creating a release and replace the body of an existing tagged release when explicitly supplied. Releases with macOS artifacts automatically append an artifact-specific quarantine-removal section unless the notes already contain a `## macOS Workaround` heading. Asset replacement is not transactional: if an upload fails after a matching asset is deleted, retry the publication explicitly.
## Artifact contract
@@ -182,7 +182,7 @@ my-tool-x86_64-unknown-linux-musl-v0.1.0.tgz
└── my-tool-helper
```
-Windows archive members have an `.exe` suffix. Raw assets are target-qualified to remain unambiguous, for example `my-tool-x86_64-unknown-linux-musl-v0.1.0` and `my-tool-x86_64-pc-windows-gnu-v0.1.0.exe`. `SHA256SUMS` lists every generated asset. Archive ownership and timestamps are normalized; identical binary bytes and modes produce identical archives. Separate builds can still produce different binaries.
+Windows archive members have an `.exe` suffix. Raw assets are target-qualified to remain unambiguous, for example `my-tool-x86_64-unknown-linux-musl-v0.1.0` and `my-tool-x86_64-pc-windows-gnu-v0.1.0.exe`. Apple raw assets omit the dotted version suffix, for example `my-tool-aarch64-apple-darwin`; use the versioned tgz archive by default. `SHA256SUMS` lists every generated asset. Archive ownership and timestamps are normalized; identical binary bytes and modes produce identical archives. Separate builds can still produce different binaries.
## Authentication and security
diff --git a/docs/automated-macos-releases.md b/docs/automated-macos-releases.md
index 907011a..ad2c5ea 100644
--- a/docs/automated-macos-releases.md
+++ b/docs/automated-macos-releases.md
@@ -166,14 +166,17 @@ a successful build or create/upload a partial release.
## Artifacts and target-aware verification
-Apple binary names have no `.exe` suffix. Existing archive and raw-binary
-naming applies unchanged. For version `{version}` and package `tiny-wb`:
+Apple binary names have no `.exe` suffix. Versioned tgz archives remain the
+recommended download because their internal executable names are ordinary Cargo
+binary names. Standalone Apple asset names omit the version so Finder does not
+mistake the final dotted version component for a file extension. For version
+`{version}` and package `tiny-wb`:
```text
tiny-wb-aarch64-apple-darwin-v{version}.tgz
-tiny-wb-aarch64-apple-darwin-v{version}
+tiny-wb-aarch64-apple-darwin
tiny-wb-x86_64-apple-darwin-v{version}.tgz
-tiny-wb-x86_64-apple-darwin-v{version}
+tiny-wb-x86_64-apple-darwin
```
Each tgz has the cargo-binstall layout:
@@ -190,6 +193,17 @@ All local archives are checked before any release creation. Existing remote
collision handling, replacement policy, upload, authenticated/private download
handling, and checksum verification apply to Apple assets too.
+When a release contains Apple artifacts, the publisher adds a
+`## macOS Workaround` section to the release body. It is generated from the
+artifacts being uploaded: named bundles are preferred, then canonical tgz
+archives, with standalone binaries used only when no archive exists. The shell
+snippet names the correct architecture, archive, extracted root, and executable
+members. It extracts into `~/Downloads`, applies
+`xattr -rd com.apple.quarantine` to the complete extracted tree, restores the
+executable bits, and starts a GUI executable when one has a `-gui` name. User
+notes supplied with `--message` or `--message-file` appear before this section.
+An existing `## macOS Workaround` heading prevents a duplicate section.
+
For every Apple executable, the Linux host parses the Mach-O header and load
commands and requires:
diff --git a/src/cli.rs b/src/cli.rs
index 61ab55f..97142f8 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -109,7 +109,7 @@ pub fn run(mut args: Cli) -> Result<(), Error> {
"--prepare-repo is a separate mode; omit --stop-after.".into(),
));
}
- let release_message = match args.message_file.as_deref() {
+ let supplied_release_message = match args.message_file.as_deref() {
Some(path) => Some(std::fs::read_to_string(path).map_err(|e| {
Error(format!(
"cannot read release message file {}: {e}",
@@ -444,12 +444,15 @@ pub fn run(mut args: Cli) -> Result<(), Error> {
}
let (api, private) =
publication.ok_or_else(|| Error("Publication client was not initialized.".into()))?;
+ let release_message =
+ release_message_with_macos_workaround(supplied_release_message.as_deref(), &artifacts)?;
let release = api.ensure_release(
&tag,
&commit,
args.draft,
args.prerelease,
release_message.as_deref(),
+ supplied_release_message.is_some(),
)?;
ui::success(format_args!("Release ready: {tag}"));
if args.stop_after == Some(Stage::Release) {
@@ -482,6 +485,145 @@ pub fn run(mut args: Cli) -> Result<(), Error> {
Ok(())
}
+fn release_message_with_macos_workaround(
+ supplied: Option<&str>,
+ artifacts: &[crate::package::Artifact],
+) -> Result