Document upstream visibility enum + cascade for advanced/hidden flags

src/api/types.ts

@@ -588,9 +588,27 @@ export interface ConfigEntry {
   pin_mode: PinMode | null;
 
   // === UI / i18n ===
-  /** When True frontend collapses this entry under an "Advanced" section. */
+  /**
+   * When True frontend collapses this entry under an "Advanced" section.
+   *
+   * Source of truth: upstream esphome's ``cv.Optional(...,
+   * advanced=True)`` schema kwarg (esphome/esphome#16267) when the
+   * field author marked it explicitly. The catalog generator's
+   * ``_classify_advanced`` heuristic in ``script/sync_components.py``
+   * is the fallback for fields the schema doesn't yet annotate; as
+   * upstream adoption grows, the heuristic shrinks toward zero.
+   */
   advanced: boolean;
-  /** When True frontend hides the entry entirely. */
+  /**
+   * When True frontend hides the entry entirely.
+   *
+   * Source of truth: upstream esphome's ``cv.Optional(...,
+   * yaml_only=True)`` schema kwarg (esphome/esphome#16267). Marks
+   * fields the user shouldn't edit through a visual editor — e.g.
+   * ``setup_priority`` on every component, where casual UI-driven
+   * tweaks can break boot. The YAML escape hatch stays available
+   * for the rare power-user override.
+   */
   hidden: boolean;
   /** Optional URL pointing to documentation specific to this field. */
   help_link: string | null;