Document design choices and standardize Dockerfile

scripts/build-linux-docker.sh

@@ -1,12 +1,21 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# Optional first argument mirrors build-linux.sh. The Docker build still writes
+# the final artifact into the local dist/ tree, not into the container.
 output="${1:-dist/linux/pysentry}"
 
-docker build -f Dockerfile.linux -t pysentry-linux-builder .
+# Dockerfile contains the native packages required by Fyne. Keeping that
+# environment in Docker makes Linux builds repeatable from Windows hosts and CI.
+docker build -f Dockerfile -t pysentry-linux-builder .
+
+# The image build produces /out/pysentry. A temporary container is used only as a
+# convenient way to copy that file out; the app is not run inside the container.
 container_id="$(docker create pysentry-linux-builder)"
 mkdir -p "$(dirname "$output")"
 docker cp "${container_id}:/out/pysentry" "$output"
 docker rm "$container_id" >/dev/null
 
+# Icons are embedded in the Go binary, so there is no assets directory to copy
+# after extracting the Linux executable.
 echo "Built $output"

scripts/build-linux.sh

@@ -1,13 +1,22 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# Optional first argument lets a developer or CI job choose the output path.
+# dist/linux/pysentry is the default so generated binaries stay outside src/.
 output="${1:-dist/linux/pysentry}"
 mkdir -p "$(dirname "$output")"
 
+# Fyne needs CGO for its native desktop backend. The script pins the target to
+# linux/amd64 because this is the first supported Linux artifact; other
+# architectures can be added later as explicit build targets.
 export CGO_ENABLED=1
 export GOOS=linux
 export GOARCH=amd64
 
+# -trimpath removes local machine paths from debug/build metadata. -s -w strips
+# symbol/debug tables to keep the desktop binary smaller.
 go build -trimpath -ldflags "-s -w" -o "$output" ./cmd/pysentry
 
+# The application icon is embedded by Go, so the Linux build does not need a
+# sidecar assets directory beside the executable.
 echo "Built $output"

scripts/build-windows.bat

@@ -1,27 +1,46 @@
 @echo off
 setlocal enabledelayedexpansion
 
+REM Optional first argument allows CI or a developer to choose another output
+REM path. The default keeps all generated binaries under dist\ so the source tree
+REM stays clean and the old bin\ folder is no longer needed.
 set "OUTPUT=%~1"
 if "%OUTPUT%"=="" set "OUTPUT=dist\windows\pysentry.exe"
 
+REM Prefer the standard Go installer path on Windows, but fall back to PATH for
+REM machines where Go was installed by another package manager.
 set "GOEXE=%ProgramFiles%\Go\bin\go.exe"
 if not exist "%GOEXE%" set "GOEXE=go"
 
+REM Fyne uses native libraries through CGO. MSYS2 UCRT64 provides the GCC toolchain
+REM expected by the Windows build; prepending it keeps the script self-contained
+REM without permanently changing the user's system PATH.
 if exist "C:\msys64\ucrt64\bin" set "PATH=C:\msys64\ucrt64\bin;%PATH%"
 
+REM Build a 64-bit Windows binary. CGO must stay enabled for Fyne; disabling it
+REM would make the native GUI backend fail to compile.
 set "CGO_ENABLED=1"
 set "GOOS=windows"
 set "GOARCH=amd64"
 
+REM Create the target directory before invoking Go so custom output paths work.
 for %%I in ("%OUTPUT%") do set "OUTDIR=%%~dpI"
 if not exist "%OUTDIR%" mkdir "%OUTDIR%"
 
+REM windres embeds the .ico file into the PE executable so Windows Explorer,
+REM shortcuts, and the taskbar can show the PySentry icon. The Go embed package
+REM handles Fyne's runtime icon, but Explorer reads this Windows resource instead.
 where windres.exe >nul 2>nul
 if %ERRORLEVEL%==0 (
     windres.exe -O coff -o cmd\pysentry\rsrc_windows_amd64.syso packaging\windows\pysentry.rc
 )
 
+REM -trimpath removes local machine paths from the binary, -s -w reduce binary
+REM size, and -H=windowsgui prevents a separate console window from opening when
+REM the GUI app starts from Explorer or a shortcut.
 "%GOEXE%" build -trimpath -ldflags "-s -w -H=windowsgui" -o "%OUTPUT%" .\cmd\pysentry
 if errorlevel 1 exit /b 1
 
+REM Icons are embedded into the executable, so no assets directory is copied next
+REM to the binary. Runtime YAML and log files are created by the app itself.
 echo Built %OUTPUT%