@nakedev/go-scaffold 0.4.0 → 0.5.0

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

@@ -1,80 +1,292 @@
 # 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:** `adapters/inbound/http/dto.go` owns JSON/binding request
+  DTOs, response DTOs, and mapping at the HTTP boundary; `handler.go` parses
+  HTTP and calls the relevant application service or command/query port.
+- **Application boundary:** `application/service.go` (or
+  `application/commands.go`/`application/queries.go` when
+  the module uses `--cqrs`) orchestrates use cases. It owns
+  workflow decisions and depends on narrow consumer-owned ports.
+- **Domain:** entities, value rules, and invariants stay independent of Gin,
+  GORM, Redis, HTTP status codes, and environment variables.
+- **Outbound adapter:** `adapters/outbound/postgres/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, application boundary, and handler. `internal/composition/` owns
+  process-level cross-feature adapters. `cmd/api/wiring.go` selects shared
+  infrastructure, supplies those adapters and security dependencies, and
+  registers feature routes; it does not contain cross-feature adapter logic.
+
+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. Put synchronous adapters in `internal/composition/`, import only
+the other feature's public package root, and keep one-way dependencies. 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 application/inbound 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.
+
+For a CQRS module, `application/commands.go` and
+`application/queries.go` are the primary application boundary and
+`composition.go` passes separate command and query handlers to the inbound
+adapter's `NewHandler`. A CQRS module must not also grow an
+`application/service.go` facade. Service and CQRS may coexist across modules;
+they are mutually exclusive inside one module.
+
+Auth and RBAC are security-sensitive modules, but they use the same canonical
+split boundary as every other feature. Auth owns user application use cases
+and ports; RBAC owns role policy and authorization adapters. Their public
+module roots compose those pieces, and one canonical implementation tree is
+generated.
+
+## Hard rule: use the CLI for generated surface
+
+If you are creating a **new domain** (`internal/app/<name>/` with its own
+domain/application/ports/adapters boundary), 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 the inbound adapter, application port, test seam,
+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 implementation is canonical: use cases live in
+  `application/`, domain rules in `domain/`, contracts in `ports/`, and
+  provider/HTTP/Postgres details in their adapters. Do not import Gin, provider
+  SDKs, or persistence models into new application use cases; keep the
+  token/OAuth/MFA tests as the security gate.
+- 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.
+
+When a River worker is installed, run `make river-migrate-test` in addition to
+`make migrate-up-test`. The queue integration test must enqueue a real job and
+observe the worker handler; a worker process that merely boots is not enough.
+
+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 domain entity,
+  errors, ports, application boundary, inbound/outbound adapters,
+  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 inbound handler, application service or command/query handler and,
+  for a GET-one lookup, its repository port/adapter 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 check` — validates every module's split hexagonal layout,
+  forbidden layer dependencies, sibling imports, and the exclusive
+  service-versus-CQRS contract.
+- `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,38 +2,75 @@
 
 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.
 
+## Installed optional features
+
+This project records its generated capabilities in `go-scaffold.config.json`:
+
+- authentication: {{#if auth}}enabled{{else}}not installed — use `go-scaffold add auth` when needed{{/if}}
+- background jobs: {{#if worker}}enabled{{else}}not installed — use `go-scaffold add worker` when needed{{/if}}
+- RBAC: {{#if rbac}}enabled{{else}}not installed — use `go-scaffold add rbac` after auth when needed{{/if}}
+- metrics and tracing: {{#if observability}}enabled{{else}}not installed — use `go-scaffold add observability` when needed{{/if}}
+
+The `add` commands refresh untouched generated architecture docs and this
+section. If a maintainer has edited a document, the command leaves it alone
+and reports that it needs a manual update.
+
 ## Layout
 
 ```
 cmd/
-└── api/
-    └── main.go                # config, slog, graceful shutdown, wires domains — the only entry point for now
+├── api/
+│   ├── main.go                # process entry point, config, slog, graceful shutdown
+│   └── wiring.go              # process composition root and route registration
 internal/
-├── platform/                  # talks to real external systems (DB, later: cache, queue, mail, ...)
-│   └── database/              # opens the connection + pool (GORM)
+├── composition/               # cross-feature adapters and process-level wiring
+├── platform/                  # adapters for external systems
+│   └── database/              # opens the PostgreSQL connection + pool
 ├── shared/                    # pure logic/framework glue, no I/O
 │   ├── config/                # loads config from env
-│   ├── apperror/               # central error type (status + payload)
-│   ├── dberr/                 # maps DB errors to constraint kind (IsDuplicate, IsForeignKey) — shared by every domain
-│   ├── httpx/                 # HTTP helpers shared by every domain (ParseID, BindErr)
-│   ├── id/                    # UUID v7 generation (id.New) — app-side, not a DB default
-│   ├── middleware/            # RequestID, Logger (slog), Error, CORS
-│   ├── pagination/             # parses ?limit=&offset=, response envelope
-│   └── tx/                    # carries a transaction on the ctx (tx.Do / tx.From) so two repositories commit together
-└── app/                       # domain packages — empty until you `generate module`
+│   ├── apperror/              # central error type (status + payload)
+│   ├── dberr/                 # maps DB errors to constraint kind — shared by every domain
+│   ├── httpx/                 # HTTP helpers shared by every domain
+│   ├── id/                    # UUID v7 generation (id.New)
+│   ├── middleware/            # RequestID, Logger, Error, CORS{{#if auth}}, auth{{/if}}{{#if rbac}}, RBAC{{/if}}{{#if observability}}, metrics, tracing{{/if}}
+│   ├── pagination/            # parses ?limit=&offset=, response envelope
+│   └── tx/                    # carries a transaction on the context
+└── app/                       # one package per domain, added with `generate module`
 ```
 
+The tree shows the baseline. Installed optional features add the process and
+platform packages listed in the section above without changing these module
+boundaries.
+
+Cross-feature adapters belong in `internal/composition/`, not in `cmd/api/`.
+The API wiring file selects infrastructure, invokes those adapters, and
+registers routes. Keep one-way dependencies and expose only narrow public
+capabilities from each feature.
+
+Optional features stay in the same architecture: auth owns user application
+use cases and provider ports, RBAC owns role policy, worker owns queue/mail
+adapters, and observability owns metrics/tracing setup.
+
 ## Run
 
 ```bash
@@ -42,7 +79,10 @@ 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
+{{#if worker}}{{#if (eq queue "river")}}make river-migrate                 # create River's job tables before queued mail
+{{else}}# start Redis and set REDIS_URL before running the worker
+{{/if}}{{/if}}
+make run                           # APP_ENV=development enables the convenience schema bootstrap
 ```
 
 `make run`/`make test`/`make migrate-up`/`make migrate-down` load `.env` if
@@ -65,17 +105,27 @@ falls back to `docker exec` into whichever container is publishing
 other Postgres container{{else}}any Postgres container{{/if}} you already have running.
 
 Server listens on `:8080` (override with `PORT`). Ctrl+C = graceful shutdown.
+{{#if worker}}`make dev` starts both the HTTP API and the worker; `make run` starts only the API.
+{{/if}}
 
 ## Makefile
 
 ```bash
 make run            # go run ./cmd/api
-make build          # go build -o bin/api ./cmd/api
+{{#if worker}}make dev            # run cmd/api and cmd/worker together
+make worker         # run cmd/worker separately
+{{#if (eq queue "river")}}make river-migrate  # create/update River's Postgres job tables
+make river-migrate-test # same River tables in TEST_DB_DSN
+{{else}}# start Redis before running make worker
+{{/if}}
+{{/if}}{{#if auth}}make seed           # run one-shot cmd/seed
+{{/if}}make build          # go build -o bin/api ./cmd/api
 make test           # go test ./...
 make fmt            # gofmt -w .
 make vet            # go vet ./...
 make lint           # golangci-lint run (see .golangci.yml)
 make tidy           # go mod tidy
+make tools          # install pinned migrate and golangci-lint tools
 make db-create       # create the database itself (safe to re-run)
 make db-drop         # drop the database
 make migrate-up      # apply migrations (reads DB_DSN from ENV_FILE)
@@ -103,10 +153,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 +179,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
@@ -152,9 +216,17 @@ make docker-up      # local postgres first
 {{/if}}
 make db-create DB_NAME={{dbName}}_test
 make migrate-up-test
+{{#if (eq queue "river")}}make river-migrate-test
+{{/if}}
 TEST_DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=disable REQUIRE_TEST_DB=true go test ./...
 ```
 
+{{#if (eq queue "river")}}The River integration test also starts a real worker,
+enqueues a JSON job, and waits for its backend-neutral handler. River's own
+schema history is separate from this project's application migrations, and the
+`river-migrate` targets use the pinned River version from `go.mod`.
+{{/if}}
+
 ## Error payload
 
 ```json
@@ -183,40 +255,51 @@ Then open `docs/openapi.bundled.yaml` — it needs no network and no running ser
 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
+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
 
+{{#if worker}}
 Two processes, one image, one target each:
 
 ```bash
 docker build --target api    -t {{projectName}}-api .
-docker build --target worker -t {{projectName}}-worker .    # once `add worker` exists
+docker build --target worker -t {{projectName}}-worker .
 ```
 
 `api` is the last stage, so a plain `docker build .` builds it — the worker
-stage has to be asked for by name, and only resolves once `add worker` has
-created `cmd/worker`.
+stage has to be asked for by name.{{#if auth}} `cmd/seed` is a one-shot
+operational binary run through `make seed`, not a long-running target.{{/if}}
+{{else}}
+The base project has one long-running `cmd/api` image. A worker target becomes
+available after `go-scaffold add worker`; do not deploy a worker that has not
+been generated.
+{{/if}}
 
 Both stages are distroless and run as `nonroot`, so there is no shell in either
 image. Debug against the `build` stage instead:
 `docker run --rm -it --entrypoint sh $(docker build -q --target build .)`.
 
-`cmd/api` serves HTTP. `cmd/worker` consumes the queue and is a separate
-deployment with **no port and no health endpoint** — scale it independently,
-and remember that not running it means queued mail is never sent, silently.
+`cmd/api` serves HTTP.{{#if worker}} `cmd/worker` consumes the queue and is a
+separate deployment with **no port and no health endpoint** — scale it
+independently, and remember that not running it means queued mail is never
+sent, silently.{{/if}}
 
 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 |