docs: clarify anonymous context key generation behavior

packages/common/lib/src/ld_context.dart

@@ -140,6 +140,28 @@ 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.
+  ///
+  /// A context is also automatically set to anonymous at build time if no key
+  /// was provided to [LDContextBuilder.kind].
+  ///
+  /// When a context is anonymous and no key has been provided, 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.
+  ///
+  /// Example of creating an anonymous context with a generated key:
+  /// ```dart
+  /// // Explicitly anonymous:
+  /// final context = LDContextBuilder()
+  ///   .kind('user')
+  ///   .anonymous(true)
+  ///   .build();
+  ///
+  /// // Also anonymous (automatically, because no key was provided):
+  /// final context2 = LDContextBuilder()
+  ///   .kind('user')
+  ///   .build();
+  /// ```
   LDAttributesBuilder anonymous(bool anonymous) {
     _anonymous = anonymous;
     return this;
@@ -287,8 +309,9 @@ final class LDAttributesBuilder {
   LDContextAttributes? _build() {
     final key = _key ?? '';
     if (key == '' && !_anonymous) {
-      // If the context is not anonymous, then the key cannot be empty.
-      return null;
+      // If no key was provided, the context is automatically anonymous.
+      // The SDK will generate a stable key during start() or identify().
+      _anonymous = true;
     }
     if (_validKind(_kind)) {
       return LDContextAttributes._internal(
@@ -461,8 +484,10 @@ 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, the context will automatically be set to anonymous
+  /// at build time, and the SDK will 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.
   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.
   ///