Document build-time db-kind, Gradle JDK, and env-var gotchas in the migration skill

[gAmUssA]

What & why

Running the migrate-spring-to-quarkus skill on a real Spring Boot → Quarkus migration surfaced three config/build behaviours the reference docs don't currently call out. Each was a silent or confusing failure, so this adds short notes right where a migrator would look. Docs-only — 2 files, 9 insertions, no code change.

references/config-map.md

• Datasource — db-kind is a build-time property. The map currently says driver-class-name → db-kind (auto-detected), and the Profiles table maps spring.profiles.active straight to quarkus.profile — which implies a Spring-style runtime database switch carries over. It doesn't: Quarkus fixes the JDBC driver/dialect at augmentation. With both quarkus-jdbc-h2 and quarkus-jdbc-postgresql on the classpath, a runtime-only quarkus.profile=prod swaps the JDBC URL but keeps the build-time driver → boot fails with Driver does not support the provided URL. Added a warning styled after the existing "Naming strategy warning," with the fix (build with the target profile, or make prod db-kind the default and override to H2 under %dev/%test).
• Server — PaaS $PORT. Short note to bind quarkus.http.port=${PORT:8080} on platforms that inject $PORT (Heroku, Railway, Cloud Run, Fly).
• Profiles — env-var form. Added the SPRING_PROFILES_ACTIVE → QUARKUS_PROFILE row (deployments override the profile via env) plus a note on SmallRye relaxed binding (FOO_BAR_BAZ → foo.bar-baz).

modules/build-gradle.md

• New "watch out" bullet: quarkusBuild runs augmentation inside the Gradle JVM and loads the compiled classes, so compileJava can pass while quarkusBuild fails with UnsupportedClassVersionError when Gradle runs on an older JDK than the code targets. Run Gradle on a JDK ≥ the target version (and use the same JDK in CI / the Docker build stage).

How to verify

These are documentation notes; each maps to standard, checkable Quarkus behaviour:

• db-kind build-time — see the Quarkus datasource guide: the db-kind/driver is resolved at build time. Reproduces as Driver does not support the provided URL when a profile-only DB switch is attempted with two JDBC drivers on the classpath.
• Gradle JDK — augmentation runs in the Gradle JVM; a JDK older than the target produces UnsupportedClassVersionError at quarkusBuild even though compileJava succeeds.
• Env / $PORT — standard SmallRye Config relaxed binding and property expressions.

No existing issue tracks these; opening directly as a small doc PR per the repo's norm.

AI disclosure

Drafted with Claude Code and reviewed, edited, and verified by me against a real Spring Boot → Quarkus migration where each of these issues occurred. The scoping and wording are mine, and I'll own the review iteration.