@@ -0,0 +1,29 @@
1+# HyperCreditsMenubar
2+
3+## Architecture
4+macOS menu bar app (SwiftUI, macOS 14+) showing Hyper (Charm) credit balance.
5+- `HyperCreditsApp.swift` — @main App, NSStatusBar, timer, sleep/wake, popover
6+- `ViewModel.swift` — Observable state: balance, refresh, notifications, history
7+- `MenuView.swift` — SwiftUI popover view (balance, sparkline, settings)
8+- `CreditsChecker.swift` — API client for `GET https://hyper.charm.land/v1/credits`
9+- `KeychainHelper.swift` — Keychain wrapper (KeychainStore + KeychainHelper)
10+- `VersionFormatter.swift` — Version string formatting
11+
12+## Build
13+- Uses [xcodegen](https://github.com/yonaskolb/XcodeGen) — `project.yml` is source of truth
14+- `xcodegen generate` creates the .xcodeproj (not committed)
15+- Build: `xcodebuild -scheme HyperCreditsMenubar -configuration Debug build`
16+- Test: `xcodebuild test -scheme HyperCreditsMenubar -configuration Debug -destination "platform=macOS"`
17+- Swift 5.9, macOS 14.0 deployment target
18+
19+## Conventions
20+- Clean minimal UI — big hero number, generous spacing, restrained color, no chrome
21+- No card-heavy/multi-material/gradient-rich designs
22+- Rounded font family at 4 sizes (hero/section/control/caption/footnote)
23+- Monospaced digits for numbers that change
24+- Tests use StubURLProtocol for network mocking, FakeKeychain for keychain mocking
25+- The app is an agent app (LSUIElement=true) — no dock icon, no main window
26+
27+## VCS
28+- jj colocated with git
29+- Push directly to master — no PRs for this repo