chore: clean up the repository root

.gitignore

@@ -134,10 +134,16 @@ application-local.yml
 
 /project_concatenated.txt
 .env
-.vscode/settings.json
 /repomix-output.txt
 src/main/resources/application-docker-keycloak.yml
-.vscode/
+
+# VS Code: personal settings stay local, shared tasks.json is tracked
+.vscode/*
+!.vscode/tasks.json
+
+# IntelliJ IDEA
+.idea/
+*.iml
 
 # Playwright
 playwright/node_modules/

CLAUDE.md

@@ -13,7 +13,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ./gradlew bootRun --args='--spring.profiles.active=local'
 
 # Build and run with debugging
-./run.sh
+./scripts/run.sh
 ```
 
 ### Testing

README.md

@@ -607,7 +607,7 @@ docker compose -f docker-compose-keycloak.yml up --build
 ./gradlew bootRun --debug-jvm
 
 # Build and run with custom script
-./run.sh
+./scripts/run.sh
 
 # Hot reload with DevTools (automatic)
 # Just save files and changes will be picked up

scripts/run.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Build the boot jar and run it with the JDWP debug agent on port 6332.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+./gradlew bootJar
+java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:6332 -jar build/libs/ds-spring-user-framework-demo-1.0.1-SNAPSHOT.jar --spring.profiles.active=local

src/test/java/com/digitalsanctuary/spring/user/api/ApiSecurityTest.java

@@ -44,7 +44,7 @@
 @ActiveProfiles("test")
 @Transactional
 @DisplayName("API Security Tests")
-@Disabled("CSRF and authentication setup issues with REST API. See TEST-ANALYSIS.md")
+@Disabled("CSRF and authentication setup issues with REST API. See docs/TEST-ANALYSIS.md")
 class ApiSecurityTest {
 
     private static final String API_BASE_PATH = "/user";

src/test/java/com/digitalsanctuary/spring/user/api/AuthenticatedUserApiTestSimplified.java

@@ -47,7 +47,7 @@
 @ActiveProfiles("test")
 @Transactional
 @DisplayName("Authenticated User API Tests - Simplified")
-@Disabled("Authentication setup issues with DSUserDetails. See TEST-ANALYSIS.md")
+@Disabled("Authentication setup issues with DSUserDetails. See docs/TEST-ANALYSIS.md")
 class AuthenticatedUserApiTestSimplified {
 
     private static final String API_BASE_PATH = "/user";

src/test/java/com/digitalsanctuary/spring/user/api/PasswordResetApiTest.java

@@ -58,7 +58,7 @@
 @ActiveProfiles("test")
 @Transactional
 @DisplayName("Password Reset API Tests")
-@Disabled("Password reset token workflow and email handling issues. See TEST-ANALYSIS.md")
+@Disabled("Password reset token workflow and email handling issues. See docs/TEST-ANALYSIS.md")
 class PasswordResetApiTest {
 
     private static final String RESET_PASSWORD_URL = "/user/resetPassword";

src/test/java/com/digitalsanctuary/spring/user/api/PasswordResetApiTestSimplified.java

@@ -42,7 +42,7 @@
 @ActiveProfiles("test")
 @Transactional
 @DisplayName("Password Reset API Tests - Simplified")
-@Disabled("Validation expectations don't match API behavior. See TEST-ANALYSIS.md")
+@Disabled("Validation expectations don't match API behavior. See docs/TEST-ANALYSIS.md")
 class PasswordResetApiTestSimplified {
 
     private static final String RESET_PASSWORD_URL = "/user/resetPassword";

src/test/java/com/digitalsanctuary/spring/user/api/PasswordResetCompletionTest.java

@@ -40,7 +40,7 @@
 @ActiveProfiles("test")
 @Transactional
 @DisplayName("Password Reset Completion Tests")
-@Disabled("Password reset completion workflow issues. See TEST-ANALYSIS.md")
+@Disabled("Password reset completion workflow issues. See docs/TEST-ANALYSIS.md")
 class PasswordResetCompletionTest {
 
     private static final String SAVE_PASSWORD_URL = "/user/savePassword";

src/test/java/com/digitalsanctuary/spring/user/api/UserApiTest.java

@@ -78,7 +78,7 @@ public class UserApiTest {
     @ParameterizedTest
     @ArgumentsSource(ApiTestRegistrationArgumentsProvider.class)
     @Order(1)
-    @Disabled("Transaction isolation issue - user created in test setup not visible to REST endpoint. See TEST-ANALYSIS.md")
+    @Disabled("Transaction isolation issue - user created in test setup not visible to REST endpoint. See docs/TEST-ANALYSIS.md")
     // correctly run separately
     public void registerUserAccount(ApiTestArgumentsHolder argumentsHolder) throws Exception {
         UserDto userDto = argumentsHolder.getUserDto();
@@ -138,7 +138,7 @@ public void resetPassword() throws Exception {
     @ParameterizedTest
     @ArgumentsSource(ApiTestUpdateUserArgumentsProvider.class)
     @Order(3)
-    @Disabled("Spring Security returns empty 401 response instead of JSON error. See TEST-ANALYSIS.md")
+    @Disabled("Spring Security returns empty 401 response instead of JSON error. See docs/TEST-ANALYSIS.md")
     public void updateUser(ApiTestArgumentsHolder argumentsHolder) throws Exception {
         // Ensure user exists
         if (userService.findUserByEmail(argumentsHolder.getUserDto().getEmail()) == null) {
@@ -169,7 +169,7 @@ public void updateUser(ApiTestArgumentsHolder argumentsHolder) throws Exception
     @ParameterizedTest
     @ArgumentsSource(ApiTestUpdatePasswordArgumentsProvider.class)
     @Order(4)
-    @Disabled("Authentication setup issues with DSUserDetails. See TEST-ANALYSIS.md")
+    @Disabled("Authentication setup issues with DSUserDetails. See docs/TEST-ANALYSIS.md")
     public void updatePassword(ApiTestArgumentsHolder argumentsHolder) throws Exception {
         // Ensure user exists
         if (userService.findUserByEmail(baseTestUser.getEmail()) == null) {
@@ -194,7 +194,7 @@ public void updatePassword(ApiTestArgumentsHolder argumentsHolder) throws Except
     @ParameterizedTest
     @ArgumentsSource(ApiTestDeleteAccountArgumentsProvider.class)
     @Order(5)
-    @Disabled("Authentication setup issues with DSUserDetails. See TEST-ANALYSIS.md")
+    @Disabled("Authentication setup issues with DSUserDetails. See docs/TEST-ANALYSIS.md")
     public void deleteAccount(ApiTestArgumentsHolder argumentsHolder) throws Exception {
         // Ensure user exists
         if (userService.findUserByEmail(baseTestUser.getEmail()) == null) {

src/test/java/com/digitalsanctuary/spring/user/api/UserRegistrationComprehensiveTest.java

@@ -48,7 +48,7 @@
 @ActiveProfiles("test")
 @Transactional
 @DisplayName("Comprehensive User Registration API Tests")
-@Disabled("Validation error response expectations don't match API behavior. See TEST-ANALYSIS.md")
+@Disabled("Validation error response expectations don't match API behavior. See docs/TEST-ANALYSIS.md")
 class UserRegistrationComprehensiveTest {
 
     private static final String REGISTRATION_URL = "/user/registration";

src/test/java/com/digitalsanctuary/spring/user/api/UserRegistrationCoreTest.java

@@ -39,7 +39,7 @@
 @ActiveProfiles("test")
 @Transactional
 @DisplayName("User Registration Core Tests")
-@Disabled("Email normalization expectations don't match API behavior. See TEST-ANALYSIS.md")
+@Disabled("Email normalization expectations don't match API behavior. See docs/TEST-ANALYSIS.md")
 class UserRegistrationCoreTest {
 
     private static final String REGISTRATION_URL = "/user/registration";

src/test/java/com/digitalsanctuary/spring/user/api/UserRegistrationEdgeCaseTest.java

@@ -43,7 +43,7 @@
 @ActiveProfiles("test")
 @Transactional
 @DisplayName("User Registration Edge Case Tests")
-@Disabled("Concurrent registration and null handling expectations don't match API behavior. See TEST-ANALYSIS.md")
+@Disabled("Concurrent registration and null handling expectations don't match API behavior. See docs/TEST-ANALYSIS.md")
 class UserRegistrationEdgeCaseTest {
 
     private static final String REGISTRATION_URL = "/user/registration";

src/test/java/com/digitalsanctuary/spring/user/concurrent/AdminUserManagementTest.java

@@ -42,7 +42,7 @@
 @ActiveProfiles("test")
 @DisplayName("Admin User Management Tests")
 @Transactional(propagation = Propagation.NOT_SUPPORTED)
-@Disabled("Role hierarchy and admin operations configuration issues. See TEST-ANALYSIS.md")
+@Disabled("Role hierarchy and admin operations configuration issues. See docs/TEST-ANALYSIS.md")
 class AdminUserManagementTest {
 
     @Autowired

src/test/java/com/digitalsanctuary/spring/user/integration/AuthenticationIntegrationTest.java

@@ -46,7 +46,7 @@
 @IntegrationTest
 @AutoConfigureMockMvc
 @DisplayName("Authentication Integration Tests")
-@Disabled("Form-based login expectations don't match REST API architecture. See TEST-ANALYSIS.md")
+@Disabled("Form-based login expectations don't match REST API architecture. See docs/TEST-ANALYSIS.md")
 class AuthenticationIntegrationTest {
 
     @Autowired

src/test/java/com/digitalsanctuary/spring/user/integration/SecurityConfigurationTest.java

@@ -154,7 +154,7 @@ void accessProtectedEndpoint_unauthenticated_redirectsToLogin() throws Exception
         @Test
         @WithMockUser(username = "security@test.com", roles = { "USER" })
         @DisplayName("Should allow authenticated user to access protected endpoints")
-        @Disabled("Protected endpoint /protected.html returns 404 - endpoint may not exist. See TEST-ANALYSIS.md")
+        @Disabled("Protected endpoint /protected.html returns 404 - endpoint may not exist. See docs/TEST-ANALYSIS.md")
         void accessProtectedEndpoint_authenticated_allowsAccess() throws Exception {
                 // Test that authenticated user is properly authenticated
                 mockMvc.perform(get("/protected.html")).andExpect(status().isOk()).andExpect(authenticated());

src/test/java/com/digitalsanctuary/spring/user/oauth2/GoogleOAuth2IntegrationTest.java

@@ -57,7 +57,7 @@
 @ExtendWith(OAuth2MockConfiguration.WireMockExtension.class)
 @Transactional
 @DisplayName("Google OAuth2 Integration Tests")
-@Disabled("Requires OAuth2 mock server infrastructure. See TEST-ANALYSIS.md")
+@Disabled("Requires OAuth2 mock server infrastructure. See docs/TEST-ANALYSIS.md")
 class GoogleOAuth2IntegrationTest {
 
     @Autowired

src/test/java/com/digitalsanctuary/spring/user/security/AuditLoggingIntegrationTest.java

@@ -52,7 +52,7 @@
 @ActiveProfiles("test")
 @DisplayName("Audit Logging Integration Tests")
 @Import(AuditLoggingIntegrationTest.TestConfiguration.class)
-@Disabled("Audit logger initialization and async timing issues. See TEST-ANALYSIS.md")
+@Disabled("Audit logger initialization and async timing issues. See docs/TEST-ANALYSIS.md")
 class AuditLoggingIntegrationTest {
 
     @org.springframework.boot.test.context.TestConfiguration

src/test/java/com/digitalsanctuary/spring/user/security/EmailVerificationEdgeCaseTest.java

@@ -67,7 +67,7 @@
 @ActiveProfiles("test")
 @Import(EmailVerificationEdgeCaseTest.TestClockConfiguration.class)
 @DisplayName("Email Verification Edge Cases")
-@Disabled("Email verification timing issues and mock email service configuration. See TEST-ANALYSIS.md")
+@Disabled("Email verification timing issues and mock email service configuration. See docs/TEST-ANALYSIS.md")
 class EmailVerificationEdgeCaseTest {
 
     @Autowired