Add documentation for HTMX-aware AuthenticationEntryPoint

- CHANGELOG.md: Add [Unreleased] entry for the new feature
- README.md: Add HTMX Support section under Security Features with
  override instructions; update features list and table of contents
- CLAUDE.md: Add HtmxAwareAuthenticationEntryPoint to Security section
  and AuthenticationEntryPoint override to Extension Points

Author: devondragon

CHANGELOG.md

@@ -1,3 +1,14 @@
+## [Unreleased]
+### Features
+- HTMX-aware AuthenticationEntryPoint for session expiry handling (#294)
+  - When HTMX requests (identified by `HX-Request: true` header) hit an expired session, the framework now returns a 401 JSON response with an `HX-Redirect` header instead of the default 302 redirect that causes HTMX to swap login page HTML into fragment targets.
+  - New classes:
+    - `HtmxAwareAuthenticationEntryPoint` — detects HTMX requests and returns 401 + JSON + `HX-Redirect`; delegates to wrapped entry point for standard browser requests
+    - `HtmxAwareAuthenticationEntryPointConfiguration` — registers the entry point via `@ConditionalOnMissingBean(AuthenticationEntryPoint.class)`
+  - `WebSecurityConfig` now always configures `exceptionHandling()` with the injected entry point (previously only configured when OAuth2 was enabled)
+  - Consumer override: define any `AuthenticationEntryPoint` bean to replace the default
+  - 100% backward-compatible: non-HTMX browser requests get the same 302 redirect as before
+
 ## [4.3.1] - 2026-03-22
 ### Features
 - No new user-facing features in this release.

CLAUDE.md

@@ -111,12 +111,14 @@ com.digitalsanctuary.spring.user
 - `DSUserDetails` - Custom UserDetails implementation wrapping User entity
 - `DSOAuth2UserService` / `DSOidcUserService` - OAuth2/OIDC user services
 - `LoginAttemptService` - Brute force protection with account lockout
+- `HtmxAwareAuthenticationEntryPoint` - Returns 401 JSON for HTMX requests instead of 302 redirect on session expiry
 
 **Extension Points:**
 - `BaseUserProfile` - Extend for custom user data (see PROFILE.md)
 - `UserProfileService<T>` - Interface for profile management
 - `BaseSessionProfile<T>` - Session-scoped profile access
 - `UserPreDeleteEvent` - Listen for user deletion to clean up related data
+- `AuthenticationEntryPoint` - Override via `@ConditionalOnMissingBean` to customize session expiry behavior
 
 ### Auto-Configuration
 

README.md

@@ -39,6 +39,7 @@ Check out the [Spring User Framework Demo Application](https://github.com/devond
     - [Role-Based Access Control](#role-based-access-control)
     - [Account Lockout](#account-lockout)
     - [Audit Logging](#audit-logging)
+    - [HTMX Support](#htmx-support)
   - [User Management](#user-management)
     - [Registration](#registration)
     - [Profile Management](#profile-management)
@@ -83,6 +84,7 @@ Check out the [Spring User Framework Demo Application](https://github.com/devond
   - Audit event framework for recording and logging security events, customizable to store audit events in a database or publish them via a REST API.
   - Role and Privilege setup service to define roles, associated privileges, and role inheritance hierarchy using `application.yml`.
   - Configurable Account Lockout after too many failed login attempts
+  - HTMX-aware session expiry handling — returns 401 JSON instead of 302 redirect for HTMX requests, preventing broken UI fragments
 
 - **Advanced Security**
   - Role and privilege-based authorization
@@ -504,6 +506,29 @@ user:
     flushRate: 10000
 ```
 
+### HTMX Support
+
+When HTMX-powered pages make requests (polling, fragment loading, etc.) and the user's session expires, Spring Security's default 302 redirect causes HTMX to swap the full login page HTML into each target element, breaking the UI.
+
+The framework automatically detects HTMX requests (via the `HX-Request` header) and returns a proper 401 response instead:
+
+- **Status**: `401 Unauthorized`
+- **Header**: `HX-Redirect: <loginUrl>` (triggers HTMX full-page redirect)
+- **Body**: `{"error": "authentication_required", "message": "Session expired. Please log in.", "loginUrl": "<loginUrl>"}`
+
+Non-HTMX browser requests continue to receive the standard 302 redirect to the login page.
+
+**Overriding the default behavior:**
+
+To provide a custom `AuthenticationEntryPoint`, define your own bean and the framework's default will back off automatically:
+
+```java
+@Bean
+public AuthenticationEntryPoint authenticationEntryPoint() {
+    return new MyCustomAuthenticationEntryPoint();
+}
+```
+
 ## User Management
 
 ### Registration