chore(release): prepare V1.0.2

Docs/Architecture.md

@@ -72,6 +72,8 @@
 - Distribution target: `Developer ID + Hardened Runtime + Notarization`
 - Initial release target: direct distribution, not Mac App Store
 - Native packaging currently uses `xcodegen + xcodebuild`, embeds the helper into `Contents/Helpers/`, and emits `.zip`, `.dmg`, and `.pkg` distribution artifacts.
+- Tagged GitHub Releases reuse the same native packaging scripts in CI and publish `.zip`, `.dmg`, `.pkg`, and checksum assets.
+- When release signing credentials are configured, CI signs and notarizes those assets; otherwise it falls back to a local development signing identity and marks the GitHub Release as a prerelease.
 - Local internal packaging now prefers a stable non-ad-hoc app signature when a usable identity is available, so macOS TCC decisions can survive rebuilds more reliably during development.
 - If Apple release certificates are unavailable, Atlas can fall back to a repo-managed local signing keychain for stable app-bundle identity; public release artifacts still require `Developer ID`.
 

Docs/DECISIONS.md

@@ -40,6 +40,8 @@
 
 - Destructive helper actions use a structured executable boundary with path validation
 - Native MVP packaging uses `xcodegen + xcodebuild`, then embeds the helper into the app bundle
+- Tagged GitHub Releases should publish the native `.zip`, `.dmg`, and `.pkg` assets from CI using the same packaging scripts as local release builds
+- If CI lacks `Developer ID` release credentials, tagged native assets may still be published as development-signed prereleases instead of blocking the packaging path entirely
 - Signing and notarization remain optional release-time steps driven by credentials
 - Internal packaging should prefer a stable local app-signing identity over ad hoc signing whenever possible so macOS permission state does not drift across rebuilds
 

Docs/Execution/Release-Signing.md

@@ -16,6 +16,7 @@ Turn Atlas for Mac from an installable local build into a publicly distributable
 - `ATLAS_CODESIGN_KEYCHAIN`
 - `ATLAS_INSTALLER_SIGN_IDENTITY`
 - `ATLAS_NOTARY_PROFILE`
+- `ATLAS_NOTARY_KEYCHAIN` (optional; required when the notary profile lives in a non-default keychain such as CI)
 
 ## Stable Local Signing
 
@@ -43,6 +44,28 @@ Run:
 
 If preflight passes, the current machine is ready for signed packaging.
 
+## Version Prep
+
+Before pushing a release tag, align the app version, build number, and changelog skeleton:
+
+```bash
+./scripts/atlas/prepare-release.sh 1.0.2
+```
+
+Optional arguments:
+
+```bash
+./scripts/atlas/prepare-release.sh 1.0.2 3 2026-03-14
+```
+
+This updates:
+
+- `project.yml`
+- `Apps/AtlasApp/Sources/AtlasApp/AtlasAppModel.swift`
+- `CHANGELOG.md`
+
+The script increments `CURRENT_PROJECT_VERSION` automatically when you omit the build number. Review the new changelog section before creating the `V1.0.2` tag.
+
 ## Signed Packaging
 
 Run:
@@ -56,6 +79,12 @@ ATLAS_NOTARY_PROFILE="<profile-name>" \
 
 This signs the app bundle, emits `.zip`, `.dmg`, and `.pkg`, submits artifacts for notarization, and staples results when credentials are available.
 
+If the notary profile is stored in a non-default keychain, also set:
+
+```bash
+ATLAS_NOTARY_KEYCHAIN="/path/to/release.keychain-db"
+```
+
 ## Install Verification
 
 After packaging, validate the DMG installation path with:
@@ -64,7 +93,52 @@ After packaging, validate the DMG installation path with:
 KEEP_INSTALLED_APP=1 ./scripts/atlas/verify-dmg-install.sh
 ```
 
+## GitHub Tag Release Automation
+
+Tagged pushes matching `V*` now reuse the same packaging flow in CI and attach native release assets to the GitHub Release created by `.github/workflows/release.yml`.
+
+Required GitHub Actions secrets:
+
+- `ATLAS_RELEASE_APP_CERT_P12_BASE64`
+- `ATLAS_RELEASE_APP_CERT_P12_PASSWORD`
+- `ATLAS_RELEASE_INSTALLER_CERT_P12_BASE64`
+- `ATLAS_RELEASE_INSTALLER_CERT_P12_PASSWORD`
+- `ATLAS_NOTARY_KEY_ID`
+- `ATLAS_NOTARY_ISSUER_ID` for Team API keys; omit only if you intentionally use an Individual API key
+- `ATLAS_NOTARY_API_KEY_BASE64`
+
+If those secrets are present, the workflow bootstraps a temporary keychain with `./scripts/atlas/setup-release-signing-ci.sh`, stores a `notarytool` profile there, derives `ATLAS_VERSION` from the pushed tag name, then runs `./scripts/atlas/package-native.sh`.
+
+If those secrets are missing, the workflow automatically falls back to:
+
+- `./scripts/atlas/ensure-local-signing-identity.sh`
+- local development signing for the app bundle
+- unsigned installer packaging if no installer identity exists
+- no notarization
+- GitHub Release marked as `prerelease`
+
+Release flow:
+
+```bash
+git tag -a V1.0.2 -m "Release V1.0.2"
+git push origin V1.0.2
+```
+
+That tag creates one GitHub Release containing:
+
+- legacy Go binaries and Homebrew tarballs from the existing release pipeline
+- `Atlas-for-Mac.zip`
+- `Atlas-for-Mac.dmg`
+- `Atlas-for-Mac.pkg`
+- native and aggregate SHA-256 checksum files
+
+Packaging mode by credential state:
+
+- `Developer ID secrets present` -> signed and notarized native assets, normal GitHub Release
+- `Developer ID secrets missing` -> development-signed native assets, GitHub `prerelease`
+
 ## Current Repo State
 
 - Internal packaging can now use a stable local app-signing identity instead of ad hoc signing.
 - Signed/notarized release artifacts remain blocked only by missing Apple release credentials on this machine.
+- Tagged GitHub Releases can still publish development-mode native assets without those credentials.