docs(12): create phase plan

.planning/ROADMAP.md

@@ -132,10 +132,11 @@ Plans:
 
 **Requirements:** UNR-01, ENV-01, ENV-02, DEBT-02
 
-**Plans:** 0 plans
+**Plans:** 2 plans
 
 Plans:
-- [ ] TBD (run /gsd:plan-phase 12 to break down)
+- [ ] 12-01-PLAN.md — Documentation update (README, env vars, DEBT-02 verification) + Unraid badge investigation
+- [ ] 12-02-PLAN.md — Deferred UAT: Update All text command (BATCH-04) and inline keyboard (BATCH-05)
 
 **Success Criteria:**
 1. After bot successfully updates a container, Unraid UI no longer shows "update available" for that container
@@ -178,10 +179,10 @@ Plans:
 | 10.1 | Aggressive Workflow Modularization | v1.2 | Complete |
 | 10.2 | Better Logging & Log Management | v1.2 | Complete (descoped) |
 | 11 | Update All & Callback Limits | v1.2 | Complete (UAT partial, 2 deferred) |
-| 12 | Polish & Audit | v1.2 | Pending |
+| 12 | Polish & Audit | v1.2 | Planned |
 | 13 | Documentation Overhaul | v1.2 | Pending |
 
 **v1.2 Coverage:** 12+ requirements mapped across 7 phases
 
 ---
-*Updated: 2026-02-08 — Phase 11 complete (bitmap encoding + Update All button deployed, 2 UAT tests deferred to Phase 12)*
+*Updated: 2026-02-08 — Phase 12 planned (2 plans in 1 wave)*

.planning/phases/12-polish-audit/12-01-PLAN.md

@@ -0,0 +1,185 @@
+---
+phase: 12-polish-audit
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - DEPLOY-SUBWORKFLOWS.md
+  - README.md
+  - .planning/REQUIREMENTS.md
+autonomous: false
+
+must_haves:
+  truths:
+    - "README documents that TELEGRAM_BOT_TOKEN is stored in n8n credential and referenced via $env in HTTP Request nodes"
+    - "README documents that user ID is hardcoded in IF nodes with instructions to change it"
+    - "README documents docker-socket-proxy architecture instead of direct socket mount"
+    - "DEBT-02 is verified fixed (single --max-time flag) and marked complete in REQUIREMENTS.md"
+    - "Unraid badge limitation is either solved programmatically or documented as known limitation with workaround"
+  artifacts:
+    - path: "README.md"
+      provides: "Updated installation and configuration documentation"
+      contains: "docker-socket-proxy"
+    - path: "DEPLOY-SUBWORKFLOWS.md"
+      provides: "Unraid badge limitation documentation (if not solvable)"
+      contains: "Known Limitation"
+    - path: ".planning/REQUIREMENTS.md"
+      provides: "Updated requirement status for DEBT-02, ENV-01, ENV-02"
+      contains: "DEBT-02"
+  key_links:
+    - from: "README.md"
+      to: "n8n-workflow.json"
+      via: "installation instructions reference workflow configuration"
+      pattern: "IF User Authenticated|IF Callback Authenticated"
+---
+
+<objective>
+Investigate Unraid update badge clearing, update environment configuration documentation, and verify DEBT-02 is resolved.
+
+Purpose: Close out documentation requirements (ENV-01, ENV-02), verify and close DEBT-02, and either solve or document the Unraid badge persistence issue (UNR-01).
+Output: Updated README.md with accurate installation/config docs, updated REQUIREMENTS.md marking DEBT-02 complete, Unraid badge solution or documented limitation.
+</objective>
+
+<execution_context>
+@/home/luc/.claude/get-shit-done/workflows/execute-plan.md
+@/home/luc/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/12-polish-audit/12-RESEARCH.md
+@README.md
+@DEPLOY-SUBWORKFLOWS.md
+@.planning/REQUIREMENTS.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Update README with accurate environment and architecture documentation</name>
+  <files>README.md, .planning/REQUIREMENTS.md</files>
+  <action>
+Update README.md to reflect the current architecture and clarify environment configuration. The current README is outdated -- it documents direct docker.sock mounting instead of docker-socket-proxy.
+
+**Section 1 -- Installation (replace "Configure n8n Container" section):**
+
+Replace the docker run example and flags to document docker-socket-proxy architecture:
+- n8n communicates with Docker via `docker-socket-proxy` container on `dockernet` network
+- No direct docker.sock mount on n8n container
+- n8n container needs `--network dockernet` and the static curl binary mount
+- docker-socket-proxy container handles Docker API filtering (blocks exec, build, commit)
+- Reference DEPLOYMENT_GUIDE.md for detailed setup
+
+**Section 2 -- Telegram Configuration (replace/expand "Configure Your User ID" and "Create Telegram API Credential" sections):**
+
+Clarify ENV-01 and ENV-02:
+
+For TELEGRAM_BOT_TOKEN (ENV-02):
+- Bot token is stored in n8n's credential manager (Settings > Credentials > Telegram API)
+- HTTP Request nodes reference it via `$env.TELEGRAM_BOT_TOKEN` environment variable
+- Both are needed: the credential for Telegram Trigger node, the env var for HTTP Request nodes that send messages/edit keyboards
+- Document: "Set TELEGRAM_BOT_TOKEN environment variable on your n8n container to the same bot token used in the credential"
+
+For TELEGRAM_USERID (ENV-01):
+- User ID is hardcoded in two IF nodes: "IF User Authenticated" and "IF Callback Authenticated"
+- No environment variable needed -- edit the workflow nodes directly
+- Keep existing step-by-step instructions for changing the user ID
+- Clarify: "No TELEGRAM_USERID environment variable is used. The user ID is configured directly in the workflow."
+
+**Section 3 -- Sub-workflows:**
+
+Add a brief note that the bot uses 7 sub-workflows that must be imported separately. Reference DEPLOY-SUBWORKFLOWS.md for details. List the files: n8n-update.json, n8n-actions.json, n8n-logs.json, n8n-batch-ui.json, n8n-status.json, n8n-confirmation.json, n8n-matching.json.
+
+**Section 4 -- Commands table:**
+
+Add missing commands to the usage table:
+- `update all` -- Update all containers with :latest tag
+- `/list` -- Alias for status command
+- Inline keyboard -- mention "Use /status to access the interactive container list with action buttons"
+
+**DEBT-02 verification and closure:**
+
+In .planning/REQUIREMENTS.md, verify and update DEBT-02:
+- Grep confirmed only ONE `--max-time 600` flag exists in n8n-update.json line 137
+- No duplicate flags found in any n8n-*.json file
+- Mark DEBT-02 as complete with note: "Verified -- single --max-time 600 flag, no duplicates found"
+- Also mark ENV-01 and ENV-02 as complete after README update
+- Update the traceability table status for DEBT-02, ENV-01, ENV-02
+  </action>
+  <verify>
+1. `grep -c "docker-socket-proxy" README.md` returns at least 1
+2. `grep -c "TELEGRAM_BOT_TOKEN" README.md` returns at least 1
+3. `grep -c "IF User Authenticated" README.md` returns at least 1
+4. `grep -c "update all" README.md` returns at least 1
+5. `grep "DEBT-02" .planning/REQUIREMENTS.md` shows completed status
+6. `grep "ENV-01" .planning/REQUIREMENTS.md` shows completed status
+  </verify>
+  <done>
+README documents docker-socket-proxy architecture (not direct socket mount), clarifies TELEGRAM_BOT_TOKEN is both n8n credential AND env var, clarifies user ID is hardcoded in IF nodes (no env var), lists all commands including "update all" and /list. DEBT-02 marked complete in REQUIREMENTS.md. ENV-01 and ENV-02 marked complete.
+  </done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 2: Investigate Unraid update badge clearing on live server</name>
+  <files>DEPLOY-SUBWORKFLOWS.md</files>
+  <action>
+Before presenting the checkpoint, Claude will add a "Known Limitations" section to DEPLOY-SUBWORKFLOWS.md documenting the Unraid update badge issue and preparing investigation commands.
+
+The checkpoint asks the user to run investigation commands on their Unraid server to determine if the update badge can be cleared programmatically. Based on findings, Claude will either implement a solution or finalize the limitation documentation.
+  </action>
+  <verify>
+User runs investigation commands on Unraid server and reports findings:
+
+**Investigation commands to run on Unraid terminal/SSH:**
+
+```bash
+# 1. Check if the update status file exists and examine its structure
+cat /var/lib/docker/unraid-update-status.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print(json.dumps(d, indent=2))" 2>/dev/null || echo "File not found or not JSON"
+
+# 2. Check for Unraid's dockerupdate.php or similar scripts
+find /usr/local/emhttp/plugins/dynamix.docker.manager -name "*.php" -exec grep -l "update" {} \; 2>/dev/null
+
+# 3. Check if Unraid has a web API endpoint for docker updates
+ls /usr/local/emhttp/plugins/dynamix.docker.manager/include/ 2>/dev/null
+
+# 4. Check Unraid's Docker management scripts
+grep -r "update" /usr/local/emhttp/plugins/dynamix.docker.manager/include/ 2>/dev/null | head -30
+```
+
+**What to report back:**
+- Contents of unraid-update-status.json (or that it doesn't exist)
+- Any PHP scripts or API endpoints found for update management
+- Any clues about how Unraid tracks update state
+
+Based on findings, Claude will either:
+- **If programmatic solution found:** Implement badge clearing in n8n-update.json
+- **If no solution found:** Finalize limitation documentation in DEPLOY-SUBWORKFLOWS.md with workaround ("Apply Update" in Unraid is instant since image is already cached)
+  </verify>
+  <done>
+Unraid badge clearing is either implemented programmatically or documented as a known limitation with clear workaround instructions. UNR-01 requirement resolved.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+- README.md accurately reflects current architecture (docker-socket-proxy, not direct socket)
+- README.md clearly documents TELEGRAM_BOT_TOKEN and user ID configuration
+- REQUIREMENTS.md has DEBT-02, ENV-01, ENV-02 marked complete
+- Unraid badge clearing either implemented or documented as known limitation
+</verification>
+
+<success_criteria>
+- README installation instructions match actual docker-socket-proxy architecture
+- ENV-01 satisfied: Documentation clarifies user ID is hardcoded, no env var needed
+- ENV-02 satisfied: Documentation clarifies bot token needs both n8n credential AND env var
+- DEBT-02 satisfied: Verified single --max-time flag, marked complete
+- UNR-01: Either programmatic solution deployed OR limitation documented with workaround
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/12-polish-audit/12-01-SUMMARY.md`
+</output>

.planning/phases/12-polish-audit/12-02-PLAN.md

@@ -0,0 +1,131 @@
+---
+phase: 12-polish-audit
+plan: 02
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: false
+
+must_haves:
+  truths:
+    - "User can type 'update all' and see confirmation listing :latest containers"
+    - "User can tap 'Update All :latest' button in container list keyboard and see confirmation"
+    - "Confirming update-all triggers batch execution with progress updates"
+    - "Final summary shows success/failure counts for updated containers"
+  artifacts: []
+  key_links:
+    - from: "Keyword Router"
+      to: "Get All Containers For Update All"
+      via: "update all text command routing"
+      pattern: "update all"
+    - from: "Route Callback [updateallstart]"
+      to: "Answer Update All Start"
+      via: "uall:start callback routing"
+      pattern: "updateallstart"
+---
+
+<objective>
+Execute deferred Phase 11 UAT tests for Update All functionality (BATCH-04 text command, BATCH-05 inline keyboard button).
+
+Purpose: Complete the two UAT tests deferred from Phase 11. Code is already deployed -- this is validation only.
+Output: UAT results confirming Update All works end-to-end via both entry points.
+</objective>
+
+<execution_context>
+@/home/luc/.claude/get-shit-done/workflows/execute-plan.md
+@/home/luc/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/11-update-all-callback-limits/11-02-SUMMARY.md
+@.planning/phases/11-update-all-callback-limits/11-VERIFICATION.md
+</context>
+
+<tasks>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 1: UAT -- Update All via text command (BATCH-04)</name>
+  <files>n8n-workflow.json</files>
+  <action>
+User verifies the Update All text command end-to-end. This was deployed in Phase 11 (Plan 11-02) but UAT was deferred. The Keyword Router matches "update all" and routes to Get All Containers For Update All, which filters :latest containers and shows a confirmation dialog. No code changes needed -- this is validation only.
+  </action>
+  <verify>
+**Preconditions:**
+- Workflow is active and deployed
+- You have containers with :latest tag on your Unraid server
+
+**Test Steps:**
+
+1. Send "update all" to the bot via Telegram
+2. **Expected:** Bot responds with a confirmation message listing all containers with :latest tag and their current status
+3. Verify the container count in the confirmation matches your actual :latest container count
+4. Tap the "Confirm" button
+5. **Expected:** Progress message appears showing batch execution starting
+6. Wait for execution to complete
+7. **Expected:** Final summary message shows N succeeded, M failed (ideally 0 failed)
+8. Send "/status" to verify containers show updated status
+
+**Pass criteria:**
+- Confirmation lists all :latest containers
+- Progress updates appear during batch execution
+- Summary shows accurate success/failure counts
+- No error messages or timeouts
+  </verify>
+  <done>
+User confirms "update all" text command triggers confirmation dialog, batch execution with progress, and summary. BATCH-04 UAT complete.
+  </done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 2: UAT -- Update All via inline keyboard (BATCH-05)</name>
+  <files>n8n-status.json, n8n-workflow.json</files>
+  <action>
+User verifies the Update All inline keyboard button end-to-end. This was deployed in Phase 11 (Plan 11-02). The container list keyboard in n8n-status.json includes a "Update All :latest" button with callback data `uall:start`. When tapped, Route Callback matches `updateallstart` and routes through Answer Update All Start to the same confirmation flow as the text command. No code changes needed -- this is validation only.
+  </action>
+  <verify>
+**Preconditions:**
+- Same as Task 1 (workflow active, :latest containers present)
+
+**Test Steps:**
+
+1. Send "/status" or "/list" to the bot to display the container list keyboard
+2. Locate the "Update All :latest" button in the inline keyboard (below navigation, above Select Multiple)
+3. Tap the "Update All :latest" button
+4. **Expected:** Bot acknowledges with "Checking for updates..." callback answer
+5. **Expected:** Confirmation message appears listing all :latest containers (same as text command flow)
+6. Tap "Confirm" button
+7. **Expected:** Same batch execution flow as Task 1 (progress, summary)
+8. Send "/status" to verify containers show updated status
+
+**Pass criteria:**
+- "Update All :latest" button visible in container list keyboard
+- Tapping button shows confirmation dialog with :latest containers
+- Confirmation and batch execution work identically to text command
+- No error messages or timeouts
+  </verify>
+  <done>
+User confirms "Update All :latest" inline keyboard button triggers same confirmation and batch execution flow as text command. BATCH-05 UAT complete.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+- BATCH-04 (Update All text command) passes end-to-end UAT
+- BATCH-05 (Update All inline keyboard) passes end-to-end UAT
+- Both entry points produce identical confirmation and execution flows
+</verification>
+
+<success_criteria>
+- User successfully triggers Update All via "update all" text command with confirmation and batch execution
+- User successfully triggers Update All via inline keyboard button with confirmation and batch execution
+- Both Phase 11 deferred UAT tests completed with pass/fail determination
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/12-polish-audit/12-02-SUMMARY.md`
+</output>