diff --git a/.env.release.example b/.env.release.example
index 502ee46f..a7751882 100644
--- a/.env.release.example
+++ b/.env.release.example
@@ -128,7 +128,9 @@ SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUER_URI=
 # To enable, set BOTH:
 #   - SKILLHUB_AUTH_DIRECT_ENABLED=true       (server: enables the /api/v1/auth/direct endpoint)
 #   - SKILLHUB_WEB_AUTH_DIRECT_ENABLED=true   (web:    surfaces the username/password form)
-# Set SKILLHUB_WEB_AUTH_DIRECT_PROVIDER to the provider id (e.g. "local-password").
+# Set SKILLHUB_WEB_AUTH_DIRECT_PROVIDER to a direct provider id returned by
+# /api/v1/auth/methods (e.g. "local"). Do not use the built-in auth method id
+# "local-password" here; that method points at /api/v1/auth/local/login.
 SKILLHUB_AUTH_DIRECT_ENABLED=false
 SKILLHUB_WEB_AUTH_DIRECT_ENABLED=false
 SKILLHUB_WEB_AUTH_DIRECT_PROVIDER=