enforce result oriented coding style for Claude

CLAUDE.md

@@ -39,7 +39,13 @@ tools.versions           Pinned tool versions (sourced by Makefile and pre-push
 - **Module imports** — always use the full module path `gitea.djmil.dev/go/template/...`
 - **Packages** — keep `cmd/` thin (wiring only); business logic belongs in `internal/`
 - **Types** — expose concrete types from constructors (`New(...) *Type`); never wrap in an interface at the implementation site. Consumers define their own interfaces if they need one (Go's implicit satisfaction makes this free)
-- **Errors** — wrap with `fmt.Errorf("context: %w", err)`; never swallow errors silently
+- **Errors** — `pkg/result` is the default error-handling mechanism for all code in this repo, including public APIs:
+  - functions return `result.Expect[T]` instead of `(T, error)`
+  - callers unwrap with `.Expect("context")` (panics with annotated error + stack trace) or `.Must()` (panics with raw error)
+  - top-level entry points (e.g. `cmd/` functions, HTTP handlers) defer `result.Catch(&err)` to convert any result panic into a normal Go error; genuine runtime panics (nil-deref, etc.) are re-panicked
+  - bridge existing `(T, error)` stdlib/third-party calls with `result.Of(...)`: `result.Of(os.ReadFile("cfg.json")).Expect("read config")`
+  - 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`
 - **Logging** — use `log.WithField("key", val)` for structured context; never `fmt.Sprintf` in log messages; `log/slog` is the backend
 - **Config** — all configuration through `internal/config` (flag-parsed); no hard-coded values in logic packages
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help init setup build run test test-race lint lint-fix security clean
+.PHONY: help init setup build run test test-race lint lint-fix security docs clean
 
 include tools.versions
 
@@ -30,6 +30,7 @@ tools: ## Install tool binaries to GOPATH/bin (versions from tools.versions)
 	go install github.com/golangci/golangci-lint/cmd/golangci-lint@$(GOLANGCI_LINT_VERSION)
 	go install github.com/securego/gosec/v2/cmd/gosec@$(GOSEC_VERSION)
 	go install golang.org/x/vuln/cmd/govulncheck@$(GOVULNCHECK_VERSION)
+	go install golang.org/x/pkgsite/cmd/pkgsite@$(PKGSITE_VERSION)
 
 # ── Build ──────────────────────────────────────────────────────────────────────
 build: ## Compile the binary to ./bin/
@@ -64,6 +65,10 @@ security: ## Run gosec + govulncheck
 	@echo "--- govulncheck ---"
 	go run golang.org/x/vuln/cmd/govulncheck@$(GOVULNCHECK_VERSION) ./...
 
+# ── Docs ───────────────────────────────────────────────────────────────────────
+docs: ## Serve package documentation locally via pkgsite (http://localhost:8080)
+	go run golang.org/x/pkgsite/cmd/pkgsite@$(PKGSITE_VERSION) -open .
+
 # ── Release ────────────────────────────────────────────────────────────────────
 release: ## List releases, or tag+push a new one (usage: make release VERSION=v0.1.0)
 ifdef VERSION

tools.versions

@@ -2,3 +2,4 @@ DELVE_VERSION=v1.26.1
 GOLANGCI_LINT_VERSION=v1.64.8
 GOSEC_VERSION=v2.24.7
 GOVULNCHECK_VERSION=v1.1.4
+PKGSITE_VERSION=latest