unraid-docker-manager/.planning/phases/12-polish-audit/12-01-PLAN.md

---
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>