docs/KB.md
Repository knowledge
Contribution guides
AGENTS.md defines the project map, change boundaries, mail privacy safeguards and verification requirements for agents. CONTRIBUTING.md provides setup, focused-change and pull-request steps for people and AI contributors. Read these before changing the repository.
Desktop targets
Aggregate Mail shares its React renderer, Electron main process and bundled mail service across Windows and macOS. npm run package builds Windows NSIS; npm run package:mac builds macOS DMG and ZIP files on a Mac. Package names include the macOS architecture. See installation and storage, product scope and ADR 0001.
The macOS target disables app and DMG signing and notarization. The Windows release workflow is unchanged. Building a package does not publish it or prove Gatekeeper acceptance.
Verification
Run npm test and npm run build before packaging. The desktop startup check opens the encrypted database, loads the renderer, requires the desktop token for API access and checks native menu roles on macOS. Use a temporary user-data directory so checks cannot open a maintainer's accounts:
| 1 | check_dir=$(mktemp -d) |
| 2 | npm run check:desktop -- --user-data-dir="$check_dir" |
For a packaged Apple silicon build, use the logged-in macOS desktop session. Quit any running copy first, since the mail service uses a fixed port:
| 1 | check_dir=$(mktemp -d) |
| 2 | open -n -W "release/mac-arm64/Aggregate Mail.app" \ |
| 3 | --stdout "$check_dir/stdout.log" --stderr "$check_dir/stderr.log" \ |
| 4 | --args --check-startup --user-data-dir="$check_dir/profile" |
| 5 | cat "$check_dir/stdout.log" "$check_dir/stderr.log" |
Require a startup: passed JSON result and process exit, then remove only the temporary directory created for that check. An open exit alone is insufficient. Intel builds use release/mac/. These checks do not drive the UI, authenticate real accounts or send mail. A direct SSH executable launch can lack Keychain access even when desktop launch works. Keychain availability is required; an access failure is a blocker, not a reason to replace encryption.
The repository has no scripts/documentation.py; documentation checks currently require link and diff review.
Public contribution boundary
Keep credentials, personal contact details, absolute machine paths, private hostnames, session records and mailbox contents out of source, commits, PRs and release attachments. Use synthetic test data and portable commands. Preserve the project's existing identity. Review commit author and committer metadata before pushing. Ignore rules and package exclusions are preventive controls; scan the final source diff and package contents too. A pattern scan cannot prove the absence of all sensitive information.