From 702aeb4ff4239bfc871859a0eadb8931201bbb13 Mon Sep 17 00:00:00 2001
From: Brandon Thomas <echelon@gmail.com>
Date: Tue, 6 Oct 2026 00:51:20 -0400
Subject: [PATCH] Release: FreeBSD artifact job, docs/releasing.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/release.yml | 41 ++++++++++++++++++++++++++++++++++-
 docs/releasing.md             | 26 ++++++++++++++++++++++
 2 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 docs/releasing.md

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 775f860..e472481 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -275,9 +275,48 @@ jobs:
           path: dist/release/*
           if-no-files-found: error
 
+  freebsd:
+    name: FreeBSD x86_64
+    needs: version
+    runs-on: ubuntu-latest
+    timeout-minutes: 300
+    env:
+      WORDCRAFT_VERSION: ${{ needs.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build in a FreeBSD VM
+        uses: vmactions/freebsd-vm@c46abacb49f09938ca4e1702d15d836285d694cc # v1
+        with:
+          release: "14.3"
+          usesh: true
+          cpu: 4
+          mem: 12288
+          envs: WORDCRAFT_VERSION
+          copyback: true
+          prepare: |
+            pkg install -y git curl pkgconf cmake python3 libxkbcommon wayland libX11 libXcursor libXrandr libXi libxcb mesa-libs vulkan-loader gtk3 fontconfig freetype2 alsa-lib
+            curl -fsSL https://sh.rustup.rs | sh -s -- -y --profile minimal
+          run: |
+            . "$HOME/.cargo/env"
+            git config --global --add safe.directory "*"
+            cargo run -q -p xtask -- version set "$WORDCRAFT_VERSION"
+            cargo build --release --locked -p wordcraft -p wordcraft-cli
+            name="wordcraft-$WORDCRAFT_VERSION-freebsd-x86_64"
+            mkdir -p "dist/release/$name"
+            cp target/release/wordcraft target/release/wordcraft-cli LICENSE-MIT LICENSE-APACHE NOTICE ATTRIBUTION.md README.md "dist/release/$name/"
+            cp packaging/linux/ai.storyteller.wordcraft.desktop "dist/release/$name/"
+            cp assets/app-icon/hicolor/256x256/apps/ai.storyteller.wordcraft.png "dist/release/$name/"
+            tar -C dist/release -czf "dist/release/$name.tar.gz" "$name"
+            rm -rf "dist/release/$name" target
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-freebsd
+          path: dist/release/*.tar.gz
+          if-no-files-found: error
+
   release:
     name: Draft GitHub Release
-    needs: [version, macos, windows, linux, web]
+    needs: [version, macos, windows, linux, web, freebsd]
     runs-on: ubuntu-latest
     environment: release
     permissions:
diff --git a/docs/releasing.md b/docs/releasing.md
new file mode 100644
index 0000000..07c6468
--- /dev/null
+++ b/docs/releasing.md
@@ -0,0 +1,26 @@
+# Releasing WordCraft
+
+The canonical recipe is [craftrules `release/playbook.md`](https://github.com/storytold/craftrules/blob/main/release/playbook.md);
+this file has the WordCraft specifics.
+
+1. Bump the version on `main`: `cargo xtask version set 0.2.0` (the one source of truth is
+   `[workspace.package] version`; the app shows it in `--version` and About, with the commit from
+   `WORDCRAFT_BUILD_SHA`).
+2. Merge `main` into `release` and push. `.github/workflows/release.yml` builds:
+
+| Platform | Artifacts | Signing |
+|---|---|---|
+| macOS | universal `WordCraft.app` in a `.dmg`, universal CLI zip | Developer ID + notarization (`APPLE_*` secrets) |
+| Windows | x64, x86 and arm64 `.msi` + portable `.zip` | Azure Trusted Signing (`AZURE_*` secrets) |
+| Linux | x86_64 and aarch64 `.AppImage`, `.deb`, `.rpm`, `.tar.gz`; Flatpak manifest | checksums |
+| FreeBSD | x86_64 `.tar.gz` | checksums |
+| Web | `wordcraft-web-<version>.zip` (static site: `index.html`, wasm, glue) | none |
+
+3. The run drafts a GitHub Release `WordCraft v<version>` with `SHA256SUMS.txt`; review and publish it.
+
+Signing secrets live in the repository's `release` environment (deployment branch: `release` only),
+synced from the release manager's machine (`craftrules/release/signing-setup.md`). Missing secrets
+produce unsigned builds with a warning, so forks still build.
+
+Local packaging: `packaging/macos/package.sh --arch universal`, `packaging/windows/package.ps1`,
+`packaging/linux/package.sh`, `packaging/web/package.sh`.