How to build Frostnotes from source, run it, and run its gates. The rules for changes are in AGENTS.md; the architecture starts at design/overview.md. The reasons for this setup are in ADR-0009.
- On the host: Go 1.27 (
go.modnames the toolchain) andmise install, which installs the tools pinned inmise.toml(golangci-lint, svu, nfpm). - For the web app: an nsl machine. Its
toolchain (Node, pnpm) lives only there (
dev/nsl/provision.sh); never run pnpm or node on the host. The native desktop app builds on the host.
make build # build/notesd and build/notesctl
build/notesd & # the daemon; one per user
build/notesctl vault add ~/Notes # registering never writes to the vault
build/notesctl search quince
claude mcp add frostnotes -- "$PWD/build/notesctl" mcp # or: mcp --read-onlyEvery write, an agent's included, is kept as a version for 30 days:
notesctl versions PATH lists them and notesctl revert undoes one
(design/vault.md).
The native app (plan 0009) is pure Go, and needs GTK 3, Pango and cairo at run time, not at build time. Its tests draw headless and need only Pango, cairo and a font.
make desktop-runmake desktop-build makes the release binary, make desktop-smoke starts it
under Xvfb against a real notesd, and make desktop-evidence records the
10,000-note and phone-to-desktop evidence. FROSTNOTES_SCREENS=DIR go test -run TestEveryScreenDraws ./internal/desktop/window writes each screen's
picture to DIR.
nsl create frostnotes --distro debian:13
nsl run -m frostnotes --root bash dev/nsl/provision.sh "$(id -un)"The Makefile's app targets run in the machine named frostnotes
(NSL_MACHINE changes it).
make check # host: generated files, vet, lint, unit tests
make ci # make verify, the race tests and the app checks (nsl)
make ui-check # nsl: Biome, typecheck and UI tests
make desktop-run # host: the native app against the running notesd
make ui-dev # nsl: notesd and Vite; open http://127.0.0.1:5173make help lists every target. AGENTS.md says
which gate a change needs, and which integration runs a change to the
scan, the write path or parsing needs.