diff --git a/app/src/main/java/de/jeanlucmakiola/calendula/widget/agenda/AgendaWidget.kt b/app/src/main/java/de/jeanlucmakiola/calendula/widget/agenda/AgendaWidget.kt
index 50c0fbb..622d846 100644
--- a/app/src/main/java/de/jeanlucmakiola/calendula/widget/agenda/AgendaWidget.kt
+++ b/app/src/main/java/de/jeanlucmakiola/calendula/widget/agenda/AgendaWidget.kt
@@ -74,11 +74,6 @@ import kotlinx.datetime.toLocalDateTime
 import kotlin.time.Instant
 import java.util.Locale
 
-/**
- * "Upcoming" agenda widget — a continuously scrolling list of the next ~30 days
- * of events grouped under day headers (the Google "Schedule" widget model).
- * Reuses the app's [groupAgendaDays] grouping so it matches the in-app agenda.
- */
 /**
  * Per-instance Glance state key holding the agenda range (as [AgendaRange.storageValue]).
  * The range is read reactively in the composition ([currentState]) so a settings
@@ -113,6 +108,11 @@ internal val AGENDA_SHOW_TODAY_STATE_KEY = booleanPreferencesKey("agenda_show_to
  */
 internal val AGENDA_SIZE_KEY = stringPreferencesKey("widget_size")
 
+/**
+ * "Upcoming" agenda widget — a continuously scrolling list of the next ~30 days
+ * of events grouped under day headers (the Google "Schedule" widget model).
+ * Reuses the app's [groupAgendaDays] grouping so it matches the in-app agenda.
+ */
 class AgendaWidget : GlanceAppWidget() {
 
     override val stateDefinition = PreferencesGlanceStateDefinition
@@ -136,9 +136,11 @@ class AgendaWidget : GlanceAppWidget() {
 }
 
 /**
- * Re-reads the calendar and redraws the widget (header refresh button). Targets
- * the tapped widget's own id rather than `updateAll`, whose provider-name lookup
- * is empty in a process a tap woke from cold — see `ShiftMonthAction` (#18).
+ * Redraws the widget (header refresh button). Targets the tapped widget's own id
+ * rather than `updateAll`, whose provider-name lookup is empty in a process a tap
+ * woke from cold — see `ShiftMonthAction` (#18). A cold process re-reads the
+ * calendar in the `provideGlance` preamble; a live session only recomposes from
+ * the snapshot it already has (see [AGENDA_RANGE_KEY]).
  */
 class RefreshAgendaAction : ActionCallback {
     override suspend fun onAction(context: Context, glanceId: GlanceId, parameters: ActionParameters) {
@@ -149,7 +151,7 @@ class RefreshAgendaAction : ActionCallback {
 /**
  * Upper bound on rows handed to the [LazyColumn], so the serialized RemoteViews
  * stays well inside the binder transaction limit regardless of range and calendar
- * size (see the [SizeMode.Exact] note above). Far more than fits on screen — a
+ * size (see the [SizeMode.Single] note above). Far more than fits on screen — a
  * user scrolling a home-screen widget past a hundred rows is not a case worth
  * risking a failed update for.
  */