docs: add openspec proposals for macOS release distribution

Add change proposals for code signing, release automation, Homebrew tap,
Sparkle auto-updates, and website landing page. Update first-launch-welcome
proposal and specs to use Mailman mailing list instead of in-app data
collection. Update privacy-settings spec to remove registration controls.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: dionmcm

openspec/changes/first-launch-welcome/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-05

openspec/changes/first-launch-welcome/proposal.md

@@ -0,0 +1,40 @@
+## Why
+
+We want to know who our users are (not just how many), build a contact list of engaged users, and encourage GitHub stars for visibility. Rather than collecting personal data in-app (which creates GDPR and Privacy Act obligations), we leverage CSIRO's existing Mailman infrastructure to offer an opt-in mailing list. This keeps the app free of personal data while giving us a communication channel with users.
+
+## What Changes
+
+- Show a first-launch welcome screen on first launch (or upgrade for existing users who haven't seen it)
+- Invite users to star the project on GitHub
+- Invite users to join the Codeagogo mailing list via a button that opens the Mailman subscription page in their browser
+- Add a "Show Welcome Screen" control to the Privacy section in Settings
+- Update PRIVACY.md to mention the mailing list (no personal data is collected by the app)
+
+## Capabilities
+
+### New Capabilities
+- `first-launch-welcome`: One-time welcome screen shown on first launch (or upgrade if not previously shown). Invites GitHub star and mailing list subscription via external Mailman page. The app never collects, stores, or transmits personal data. Never linked to anonymous usage metrics.
+
+### Modified Capabilities
+- `privacy-settings`: Add "Show Welcome Screen" button to the existing Privacy section (added by the `anonymous-install-metrics` change). Registration status and "Clear Registration" are no longer needed since the app stores no personal data.
+
+## Impact
+
+- **AppDelegate.swift**: Welcome screen trigger added to launch sequence
+- **SettingsView.swift**: "Show Welcome Screen" button added to Privacy GroupBox
+- **PRIVACY.md**: Updated to mention mailing list link (no personal data collected by app)
+- **CHANGELOG.md**: New entry
+- **New files**: `WelcomeSettings.swift`, `WelcomeView.swift`, plus test files
+- **No breaking changes**
+- **No new dependencies**
+
+## Design Decisions
+
+1. **Mailman over in-app collection**: CSIRO runs Mailman-managed lists (e.g. ontoserver-announce) that are one-way, opt-in, user-managed, and IM&T-supported. Using Mailman means:
+   - The app collects zero personal data (near-zero privacy compliance burden)
+   - Double opt-in consent via Mailman's confirmation email (GDPR gold standard)
+   - Users can self-manage subscription (subscribe/unsubscribe without our involvement)
+   - Infrastructure is maintained by CSIRO IM&T, not us
+   - Well-understood social contract ("join our mailing list")
+
+2. **No personal data in the app**: Since the app just opens a URL, there are no name/email fields, no UserDefaults storage of personal info, no "Clear Registration" button needed, and no data breach notification obligations for the app.

openspec/changes/homebrew-tap/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-06

openspec/changes/homebrew-tap/proposal.md

@@ -0,0 +1,35 @@
+## Why
+
+Homebrew is the dominant package manager on macOS. A Homebrew tap lets users install and update Codeagogo with a single command, which is the expected experience for developer and clinical informatician audiences.
+
+## What Changes
+
+- Add a Homebrew Cask formula at `Casks/codeagogo.rb` in this repository
+- Formula points to the signed `.dmg` on GitHub Releases
+- Document the installation instructions in README and on the website
+
+## Capabilities
+
+### New Capabilities
+- `homebrew-tap`: Homebrew Cask formula in the existing repository, enabling `brew tap aehrc/codeagogo https://github.com/aehrc/codeagogo && brew install --cask codeagogo`. Formula references the GitHub Releases download URL and SHA256 hash of the signed `.dmg`.
+
+### Modified Capabilities
+<!-- None -->
+
+## Impact
+
+- **New file**: `Casks/codeagogo.rb`
+- **README.md**: Updated with Homebrew installation instructions
+- **Release process**: Each release needs the Cask formula updated with new version and SHA256
+- **No new repositories** — formula lives in the existing mac app repo
+- **No code changes to Codeagogo itself**
+
+## Prerequisites
+
+- `macos-code-signing` change completed (signed `.dmg` available)
+- At least one GitHub Release published with the signed `.dmg`
+
+## Open Questions
+
+1. **Formula update automation**: Manually update the formula per release, or automate via GitHub Actions in the release workflow?
+2. **Submission to homebrew-cask main**: Worth doing once we have user numbers. Requires minimum notability — revisit after launch.

openspec/changes/macos-code-signing/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-06

openspec/changes/macos-code-signing/proposal.md

@@ -0,0 +1,39 @@
+## Why
+
+Unsigned macOS apps trigger Gatekeeper warnings ("this app can't be opened because it is from an unidentified developer"), which is a significant barrier to adoption — especially for a tool that requires Accessibility permissions. Developer ID signing plus Apple notarization removes this friction entirely.
+
+## What Changes
+
+- Update `package-zip.sh` (or replace with a new `release.sh`) to include Developer ID code signing, notarization via `notarytool`, and stapling
+- Add a `.dmg` packaging step (drag-to-Applications disk image) as the primary distribution format
+- Document the signing prerequisites and release process
+- Add entitlements file if not already present (Accessibility, Hardened Runtime)
+
+## Capabilities
+
+### New Capabilities
+- `macos-code-signing`: Build script that signs the app with a Developer ID certificate, submits to Apple for notarization, waits for approval, and staples the notarization ticket to the binary. Produces a signed, notarized `.dmg` ready for distribution.
+
+### Modified Capabilities
+<!-- None -->
+
+## Impact
+
+- **package-zip.sh**: Replaced or extended with signing/notarization steps
+- **Codeagogo.entitlements**: May need updates for Hardened Runtime compatibility
+- **New files**: `release.sh` (or equivalent), release documentation
+- **No code changes** — this is build/packaging only
+- **No new dependencies** (uses Xcode command-line tools)
+
+## Prerequisites
+
+- Apple Developer Program team seat (via CSIRO Publications)
+- Developer ID Application certificate installed in keychain
+- App-specific password or API key for `notarytool`
+- Team ID for notarization submission
+
+## Open Questions
+
+1. **Certificate access**: Will we use a shared team certificate or an individual one? Affects CI/CD setup.
+2. **DMG vs ZIP**: DMG with drag-to-Applications is more polished; ZIP is simpler. Recommend DMG.
+3. **Entitlements**: Need to verify Hardened Runtime compatibility with Accessibility APIs and Carbon hotkeys.

openspec/changes/release-automation/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-06

openspec/changes/release-automation/proposal.md

@@ -0,0 +1,37 @@
+## Why
+
+Manual release processes are error-prone and slow. A GitHub Actions workflow that builds, signs, packages, and publishes macOS releases ensures consistent, reproducible releases and removes the bus factor of needing a specific person's machine.
+
+## What Changes
+
+- Add a GitHub Actions workflow triggered by version tags (e.g. `v1.0.0`)
+- Build, sign with Developer ID, notarize, staple, package as `.dmg`
+- Create a GitHub Release with the `.dmg` attached and auto-generated release notes
+- Update Homebrew tap formula (if automated)
+
+## Capabilities
+
+### New Capabilities
+- `release-automation`: GitHub Actions workflow that produces a signed, notarized macOS `.dmg` from a version tag push. Creates a GitHub Release with the artifact attached.
+
+### Modified Capabilities
+<!-- None -->
+
+## Impact
+
+- **New files**: `.github/workflows/release.yml`, release documentation
+- **Secrets required**: Apple Developer ID cert + password, Apple API key for notarytool
+- **No code changes** — CI/CD only
+- **No new dependencies**
+
+## Prerequisites
+
+- `macos-code-signing` change completed (signing script exists to call)
+- GitHub repo secrets configured for signing certificate
+- Apple signing credentials available in CI
+
+## Open Questions
+
+1. **Self-hosted vs GitHub runners**: macOS signing may need a self-hosted runner if the certificate can't be installed in CI. GitHub-hosted macOS runners work but are slower and more expensive for private repos.
+2. **Release notes**: Auto-generate from CHANGELOG.md or write manually per release?
+3. **Depends on open/closed source decision**: Free CI/CD minutes for public repos; limited for private.

openspec/changes/sparkle-updates/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-06

openspec/changes/sparkle-updates/proposal.md

@@ -0,0 +1,54 @@
+## Why
+
+Without auto-updates, users must manually check GitHub for new versions. Sparkle is the de facto standard framework for macOS app updates outside the App Store — used by Firefox, VLC, iTerm2, and hundreds of other apps. It handles checking for updates, downloading, verifying signatures, and installing — all in-app with no browser required. Auto-update should be enabled by default so users always have the latest version.
+
+## What Changes
+
+- Integrate the Sparkle 2.x framework via Swift Package Manager
+- Host an appcast XML file (version feed) on the website or in the repo
+- Sign updates with an Ed25519 key for integrity verification
+- Add "Check for Updates" menu item and auto-check on launch (enabled by default)
+- Add update preferences to Settings (auto-check on/off, check now button)
+- Update the release process to generate appcast entries and sign update archives
+
+## Capabilities
+
+### New Capabilities
+- `sparkle-updates`: In-app update mechanism using the Sparkle framework. Checks an appcast feed for new versions. Downloads, verifies (Ed25519 signature), and installs updates in-place. Auto-check is enabled by default. Users can check manually via menu item or disable automatic checks in Settings.
+
+### Modified Capabilities
+- `privacy-settings`: Add update check preferences (auto-check on/off, check now button) to the Settings view.
+
+## Impact
+
+- **AppDelegate.swift**: Initialize Sparkle updater, add "Check for Updates" menu item
+- **SettingsView.swift**: Add update preferences section
+- **Info.plist**: Add Sparkle configuration keys (feed URL, public key)
+- **Release process**: Generate and sign appcast entries using `generate_appcast` tool
+- **New dependency**: Sparkle 2.x framework (via Swift Package Manager) — MIT licence, open source
+- **CHANGELOG.md**: New entry
+
+## How Sparkle Works
+
+1. App checks the appcast URL on a schedule (default: daily, configurable)
+2. Appcast lists versions with download URLs, Ed25519 signatures, and release notes
+3. If a newer version exists, Sparkle shows an update dialog with release notes
+4. User clicks "Install Update" — Sparkle downloads the archive, verifies the signature, replaces the app, and relaunches
+5. No browser, no manual download, no drag-to-Applications
+
+## Prerequisites
+
+- `macos-code-signing` change completed (signed builds required for updates)
+- Appcast hosting decided (website or repo — see `website-landing-page` change)
+- Ed25519 key pair generated for update signing (separate from Apple code signing)
+
+## Notes
+
+- This is the first external dependency in the project. Sparkle is MIT-licenced, widely used, and actively maintained. The alternative (rolling our own update checker) would be significantly more work for a worse result.
+- Auto-check is enabled by default with a daily interval. Users can disable it in Settings.
+
+## Open Questions
+
+1. **Appcast hosting**: On the website (alongside the landing page) or committed to the repo (served via GitHub raw URL)?
+2. **Appcast generation**: Automate with `generate_appcast` tool (ships with Sparkle) in the release workflow, or maintain manually? Recommend automating.
+3. **Delta updates**: Sparkle supports binary diffs (smaller downloads). Worth enabling or overkill for a small app?