@nakedev/go-scaffold 0.1.2 → 0.1.4

package/templates/create/base/.github/workflows/ci.yml.hbs

@@ -14,7 +14,9 @@ jobs:
         env:
           POSTGRES_USER: postgres
           POSTGRES_PASSWORD: postgres
-          POSTGRES_DB: {{dbName}}
+          # repository integration tests run against this isolated database after
+          # applying the same versioned SQL migrations used in production
+          POSTGRES_DB: {{dbName}}_test
         ports:
           - 5432:5432
         options: >-
@@ -41,6 +43,19 @@ jobs:
         with:
           version: latest
 
-      # TEST_DB_DSN not set: the default in handler_test.go already points at
-      # localhost:5432/{{dbName}} with postgres/postgres, matching the service above
-      - run: go test ./...
+      - name: Install migration runner
+        run: go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.18.3
+
+      - name: Apply production migrations to the test database
+        env:
+          DB_DSN: postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable
+        run: |
+          if compgen -G "migrations/*.up.sql" > /dev/null; then
+            migrate -path migrations -database "$DB_DSN" up
+          fi
+
+      - name: Test (required PostgreSQL integration tests cannot skip)
+        env:
+          TEST_DB_DSN: postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable
+          REQUIRE_TEST_DB: "true"
+        run: go test ./...

package/templates/create/base/.gitignore.hbs

@@ -1,5 +1,7 @@
 app.db
 *.db
 .env
+.env.*
+!.env.example
 bin/
 docs/openapi.bundled.yaml

package/templates/create/base/AGENTS.md.hbs

@@ -45,21 +45,19 @@ hand-rolling anything that looks like scaffolding.
 
 ## Command quick reference
 
-- `go-scaffold generate module <name>` — model + dto + errors + repository +
-  service + handler + tests, wired into `cmd/api/main.go` (AutoMigrate +
-  route registration) and appended to `migrations/`. Use `--no-full` for a
-  bare skeleton (no default CRUD/routes) when you'd rather add endpoints one
-  at a time with `generate method`
+- `go-scaffold generate module <name>` — safe minimal model + errors +
+  repository + service/handler plumbing, wired into `cmd/api/main.go` and
+  appended to `migrations/`. Add endpoints one at a time with `generate
+  method`, or pass `--full` to opt into a CRUD skeleton with TODO DTO fields
 - `go-scaffold generate method <module> <name> --type <get|post|put|patch|delete> [--get-mode all|one] [--field <name>]` —
   patches an *existing* module's handler + service (and repository, for a
   `get --get-mode one --field` lookup) in place; never overwrites a method
-  with the same name — pick a different one if it collides. Endpoint docs in
-  `docs/openapi.yaml` are **not** auto-updated for methods — the command
-  prints the route so you can add the spec entry by hand
-- `go-scaffold remove module <name>` — the inverse of `generate module`:
-  deletes the package and un-wires main.go / openapi.yaml / migrations. Use
-  this to drop a domain instead of hand-deleting the folder (a partial
-  hand-delete leaves duplicate wiring behind)
+  with the same name — pick a different one if it collides. With OpenAPI
+  enabled it also writes a valid TODO path document and wires the index;
+  replace placeholder schemas while implementing the method
+- `go-scaffold remove module <name>` — deletes the package and un-wires
+  main.go/OpenAPI while preserving immutable migrations and table data. Use
+  `generate migration drop_<table>` for an explicit reviewed data removal
 - Every route in this project is grouped under{{#if apiPrefix}} `/{{apiPrefix}}`{{else}} no prefix{{/if}}
   (set once at `create` time via `--api-prefix`) — there is no per-domain
   versioning; a breaking API change gets a new domain package or a new DTO

package/templates/create/base/Makefile.hbs

@@ -3,17 +3,34 @@ DB_PORT ?= 5432
 DB_USER ?= postgres
 DB_NAME ?= {{dbName}}
 PGPASSWORD ?= postgres
+POSTGRES_CONTAINER ?=
 
-.PHONY: run build test fmt vet lint tidy db-create db-drop migrate-up migrate-down{{#if openapiDocs}} openapi-bundle{{/if}}{{#if docker}} docker-up docker-down{{/if}}
+# which env file to load — defaults to .env (your local override, gitignored).
+# override to run against another file, e.g. copy .env.example to .env.production,
+# fill it in, then `make run ENV_FILE=.env.production`.
+#
+# Every target that needs config loads it the same way: drop whole-line comments
+# (^#) AND trailing ` # ...` comments — the sed only strips a `#` preceded by
+# whitespace, so a `#` inside a value (password, DSN) is kept. Without the sed,
+# `xargs` hands the comment's words to `export` too: `PORT=8080 # prod: PORT=80`
+# would export PORT twice and the comment's value would win. (Can't factor this
+# into a make variable: a `#` in a variable value starts a make comment; in a
+# recipe line it's passed to the shell untouched.)
+ENV_FILE ?= .env
+
+.PHONY: run build test fmt vet lint tidy db-create db-drop migrate-up migrate-down migrate-verify{{#if openapiDocs}} openapi-bundle{{/if}}{{#if docker}} docker-up docker-down{{/if}}
 
 run:
-	@[ -f .env ] && export $$(grep -v '^#' .env | xargs); go run ./cmd/api
+	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); go run ./cmd/api
 
 build:
 	go build -o bin/api ./cmd/api
 
+# loads ENV_FILE like every other target, so TEST_DB_DSN set there reaches the
+# integration tests. A bare `go test ./...` still works, but falls back to
+# whatever defaults the test files carry.
 test:
-	go test ./...
+	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); go test ./...
 
 fmt:
 	gofmt -w .
@@ -31,14 +48,17 @@ tidy:
 # connects to the always-present "postgres" maintenance DB to run CREATE DATABASE,
 # since the target DB may not exist yet. Safe to re-run — skips if it already exists.
 # \gexec only works read from stdin, not through -c, hence the pipe.
-# no local psql? falls back to `docker exec` into whatever container is publishing
-# DB_PORT — the project's own `docker compose up`'d postgres, or an unrelated
-# shared Postgres container you already have running, either works the same way.
+# `POSTGRES_CONTAINER` selects an exact Docker container when no host psql is
+# installed; otherwise the fallback discovers a container publishing DB_PORT.
 # override DB_HOST/DB_PORT/DB_USER/DB_NAME/PGPASSWORD to point at a different server.
 db-create:
 	@if command -v psql >/dev/null 2>&1; then \
 		echo "SELECT 'CREATE DATABASE $(DB_NAME)' WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '$(DB_NAME)')\gexec" | \
 			PGPASSWORD=$(PGPASSWORD) psql -h $(DB_HOST) -p $(DB_PORT) -U $(DB_USER) -d postgres && echo "SUCCESS! database $(DB_NAME) is ready"; \
+	elif [ -n "$(POSTGRES_CONTAINER)" ]; then \
+		echo "no local psql — using docker exec into $(POSTGRES_CONTAINER)"; \
+		echo "SELECT 'CREATE DATABASE $(DB_NAME)' WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '$(DB_NAME)')\gexec" | \
+			docker exec -i -e PGPASSWORD=$(PGPASSWORD) $(POSTGRES_CONTAINER) psql -U $(DB_USER) -d postgres && echo "SUCCESS! database $(DB_NAME) is ready"; \
 	elif [ "$(DB_HOST)" = "localhost" ] || [ "$(DB_HOST)" = "127.0.0.1" ]; then \
 		container=$$(docker ps -q --filter "publish=$(DB_PORT)" | head -1); \
 		if [ -z "$$container" ]; then \
@@ -56,6 +76,8 @@ db-create:
 db-drop:
 	@if command -v psql >/dev/null 2>&1; then \
 		PGPASSWORD=$(PGPASSWORD) psql -h $(DB_HOST) -p $(DB_PORT) -U $(DB_USER) -d postgres -c "DROP DATABASE IF EXISTS $(DB_NAME);" && echo "SUCCESS! database $(DB_NAME) dropped"; \
+	elif [ -n "$(POSTGRES_CONTAINER)" ]; then \
+		docker exec -i -e PGPASSWORD=$(PGPASSWORD) $(POSTGRES_CONTAINER) psql -U $(DB_USER) -d postgres -c "DROP DATABASE IF EXISTS $(DB_NAME);" && echo "SUCCESS! database $(DB_NAME) dropped"; \
 	elif [ "$(DB_HOST)" = "localhost" ] || [ "$(DB_HOST)" = "127.0.0.1" ]; then \
 		container=$$(docker ps -q --filter "publish=$(DB_PORT)" | head -1); \
 		if [ -z "$$container" ]; then \
@@ -69,10 +91,19 @@ db-drop:
 	fi
 
 migrate-up:
-	migrate -path migrations -database "$$DB_DSN" up
+	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); migrate -path migrations -database "$$DB_DSN" up
 
 migrate-down:
-	migrate -path migrations -database "$$DB_DSN" down 1
+	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); migrate -path migrations -database "$$DB_DSN" down 1
+
+# runs up -> down-to-zero -> up against $DB_DSN to catch a bit-rotted down.sql
+# (one that no longer reverses cleanly) before you actually need a rollback.
+# point DB_DSN at a throwaway/test database first — this drops every table.
+migrate-verify:
+	@[ -f $(ENV_FILE) ] && export $$(grep -v '^#' $(ENV_FILE) | sed -E 's/[[:space:]]+#.*$$//' | xargs); \
+	migrate -path migrations -database "$$DB_DSN" up && \
+	migrate -path migrations -database "$$DB_DSN" down -all && \
+	migrate -path migrations -database "$$DB_DSN" up
 {{#if openapiDocs}}
 
 # docs/openapi.yaml is hand-written and split across sibling files via relative

package/templates/create/base/README.md.hbs

@@ -2,12 +2,15 @@
 
 Gin + GORM backend, scaffolded by [go-scaffold](https://github.com/nakedev/go-scaffold). Organized by feature (domain), Postgres-backed, schema managed with [golang-migrate](https://github.com/golang-migrate/migrate).
 
-This is a bare skeleton — no domain modules yet. Add one with:
+This project starts as a bare skeleton. Add a safe minimal domain with:
 
 ```bash
 go-scaffold generate module orders
 ```
 
+Add endpoints one at a time with `generate method`, or pass `--full` to opt
+into a CRUD skeleton whose DTO fields and business rules remain explicit TODOs.
+
 See `docs/architect/` for the conventions every generated module follows, and `AGENTS.md`/`CLAUDE.md` if you're working with an AI coding agent in this repo.
 
 ## Layout
@@ -40,9 +43,13 @@ go mod tidy
 make run                           # AUTO_MIGRATE=true creates the schema automatically in dev
 ```
 
-`make run` loads `.env` if present (copy `.env.example` to `.env` to override
-defaults — the app itself just reads `os.Getenv`, no `.env` parsing at
-runtime).
+`make run`/`make test`/`make migrate-up`/`make migrate-down` load `.env` if
+present (copy `.env.example` to `.env` to override defaults — the app itself
+just reads `os.Getenv`, no `.env` parsing at runtime). Point them at another
+file with `ENV_FILE`: copy `.env.example` to `.env.production`, fill it in,
+then `make run ENV_FILE=.env.production`. Trailing `# ...` comments in the env
+file are stripped before loading, so a `# prod: ...` note next to a value is
+safe; a `#` inside a value (password, DSN) is kept.
 
 `make db-create` connects to Postgres at `DB_HOST`/`DB_PORT`/`DB_USER` (default:
 `localhost`/`5432`/`postgres`, matching `.env.example`) using the `psql`
@@ -68,15 +75,20 @@ make lint           # golangci-lint run (see .golangci.yml)
 make tidy           # go mod tidy
 make db-create       # create the database itself (safe to re-run)
 make db-drop         # drop the database
-make migrate-up      # apply migrations (needs $DB_DSN)
+make migrate-up      # apply migrations (reads DB_DSN from ENV_FILE)
 make migrate-down     # roll back one migration
+make migrate-verify   # up -> down-to-zero -> up, catches a broken down.sql (point DB_DSN at a throwaway DB)
 {{#if docker}}make docker-up       # docker compose up -d
 make docker-down     # docker compose down
 {{/if}}```
 
 ## Migrations
 
-Schema is managed with [golang-migrate](https://github.com/golang-migrate/migrate), files live in `migrations/`.
+Schema is managed with [golang-migrate](https://github.com/golang-migrate/migrate), files live in `migrations/`, named `<version>_<name>.{up,down}.sql`. `version` is a 14-digit UTC timestamp, not an incrementing counter — two people adding a migration off the same base branch get different filenames instead of both claiming the same number and colliding on merge. (`generate module` names its own migration the same way; existing sequential `0000NN_*` files from before this convention sort fine alongside timestamped ones either way.)
+
+```bash
+go-scaffold generate migration add_status_to_orders   # reserves migrations/<version>_add_status_to_orders.{up,down}.sql, TODO-stubbed — you write the SQL
+```
 
 ```bash
 brew install golang-migrate
@@ -84,16 +96,31 @@ brew install golang-migrate
 
 migrate -path migrations -database "$DB_DSN" up
 migrate -path migrations -database "$DB_DSN" down 1
-migrate create -ext sql -dir migrations -seq add_something
+migrate create -ext sql -dir migrations -seq=false add_something   # same as `go-scaffold generate migration`, if you'd rather not use the CLI
 ```
 
 **dev:** leave `AUTO_MIGRATE=true` (default) so GORM's AutoMigrate creates the schema quickly.
 **prod:** set `AUTO_MIGRATE=false` and run `migrate up` as a separate deploy step — versioned, has rollback (`down`), doesn't lock the table the way AutoMigrate does once there's real data.
 
+With `AUTO_MIGRATE=false`, the app checks the DB's applied migration version
+against the migration files baked into the binary (embedded at build time)
+before it starts serving traffic — a stale or half-applied schema fails fast
+at boot with a clear message, instead of failing later on whatever query
+happens to hit the missing column first:
+
+```text
+DB schema is at migration 3, this binary expects 5 — run `make migrate-up`
+```
+
+```bash
+make migrate-verify   # up -> down-to-zero -> up, catches a broken down.sql before you actually need a rollback (point DB_DSN at a throwaway DB first — this drops every table)
+```
+
 ## Env vars
 
 | var | default | notes |
 |---|---|---|
+| `APP_ENV` | `development` | `development` or `production` — **the prod gate**: hides error `details` from responses. App refuses to boot on any other value |
 | `PORT` | `8080` | |
 | `DB_DSN` | `postgres://postgres:postgres@localhost:5432/{{dbName}}?sslmode=disable` | used by both GORM and the `migrate` CLI |
 | `LOG_LEVEL` | `info` | debug/info/warn/error |
@@ -101,17 +128,27 @@ migrate create -ext sql -dir migrations -seq add_something
 | `DB_MAX_OPEN_CONNS` | `10` | |
 | `DB_MAX_IDLE_CONNS` | `10` | |
 | `DB_CONN_MAX_LIFETIME_MIN` | `5` | minutes |
+| `CORS_ALLOWED_ORIGINS` | `http://localhost:3000` | comma-separated frontend origins allowed to call this API with credentials (cookies) |
 
 ## Tests
 
-Integration tests (handler-level) run against a **real Postgres** instance (same engine as prod), each test in a transaction that's rolled back — no leftover rows. If the DB isn't reachable those tests **skip** (unit tests using a fake repo always run).
+Handler and service tests are fast unit tests: handlers depend on a narrow
+service interface, and services use function-backed repository stubs. Neither
+suite requires a database.
+
+Repository integration tests run against a **real Postgres** instance using
+the same versioned SQL migrations as production, each test in a transaction
+that's rolled back. Locally they skip when `TEST_DB_DSN` is unset; CI sets
+`REQUIRE_TEST_DB=true`, so a missing or unmigrated database fails instead of
+becoming a false-green skip. Use a separate `{{dbName}}_test` database:
 
 ```bash
 {{#if docker}}
 make docker-up      # local postgres first
 {{/if}}
-make test
-# point at a different test DB: TEST_DB_DSN=postgres://... go test ./...
+make db-create DB_NAME={{dbName}}_test
+DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable make migrate-up
+TEST_DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable REQUIRE_TEST_DB=true go test ./...
 ```
 
 ## Error payload
@@ -120,7 +157,7 @@ make test
 {"error":{"code":"VALIDATION_ERROR","message":"invalid input","details":{"email":"email"},"request_id":"a1b2..."}}
 ```
 
-`code` is machine-readable, `details` names the field that failed, `request_id` correlates with server logs (header `X-Request-ID`).
+`code` is machine-readable, `details` names the field that failed, `request_id` correlates with server logs (header `X-Request-ID`). `details` is **only returned outside production** (`APP_ENV` != `production`) — in prod it's stripped from every error so a direct caller can't learn the API's shape; the server log still has the full detail keyed by `request_id`.
 {{#if openapiDocs}}
 
 ## API spec
@@ -142,4 +179,7 @@ Import `docs/openapi.bundled.yaml` instead. Tools that resolve `$ref` over HTTP
 go-scaffold generate module orders
 ```
 
-Scaffolds `internal/app/orders/` (model/dto/errors/repository/service/handler + tests), wires it into `cmd/api/main.go` (AutoMigrate, route registration), and appends a migration file. See `docs/architect/patterns.md` for the module shape and the rules for domains with foreign keys.
+Scaffolds the safe minimal `internal/app/order/` module, wires its empty route
+group/model into `cmd/api/main.go`, and appends a migration file. Add endpoints
+with `generate method`; use `--full` only when a CRUD skeleton is intentional.
+See `docs/architect/patterns.md` for the module shape and foreign-key rules.

package/templates/create/base/cmd/api/main.go.hbs

@@ -11,11 +11,17 @@ import (
 	"time"
 
 	"{{goModule}}/internal/platform/database"
+{{#if observability}}
+	"{{goModule}}/internal/platform/telemetry"
+{{/if}}
 	"{{goModule}}/internal/shared/config"
 	"{{goModule}}/internal/shared/middleware"
 	// go-scaffold:imports
 
 	"github.com/gin-gonic/gin"
+{{#if observability}}
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+{{/if}}
 )
 
 func main() {
@@ -23,7 +29,17 @@ func main() {
 
 	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: parseLevel(cfg.LogLevel)}))
 	slog.SetDefault(logger)
+	// go-scaffold:config-checks
 
+{{#if observability}}
+	shutdownTelemetry, err := telemetry.Init(context.Background(), "{{projectName}}", cfg.OTELExporterEndpoint)
+	if err != nil {
+		logger.Error("init telemetry", "error", err)
+		os.Exit(1)
+	}
+	defer func() { _ = shutdownTelemetry(context.Background()) }()
+
+{{/if}}
 	db, err := database.Open(cfg)
 	if err != nil {
 		logger.Error("open db", "error", err)
@@ -35,6 +51,7 @@ func main() {
 		logger.Error("db handle", "error", err)
 		os.Exit(1)
 	}
+	// go-scaffold:platform-init
 
 	if cfg.AutoMigrate {
 		// ponytail: AutoMigrate is for dev only (add-only, locks the table once data grows)
@@ -45,10 +62,13 @@ func main() {
 			logger.Error("migrate", "error", err)
 			os.Exit(1)
 		}
+	} else if err := database.CheckMigrationVersion(db); err != nil {
+		logger.Error("migration version check", "error", err)
+		os.Exit(1)
 	}
 
 	r := gin.New()
-	r.Use(gin.Recovery(), middleware.RequestID(), middleware.Logger(logger), middleware.Error())
+	r.Use(gin.Recovery(), middleware.CORS(cfg.CORSAllowedOrigins), middleware.RequestID(), middleware.Logger(logger), middleware.Error(!cfg.IsProd()){{#if observability}}, middleware.Metrics(), middleware.Tracing("{{projectName}}"){{/if}})
 
 	// liveness = is the process up / readiness = ready for traffic (can it reach the DB)
 	r.GET("/livez", func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"status": "ok"}) })
@@ -57,8 +77,12 @@ func main() {
 			c.JSON(http.StatusServiceUnavailable, gin.H{"status": "unavailable"})
 			return
 		}
+		// go-scaffold:readyz-checks
 		c.JSON(http.StatusOK, gin.H{"status": "ok"})
 	})
+{{#if observability}}
+	r.GET("/metrics", gin.WrapH(promhttp.Handler()))
+{{/if}}
 {{#if openapiDocs}}
 	// hand-written spec at docs/openapi.yaml, split across sibling files (common/, health/,
 	// <domain>/) via relative $ref — serve the whole tree under one prefix so a client that
@@ -99,6 +123,7 @@ func main() {
 	if err := srv.Shutdown(shutdownCtx); err != nil {
 		logger.Error("shutdown", "error", err)
 	}
+	// go-scaffold:shutdown
 	logger.Info("stopped")
 }
 

package/templates/create/base/internal/platform/database/database.go.hbs

@@ -1,7 +1,15 @@
 package database
 
 import (
+	"fmt"
+	"regexp"
+	"strconv"
+
+{{#if observability}}
+	"{{goModule}}/internal/platform/telemetry"
+{{/if}}
 	"{{goModule}}/internal/shared/config"
+	"{{goModule}}/migrations"
 
 	"gorm.io/driver/postgres"
 	"gorm.io/gorm"
@@ -16,6 +24,12 @@ func Open(cfg config.Config) (*gorm.DB, error) {
 		return nil, err
 	}
 
+{{#if observability}}
+	if err := db.Use(telemetry.NewGormPlugin()); err != nil {
+		return nil, err
+	}
+
+{{/if}}
 	sqlDB, err := db.DB()
 	if err != nil {
 		return nil, err
@@ -26,3 +40,42 @@ func Open(cfg config.Config) (*gorm.DB, error) {
 
 	return db, nil
 }
+
+var migrationVersionRe = regexp.MustCompile(`^(\d+)_.*\.up\.sql$`)
+
+// CheckMigrationVersion fails fast if the DB's applied schema version (the
+// golang-migrate CLI's own schema_migrations table) doesn't match the newest
+// migration file baked into this binary — instead of booting against a stale
+// or half-applied schema and failing later on whatever query hits the
+// missing column first. Only meaningful when AutoMigrate is off (prod); call
+// this from that branch only.
+func CheckMigrationVersion(db *gorm.DB) error {
+	entries, err := migrations.FS.ReadDir(".")
+	if err != nil {
+		return fmt.Errorf("read embedded migrations: %w", err)
+	}
+	var latest int
+	for _, e := range entries {
+		m := migrationVersionRe.FindStringSubmatch(e.Name())
+		if m == nil {
+			continue
+		}
+		if v, _ := strconv.Atoi(m[1]); v > latest {
+			latest = v
+		}
+	}
+
+	var version int
+	var dirty bool
+	row := db.Raw("SELECT version, dirty FROM schema_migrations").Row()
+	if err := row.Scan(&version, &dirty); err != nil {
+		return fmt.Errorf("read schema_migrations (did you run `make migrate-up`?): %w", err)
+	}
+	if dirty {
+		return fmt.Errorf("schema_migrations is dirty at version %d — a previous migration failed partway; fix it before starting the app", version)
+	}
+	if version != latest {
+		return fmt.Errorf("DB schema is at migration %d, this binary expects %d — run `make migrate-up`", version, latest)
+	}
+	return nil
+}

package/templates/create/base/internal/shared/config/config.go.hbs

@@ -1,13 +1,16 @@
 package config
 
 import (
+	"fmt"
 	"os"
 	"strconv"
+	"strings"
 	"time"
 )
 
 // Config loads from env (with dev-friendly defaults).
 type Config struct {
+	AppEnv            string // "development" | "production" — the one source of truth for env-gated behavior; see IsProd (validated in Load)
 	Port              string
 	DBDSN             string
 	LogLevel          string
@@ -15,10 +18,22 @@ type Config struct {
 	DBMaxOpenConns    int
 	DBMaxIdleConns    int
 	DBConnMaxLifetime time.Duration
+
+	CORSAllowedOrigins []string
+{{#if observability}}
+	OTELExporterEndpoint string
+{{/if}}
+	// go-scaffold:config-fields
 }
 
+// IsProd reports whether env-gated production behavior should be active
+// (e.g. hiding internal error details from responses). Everything that
+// isn't APP_ENV=production is treated the same way.
+func (c Config) IsProd() bool { return c.AppEnv == "production" }
+
 func Load() Config {
-	return Config{
+	cfg := Config{
+		AppEnv:            env("APP_ENV", "development"),
 		Port:              env("PORT", "8080"),
 		DBDSN:             env("DB_DSN", "postgres://postgres:postgres@localhost:5432/{{dbName}}?sslmode=disable"),
 		LogLevel:          env("LOG_LEVEL", "info"),
@@ -26,7 +41,23 @@ func Load() Config {
 		DBMaxOpenConns:    envInt("DB_MAX_OPEN_CONNS", 10),
 		DBMaxIdleConns:    envInt("DB_MAX_IDLE_CONNS", 10),
 		DBConnMaxLifetime: time.Duration(envInt("DB_CONN_MAX_LIFETIME_MIN", 5)) * time.Minute,
+
+		CORSAllowedOrigins: envList("CORS_ALLOWED_ORIGINS", "http://localhost:3000"),
+{{#if observability}}
+		OTELExporterEndpoint: env("OTEL_EXPORTER_OTLP_ENDPOINT", ""),
+{{/if}}
+		// go-scaffold:config-load
+	}
+
+	// Fail closed on an unknown APP_ENV: an unrecognized value (typo, stale var)
+	// would otherwise be treated as non-prod and silently disable the prod guard
+	// (leaking error details). Panics here — the one place the binary loads
+	// config — so a bad value is caught at boot, not discovered in prod later.
+	if cfg.AppEnv != "development" && cfg.AppEnv != "production" {
+		panic(fmt.Sprintf("invalid APP_ENV %q — must be development or production", cfg.AppEnv))
 	}
+
+	return cfg
 }
 
 func env(k, def string) string {
@@ -36,6 +67,17 @@ func env(k, def string) string {
 	return def
 }
 
+func envList(k, def string) []string {
+	raw := strings.Split(env(k, def), ",")
+	out := make([]string, 0, len(raw))
+	for _, v := range raw {
+		if v = strings.TrimSpace(v); v != "" {
+			out = append(out, v)
+		}
+	}
+	return out
+}
+
 func envInt(k string, def int) int {
 	if v := os.Getenv(k); v != "" {
 		if n, err := strconv.Atoi(v); err == nil {

package/templates/create/base/internal/shared/middleware/cors.go.hbs

@@ -0,0 +1,29 @@
+package middleware
+
+import (
+	"net/http"
+	"slices"
+
+	"github.com/gin-gonic/gin"
+)
+
+// CORS allows a fixed set of browser origins to call the API with
+// credentials (cookies) — "*" can't be combined with Allow-Credentials per
+// the fetch spec, so the origin is echoed back only when it's in
+// allowedOrigins.
+func CORS(allowedOrigins []string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		c.Header("Vary", "Origin")
+		if origin := c.GetHeader("Origin"); slices.Contains(allowedOrigins, origin) {
+			c.Header("Access-Control-Allow-Origin", origin)
+			c.Header("Access-Control-Allow-Credentials", "true")
+			c.Header("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS")
+			c.Header("Access-Control-Allow-Headers", "Content-Type, Authorization")
+		}
+		if c.Request.Method == http.MethodOptions {
+			c.AbortWithStatus(http.StatusNoContent)
+			return
+		}
+		c.Next()
+	}
+}

package/templates/create/base/internal/shared/middleware/error.go.hbs

@@ -11,7 +11,12 @@ import (
 
 // Error reads the last error attached via c.Error() and renders it once, so
 // handlers only ever do c.Error(err); return — no c.JSON per call site.
-func Error() gin.HandlerFunc {
+//
+// exposeDetail controls whether an error's Details (a validation field map,
+// or an unexpected error's real message) is echoed back in the response body
+// — wire this to !cfg.IsProd() so a caller hitting the API directly never
+// learns field names/shape from prod responses; devs still get it locally.
+func Error(exposeDetail bool) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		c.Next()
 
@@ -25,6 +30,13 @@ func Error() gin.HandlerFunc {
 			// Unexpected error: log the real thing, answer the client generically.
 			slog.Error("unhandled error", "error", err.Err, "request_id", c.GetString(RequestIDKey))
 			appErr = apperror.NewInternal()
+			if exposeDetail {
+				appErr.Details = err.Err.Error()
+			}
+		} else if !exposeDetail {
+			// Known AppError (e.g. VALIDATION_ERROR): still strip Details in
+			// prod, so a direct API call doesn't get field-level hints.
+			appErr.Details = nil
 		}
 
 		appErr.RequestID = c.GetString(RequestIDKey)

package/templates/create/base/migrations/embed.go.hbs

@@ -0,0 +1,15 @@
+// Package migrations embeds the migration SQL files so the running binary
+// can check its own schema version without shelling out to the migrate CLI.
+package migrations
+
+import "embed"
+
+// ponytail: pattern is "*", not "*.sql" — a fresh project has zero .sql files
+// until the first `generate module`, and "*.sql" fails to compile ("no
+// matching files") until one exists. "*" always matches at least .gitkeep, so
+// this builds from `create` onward; the harmless cost is embedding .gitkeep
+// and this file itself alongside real migrations, which CheckMigrationVersion
+// already skips over (regex requires a numeric prefix and .up.sql suffix).
+//
+//go:embed *
+var FS embed.FS

package/templates/create/features/docs/architecture.md.hbs

@@ -91,6 +91,28 @@ Scalar/Swagger UI/Redoc to follow them).
 comment-generated (swaggo) if hand-updates start drifting.
 {{/if}}
 
+{{#if observability}}
+## 9. Observability
+
+**Decision:** Prometheus metrics (`GET /metrics`, request count + latency
+per route) always-on when this feature is enabled; OpenTelemetry tracing
+(Gin + GORM) exports via OTLP/HTTP only when `OTEL_EXPORTER_OTLP_ENDPOINT`
+is set — empty means no exporter is created and no network calls are made.
+**Rationale:** Metrics have no external dependency to turn on (Prometheus
+scrapes the app, the app never dials out) so there's no reason to gate them
+further. Tracing needs a collector to be useful, so it stays off until one's
+actually configured, instead of trying to dial a collector that isn't there.
+This is a `create`-time choice (unlike `add auth`/`add rbac`), not something
+layered on afterward — flip it by hand (`internal/shared/middleware/{metrics,tracing}.go`,
+`internal/platform/telemetry/tracing.go`, wiring in `cmd/api/main.go` and
+`internal/platform/database`) if the project needs it later. Both the Gin and
+GORM tracing hooks are hand-rolled against the OTel SDK directly, not the
+official `otelgin`/`gorm.io/plugin/opentelemetry` contrib packages — those
+pull in a newer Gin (→ HTTP/3/quic-go) and every DB driver they support
+tracing for (MySQL, ClickHouse, MongoDB), respectively, for a Postgres-only
+project that only wants request/query spans.
+
+{{/if}}
 ## Evolution Notes
 
 - `go-scaffold generate module <name>` adds a new domain package and