Release: Flatpak x86_64 + aarch64 bundles, AppImage zsync auto-update, README Downloads (#22)

- packaging/linux/package.sh: embed gh-releases-zsync update information in each AppImage (appimagetool -u) and write the .zsync beside it; the Linux job installs zsync and checks both. - New flatpak job (x86_64 on ubuntu-24.04, aarch64 on ubuntu-24.04-arm) repackages the Linux tarball with packaging/linux/flatpak-bundle.sh and ai.storyteller.wordcraft.bundle.yml; no Rust build, no release environment. The release job needs it. - version, Linux and web jobs drop `environment: release` (they sign nothing), so a branch workflow_dispatch dry-runs every unsigned job; the release job still needs the signed jobs. - FreeBSD release build embeds craft-fonts like the other desktop builds and ships its licences. - Flathub manifest: same finish-args as the bundle (adds xdg-documents), builds the CLI too; packaging-lint checks both manifests agree. - README: Downloads section; docs/releasing.md updated. Co-authored-by: Brandon Thomas <shared2@storyteller.ai> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 19:26:53 +00:00 · 2026-10-08 09:38:25 -04:00
1 parent 2ed3895276
commit b830fae017
@@ -54,4 +54,13 @@ jobs:
          desktop-file-validate packaging/linux/ai.storyteller.wordcraft.desktop
          sed -e 's/@VERSION@/0.0.0/' -e 's/@DATE@/2026-01-01/' packaging/linux/ai.storyteller.wordcraft.metainfo.xml.in >"$RUNNER_TEMP/ai.storyteller.wordcraft.metainfo.xml"
          appstreamcli validate --no-net --explain "$RUNNER_TEMP/ai.storyteller.wordcraft.metainfo.xml"
-          python3 -c "import yaml; m = yaml.safe_load(open('packaging/linux/flatpak/ai.storyteller.wordcraft.yml')); assert m['id'] == 'ai.storyteller.wordcraft' and m['command'] == 'wordcraft'"
+          python3 - <<'EOF'
+          import yaml
+          src = yaml.safe_load(open("packaging/linux/flatpak/ai.storyteller.wordcraft.yml"))
+          bundle = yaml.safe_load(open("packaging/linux/flatpak/ai.storyteller.wordcraft.bundle.yml"))
+          for m in (src, bundle):
+              assert m["id"] == "ai.storyteller.wordcraft" and m["command"] == "wordcraft", m["id"]
+          for key in ("runtime", "runtime-version", "sdk", "finish-args"):
+              assert src[key] == bundle[key], f"Flatpak manifests disagree on {key}: {src[key]} vs {bundle[key]}"
+          print("Flatpak manifests ok")
+          EOF
@@ -1,9 +1,12 @@
 # Release pipeline: every push to `release` builds signed installers for every platform and
 # creates or updates the draft GitHub Release "WordCraft v<version>". See docs/releasing.md.
 #
-# All jobs run in the `release` environment (restricted to the `release` branch), which holds
-# the signing secrets. Every secret is optional: missing ones produce unsigned artifacts and a
-# warning, never a failed build.
+# The signing jobs (macOS, Windows) and the job that drafts the release run in the `release`
+# environment (restricted to the `release` branch), which holds the signing secrets. Every secret
+# is optional: missing ones produce unsigned artifacts and a warning, never a failed build. The
+# jobs that sign nothing (version, Linux, Flatpak, FreeBSD, web) get no environment and no
+# secrets, so a `workflow_dispatch` on any branch dry-runs them; there the signing jobs are refused
+# by the environment's branch rule, and the release job, which needs them, is skipped.
 name: Release

 on:
@@ -35,7 +38,6 @@ jobs:
  version:
    name: version
    runs-on: ubuntu-latest
-    environment: release
    outputs:
      version: ${{ steps.v.outputs.version }}
      date: ${{ steps.v.outputs.date }}
@@ -175,7 +177,7 @@ jobs:
    # The oldest GitHub-hosted image, so the binaries only need glibc >= 2.35 (Ubuntu 22.04+,
    # Debian 12+, Fedora 36+, RHEL 10). See docs/releasing.md.
    runs-on: ${{ matrix.runner }}
-    environment: release
+    # No `environment: release`: this job signs nothing, so it gets no release secrets.
    strategy:
      fail-fast: false
      matrix:
@@ -200,7 +202,7 @@ jobs:
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            libxkbcommon-dev libwayland-dev libx11-dev libxrandr-dev libxi-dev libgl1-mesa-dev \
-            desktop-file-utils appstream python3-yaml
+            desktop-file-utils appstream python3-yaml zsync
          curl -fsSL -o "$RUNNER_TEMP/nfpm.deb" \
            "https://github.com/goreleaser/nfpm/releases/download/v${NFPM_VERSION}/nfpm_${NFPM_VERSION}_${{ matrix.deb }}.deb"
          sudo dpkg -i "$RUNNER_TEMP/nfpm.deb"
@@ -225,6 +227,9 @@ jobs:
          for appimage in dist/release/*.AppImage; do
            chmod +x "$appimage"
            APPIMAGE_EXTRACT_AND_RUN=1 "$appimage" --version
+            # Update information is embedded, and the .zsync for delta updates sits beside it.
+            "$appimage" --appimage-updateinformation | grep -F 'gh-releases-zsync|'
+            test -s "$appimage.zsync"
          done
      - uses: actions/upload-artifact@v4
        with:
@@ -232,11 +237,49 @@ jobs:
          path: dist/release/*
          if-no-files-found: error

+  flatpak:
+    name: Flatpak ${{ matrix.arch }}
+    needs: [version, linux]
+    # Repackages the Linux job's tarball (the same binaries as the AppImage/deb/rpm); no Rust
+    # build here. 24.04 for a newer flatpak-builder (1.4) than 22.04 ships.
+    runs-on: ${{ matrix.runner }}
+    # No `environment: release`: this job signs nothing, so it gets no release secrets.
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { arch: x86_64, runner: ubuntu-24.04 }
+          - { arch: aarch64, runner: ubuntu-24.04-arm }
+    env:
+      WORDCRAFT_VERSION: ${{ needs.version.outputs.version }}
+      WORDCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-linux-${{ matrix.arch }}
+          path: dist/linux
+      - name: Install flatpak-builder
+        run: |
+          sudo apt-get update
+          # librsvg2-common: the SVG pixbuf loader. flatpak-builder runs the host's
+          # `appstreamcli compose`, which renders the scalable icon and fails without it.
+          sudo apt-get install -y --no-install-recommends flatpak flatpak-builder librsvg2-common
+          # Ubuntu 24.04's AppArmor blocks the unprivileged user namespaces bubblewrap needs.
+          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+      - name: Build the Flatpak bundle
+        run: packaging/linux/flatpak-bundle.sh "dist/linux/wordcraft-$WORDCRAFT_VERSION-linux-${{ matrix.arch }}.tar.gz"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-flatpak-${{ matrix.arch }}
+          path: dist/release/*.flatpak
+          if-no-files-found: error
+
  web:
    name: Web (wasm)
    needs: version
    runs-on: ubuntu-latest
-    environment: release
+    # No `environment: release`: this job signs nothing, so it gets no release secrets.
    env:
      WORDCRAFT_VERSION: ${{ needs.version.outputs.version }}
      WORDCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
@@ -280,10 +323,20 @@ jobs:
    needs: version
    runs-on: ubuntu-latest
    timeout-minutes: 300
+    # No `environment: release`: this job signs nothing, so it gets no release secrets.
    env:
      WORDCRAFT_VERSION: ${{ needs.version.outputs.version }}
+      WORDCRAFT_BUILD_DATE: ${{ needs.version.outputs.date }}
    steps:
      - uses: actions/checkout@v4
+      # Optional font input (docs: storytold/craft-fonts docs/integration.md); releases always embed it.
+      # Synced into the VM with the sources.
+      - name: Check out craft-fonts
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          repository: storytold/craft-fonts
+          ref: abb83316d96aa59c1cf64784289e378fe9fa5695
+          path: craft-fonts
      - name: Build in a FreeBSD VM
        uses: vmactions/freebsd-vm@c46abacb49f09938ca4e1702d15d836285d694cc # v1
        with:
@@ -291,7 +344,7 @@ jobs:
          usesh: true
          cpu: 4
          mem: 12288
-          envs: WORDCRAFT_VERSION
+          envs: "WORDCRAFT_VERSION WORDCRAFT_BUILD_DATE WORDCRAFT_BUILD_SHA"
          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
@@ -300,12 +353,14 @@ jobs:
            . "$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
+            CRAFT_FONTS_DIR="$PWD/craft-fonts" CRAFT_FONTS_REQUIRED=1 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/"
+            # The embedded craft-fonts' licences, as in the Linux packages (OFL-<family>.txt).
+            for f in craft-fonts/fonts/*/OFL.txt; do cp "$f" "dist/release/$name/OFL-$(basename "$(dirname "$f")").txt"; done
            tar -C dist/release -czf "dist/release/$name.tar.gz" "$name"
            rm -rf "dist/release/$name" target
      - uses: actions/upload-artifact@v4
@@ -316,7 +371,8 @@ jobs:

  release:
    name: Draft GitHub Release
-    needs: [version, macos, windows, linux, web, freebsd]
+    # Needs the signing jobs, which only run on `release`: a branch dry run never gets here.
+    needs: [version, macos, windows, linux, flatpak, freebsd, web]
    runs-on: ubuntu-latest
    environment: release
    permissions:
@@ -57,6 +57,7 @@
  <a href="#for-agents-cli-and-mcp">For agents</a> ·
  <a href="#architecture">Architecture</a> ·
  <a href="#roadmap">Roadmap</a> ·
+  <a href="#downloads">Downloads</a> ·
  <a href="#the-crafting-apps">The Crafting Apps</a> ·
  <a href="#license-and-credits">License and credits</a>
 </p>
@@ -183,6 +184,50 @@ the remaining work is mostly testing against real-world .docx files, native prin
 first signed builds. Charts, SmartArt, the equation editor and the Draw tab come after.
 Details and estimates: [ROADMAP.md](ROADMAP.md).

+## Downloads
+
+Every [release](https://github.com/storytold/wordcraft/releases/latest) ships these builds. `<ver>` is the
+version number; `SHA256SUMS.txt` lists a checksum for every file.
+
+### macOS
+
+| Build | File | Notes |
+|---|---|---|
+| App, universal (Apple silicon + Intel) | `wordcraft-<ver>-macos-universal.dmg` | Signed and notarized |
+| Command-line tool, universal | `wordcraft-cli-<ver>-macos-universal.zip` | Signed and notarized |
+
+### Windows
+
+| Build | Installer | Portable |
+|---|---|---|
+| x64 (64-bit Intel/AMD) | `wordcraft-<ver>-windows-x64.msi` | `wordcraft-<ver>-windows-x64-portable.zip` |
+| arm64 (Snapdragon and other ARM PCs) | `wordcraft-<ver>-windows-arm64.msi` | `wordcraft-<ver>-windows-arm64-portable.zip` |
+| x86 (32-bit) | `wordcraft-<ver>-windows-x86.msi` | `wordcraft-<ver>-windows-x86-portable.zip` |
+
+Installers and executables are code-signed.
+
+### Linux
+
+| Format | x86_64 | aarch64 (ARM64) | Notes |
+|---|---|---|---|
+| AppImage | `wordcraft-<ver>-linux-x86_64.AppImage` | `wordcraft-<ver>-linux-aarch64.AppImage` | Runs anywhere; updates itself with [AppImageUpdate](https://github.com/AppImageCommunity/AppImageUpdate) (`.zsync` files) |
+| Flatpak | `wordcraft-<ver>-linux-x86_64.flatpak` | `wordcraft-<ver>-linux-aarch64.flatpak` | Sandboxed; `flatpak install --user <file>` |
+| Debian/Ubuntu | `wordcraft-<ver>-linux-x86_64.deb` | `wordcraft-<ver>-linux-aarch64.deb` | |
+| Fedora/RHEL/openSUSE | `wordcraft-<ver>-linux-x86_64.rpm` | `wordcraft-<ver>-linux-aarch64.rpm` | |
+| Tarball | `wordcraft-<ver>-linux-x86_64.tar.gz` | `wordcraft-<ver>-linux-aarch64.tar.gz` | Unpack anywhere |
+
+### FreeBSD
+
+| Build | File |
+|---|---|
+| x86_64 | `wordcraft-<ver>-freebsd-x86_64.tar.gz` |
+
+### Web (WebAssembly)
+
+| Build | File | Notes |
+|---|---|---|
+| Static site | `wordcraft-web-<ver>.zip` | Runs in a modern browser; host it on any static server |
+
 ## The Crafting Apps

 WordCraft is one of the **Crafting Apps**: free, open-source creative tools from the
@@ -12,7 +12,7 @@ this file has the WordCraft specifics.
 |---|---|---|
 | 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 |
+| Linux | x86_64 and aarch64 `.AppImage` (+ `.zsync` for AppImageUpdate), `.flatpak` bundle, `.deb`, `.rpm`, `.tar.gz`; Flathub manifest | checksums |
 | FreeBSD | x86_64 `.tar.gz` | checksums |
 | Web | `wordcraft-web-<version>.zip` (static site: `index.html`, wasm, glue) | none |

@@ -23,4 +23,8 @@ synced from the release manager's machine (`craftrules/release/signing-setup.md`
 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`.
+`packaging/linux/package.sh` (then `packaging/linux/flatpak-bundle.sh` for the Flatpak), `packaging/web/package.sh`.
+
+Dry run: `gh workflow run release.yml --ref <branch>` builds the unsigned jobs (version, Linux,
+Flatpak, FreeBSD, web) on any branch; the signing jobs are refused there by the `release`
+environment's branch rule, so no draft release is made.
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Repackage a WordCraft Linux tarball as a single-file Flatpak bundle:
+#
+#   $DIST/wordcraft-<version>-linux-<arch>.flatpak
+#
+# Usage: packaging/linux/flatpak-bundle.sh [--no-test] [TARBALL]
+#
+# TARBALL defaults to $DIST/wordcraft-<version>-linux-<arch>.tar.gz from package.sh. The bundle
+# is built for the host architecture (x86_64 or aarch64), which must match the tarball's.
+# Needs flatpak, flatpak-builder and the SVG pixbuf loader (librsvg2-common) for the host's
+# `appstreamcli compose`; the freedesktop runtime and SDK named in the manifest are
+# installed per-user from Flathub. Unless --no-test, the bundle is then installed per-user and
+# `wordcraft-cli --version` is run inside the sandbox as a smoke test.
+# Manifest: packaging/linux/flatpak/ai.storyteller.wordcraft.bundle.yml.
+set -euo pipefail
+# shellcheck source=../env.sh
+. "$(dirname "${BASH_SOURCE[0]}")/../env.sh"
+HERE="$ROOT/packaging/linux"
+APP_ID=ai.storyteller.wordcraft
+FLATHUB=https://dl.flathub.org/repo/flathub.flatpakrepo
+
+TEST=1
+TARBALL=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --no-test) TEST=0; shift ;;
+    -h | --help) sed -n '2,14p' "$0"; exit 0 ;;
+    -*) echo "unknown argument: $1" >&2; exit 2 ;;
+    *) TARBALL="$1"; shift ;;
+  esac
+done
+
+ARCH="$(uname -m)"
+case "$ARCH" in
+  x86_64) ;;
+  aarch64 | arm64) ARCH=aarch64 ;;
+  *) echo "unsupported architecture $ARCH" >&2; exit 2 ;;
+esac
+BASENAME="wordcraft-$VERSION-linux-$ARCH"
+TARBALL="${TARBALL:-$DIST/$BASENAME.tar.gz}"
+[ -f "$TARBALL" ] || { echo "error: $TARBALL not found (run packaging/linux/package.sh --formats tar first)" >&2; exit 1; }
+for tool in flatpak flatpak-builder; do
+  command -v "$tool" >/dev/null || { echo "error: $tool not found (apt install flatpak flatpak-builder librsvg2-common)" >&2; exit 1; }
+done
+
+echo "==> WordCraft $VERSION Flatpak bundle for $ARCH from $(basename "$TARBALL")"
+
+WORK="$CARGO_TARGET_DIR/flatpak-bundle"
+rm -rf "$WORK"
+mkdir -p "$WORK/stage"
+tar -xzf "$TARBALL" -C "$WORK/stage" --strip-components=1
+[ -x "$WORK/stage/bin/wordcraft" ] || { echo "error: $TARBALL has no bin/wordcraft" >&2; exit 1; }
+cp "$HERE/flatpak/$APP_ID.bundle.yml" "$WORK/$APP_ID.yml"
+
+flatpak remote-add --user --if-not-exists flathub "$FLATHUB"
+# --disable-rofiles-fuse: no FUSE in containers and CI runners.
+flatpak-builder --user --install-deps-from=flathub --disable-rofiles-fuse --force-clean \
+  --default-branch=stable --repo="$WORK/repo" --state-dir="$WORK/state" "$WORK/build" "$WORK/$APP_ID.yml"
+
+OUT="$DIST/$BASENAME.flatpak"
+# --runtime-repo lets `flatpak install` fetch the freedesktop runtime from Flathub if missing.
+flatpak build-bundle --runtime-repo="$FLATHUB" "$WORK/repo" "$OUT" "$APP_ID" stable
+echo "wrote $OUT"
+
+if [ "$TEST" = 1 ]; then
+  flatpak install --user -y --noninteractive --reinstall "$OUT"
+  flatpak info --user "$APP_ID"
+  flatpak run --command=wordcraft-cli "$APP_ID" --version
+  flatpak run --command=sh "$APP_ID" -c 'ls /app/share/applications /app/share/metainfo /app/share/mime/packages /app/share/icons/hicolor/scalable/apps'
+fi
+echo "==> done"
+ls -lh "$OUT"
@@ -0,0 +1,50 @@
+# Flatpak manifest for the single-file bundle attached to every GitHub release
+# (wordcraft-<version>-linux-<arch>.flatpak). Build it with packaging/linux/flatpak-bundle.sh.
+#
+# It repackages the release's own Linux tarball (wordcraft-<version>-linux-<arch>.tar.gz,
+# built on Ubuntu 22.04 by package.sh) instead of compiling Rust inside flatpak-builder: no
+# network and no vendored crate sources during the build, a few seconds instead of 20+ minutes,
+# and byte-for-byte the same binaries as the AppImage/deb/rpm. The script unpacks the tarball
+# into `stage/` next to a copy of this file. The binaries need glibc >= 2.35 and load X11,
+# Wayland, xkbcommon and Vulkan at runtime; the freedesktop runtime has all of them, and the
+# GPU driver comes from its org.freedesktop.Platform.GL extension.
+#
+# ai.storyteller.wordcraft.yml (same directory) is the from-source manifest for Flathub. Keep
+# runtime, runtime-version, sdk and finish-args identical in both (packaging-lint checks this).
+id: ai.storyteller.wordcraft
+runtime: org.freedesktop.Platform
+runtime-version: '25.08'
+sdk: org.freedesktop.Sdk
+command: wordcraft
+finish-args:
+  # Display: Wayland first; X11 only when no Wayland compositor is running.
+  - --socket=wayland
+  - --socket=fallback-x11
+  # X11 shared memory (MIT-SHM). Without it the X11 fallback is slow or fails.
+  - --share=ipc
+  # GPU access for the wgpu renderer (Vulkan, or GL as a fallback).
+  - --device=dri
+  # Open/Save dialogs go through the file-chooser portal (rfd's xdg-portal backend) and
+  # drag-and-drop through the document portal, so picked files work anywhere without broad
+  # filesystem access. Documents and Pictures are granted so files passed by path (the command
+  # line, Open Recent, "Save" next to the original) work in the usual places.
+  - --filesystem=xdg-documents
+  - --filesystem=xdg-pictures
+  # Deliberately not granted: network (the optional --control server listens on 127.0.0.1 in
+  # the sandbox; `flatpak override --user --share=network ai.storyteller.wordcraft` exposes it to
+  # host agents) and home/host filesystem access.
+modules:
+  - name: wordcraft
+    buildsystem: simple
+    build-commands:
+      - install -Dm755 bin/wordcraft /app/bin/wordcraft
+      - install -Dm755 bin/wordcraft-cli /app/bin/wordcraft-cli
+      - install -Dm644 share/applications/ai.storyteller.wordcraft.desktop /app/share/applications/ai.storyteller.wordcraft.desktop
+      - install -Dm644 share/mime/packages/ai.storyteller.wordcraft.xml /app/share/mime/packages/ai.storyteller.wordcraft.xml
+      # Already has the release's version and date substituted by package.sh.
+      - install -Dm644 share/metainfo/ai.storyteller.wordcraft.metainfo.xml /app/share/metainfo/ai.storyteller.wordcraft.metainfo.xml
+      # Docs include the licences of the embedded craft-fonts (OFL-*.txt).
+      - mkdir -p /app/share/icons /app/share/doc && cp -R share/icons/hicolor /app/share/icons/ && cp -R share/doc/wordcraft /app/share/doc/
+    sources:
+      - type: dir
+        path: stage
@@ -8,6 +8,8 @@
 #   flatpak run ai.storyteller.wordcraft
 #
 # For Flathub, replace the `dir` source with a `git` source pinned to a release tag and commit.
+# The release's .flatpak bundles come from ai.storyteller.wordcraft.bundle.yml instead (see there);
+# keep runtime, runtime-version, sdk and finish-args identical in both (packaging-lint checks this).
 id: ai.storyteller.wordcraft
 runtime: org.freedesktop.Platform
 runtime-version: '25.08'
@@ -16,14 +18,22 @@ sdk-extensions:
  - org.freedesktop.Sdk.Extension.rust-stable
 command: wordcraft
 finish-args:
-  - --share=ipc
+  # Display: Wayland first; X11 only when no Wayland compositor is running.
  - --socket=wayland
  - --socket=fallback-x11
+  # X11 shared memory (MIT-SHM). Without it the X11 fallback is slow or fails.
+  - --share=ipc
+  # GPU access for the wgpu renderer (Vulkan, or GL as a fallback).
  - --device=dri
-  # Open/Save dialogs use the file-chooser portal (rfd), and drag-and-drop uses the document
-  # portal, so broad filesystem access isn't needed. Pictures is granted for opening files by
-  # path from the command line.
+  # Open/Save dialogs go through the file-chooser portal (rfd's xdg-portal backend) and
+  # drag-and-drop through the document portal, so picked files work anywhere without broad
+  # filesystem access. Documents and Pictures are granted so files passed by path (the command
+  # line, Open Recent, "Save" next to the original) work in the usual places.
+  - --filesystem=xdg-documents
  - --filesystem=xdg-pictures
+  # Deliberately not granted: network (the optional --control server listens on 127.0.0.1 in
+  # the sandbox; `flatpak override --user --share=network ai.storyteller.wordcraft` exposes it to
+  # host agents) and home/host filesystem access.
 build-options:
  append-path: /usr/lib/sdk/rust-stable/bin
 modules:
@@ -34,8 +44,9 @@ modules:
        CARGO_HOME: /run/build/wordcraft/cargo
        CARGO_NET_OFFLINE: 'true'
    build-commands:
-      - cargo --offline build --release --locked -p wordcraft
+      - cargo --offline build --release --locked -p wordcraft -p wordcraft-cli
      - install -Dm755 target/release/wordcraft /app/bin/wordcraft
+      - install -Dm755 target/release/wordcraft-cli /app/bin/wordcraft-cli
      - install -Dm644 packaging/linux/ai.storyteller.wordcraft.desktop /app/share/applications/ai.storyteller.wordcraft.desktop
      - install -Dm644 packaging/linux/ai.storyteller.wordcraft.mime.xml /app/share/mime/packages/ai.storyteller.wordcraft.xml
      - mkdir -p /app/share/icons && cp -R assets/app-icon/hicolor /app/share/icons/
@@ -2,6 +2,7 @@
 # Build and package WordCraft for Linux (<arch> is x86_64 or aarch64):
 #
 #   $DIST/wordcraft-<version>-linux-<arch>.AppImage  any distro with glibc >= the build host's
+#   $DIST/wordcraft-<version>-linux-<arch>.AppImage.zsync  delta updates (needs zsyncmake)
 #   $DIST/wordcraft-<version>-linux-<arch>.deb       Debian, Ubuntu, Mint, Pop!_OS, ...
 #   $DIST/wordcraft-<version>-linux-<arch>.rpm       Fedora, openSUSE, RHEL, ...
 #   $DIST/wordcraft-<version>-linux-<arch>.tar.gz    plain FHS-style tree (bin/, share/)
@@ -10,7 +11,8 @@
 #
 # Needs: cargo; nfpm for deb/rpm (https://nfpm.goreleaser.com); appimagetool for the AppImage
 # (downloaded into $CARGO_TARGET_DIR if missing). Build on an old distro (CI: Ubuntu 22.04,
-# glibc 2.35) so the binaries run on newer ones. Optional: desktop-file-validate, appstreamcli.
+# glibc 2.35) so the binaries run on newer ones. Optional: desktop-file-validate, appstreamcli,
+# zsyncmake (the zsync package) for the AppImage's .zsync.
 set -euo pipefail
 # shellcheck source=../env.sh
 . "$(dirname "${BASH_SOURCE[0]}")/../env.sh"
@@ -108,11 +110,29 @@ if has appimage; then
      chmod +x "$TOOL"
    fi
  fi
-  OUT="$DIST/$BASENAME.AppImage"
+  # Absolute, because appimagetool runs in $DIST below (CARGO_TARGET_DIR or APPIMAGETOOL may be
+  # relative, e.g. target/agent-<name>).
+  OUT="$(cd "$DIST" && pwd)/$BASENAME.AppImage"
+  APPDIR="$(cd "$APPDIR" && pwd)"
+  TOOL="$(cd "$(dirname "$TOOL")" && pwd)/$(basename "$TOOL")"
+  # A .zsync left by an earlier run would hide a missing zsyncmake and describe another file.
+  rm -f "$OUT.zsync"
+  # Update information: AppImageUpdate, AppImageLauncher and the like read it from the file and
+  # fetch only the blocks that changed in a newer release, through the .zsync published next to
+  # each AppImage on GitHub Releases. `latest` is the newest published release that is not a
+  # pre-release. A fork's builds point at its own releases through GITHUB_REPOSITORY.
+  REPO="${GITHUB_REPOSITORY:-storytold/wordcraft}"
+  UPDATE_INFO="gh-releases-zsync|${REPO%%/*}|${REPO#*/}|latest|wordcraft-*-linux-$ARCH.AppImage.zsync"
  # Extract-and-run: works without FUSE (containers, CI). The output embeds the static runtime,
-  # so users don't need libfuse2 either.
-  ARCH="$ARCH" APPIMAGE_EXTRACT_AND_RUN=1 "$TOOL" --no-appstream "$APPDIR" "$OUT"
+  # so users don't need libfuse2 either. With zsyncmake on the host (CI installs the zsync
+  # package) appimagetool also writes the .zsync, into its working directory, hence the cd.
+  (cd "$DIST" && ARCH="$ARCH" APPIMAGE_EXTRACT_AND_RUN=1 "$TOOL" --no-appstream -u "$UPDATE_INFO" "$APPDIR" "$OUT")
  echo "wrote $OUT"
+  if [ -s "$OUT.zsync" ]; then
+    echo "wrote $OUT.zsync"
+  else
+    warn "zsyncmake not found, so $OUT.zsync was not written; AppImage delta updates need it"
+  fi
 fi

 "$STAGE/usr/bin/wordcraft-cli" --version