Document every exported symbol and how callers use the library.

Co-authored-by: Cursor <cursoragent@cursor.com>

auth.go

@@ -29,8 +29,14 @@ type Auth struct {
 	v tokenVerifier
 }
 
-// FromEnv reads the process environment. See the authentication procedure for names.
-// Both USER_TOKEN_PUBLIC_KEY_FILE and OIDC_ISSUER set, or neither set, is an error.
+// FromEnv reads the process environment and builds an Auth.
+// Set USER_TOKEN_PUBLIC_KEY_FILE or OIDC_ISSUER, not both and not neither.
+// Static mode also reads USER_TOKEN_ISSUER and USER_TOKEN_AUDIENCE.
+// OIDC mode reads OIDC_AUDIENCE and optional OIDC_GROUPS_CLAIM.
+// Optional USER_TOKEN_SKEW is a time.Duration; empty uses 1 minute.
+// It returns an error when the mode is ambiguous, the key file is unreadable,
+// USER_TOKEN_SKEW cannot be parsed, or OIDC discovery fails.
+// ctx is used for OIDC discovery.
 func FromEnv(ctx context.Context) (*Auth, error) {
 	pubFile := strings.TrimSpace(os.Getenv("USER_TOKEN_PUBLIC_KEY_FILE"))
 	oidcIss := strings.TrimSpace(os.Getenv("OIDC_ISSUER"))
@@ -89,7 +95,9 @@ func New(ctx context.Context, cfg Config) (*Auth, error) {
 	return &Auth{v: v}, nil
 }
 
-// Verify checks a raw JWT (no "Bearer " prefix).
+// Verify checks a raw JWT. raw has no "Bearer " prefix.
+// A failed check wraps ErrUnauthorized.
+// Startup and configuration failures do not.
 func (a *Auth) Verify(ctx context.Context, raw string) (Caller, error) {
 	return a.v.verify(ctx, raw)
 }