fix: make release

- public API streamline
- Failf[T]("msg") -	originate a failure from a message; embed a cause with %w
- Err[T](err) - sets .err verbatim (the return zero, err / sentinel case)

.devcontainer/devcontainer.json

@@ -62,6 +62,8 @@
   "forwardPorts": [8080],
 
   "remoteEnv": {
-    "GOPRIVATE": "gitea.djmil.dev"
+    "GOPRIVATE": "gitea.djmil.dev",
+    // Adds ./bin/ to PATH so built binaries are runnable by name after `make build`.
+    "PATH": "${containerWorkspaceFolder}/bin:${localEnv:PATH}"
   }
 }

.vscode/tasks.json

@@ -9,14 +9,6 @@
       "presentation": { "reveal": "always", "panel": "shared" },
       "problemMatcher": "$go"
     },
-    {
-      "label": "run",
-      "type": "shell",
-      "command": "make run",
-      "group": "none",
-      "presentation": { "reveal": "always", "panel": "dedicated" },
-      "isBackground": false
-    },
     {
       "label": "test",
       "type": "shell",

CLAUDE.md

@@ -66,8 +66,12 @@ tools.versions           Pinned tool versions (sourced by Makefile and pre-push
   - top-level entry points defer `result.Catch(&err)` (or use `result.Run(...)`) to convert any result exit into a normal Go error; genuine runtime panics (nil-deref, etc.) are re-panicked
   - **`result.Catch` is incompatible with `-tags result_goexit`**: it relies on `recover()` which cannot intercept `runtime.Goexit`; prefer `result.Run`/`result.Go` which work in both builds
   - bridge existing `(T, error)` stdlib/third-party calls with `result.Of(...)`: `result.Of(os.ReadFile("cfg.json")).Expect("read config")`
+  - construct failures with these constructors, each a distinct intent — don't invent more:
+    - `result.Ok[T](v)` / `result.Err[T](err)` — the two field constructors: a success value, or a bare error boxed verbatim (use `Err` for `return zero, err` and sentinels)
+    - `result.Failf[T]("msg")` — *originate* a failure from a message; embed a cause with `%w` (`result.Failf[T]("load config: %w", err)`)
+    - `result.Wrap[U](r, "msg")` — *propagate* an already-failed `Expect` into a new type `U`, optionally adding context; only valid on a failed result (panics on a success), so guard with `if r.Err() != nil`. Use this instead of pulling the error out with `r.Err()` by hand
   - use `result.StackTrace(err)` to retrieve the capture-site stack from a caught error
-  - still use `fmt.Errorf("context: %w", err)` when wrapping errors *before* constructing a `result.Fail`
+  - still use `fmt.Errorf("context: %w", err)` when wrapping errors *before* constructing a `result.Err`
 - **Logging** — logs go to `stderr` per 12-factor XI; human output goes to `stdout` via `fmt.Print*`.
   Use `logger.NewCLI(level, debugFile)` for CLI apps: auto-detects TTY → human text on terminal,
   JSON when piped. Use `logger.New(level)` for headless services that always want JSON.
@@ -153,3 +157,5 @@ make clean         # remove bin/
 - 2026-04-01 — Added make release: lists tags with no args; validates semver, runs test-race+lint+security, then tags+pushes.
 - 2026-04-23 — Documented result layering rule: pkg/ libraries only return Expect[T]; .Expect()/.Must() calls belong in application-layer code.
 - 2026-06-03 — pkg/logger v0.4.0: replaced NewDevelopment with NewCLI(level, debugFile); two-mode model (human text on TTY / JSON when piped); debug file mode; IsInteractive() helper. Established "form over mechanism" as core design principle.
+- 2026-06-13 — Build stamping + multi-binary build: internal/buildinfo (Version, Commit, BuildTime injected via -ldflags); make build discovers all cmd/* via find and produces named binaries in ./bin/; make run replaced with make run/<name> pattern; devcontainer adds ./bin to PATH via ${containerWorkspaceFolder}.
+- 2026-06-14 — pkg/result: reworked the failure surface into four intent-split constructors — Ok/Err (field constructors: value / bare error), Failf (originate from a message, %w for a cause), Wrap[U](r, "msg") (propagate a failed Expect into a new type; panics on success). Removed Errf/Errw. Wrap eliminates the r.Err() unwrap-rewrap dance; behavioral guarantees covered in pkg/result/wrap_test.go.

Makefile

@@ -1,11 +1,19 @@
-.PHONY: help init setup build run test test-race test-verbose lint lint-fix security docs release clean
+.PHONY: help init setup build test test-race test-verbose lint lint-fix security docs release clean
 
 include tools.versions
 
 # ── Variables ──────────────────────────────────────────────────────────────────
-BINARY_NAME  := app
-BINARY_PATH  := ./bin/$(BINARY_NAME)
-CMD_PATH     := ./cmd/app
+MODULE   := $(shell go list -m)
+VERSION  ?= $(shell git describe --tags 2>/dev/null || echo dev)
+COMMIT   := $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown)
+BUILT_AT := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
+LDFLAGS  := -ldflags "\
+  -X $(MODULE)/internal/buildinfo.Version=$(VERSION) \
+  -X $(MODULE)/internal/buildinfo.Commit=$(COMMIT) \
+  -X $(MODULE)/internal/buildinfo.BuildTime=$(BUILT_AT)"
+
+CMDS := $(shell find cmd -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+BINS := $(patsubst cmd/%,bin/%,$(CMDS))
 
 # ── Default target ─────────────────────────────────────────────────────────────
 help: ## Show this help message
@@ -34,12 +42,11 @@ tools: ## Install tool binaries to GOPATH/bin (versions from tools.versions)
 	go install golang.org/x/pkgsite/cmd/pkgsite@$(PKGSITE_VERSION)
 
 # ── Build ──────────────────────────────────────────────────────────────────────
-build: ## Compile the binary to ./bin/
-	go build -o $(BINARY_PATH) $(CMD_PATH)
+build: $(BINS) ## Compile all cmd/* binaries to ./bin/ (stamped with version, commit, build time)
 
-# ── Run ────────────────────────────────────────────────────────────────────────
-run: ## Run the application with default flags
-	go run $(CMD_PATH)/main.go
+bin/%: cmd/%
+	@mkdir -p bin
+	go build $(LDFLAGS) -o $@ ./$<
 
 # ── Test ───────────────────────────────────────────────────────────────────────
 test: ## Run all tests
@@ -72,7 +79,7 @@ docs: ## Serve package documentation locally via pkgsite (http://localhost:8080)
 
 # ── Release ────────────────────────────────────────────────────────────────────
 release: ## List releases, or tag+push a new one (usage: make release VERSION=v0.1.0)
-ifdef VERSION
+ifeq ($(origin VERSION), command line)
 	@echo "$(VERSION)" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+$$' || \
 		(echo "VERSION must be semver: v0.1.0"; exit 1)
 	@git diff --quiet && git diff --cached --quiet || \

README.md

@@ -75,10 +75,13 @@ make tools         # (optional) install tool binaries to GOPATH/bin for IDE inte
 ### 3. Build and run
 
 ```bash
-make build  # compiles to ./bin/app
-make run    # go run with default flags
+make build   # compiles every cmd/* binary to ./bin/, stamped with git commit + build time
 ```
 
+Every subdirectory under `cmd/` becomes a named binary in `./bin/`. In the devcontainer,
+`./bin/` is on `PATH` automatically, so after `make build` you can run `app` (or any other
+binary) directly — with any flags — from any directory in the terminal.
+
 ---
 
 ## Daily workflow
@@ -89,7 +92,8 @@ make test-race     # … with race detector
 make lint          # go vet + golangci-lint
 make lint-fix      # go fix + golangci-lint auto-fix
 make security      # gosec + govulncheck
-make release       # list tags, or run full checks then tag+push (make release VERSION=v0.1.0)
+make release       # list tags
+make release VERSION=v0.1.0  # run full checks then tag+push
 ```
 
 > **Keyboard shortcut (VSCode):** `Ctrl+Shift+B` → build, `Ctrl+Shift+T` → test.
@@ -130,15 +134,6 @@ Commands live in `.claude/commands/` and are available to anyone who clones the
 
 ---
 
-## Releasing
-
-```bash
-make release                    # list all existing tags
-make release VERSION=v0.1.0     # run full checks, then tag and push
-```
-
----
-
 ## Devcontainer
 
 Open this repo in VSCode and choose **"Reopen in Container"**. Run `make init` to

cmd/app/config.go

@@ -6,6 +6,7 @@ import (
 
 // Config is the root configuration object. Add sub-structs as the app grows.
 type Config struct {
+	Version bool
 	App     AppConfig
 	Logger  LoggerConfig
 	Greeter GreeterConfig
@@ -38,6 +39,7 @@ type GreeterConfig struct {
 //	cfg := config.parseArgs()
 //	fmt.Println(cfg.App.Port)
 func parseArgs() *Config {
+	version := flag.Bool("version", false, "print version information and exit")
 	name := flag.String("name", "Gopher", "application name")
 	port := flag.Int("port", 8080, "listen port")
 	env := flag.String("env", "dev", "environment: dev | staging | prod")
@@ -47,6 +49,7 @@ func parseArgs() *Config {
 	flag.Parse()
 
 	return &Config{
+		Version: *version,
 		App: AppConfig{
 			Port: *port,
 			Env:  *env,

cmd/app/main.go

@@ -10,6 +10,7 @@ import (
 	"os"
 	"path/filepath"
 
+	"gitea.djmil.dev/go/template/internal/buildinfo"
 	"gitea.djmil.dev/go/template/internal/greeter"
 	"gitea.djmil.dev/go/template/pkg/logger"
 	"gitea.djmil.dev/go/template/pkg/result"
@@ -44,6 +45,11 @@ func newApp(cfg *Config) *app {
 func main() {
 	conf := parseArgs()
 
+	if conf.Version {
+		fmt.Println(buildinfo.String())
+		return
+	}
+
 	app := newApp(conf)
 	app.log.WithFields(map[string]any{
 		"app": filepath.Base(os.Args[0]),

internal/buildinfo/buildinfo.go

@@ -0,0 +1,25 @@
+// Package buildinfo exposes build-time metadata injected via -ldflags.
+// All vars default to safe fallbacks so the binary runs without stamping.
+//
+// Wire into the binary by passing LDFLAGS from the Makefile:
+//
+//	go build -ldflags "-X .../internal/buildinfo.Commit=$(git rev-parse --short HEAD) \
+//	                   -X .../internal/buildinfo.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
+//	                   -X .../internal/buildinfo.Version=$(git describe --tags)"
+package buildinfo
+
+import "fmt"
+
+// Version is the semver release tag (e.g. "v1.2.3") or "dev" for untagged builds.
+var Version = "dev"
+
+// Commit is the short git SHA of the build (e.g. "a1b2c3d").
+var Commit = "unknown"
+
+// BuildTime is the UTC timestamp when the binary was compiled (RFC 3339).
+var BuildTime = "unknown"
+
+// String returns a one-line summary suitable for a --version flag or startup log line.
+func String() string {
+	return fmt.Sprintf("version=%s commit=%s built=%s", Version, Commit, BuildTime)
+}

internal/greeter/greeter.go

@@ -26,7 +26,7 @@ func New(log *logger.Logger) *Service {
 // Greet returns a personalized greeting and logs the interaction.
 func (s *Service) Greet(name string) result.Expect[string] {
 	if name == "" {
-		return result.Errf[string]("name must not be empty")
+		return result.Failf[string]("name must not be empty")
 	}
 
 	msg := fmt.Sprintf("Hello, %s!", name)

internal/greeter/greeter_test.go

@@ -4,9 +4,9 @@ import (
 	"testing"
 
 	"gitea.djmil.dev/go/template/internal/greeter"
+	"gitea.djmil.dev/go/template/pkg/check"
 	"gitea.djmil.dev/go/template/pkg/logger"
 	"gitea.djmil.dev/go/template/pkg/result"
-	"gitea.djmil.dev/go/template/pkg/testutil"
 )
 
 // ── Service (unit tests) ──────────────────────────────────────────────────────
@@ -16,12 +16,12 @@ func TestGreet(t *testing.T) {
 
 	t.Run("returns personalized greeting", func(t *testing.T) {
 		msg, err := svc.Greet("World").Unwrap()
-		testutil.NoError(t, err)
-		testutil.Equal(t, msg, "Hello, World!")
+		check.NoError(t, err)
+		check.Equal(t, msg, "Hello, World!")
 	})
 
 	t.Run("rejects empty name", func(t *testing.T) {
-		testutil.ErrorContains(t, svc.Greet("").Err(), "name must not be empty")
+		check.ErrorContains(t, svc.Greet(""), "name must not be empty")
 	})
 }
 
@@ -45,6 +45,6 @@ func TestFakeUsageExample(t *testing.T) {
 	}
 
 	msg, err := fake.Greet("Alice").Unwrap()
-	testutil.NoError(t, err)
-	testutil.Equal(t, msg, "Hello, Alice!")
+	check.NoError(t, err)
+	check.Equal(t, msg, "Hello, Alice!")
 }

pkg/check/check.go

@@ -0,0 +1,132 @@
+// Package check provides lightweight test helpers to reduce boilerplate in
+// table-driven tests.
+//
+// Error-family functions (NoError, Error, ErrorContains) accept either a plain
+// error or a result.Expect[T] value — the package extracts the error from
+// whichever type it receives.
+//
+// Every helper calls t.Helper() so failures are reported at the call site.
+package check
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+
+	"gitea.djmil.dev/go/template/pkg/result"
+)
+
+// extractErr pulls an error out of v, which must be error or result.Expect[T].
+// Fatally fails the test for any other type.
+func extractErr(t *testing.T, v any) error {
+	t.Helper()
+	if v == nil {
+		return nil
+	}
+	switch x := v.(type) {
+	case error:
+		return x
+	case interface{ Err() error }:
+		return x.Err()
+	default:
+		t.Fatalf("check: unsupported type %T (want error or result.Expect[T])", v)
+		return nil
+	}
+}
+
+// NoError fails the test if v contains a non-nil error.
+func NoError(t *testing.T, v any) {
+	t.Helper()
+	if err := extractErr(t, v); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// Error fails the test if v contains no error.
+func Error(t *testing.T, v any) {
+	t.Helper()
+	if extractErr(t, v) == nil {
+		t.Fatal("expected error, got nil")
+	}
+}
+
+// ErrorContains fails the test if v contains no error or its message does not
+// contain substr.
+func ErrorContains(t *testing.T, v any, substr string) {
+	t.Helper()
+	err := extractErr(t, v)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+		return
+	}
+	if !strings.Contains(err.Error(), substr) {
+		t.Errorf("error %q does not contain %q", err.Error(), substr)
+	}
+}
+
+// Equal fails the test if got != want.
+func Equal[T comparable](t *testing.T, got, want T) {
+	t.Helper()
+	if got != want {
+		t.Errorf("got %v, want %v", got, want)
+	}
+}
+
+// NotEqual fails the test if got == want.
+func NotEqual[T comparable](t *testing.T, got, want T) {
+	t.Helper()
+	if got == want {
+		t.Errorf("expected values to differ, got %v", got)
+	}
+}
+
+// DeepEqual fails the test if got and want are not deeply equal.
+// Use instead of Equal for maps, slices, and structs with slice fields.
+func DeepEqual(t *testing.T, got, want any) {
+	t.Helper()
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("got %v, want %v", got, want)
+	}
+}
+
+// ElementsMatch fails the test if got and want do not contain the same
+// elements regardless of order, including duplicates. T must be comparable —
+// for slices or maps as elements, use DeepEqual after sorting manually.
+func ElementsMatch[T comparable](t *testing.T, got, want []T) {
+	t.Helper()
+	if len(got) != len(want) {
+		t.Errorf("length mismatch: got %d elements, want %d", len(got), len(want))
+		return
+	}
+	freq := make(map[T]int, len(want))
+	for _, v := range want {
+		freq[v]++
+	}
+	for _, v := range got {
+		if freq[v]--; freq[v] < 0 {
+			t.Errorf("unexpected element: %v", v)
+			return
+		}
+	}
+}
+
+// Ok fails the test if r holds an error, then returns the value.
+func Ok[T any](t *testing.T, r result.Expect[T]) T {
+	t.Helper()
+	if r.Err() != nil {
+		t.Fatalf("unexpected error: %v", r.Err())
+	}
+	return r.Value()
+}
+
+// OkNotNil fails the test if r holds an error or its value is the zero value.
+// T must be a pointer or comparable type where zero means absent.
+func OkNotNil[T comparable](t *testing.T, r result.Expect[T]) T {
+	t.Helper()
+	v := Ok(t, r)
+	var zero T
+	if v == zero {
+		t.Fatal("expected non-nil value, got zero")
+	}
+	return v
+}

pkg/logger/handler.go

@@ -47,6 +47,10 @@ type writeState struct {
 //	INFO:  message: k=v, …    full fields — debug mode dumps everything
 //	WARN:  warning: msg: k=v, …
 //	ERROR: error:   msg: k=v, …
+//
+// INFO fields are intentionally hidden in normal mode: they are context for a
+// debug session, not alerts for the operator. Put fields on WARN or ERROR when
+// the reader needs them immediately to understand a problem.
 type humanHandler struct {
 	w      io.Writer
 	level  slog.Level

pkg/logger/logger.go

@@ -54,7 +54,7 @@ type Logger struct {
 func New(level string) result.Expect[*Logger] {
 	lvl := parseLevel(level)
 	if lvl.Err() != nil {
-		return result.Errw[*Logger](lvl.Err(), "parse log level")
+		return result.Wrap[*Logger](lvl, "parse log level")
 	}
 
 	h := slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{Level: lvl.Value()})
@@ -76,7 +76,7 @@ func New(level string) result.Expect[*Logger] {
 func NewCLI(level string, debugOut io.Writer) result.Expect[*Logger] {
 	lvl := parseLevel(level)
 	if lvl.Err() != nil {
-		return result.Errw[*Logger](lvl.Err(), "parse log level")
+		return result.Wrap[*Logger](lvl, "parse log level")
 	}
 
 	if !isTerminal(os.Stderr) {
@@ -112,7 +112,7 @@ func IsInteractive() bool {
 func NewWriter(w io.Writer, level string) result.Expect[*Logger] {
 	lvl := parseLevel(level)
 	if lvl.Err() != nil {
-		return result.Errw[*Logger](lvl.Err(), "parse log level")
+		return result.Wrap[*Logger](lvl, "parse log level")
 	}
 
 	h := slog.NewJSONHandler(w, &slog.HandlerOptions{Level: lvl.Value()})
@@ -154,8 +154,6 @@ func (l *Logger) WithFields(fields map[string]any) *Logger {
 
 func parseLevel(level string) result.Expect[slog.Level] {
 	var lvl slog.Level
-	if err := lvl.UnmarshalText([]byte(level)); err != nil {
-		return result.Errw[slog.Level](err, "unknown level (use debug|info|warn|error)")
-	}
-	return result.Ok(lvl)
+	err := lvl.UnmarshalText([]byte(level))
+	return result.Of(lvl, err)
 }

pkg/logger/logger_test.go

@@ -3,8 +3,8 @@ package logger_test
 import (
 	"testing"
 
+	"gitea.djmil.dev/go/template/pkg/check"
 	"gitea.djmil.dev/go/template/pkg/logger"
-	"gitea.djmil.dev/go/template/pkg/testutil"
 )
 
 func TestNewCLI(t *testing.T) {
@@ -24,10 +24,10 @@ func TestNewCLI(t *testing.T) {
 			// In tests stderr is not a terminal — NewCLI uses JSON path.
 			r := logger.NewCLI(tc.level, nil)
 			if tc.wantErr {
-				testutil.ResultErr(t, r)
+				check.Error(t, r)
 				return
 			}
-			testutil.ResultOkNotNil(t, r)
+			check.OkNotNil(t, r)
 		})
 	}
 }
@@ -49,10 +49,10 @@ func TestNew(t *testing.T) {
 		t.Run(tc.level, func(t *testing.T) {
 			r := logger.New(tc.level)
 			if tc.wantErr {
-				testutil.ResultErr(t, r)
+				check.Error(t, r)
 				return
 			}
-			testutil.ResultOkNotNil(t, r)
+			check.OkNotNil(t, r)
 		})
 	}
 }

pkg/result/bench_test.go

@@ -252,7 +252,7 @@ func r_parseHeader3(raw string) result.Expect[bHeader] {
 	}
 	parts := strings.SplitN(raw, "|", 3)
 	if len(parts) != 3 {
-		return result.Errf[bHeader]("malformed record: %q", raw)
+		return result.Failf[bHeader]("malformed record: %q", raw)
 	}
 	return result.Ok(bHeader{raw: raw, id: parts[0], name: parts[1], val: parts[2]})
 }
@@ -273,10 +273,10 @@ func r_validate4(h bHeader) result.Expect[bFields] { return r_validate5(h) }
 func r_validate5(h bHeader) result.Expect[bFields] {
 	id, err := strconv.Atoi(h.id)
 	if err != nil {
-		return result.Errf[bFields]("parse id %q: %w", h.id, err)
+		return result.Failf[bFields]("parse id %q: %w", h.id, err)
 	}
 	if id <= 0 {
-		return result.Errf[bFields]("id %d: must be > 0", id)
+		return result.Failf[bFields]("id %d: must be > 0", id)
 	}
 	return result.Ok(bFields{id: id, name: h.name, val: h.val})
 }
@@ -297,7 +297,7 @@ func r_transform4(f bFields) result.Expect[bRecord] { return r_transform5(f) }
 func r_transform5(f bFields) result.Expect[bRecord] {
 	v, err := strconv.ParseFloat(f.val, 64)
 	if err != nil {
-		return result.Errf[bRecord]("parse value %q: %w", f.val, err)
+		return result.Failf[bRecord]("parse value %q: %w", f.val, err)
 	}
 	return result.Ok(bRecord{id: f.id, name: f.name, score: v * 1.5})
 }

pkg/result/doc.go

@@ -9,7 +9,7 @@
 //
 //	func parseHost(s string) result.Expect[string] {
 //		if s == "" {
-//			return result.Errf[string]("host must not be empty")
+//			return result.Failf[string]("host must not be empty")
 //		}
 //		return result.Ok(s)
 //	}
@@ -54,8 +54,10 @@
 //
 // # Constructors
 //
-// Use [Ok] to wrap a success value, [Err] / [Errf] / [Errw] to wrap errors,
-// and [Of] to bridge existing (value, error) return signatures:
+// [Ok] and [Err] are the two field constructors (a success value or a bare
+// error). On top of them, [Failf] originates a failure from a message (embed a
+// cause with %w), [Wrap] propagates an already-failed result into a new type,
+// and [Of] bridges existing (value, error) return signatures:
 //
 //	data := result.Of(os.ReadFile("cfg.json")).Expect("read config")
 //

pkg/result/example_test.go

@@ -10,7 +10,7 @@ import (
 // parseHost is an example of a simple utility function, that validates a hostname.
 func parseHost(s string) result.Expect[string] {
 	if s == "" {
-		return result.Errf[string]("host must not be empty")
+		return result.Failf[string]("host must not be empty")
 	}
 	return result.Ok(s)
 }
@@ -19,10 +19,10 @@ func parseHost(s string) result.Expect[string] {
 func parsePort(s string) result.Expect[int] {
 	port := result.Of(strconv.Atoi(s))
 	if port.Err() != nil {
-		return result.Errw[int](port.Err(), "result.Of")
+		return result.Wrap[int](port, "result.Of")
 	}
 	if port.Value() < 1 || port.Value() > 65535 {
-		return result.Errf[int]("%d out of range", port.Value())
+		return result.Failf[int]("%d out of range", port.Value())
 	}
 	return port
 }
@@ -148,3 +148,25 @@ func Example_unwrap() {
 	// Output:
 	// 443
 }
+
+// Example_wrap shows propagating a failure across result types. parsePort
+// returns Expect[int], but buildAddr returns Expect[string]; Wrap carries the
+// same failure into the new type and layers on its own context — no manual
+// r.Err() unwrap-and-rebuild. The result reads as a top-down trace: outermost
+// context first, root cause last.
+func Example_wrap() {
+	buildAddr := func(portStr string) result.Expect[string] {
+		port := parsePort(portStr) // Expect[int]
+		if port.Err() != nil {
+			return result.Wrap[string](port, "build address")
+		}
+		return result.Ok(fmt.Sprintf(":%d", port.Value()))
+	}
+
+	if r := buildAddr("99999"); r.Err() != nil {
+		fmt.Println("failed:", r.Err())
+	}
+	// Output:
+	// failed: example_test.go:161: build address
+	// example_test.go:25: 99999 out of range
+}

pkg/result/panic_test.go

@@ -16,7 +16,7 @@ import (
 // without a subprocess, so it is only documented here.
 func TestMustCollected(t *testing.T) {
 	err := result.Run(func() {
-		result.Errf[int]("unrecoverable").Must()
+		result.Failf[int]("unrecoverable").Must()
 	})
 
 	if err == nil {

pkg/result/result.go

@@ -49,32 +49,63 @@ func Ok[T any](v T) Expect[T] {
 	return Expect[T]{value: v}
 }
 
-// Err wraps an error in an Expect.
+// Err wraps an error in an Expect — the failure-side counterpart to [Ok],
+// setting the error field verbatim with no added location or message. Use it to
+// pass an error along unchanged, including a package-level sentinel:
+//
+//	return result.Err[T](err)
+//	return result.Err[bHeader](ErrEmpty)
+//
+// To build a failure from a message (optionally wrapping a cause with %w), use
+// [Failf]; to carry an already-failed result into a new type, use [Wrap].
 func Err[T any](err error) Expect[T] {
 	return Expect[T]{err: err}
 }
 
-// Errf wraps a formatted error in an Expect. It is a convenience shorthand
-// for [Err][fmt.Errorf(format, args...)]. The caller's file and line are
-// prepended to the error message automatically.
-func Errf[T any](format string, args ...any) Expect[T] {
+// Failf originates a failure from a formatted message. Where [Err] boxes an
+// existing error verbatim, Failf builds a new one — optionally embedding a
+// cause with %w to preserve the errors.Is/As chain:
+//
+//	return result.Failf[string]("host must not be empty")
+//	return result.Failf[T]("create dir %q: %w", dir, err)
+//
+// The caller's file and line are prepended automatically. To propagate an
+// already-failed result, use [Wrap] instead of pulling its error out by hand.
+func Failf[T any](format string, args ...any) Expect[T] {
 	_, file, line, _ := runtime.Caller(1)
 	loc := fmt.Sprintf("%s:%d", filepath.Base(file), line)
 	return Expect[T]{err: fmt.Errorf(loc+": "+format, args...)}
 }
 
-// Errw wraps an existing error with a context message, following the standard
-// Go error-propagation convention (errors.Is/As chain is preserved). Each
-// wrapping level is placed on its own line so the full error reads as a
-// top-down trace: outermost context first, root cause last. The caller's file
-// and line are prepended automatically.
+// Wrap propagates a failed Expect[T] as an Expect[U], optionally annotating it
+// with a context message. It carries a failure across the type boundary between
+// two result-returning functions without the unwrap-then-rebuild dance of
+// reaching into [Expect.Err] by hand.
 //
-//	main.go:42: load config
-//	logger.go:35: parse log level
-//	strconv.Atoi: parsing "x": invalid syntax
-func Errw[T any](err error, format string, args ...any) Expect[T] {
+// Wrap is meaningful only on a failed result — a successful r holds a T whose
+// value cannot be retyped to U — so guard it with the usual error check:
+//
+//	lvl := parseLevel(level)
+//	if lvl.Err() != nil {
+//	    return result.Wrap[*Logger](lvl, "parse log level")
+//	}
+//
+// With no message Wrap retypes the failure verbatim. With a message (optionally
+// fmt.Sprintf-formatted) it follows Go's error-propagation convention: the
+// errors.Is/As chain is preserved and the caller's file and line are prepended,
+// each wrapping level on its own line so the error reads as a top-down trace.
+//
+// Calling Wrap on a successful r is a programmer error and panics.
+func Wrap[U, T any](r Expect[T], msgArgs ...any) Expect[U] {
+	if r.err == nil {
+		panic("result.Wrap called on a successful Expect")
+	}
+	if len(msgArgs) == 0 {
+		return Expect[U]{err: r.err}
+	}
 	_, file, line, _ := runtime.Caller(1)
-	return Expect[T]{err: fmt.Errorf("%s:%d: %s\n%w", filepath.Base(file), line, fmt.Sprintf(format, args...), err)}
+	msg := fmt.Sprintf(msgArgs[0].(string), msgArgs[1:]...)
+	return Expect[U]{err: fmt.Errorf("%s:%d: %s\n%w", filepath.Base(file), line, msg, r.err)}
 }
 
 // Of is a convenience constructor that bridges standard Go (value, error)
@@ -191,7 +222,7 @@ func Async[T any](fn func() T) <-chan Expect[T] {
 			if err := collectGoexitFailure(); err != nil {
 				ch <- Err[T](err)
 			} else {
-				ch <- Errf[T]("goroutine exited unexpectedly")
+				ch <- Failf[T]("goroutine exited unexpectedly")
 			}
 		}()
 		val = fn()

pkg/result/wrap_test.go

@@ -0,0 +1,82 @@
+package result_test
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"gitea.djmil.dev/go/template/pkg/result"
+)
+
+var errRoot = errors.New("root cause")
+
+// Intended usage of Wrap is demonstrated in example_test.go (parsePort). These
+// tests pin the behavioral guarantees that an example's Output cannot assert:
+// chain preservation, file:line stamping, stack survival, and the panic
+// contract on misuse.
+
+// TestWrapRetypesVerbatim verifies that Wrap with no message carries a failure
+// from one value type to another, preserving the error chain unchanged.
+func TestWrapRetypesVerbatim(t *testing.T) {
+	src := result.Err[int](errRoot) // Expect[int]
+
+	dst := result.Wrap[string](src) // Expect[string]
+
+	if !errors.Is(dst.Err(), errRoot) {
+		t.Fatalf("errors.Is chain not preserved: %v", dst.Err())
+	}
+	if dst.Err().Error() != errRoot.Error() {
+		t.Fatalf("verbatim wrap changed the message: got %q want %q", dst.Err(), errRoot)
+	}
+}
+
+// TestWrapAnnotates verifies that a context message is prepended with the
+// caller's file:line while the underlying chain stays intact and leads the
+// trace (outermost context first, root cause last).
+func TestWrapAnnotates(t *testing.T) {
+	src := result.Failf[int]("parse %d", 7)
+
+	dst := result.Wrap[string](src, "load config id=%d", 42)
+
+	msg := dst.Err().Error()
+	if !strings.Contains(msg, "load config id=42") {
+		t.Fatalf("formatted context missing: %q", msg)
+	}
+	if !strings.Contains(msg, "wrap_test.go:") {
+		t.Fatalf("caller file:line not prepended: %q", msg)
+	}
+	if !strings.Contains(msg, "parse 7") {
+		t.Fatalf("underlying cause lost: %q", msg)
+	}
+	if first, _, _ := strings.Cut(msg, "\n"); !strings.Contains(first, "load config id=42") {
+		t.Fatalf("context should head the trace, got first line %q", first)
+	}
+}
+
+// TestWrapPreservesStackError verifies that a failure captured by Expect (a
+// *stackError) survives the retype, so StackTrace still resolves it.
+func TestWrapPreservesStackError(t *testing.T) {
+	captured := result.Run(func() {
+		result.Err[int](errRoot).Expect("inner")
+	})
+	if captured == nil {
+		t.Fatal("setup: expected Run to collect an error")
+	}
+
+	dst := result.Wrap[string](result.Err[int](captured), "outer")
+
+	if result.StackTrace(dst.Err()) == "" {
+		t.Fatal("stack trace lost through Wrap")
+	}
+}
+
+// TestWrapOnSuccessPanics locks in the documented contract: Wrap is only valid
+// on a failed result; calling it on a success is a programmer error.
+func TestWrapOnSuccessPanics(t *testing.T) {
+	defer func() {
+		if recover() == nil {
+			t.Fatal("expected Wrap on a successful Expect to panic")
+		}
+	}()
+	_ = result.Wrap[string](result.Ok(1))
+}

pkg/testutil/testutil.go

@@ -1,75 +0,0 @@
-// Package testutil provides lightweight test helpers to reduce boilerplate in
-// table-driven tests.
-//
-// Every helper calls t.Helper() so failures are reported at the call site, not
-// inside this package.
-package testutil
-
-import (
-	"strings"
-	"testing"
-
-	"gitea.djmil.dev/go/template/pkg/result"
-)
-
-// NoError fails the test immediately if err is not nil.
-func NoError(t *testing.T, err error) {
-	t.Helper()
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-}
-
-// Error fails the test if err is nil.
-func Error(t *testing.T, err error) {
-	t.Helper()
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-}
-
-// ErrorContains fails the test if err is nil or its message does not contain substr.
-func ErrorContains(t *testing.T, err error, substr string) {
-	t.Helper()
-	Error(t, err)
-	if !strings.Contains(err.Error(), substr) {
-		t.Errorf("error %q does not contain %q", err.Error(), substr)
-	}
-}
-
-// Equal fails the test if got != want.
-func Equal[T comparable](t *testing.T, got, want T) {
-	t.Helper()
-	if got != want {
-		t.Errorf("got %v, want %v", got, want)
-	}
-}
-
-// ResultOk fails the test if r holds an error, then returns the value.
-func ResultOk[T any](t *testing.T, r result.Expect[T]) T {
-	t.Helper()
-	if r.Err() != nil {
-		t.Fatalf("unexpected error: %v", r.Err())
-	}
-	return r.Value()
-}
-
-// ResultOkNotNil fails the test if r holds an error or its value is nil.
-// T must be a pointer type.
-func ResultOkNotNil[T comparable](t *testing.T, r result.Expect[T]) T {
-	t.Helper()
-	v := ResultOk(t, r)
-	var zero T
-	if v == zero {
-		t.Fatal("expected non-nil value, got nil")
-	}
-	return v
-}
-
-// ResultErr fails the test if r does not hold an error.
-func ResultErr[T any](t *testing.T, r result.Expect[T]) {
-	t.Helper()
-	if r.Err() == nil {
-		t.Fatal("expected error, got nil")
-	}
-}