spring-boot4-skill 1.0.0 → 1.1.0

package/README.md

@@ -1,7 +1,7 @@
 # Spring Boot 4 · Java 25 · Spring Framework 7
 
 > **2026-standard** project scaffolder + Claude Code AI skill for Java / Spring development.
-> By [AyrtonAldayr](https://github.com/AyrtonAldayr)
+> By [AyrtonAldayr](https://github.com/AyrtonAldayr) · **v1.1.0**
 
 This repository provides two tools in one:
 
@@ -70,7 +70,26 @@ After answering a few prompts, you get a complete project with:
 
 Install the skill to get AI assistance aligned with Spring Boot 4 / Framework 7 standards.
 
-### Install from GitHub
+There are **two common ways** to install it, depending on which tool you use:
+
+### Option 1 — npx (Skills CLI, multi-agent)
+
+Uses the open [Skills CLI](https://github.com/vercel-labs/skills) (`npx skills`). Works with Claude Code, Cursor, Codex, and other agents that follow the same skill layout.
+
+```bash
+# Install the skill (prompts for which agent(s) to install to)
+npx skills add AyrtonAldayr/agent-skill-java-spring-framework --skill java-spring-framework
+
+# Install only for Claude Code
+npx skills add AyrtonAldayr/agent-skill-java-spring-framework --skill java-spring-framework -a claude-code
+
+# Install for Cursor
+npx skills add AyrtonAldayr/agent-skill-java-spring-framework --skill java-spring-framework -a cursor
+```
+
+### Option 2 — Claude Code official CLI
+
+If you use the `claude` CLI (Anthropic’s Claude Code), you can install directly from GitHub:
 
 ```bash
 claude skills install github:AyrtonAldayr/agent-skill-java-spring-framework
@@ -93,9 +112,11 @@ Once installed, Claude Code acts as a **Senior Spring Boot 4 architect**:
 | File | Contents |
 |---|---|
 | `skills/java-spring-framework/references/spring-framework-7.md` | All Spring 7 APIs with code examples |
-| `skills/java-spring-framework/references/spring-boot-4.md` | Boot 4 features: native, virtual threads, Security 7, testing |
-| `skills/java-spring-framework/references/spring-modulith.md` | Module structure, events, integration testing |
+| `skills/java-spring-framework/references/spring-boot-4.md` | Boot 4: native, virtual threads, testing (Testcontainers), reactive stack |
+| `skills/java-spring-framework/references/spring-security-7.md` | OAuth2 Resource Server, JWT, method security, CORS |
+| `skills/java-spring-framework/references/spring-modulith.md` | Module structure, events, integration testing, common pitfalls |
 | `skills/java-spring-framework/references/build-templates.md` | Complete Gradle KTS + Maven POM templates |
+| `skills/java-spring-framework/references/troubleshooting-migration.md` | Common errors (javax/jakarta, RestTemplate), Boot 3→4 checklist |
 
 ---
 

package/lib/generator.js

@@ -179,9 +179,11 @@ ${chalk.bold('Next steps:')}
   ${chalk.cyan(cd)}
   ${chalk.cyan(run)}
 
-${chalk.bold('Install the AI coding skill:')}
+${chalk.bold('Install the AI coding skill (optional):')}
 
-  ${chalk.cyan(`claude skills install github:AyrtonAldayr/agent-skill-java-spring-framework`)}
+  ${chalk.cyan('npx skills add AyrtonAldayr/agent-skill-java-spring-framework --skill java-spring-framework')}
+  ${chalk.dim('or')}
+  ${chalk.cyan('claude skills install github:AyrtonAldayr/agent-skill-java-spring-framework')}
 
 ${chalk.dim('Docs: https://github.com/AyrtonAldayr/agent-skill-java-spring-framework')}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spring-boot4-skill",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Interactive CLI scaffold for Java 25 / Spring Boot 4.x projects — with a bundled Claude Code skill for AI-assisted development.",
   "type": "module",
   "bin": {

package/skills/java-spring-framework/SKILL.md

@@ -16,6 +16,32 @@ description: >
 You are a Senior Java & Spring Boot 4 / Spring Framework 7 architect. All code must be
 idiomatic for **2026 standards**: Spring Boot 4.0.x, Spring Framework 7.0.x, Java 25, Jakarta EE 11.
 
+**Triggers:** REST APIs, microservices, JdbcClient/JPA 3.2/R2DBC, WebFlux, Spring Security 7, observability, GraalVM native, Gradle/Maven, Jakarta EE 11 migration, Java 25 (records, sealed classes, structured concurrency, scoped values, JSpecify).
+
+## When NOT to use this skill
+
+- Legacy Spring Boot 2.x or 3.x with no upgrade plan to Boot 4 / Framework 7.
+- Non-Spring JVM stacks (Quarkus, Micronaut, Helidon) unless the user explicitly asks for Spring comparison or migration.
+- Tasks that do not touch Java/Spring backend (e.g. only frontend, only infra/DevOps with no Spring code).
+- General Java questions with no Spring or framework context.
+
+## Quick decision (which reference to load first)
+
+```mermaid
+flowchart TD
+    A[User request] --> B{REST blocking or reactive?}
+    B -->|Blocking MVC + JDBC/JPA| C[spring-boot-4.md + spring-framework-7.md]
+    B -->|Reactive WebFlux + R2DBC| D[spring-boot-4.md Reactive section + spring-framework-7.md]
+    A --> E{Modular monolith?}
+    E -->|Yes| F[spring-modulith.md]
+    A --> G{Security / OAuth2 / JWT?}
+    G -->|Yes| H[spring-security-7.md]
+    A --> I{Scaffold / build / versions?}
+    I -->|Yes| J[build-templates.md]
+    A --> K{Migration or errors?}
+    K -->|Yes| L[troubleshooting-migration.md]
+```
+
 ## Mandatory Workflow
 
 1. **Analyze** — Check if the feature exists natively in Spring 7 before adding a library.
@@ -52,5 +78,7 @@ Load these as needed — do not load all at once:
 |---|---|---|
 | Spring Framework 7 APIs | `references/spring-framework-7.md` | Framework-level features: versioning, resilience, JSpecify, SpEL, streaming |
 | Spring Boot 4 features | `references/spring-boot-4.md` | Boot auto-config, Actuator, native images, testing, virtual threads |
+| Spring Security 7 | `references/spring-security-7.md` | OAuth2 Resource Server, JWT, method security, CORS, authentication/authorization |
 | Spring Modulith | `references/spring-modulith.md` | Domain-driven module design, event-driven architecture |
 | Build templates | `references/build-templates.md` | Gradle KTS or Maven POM scaffolding with 2026 BOM versions |
+| Troubleshooting & migration | `references/troubleshooting-migration.md` | Migration from Boot 3, compile/runtime errors (javax/jakarta, RestTemplate, native, null-safety) |

package/skills/java-spring-framework/references/spring-boot-4.md

@@ -15,6 +15,7 @@
 8. [Scoped Values (Java 25)](#8-scoped-values-java-25)
 9. [Docker Compose Support](#9-docker-compose-support)
 10. [Spring Security 7 Basics](#10-spring-security-7-basics)
+11. [Reactive Stack (R2DBC + WebFlux)](#11-reactive-stack-r2dbc--webflux)
 
 ---
 
@@ -126,19 +127,67 @@ class UserRepositoryTest {
 }
 ```
 
+### Testcontainers (integration tests)
+
+For full integration tests against a real database, use **Testcontainers**. Prefer this when testing repository logic, transactions, or schema; use `@MockBean` for unit/slice tests where the focus is the controller or service in isolation.
+
+```kotlin
+// build.gradle.kts
+testImplementation("org.springframework.boot:spring-boot-testcontainers")
+testImplementation("org.testcontainers:postgresql")
+testImplementation("org.testcontainers:junit-jupiter")
+```
+
+```java
+@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
+@Testcontainers
+class OrderRepositoryIntegrationTest {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:17")
+        .withDatabaseName("testdb").withUsername("test").withPassword("test");
+
+    @DynamicPropertySource
+    static void props(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", postgres::getJdbcUrl);
+        registry.add("spring.datasource.username", postgres::getUsername);
+        registry.add("spring.datasource.password", postgres::getPassword);
+    }
+
+    @Autowired OrderRepository repository;
+
+    @Test
+    void shouldFindOrdersByUserId() {
+        // real DB; no mocks
+        List<Order> orders = repository.findByUserId("user-1");
+        assertThat(orders).isNotEmpty();
+    }
+}
+```
+
+**When to use @MockBean vs Testcontainers:** Use `@MockBean` in `@WebMvcTest` or `@DataJpaTest` when you want fast, isolated tests. Use Testcontainers when you need real DB/network behavior (transactions, constraints, SQL).
+
 ---
 
 ## 4. Actuator & Observability
 
 Spring Boot 4 ships first-class **Micrometer Tracing + OpenTelemetry** support.
 
+### Endpoint exposure (secure by default)
+
+Expose only what you need. In production, prefer `health` and `info` for public checks; restrict `metrics`, `prometheus`, and `traces` to an internal network or secure endpoint (e.g. via Spring Security).
+
 ```yaml
 # application.yaml
 management:
   endpoints:
     web:
       exposure:
-        include: health,info,metrics,prometheus,traces
+        include: health,info,metrics,prometheus,traces   # restrict in prod
+      base-path: /actuator
+  endpoint:
+    health:
+      show-details: when-authorized   # or "never" in prod
   tracing:
     sampling:
       probability: 1.0
@@ -150,13 +199,17 @@ management:
       endpoint: http://otel-collector:4318/v1/traces
 ```
 
+Protect actuator in Security 7: allow `health`/`info` for load balancers, require authentication for `metrics`/`prometheus`/`traces`. See `references/spring-security-7.md`.
+
+### Dependencies (Micrometer + OTEL)
+
 ```kotlin
 // build.gradle.kts
 implementation("io.micrometer:micrometer-tracing-bridge-otel")
 implementation("io.opentelemetry:opentelemetry-exporter-otlp")
 ```
 
-Custom span:
+### Custom span (Tracer)
 
 ```java
 @Service
@@ -318,7 +371,7 @@ No manual connection properties needed — Boot auto-configures `DataSource` and
 
 ## 10. Spring Security 7 Basics
 
-Lambda DSL is the only supported style in Spring Security 7.
+Spring Security 7 uses **lambda DSL** only for `SecurityFilterChain` and related config. Minimal example:
 
 ```java
 @Configuration
@@ -332,10 +385,8 @@ public class SecurityConfig {
                 .requestMatchers("/api/public/**").permitAll()
                 .requestMatchers("/api/admin/**").hasRole("ADMIN")
                 .anyRequest().authenticated())
-            .oauth2ResourceServer(oauth2 -> oauth2
-                .jwt(jwt -> jwt.decoder(jwtDecoder())))
-            .sessionManagement(session -> session
-                .sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .oauth2ResourceServer(oauth2 -> oauth2.jwt(jwt -> jwt.decoder(jwtDecoder())))
+            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
             .build();
     }
 
@@ -345,3 +396,28 @@ public class SecurityConfig {
     }
 }
 ```
+
+For **OAuth2 Resource Server (JWT)**, **method security (`@PreAuthorize`)**, and **CORS**, load `references/spring-security-7.md`.
+
+---
+
+## 11. Reactive Stack (R2DBC + WebFlux)
+
+Choose the reactive stack when you need non-blocking I/O end-to-end (high concurrency, streaming, or integration with reactive drivers). For typical CRUD APIs with blocking JDBC/JPA, prefer **Spring MVC + virtual threads** (section 6).
+
+### Dependencies
+
+```kotlin
+// build.gradle.kts — replace or add to starters
+implementation("org.springframework.boot:spring-boot-starter-webflux")
+implementation("org.springframework.boot:spring-boot-starter-data-r2dbc")
+runtimeOnly("org.postgresql:r2dbc-postgresql")
+```
+
+### Main application
+
+Use `Netty` as the default server (Boot chooses it when `spring-boot-starter-webflux` is on the classpath and `spring-boot-starter-web` is not).
+
+### R2DBC repositories and WebFlux controllers
+
+Define reactive repositories (`ReactiveCrudRepository`) and inject them into `@RestController` or handler functions. Use `ServerWebExchange`, `Mono`, and `Flux` for reactive types. For **RestClient** in a reactive app, use the reactive variant and streaming; see `references/spring-framework-7.md` (Streaming Support) for alignment with Spring 7 APIs.

package/skills/java-spring-framework/references/spring-framework-7.md

@@ -2,6 +2,8 @@
 
 **Version**: 7.0.5 (Stable) | **Java baseline**: 17 (25 recommended) | **Jakarta EE**: 11
 
+For **reactive applications (WebFlux + R2DBC)**, combine this reference with the **Reactive stack** section in `references/spring-boot-4.md`.
+
 ---
 
 ## Table of Contents

package/skills/java-spring-framework/references/spring-modulith.md

@@ -13,6 +13,7 @@
 6. [Transactional Event Listeners](#6-transactional-event-listeners)
 7. [Module Integration Testing](#7-module-integration-testing)
 8. [Generating Documentation](#8-generating-documentation)
+9. [Common Pitfalls](#9-common-pitfalls)
 
 ---
 
@@ -218,3 +219,15 @@ void generateModuleDocumentation() throws Exception {
 ```
 
 Output lands in `target/spring-modulith-docs/` (Maven) or `build/spring-modulith-docs/` (Gradle).
+
+---
+
+## 9. Common Pitfalls
+
+| Pitfall | Remedy |
+|--------|--------|
+| **Circular module dependencies** | `ApplicationModules.of(...).verify()` fails. Break the cycle: introduce a shared module or move the coupling to events so no module depends on the other. |
+| **Exposing internal types in the module API** | Public classes in the module root (e.g. `OrderService`) must not return or accept types from `internal/`. Use DTOs or domain types in the public package only. |
+| **Forgetting the verification test in CI** | Add the module verification test (section 3) to your CI pipeline so boundary violations are caught on every commit. |
+| **Direct service calls across modules** | One module must not inject another module's service and call it directly. Use `ApplicationEventPublisher` and `@ApplicationModuleListener` (or transactional events) for cross-module communication. |
+| **Putting shared DTOs in one module's internal** | Types used in events or APIs consumed by several modules belong in a `shared/` (or similar) package, not in one module's `internal/`. |

package/skills/java-spring-framework/references/spring-security-7.md

@@ -0,0 +1,203 @@
+# Spring Security 7 — Reference (Boot 4)
+
+**Spring Boot**: 4.0.x | **Spring Security**: 7.0.x | **Jakarta EE**: 11
+
+---
+
+## Table of Contents
+
+1. [Dependencies](#1-dependencies)
+2. [OAuth2 Resource Server (JWT)](#2-oauth2-resource-server-jwt)
+3. [SecurityFilterChain (Lambda DSL)](#3-securityfilterchain-lambda-dsl)
+4. [Method Security (@PreAuthorize)](#4-method-security-preauthorize)
+5. [CORS](#5-cors)
+6. [application.yaml](#6-applicationyaml)
+
+---
+
+## 1. Dependencies
+
+Spring Boot 4 BOM brings Spring Security 7. Add only what you need:
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation("org.springframework.boot:spring-boot-starter-security")
+    implementation("org.springframework.boot:spring-boot-starter-oauth2-resource-server")  // JWT
+    implementation("org.springframework.boot:spring-boot-starter-oauth2-client")             // optional: OAuth2 login
+}
+```
+
+---
+
+## 2. OAuth2 Resource Server (JWT)
+
+Validate JWTs from an authorization server (e.g. OIDC issuer). Lambda DSL is the only supported style in Security 7.
+
+```java
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.oauth2.jwt.JwtDecoder;
+import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
+import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.security.config.http.SessionCreationPolicy;
+
+@Configuration
+@EnableWebSecurity
+public class SecurityConfig {
+
+    @Bean
+    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        return http
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/api/public/**", "/actuator/health").permitAll()
+                .requestMatchers("/api/admin/**").hasRole("ADMIN")
+                .anyRequest().authenticated())
+            .oauth2ResourceServer(oauth2 -> oauth2
+                .jwt(jwt -> jwt.decoder(jwtDecoder())))
+            .sessionManagement(session -> session
+                .sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .csrf(csrf -> csrf.disable())   // typical for stateless API
+            .build();
+    }
+
+    @Bean
+    JwtDecoder jwtDecoder() {
+        return NimbusJwtDecoder.withJwkSetUri("https://auth.example.com/.well-known/jwks.json").build();
+    }
+}
+```
+
+With **issuer-uri** (Boot auto-configures `JwtDecoder`):
+
+```yaml
+# application.yaml
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: https://auth.example.com
+```
+
+Then omit the custom `JwtDecoder` bean; Boot provides it.
+
+---
+
+## 3. SecurityFilterChain (Lambda DSL)
+
+All security configuration uses the lambda style. Example: form login + API protected by JWT.
+
+```java
+import org.springframework.security.config.Customizer;
+
+@Bean
+SecurityFilterChain webFilterChain(HttpSecurity http) throws Exception {
+    return http
+        .securityMatcher("/api/**")
+        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
+        .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
+        .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+        .build();
+}
+```
+
+---
+
+## 4. Method Security (@PreAuthorize)
+
+Enable method security and use SpEL in annotations (Jakarta namespace).
+
+```java
+@Configuration
+@EnableMethodSecurity
+public class MethodSecurityConfig {}
+```
+
+```java
+import org.springframework.security.access.prepost.PreAuthorize;
+
+@Service
+public class OrderService {
+
+    @PreAuthorize("hasRole('ADMIN') or #userId == authentication.name")
+    public Order getOrder(String userId, String orderId) {
+        return orderRepository.findById(orderId).orElseThrow();
+    }
+
+    @PreAuthorize("hasAuthority('SCOPE_orders:write')")
+    public Order create(OrderRequest request) {
+        return orderRepository.save(map(request));
+    }
+}
+```
+
+Use `@PreAuthorize` / `@PostAuthorize` for read; `@PreFilter` / `@PostFilter` for filtering collections. All use Jakarta annotations in Spring Security 7.
+
+---
+
+## 5. CORS
+
+Configure CORS in the security pipeline or globally. Example: allow a frontend origin.
+
+```java
+import org.springframework.security.config.Customizer;
+import org.springframework.web.cors.CorsConfiguration;
+import org.springframework.web.cors.CorsConfigurationSource;
+import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
+
+@Bean
+SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+    return http
+        .cors(cors -> cors.configurationSource(corsConfigurationSource()))
+        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
+        .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
+        .build();
+}
+
+@Bean
+CorsConfigurationSource corsConfigurationSource() {
+    CorsConfiguration config = new CorsConfiguration();
+    config.setAllowedOrigins(List.of("https://app.example.com"));
+    config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
+    config.setAllowedHeaders(List.of("*"));
+    config.setAllowCredentials(true);
+
+    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+    source.registerCorsConfiguration("/**", config);
+    return source;
+}
+```
+
+Or use `WebMvcConfigurer` for non-security CORS only; for APIs with credentials, the above is typical.
+
+---
+
+## 6. application.yaml
+
+Minimal Security 7 + OAuth2 RS settings:
+
+```yaml
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: https://auth.example.com
+          jwk-set-uri: https://auth.example.com/.well-known/jwks.json  # if no issuer-uri
+
+# Optional: restrict actuator by profile
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,metrics
+```
+
+For **development only**, you can disable security (e.g. with a `SecurityFilterChain` that permits all when a profile is active). Never disable in production.
+
+---
+
+**Summary:** Use `SecurityFilterChain` with lambda DSL, OAuth2 Resource Server with JWT for APIs, `@EnableMethodSecurity` and `@PreAuthorize` for method-level rules, and configure CORS in the security pipeline when the API is consumed by a browser client.

package/skills/java-spring-framework/references/troubleshooting-migration.md

@@ -0,0 +1,119 @@
+# Troubleshooting & Migration — Spring Boot 4 / Framework 7
+
+Quick fixes for common errors and a short checklist for migrating from Boot 3 to Boot 4.
+
+---
+
+## Table of Contents
+
+1. [Common errors](#1-common-errors)
+2. [Boot 3 → 4 migration checklist](#2-boot-3--4-migration-checklist)
+
+---
+
+## 1. Common errors
+
+### javax vs jakarta
+
+**Symptom:** Compilation errors like `package javax.servlet does not exist`, `javax.persistence` not found, or similar for `javax.*`.
+
+**Cause:** Spring Boot 4 and Spring Framework 7 use **Jakarta EE 11**. All `javax.*` namespaces were replaced by `jakarta.*`.
+
+**Fix:**
+
+- Replace imports: `javax.servlet.*` → `jakarta.servlet.*`, `javax.persistence.*` → `jakarta.persistence.*`, `javax.validation.*` → `jakarta.validation.*`, etc.
+- Ensure dependencies use Jakarta. Spring Boot 4 BOM already brings Jakarta-based starters. Third-party libs must be Jakarta-compatible (e.g. Hibernate 7.x, Bean Validation 3.x, Servlet API 6.x).
+- Search the project for `javax.` and replace with `jakarta.` where applicable.
+
+---
+
+### RestTemplate not found or deprecated
+
+**Symptom:** `RestTemplate` cannot be resolved, or IDE/compiler warns it is deprecated.
+
+**Cause:** In Spring Framework 6+, `RestTemplate` is in maintenance mode. Spring 7 promotes `RestClient` for synchronous HTTP.
+
+**Fix:**
+
+- Add dependency (usually already present with `spring-boot-starter-web`): `RestClient` is in `spring-web`.
+- Replace usage:
+
+```java
+// Before
+RestTemplate rest = new RestTemplate();
+MyDto dto = rest.getForObject(url, MyDto.class);
+
+// After (Spring 7)
+RestClient rest = RestClient.create();
+MyDto dto = rest.get().uri(url).retrieve().body(MyDto.class);
+```
+
+For declarative clients, use `HttpServiceProxyFactory` + interface. See `references/spring-framework-7.md`.
+
+---
+
+### Null-safety: JSR-305 vs JSpecify
+
+**Symptom:** Warnings or errors about `@Nullable` / `@NonNull` (e.g. wrong package or conflicting annotations).
+
+**Cause:** Spring 7 aligns with **JSpecify** (`org.jspecify.annotations`). Legacy JSR-305 (`javax.annotation` or `org.checkerframework`) is not the standard for Spring 7.
+
+**Fix:**
+
+- Remove JSR-305 / Checker Framework null annotations from dependencies if possible.
+- Add JSpecify and use it consistently:
+
+```kotlin
+implementation("org.jspecify:jspecify:1.0.0")
+```
+
+```java
+import org.jspecify.annotations.Nullable;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullMarked;
+```
+
+- Annotate packages or types with `@NullMarked` where you want strict null checking. Replace `javax.annotation.Nullable` with `org.jspecify.annotations.Nullable`, etc.
+
+---
+
+### Native image: reflection or classpath errors
+
+**Symptom:** GraalVM native build fails with "Class not found", "Reflection without registration", or similar.
+
+**Cause:** Native images need explicit metadata for reflection, resources, and dynamic proxies. Spring Boot AOT helps but not all code paths are covered.
+
+**Fix:**
+
+- Prefer **functional bean registration** instead of classpath scanning where possible. Use `ApplicationContextInitializer` or `BeanDefinitionRegistryPostProcessor` to register beans programmatically.
+- For DTOs or types used in JSON/serialization, register reflection:
+
+```java
+@RegisterReflectionForBinding({MyDto.class, OtherDto.class})
+@Configuration(proxyBeanMethods = false)
+public class NativeHintsConfig {}
+```
+
+- Add GraalVM reachability metadata for third-party libraries if needed (e.g. `native-image.properties` or library-specific hints). Check [GraalVM Native Image documentation](https://www.graalvm.org/latest/reference-manual/native-image/) and Spring Boot’s native support.
+- Ensure you are not loading classes only by name (e.g. `Class.forName`) without registering them for reflection.
+
+---
+
+## 2. Boot 3 → 4 migration checklist
+
+Use this as a short guide. For authoritative steps, refer to the official [Spring Boot 4 release notes](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes) and upgrade guides.
+
+| Step | Action |
+|------|--------|
+| **Java** | Use Java 17 minimum; **Java 21 or 25** recommended. |
+| **BOM** | Update parent or BOM to Spring Boot **4.0.x** (e.g. `4.0.3`). |
+| **javax → jakarta** | Replace all `javax.*` imports and dependencies with `jakarta.*` (servlet, persistence, validation, etc.). |
+| **Dependencies** | Align with Boot 4: Jackson **3.x**, JPA/Hibernate **3.2 / 7.x**, Bean Validation **3.1**, Spring Framework **7.0.x**. Remove or upgrade any lib that still depends on `javax.*` or old versions. |
+| **RestTemplate** | Migrate to **RestClient** (or WebClient for reactive). See `references/spring-framework-7.md`. |
+| **Null annotations** | Migrate to **JSpecify** (`org.jspecify`) if you use null-safety annotations. |
+| **Security** | Spring Security 7 uses **lambda DSL** only. Update `SecurityFilterChain` and related config to lambda style. See `references/spring-security-7.md`. |
+| **Optional: Virtual threads** | Enable with `spring.threads.virtual.enabled: true` in `application.yaml` for eligible workloads. |
+| **Optional: Java 25 features** | For Structured Concurrency or Scoped Values, enable `--enable-preview` in compile and run; use Boot 4 + Java 25. See `references/spring-boot-4.md`. |
+| **Tests** | Run full test suite; fix any failures due to API changes (e.g. `RestTestClient` instead of `TestRestTemplate` where applicable). Use **Testcontainers** for integration tests if needed. See `references/spring-boot-4.md` Testing section. |
+
+After migration, verify actuator endpoints, security rules, and database access. For deeper issues, load the appropriate reference file (e.g. `spring-security-7.md`, `spring-framework-7.md`, `spring-boot-4.md`) as indicated in the skill’s Reference Files table.