Enforce LF line endings for Unix artifacts via .gitattributes

A shell script, .desktop, .rules, or .spec file checked out with CRLF (Windows
with core.autocrlf=true) breaks when run/parsed on Linux — a
`#!/usr/bin/env bash\r` shebang is a "bad interpreter" error, and the Linux
package would ship broken scripts. Pin these (and other text) to LF, and mark
binary assets (png/gz/traineddata) so they are never converted. Also harden
the packaging/wayland structural tests to strip CR defensively.

Co-Authored-By: Claude Fable 5 <[email protected]>

.gitattributes

@@ -0,0 +1,24 @@
+# Normalize line endings. Unix artifacts MUST stay LF: a shell script or
+# desktop/udev/spec file checked out with CRLF (e.g. on Windows with
+# core.autocrlf=true) fails to run on Linux — `#!/usr/bin/env bash\r` is a
+# "bad interpreter" error, and .desktop/.rules parsers choke on trailing \r.
+* text=auto eol=lf
+
+*.sh          text eol=lf
+*.desktop     text eol=lf
+*.rules       text eol=lf
+*.spec        text eol=lf
+*.xml         text eol=lf
+control.in    text eol=lf
+*.js          text eol=lf
+*.mjs         text eol=lf
+*.cjs         text eol=lf
+*.json        text eol=lf
+*.md          text eol=lf
+launcher.sh   text eol=lf
+
+# Binary assets must never be line-ending converted.
+*.png         binary
+*.ico         binary
+*.gz          binary
+*.traineddata binary

app/main.js

@@ -900,8 +900,14 @@ function setupIpc() {
     platform: process.platform,
   }));
   // Platform capture-capability profile (session type, portal/PipeWire,
-  // xinput, click source, actionable messages) for the diagnostics UI.
-  h('platform:capabilities', () => require('./platform').detectCapabilities());
+  // xinput, click source, actionable messages) for the diagnostics UI, plus
+  // the honest active trigger for this machine and settings.
+  h('platform:capabilities', () => {
+    const platform = require('./platform');
+    const caps = platform.detectCapabilities();
+    const activeTrigger = platform.chooseCaptureTrigger(caps, settings.get('capture.fallbackTrigger') || 'interval');
+    return { ...caps, activeTrigger };
+  });
 }
 
 // ---- lifecycle --------------------------------------------------------------

app/platform/index.js

@@ -63,4 +63,19 @@ function detectCapabilities({ platform = process.platform, env = process.env } =
   };
 }
 
-module.exports = { detectPlatform, createWindowContextProvider, detectCapabilities };
+/**
+ * The honest capture-trigger decision for the current capabilities. On Linux
+ * this defers to the diagnostics helper (which never promises per-click
+ * capture with coordinates on Wayland); other platforms have a fixed answer.
+ */
+function chooseCaptureTrigger(capabilities, userTriggerPreference = 'interval') {
+  if (capabilities && capabilities.os === 'linux') {
+    return require('./linux/diagnostics').chooseCaptureTrigger(capabilities, userTriggerPreference);
+  }
+  if (capabilities && capabilities.os === 'windows') {
+    return { trigger: 'click', clickSource: 'windows-hook', coordinates: true, marker: true, note: '' };
+  }
+  return { trigger: 'click', clickSource: capabilities ? capabilities.os : 'unavailable', coordinates: true, marker: true, note: '' };
+}
+
+module.exports = { detectPlatform, createWindowContextProvider, detectCapabilities, chooseCaptureTrigger };

app/platform/linux/diagnostics.js

@@ -96,4 +96,61 @@ function detectLinuxCapabilities({
   };
 }
 
-module.exports = { detectLinuxCapabilities, detectSessionType };
+/**
+ * Decide the honest capture trigger for a Linux capability profile. StepForge
+ * must never *promise* per-click capture with coordinates on Wayland, because
+ * the platform does not expose pointer position to apps. Returns the trigger,
+ * whether clicks carry coordinates, whether a marker can be drawn, and a
+ * user-facing note. `userTriggerPreference` is the capture.fallbackTrigger
+ * setting ('interval' | 'hotkey') used only when no click source exists.
+ */
+function chooseCaptureTrigger(capabilities, userTriggerPreference = 'interval') {
+  const caps = capabilities || {};
+  const click = caps.clickCapture;
+
+  if (click === 'x11-xinput') {
+    return {
+      trigger: 'click',
+      clickSource: 'x11',
+      coordinates: true,
+      marker: true,
+      note: 'Per-click capture with an accurate marker (X11 + xinput).',
+    };
+  }
+  if (click === 'evdev-x11') {
+    return {
+      trigger: 'click',
+      clickSource: 'evdev-x11',
+      coordinates: true,
+      marker: true,
+      note: 'Per-click capture via kernel input devices (X11, no xinput).',
+    };
+  }
+  if (click === 'evdev-wayland') {
+    // Wayland exposes button presses (via evdev, if permitted) but NOT pointer
+    // position, so a step is captured per click but without a marker. This is
+    // only reached when the user opted into the least-privilege device rule.
+    return {
+      trigger: 'click',
+      clickSource: 'evdev-wayland',
+      coordinates: false,
+      marker: false,
+      note: 'Per-click capture on Wayland has no pointer position, so no marker is drawn.',
+    };
+  }
+
+  // No global click source: the safe baseline is the user's chosen fallback.
+  const trigger = userTriggerPreference === 'hotkey' ? 'hotkey' : 'interval';
+  return {
+    trigger,
+    clickSource: trigger,
+    coordinates: false,
+    marker: false,
+    note: caps.isWayland
+      ? 'Wayland does not expose global clicks; recording uses your ' + trigger + ' trigger. '
+        + 'Screen sharing is requested once per recording via the portal.'
+      : 'No global click source available; recording uses your ' + trigger + ' trigger.',
+  };
+}
+
+module.exports = { detectLinuxCapabilities, detectSessionType, chooseCaptureTrigger };

docs/GETTING_STARTED_WITH_LINUX.md

@@ -13,10 +13,11 @@ difference, how to get the best experience, and how to enable per-click capture.
 
 | | **X11 / "Ubuntu on Xorg"** | **Wayland (default on Ubuntu)** |
 |---|---|---|
-| Screenshot per click | ✅ Yes | ✅ Yes (needs `input` group) |
+| Screenshot per click | ✅ Yes | ⚙️ Optional (least-privilege mouse rule) |
 | Red circle on the click | ✅ Yes | ❌ No (Wayland hides the cursor position) |
 | "Share your screen" prompt | Never | Once per recording session |
-| Setup needed | None | Add yourself to the `input` group |
+| Default trigger | Per click | Global hotkey or timed interval |
+| Setup needed | None | None (per-click is opt-in, mice only) |
 
 **If you want the full Windows-like experience (click capture *with* the red
 marker), use an Xorg session — see [Option A](#option-a-best-experience--use-xorg).**
@@ -67,27 +68,30 @@ stream stays open until you stop recording.
 > If you never see steps appear, make sure you actually picked a screen and
 > clicked **Share** in that dialog.
 
-### Per-click capture (requires the `input` group)
+### Per-click capture (optional, least-privilege)
 
-By default on Wayland, StepForge cannot see your clicks, so it falls back to
-**capturing a screenshot every few seconds** (timed capture).
+By default on Wayland, StepForge cannot see your clicks, so it uses a **global
+hotkey or a timed interval** to capture (see below). This is the recommended,
+no-extra-permissions path.
 
-To get a screenshot **on every click** instead, give your user read access to
-the mouse devices by joining the `input` group:
+If you want a screenshot **on every click**, you can grant StepForge read
+access to your **mouse** devices. Do **not** use `sudo usermod -aG input`:
+joining the `input` group grants your user access to *all* input devices —
+**including keyboards** — permanently, on every session. That is a keylogging
+surface StepForge does not need.
+
+Instead, install the least-privilege udev rule, which grants your active
+session read access to **mouse devices only** (never keyboards), scoped to
+whoever is physically logged in:
 
 ```bash
-sudo usermod -aG input "$USER"
+bash scripts/linux/enable-click-capture.sh
 ```
 
-Then **log out and log back in** (group membership only applies to new sessions).
-Verify it took effect:
-
-```bash
-groups | tr ' ' '\n' | grep input    # should print: input
-```
-
-Now StepForge reads mouse buttons directly from the kernel (`/dev/input`) and
-captures a screenshot on each click.
+It shows you the exact rule and asks for confirmation before installing. Under
+the hood it uses a systemd `uaccess` ACL restricted to `ID_INPUT_MOUSE`
+devices — see [packaging/linux/common/60-stepforge-input.rules](../packaging/linux/common/60-stepforge-input.rules).
+Re-log in (or replug a USB mouse) for it to apply.
 
 > **No red marker on Wayland.** Even with per-click capture working, Wayland
 > does not tell apps *where* the pointer is, so StepForge cannot draw the circle
@@ -114,10 +118,16 @@ On launch StepForge chooses the best available click source:
 1. **Windows** — low-level mouse hook (position + timing).
 2. **X11** — `xinput` (position + timing → full red marker).
 3. **Linux evdev** (`/dev/input`) — button presses on X11 *and* Wayland, no
-   position on Wayland. Used when `xinput` can't see clicks (i.e. Wayland), if
-   you're in the `input` group.
-4. **Timed capture** — the always-works fallback (a screenshot every N seconds)
-   when no click source is available.
+   position on Wayland. Used when `xinput` can't see clicks (i.e. Wayland) and
+   only if you opted into the least-privilege mouse rule
+   (`scripts/linux/enable-click-capture.sh`).
+4. **Hotkey / timed capture** — the always-works fallback (the Capture hotkey,
+   or a screenshot every N seconds) when no click source is available. On
+   Wayland this is the default, and StepForge reports it honestly instead of
+   pretending clicks are captured.
+
+Open **Settings → Diagnostics** to see the detected session type, portal/
+PipeWire status, and the active capture trigger for your machine.
 
 Screen frames come from a single long-lived capture stream per recording, so
 clicks/timer ticks never re-open the screen-share dialog.
@@ -149,7 +159,9 @@ STEPFORGE_CAPTURE_LOG=1 npm start
 
 - `[stepforge] screen-capture stream active …` — the stream is up.
 - `[stepforge] per-click capture via evdev on N device(s) …` — clicks are wired up.
-- `[stepforge] no readable mouse input devices …` — you need the `input` group (see above).
+- `[stepforge] no readable mouse input devices …` — per-click capture is not
+  enabled; run `scripts/linux/enable-click-capture.sh` for the least-privilege
+  mouse rule, or just use the hotkey/interval trigger.
 
 **Harmless console noise.** Lines like `vaInitialize failed`, `Frame latency is
 negative`, and `StatusNotifierItem … already exported` come from Chromium/GNOME,

docs/linux/dnf.md

@@ -0,0 +1,63 @@
+# StepForge on dnf-based Linux (Fedora / RHEL)
+
+This is the setup and packaging guide for **dnf-based** distributions. Debian,
+Ubuntu, and other apt-based systems have a separate guide:
+[apt.md](apt.md).
+
+## Install from the .rpm
+
+```bash
+sudo dnf install ./stepforge-<version>-1.<arch>.rpm
+```
+
+dnf pulls the required runtime libraries automatically (they are declared as
+`Requires`). The package installs:
+
+- the app and a fixed Electron runtime under `/opt/stepforge`,
+- the `stepforge` launcher at `/usr/bin/stepforge`,
+- a desktop entry, icons, and `.sfgz`/`.sfglt` file associations.
+
+Launch it from your application menu or run `stepforge`.
+
+### Sandbox
+
+The launcher runs **sandboxed**. On most modern kernels the Chromium
+user-namespace sandbox works out of the box; the package's `%post` also makes
+the setuid `chrome-sandbox` helper usable as a fallback. StepForge will **not**
+silently launch unsandboxed.
+
+## Install from the portable tarball
+
+The portable tarball (same one shipped for apt systems) includes the
+`/usr/bin/stepforge` launcher. Install the runtime libraries first:
+
+```bash
+bash scripts/linux/dnf/install-runtime-deps.sh
+tar -xzf stepforge_<version>_linux-x64.tar.gz
+./usr/bin/stepforge
+```
+
+## Capture capabilities on dnf systems
+
+- **X11**: full per-click capture with an accurate marker (needs `xinput`).
+- **Wayland** (Fedora's default): screen capture via the XDG Desktop Portal +
+  PipeWire; the portal asks permission once per recording. Per-click capture
+  with coordinates is not exposed by Wayland, so recording uses a global
+  hotkey or interval trigger. StepForge reports the active trigger honestly.
+
+Open Settings → Diagnostics in the app to see the detected session type,
+portal/PipeWire status, and the active capture profile.
+
+## Build the .rpm yourself
+
+```bash
+bash scripts/linux/dnf/install-build-deps.sh    # rpm-build, rpmdevtools, Xvfb, …
+nvm install && nvm use                           # pinned Node 22 (see .nvmrc)
+npm ci
+npm run package:linux:rpm                         # -> build/artifacts/*.rpm + sha256
+```
+
+The builder stages **only** runtime files (shared with the `.deb` builder via
+`packaging/linux/common/stage-runtime.sh`): the app code, a fixed Electron
+runtime, and production npm dependencies. It never copies the development
+`node_modules` and fails if `node_modules` is missing.

packaging/linux/common/60-stepforge-input.rules

@@ -0,0 +1,19 @@
+# StepForge least-privilege input access (OPTIONAL, opt-in).
+#
+# Grants the user at the ACTIVE local session read/write access to MOUSE input
+# devices only, via systemd-logind's `uaccess` ACL. This is the least-privilege
+# alternative to joining the broad `input` group, which would grant access to
+# ALL input devices — including keyboards — for the user permanently, on every
+# session. StepForge never needs keystrokes, so this rule deliberately EXCLUDES
+# keyboards.
+#
+# Scope of what this grants:
+#   * only devices udev classifies as a mouse (ID_INPUT_MOUSE=1),
+#   * only when they are NOT also a keyboard (ID_INPUT_KEYBOARD!=1),
+#   * only to whoever is logged in at the physical seat (uaccess is
+#     session-scoped, not a permanent group membership).
+#
+# StepForge uses this only for the optional Wayland per-click *trigger* (button
+# presses, no coordinates). It is not required — the safe default is a global
+# hotkey or interval capture.
+SUBSYSTEM=="input", KERNEL=="event*", ENV{ID_INPUT_MOUSE}=="1", ENV{ID_INPUT_KEYBOARD}!="1", TAG+="uaccess"

packaging/linux/common/stage-runtime.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Shared staging for the Linux packages. Populates $STAGE_ROOT with the FHS
+# layout common to the .deb and .rpm: a pruned runtime-only /opt/stepforge, the
+# launcher, desktop entry, icons, MIME registration, and the license.
+#
+# Distro-specific metadata (Depends vs Requires) and the packaging step
+# (dpkg-deb vs rpmbuild) stay in the per-distro builders. This file only
+# assembles the payload so the two never drift.
+#
+# Usage:  ROOT_DIR=<repo> STAGE_ROOT=<dir> bash stage-runtime.sh
+set -euo pipefail
+
+: "${ROOT_DIR:?ROOT_DIR must be set}"
+: "${STAGE_ROOT:?STAGE_ROOT must be set}"
+
+# A packaged app must contain a fixed runtime; never install at build time and
+# never ship without node_modules.
+if [ ! -d "$ROOT_DIR/node_modules/electron/dist" ]; then
+  echo "error: node_modules/electron is missing. Run 'npm ci' before packaging." >&2
+  exit 1
+fi
+
+APP_DIR="$STAGE_ROOT/opt/stepforge"
+mkdir -p "$APP_DIR/node_modules" \
+  "$STAGE_ROOT/usr/bin" \
+  "$STAGE_ROOT/usr/share/applications" \
+  "$STAGE_ROOT/usr/share/mime/packages"
+
+# --- application code (runtime only) ----------------------------------------
+for item in app core exporters package.json package-lock.json; do
+  cp -a "$ROOT_DIR/$item" "$APP_DIR/$item"
+done
+
+# --- runtime node_modules ----------------------------------------------------
+# The fixed Electron runtime (needed at runtime even though it is a dev dep):
+cp -a "$ROOT_DIR/node_modules/electron" "$APP_DIR/node_modules/electron"
+# Production npm dependencies (tesseract.js + language data + transitive):
+while IFS= read -r dep; do
+  [ -n "$dep" ] || continue
+  rel="${dep#"$ROOT_DIR"/}"
+  [ "$rel" != "$dep" ] || continue
+  [ -d "$dep" ] || continue
+  mkdir -p "$APP_DIR/$(dirname "$rel")"
+  cp -a "$dep" "$APP_DIR/$rel"
+done < <(cd "$ROOT_DIR" && npm ls --omit=dev --all --parseable 2>/dev/null | tail -n +2)
+
+# Guard: the development-only packaging toolchain must not have leaked in.
+if [ -d "$APP_DIR/node_modules/electron-builder" ] || [ -d "$APP_DIR/node_modules/app-builder-lib" ]; then
+  echo "error: build-only dependency leaked into the package payload." >&2
+  exit 1
+fi
+
+# --- launcher ----------------------------------------------------------------
+install -m 0755 "$ROOT_DIR/packaging/linux/common/launcher.sh" "$STAGE_ROOT/usr/bin/stepforge"
+
+# --- desktop entry, icons, MIME ---------------------------------------------
+install -m 0644 "$ROOT_DIR/packaging/linux/common/stepforge.desktop" "$STAGE_ROOT/usr/share/applications/stepforge.desktop"
+install -m 0644 "$ROOT_DIR/packaging/linux/common/stepforge-mime.xml" "$STAGE_ROOT/usr/share/mime/packages/stepforge.xml"
+for size in 16 32 48 64 128 256 512; do
+  icon="$ROOT_DIR/packaging/assets/icons/stepforge-${size}.png"
+  [ -f "$icon" ] || continue
+  dest="$STAGE_ROOT/usr/share/icons/hicolor/${size}x${size}/apps"
+  mkdir -p "$dest"
+  install -m 0644 "$icon" "$dest/stepforge.png"
+done

packaging/linux/debian/package.sh

@@ -25,59 +25,13 @@ case "$DEB_ARCH" in
   *) NODE_ARCH="$DEB_ARCH" ;;
 esac
 
-# A packaged app must contain a fixed runtime; never install at build time from
-# within the package step, and never ship without node_modules.
-if [ ! -d "$ROOT_DIR/node_modules/electron/dist" ]; then
-  echo "error: node_modules/electron is missing. Run 'npm ci' before packaging." >&2
-  exit 1
-fi
-
 WORK_DIR="$(mktemp -d "${OUT_DIR%/}/.deb.XXXXXX")"
 trap 'rm -rf "$WORK_DIR"' EXIT
-APP_DIR="$WORK_DIR/opt/stepforge"
-mkdir -p "$APP_DIR" "$WORK_DIR/usr/bin" "$WORK_DIR/DEBIAN"
-mkdir -p "$WORK_DIR/usr/share/applications"
-mkdir -p "$WORK_DIR/usr/share/mime/packages"
-mkdir -p "$WORK_DIR/usr/share/doc/stepforge"
 
-# --- application code (runtime only) ----------------------------------------
-for item in app core exporters package.json package-lock.json; do
-  cp -a "$ROOT_DIR/$item" "$APP_DIR/$item"
-done
+# Stage the shared runtime-only payload (fails if node_modules is missing).
+ROOT_DIR="$ROOT_DIR" STAGE_ROOT="$WORK_DIR" bash "$ROOT_DIR/packaging/linux/common/stage-runtime.sh"
 
-# --- runtime node_modules ----------------------------------------------------
-# The fixed Electron runtime (needed at runtime even though it is a dev dep):
-mkdir -p "$APP_DIR/node_modules"
-cp -a "$ROOT_DIR/node_modules/electron" "$APP_DIR/node_modules/electron"
-# Production npm dependencies (tesseract.js + language data + transitive):
-while IFS= read -r dep; do
-  [ -n "$dep" ] || continue
-  rel="${dep#"$ROOT_DIR"/}"
-  [ "$rel" != "$dep" ] || continue          # only paths under the repo
-  [ -d "$dep" ] || continue
-  mkdir -p "$APP_DIR/$(dirname "$rel")"
-  cp -a "$dep" "$APP_DIR/$rel"
-done < <(npm ls --omit=dev --all --parseable 2>/dev/null | tail -n +2)
-
-# Guard: the development-only packaging toolchain must not have leaked in.
-if [ -d "$APP_DIR/node_modules/electron-builder" ] || [ -d "$APP_DIR/node_modules/app-builder-lib" ]; then
-  echo "error: build-only dependency leaked into the package payload." >&2
-  exit 1
-fi
-
-# --- launcher ----------------------------------------------------------------
-install -m 0755 "$ROOT_DIR/packaging/linux/common/launcher.sh" "$WORK_DIR/usr/bin/stepforge"
-
-# --- desktop entry, icons, MIME ---------------------------------------------
-install -m 0644 "$ROOT_DIR/packaging/linux/common/stepforge.desktop" "$WORK_DIR/usr/share/applications/stepforge.desktop"
-install -m 0644 "$ROOT_DIR/packaging/linux/common/stepforge-mime.xml" "$WORK_DIR/usr/share/mime/packages/stepforge.xml"
-for size in 16 32 48 64 128 256 512; do
-  icon="$ROOT_DIR/packaging/assets/icons/stepforge-${size}.png"
-  [ -f "$icon" ] || continue
-  dest="$WORK_DIR/usr/share/icons/hicolor/${size}x${size}/apps"
-  mkdir -p "$dest"
-  install -m 0644 "$icon" "$dest/stepforge.png"
-done
+mkdir -p "$WORK_DIR/DEBIAN" "$WORK_DIR/usr/share/doc/stepforge"
 
 # --- license + docs pointer --------------------------------------------------
 if [ -f "$ROOT_DIR/LICENSE" ]; then

packaging/linux/fedora/package.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Build a production StepForge .rpm from a pruned, runtime-only tree, mirroring
+# the .deb builder. Stages the shared payload via common/stage-runtime.sh, then
+# packages it with rpmbuild against a prebuilt BuildRoot (no compilation).
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+cd "$ROOT_DIR"
+
+VERSION="$(node -p "require('./package.json').version")"
+MAINTAINER="${STEPFORGE_MAINTAINER:-StepForge <[email protected]>}"
+OUT_DIR="${STEPFORGE_PACKAGE_DIR:-$ROOT_DIR/build/artifacts}"
+mkdir -p "$OUT_DIR"
+
+if ! command -v rpmbuild >/dev/null 2>&1; then
+  echo "error: rpmbuild is not installed. Run scripts/linux/dnf/install-build-deps.sh" >&2
+  exit 1
+fi
+
+# RPM arch label from the host.
+RPM_ARCH="$(rpm --eval '%{_arch}' 2>/dev/null || uname -m)"
+
+BUILD_ROOT="$(mktemp -d "${OUT_DIR%/}/.rpm.XXXXXX")"
+trap 'rm -rf "$BUILD_ROOT"' EXIT
+STAGE="$BUILD_ROOT/buildroot"
+mkdir -p "$STAGE"
+
+# Shared runtime-only payload (fails if node_modules is missing).
+ROOT_DIR="$ROOT_DIR" STAGE_ROOT="$STAGE" bash "$ROOT_DIR/packaging/linux/common/stage-runtime.sh"
+
+# License into the RPM's conventional location.
+mkdir -p "$STAGE/usr/share/licenses/stepforge"
+if [ -f "$ROOT_DIR/LICENSE" ]; then
+  install -m 0644 "$ROOT_DIR/LICENSE" "$STAGE/usr/share/licenses/stepforge/LICENSE"
+elif [ -f "$ROOT_DIR/docs/LICENSE" ]; then
+  install -m 0644 "$ROOT_DIR/docs/LICENSE" "$STAGE/usr/share/licenses/stepforge/LICENSE"
+else
+  # rpmbuild %license requires the file to exist; write a pointer if absent.
+  echo "See project LICENSE." > "$STAGE/usr/share/licenses/stepforge/LICENSE"
+fi
+
+# Materialize the spec with version/maintainer substituted.
+SPEC="$BUILD_ROOT/stepforge.spec"
+sed -e "s/@VERSION@/$VERSION/" -e "s#@MAINTAINER@#$MAINTAINER#" \
+  "$ROOT_DIR/packaging/linux/fedora/stepforge.spec" > "$SPEC"
+
+rpmbuild -bb \
+  --define "_topdir $BUILD_ROOT/rpmbuild" \
+  --define "_rpmdir $OUT_DIR" \
+  --define "_build_id_links none" \
+  --buildroot "$STAGE" \
+  --target "$RPM_ARCH" \
+  "$SPEC" >/dev/null
+
+# rpmbuild writes to $OUT_DIR/<arch>/<name>.rpm — surface the final path.
+RPM_FILE="$(find "$OUT_DIR" -name "stepforge-${VERSION}-1*.${RPM_ARCH}.rpm" -newer "$SPEC" | head -1)"
+if [ -z "$RPM_FILE" ]; then
+  RPM_FILE="$(find "$OUT_DIR" -name "stepforge-${VERSION}-1*.rpm" | head -1)"
+fi
+[ -n "$RPM_FILE" ] || { echo "error: rpmbuild did not produce an .rpm" >&2; exit 1; }
+
+# Checksum.
+( cd "$(dirname "$RPM_FILE")" && sha256sum "$(basename "$RPM_FILE")" > "$(basename "$RPM_FILE").sha256" )
+
+echo "$RPM_FILE"

packaging/linux/fedora/stepforge.spec

@@ -0,0 +1,69 @@
+# StepForge RPM spec. The payload is prebuilt into a staging BuildRoot by
+# packaging/linux/fedora/package.sh (which stages a pruned runtime tree), so
+# this spec only packages and declares metadata — it does not compile.
+#
+# Placeholders @VERSION@ / @MAINTAINER@ are substituted by package.sh.
+
+%global debug_package %{nil}
+%global __brp_check_rpaths %{nil}
+%define _build_id_links none
+
+Name:           stepforge
+Version:        @VERSION@
+Release:        1%{?dist}
+Summary:        Local-first step-by-step guide capture and export tool
+
+License:        MPL-2.0
+URL:            https://github.com/Twest2/StepForge
+
+# Runtime shared libraries (Chromium/Electron) + capture integration.
+Requires:       nss
+Requires:       nspr
+Requires:       atk
+Requires:       at-spi2-atk
+Requires:       cups-libs
+Requires:       gtk3
+Requires:       mesa-libgbm
+Requires:       alsa-lib
+Requires:       libxkbcommon
+Recommends:     xinput
+Recommends:     xdg-desktop-portal
+Recommends:     pipewire
+
+# The payload is architecture-specific (bundles the Electron binary).
+%description
+StepForge captures step-by-step workflows as screenshots, lets you annotate
+and describe each step, and exports to Markdown, PDF, DOCX, PPTX, HTML, and
+more. Local-first: no telemetry, with an optional user-configured local AI
+integration. This package bundles a fixed Electron runtime and only
+production dependencies; it does not install anything at runtime.
+
+%files
+/opt/stepforge
+/usr/bin/stepforge
+/usr/share/applications/stepforge.desktop
+/usr/share/mime/packages/stepforge.xml
+/usr/share/icons/hicolor/*/apps/stepforge.png
+%license /usr/share/licenses/stepforge/LICENSE
+
+%post
+# Make the Chromium setuid sandbox helper usable so the app launches sandboxed.
+HELPER=/opt/stepforge/node_modules/electron/dist/chrome-sandbox
+if [ -e "$HELPER" ]; then
+  chown root:root "$HELPER" || true
+  chmod 4755 "$HELPER" || true
+fi
+if command -v update-desktop-database >/dev/null 2>&1; then update-desktop-database -q /usr/share/applications || true; fi
+if command -v update-mime-database >/dev/null 2>&1; then update-mime-database /usr/share/mime || true; fi
+if command -v gtk-update-icon-cache >/dev/null 2>&1; then gtk-update-icon-cache -q /usr/share/icons/hicolor || true; fi
+
+%postun
+if [ "$1" = 0 ]; then
+  if command -v update-desktop-database >/dev/null 2>&1; then update-desktop-database -q /usr/share/applications || true; fi
+  if command -v update-mime-database >/dev/null 2>&1; then update-mime-database /usr/share/mime || true; fi
+  if command -v gtk-update-icon-cache >/dev/null 2>&1; then gtk-update-icon-cache -q /usr/share/icons/hicolor || true; fi
+fi
+
+%changelog
+* Fri Jul 03 2026 @MAINTAINER@ - @VERSION@-1
+- Production runtime-only package (pruned tree, fixed Electron runtime).

scripts/linux/dnf/install-build-deps.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Install the BUILD toolchain for producing StepForge packages on dnf-based
+# systems (Fedora/RHEL). For DEVELOPERS/packagers only; never shipped inside
+# the end-user package.
+set -euo pipefail
+
+if ! command -v dnf >/dev/null 2>&1; then
+  echo "This script is for dnf-based systems (Fedora/RHEL)." >&2
+  exit 1
+fi
+
+SUDO=""
+if [ "$(id -u)" -ne 0 ]; then SUDO="sudo"; fi
+
+PACKAGES=(
+  rpm-build rpmdevtools   # build the .rpm
+  desktop-file-utils      # validate the .desktop entry
+  ca-certificates         # npm ci over https
+  xorg-x11-server-Xvfb    # headless smoke test under Xvfb
+)
+
+echo "Installing StepForge build dependencies via dnf..."
+$SUDO dnf install -y "${PACKAGES[@]}"
+
+cat <<'MSG'
+Done. Also install the pinned Node toolchain (see .nvmrc — Node 22.12+):
+  nvm install && nvm use     # or another Node 22 LTS install method
+Then, from the repo root:
+  npm ci
+  npm run package:linux:rpm
+MSG

scripts/linux/dnf/install-runtime-deps.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Install the RUNTIME libraries StepForge needs on dnf-based systems (Fedora,
+# RHEL/derivatives). These are the shared libraries the packaged Electron
+# runtime links against, plus the X11/portal integration used for capture.
+# For END USERS installing from the tarball; the .rpm declares the same set as
+# Requires so dnf pulls them automatically.
+set -euo pipefail
+
+if ! command -v dnf >/dev/null 2>&1; then
+  echo "This script is for dnf-based systems (Fedora/RHEL). Use the apt script on Debian/Ubuntu." >&2
+  exit 1
+fi
+
+SUDO=""
+if [ "$(id -u)" -ne 0 ]; then SUDO="sudo"; fi
+
+PACKAGES=(
+  # Chromium/Electron shared libraries
+  nss nspr atk at-spi2-atk at-spi2-core cups-libs libdrm
+  gtk3 mesa-libgbm alsa-lib libxkbcommon
+  libXcomposite libXdamage libXfixes libXrandr libxshmfence
+  # X11 per-click capture (marker-accurate) — X11 sessions only
+  xorg-x11-server-utils xinput
+  # Wayland screen-share via the XDG portal + PipeWire
+  xdg-desktop-portal pipewire
+)
+
+echo "Installing StepForge runtime dependencies via dnf..."
+# Some package names differ across Fedora releases; install best-effort so one
+# missing optional name doesn't abort the whole set.
+$SUDO dnf install -y "${PACKAGES[@]}" || {
+  echo "Some packages were unavailable; retrying individually..." >&2
+  for pkg in "${PACKAGES[@]}"; do $SUDO dnf install -y "$pkg" || echo "  (skipped: $pkg)" >&2; done
+}
+echo "Done. StepForge runtime dependencies are installed."

scripts/linux/enable-click-capture.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# OPTIONAL: enable per-click capture on Wayland (or X11 without xinput) using a
+# LEAST-PRIVILEGE udev rule instead of the broad `input` group.
+#
+# Security tradeoff (read before running):
+#   * This grants your ACTIVE local session read access to MOUSE devices only.
+#   * It deliberately EXCLUDES keyboards — StepForge never needs keystrokes.
+#   * Access is session-scoped (systemd `uaccess` ACL), not a permanent group.
+#   * It is NOT required: the safe default is a global hotkey or interval
+#     capture. Only enable this if you want a screenshot on every click.
+#
+# Compare to `sudo usermod -aG input "$USER"`, which grants access to ALL input
+# devices (including keyboards) for your user on every session — a much larger
+# surface. This script does not do that.
+set -euo pipefail
+
+RULE_SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/packaging/linux/common/60-stepforge-input.rules"
+RULE_DEST="/etc/udev/rules.d/60-stepforge-input.rules"
+
+if [ ! -f "$RULE_SRC" ]; then
+  echo "error: rule file not found at $RULE_SRC" >&2
+  exit 1
+fi
+
+echo "This installs a least-privilege udev rule granting your session read"
+echo "access to MOUSE devices only (never keyboards):"
+echo
+sed 's/^/    /' "$RULE_SRC"
+echo
+printf 'Install it to %s? [y/N] ' "$RULE_DEST"
+read -r reply
+case "$reply" in
+  y|Y|yes|YES) ;;
+  *) echo "Aborted. No changes made."; exit 0 ;;
+esac
+
+SUDO=""
+if [ "$(id -u)" -ne 0 ]; then SUDO="sudo"; fi
+
+$SUDO install -m 0644 "$RULE_SRC" "$RULE_DEST"
+$SUDO udevadm control --reload-rules
+$SUDO udevadm trigger --subsystem-match=input --action=change || true
+
+cat <<'MSG'
+
+Installed. You may need to unplug/replug a USB mouse or re-log in for the ACL
+to apply to already-connected devices.
+
+To remove it later:
+  sudo rm /etc/udev/rules.d/60-stepforge-input.rules
+  sudo udevadm control --reload-rules
+MSG

tests/integration/linux/package-rpm.test.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Integration test: build the production .rpm and assert it is a real,
+# runtime-only package. Honest skip policy: skip ONLY when the prerequisites
+# are genuinely absent (rpmbuild missing or node_modules not installed). Once
+# we build, any structural failure fails the test.
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+cd "$ROOT_DIR"
+
+if ! command -v rpmbuild >/dev/null 2>&1; then
+  echo "package-rpm SKIPPED: rpmbuild not installed (not a dnf-based build host)"
+  exit 0
+fi
+if [ ! -d "$ROOT_DIR/node_modules/electron/dist" ]; then
+  echo "package-rpm SKIPPED: node_modules/electron missing (run npm ci first)"
+  exit 0
+fi
+
+OUT_DIR="$(mktemp -d)"
+trap 'rm -rf "$OUT_DIR"' EXIT
+
+RPM="$(STEPFORGE_PACKAGE_DIR="$OUT_DIR" bash packaging/linux/fedora/package.sh | tail -1)"
+[ -f "$RPM" ] || { echo "package-rpm FAILED: builder produced no .rpm" >&2; exit 1; }
+
+fail() { echo "package-rpm FAILED: $1" >&2; exit 1; }
+
+listing="$(rpm -qlp "$RPM" 2>/dev/null)"
+
+for needle in \
+  '/usr/bin/stepforge' \
+  '/usr/share/applications/stepforge.desktop' \
+  '/usr/share/mime/packages/stepforge.xml' \
+  '/opt/stepforge/node_modules/electron/dist/electron' \
+  '/opt/stepforge/app/main.js'; do
+  echo "$listing" | grep -qF "$needle" || fail "missing packaged file: $needle"
+done
+echo "$listing" | grep -q '/usr/share/icons/hicolor/256x256/apps/stepforge.png' || fail "missing 256px icon"
+
+# No dev tree / build tooling / app docs.
+for banned in 'electron-builder' '/opt/stepforge/docs/' '/opt/stepforge/ai_prompts/' '/opt/stepforge/examples/'; do
+  echo "$listing" | grep -qF "$banned" && fail "unexpected payload: $banned" || true
+done
+
+# Metadata sanity.
+rpm -qip "$RPM" 2>/dev/null | grep -q '^Name *: stepforge' || fail "rpm Name is not stepforge"
+rpm -qp --requires "$RPM" 2>/dev/null | grep -q '^nss' || fail "rpm does not Require nss"
+
+echo "package-rpm OK ($(basename "$RPM"))"

tests/unit/packaging-linux.test.js

@@ -6,7 +6,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const ROOT = path.resolve(__dirname, '..', '..');
-const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+// Strip CR so /^...$/m assertions are robust to CRLF checkouts on Windows CI.
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8').replace(/\r\n/g, '\n');
 const exists = (rel) => fs.existsSync(path.join(ROOT, rel));
 
 // These are structural checks that run in the normal (cross-platform) unit
@@ -33,6 +34,55 @@ test('the old non-production package-linux.sh is gone', () => {
   assert.equal(exists('scripts/package-linux.sh'), false);
 });
 
+test('Fedora/dnf packaging files exist in their own separate locations', () => {
+  for (const f of [
+    'packaging/linux/fedora/package.sh',
+    'packaging/linux/fedora/stepforge.spec',
+    'packaging/linux/common/stage-runtime.sh',
+    'scripts/linux/dnf/install-runtime-deps.sh',
+    'scripts/linux/dnf/install-build-deps.sh',
+    'docs/linux/dnf.md',
+    'tests/integration/linux/package-rpm.test.sh',
+  ]) {
+    assert.ok(exists(f), `expected ${f} to exist`);
+  }
+});
+
+test('the RPM spec declares runtime Requires, license, and MPL-2.0', () => {
+  const spec = read('packaging/linux/fedora/stepforge.spec');
+  assert.match(spec, /^License:\s+MPL-2\.0$/m);
+  assert.match(spec, /^Requires:\s+nss$/m);
+  assert.match(spec, /%license/);
+  assert.match(spec, /chrome-sandbox/); // %post makes the sandbox helper setuid
+  assert.match(spec, /@VERSION@/);
+  assert.doesNotMatch(spec, /fully offline/i);
+});
+
+test('the rpm builder shares staging and requires rpmbuild + node_modules', () => {
+  const script = read('packaging/linux/fedora/package.sh');
+  assert.match(script, /stage-runtime\.sh/);
+  assert.match(script, /rpmbuild/);
+  assert.match(script, /rpm --eval '%\{_arch\}'|uname -m/); // arch detected
+  assert.doesNotMatch(script, /cp -a "\$ROOT_DIR\/node_modules" /);
+});
+
+test('dnf setup scripts target dnf and keep build vs runtime deps separate', () => {
+  const runtime = read('scripts/linux/dnf/install-runtime-deps.sh');
+  const build = read('scripts/linux/dnf/install-build-deps.sh');
+  assert.match(runtime, /dnf install/);
+  assert.match(runtime, /nss/);
+  assert.doesNotMatch(runtime, /rpm-build|rpmdevtools/, 'runtime script must not install build tools');
+  assert.match(build, /rpm-build/);
+});
+
+test('the shared staging never copies the whole dev node_modules', () => {
+  const staging = read('packaging/linux/common/stage-runtime.sh');
+  assert.match(staging, /npm ls --omit=dev/);
+  assert.match(staging, /electron-builder/); // leak guard
+  assert.doesNotMatch(staging, /cp -a "\$ROOT_DIR\/node_modules" "\$APP_DIR/);
+  assert.match(staging, /node_modules\/electron\/dist/); // requires the runtime
+});
+
 test('the desktop entry is valid and app-branded', () => {
   const desktop = read('packaging/linux/common/stepforge.desktop');
   assert.match(desktop, /^\[Desktop Entry\]/);
@@ -62,11 +112,9 @@ test('the launcher refuses an unsandboxed launch unless explicitly opted in', ()
   assert.doesNotMatch(launcher, /npm (install|ci|rebuild)/);
 });
 
-test('the package builder requires node_modules and guards against dev-dep leaks', () => {
+test('the deb builder detects arch and delegates to shared staging', () => {
   const script = read('packaging/linux/debian/package.sh');
-  assert.match(script, /node_modules\/electron\/dist/);
-  assert.match(script, /npm ls --omit=dev/);
-  assert.match(script, /electron-builder/); // the leak guard references it
+  assert.match(script, /stage-runtime\.sh/); // runtime-only staging is shared
   assert.match(script, /dpkg --print-architecture/); // arch detected, not hardcoded
   assert.doesNotMatch(script, /cp -a "\$ROOT_DIR\/node_modules" /); // never copy the whole dev tree
 });

tests/unit/wayland-honesty.test.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { chooseCaptureTrigger, detectLinuxCapabilities } = require('../../app/platform/linux/diagnostics');
+const platform = require('../../app/platform');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+// Strip CR so assertions are robust to CRLF checkouts on Windows CI.
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8').replace(/\r\n/g, '\n');
+const exists = (rel) => fs.existsSync(path.join(ROOT, rel));
+
+// ---- honest trigger decisions ----------------------------------------------
+
+test('X11 + xinput promises per-click capture with a marker', () => {
+  const t = chooseCaptureTrigger({ os: 'linux', isWayland: false, clickCapture: 'x11-xinput' });
+  assert.equal(t.trigger, 'click');
+  assert.equal(t.coordinates, true);
+  assert.equal(t.marker, true);
+});
+
+test('Wayland evdev captures per click but never promises coordinates or a marker', () => {
+  const t = chooseCaptureTrigger({ os: 'linux', isWayland: true, clickCapture: 'evdev-wayland' });
+  assert.equal(t.trigger, 'click');
+  assert.equal(t.coordinates, false, 'Wayland exposes no pointer position');
+  assert.equal(t.marker, false);
+});
+
+test('Wayland without a click source falls back to the user trigger, honestly', () => {
+  const interval = chooseCaptureTrigger({ os: 'linux', isWayland: true, clickCapture: 'hotkey-or-interval-only' }, 'interval');
+  assert.equal(interval.trigger, 'interval');
+  assert.equal(interval.coordinates, false);
+  assert.match(interval.note, /Wayland does not expose global clicks/i);
+
+  const hotkey = chooseCaptureTrigger({ os: 'linux', isWayland: true, clickCapture: 'hotkey-or-interval-only' }, 'hotkey');
+  assert.equal(hotkey.trigger, 'hotkey');
+});
+
+test('the platform facade wires the Linux trigger decision from real capabilities', () => {
+  const caps = detectLinuxCapabilities({
+    env: { XDG_SESSION_TYPE: 'wayland', WAYLAND_DISPLAY: 'wayland-0' },
+    hasBinary: () => false,
+    existsSync: () => false,
+    readdirSync: () => [],
+  });
+  const t = platform.chooseCaptureTrigger(caps, 'interval');
+  assert.equal(t.trigger, 'interval');
+  assert.equal(t.marker, false);
+});
+
+test('Windows always reports per-click capture', () => {
+  const t = platform.chooseCaptureTrigger({ os: 'windows' });
+  assert.equal(t.trigger, 'click');
+  assert.equal(t.coordinates, true);
+});
+
+// ---- least-privilege input access -------------------------------------------
+
+test('the udev rule grants mouse-only access and excludes keyboards', () => {
+  assert.ok(exists('packaging/linux/common/60-stepforge-input.rules'));
+  const rule = read('packaging/linux/common/60-stepforge-input.rules');
+  assert.match(rule, /ID_INPUT_MOUSE\}=="1"/);
+  assert.match(rule, /ID_INPUT_KEYBOARD\}!="1"/, 'must exclude keyboards');
+  assert.match(rule, /TAG\+="uaccess"/, 'session-scoped ACL, not a permanent group');
+});
+
+test('the enable script is opt-in and installs the least-privilege rule, not the input group', () => {
+  assert.ok(exists('scripts/linux/enable-click-capture.sh'));
+  const script = read('scripts/linux/enable-click-capture.sh');
+  assert.match(script, /read -r reply/, 'must confirm before installing');
+  assert.match(script, /60-stepforge-input\.rules/, 'installs the least-privilege udev rule');
+  // usermod may only appear in a comment (warning), never as an executed
+  // command. Check command position (line start, optional sudo) so this is
+  // robust to CRLF vs LF line endings across platforms.
+  assert.doesNotMatch(script, /^\s*(sudo\s+)?usermod\b/m, 'must not run the broad input-group command');
+});
+
+// ---- docs no longer push the broad input group ------------------------------
+
+test('Linux docs recommend the least-privilege path and warn against the input group', () => {
+  const doc = read('docs/GETTING_STARTED_WITH_LINUX.md');
+  assert.match(doc, /enable-click-capture\.sh/);
+  assert.match(doc, /least-privilege/i);
+  // The broad group is now presented as a warning ("Do not use ..."), not a
+  // recommended step.
+  assert.match(doc, /Do \*\*not\*\* use `sudo usermod/);
+});