docs(12): plan phase with Unraid badge research and UAT

Research found Unraid badge issue is architectural (bot bypasses
Unraid's XML template system). Updated plans to document limitation
with workaround instead of attempting programmatic fix. Plan 01
covers docs/env/debt, Plan 02 covers deferred Update All UAT.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.planning/phases/12-polish-audit/12-RESEARCH.md

@@ -70,62 +70,73 @@ No new libraries required. All tooling already in place.
 
 ### Unraid Update Status Tracking
 
-**Current understanding:**
+**UPDATED based on user testing (2026-02-08):**
+
+User tested with code-server container. Key observations:
+1. Bot pulled update for code-server that wasn't yet showing in Unraid UI
+2. After clicking "Check for Updates" in Unraid, it went from "up to date" to "apply update"
+3. Clicking "Apply Update" just restarted the container (image was already cached)
+4. "Check for Updates" does NOT clear the badge — it actually CREATES it
+
+**Root cause (revised):** Unraid compares the running container's image ID against the latest pulled image. When the bot pulls a new image and recreates the container via Docker API, Unraid's template system doesn't register the recreation. On next "Check for Updates", Unraid sees the new image is available and flags the container — even though the container may already be running the new image.
+
+The issue is that Unraid manages containers through its own **XML template system** (`/boot/config/plugins/dockerMan/templates-user/`). When Unraid "applies" an update, it:
+1. Removes the old container
+2. Pulls the image (already cached = instant)
+3. Recreates the container FROM ITS XML TEMPLATE
+4. Updates its internal tracking
+
+The bot bypasses this template system entirely — it uses Docker API directly. Unraid doesn't know the container was recreated.
 
 ```
-Unraid update tracking mechanism:
+Unraid update tracking mechanism (revised):
+├── /boot/config/plugins/dockerMan/templates-user/my-*.xml
+│   └── Container creation templates (ports, volumes, env vars)
 ├── /var/lib/docker/unraid-update-status.json
-│   └── Stores local sha256 hash information
+│   └── Stores image digest comparison state
 ├── "Check for Updates" button
-│   └── Queries Docker registries for new digests
-│   └── Updates unraid-update-status.json
-└── Container XML templates
-    └── <Registry> element stores Docker Registry URL
+│   └── Compares running container image ID vs registry latest
+│   └── If different → shows "apply update" (even if bot already updated)
+├── "Apply Update" button
+│   └── Removes container, pulls image (cached), recreates from XML template
+│   └── Updates tracking state
+└── Key insight: "Check for Updates" does NOT clear badges, it CREATES them
 ```
 
-**Pattern 1: Post-Update Notification**
+**Pattern 1: Update via Unraid's Template System**
 
-**What:** After bot successfully pulls image and recreates container, trigger Unraid's update check mechanism
+**What:** After pulling the image, use Unraid's own update mechanism to recreate the container
 
-**When to use:** If Unraid exposes an API endpoint or file-based trigger
+**When to use:** If Unraid exposes an API endpoint to apply updates
 
-**Implementation options:**
+**Potential approach:** Unraid's web UI makes HTTP calls to its own emhttp backend. The "Apply Update" button likely hits an endpoint like `/plugins/dynamix.docker.manager/include/CreateDocker.php` or similar. If we can replicate that call, Unraid would properly track the update.
 
-```bash
-# Option A: Delete update status file to force refresh
-rm /var/lib/docker/unraid-update-status.json
-# Unraid regenerates on next check
+**Caveat:** The bot would need network access to the Unraid web UI (port 80/443), which is separate from the Docker socket proxy.
 
-# Option B: Call Unraid API (if exists)
-curl -X POST http://localhost/api/docker/check-updates
+**Pattern 2: Workaround Documentation (RECOMMENDED)**
 
-# Option C: Update JSON directly
-# Read unraid-update-status.json, modify specific container entry, write back
-# RISK: Schema unknown, could break Unraid's tracking
-```
+**What:** Document the limitation honestly and explain why "Apply Update" is instant
 
-**Pattern 2: Workaround Documentation**
-
-**What:** If no programmatic solution exists, document the limitation and provide user instructions
-
-**When to use:** If Unraid doesn't expose APIs and file manipulation is too risky
-
-**Example documentation:**
+**When to use:** Default approach — programmatic solution requires Unraid API access which adds significant complexity
 
 ```markdown
 ## Known Limitation: Unraid Update Badges
 
-When the bot updates a container, Unraid's UI may continue showing
-"update available" until you manually click "Apply Update" in the
-Unraid Docker tab. This is safe — the image is already cached, so
-Unraid will recreate the container instantly.
+After the bot updates a container, Unraid's UI may show "apply update"
+on the next update check. This is expected — Unraid tracks container
+updates through its own template system, which the bot bypasses.
 
-**Why this happens:** Unraid tracks updates separately from Docker
-image digests. The bot pulls the image correctly, but Unraid's
-tracking file isn't notified.
+**Why this happens:** The bot uses the Docker API directly to pull images
+and recreate containers. Unraid doesn't know the container was updated
+because it wasn't done through Unraid's template system.
 
-**Workaround:** Click "Apply Update" in Unraid UI, or click "Check
-for Updates" to refresh the status.
+**What to do:** Click "Apply Update" in Unraid's Docker tab. It completes
+instantly because the image is already cached — Unraid just recreates the
+container from its template to sync its tracking state.
+
+**Note:** "Check for Updates" does NOT clear the badge. It may actually
+cause a badge to appear if the bot updated a container that Unraid hadn't
+checked yet.
 ```
 
 ### Environment Variable Documentation