build-and-verify

1# Build and verify
2 
3A change is done when four things are true:
4 
51. `./build.sh` finishes with no errors.
62. You looked at the light and dark snapshots of every page you touched.
73. The snapshots match what the user story or reference screenshot asks for.
84. The grid checks pass (`layout-grid` skill).
9 
10App not made from the `new-mac-app` template (Xcode, XcodeGen, a menu bar
11utility, Swift 5)? Map the commands below with
12[existing-app.md](existing-app.md) first.
13 
14Do not report a UI change as done from the code alone. SwiftUI code that
15compiles can still render an empty sidebar, clipped text, or unreadable dark
16mode.
17 
18## 1. Build
19 
20```bash
21./build.sh            # release build, installs ~/Applications/<AppName>.app
22./build.sh --debug    # faster build while iterating
23./build.sh --open     # also restarts the app so the user sees the new build
24```
25 
26Read the errors, fix them, and build again. Fix the first error first: later
27errors often come from it. If a new file is "not in scope" right after you
28created it, run `swift package clean --scratch-path ~/Library/Developer/<AppName>/build`.
29 
30## 2. Snapshot
31 
32Run the installed binary directly with a test database and a folder for the
33images. The app opens, walks through every sidebar page and every Settings
34tab in light and dark mode, saves one PNG per page and mode, and quits.
35 
36```bash
37tools/snap.sh
38# SNAPSHOT /tmp/<AppName>-shots/all-light.png
39# ...
40# SNAPSHOT done /tmp/<AppName>-shots
41```
42…