diff --git a/README.md b/README.md
index a105193..8bbe838 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,8 @@ await confidence.getString("[FLAG]", "Default"))
 The schema of the property plays a crucial role in resolving the property, if the schema type matches the asked type, the value will be returned otherwise
 we expect default value to be returned.
 
+> **Deprecated:** list/array flag schemas and flag values are deprecated. Existing list flags continue to resolve (e.g. via `resolveKey<List<dynamic>>`), but new flags should avoid list properties. This applies only to flag values; lists in context and event data remain supported.
+
 ### Send custom Events
 we can send custom events to the confidence sdk like following:
 
diff --git a/lib/confidence_flutter_sdk.dart b/lib/confidence_flutter_sdk.dart
index 44ca5e9..4cfe141 100644
--- a/lib/confidence_flutter_sdk.dart
+++ b/lib/confidence_flutter_sdk.dart
@@ -36,6 +36,11 @@ class ConfidenceFlutterSdk {
     return resolveKey(key) ?? defaultValue;
   }
 
+  /// Resolves the flag value at the dot-separated [key] as [T].
+  ///
+  /// Note: resolving list/array flag values (e.g. `T` = `List<dynamic>`) is
+  /// deprecated. It keeps working for existing flags, but new flags should
+  /// not use list schemas. Lists in context and event data are unaffected.
   T? resolveKey<T>(String key) {
     List<String> keys = key.split(".");
     Map<String, dynamic> flags = _flags;