@nakedev/go-scaffold 0.3.3 → 0.4.3

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

@@ -1,80 +1,268 @@
 # Agent Guidance: {{projectName}}
 
-This project was scaffolded by `@nakedev/go-scaffold` and is maintained using
-its `generate` subcommands — new domain modules and new endpoints are not
-hand-written.
+This project was scaffolded by `@nakedev/go-scaffold`. It is a modular
+monolith: each business capability lives in its own feature package, while
+`cmd/api/wiring.go` is the process composition root. This file is the working
+contract for AI coding agents and humans; keep generated structure and the
+runtime safety rules below intact.
 
-## Hard rule: use the CLI to add a new domain module or a new endpoint
+## Start every task here
 
-If you are about to create a **new** domain (a new `internal/app/<name>/`
-package with its own model/handler/service/repository), or add a **new**
-endpoint to an existing one — stop and run the CLI instead:
+1. Read the relevant code, `docs/architect/`, tests, and this file before
+   editing. Search for an existing module or port before creating one.
+2. Check `git status --short --branch`. Work on a dedicated, non-protected
+   branch and preserve unrelated changes. Never edit a protected branch just
+   to make a quick fix.
+3. Classify the request: generated surface, business behavior, schema, auth /
+   security, infrastructure, or documentation. Ask the owner before changing
+   schema/migrations, authentication or security behavior, architecture,
+   dependencies, or deployment configuration when the project workflow
+   requires approval.
+4. Make the smallest complete change, add a focused test, and report exact
+   commands and output. Do not claim a check passed if it was skipped or
+   failed.
+
+## Architecture contract
+
+This scaffold combines modular boundaries with Hexagonal Architecture,
+domain-oriented design, and an optional CQRS style. They are compatible:
+apply them inside each feature instead of creating a second architecture or
+an empty layer for every noun.
+
+- **Inbound adapter:** `handler.go` parses HTTP, validates/binds transport
+  input, calls an application service, and maps the result to HTTP.
+- **Application boundary:** `service.go` (or `commands.go`/`queries.go` when
+  the module uses `--cqrs`; complex auth may also use
+  `internal/app/<feature>/application/`) orchestrates use cases. It owns
+  workflow decisions and depends on narrow consumer-owned ports.
+- **Domain:** models, value rules, and invariants stay independent of Gin,
+  GORM, Redis, HTTP status codes, and environment variables.
+- **Outbound adapter:** `repository.go`, token stores, mail/queue clients,
+  and other platform integrations translate a port into persistence or I/O.
+- **Composition:** the feature-local `composition.go` constructs its
+  repository, service, and handler. `cmd/api/wiring.go` selects shared
+  infrastructure, supplies explicitly declared cross-feature ports/security
+  dependencies, and registers the feature route; it does not contain
+  business logic or feature-internal constructors.
+
+The project defaults new modules to `{{defaultApplicationStyle}}` application
+handling and a `{{defaultModuleSurface}}` surface. The `generate module` wizard
+starts there through the named Lean/CRUD/CQRS profiles; `Advanced` exposes the
+two axes for unusual combinations. `--profile` is the clear per-module
+override, while `--cqrs`/`--full` remain supported for existing scripts, and
+`go-scaffold config` changes defaults for future modules only.
+
+Use CQRS when a feature has genuinely different command and query models,
+consistency needs, or scaling/read-shape pressure: commands mutate state and
+queries read state. For simple CRUD, one application service and one port are
+clearer. Do not introduce a broker, a second database, or a command/query
+folder only to satisfy a label.
+
+Keep feature boundaries real. Do not import another feature's private model,
+repository, or handler. Expose a small public application port, call a
+documented feature API, or use an explicit event when cross-feature behavior
+is required. Keep dependency direction flowing inward:
+
+```text
+handler -> application/use case -> domain + ports -> adapters
+                                  ^                 |
+                                  +--- composition -+
+```
+
+The generated CRUD shape is an intentionally incremental starter. It gives
+each module a testable service/handler seam and a feature-local composition
+root; it does not decide the final aggregate, fields, invariants, or split
+between commands and queries for the product.
+
+## Hard rule: use the CLI for generated surface
+
+If you are creating a **new domain** (`internal/app/<name>/` with its own
+model/service/repository/handler), or adding a **new endpoint** to an existing
+domain, stop and run the CLI:
 
 ```bash
 go-scaffold generate module <name> --defaults
 go-scaffold generate method <module> <name> --type <get|post|put|patch|delete>
 ```
 
-**Pass every value as a flag.** Run interactively, these commands ask for
-anything you left out — which has no answer in a non-interactive shell, so
-they exit 1 having written nothing. `--defaults` on `generate module` means
-"minimal, no auth, ask nothing"; add `--full`/`--auth`/`--permission` to it
-when you want those. Same rule elsewhere: `--get-mode` is required with
-`--type get`, and `undo module` needs `-y`. Every `add` command confirms
-before writing — `-y` skips that, but `add auth`/`add worker` also ask which
-backing store to use, so those two want `--defaults` (or `--store`/`--queue`
-plus `-y`).
-
-This applies **even when the request doesn't say "module"/"method" or name
-the CLI at all**. Recognize indirect asks as generation work, for example:
-
-- "add a products feature" → a new domain (`generate module products --defaults`)
-- "let admins approve orders" → a new method on an existing module
-  (`generate method orders approve --type patch`)
-- "we need an endpoint that lists overdue invoices" → a new `get` method
-  (`generate method invoices findOverdue --type get --get-mode all`)
-- "add a way to look up a user by email" → a new `get` lookup
-  (`generate method users findByEmail --type get --get-mode one --field email`)
-
-Run `go-scaffold generate module --help` / `generate method --help` before
-hand-rolling anything that looks like scaffolding.
-
-## What the CLI does NOT do — these are still done by hand, as normal
-
-- Business logic inside a generated method (the CLI leaves a TODO-marked
-  stub — filling in real behavior is your job)
-- Adding fields to a generated model/DTO beyond `id`/`created_at`/`updated_at`
-- Foreign keys / relations between domains — add the column, the migration
-  `REFERENCES ... ON DELETE ...` clause, and the `dberr.IsForeignKey` mapping
-  yourself; see `docs/architect/patterns.md` for the 3 rules domains with a
-  relation must follow
-- Bug fixes, refactors, or edits to existing logic
-- Anything in a project that does **not** have `go-scaffold.config.json` at
-  its root — that means the project wasn't scaffolded by this CLI, and this
-  rule does not apply
+Pass every value as a flag in CI. In an interactive shell, omitted values use
+the project defaults as the initial wizard choices. In a non-interactive
+shell, omitted values prompt and the command exits without writing.
+`--defaults` uses the recorded project defaults and no auth; use `--profile`
+for a named per-module preset, or add `--full`, `--cqrs`, `--auth`, and
+`--permission <code>` deliberately.
+`--get-mode`
+is required for `--type get`, and `undo module` needs `-y`. For `add auth`,
+choose the backing store and browser topology with `--defaults` or explicit
+flags (`--store`, `--browser-topology`) as well as the confirmation flag.
+For `add worker`, choose the backing queue with `--defaults` or an explicit
+flag.
+
+Recognize indirect requests as generation work:
+
+- “add a products feature” → `generate module products --defaults`
+- “let admins approve orders” → `generate method orders approve --type patch`
+- “list overdue invoices” → `generate method invoices findOverdue --type get --get-mode all`
+- “look up a user by email” → `generate method users findByEmail --type get --get-mode one --field email`
+
+Run `go-scaffold generate module --help` or `generate method --help` when the
+desired shape is unclear. Do not hand-edit generated route markers to add a
+new endpoint; the CLI keeps handler, service interface, test stub, and
+OpenAPI/migration patching in sync.
+
+## What the CLI does not decide
+
+These remain deliberate engineering work:
+
+- business behavior, invariants, authorization policy, and real DTO/model
+  fields;
+- validation beyond the transport shape and all domain-specific rules;
+- foreign keys and relations between domains, including their reviewed SQL
+  and `dberr.IsForeignKey` mapping;
+- the business-specific command/query contracts and the public port used for
+  cross-feature collaboration;
+- bug fixes, refactors, and changes to an existing method;
+- any work in a repository that lacks `go-scaffold.config.json`.
+
+Generated methods are explicit stubs. `generate method` GET-all reuses
+`FindAll` until real filtering is added; POST and DELETE return an internal
+error until implemented; PUT/PATCH intentionally return `501 Not Implemented`
+and must not read or write a record before their behavior is designed. Treat
+the generated OpenAPI TODO contract as incomplete, not as a promise that the
+endpoint is production-ready.
+
+## Runtime and schema safety
+
+- `APP_ENV` is the single environment gate and accepts only `development` or
+  `production`. Do not add a parallel flag such as `AUTO_MIGRATE`.
+- Development may use the convenience `db.AutoMigrate(...)` path for the
+  models registered by the generator. Production must never bootstrap or
+  mutate schema at API startup: apply versioned SQL with
+  `make migrate-up`, then let the startup migration-version check fail fast if
+  the database is behind or dirty.
+- Any schema change is a reviewed pair of versioned files in `migrations/`.
+  Use `go-scaffold generate migration <name>` for changes outside a new
+  module, write both directions, and test them against a disposable database.
+- Keep `*sql.DB`, Redis, queue, mail, and other external resources owned by
+  their composition root. Close them on every exit path and preserve the
+  signal-driven graceful shutdown; do not call `os.Exit` from a goroutine or
+  hide a startup error.
+- Keep liveness and readiness semantics intact. Readiness may check external
+  dependencies; liveness must not turn a transient dependency failure into a
+  process restart.
+
+## Auth and error boundaries
+
+Treat auth and security changes as high-risk and get the required owner
+approval before changing their contract.
+
+- Never log passwords, raw access/refresh/reset/verification tokens, JWT
+  secrets, OAuth client secrets, or authorization headers.
+- Refresh rotation is an atomic consume: Postgres uses one SQL unit and Redis
+  uses one Lua operation, including active-session cleanup and the reuse
+  tombstone. Its inactivity expiry may move on rotation, but its persisted
+  absolute expiry never moves. Never replace it with a read-then-delete
+  sequence.
+- Password reset and email verification consume a one-time token in the same
+  retry-safe transaction as the user/identity update. A failed post-commit
+  session revocation must not make a successful reset impossible to retry.
+- The generated auth facade is a pragmatic compatibility boundary: its service
+  contracts currently use the feature's `model` values and shared `apperror`,
+  while handlers own Gin and provider adapters own SDK configuration. Do not
+  broaden that coupling by importing Gin, provider SDKs, or HTTP handlers into
+  use cases. New complex flows should prefer transport-neutral DTOs and narrow
+  ports; a deeper separation of the existing auth facade is an explicit
+  architecture refactor and needs focused tests.
+- Browser provider exchange consumes a one-time server-side transaction bound
+  to provider, state, S256 PKCE challenge, and OIDC nonce. Google ID tokens
+  must be signature, issuer, audience/azp, time-claim, nonce, and subject
+  validated before identity resolution. Token responses use
+  `Cache-Control: no-store` and `Pragma: no-cache`; SameSite=None also needs an
+  exact allowed Origin guard in addition to CORS.
+
+MFA has an operator capability switch and a separate per-user enrollment:
+
+- `AUTH_MFA_ENABLED=false` is the default. When enabled, the composition root
+  must validate `MFA_ENCRYPTION_KEY` as a base64-encoded 32-byte key before
+  serving traffic. Keep the issuer, challenge TTL, TOTP window, and recovery
+  code count explicit and within their safety limits.
+- Authenticated users manage enrollment through `GET /users/me/mfa`,
+  `POST /users/me/mfa/setup`, `POST /users/me/mfa/confirm`, and
+  `POST /users/me/mfa/disable` (the last requires the current TOTP code).
+  Setup material is pending-only; recovery codes are returned once.
+- Password login and provider exchange may return a pre-session
+  `{ "mfa_required": true, "challenge": "..." }`. Do not issue an access
+  token or refresh cookie until `POST /auth/mfa/verify` succeeds. Challenges
+  are hashed, short-lived, and one-use; failed verification consumes the
+  challenge. Recovery codes are hashed, atomic one-use login factors and are
+  not accepted to disable MFA.
+- MFA data is durable in Postgres for both refresh-token store choices. The
+  `create_mfa` migration must be applied before production and covered by
+  real-store/concurrency tests.
+
+Keep auth construction explicit: `NewService(deps Dependencies, cfg
+AuthConfig)`. `Dependencies` owns narrow ports such as `MFA`, `Providers`,
+`RefreshTokens`, `RecoveryTokens`, `Mailer`, `Roles`, and `Clock`; `AuthConfig`
+owns JWT, OAuth, recovery, and `MFASettings` policy. Do not pass the generated
+shared config package into the application service or replace these contracts
+with a positional constructor.
+- Return a stable, generic client error for unexpected failures. Wrap causes
+  with `%w` or pass them to `apperror.NewInternal(cause)` so middleware can
+  log the server-side cause with `request_id`; production responses must not
+  expose that cause or internal field details.
+
+## Verification workflow
+
+After changing Go templates or generated Go code, run the checks that match
+the change (from the generated project root):
+
+```bash
+gofmt -w <changed-go-files>
+go test ./...
+go test -race ./...       # required for concurrency/auth/token changes
+go vet ./...
+golangci-lint run
+```
+
+For schema/repository/auth adapter work, run the real-store tests with a
+migrated disposable PostgreSQL/Redis instance and `REQUIRE_TEST_DB=true` or
+`REQUIRE_TEST_REDIS=true`; a skipped integration test is not evidence of
+correctness. MFA state still requires PostgreSQL even when refresh tokens use
+Redis. When routes or OpenAPI templates change, inspect the updated
+`docs/openapi.yaml` and run the configured OpenAPI linter.
+
+Only in the `go-scaffold` source repository, run the generator project's
+`pnpm run verify` for CLI/template changes, then generate fresh sample projects
+to inspect the output. A generated Go project does not contain the generator's
+`package.json` or pnpm scripts; from that project run the Go checks above and
+use the installed/local CLI for generation checks.
+
+At each checkpoint record: branch and base, files changed, generated output
+shape, tests and their exact result, and any limitation. Before handoff,
+review `git diff --check`, `git diff`, and `git status --short`; leave unrelated
+work untouched.
 
 ## Command quick reference
 
-- `go-scaffold generate module <name> --defaults` — safe minimal model + errors +
-  repository + service/handler plumbing, wired into `cmd/api/wiring.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. With OpenAPI
-  enabled it also writes a valid TODO path document and wires the index;
-  replace placeholder schemas while implementing the method
-- `go-scaffold undo module <name> -y` — takes back a `generate module` that
-  shouldn't have happened (typo'd name, domain decided against): deletes the
-  package, un-wires main.go/OpenAPI, and deletes the module's migration files.
-  It refuses if those migrations are committed to git or already applied to
-  your database, since then they may exist somewhere this can't reach. Not for
-  retiring a domain that has shipped — that's `generate migration drop_<table>`
-  plus a reviewed data removal; the table is never dropped either way
-- 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
-  field, not a duplicated model
-- Full architecture rationale for this project's configuration: see
-  `docs/architect/`
+- `go-scaffold generate module <name> --defaults` — minimal model, errors,
+  repository, service/handler seams, feature-local `composition.go`, root
+  route registration, and versioned module migrations. Add endpoints with
+  `generate method`, use `--profile crud` for a CRUD skeleton, or
+  `--profile cqrs` for separate command/query application handlers.
+- `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, for a GET-one lookup, repository plus test
+  seam. It never overwrites a same-named method.
+- `go-scaffold generate migration <name>` — reserves a timestamped SQL
+  migration pair for a reviewed schema change.
+- `go-scaffold config` — interactively change future module defaults;
+  `config show` prints the resolved manifest and `config validate` checks it
+  without writing.
+- `go-scaffold undo module <name> -y` — removes an unshipped generated module,
+  its migration, and its wiring. It refuses once those migrations are
+  committed or applied; use a reviewed drop migration for a shipped domain.
+- All routes share the project-wide prefix chosen at `create` time:
+  `{{#if apiPrefix}}/{{apiPrefix}}{{else}}(no prefix){{/if}}`. There is no
+  per-domain versioning.
+
+Read `docs/architect/architecture.md`, `docs/architect/patterns.md`, and
+`docs/architect/techstack.md` for the rationale behind these constraints.

package/templates/create/base/Makefile.hbs

@@ -68,7 +68,8 @@ tools:
 tidy:
 	go mod tidy
 
-# creates the database itself (not the schema — AUTO_MIGRATE or migrate-up does that).
+# creates the database itself (not the schema — the app's development path or
+# migrate-up does that).
 # 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.

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

@@ -2,14 +2,23 @@
 
 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 project starts as a bare skeleton. Add a safe minimal domain with:
+This project starts as a bare skeleton. Its defaults for future modules resolve
+to `{{defaultModuleSurface}}` surface + `{{defaultApplicationStyle}}` application
+style. The `generate module` wizard presents this as a named Lean, CRUD, CQRS,
+or Advanced profile so you can choose by intent instead of memorising two
+implementation axes. Add a 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.
+The `generate module` wizard starts from those defaults. Add endpoints one at a
+time with `generate method`, pass `--profile crud` for a CRUD skeleton, or use
+`--profile cqrs` when commands and queries deserve separate application
+handlers. DTO fields and business rules remain explicit TODOs. Run
+`go-scaffold config` later to change defaults for future modules; existing
+modules are unchanged. The older `--full` and `--cqrs` flags remain supported
+for scripts.
 
 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.
 
@@ -18,7 +27,8 @@ See `docs/architect/` for the conventions every generated module follows, and `A
 ```
 cmd/
 └── api/
-    └── main.go                # config, slog, graceful shutdown, wires domains — the only entry point for now
+    ├── main.go                # process entry point, config, slog, graceful shutdown
+    └── wiring.go              # composition root: infrastructure + domain registration
 internal/
 ├── platform/                  # talks to real external systems (DB, later: cache, queue, mail, ...)
 │   └── database/              # opens the connection + pool (GORM)
@@ -42,7 +52,7 @@ make docker-up                     # local Postgres (postgres:5432)
 {{/if}}
 make db-create                     # create the {{dbName}} database itself (once — safe to re-run)
 go mod tidy
-make run                           # AUTO_MIGRATE=true creates the schema automatically in dev
+make run                           # APP_ENV=development enables the convenience schema bootstrap
 ```
 
 `make run`/`make test`/`make migrate-up`/`make migrate-down` load `.env` if
@@ -103,10 +113,11 @@ migrate -path migrations -database "$DB_DSN" down 1
 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.
+**dev:** `APP_ENV=development` enables the convenience table bootstrap.
+**prod:** `APP_ENV=production` never bootstraps or mutates the schema; run
+`migrate up` as a separate deploy step — versioned and rollback-capable.
 
-With `AUTO_MIGRATE=false`, the app checks the DB's applied migration version
+In production, 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
@@ -128,12 +139,25 @@ make migrate-verify   # up -> down-to-zero -> up, catches a broken down.sql befo
 | `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 |
-| `AUTO_MIGRATE` | `true` | disable in prod and use `migrate up` (see Migrations) |
 | `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) |
 
+After `go-scaffold add auth`, `.env.example` also contains
+`GOOGLE_OAUTH_REDIRECT_URI` (the exact browser callback URI registered with
+Google), `JWT_REFRESH_MAX_TTL_MIN`, `OAUTH_STATE_TTL_MIN`, and
+`AUTH_BROWSER_TOPOLOGY`. Refresh rotation uses the configured inactivity TTL
+but never moves a token past its absolute lifetime. The backend stores a
+one-time OAuth transaction binding provider, state, S256 challenge, and OIDC
+nonce; the frontend still owns the callback route and sends the code to the
+exchange endpoint. The provider redirect URI is separate from
+`CORS_ALLOWED_ORIGINS`; the latter remains an exact-origin credentialed API
+policy. Token responses use `Cache-Control: no-store` and `Pragma: no-cache`.
+For `cross-site`, configure HTTPS origins, `COOKIE_SAMESITE=none`,
+`COOKIE_SECURE=true`, and an exact allowed Origin; the API applies an Origin
+guard independently of CORS.
+
 ## Tests
 
 Handler and service tests are fast unit tests: handlers depend on a narrow
@@ -166,15 +190,15 @@ TEST_DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=
 
 ## API spec
 
-`docs/openapi.yaml` is hand-written and served, along with every file it `$ref`s (`common/`, `health/`, per-domain folders), under `/docs` while the server runs — point a renderer (Scalar, Swagger UI, Redoc) or a client generator (Hey API) at `http://localhost:8080/docs/openapi.yaml`, or browse the tree at `http://localhost:8080/docs/`. Update the spec by hand whenever an endpoint/DTO changes.
+`docs/openapi.yaml` is hand-written and split across sibling files (`common/`, `health/`, per-domain folders) via relative `$ref`. **The server never serves it** — there is no `/docs` route, in any environment, so the API surface and `docs/architect/`'s internal notes stay off the wire. Update the spec by hand whenever an endpoint/DTO changes.
 
-Some tools don't resolve external `$ref`s when importing a local file — they read it as-is and see zero routes (Bruno's "Import Collection" does this; some Postman flows too). For those, bundle the spec into one fully-resolved file first:
+To open it in a renderer (Scalar, Swagger UI, Redoc) or a client generator (Hey API), bundle it into one fully-resolved file and point the tool at that file. Bundling is also what importers that don't resolve external `$ref`s need — they read the index as-is and see zero routes (Bruno's "Import Collection" does this; some Postman flows too):
 
 ```bash
 make openapi-bundle          # writes docs/openapi.bundled.yaml (gitignored — regenerate anytime)
 ```
 
-Import `docs/openapi.bundled.yaml` instead. Tools that resolve `$ref` over HTTP or when reading a URL (Scalar, Swagger UI, Redoc) don't need this — point them at the live `/docs/openapi.yaml` URL above.
+Then open `docs/openapi.bundled.yaml` — it needs no network and no running server.
 {{/if}}
 
 ## Adding a domain
@@ -183,10 +207,12 @@ Import `docs/openapi.bundled.yaml` instead. Tools that resolve `$ref` over HTTP
 go-scaffold generate module orders
 ```
 
-Scaffolds the safe minimal `internal/app/order/` module, wires its empty route
-group/model into `cmd/api/wiring.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.
+Scaffolds an `internal/app/order/` module using the project defaults
+(`{{defaultModuleSurface}}` + `{{defaultApplicationStyle}}`), wires its route/
+model into `cmd/api/wiring.go`, and appends a migration file. Add endpoints
+with `generate method`; use `--profile crud` for a CRUD skeleton or
+`--profile cqrs` for separate command/query handlers. See
+`docs/architect/patterns.md` for the module shape and foreign-key rules.
 
 ## Deploying
 
@@ -213,10 +239,12 @@ Before the first deploy of a release:
 
 | | |
 |---|---|
-| `AUTO_MIGRATE` | leave unset — it defaults off when `APP_ENV=production`, and the app checks the applied migration version instead |
+| `APP_ENV` | `production` | production disables schema bootstrap and requires the applied migration version |
 | migrations | `migrate -path migrations -database "$DB_DSN" up` as its own step, before the new binaries roll |
 | `TRUSTED_PROXIES` | the CIDRs of your ingress, or the auth rate limiter keys on a header anyone can send |
 | `COOKIE_SECURE` | `true` · `COOKIE_SAMESITE=none` as well if your frontend is on a different site |
+| `JWT_REFRESH_MAX_TTL_MIN` | `43200` | absolute refresh-token lifetime; rotation cannot extend beyond it |
+| `OAUTH_STATE_TTL_MIN` | `10` | lifetime of the one-time server-side OAuth state transaction |
 | `/metrics` | reachable in-cluster for Prometheus, blocked at the ingress |
 | `JWT_SECRET`, `SMTP_HOST` | the app refuses to start in production without real values |
 

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

@@ -46,17 +46,20 @@ func run() error {
 	if err != nil {
 		return fmt.Errorf("db handle: %w", err)
 	}
+	defer func() {
+		if err := sqlDB.Close(); err != nil {
+			logger.Error("close db", "error", err)
+		}
+	}()
 	// go-scaffold:platform-init
 
-	// AutoMigrate creates tables but never the schema they live in — each
-	// domain gets its own (see model.go's TableName), so it has to exist
-	// before AutoMigrate runs. The versioned SQL migrations create the same
-	// schemas with CREATE SCHEMA IF NOT EXISTS, so this only matters for dev.
-	// go-scaffold:schemas
+	if !cfg.IsProd() {
+		// Development boot creates tables but never the schema they live in — each
+		// domain gets its own (see model.go's TableName), so it has to exist
+		// before the bootstrap runs. Production runs the versioned SQL migrations
+		// instead, so this entire branch is skipped there.
+		// go-scaffold:schemas
 
-	if cfg.AutoMigrate {
-		// ponytail: AutoMigrate is for dev only (add-only, locks the table once data grows)
-		// prod: set AUTO_MIGRATE=false and run golang-migrate as versioned SQL instead
 		if err := db.AutoMigrate(
 			// go-scaffold:models
 		); err != nil {
@@ -89,23 +92,13 @@ func run() error {
 	})
 	// go-scaffold:extra-routes
 {{#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
-	// resolves $ref over HTTP (Scalar, Swagger UI, Redoc, Hey API pointed at a URL) can reach
-	// them too; StaticFile on just the index file would 404 on every $ref it follows.
-	//
-	// gin.Dir(..., true) keeps directory listings on, which r.Static suppresses:
-	// without them opening /docs/ in a browser answers 404 with a blank page,
-	// which reads as "this is broken" rather than "ask for a file". The listing
-	// costs nothing here — every file in the tree is already downloadable — and
-	// it makes openapi.yaml discoverable without knowing its name up front.
-	//
-	// Not in production: this serves your whole API surface — every path,
-	// parameter and schema — to anyone who asks. Publish the spec deliberately
-	// (`make openapi-bundle`) rather than by leaving this on.
-	if !cfg.IsProd() {
-		r.StaticFS("/docs", gin.Dir("./docs", true))
-	}
+	// ponytail: docs/ is deliberately NOT served over HTTP, in any environment.
+	// The whole tree — every path, parameter and schema, plus docs/architect/'s
+	// internal design notes — used to be reachable at /docs outside production.
+	// Read the spec from the working copy instead: `make openapi-bundle` writes
+	// one fully-resolved docs/openapi.bundled.yaml for a renderer or client
+	// generator to open as a local file. Publish it deliberately if you want
+	// it public.
 {{/if}}
 
 	api := r.Group("/{{apiPrefix}}")

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

@@ -20,7 +20,8 @@ import (
 
 // Open connects to Postgres and sets the connection pool — it talks to a
 // real external system, so it lives in platform/, not shared/.
-// Schema is managed via golang-migrate (migrations/) in prod, not AutoMigrate — see README.
+// Production schema is managed via golang-migrate (migrations/); development
+// may use the convenience path selected by APP_ENV in the composition root.
 func Open(cfg config.Config) (*gorm.DB, error) {
 	// GORM's default logger reports ErrRecordNotFound at ERROR level, so an
 	// ordinary miss — every FindByID behind a 404, cmd/seed's "does this admin
@@ -58,8 +59,7 @@ var migrationVersionRe = regexp.MustCompile(`^(\d+)_.*\.up\.sql$`)
 // 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.
+// missing column first. Call this from the production branch only.
 func CheckMigrationVersion(db *gorm.DB) error {
 	entries, err := migrations.FS.ReadDir(".")
 	if err != nil {

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

@@ -10,10 +10,15 @@ type AppError struct {
 	Message    string `json:"message"`
 	Details    any    `json:"details,omitempty"`
 	RequestID  string `json:"request_id,omitempty"` // filled in by the error middleware
+	cause      error
 }
 
 func (e *AppError) Error() string { return e.Message }
 
+// Unwrap keeps the technical cause available to structured logging and
+// errors.Is/As without putting it in the JSON response.
+func (e *AppError) Unwrap() error { return e.cause }
+
 func New(status int, code, msg string) *AppError {
 	return &AppError{HTTPStatus: status, Code: code, Message: msg}
 }
@@ -30,7 +35,15 @@ func NewConflict(msg string) *AppError {
 	return &AppError{HTTPStatus: http.StatusConflict, Code: "CONFLICT", Message: msg}
 }
 
-func NewInternal() *AppError {
+func NewInternal(cause ...error) *AppError {
 	// ponytail: never leak internal details to the client, log separately in middleware
-	return &AppError{HTTPStatus: http.StatusInternalServerError, Code: "INTERNAL", Message: "internal server error"}
+	err := &AppError{HTTPStatus: http.StatusInternalServerError, Code: "INTERNAL", Message: "internal server error"}
+	if len(cause) > 0 {
+		err.cause = cause[0]
+	}
+	return err
+}
+
+func NewNotImplemented() *AppError {
+	return &AppError{HTTPStatus: http.StatusNotImplemented, Code: "NOT_IMPLEMENTED", Message: "not implemented"}
 }