AGENTS.md

1# macOS development
2- Don't use xcode directly to develop
3- Use pure swift 5.8 code to make the app. No interface builder. No SwiftUI.
4- Aim for compact code. Within methods, don't have groups of statements separated with newlines. No inline comments for simple code. Instead, split statements into sub-methods.
5- Use guard closes as much as possible to separate the happy-path under them
6- Organize source files into folders. Folders should group files that change together, at the same pace (e.g. one feature)
7- When possible, follow the triad pattern: specs in *Specs.md, unit-tests in *Tests.swift, and *swift for the implementation. Document features and their edge-cases this way
8- Favor low latency and responsiveness. Reuse objects, avoid wasting memory or I/O. Use observer APIs; don't poll.
9 
10# Workflow
11- Copy commands from ai/build.sh and run them, to confirm compilation works after you're done with implementing a change
12- Git commit messages must respect our pre-hook conventions, and must be clear and high-level, written for end-users (changelog)
13 
14# License / Keychain invariant
15- The app's Developer ID, TeamID, and bundle ID must remain stable across builds. Keychain items are tied to the code signature; changing any of these orphans every user's stored license key and forces mass re-activation. If a rotation is unavoidable, plan a migration first (e.g., a backup-restore handler, or `kSecAttrAccessGroup` with a stable group identifier).
16- Do not introduce legacy `SecKeychain*` API or `kSecAccessControl` (biometric/PIN gating) into license code — both can trigger Keychain password prompts, which is bad UX for license activation.
17