@nakedev/go-scaffold 0.4.3 → 0.5.0

package/templates/create/base/internal/composition/doc.go.hbs

@@ -0,0 +1,7 @@
+// Package composition contains process-level wiring and cross-feature adapters.
+//
+// Feature-local construction belongs in internal/app/<feature>/composition.go.
+// Keep this package focused on translating caller-owned ports to another
+// feature's public application capabilities. Do not put business rules,
+// persistence adapters, or HTTP handlers here.
+package composition

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

@@ -2,15 +2,17 @@
 
 ## Composition root
 
-`cmd/api/main.go` decides the exit code and nothing else. Everything it used to
-do lives in `cmd/api/wiring.go`, in a `run() error` — the one function that sees
-every module and hands them what they need.
+`cmd/api/main.go` decides the exit code and nothing else. `cmd/api/wiring.go`
+owns process bootstrap and route registration; `internal/composition/` owns
+reusable process-level adapters that connect feature ports.
 
 Modules never import one another. Each generated domain owns its local
-repository → service → handler composition in `composition.go`; `wiring.go`
-supplies the DB and any cross-feature security dependencies. A domain that
-needs another's behaviour declares a narrow interface for exactly what it
-needs and receives the concrete service from `run()`; `.golangci.yml` has a
+outbound adapter → service or command/query application handlers → inbound
+adapter composition in `composition.go`; `internal/composition/` owns
+cross-feature adapters and `wiring.go` supplies infrastructure, invokes those
+adapters, and registers routes. A domain that needs another's behaviour
+declares a narrow interface for exactly what it needs and receives its
+concrete implementation from the process composition; `.golangci.yml` has a
 depguard rule per domain that fails the build if anyone shortcuts that.
 
 Two things the split buys. `run()` returns an error instead of calling
@@ -21,32 +23,49 @@ you open to understand the binary: `wiring.go` grows with the system, which is
 what a composition root is for, while `main.go` stays put.
 
 
-> Status: generated by `@nakedev/go-scaffold`
-> Scope: initial scaffold
+> Status: generated by `@nakedev/go-scaffold`; refreshes as optional features are added
+> Scope: current generated project configuration
 
 ## 1. Topology
 
-**Decision:** Single Go binary (`cmd/api`), REST over Gin.
-**Rationale:** One process serves all domains; a second entry point
-(`cmd/worker`, `cmd/migrate`) gets its own `main.go` only once there's a real
-second process — `main.go` has no importers, so adding one later touches no
-other file.
+**Decision:** `cmd/api` serves REST over Gin. Optional operational binaries
+are separate entry points: `cmd/worker` for queued jobs and `cmd/seed` for
+one-shot bootstrap tasks when those features are installed.
+**Rationale:** The HTTP process stays independently deployable while worker and
+seed lifecycles remain explicit. Adding either binary does not turn an API
+handler or feature composition root into a process-wide god object.
 
 ## 2. Package Layout
 
 ```text
 cmd/
-└── api/main.go             # config, slog, graceful shutdown, wires domains
+└── api/
+    ├── main.go             # process entrypoint and exit code
+    └── wiring.go           # config, infrastructure, graceful shutdown, routes
 internal/
-├── platform/                # talks to real external systems (DB, later: cache, queue, mail, ...)
-│   └── database/
+├── composition/             # process-level cross-feature adapters
+├── platform/                # talks to real external systems
+│   └── database/             # PostgreSQL connection and pool
 ├── shared/                  # pure logic/framework glue, no I/O
 │   ├── config/  apperror/  dberr/  httpx/  id/
 │   └── middleware/  pagination/  tx/
 └── app/                     # domain packages (one per feature)
     └── <domain>/
+        ├── domain/          # business entities and errors
+        ├── ports/           # consumer-owned application dependencies
+        ├── application/     # service OR commands + queries
+        ├── adapters/inbound/http/ # request/response DTOs + HTTP adapter
+        ├── adapters/outbound/postgres/
+        └── composition.go   # feature-local object graph
 ```
 
+Installed process and platform additions:
+{{#if auth}}- `cmd/seed` and `platform/authprovider/google/` for user bootstrap and Google OAuth/OIDC
+{{/if}}{{#if worker}}- `cmd/worker` and `platform/{mail,queue}/` for queue/SMTP jobs{{#if (eq queue "asynq")}}, plus `platform/cache/` for Redis{{/if}}
+{{/if}}{{#if observability}}- `platform/telemetry/` for the OTLP exporter
+{{/if}}{{#if rbac}}- `shared/middleware/authz.go` and `app/role/` for RBAC policy
+{{/if}}
+
 **Decision:** `platform/` vs `shared/` is split by whether the code talks to
 a real external system.
 **Rationale:** Code that does I/O against Postgres/cache/queue/SMTP/S3 →
@@ -54,12 +73,19 @@ a real external system.
 add a `shared/utils` or similarly generic package — name it after what it
 actually does.
 
+Optional feature boundaries are explicit: auth owns user authentication and
+provider ports; RBAC owns role policy and authorization; worker owns queue and
+mail adapters; observability owns metrics/tracing setup. They do not create a
+second domain architecture.
+
 ## 3. API Style
 
 **Decision:** REST over Gin, one handler package per domain, every route
 grouped under{{#if apiPrefix}} `/{{apiPrefix}}`{{else}} no prefix{{/if}}.
-**Rationale:** `handler → service → repository`, one direction, all three
-layers in the same package — no cross-domain imports. The prefix is a
+**Rationale:** `inbound HTTP adapter → application boundary → domain + ports →
+outbound adapter`, one direction,
+with delivery, application, and persistence concerns kept inside the feature
+boundary — no cross-domain imports. The prefix is a
 single project-wide choice made at `create` time (`--api-prefix`) — there is
 no per-domain versioning; a domain that needs a real breaking change gets a
 new domain package (or a new field on the existing DTO), not a duplicated
@@ -80,10 +106,16 @@ from empty command/query wrappers, so it keeps one service until its business
 needs justify the split. CQRS here does not require a second database, broker,
 or event-sourcing runtime.
 
-When enabled, `commands.go` owns state-changing application use cases,
-`queries.go` owns read use cases, and `composition.go` constructs both. The
-HTTP handler is still an inbound adapter and `cmd/api/wiring.go` still only
-selects infrastructure and registers the feature.
+When enabled, `application/commands.go` owns state-changing application use
+cases, `application/queries.go` owns read use cases, and `composition.go`
+constructs both. The HTTP adapter is still an inbound adapter and
+`cmd/api/wiring.go` still selects infrastructure, invokes process-level
+adapters from `internal/composition/`, and registers the feature. A service
+module instead has one `application/service.go`; these
+styles are exclusive inside a module but can coexist across the monolith.
+
+The CQRS inbound adapter is wired through `NewHandler` with separate command
+and query ports. It does not generate an `application/service.go` facade.
 
 ## 5. Response and Error Model
 
@@ -92,7 +124,7 @@ selects infrastructure and registers the feature.
 **Rationale:** Handlers only ever do `c.Error(err); return` — no `c.JSON` per
 call site, no error-shape drift between domains.
 
-- Domain-specific errors live in each package's `errors.go` (e.g.
+- Domain-specific errors live in each module's `domain/errors.go` (e.g.
   `USER_NOT_FOUND`, not a bare `NOT_FOUND`)
 - DB errors are classified once in `shared/dberr` (`IsDuplicate`,
   `IsForeignKey`) and mapped to the right HTTP status per domain
@@ -169,5 +201,11 @@ skipped by the `os.Exit` calls already in there.
 
 - `go-scaffold generate module <name>` adds a new domain package and
   wires it into `cmd/api/wiring.go`
-- This document only reflects the initial scaffold — update it as the real
-  architecture evolves
+- `go-scaffold check` validates the physical split, process-composition
+  boundary, layer dependencies, and exclusive service/CQRS choice for every
+  discovered module
+- `go-scaffold add auth`, `add worker`, `add rbac`, and `add observability`
+  refresh this document while it still matches the generated version. A
+  hand-edited document is preserved and must be updated by its owner.
+- This document describes package boundaries, not completed business behavior;
+  generated methods remain explicit TODO/501 stubs until implemented.

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

@@ -1,7 +1,7 @@
 # Coding Patterns: {{projectName}}
 
-> Status: generated by `@nakedev/go-scaffold`
-> Last updated: scaffold creation time
+> Status: generated by `@nakedev/go-scaffold`; current generated-project conventions
+> Last reviewed: generated at project creation and refreshed with feature docs
 
 ## Domain Package Shape
 
@@ -10,44 +10,56 @@ like this — copy the shape by hand if you ever add one without the CLI:
 
 ```text
 internal/app/<domain>/
-├── model/             # domain model(s) + GORM table(s) — a folder, one file per table
-│   └── model.go
-├── dto.go             # request/response structs + mapping (never leak the model directly)
-├── errors.go          # domain error catalog (<DOMAIN>_NOT_FOUND, ...)
-├── repository.go       # the only place that touches the DB for this domain, every method takes ctx
-├── service.go          # business logic; declares the repository interface it needs (mockable in tests)
-├── commands.go         # optional: command port + state-changing application handlers (`--cqrs`)
-├── queries.go          # optional: query port + read-only application handlers (`--cqrs`)
-├── composition.go      # feature-local repository → service → handler wiring
-├── handler.go          # HTTP: routing, bind, delegate, respond
-├── service_test.go     # unit test, function-backed repository stub, no DB
-├── handler_test.go     # HTTP unit test, service stub, no DB
-└── repository_test.go  # Postgres integration test against migrated schema
+├── domain/
+│   ├── entity.go       # business state and invariants; no Gin/GORM/HTTP
+│   └── errors.go       # domain error catalog (<DOMAIN>_NOT_FOUND, ...)
+├── ports/
+│   └── repository.go   # consumer-owned persistence/application interfaces
+├── application/
+│   ├── dto.go          # transport-neutral use-case input/output types
+│   ├── service.go      # service-style use-case orchestration
+│   ├── commands.go     # CQRS writes, when selected
+│   ├── queries.go      # CQRS reads, when selected
+│   └── *_test.go       # application unit tests, no DB
+├── adapters/
+│   ├── inbound/http/
+│   │   ├── dto.go           # JSON/binding DTOs and application/HTTP mapping
+│   │   ├── handler.go       # Gin routing, error/response mapping
+│   │   └── handler_test.go  # HTTP adapter tests, no DB
+│   └── outbound/postgres/
+│       ├── model.go         # persistence model + explicit domain mapping
+│       ├── repository.go    # GORM adapter; the only DB access in the module
+│       └── repository_test.go # Postgres integration tests
+└── composition.go       # feature-local adapter → application → handler wiring
 ```
 
-### Model
-
-- Lives in its own `model` subpackage (`internal/app/<domain>/model`), imported
-  by the rest of the domain as `model.<Type>`
-- A folder, not a single file, so a domain with more than one table (e.g.
-  `order` + `order_item`) adds one file per table instead of growing a single
-  file — `generate module` only ever creates the first one
-- Every consumer inside `cmd/api/wiring.go` imports each domain's `model`
-  package under an alias (`ordermodel`, `usermodel`, ...) since they all share
-  the package name `model`
+`service.go` and `commands.go`/`queries.go` are mutually exclusive inside a
+module. Service and CQRS can coexist across different modules in the same
+modular monolith. The root package contains only `composition.go`; other code
+must import the specific boundary package it belongs to.
+
+### Domain and persistence model
+
+- `domain/entity.go` owns business state and invariants. It must not import
+  Gin, GORM, SQL drivers, Redis, HTTP, or environment configuration.
+- `adapters/outbound/postgres/model.go` owns persistence-only fields and
+  explicit `toDomain`/`fromDomain` mapping. A database column or GORM tag must
+  not silently become part of the business API.
+- A domain with more than one table should add one persistence model per table
+  in the outbound adapter, with the corresponding domain type or value object
+  kept in `domain/`.
 - `TableName()` returns a schema-qualified name (`order_svc.orders`, not
   `orders`) — every domain gets its own Postgres schema, created by its own
   migration (`CREATE SCHEMA IF NOT EXISTS`) and by `cmd/api/wiring.go` before
-  the development table bootstrap runs (the bootstrap creates tables, never
-  the schema they live in). A cross-domain FK is still fine — see the FK rules below — this
-  only stops one domain's table from silently colliding with another's, or a
-  raw SQL `JOIN` from reaching into a domain it doesn't own without at least
-  naming the schema it's crossing into.
+  the development table bootstrap runs. A cross-domain FK is still fine — see
+  the FK rules below — this only stops one domain's table from silently
+  colliding with another's.
 
 ## Layer Conventions
 
 ### Handler
-- Owns routing, request binding, and calling the service
+- Owns routing, request binding, and calling the application service or
+  command/query port
 - No business logic — `c.Error(err); return` on failure, nothing more
 - Reads pagination via `pagination.Parse(c)`, wraps list responses with
   `p.Response(out)`
@@ -64,22 +76,26 @@ selects the matching port for each route. They may share the same
 repository/database in this modular monolith — separate storage or event
 sourcing is not implied.
 
-The generated `Service` remains a compatibility facade for tests and existing
-callers. New feature code should depend on the narrower command/query port it
-actually needs. `generate module --defaults` uses the project default; choose
-the single service path for simple CRUD and CQRS only when the feature earns
-the extra boundary.
+The generated CQRS application has separate `CommandPort` and `QueryPort`
+interfaces and separate handlers. Its HTTP adapter receives both through
+`NewHandler`; there is no generated `application/service.go` facade to hide the
+split. New feature code should depend on the narrower port it actually needs.
+`generate module --defaults` uses the project default; choose the single service
+path for simple CRUD and CQRS only when the feature earns the extra boundary.
 
 ### Service
 - Contains the business logic, knows nothing about HTTP
-- Declares a `repository` interface for what it needs from the data layer —
-  this is what makes it mockable in `service_test.go` without a DB
+- Depends on consumer-owned interfaces from `ports/` for what it needs from
+  the data layer — this is what makes it mockable in `application/*_test.go`
+  without a DB
 - Generates the ID itself via `id.New()` before calling `repository.Create`
-- Maps DB errors to domain errors with `dberr.IsDuplicate` /
-  `dberr.IsForeignKey`, never lets a raw DB error escape
+- Returns domain errors and never constructs an HTTP response. The outbound
+  adapter maps driver errors with `dberr.IsDuplicate` /
+  `dberr.IsForeignKey` before they reach the application boundary.
 
-### Repository
-- The only file per domain that talks to GORM
+### Repository adapter
+- `adapters/outbound/postgres/repository.go` is the only module code that talks
+  to GORM
 - Every method takes `ctx context.Context` first, so a cancelled request
   cancels the query
 - Every query starts from `tx.From(ctx, r.db).WithContext(ctx)`, never from
@@ -95,16 +111,18 @@ the extra boundary.
   and GORM can misinterpret a bare struct arg
 
 ### DTOs
-- `createInput`/`updateInput` (request, `binding:` tags) and `response`
-  (what's actually sent back) are separate types from the model — adding a
-  DB column later doesn't leak it to clients until you decide to
+- `application/dto.go` owns transport-neutral use-case inputs and output read
+  models. `adapters/inbound/http/dto.go` owns JSON names, binding/validation
+  tags, and explicit request/response mapping at the HTTP boundary.
+- When `generate method` adds a POST input, it adds both the application input
+  and an inbound HTTP DTO/mapping seam. Fill both deliberately; do not bind
+  Gin JSON directly into an application type.
 
 ### Error Catalog
-- One function per error, not a shared `var` — the error middleware writes
-  the request ID onto the returned pointer, so a shared instance would race
-  across concurrent requests
-- Codes are domain-specific (`ORDER_NOT_FOUND`), never the generic
-  `apperror.NewNotFound()` directly from a handler
+- Domain sentinels live in `domain/errors.go`; they are values used with
+  `errors.Is`, not HTTP errors or mutable request state.
+- The inbound adapter maps those sentinels to domain-specific HTTP codes
+  (`ORDER_NOT_FOUND`); domain/application code never constructs an HTTP error.
 
 ## Optimistic Locking
 
@@ -123,13 +141,13 @@ and `response` echoes it back: the client round-trips the value, and an
 update that arrives without one is rejected rather than treated as a blind
 overwrite.
 
-In a CRUD skeleton the service translates `ErrStaleVersion` into `errStale()`
-from the domain's error catalog (`<DOMAIN>_STALE`, HTTP 409) — a lost update
-is a client problem to retry, not a 500. A minimal module has the same
-`Repository.Update` and the same `errStale()` waiting for it, just no update
-path yet. Keep the chain intact when you add one by hand:
-`errors.Is(err, ErrStaleVersion)` → `errStale()`, and never set `Version` on
-the model yourself — `Repository.Update` owns the bump.
+The inbound adapter maps `ErrStaleVersion` to the domain's `<DOMAIN>_STALE`
+HTTP 409 response — a lost update is a client problem to retry, not a 500. A
+minimal module has the same `Repository.Update` guard waiting for its first
+update use case. Keep the chain intact when you add one by hand:
+`errors.Is(err, domain.ErrStaleVersion)` → adapter HTTP mapping, and never set
+`Version` on the persistence model yourself — `Repository.Update` owns the
+bump.
 
 ## Domains With a Foreign Key (Relations) — 3 Rules
 
@@ -143,18 +161,19 @@ if this project has one):
 2. **Declare the FK constraint in migration SQL**
    (`REFERENCES ... ON DELETE ...`), not a GORM tag — the development bootstrap
    doesn't create the constraint, which would make dev and prod schemas diverge.
-3. **Map the FK error to the right status** via `dberr.IsForeignKey` —
-   inserting a reference to a missing parent, or deleting a parent that
-   still has children, is a client error (409/422), not a 500. Don't
-   pre-check existence before insert; let the DB enforce it atomically and
-   catch the error — a pre-check has a TOCTOU race.
+3. **Map the FK error to the right status** in the outbound adapter with
+   `dberr.IsForeignKey`, then let the inbound adapter render it — inserting a
+   reference to a missing parent, or deleting a parent that still has children,
+   is a client error (409/422), not a 500. Don't pre-check existence before
+   insert; let the DB enforce it atomically and catch the error — a pre-check
+   has a TOCTOU race.
 
 ## Calling Another Domain's Logic
 
 For behavior, not just a data reference (e.g. `order` needs `user`'s email
-to put on a receipt) — the caller's `service.go` declares its own narrow
-interface for exactly what it needs, the same way it already declares a
-`repository` interface.
+to put on a receipt) — the caller's application boundary (`application/service.go`,
+`application/commands.go`, or `application/queries.go`) declares its own narrow interface for exactly
+what it needs, the same way it already declares a `repository` interface.
 
 **The interface speaks in the caller's own terms.** No domain package ever
 imports another domain package — `golangci-lint`'s `depguard` rules enforce
@@ -162,15 +181,16 @@ this, and it is the same rule that makes rule 1 above work. So the interface
 names primitives, or types the caller owns, never `user.Response`:
 
 ```go
-// order/service.go
+// order/application/service.go
 type userLookup interface {
     EmailOf(ctx context.Context, id uuid.UUID) (string, error)
 }
 ```
 
-The feature keeps its own repository/service/handler composition in
-`composition.go`; `cmd/api/wiring.go` supplies the DB and any cross-feature
-security dependencies. For example, auth and RBAC are composed locally and
+The feature keeps its own repository/application/handler composition in
+`composition.go`; `cmd/api/wiring.go` supplies the DB and registers routes.
+Process-level adapters for cross-feature capabilities live in
+`internal/composition/`. For example, auth and RBAC are composed locally and
 the root passes only the role feature's public capabilities:
 
 ```go
@@ -181,12 +201,13 @@ user.NewHandlerFromDB(
 ```
 
 For ordinary cross-domain behaviour, the caller still declares a narrow
-interface next to its application service. Its local composition accepts that
-port, while the root supplies an adapter; the root never reaches into the
-callee's repository or handler. A func-to-interface shim is one small option:
+interface next to its application boundary. Its local composition accepts that
+port, while `internal/composition/` supplies an adapter; the process root never
+reaches into the callee's repository or handler. A func-to-interface shim is
+one small option:
 
 ```go
-// order/service.go
+// order/application/service.go
 type UserLookupFunc func(ctx context.Context, id uuid.UUID) (string, error)
 
 func (f UserLookupFunc) EmailOf(ctx context.Context, id uuid.UUID) (string, error) {
@@ -201,6 +222,10 @@ can never silently ripple into `order`. The adapter is also the honest place
 to notice you are reaching for something that should have been the caller's
 own data.
 
+Cross-feature integration tests belong under `internal/integration`, where
+they may compose real feature services and adapters. A feature's own unit and
+repository tests stay inside its package and must not import another feature.
+
 - **One direction only.** If `user` would need to call back into `order`,
   don't wire it both ways — either the two belong in one domain, or the
   callback needs an event/queue, not a direct call.
@@ -216,31 +241,33 @@ own data.
 go-scaffold generate method <domain> <name> --type <get|post|put|patch|delete> [--get-mode all|one] [--field <name>]
 ```
 
-Patches `handler.go`/`service.go` (and `commands.go` or `queries.go` for a
-module generated with `--cqrs`; plus `repository.go` + the relevant repository
-port + its `repositoryStub` test stub, for a `get --get-mode one --field`
-lookup) in place, at the `// go-scaffold:*` marker comments near the end of
-each file. **Don't delete those markers** — they're where the next
-`generate method` call inserts. The method body is always left as a `TODO`
-that compiles and returns a clean `500` (`apperror.NewInternal(cause)`) rather
-than guessing at business logic — same spirit as `generate module`'s
-placeholder fields.
+Patches `adapters/inbound/http/handler.go`, its request DTO seam, and the application boundary (or
+`application/commands.go`/`application/queries.go` for a CQRS module; plus
+`ports/repository.go` and the outbound repository adapter/test seam for a
+`get --get-mode one --field` lookup) in place, at the
+`// go-scaffold:*` marker comments near the end of each file. **Don't delete
+those markers** — they're where the next `generate method` call inserts. The
+method body is always left as a compiling `TODO` rather than guessing at
+business logic — same spirit as `generate module`'s placeholder fields.
 
 ## Testing Conventions
 
 - Unit and integration tests live in the same directory as the code under
   test (Go convention) — never a separate `test/` folder. `test/` is only
   for e2e black-box suites or fixtures.
-- `service_test.go` uses a function-backed repository stub so each dependency
-  method has independent behavior and argument assertions.
-- `handler_test.go` uses a service stub — HTTP tests never need Postgres.
-- `repository_test.go` runs against a migrated Postgres database inside a
+- `application/service_test.go` uses a function-backed repository stub so each
+  dependency method has independent behavior and argument assertions.
+- `adapters/inbound/http/handler_test.go` checks route composition; focused
+  HTTP tests can inject an application port and never need Postgres.
+- `adapters/outbound/postgres/repository_test.go` runs against a migrated
+  Postgres database inside a
   transaction that's rolled back after each test. Local runs may skip when
   `TEST_DB_DSN` is unset; CI sets `REQUIRE_TEST_DB=true` so it must run.
 
 ## Docs Maintenance
 
-- This document describes the output produced by `go-scaffold create` for
-  the current configuration
-- If new domains are generated or the architecture changes, update this doc
-  to match the real project
+- This document describes the conventions used by generated domains and the
+  canonical split emitted by `go-scaffold`.
+- When a shared generator contract changes, update the templates and add a
+  regression test. Generated projects with hand-edited docs are left alone by
+  incremental feature refreshes and must be updated by their owners.

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

@@ -1,6 +1,6 @@
 # Tech Stack: {{projectName}}
 
-> Status: generated by `@nakedev/go-scaffold`
+> Status: generated by `@nakedev/go-scaffold`; refreshes as optional features are added
 
 ## Stack Overview
 
@@ -15,6 +15,9 @@
 | Logging | `log/slog`, JSON handler |
 | Migrations | [golang-migrate](https://github.com/golang-migrate/migrate) |
 | Testing | stdlib `testing`, real Postgres for integration tests |
+| Authentication | {{#if auth}}JWT access/refresh sessions, password recovery, email verification, provider login, and MFA{{else}}optional via `go-scaffold add auth`{{/if}} |
+| Authorization | {{#if rbac}}RBAC role/permission middleware{{else}}optional RBAC via `go-scaffold add rbac`{{/if}} |
+| Background jobs | {{#if worker}}{{queue}} queue backend with SMTP mail and `cmd/worker`{{else}}optional via `go-scaffold add worker`{{/if}} |
 
 ## Scaffolded Capabilities
 
@@ -24,6 +27,9 @@
 - Docker Compose (local Postgres): `{{#if docker}}enabled{{else}}disabled{{/if}}`
 - OpenAPI docs (`docs/openapi.yaml`, working-copy only — never served over HTTP): `{{#if openapiDocs}}enabled{{else}}disabled{{/if}}`
 - Metrics + tracing (Prometheus `/metrics`, OpenTelemetry for Gin + GORM, `cmd/api` only): `{{#if observability}}enabled{{else}}disabled{{/if}}`
+- Authentication and browser OAuth: `{{#if auth}}enabled{{else}}disabled{{/if}}`
+- Background worker and mail: `{{#if worker}}enabled{{else}}disabled{{/if}}`
+- RBAC roles, permissions, and authorization: `{{#if rbac}}enabled{{else}}disabled{{/if}}`
 - API route prefix: `{{#if apiPrefix}}/{{apiPrefix}}{{else}}(none){{/if}}`
 - CI (`.github/workflows/ci.yml` — build, vet, gofmt check, golangci-lint, `go test` with a real Postgres service): always enabled
 
@@ -31,8 +37,14 @@
 
 {{#if docker}}- Local Postgres comes from `docker-compose.yml`
 {{else}}- No Docker scaffolding included — bring your own Postgres and point `DB_DSN` at it
-{{/if}}- `APP_ENV=development` enables the convenience table bootstrap;
+{{/if}}{{#if worker}}{{#if (eq queue "river")}}- Run `make river-migrate` before relying on queued jobs in a fresh database;
+  run `make river-migrate-test` as well when `REQUIRE_TEST_DB=true` runs the
+  River worker round-trip test.{{/if}}{{/if}}
+- `APP_ENV=development` enables the convenience table bootstrap;
   `APP_ENV=production` requires `migrate up` as a deploy step instead
+{{#if worker}}{{#if (eq queue "river")}}- River uses the database/sql driver and polls for jobs instead of receiving
+  PostgreSQL LISTEN/NOTIFY wakeups; this is deliberate for a shared GORM pool.
+{{/if}}{{/if}}
 {{#if openapiDocs}}- `docs/openapi.yaml` is hand-written, not generated — update it whenever an
   endpoint or DTO changes
 {{/if}}{{#if observability}}- `OTEL_EXPORTER_OTLP_ENDPOINT` unset (dev default) means tracing exports
@@ -44,3 +56,6 @@
   resolves them to the versions that feature was built against instead of
   whatever happened to be newest that day. The full list is `go.mod`; this
   table only covers what `create` itself brings in
+- Auth, worker, and RBAC are opt-in. Their `add` commands update this snapshot
+  when the generated file is untouched; hand-edited docs are left alone and
+  require a manual update.

package/templates/generate/module/hexagonal/adapters/inbound/http/dto.go.hbs

@@ -0,0 +1,45 @@
+package httpadapter
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/{{modulePath}}/application"
+
+	"github.com/google/uuid"
+)
+
+// response is the HTTP representation of the application output. Keep JSON
+// names and protocol-only fields at this inbound boundary.
+type response struct {
+	ID        uuid.UUID `json:"id"`
+	CreatedAt time.Time `json:"created_at"`
+	Version   int       `json:"version"`
+}
+
+func toResponse(out application.Response) response {
+	return response{ID: out.ID, CreatedAt: out.CreatedAt, Version: out.Version}
+}
+
+// Request DTOs belong to the inbound adapter. Keep JSON names, validation
+// tags, and request-to-command mapping here; application inputs stay usable
+// from jobs, tests, and other non-HTTP callers.
+type createInput struct {
+	// TODO: mirror the request fields added to application.CreateInput.
+}
+
+type updateInput struct {
+	Version int `json:"version" binding:"required,min=1"`
+	// TODO: mirror the update fields added to application.UpdateInput.
+}
+
+func toCreateInput(in createInput) application.CreateInput {
+	// TODO: map request fields explicitly as the application contract evolves.
+	_ = in
+	return application.CreateInput{}
+}
+
+func toUpdateInput(in updateInput) application.UpdateInput {
+	return application.UpdateInput{Version: in.Version}
+}
+
+// go-scaffold:dto

package/templates/generate/module/hexagonal/adapters/inbound/http/dto.minimal.go.hbs

@@ -0,0 +1,28 @@
+package httpadapter
+
+import (
+	"time"
+
+	"{{goModule}}/internal/app/{{modulePath}}/application"
+
+	"github.com/google/uuid"
+)
+
+// response is the HTTP representation of the application output. Keep JSON
+// names and protocol-only fields at this inbound boundary.
+//nolint:unused // generate method uses this seam when the first endpoint is added.
+type response struct {
+	ID        uuid.UUID `json:"id"`
+	CreatedAt time.Time `json:"created_at"`
+	Version   int       `json:"version"`
+}
+
+//nolint:unused // generate method uses this seam when the first endpoint is added.
+func toResponse(out application.Response) response {
+	return response{ID: out.ID, CreatedAt: out.CreatedAt, Version: out.Version}
+}
+
+// A lean module has no HTTP body endpoints yet. The marker gives
+// `generate method` a stable place to add request DTOs when a POST is earned.
+
+// go-scaffold:dto