Document set_internal() limitations inline

esphome/core/entity_base.h

@@ -91,6 +91,16 @@ class EntityBase {
   // Set whether this Entity should be hidden outside ESPHome. Must be called before MQTT and the
   // API read the flag: from on_boot at the default priority, or a setup() that runs above
   // setup_priority::AFTER_CONNECTION. Calls after setup finishes are ignored and log an error.
+  //
+  // Known limitations, all by design and not going to be fixed:
+  // - No consumer is notified of a change, so the flag can only be decided once per boot.
+  // - The guard is coarse: a call from a priority below AFTER_CONNECTION (an on_boot with a low
+  //   priority, or a setup() at LATE) still passes, but MQTT has already cached the flag and the
+  //   API camera listener is already registered, so those consumers keep the old value.
+  // - Un-hiding an entity declared 'internal: true' in YAML skips the duplicate name check that
+  //   codegen runs for exposed entities, so a name collision can surface at runtime. Entities with
+  //   only an 'id:' are forced internal and use the id as their name.
+  // - Zigbee codegen skips YAML internal entities entirely, so un-hiding cannot add them to Zigbee.
   void set_internal(bool internal);
 
   // Check if this object is declared to be disabled by default.