diff --git a/buildinfo/buildinfo.go b/buildinfo/buildinfo.go
new file mode 100644
index 0000000..d8ffeba
--- /dev/null
+++ b/buildinfo/buildinfo.go
@@ -0,0 +1,35 @@
+// Package buildinfo exposes compile-time build metadata for every Go
+// binary in instanode.dev (api / worker / provisioner / cli).
+//
+// The three vars are wired in at link time via the Go linker's
+// `-X` flag:
+//
+//	go build -ldflags "-X instant.dev/common/buildinfo.GitSHA=abc1234 \
+//	                   -X instant.dev/common/buildinfo.BuildTime=2026-05-12T16:00:00Z \
+//	                   -X instant.dev/common/buildinfo.Version=v3.6.0" ./...
+//
+// Defaults are sentinel strings (`dev` / `unknown`) so an un-flagged
+// `go build` still produces a runnable binary — useful for local
+// `make run` and `go test ./...`. CI and the Dockerfiles always pass
+// real values via `--build-arg`.
+//
+// Consumers (slog handlers, /healthz, /api/v1/buildinfo, the worker's
+// startup log, NR custom attributes) read these vars directly. The
+// package has zero deps so it is safe to import from any other
+// package without creating cycles.
+package buildinfo
+
+// GitSHA is the short Git SHA of the commit the binary was built from.
+// Set at link time via -ldflags. Defaults to "dev" for un-flagged
+// local builds.
+var GitSHA = "dev"
+
+// BuildTime is the RFC-3339 UTC timestamp the binary was built at.
+// Set at link time via -ldflags. Defaults to "unknown" for un-flagged
+// local builds.
+var BuildTime = "unknown"
+
+// Version is the semver / release tag the binary was built from.
+// Set at link time via -ldflags. Defaults to "dev" for un-flagged
+// local builds.
+var Version = "dev"
diff --git a/buildinfo/buildinfo_test.go b/buildinfo/buildinfo_test.go
new file mode 100644
index 0000000..f6ee732
--- /dev/null
+++ b/buildinfo/buildinfo_test.go
@@ -0,0 +1,48 @@
+package buildinfo
+
+import "testing"
+
+// The three vars are package-level globals overwritten by `-ldflags -X`
+// at link time. These tests verify:
+//
+//  1. The names are reachable from importers (compile-time check).
+//  2. Default values match the documented sentinels — "dev" / "unknown".
+//     If a default changes accidentally, log enrichment and /healthz
+//     would silently report the new sentinel as truth, masking missing
+//     -ldflags in CI.
+//
+// The real -ldflags injection check is the `make smoke-buildinfo`
+// target — it builds a separate binary with -X overrides and verifies
+// the runtime value matches. That cannot be done from within the same
+// package's `go test` because the Go test binary itself is the linked
+// artifact under test (and we don't want to mutate package globals
+// from tests — flaky if any other test cares about them).
+
+func TestDefaults(t *testing.T) {
+	t.Run("GitSHA default", func(t *testing.T) {
+		if GitSHA != "dev" {
+			t.Errorf("GitSHA default = %q, want %q", GitSHA, "dev")
+		}
+	})
+	t.Run("BuildTime default", func(t *testing.T) {
+		if BuildTime != "unknown" {
+			t.Errorf("BuildTime default = %q, want %q", BuildTime, "unknown")
+		}
+	})
+	t.Run("Version default", func(t *testing.T) {
+		if Version != "dev" {
+			t.Errorf("Version default = %q, want %q", Version, "dev")
+		}
+	})
+}
+
+// TestReachable is a trivial compile-time check that the three exported
+// names are addressable from outside the package. If a refactor renames
+// or unexports any of them, ~306 slog log callsites and three /healthz
+// handlers stop compiling — but this catches it immediately at the
+// package boundary.
+func TestReachable(t *testing.T) {
+	_ = GitSHA
+	_ = BuildTime
+	_ = Version
+}