docs/core/entity/scene.md (3)

26-34: Good rename; consider clarifying imports in the snippet.

Renaming MySwitch → MyScene aligns the example with the domain. Minor nit: since the snippet uses Any, consider adding a brief comment like “# imports omitted for brevity (e.g., from typing import Any)” to avoid confusion for copy/paste.

---

39-42: Clarify statelessness vs “state updated” phrasing.

Scenes are documented as stateless above. Suggest wording that reflects recording an activation without implying an on/off state.

Apply this diff to tighten the language:

-Some integrations can receive external events (for example, physical button presses) that activate scenes outside of Home Assistant. These activations do not originate from the Home Assistant UI or service calls, but from external sources such as hardware controllers or third-party systems.
-
-To support this scenario, integrations should notify Home Assistant when an external scene activation occurs. This ensures the scene entity's state is updated and can be used in automations.
+Some integrations can receive external events (for example, physical button presses) that activate scenes outside of Home Assistant. These activations do not originate from the Home Assistant UI or service calls, but from external sources such as hardware controllers or third-party systems.
+
+To support this scenario, integrations should notify Home Assistant when an external scene activation occurs. This records the activation and schedules a state update (for example, updating a last_activated attribute) so automations can react. Note: Scenes remain stateless; this does not imply a persistent “on” state.

---

43-57: Verify BaseScene API and private hooks; make the example self-contained.

Great addition. A few actionable adjustments:

• Ensure BaseScene and the protected hooks you’re documenting (_async_activate, _state_received, _async_record_activation) exist as public-to-override hooks in the linked Core PR; otherwise the docs will direct integrators to private APIs.
• Consider adding minimal imports so types like Any and ReceiveMessage are resolved in copy/paste scenarios.
• Add a pointer to the BaseScene symbol (path or link) just like you did for Scene to help discoverability.

Suggested doc/code tweaks:

-# Inherit from BaseScene
-class MyScene(BaseScene):
+# Inherit from BaseScene (homeassistant.components.scene.BaseScene)
+# Imports shown for completeness:
+from typing import Any
+from homeassistant.components.scene import BaseScene
+from homeassistant.components.mqtt import async_publish as mqtt_publish
+from homeassistant.components.mqtt.models import ReceiveMessage
+
+class MyScene(BaseScene):

     # Note the leading underscore
     async def _async_activate(self, **kwargs: Any) -> None:
         """Activate scene."""
         # Call a service to activate scene
-        await mqtt.async_publish(self.hass, self._topic, self._payload)
+        await mqtt_publish(self.hass, self._topic, self._payload)

     # Record the activation in the callback of your service
     async def _state_received(self, msg: ReceiveMessage) -> None:
-        self._async_record_activation()
+        # Record the activation so automations can react (e.g., updates last_activated)
+        self._async_record_activation()
         self.async_schedule_update_ha_state()

Follow-ups:

• After this code block, add a short note that these are protected hooks provided by BaseScene and are safe to override.
• Optionally add a link to BaseScene in the header paragraph similar to the link you provide for Scene.

To confirm symbol names and stability, please verify against the Core PR you referenced. If helpful, I can also open a small follow-up PR to add the BaseScene link and import hints once the Core PR is merged.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

docs/core/entity/scene.md (1)

39-40: Clear rationale for external activations — good addition.

Nicely explains that activations can originate outside HA (e.g., physical buttons). This addresses prior feedback.

docs/core/entity/scene.md (3)

41-41: Wording and cross-link nit: “inherit from” and link BaseScene.

Suggest minor wording tweak for precision and adding a link, to mirror the earlier link to Scene.

-To support this scenario, integrations should extend from `BaseScene` instead of `Scene`, override `_async_activate()` to handle the scene activation from the Home Assistant side, and call `_async_record_activation()` when an external scene activation occurs.
+To support this scenario, integrations should inherit from [`BaseScene`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/scene/__init__.py) instead of [`Scene`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/scene/__init__.py), override `_async_activate()` to handle activation initiated by Home Assistant, and call `_async_record_activation()` when an external activation is observed.

---

43-43: Grammar/clarity: article and phrasing around the timestamp.

Tighten wording (also matches the static analyzer hint).

-Also, since these scenes activate outside of Home Assistant, the integration may want to delay updating scene state timestamp until the external scene reports being active, even when it is activated from the Home Assistant UI.
+Also, because these scenes can be activated outside of Home Assistant, the integration might delay updating the activation timestamp until the external scene reports as active—even when the activation originates from the Home Assistant UI.

---

45-59: Example: add one clarifying comment to the callback.

Make it explicit that _state_received is called from an integration callback (e.g., MQTT message handler).

     # Record the activation in the callback of your service
-    async def _state_received(self, msg: ReceiveMessage) -> None:
+    # Called from your integration's message handler (e.g., MQTT) when the scene reports active
+    async def _state_received(self, msg: ReceiveMessage) -> None:
         self._async_record_activation()
         self.async_schedule_update_ha_state()

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.