Epic: v2.5.0 consumer-feedback release (hooks + tenancy + error envelope + extensibility)

[thegdsks]

Goal

Ship the four additive items from the 2026-06-22 consumer feedback session as a single v2.5.0 release. No breaking changes. Byte-stable public API preserved.

Why a bundled release

Each item compounds the others:

• The hook surface (feat(hooks): Config.Hooks surface (OnSignup, OnSignin, OnPasswordChange, OnMFAEnabled, OnTokenIssued, OnOrgSwitch) #76) unlocks the default OnSignup that tenancy (feat(tenancy): public helpers + optional auto-create personal org (kill the SQL-seeding friction) #77) relies on for auto-provisioning.
• Fixing the error envelope (fix(middleware): RequireAuth must emit RFC 7807 problem+json (matches RequirePermission) #78) standardizes the contract that hook-emitted errors propagate through.
• Selective re-exports (feat(extensibility): selective re-exports from internal/* to unblock deep customization #79) covers the deep-customization cases that hooks alone can't reach.

Shipping any one of these alone would leave consumers stitching together stopgaps. Together they kill the ~140 LOC of local workarounds our reference consumer is maintaining.

Scope

#	Item	Type	Blocker chain
#76	Config.Hooks surface (OnSignup, OnSignin, OnPasswordChange, OnMFAEnabled, OnTokenIssued, OnOrgSwitch)	feat	—
#77	Tenancy primitives + optional auto-create personal org	feat	depends on #76
#78	RequireAuth emits RFC 7807 (consistency with RequirePermission)	fix	independent
#79	Selective re-exports from internal/*	feat	follow-up after #76

Out of scope (explicitly)

• Module path /v3 correction (chore(modpath): correct go.mod to /v3 per Go Semantic Import Versioning (deferred to v3.0.0) #80) — requires major version bump, deferred to a future v3.0.0
• Facade refactor — separate architectural decision, not needed for these features
• MCP / OAuth-AS surface changes — v2.4 already solid here

Ship order

1. fix(middleware): RequireAuth must emit RFC 7807 problem+json (matches RequirePermission) #78 first — small, additive, no design needed. Patch out to v2.4.1 as a pre-cursor if useful.
2. feat(hooks): Config.Hooks surface (OnSignup, OnSignin, OnPasswordChange, OnMFAEnabled, OnTokenIssued, OnOrgSwitch) #76 next — biggest design effort. Hook contract + recovery semantics + RFC 7807 mapping.
3. feat(tenancy): public helpers + optional auto-create personal org (kill the SQL-seeding friction) #77 builds on feat(hooks): Config.Hooks surface (OnSignup, OnSignin, OnPasswordChange, OnMFAEnabled, OnTokenIssued, OnOrgSwitch) #76 — uses default OnSignup for tenant provisioning.
4. feat(extensibility): selective re-exports from internal/* to unblock deep customization #79 last — informed by what hooks can't cover after feat(hooks): Config.Hooks surface (OnSignup, OnSignin, OnPasswordChange, OnMFAEnabled, OnTokenIssued, OnOrgSwitch) #76 + feat(tenancy): public helpers + optional auto-create personal org (kill the SQL-seeding friction) #77 land.

Acceptance for the release

• All four child issues closed
• CHANGELOG.md [2.5.0] section with grouped entries
• docs/MIGRATION.md v2.4 → v2.5 section (no break, but ergonomics shift)
• New examples/hooks/ and examples/multi-tenant/
• theauth.dev docs updated under Concepts > Hooks and Concepts > Tenancy
• go test -race -count=3 ./... clean
• No em dashes or en dashes added
• Release tagged v2.5.0, signed per docs/RELEASING.md

Reference

Closes the gap with better-auth (TS) on hooks ergonomics while keeping the Go + RFC-complete + self-host triangle that nothing else owns. See conversation thread for full competitive read.

Source: consumer feedback session 2026-06-22