Merge pull request #160 from thawn/copilot/add-docs-unsigned-executables

Document unsigned executable warnings for macOS and Windows

Author: thawn

docs/building-executables.md

@@ -115,7 +115,19 @@ Or double-click the app bundle in Finder.
 
 **Bundled binaries not found**: Verify `lib/` directory structure in spec files
 
-**macOS Gatekeeper issues**: Users must right-click → Open first time. For distribution, sign and notarize with Apple Developer certificate.
+**macOS Gatekeeper issues**: Users must right-click → Open first time ([bypass instructions](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac))
+
+**Windows SmartScreen issues**: Users must click "More info" → "Run anyway" ([bypass instructions](https://support.microsoft.com/en-us/windows/what-is-smartscreen-and-how-can-it-help-protect-me-1c9a874a-6826-be5e-45b1-67fa445a74c8))
+
+## Code Signing
+
+The distributed executables are **not code-signed** as code signing certificates are not available. This causes security warnings on macOS and Windows:
+- **macOS**: Gatekeeper warning - users must right-click → Open
+- **Windows**: SmartScreen warning - users must click "More info" → "Run anyway"
+
+To sign executables for distribution, you would need:
+- **macOS**: Apple Developer account and notarization ($99/year)
+- **Windows**: Code signing certificate from trusted CA ($100-400/year)
 
 ## Notes
 

docs/installation.md

@@ -4,6 +4,8 @@
 
 Download pre-built executables from [releases page](https://github.com/thawn/ttmp32gme/releases), extract, and run. Open `http://localhost:10020` in browser.
 
+**⚠️ Security Warning**: The executables are unsigned as code signing certificates are not available. Your OS will show security warnings on first run.
+
 **Requirements**:
 - Chrome or Chromium browser (optional, for PDF generation) - [Download Chrome](https://www.google.com/chrome/)
   - Note: Chromium is only needed if printing directly from your browser doesn't work. You can print control sheets directly from most browsers without Chromium.
@@ -14,8 +16,10 @@ Download pre-built executables from [releases page](https://github.com/thawn/ttm
    - `ttmp32gme-macos.zip` for macOS
 2. Extract the ZIP file to a location of your choice
 3. Run the executable:
-   - Windows: Double-click `ttmp32gme.exe` or run from command prompt
-   - macOS: Right-click `ttmp32gme.app` → Open (first time only to bypass Gatekeeper)
+   - **Windows**: Double-click `ttmp32gme.exe` or run from command prompt
+     - If Windows SmartScreen blocks it: Click "More info" → "Run anyway" ([details](https://support.microsoft.com/en-us/windows/what-is-smartscreen-and-how-can-it-help-protect-me-1c9a874a-6826-be5e-45b1-67fa445a74c8))
+   - **macOS**: Right-click `ttmp32gme.app` → "Open" (first time only to bypass Gatekeeper)
+     - If blocked: System Settings → Privacy & Security → scroll down → "Open Anyway" ([details](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac))
 4. Open your browser to `http://localhost:10020`
 
 The executable includes all necessary dependencies (tttool, ffmpeg) except Chrome/Chromium which should be installed separately.

docs/troubleshooting.md

@@ -2,6 +2,8 @@
 
 ## Installation
 
+**Security warnings (Windows/macOS executables)**: The executables are unsigned. Windows SmartScreen: Click "More info" → "Run anyway". macOS Gatekeeper: Right-click → "Open", or System Settings → Privacy & Security → "Open Anyway". See [Installation](installation.md) for details.
+
 **Python version error**: Use Python 3.11+ (`python3.11 -m pip install -e .` or `uv pip install -e .`)
 
 **tttool not found**: Install tttool ([instructions](installation.md)), check PATH