Add JavaDoc deprecation notice for selector option

Co-authored-by: aepfli <9987394+aepfli@users.noreply.github.com>

Author: Copilot

providers/flagd/src/main/java/dev/openfeature/contrib/providers/flagd/FlagdOptions.java

@@ -124,6 +124,15 @@ public class FlagdOptions {
             fallBackToEnvOrDefault(Config.STREAM_RETRY_GRACE_PERIOD, Config.DEFAULT_STREAM_RETRY_GRACE_PERIOD);
     /**
      * Selector to be used with flag sync gRPC contract.
+     * <p>
+     * <b>Note:</b> This currently uses the gRPC request body approach. The preferred approach is to use
+     * the {@code flagd-selector} header via a {@link ClientInterceptor}.
+     * See the <a href="https://github.com/open-feature/java-sdk-contrib/tree/main/providers/flagd#selector-filtering-in-process-mode-only">selector migration guidance</a>
+     * for details on the header-based approach.
+     * <p>
+     * Only applicable for in-process resolver mode.
+     * 
+     * @see <a href="https://github.com/open-feature/flagd/issues/1814">flagd selector normalization issue</a>
      **/
     @Builder.Default
     private String selector = fallBackToEnvOrDefault(Config.SOURCE_SELECTOR_ENV_VAR_NAME, null);