From d1f57a8a930f77ad312ec0b24f706bc27d46491f Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Fri, 10 Jul 2026 12:50:05 +0000
Subject: [PATCH] docs(#232): document mint deploy-time source stamping pattern

Add a paragraph to the Mint function section of AGENTS.md
documenting that build metadata (version, commit) must use
deploy-time source stamping, not runtime environment variables.
The provisioner should write a generated source file into the
function source zip at bundle time with values baked in, so
metadata cannot drift from the deployed code.

This prevents the env-var anti-pattern seen in upstream PR
#2909, where the code agent chose runtime env vars and a human
had to intervene to switch to source stamping.

Closes #232
---
 AGENTS.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 5620b735f..864b0b971 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,6 +23,8 @@ Fullsend is a platform for fully autonomous agentic development for GitHub-hoste
 
 When changing `internal/mint/main.go`, always copy it to `internal/dispatch/gcf/mintsrc/main.go.embed`. If `go.mod` or `go.sum` changed, sync those to `go.mod.embed` and `go.sum.embed` too.
 
+**Build metadata stamping:** When adding version or commit metadata to the mint Cloud Function, use deploy-time source stamping rather than runtime environment variables. The provisioner should write a generated source file (e.g., `mintcore/version.go`) into the function source zip at bundle time with values baked in, so metadata cannot drift from the deployed code. Follow this approach for any future build metadata the function needs — do not use environment variables for values that must stay in lockstep with the deployed source.
+
 **Mint client:** `internal/mintclient/` is the Go client for calling the mint service at runtime. It exchanges a GitHub Actions OIDC JWT for a role-scoped installation token. Unlike `internal/mint/` and `internal/mintcore/`, it has no embedded copies or sync requirements.
 
 The `internal/mintcore/` module is shared between the mint and devmint. Its files are also embedded for Cloud Function deployment at `internal/dispatch/gcf/mintsrc/mintcore/*.embed`. When changing any file in `internal/mintcore/`, sync it to the corresponding `.embed` file under `mintsrc/mintcore/`. Note: the mint's `go.mod.embed` uses `replace mintcore => ./mintcore` (not `../mintcore`), because `provisioner.go` rewrites the replace directive at bundle time to match the deployed directory layout.