From a96c0c5b18de38d581277b7901941cf5bce35474 Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Tue, 14 Jul 2026 15:22:17 +0000
Subject: [PATCH] docs(#200): document mint deploy-time source stamping pattern

Add prescriptive guidance to the Mint function section of AGENTS.md
explaining that build metadata for the mint Cloud Function should
use deploy-time source stamping rather than runtime environment
variables. This prevents metadata from drifting out of sync with
the deployed function code.

The paragraph uses aspirational language describing the intended
pattern, since the mechanism is not yet fully implemented in the
codebase. It guides future agents to choose source stamping over
env vars when adding build metadata to the Cloud Function.

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

diff --git a/AGENTS.md b/AGENTS.md
index 5620b735f..31e7425b8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,6 +27,8 @@ When changing `internal/mint/main.go`, always copy it to `internal/dispatch/gcf/
 
 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.
 
+**Build metadata stamping:** When the mint Cloud Function needs version, commit, or other build metadata, inject it via deploy-time source stamping — not 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 the values baked in. This ensures metadata cannot drift from the deployed code. Follow the same pattern for any future build metadata the function needs: stamp it into source at bundle time rather than passing it as an environment variable.
+
 **Dispatch workflows:** The scaffold `dispatch.yml` (at `internal/scaffold/fullsend-repo/.github/workflows/dispatch.yml`) and the repo's `reusable-dispatch.yml` (at `.github/workflows/reusable-dispatch.yml`) share identical routing logic for different installation modes (per-org vs per-repo). When changing the jq payload construction, stage routing, or input/secret threading in one, apply the same change to the other.
 
 When making changes to Go code under `cmd/` or `internal/`: