@nakedev/go-scaffold 0.4.3 → 0.5.0

package/templates/add/rbac/migrations/add_roles.down.sql.hbs

@@ -1,14 +1,6 @@
--- if an admin created a custom role after this migration and it's still
--- assigned to any user, dropping the roles table would orphan that value —
--- raise a clear, actionable error instead of a raw FK-violation.
-DO $$
-BEGIN
-    IF EXISTS (SELECT 1 FROM user_svc.users WHERE role NOT IN ('staff', 'admin')) THEN
-        RAISE EXCEPTION 'cannot roll back add_roles: users still have a role other than staff/admin — reassign them to staff/admin first';
-    END IF;
-END $$;
-
-ALTER TABLE user_svc.users DROP COLUMN role;
+-- Auth owns users.role, so RBAC removes only the constraint it added. The
+-- column and existing assignments remain valid for auth-only operation.
+ALTER TABLE user_svc.users DROP CONSTRAINT IF EXISTS users_role_fkey;
 
 DROP TABLE role_svc.role_permissions;
 DROP TABLE role_svc.permissions;

package/templates/add/rbac/migrations/add_roles.up.sql.hbs

@@ -33,9 +33,20 @@ INSERT INTO role_svc.permissions (code, description) VALUES
 INSERT INTO role_svc.role_permissions (role_code, permission_code)
 SELECT 'admin', code FROM role_svc.permissions;
 
--- cross-schema FK: role_svc's migration is the one place allowed to alter
--- user_svc's table, because this feature's whole point is "give users a
--- role" — see docs/architect/patterns.md's FK rules for why a plain FK, not
--- an app-level existence check, is the right way to enforce this.
-ALTER TABLE user_svc.users
-    ADD COLUMN role VARCHAR(20) NOT NULL DEFAULT 'staff' REFERENCES role_svc.roles(code);
+-- Auth owns the stable users.role column. RBAC owns the role catalog and adds
+-- only the cross-schema constraint after that catalog exists. This keeps each
+-- migration aligned with its module instead of making RBAC recreate auth's
+-- persistence shape.
+DO $$
+BEGIN
+    IF NOT EXISTS (
+        SELECT 1
+        FROM pg_constraint
+        WHERE conname = 'users_role_fkey'
+          AND conrelid = 'user_svc.users'::regclass
+    ) THEN
+        ALTER TABLE user_svc.users
+            ADD CONSTRAINT users_role_fkey
+            FOREIGN KEY (role) REFERENCES role_svc.roles(code);
+    END IF;
+END $$;

package/templates/add/worker/internal/platform/queue/river_test.go.hbs

@@ -0,0 +1,84 @@
+package queue
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+)
+
+type riverRoundTripJob struct {
+	Marker string `json:"marker"`
+}
+
+func (riverRoundTripJob) Kind() string { return "queue-test-round-trip" }
+
+// TestRiverEnqueueAndWorkerProcess proves the Postgres queue path beyond
+// client construction: a job is written, picked up by the worker adapter,
+// decoded, and handed to the registered backend-neutral handler.
+func TestRiverEnqueueAndWorkerProcess(t *testing.T) {
+	dsn := os.Getenv("TEST_DB_DSN")
+	if dsn == "" {
+		if os.Getenv("REQUIRE_TEST_DB") == "true" {
+			t.Fatal("TEST_DB_DSN is required when REQUIRE_TEST_DB=true")
+		}
+		t.Skip("River integration test skipped: set TEST_DB_DSN to a database with River migrations")
+	}
+
+	db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open test database: %v", err)
+	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("get test database handle: %v", err)
+	}
+	t.Cleanup(func() { _ = sqlDB.Close() })
+
+	worker, err := NewRiverWorker(db, 1)
+	if err != nil {
+		t.Fatalf("create River worker: %v", err)
+	}
+
+	received := make(chan string, 1)
+	worker.Handle((riverRoundTripJob{}).Kind(), func(_ context.Context, raw []byte) error {
+		var job riverRoundTripJob
+		if err := json.Unmarshal(raw, &job); err != nil {
+			return err
+		}
+		received <- job.Marker
+		return nil
+	})
+
+	workerCtx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(func() {
+		cancel()
+		stopCtx, stopCancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer stopCancel()
+		if err := worker.Stop(stopCtx); err != nil {
+			t.Errorf("stop River worker: %v", err)
+		}
+	})
+	if err := worker.Start(workerCtx); err != nil {
+		t.Fatalf("start River worker: %v", err)
+	}
+
+	expected := uuid.NewString()
+	if err := worker.Enqueue(context.Background(), riverRoundTripJob{Marker: expected}, nil); err != nil {
+		t.Fatalf("enqueue River job: %v", err)
+	}
+
+	select {
+	case actual := <-received:
+		if actual != expected {
+			t.Fatalf("worker received marker %q, want %q", actual, expected)
+		}
+	case <-time.After(10 * time.Second):
+		t.Fatal("River worker did not process the enqueued job within 10s")
+	}
+}

package/templates/create/base/.claude/skills/go-scaffold/SKILL.md.hbs

@@ -76,6 +76,7 @@ Run from the project root and pass every value as a flag:
 go-scaffold generate module <name> [--profile <lean|crud|cqrs>] [--defaults] [--auth] [--permission <code>]
 go-scaffold generate method <module> <name> --type <get|post|put|patch|delete> [--get-mode all|one] [--field <name>]
 go-scaffold generate migration <name>
+go-scaffold check
 go-scaffold config
 go-scaffold add auth --store <postgres|redis> --browser-topology <same-origin|same-site|cross-site> [--defaults] [--yes]
 go-scaffold add worker --queue <postgres|redis> [--defaults]
@@ -116,10 +117,10 @@ corresponding features installed. There is no final confirmation for module
 generation; review the profile and flags before running it.
 
 `go-scaffold config` changes defaults for future modules only. Existing modules
-are not rewritten. `config show` and `config validate` are intentionally
-read-only and do not open a wizard. The bare `generate` command first asks
-whether to generate a module, method, or migration; the bare `add` command
-first asks which infrastructure feature to add.
+are not rewritten. `check`, `config show`, and `config validate` are
+intentionally read-only and do not open a wizard. The bare `generate` command
+first asks whether to generate a module, method, or migration; the bare `add`
+command first asks which infrastructure feature to add.
 
 ## Generated module contract
 
@@ -128,34 +129,41 @@ defaults. On a fresh project that is a Lean module with:
 
 ~~~text
 internal/app/<pkg>/
-  model/model.go
-  dto.go
-  errors.go
-  repository.go
-  service.go
+  domain/entity.go
+  domain/errors.go
+  ports/repository.go
+  application/dto.go
+  application/service.go
+  application/service_test.go
+  adapters/inbound/http/dto.go
+  adapters/inbound/http/handler.go
+  adapters/inbound/http/handler_test.go
+  adapters/outbound/postgres/model.go
+  adapters/outbound/postgres/repository.go
+  adapters/outbound/postgres/repository_test.go
   composition.go
-  handler.go
-  service_test.go
-  handler_test.go
-  repository_test.go
 migrations/<version>_create_<plural>.{up,down}.sql
 ~~~
 
 The Lean/minimal module has no endpoint yet, but includes the complete
 data-access surface and test seams needed by generate method. The CRUD profile
 adds a CRUD starter and routes list/get/create/update/delete. The CQRS profile
-adds separate commands.go and queries.go application handlers; Advanced can
-combine CRUD + CQRS, or use CQRS alone before adding methods one at a time.
+replaces `application/service.go` and its test with
+`application/commands.go`, `application/queries.go`, and
+`application/cqrs_test.go`; Advanced can combine CRUD + CQRS, or use CQRS
+alone before adding methods one at a time. Service and CQRS are mutually
+exclusive within one module, but may coexist across modules.
 With OpenAPI enabled it also creates the per-domain documents and updates
 docs/openapi.yaml.
 
 Feature-local composition.go constructs repository → application handlers →
 handler. A module generated with `--cqrs` constructs separate command/query
 handlers there; a regular module constructs its service there.
-cmd/api/wiring.go is the process composition root: it selects shared
-infrastructure, supplies explicit cross-feature ports/security dependencies,
-and registers routes. Do not move business rules or feature-internal
-constructors into wiring, or hand-edit root route markers for a new endpoint.
+`internal/composition/` owns process-level adapters between feature ports.
+`cmd/api/wiring.go` selects shared infrastructure, invokes those adapters, and
+registers routes. Do not move business rules or feature-internal constructors
+into either process-level location, or hand-edit root route markers for a new
+endpoint.
 
 ## Method shapes and stub safety
 
@@ -182,14 +190,19 @@ This project is modular plus Hexagonal/DDD-friendly, with CQRS available via
 the `cqrs` profile or the backwards-compatible
 `go-scaffold generate module <name> --cqrs` flag:
 
-- handlers are inbound adapters and know HTTP/Gin only;
-- services or commands.go/queries.go (and, for complex flows,
-  internal/app/<feature>/application/) are application/use-case boundaries and
-  depend on narrow ports;
-- models and domain invariants stay independent of Gin, GORM, Redis, and HTTP;
+- `adapters/inbound/http/dto.go` owns JSON names, binding/validation tags, and
+  request/response mapping; handlers are inbound adapters and know HTTP/Gin
+  only;
+- `application/service.go` or `application/commands.go` plus
+  `application/queries.go` are application/use-case boundaries and depend on
+  narrow ports. The service and CQRS shapes are mutually exclusive inside one
+  module;
+- `domain/` entities and invariants stay independent of Gin, GORM, Redis, and
+  HTTP; persistence models belong under `adapters/outbound/postgres`;
 - repositories/token stores/mail/queue clients are outbound adapters;
-- composition.go wires one feature locally, while cmd/api/wiring.go wires
-  the process.
+- composition.go wires one feature locally, internal/composition/ wires
+  cross-feature capabilities, and cmd/api/wiring.go boots the process and
+  registers routes.
 
 DDD does not require every CRUD row to become a large aggregate. CQRS optional:
 use the CQRS profile when command and query models, consistency, or
@@ -199,9 +212,10 @@ service and repository port are clearer. Do not add a broker, a second
 database, or empty command/query layers just for naming.
 
 Never import another feature's private model, repository, or handler. For
-cross-feature behavior, define a narrow public application port, use a
-documented feature API, or publish an explicit event. Keep dependencies
-flowing inward:
+cross-feature behavior, define a narrow public application port, put a
+synchronous adapter in internal/composition/ (importing only the feature's
+public package root), use a documented feature API, or publish an explicit
+event. Keep dependencies flowing inward:
 
 ~~~text
 handler -> application/use case -> domain + ports -> adapters
@@ -209,13 +223,13 @@ handler -> application/use case -> domain + ports -> adapters
                                   +--- composition -+
 ~~~
 
-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.
+Auth and RBAC use the same canonical split as every other feature:
+`domain/`, `application/`, `ports/`, `adapters/`, and a feature-local
+`composition.go`. Auth owns user use cases and ports; RBAC owns role policy and
+authorization adapters. There is no `compat/`, feature-level `model/`, or
+second implementation tree. If an existing security flow needs a refactor,
+split it at the application boundary and keep provider SDKs, Gin, and GORM
+inside their respective adapters.
 
 ## Authentication and browser OAuth contract
 
@@ -345,6 +359,10 @@ 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 the project uses River, run `make river-migrate-test` after
+`make migrate-up-test`. The River integration test must enqueue a real job and
+observe the worker handler; a process that only boots is not enough evidence.
+
 Only in the `go-scaffold` source repository, run `pnpm run verify` for CLI or
 template changes, then generate a fresh sample project and inspect both its
 source and guidance files. A generated Go project does not contain the

package/templates/create/base/.golangci.yml.hbs

@@ -15,8 +15,8 @@ linters:
     depguard:
       # What keeps this a modular monolith rather than a pile of folders: a
       # domain may not reach into another domain's package. It declares a
-      # narrow interface for what it needs and cmd/api/wiring.go supplies the
-      # concrete service — see docs/architect/patterns.md "Calling Another
+      # narrow interface for what it needs and internal/composition plus
+      # cmd/api/wiring.go supply the concrete service — see docs/architect/patterns.md "Calling Another
       # Domain's Logic". Without this, the first shortcut someone takes stays
       # invisible until the coupling is everywhere.
       #

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

@@ -29,21 +29,23 @@ 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
+- **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:** models, value rules, and invariants stay independent of Gin,
+- **Domain:** entities, 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,
+- **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, 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.
+  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
@@ -61,7 +63,9 @@ 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:
+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
@@ -70,15 +74,28 @@ handler -> application/use case -> domain + ports -> adapters
 ```
 
 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.
+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
-model/service/repository/handler), or adding a **new endpoint** to an existing
-domain, stop and run the CLI:
+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
@@ -107,8 +124,8 @@ Recognize indirect requests as generation work:
 
 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.
+new endpoint; the CLI keeps the inbound adapter, application port, test seam,
+and OpenAPI/migration patching in sync.
 
 ## What the CLI does not decide
 
@@ -166,13 +183,11 @@ approval before changing their contract.
 - 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.
+- 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
@@ -231,6 +246,10 @@ 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
@@ -244,19 +263,24 @@ work untouched.
 
 ## Command quick reference
 
-- `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
+- `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 handler/service and, for a GET-one lookup, repository plus test
-  seam. It never overwrites a same-named method.
+  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.

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

@@ -22,28 +22,55 @@ 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                # process entry point, config, slog, graceful shutdown
-    └── wiring.go              # composition root: infrastructure + domain registration
+├── 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
@@ -52,6 +79,9 @@ make docker-up                     # local Postgres (postgres:5432)
 {{/if}}
 make db-create                     # create the {{dbName}} database itself (once — safe to re-run)
 go mod tidy
+{{#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
 ```
 
@@ -75,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)
@@ -176,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
@@ -208,32 +256,39 @@ go-scaffold generate module orders
 ```
 
 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
+(`{{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:
 

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

@@ -22,7 +22,8 @@ import (
 // run is this binary's composition root — the only function that sees every
 // module and wires them to each other. Modules never import one another; a
 // domain that needs another's behaviour declares a narrow interface and gets
-// the concrete service from here (see docs/architect/patterns.md).
+// its concrete implementation from the process composition package (see
+// docs/architect/patterns.md).
 //
 // It returns an error rather than calling os.Exit, so every defer below runs
 // on the way out and main() holds the only exit in the binary.
@@ -55,7 +56,7 @@ func run() error {
 
 	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
+		// domain gets its own (see the outbound postgres model'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