docs: clarify anonymous context key generation behavior

packages/common/lib/src/ld_context.dart

@@ -140,6 +140,22 @@ final class LDAttributesBuilder {
   /// It does not exclude it from analytics event data, so it is not the same as
   /// making attributes private; all non-private attributes will still be
   /// included in events and data export.
+  ///
+  /// When a context is anonymous and no key has been provided (i.e. the key
+  /// parameter was omitted from [LDContextBuilder.kind]), the SDK will
+  /// automatically generate a key for the context during [LDClient.start] or
+  /// [LDClient.identify]. The generated key is a UUID that is persisted
+  /// on the device, so it will remain stable across application restarts.
+  /// If persistence is not available, the generated key will not be stable
+  /// across application restarts.
+  ///
+  /// Example of creating an anonymous context with a generated key:
+  /// ```dart
+  /// final context = LDContextBuilder()
+  ///   .kind('user')
+  ///   .anonymous(true)
+  ///   .build();
+  /// ```
   LDAttributesBuilder anonymous(bool anonymous) {
     _anonymous = anonymous;
     return this;
@@ -461,8 +477,13 @@ final class LDContextBuilder {
   /// non-empty.  Calling this method again with the same kind returns the same
   /// [LDAttributesBuilder] as before.
   ///
-  /// If key is omitted, this will create an anonymous context with a generated key.
-  /// The generated key will be persisted and reused for future application runs.
+  /// If [key] is omitted and [LDAttributesBuilder.anonymous] is set to true,
+  /// the SDK will automatically generate a stable key for this context during
+  /// [LDClient.start] or [LDClient.identify]. The generated key will be
+  /// persisted on the device and reused for future application runs.
+  ///
+  /// If [key] is omitted and anonymous is not set to true, the context will
+  /// be invalid.
   LDAttributesBuilder kind(String kind, [String? key]) {
     LDAttributesBuilder builder = _buildersByKind.putIfAbsent(
         kind, () => LDAttributesBuilder._internal(this, kind));

packages/flutter_client_sdk/lib/src/ld_client.dart

@@ -112,6 +112,11 @@ interface class LDClient {
   /// `runApp` is called, you must ensure the binding is initialized with
   /// `WidgetsFlutterBinding.ensureInitialized`.
   ///
+  /// During startup, if the initial context contains any anonymous contexts
+  /// without keys (i.e. [LDAttributesBuilder.anonymous] was set to true and
+  /// no key was provided to [LDContextBuilder.kind]), the SDK will
+  /// automatically generate and persist a stable key for each such context.
+  ///
   /// The [start] function can take an indeterminate amount of time to
   /// complete. For instance if the SDK is started while a device is in airplane
   /// mode, then it may not complete until some time in the future when the
@@ -144,6 +149,12 @@ interface class LDClient {
   /// service containing the public [LDContext] fields for indexing on the
   /// dashboard.
   ///
+  /// If the provided context contains any anonymous contexts without keys
+  /// (i.e. [LDAttributesBuilder.anonymous] was set to true and no key was
+  /// provided to [LDContextBuilder.kind]), the SDK will automatically generate
+  /// and persist a stable key for each such context before processing the
+  /// identify.
+  ///
   /// A context with the same kinds and same keys will use the same cached
   /// context.
   ///