docs: v0.12.0 - image updates, auto-heal, richer startup

Author: dervish666

.claude/structure/monitors.yaml

@@ -212,3 +212,34 @@ files:
     imports:
       - from: src.config
         items: [MemoryConfig]
+
+  image_update_monitor.py:
+    description: Polls Docker registries for image digest changes, deduplicates across polls, sends batched update alert with Pull buttons
+    exports:
+      - name: extract_local_digests
+        kind: function
+        description: Return sha256 digests from a container's RepoDigests
+        params: [{name: container, type: Any}]
+        returns: list[str]
+
+      - name: ImageUpdateMonitor
+        kind: class
+        description: Poll loop that checks opted-in containers for newer registry images and emits a batched digest alert
+        methods:
+          - name: start
+            params: []
+            returns: Awaitable[None]
+          - name: stop
+            params: []
+            returns: None
+          - name: is_running
+            params: []
+            returns: bool
+
+    imports:
+      - from: src.config
+        items: [ImageUpdatesConfig]
+      - from: src.alerts.manager
+        items: [AlertSender]
+      - from: src.services.docker_client
+        items: [SharedDockerClient]

.claude/structure/services.yaml

@@ -199,3 +199,25 @@ files:
         items: [format_uptime]
       - from: src.utils.sanitize
         items: [sanitize_container_name, sanitize_logs]
+
+  auto_healer.py:
+    description: Auto-restarts opted-in containers that report HEALTHCHECK unhealthy, with per-container time-windowed storm guard
+    exports:
+      - name: AutoHealer
+        kind: class
+        description: Checks opt-in list and protected containers, tracks restart counts in a rolling window, restarts or escalates
+        methods:
+          - name: is_enabled
+            params: [{name: container_name, type: str}]
+            returns: bool
+          - name: heal
+            params: [{name: container_name, type: str}]
+            returns: Awaitable[None]
+
+    imports:
+      - from: src.config
+        items: [AutoHealConfig]
+      - from: src.services.container_control
+        items: [ContainerController]
+      - from: src.alerts.manager
+        items: [AlertSender]

.claude/structure/utils.yaml

@@ -151,3 +151,24 @@ files:
         items: [TypeVar, Callable, Awaitable, ParamSpec]
       - from: aiogram.exceptions
         items: [TelegramRetryAfter, TelegramAPIError]
+
+  version_store.py:
+    description: Read/write data/announced_version.json atomically to persist the last-announced bot version for the startup What's new gate.
+    exports:
+      - name: read_announced_version
+        kind: function
+        description: Return the last-announced bot version string, or None if unset or unreadable
+        params: [{name: path, type: str}]
+        returns: str | None
+      - name: write_announced_version
+        kind: function
+        description: Atomically persist the given version string to the announced_version file
+        params: [{name: path, type: str}, {name: version, type: str}]
+        returns: None
+    imports:
+      - from: json
+        items: [json]
+      - from: pathlib
+        items: [Path]
+      - from: tempfile
+        items: [tempfile]

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to UnraidMonitor will be documented in this file.
 
+## [0.12.0] - 2026-06-03
+
+### Added
+- **Image-update detection** (opt-in: `image_updates.enabled`) — polls registries every 24 hours (configurable via `image_updates.poll_interval_hours`), sends a batched digest alert when newer images are available, with per-container Pull buttons
+- **Auto-heal** (opt-in: `auto_heal.containers`) — automatically restarts opted-in containers that report a Docker HEALTHCHECK `unhealthy` status; storm guard prevents restart loops (configurable `max_restarts` / `window_minutes`); protected containers are never touched
+- **Richer startup message** — on first boot after a version upgrade, shows a "What's new" section with user-facing highlights; persists last-announced version to `data/announced_version.json`
+- **CI test pipeline** — GitHub Actions workflow runs tests, ruff lint, and mypy type-check on every push and pull request
+
 ## [0.11.1] - 2026-05-17
 
 ### Changed

CLAUDE.md

@@ -65,6 +65,7 @@ src/monitors/docker_events.py - DockerEventMonitor with CrashTracker for contain
 src/monitors/log_watcher.py - LogWatcher for streaming container logs, error detection
 src/monitors/resource_monitor.py - ResourceMonitor for per-container CPU/memory polling
 src/monitors/memory_monitor.py - MemoryMonitor for system memory pressure management
+src/monitors/image_update_monitor.py - ImageUpdateMonitor for daily image digest polling and batched update alerts
 
 # Services
 src/services/docker_client.py - SharedDockerClient wrapper for reconnectable Docker access
@@ -73,6 +74,7 @@ src/services/nl_tools.py - Tool definitions and executor for Claude tool use
 src/services/container_control.py - ContainerController for safe restart/stop/start
 src/services/container_classifier.py - ContainerClassifier using patterns and AI for roles
 src/services/diagnostic.py - DiagnosticService for AI container log analysis
+src/services/auto_healer.py - AutoHealer for opt-in auto-restart of unhealthy containers with storm guard
 
 # Unraid
 src/unraid/client.py - UnraidClientWrapper with direct GraphQL API access
@@ -85,10 +87,11 @@ src/utils/formatting.py - Bytes/uptime formatting, safe_reply/safe_edit, format_
 src/utils/rate_limiter.py - PerUserRateLimiter for per-user API rate limiting
 src/utils/sanitize.py - Prompt injection prevention, sensitive data redaction
 src/utils/telegram_retry.py - Telegram API retry logic for rate limit handling
+src/utils/version_store.py - read/write data/announced_version.json for startup What's new gate (atomic)
 
 ## Project Overview
 
-Unraid Server Monitor Bot (v0.11.1) - A Docker-based Telegram bot for monitoring Unraid servers. Monitors Docker containers (events, logs, resources) and Unraid server health (CPU, memory, disks, array, UPS). Uses multi-provider LLM support (Anthropic, OpenAI, Ollama) for AI-powered diagnostics and natural language interaction. Sends alerts via Telegram with quick-action buttons.
+Unraid Server Monitor Bot (v0.12.0) - A Docker-based Telegram bot for monitoring Unraid servers. Monitors Docker containers (events, logs, resources) and Unraid server health (CPU, memory, disks, array, UPS). Uses multi-provider LLM support (Anthropic, OpenAI, Ollama) for AI-powered diagnostics and natural language interaction. Sends alerts via Telegram with quick-action buttons.
 
 ## Commands
 
@@ -191,6 +194,7 @@ Inline keyboard buttons use `prefix:data` format, parsed with `split(":", 1)` to
 - `srv_set:metric:value` (apply server threshold, e.g., `srv_set:cpu_temp:90`, 0 = reset to default)
 - `model:provider_name`, `model_select:provider:model`, `model:back`
 - `setup:confirm`, `setup:toggle:category:container_name` (e.g., `setup:toggle:watched:plex`), `setup:adjust:category`, `setup:adjust_done`
+- `pull:container_name` (image-update digest -> shows pull confirmation)
 
 Callback handlers are registered with `F.data.startswith("prefix:")` filters in `register_commands()`.
 
@@ -266,8 +270,10 @@ Environment variables can also be set via `config/.env` (loaded by pydantic-sett
 - `protected_containers` / `ignored_containers` - Safety and visibility controls
 - `memory_management` - System memory pressure thresholds and kill policy
 - `resource_monitoring` - Per-container CPU/memory alert thresholds
+- `image_updates` - Opt-in daily digest of containers with newer images (enabled, poll_interval_hours)
+- `auto_heal` - Opt-in auto-restart of unhealthy containers (enabled, containers, max_restarts, window_minutes)
 
-Data files in `data/`: `mutes.json`, `server_mutes.json`, `array_mutes.json`, `ignored_errors.json`, `model_selection.json` (runtime LLM choice), `chat_ids.json` (persistent Telegram chat IDs for alert delivery)
+Data files in `data/`: `mutes.json`, `server_mutes.json`, `array_mutes.json`, `ignored_errors.json`, `model_selection.json` (runtime LLM choice), `chat_ids.json` (persistent Telegram chat IDs for alert delivery), `announced_version.json` (last-announced bot version for startup What's new gate)
 
 ## Design Context
 

README.md

@@ -12,19 +12,21 @@ A Telegram bot for monitoring Docker containers and Unraid servers. Get real-tim
 - **Smart Ignore Patterns** - AI-generated patterns to filter known errors, with interactive toggle selection
 - **Multi-Provider LLM** - Switch between Anthropic Claude, OpenAI GPT, or local Ollama models at runtime
 - **Container Control** - Start, stop, restart, and pull containers with inline confirmation buttons
+- **Image-Update Detection** - Opt-in daily digest of containers with newer images available, with Pull buttons
+- **Auto-Heal** - Opt-in automatic restart of unhealthy containers (HEALTHCHECK failures) with storm guard
 - **Unraid Server Monitoring** - CPU/memory, temperatures, UPS status, and array health
 - **Memory Pressure Management** - Automatic container priority handling during high memory
 - **Mute System** - Temporarily silence alerts per container, server, or array
 - **Natural Language Chat** - Ask questions naturally instead of using commands
 - **Interactive Dashboard** - `/manage` hub for status, resources, ignores, and mutes
 - **Sectioned Help** - `/help` with navigable category buttons instead of a text wall
 
-## What's New in v0.11.0
+## What's New in v0.12.0
 
-- **Server alert action buttons** (v0.10.0) - CPU temperature and usage alerts now include Mute and Adjust Threshold buttons, matching the UX of container and array alerts
-- **Model family system** (v0.10.0) - Use family names like `sonnet`, `haiku`, `opus` instead of dated model IDs; per-feature model switching with `/model chat sonnet`, `/model diagnose haiku`
-- **Dynamic provider resolution** (v0.10.1-0.10.3) - `/model` changes take effect immediately, config persistence fixes, and tool-call translation fixes for Anthropic API
-- **Security hardening** (v0.11.0) - Prompt injection defense for LLM inputs, SSRF protection in setup wizard, race condition fixes in memory monitor, crash tracker memory leak fix, and tighter file permissions
+- **Image-update detection** - Opt-in daily digest of containers with newer images available, with per-container Pull buttons (`image_updates.enabled: true`)
+- **Auto-heal** - Opt-in automatic restart of containers that fail their Docker HEALTHCHECK, with a storm guard that gives up after configurable retries (`auto_heal.containers: [...]`)
+- **Richer startup message** - On first boot after an upgrade, shows a "What's new" summary so you always know what changed
+- **CI test pipeline** - Tests, lint, and type-check now run automatically on every push and pull request
 
 See the [changelog](CHANGELOG.md) for full details.
 
@@ -350,6 +352,30 @@ unraid:
     ups_battery: 30      # Alert below this %
 ```
 
+### Image-Update Detection
+
+Checks once per day (configurable) whether a newer image is available for watched containers. Sends a single batched digest message with Pull buttons. Disabled by default — opt in per-deployment.
+
+```yaml
+image_updates:
+  enabled: false             # Set true to enable daily image-update checks
+  poll_interval_hours: 24    # How often to check (minimum 1)
+```
+
+### Auto-Heal
+
+Automatically restarts containers that report a Docker HEALTHCHECK `unhealthy` status. A per-container storm guard gives up after `max_restarts` within `window_minutes` and sends an escalation alert. Protected containers are never touched regardless of this setting.
+
+```yaml
+auto_heal:
+  enabled: true              # Master switch
+  containers:                # List of container names to auto-heal (opt-in)
+    - radarr
+    - sonarr
+  max_restarts: 3            # Give up after this many restarts in the window
+  window_minutes: 60         # Rolling window for the restart count
+```
+
 ---
 
 ## Commands

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unraid-monitor-bot"
-version = "0.11.1"
+version = "0.12.0"
 requires-python = ">=3.11"
 dependencies = [
     "docker>=7.0.0,<8.0.0",