docs: rewrite README into docs/, fix documented run paths, Keycloak stack, and two demo bugs

.dockerignore

@@ -0,0 +1,19 @@
+# Keep the build context small and keep local files out of the image.
+.git/
+.github/
+.gradle/
+build/
+build.bak/
+.superpowers/
+.vscode/
+.idea/
+docs/
+playwright/
+node_modules/
+**/node_modules/
+logs/
+*.log
+
+# Gitignored local config holding real credentials: must never reach an image.
+.env
+src/main/resources/application-local.yml

.gitignore

@@ -135,7 +135,8 @@ application-local.yml
 /project_concatenated.txt
 .env
 /repomix-output.txt
-src/main/resources/application-docker-keycloak.yml
+# src/main/resources/application-docker-keycloak.yml is tracked on purpose: it holds only ${ENV_VAR}
+# placeholders, and the Keycloak stack builds the app image from src/, so it must be in the repo.
 
 # VS Code: personal settings stay local, shared tasks.json is tracked
 .vscode/*

CHANGELOG.md

@@ -9,6 +9,66 @@ the library.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 2026-08-15
+
+### Added
+- Admin lock/unlock API (`POST /admin/lockAccount`, `POST /admin/unlockAccount`), guarded by
+  `ADMIN_PRIVILEGE` and backing the admin actions page, whose JavaScript already called those paths
+- `keycloak/README.md`: contents, ports, credentials, and realm re-export for the Keycloak stack
+- `.dockerignore`, so the image build context excludes `build/`, `.git/`, and local config
+
+### Changed
+- Rewrote `README.md` and split its content into `docs/CONFIGURATION.md`, `docs/DEVELOPMENT.md`,
+  `docs/TESTING.md`, `docs/EXTENDING.md`, `docs/AUTHENTICATION.md`, and `keycloak/README.md`
+- `Dockerfile` is now multi-stage on Java 21: a JDK stage runs `bootJar` inside the image, a JRE
+  stage runs it, so `docker compose up --build` works from a fresh clone with no local Gradle build
+- The Docker demo stack sets `USER_REGISTRATION_SENDVERIFICATIONEMAIL=false` in `compose.yaml`, so
+  registered accounts are enabled immediately instead of waiting on mail the relay cannot deliver
+- Moved `spring.docker.compose.file: compose.dev.yaml` from `application-local.yml-example` into base
+  `application.yml`, so `./gradlew bootRun` starts its database without a copied config file
+- `build.gradle` no longer extends `runtimeOnly` from `developmentOnly`, keeping
+  `spring-boot-docker-compose` out of the packaged jar (it made containerized runs fail at startup)
+- `application-local.yml-example` now points at the `compose.dev.yaml` database and seeds
+  `data-local.sql`, so the `local` profile has sample events
+- Added `/actuator/health` to `user.security.unprotectedURIs` for container healthchecks; the rest of
+  `/actuator` still requires a login
+- `src/main/resources/application-docker-keycloak.yml` is now tracked; it holds only environment
+  variable placeholders, so there is nothing to copy before running the Keycloak stack
+- `mise.toml` pins Java 21
+- `@Disabled` test annotations now point at `docs/TESTING.md`
+
+### Fixed
+- Keycloak OIDC stack, which could not complete a login: the realm export is now named `demo` rather
+  than `master` (Keycloak skips a `master` import), the client secret matches `keycloak.env`,
+  authorization services that blocked the import were removed, a `demo` user with an email address
+  was added, the browser-facing and container-facing Keycloak URLs are split, the client's redirect
+  URI is narrowed to the exact callback, and the healthcheck probes the realm's discovery document
+- `DemoSessionProfile` is now `@SessionScopedProfile`; as a plain `@Component` it was a singleton
+  shared by every HTTP session
+- `DomainRegistrationGuard`'s Javadoc link to the framework's registration guard documentation
+- The `local` quick start, which died at startup once `application-local.yml-example` was copied into
+  place: the example's masked Keycloak `client-secret` was not valid YAML, and its Keycloak
+  `issuer-uri` pointed at a host that does not resolve but that Spring Boot fetches at startup. The
+  Keycloak client registration and provider blocks are now commented out, with a pointer to the
+  Keycloak stack for OIDC
+- `application-playwright-test.yml` replaced `user.security.unprotectedURIs` wholesale and lost
+  `/user/registration/passwordless`, `/webauthn/authenticate/**`, `/login/webauthn`, and
+  `/actuator/health`; the override now matches the base list
+- `docker-compose-keycloak.yml` sets `USER_REGISTRATION_SENDVERIFICATIONEMAIL: "false"` like
+  `compose.yaml`, so form registration in that stack no longer creates an account waiting on mail the
+  bundled relay cannot deliver
+
+### Removed
+- Root `CONFIG.md` (a stale copy of the framework's property reference), `docs/HELP.md` (Spring
+  Initializr boilerplate), `docs/TEST-ANALYSIS.md` (absorbed into `docs/TESTING.md`), and the
+  `TempTest` startup debug logger
+
+### Dependencies
+- **Spring User Framework 5.3.0**, Spring Boot 4.1.0 (2026-08-14)
+- Backfill of the bumps between the entries: framework 4.3.1 (2026-03-22, missing from that entry),
+  4.4.0, 5.0.0, and 5.0.1 (2026-06-15), 5.1.0 (2026-07-10), 5.1.1 (2026-07-24), 5.2.0 (2026-08-12);
+  Gradle wrapper 9.4.1 to 9.7.0 (2026-08-13). Spring Boot stayed on 4.0.4 until the 4.1.0 bump above
+
 ## 2026-03-22
 
 ### Changed

CLAUDE.md

@@ -9,7 +9,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 # Standard run
 ./gradlew bootRun
 
-# Run with specific profile (local, dev, test, docker-keycloak)
+# Run with specific profile (see "Configuration Profiles" below for the full list)
 ./gradlew bootRun --args='--spring.profiles.active=local'
 
 # Build and run with debugging
@@ -60,25 +60,32 @@ This is a Spring Boot demo application showcasing the [Spring User Framework](ht
 
 ### Important Conventions
 
-1. **No Custom User Entity**: This demo uses the framework's User entity directly. Custom user data goes in separate entities (like UserProfile).
+1. **No Custom User Entity**: This demo uses the framework's User entity directly. Custom user data goes in separate entities (like `DemoUserProfile`).
 
 2. **Configuration Profiles**:
    - `local`: Development with local database
-   - `test`: Integration testing with H2
+   - `dev`: Debug-heavy dev server; also what the `compose.yaml` Docker stack runs
+   - `prd`: Production settings (env-driven datasource and URLs, strict cookies)
+   - `test`: Integration testing with H2, applied automatically by `./gradlew test`
+   - `playwright-test`: Enables the test-only API for E2E runs; combine with a base profile
    - `docker-keycloak`: OIDC integration with Keycloak
    - `registration-guard`: Enables domain-restricted registration (form/passwordless only)
    - `mfa`: Enables multi-factor authentication (PASSWORD + WEBAUTHN); combine with another profile, e.g. `local,mfa`
 
-3. **Template Organization**: All Thymeleaf templates are in `src/main/resources/templates/` with subdirectories for user management (`email/`, `password/`, etc.)
+3. **Template Organization**: All Thymeleaf templates are in `src/main/resources/templates/`, with subdirectories `user/` (including `user/mfa/`), `mail/`, `event/`, `admin/`, and `fragments/`
 
-4. **Test Data Builders**: Use the builder classes in `src/test/java/com/devondragon/springdemo/test/data/` for consistent test data creation.
+4. **Test Data Builders**: Use the builder classes in `src/test/java/com/digitalsanctuary/spring/user/test/builders/` for consistent test data creation.
 
 ### Framework Integration Points
 
 The application demonstrates framework usage through:
-- Custom controllers that extend framework functionality (EventController)
-- Service extensions (CustomUserService extends UserService)
+- Custom controllers that build on framework functionality (`event/EventAPIController`, `event/EventPageController`)
+- Service extensions (`service/CustomUserEmailService` extends the framework's `UserEmailService` and is `@Primary`)
 - Configuration of framework components via application.yml
 - Event listeners for user lifecycle events
 
-When modifying user-related functionality, check if the Spring User Framework already provides it before implementing custom solutions.
+When modifying user-related functionality, check if the Spring User Framework already provides it before implementing custom solutions.
+
+## Documentation
+
+Demo documentation lives in `docs/`: `CONFIGURATION.md` (profiles and properties), `DEVELOPMENT.md` (running and building), `TESTING.md` (JUnit and Playwright), `EXTENDING.md` (framework extension points), `AUTHENTICATION.md` (every auth path). The Keycloak stack has its own `keycloak/README.md`. Update these rather than growing `README.md`.

Dockerfile

@@ -1,6 +1,22 @@
-FROM eclipse-temurin:17-jre-jammy
+# Stage 1: build the boot jar inside the image, so no local Gradle build is required.
+# JDK 21 matches the toolchain declared in build.gradle.
+FROM eclipse-temurin:21-jdk-jammy AS build
 
-# Install wget for healthcheck
+WORKDIR /workspace
+
+# Resolve dependencies in their own layer so editing sources does not re-download them.
+COPY gradlew gradlew
+COPY gradle gradle
+COPY build.gradle settings.gradle ./
+RUN ./gradlew --no-daemon dependencies --configuration runtimeClasspath > /dev/null
+
+COPY src src
+RUN ./gradlew --no-daemon bootJar -x test
+
+# Stage 2: runtime image, JRE only.
+FROM eclipse-temurin:21-jre-jammy
+
+# Install wget for the healthcheck (the JRE image has no curl)
 RUN apt-get update && apt-get install -y wget && rm -rf /var/lib/apt/lists/*
 
 # Add a non-root user to run the application
@@ -9,8 +25,8 @@ RUN groupadd -r spring && useradd -r -g spring spring
 # Set working directory
 WORKDIR /opt/app
 
-# Copy the JAR file
-COPY build/libs/*SNAPSHOT.jar app.jar
+# Copy the JAR file built in stage 1
+COPY --from=build /workspace/build/libs/*-SNAPSHOT.jar app.jar
 
 # Set ownership of the files
 RUN chown -R spring:spring /opt/app