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

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="auto">
  <name>Task 2: Document Unraid update badge limitation (UNR-01)</name>
  <files>DEPLOY-SUBWORKFLOWS.md</files>
  <action>
Document the Unraid update badge limitation as a known issue with clear explanation and workaround.

**Root cause (confirmed by user testing):**
- The bot uses Docker API directly to pull images and recreate containers
- Unraid manages containers through its own XML template system (`/boot/config/plugins/dockerMan/templates-user/`)
- When Unraid checks for updates, it compares the running container's image against the registry
- Since the bot bypassed Unraid's template system, Unraid shows "apply update" even though the container may already be running the new image
- "Check for Updates" does NOT clear the badge — it actually CREATES the badge if the bot updated a container Unraid hadn't checked yet
- "Apply Update" completes instantly because the image is already cached — Unraid just recreates from its template

**Add a "Known Limitations" section to DEPLOY-SUBWORKFLOWS.md:**

```markdown
## Known Limitations

### Unraid Update Badges (UNR-01)

After the bot updates a container, Unraid's Docker tab may show "apply update"
on the next update check. This is expected behavior.

**Why this happens:** The bot uses the Docker API directly to pull images and
recreate containers. Unraid manages containers through its own XML template
system and doesn't know the container was updated outside of its control.

**What to do:** Click "Apply Update" in Unraid's Docker tab. It completes
instantly because the image is already pulled and cached — Unraid just
recreates the container from its template to sync its internal tracking.

**Important:** "Check for Updates" in Unraid does NOT clear an existing badge.
It may actually cause a new badge to appear if the bot updated a container that
Unraid hadn't checked yet.

**Why not fix programmatically:** Clearing the badge would require calling
Unraid's internal web API to "apply" the update through its template system.
This adds significant complexity (Unraid web UI access, authentication,
template parsing) for a cosmetic issue that takes one click to resolve.
```

Also update .planning/REQUIREMENTS.md to mark UNR-01 status as "Documented limitation with workaround" and update the traceability table.
  </action>
  <verify>
1. `grep -c "Known Limitations" DEPLOY-SUBWORKFLOWS.md` returns at least 1
2. `grep -c "UNR-01" DEPLOY-SUBWORKFLOWS.md` returns at least 1
3. `grep "UNR-01" .planning/REQUIREMENTS.md` shows updated status
  </verify>
  <done>
Unraid update badge limitation documented in DEPLOY-SUBWORKFLOWS.md with root cause explanation and workaround. UNR-01 marked as resolved (documented limitation) in REQUIREMENTS.md.
  </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>