unraid-docker-manager/.planning/phases/13-documentation-overhaul/13-01-PLAN.md

---
phase: 13-documentation-overhaul
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - README.md
  - DEPLOYMENT_GUIDE.md
  - DEPLOY-SUBWORKFLOWS.md
autonomous: true

must_haves:
  truths:
    - "README has a dedicated Architecture section explaining the system design (main workflow + 7 sub-workflows + docker-socket-proxy)"
    - "README has a dedicated Configuration section separated from Installation"
    - "README documents batch selection workflow (how to select multiple containers via inline keyboard)"
    - "README documents the inline keyboard Update All button"
    - "README has a Troubleshooting section covering common issues"
    - "DEPLOYMENT_GUIDE.md is removed (superseded by DEPLOY-SUBWORKFLOWS.md)"
    - "All documentation cross-references are valid (no broken links to removed files)"
  artifacts:
    - path: "README.md"
      provides: "Complete user-facing documentation with architecture, configuration, and troubleshooting sections"
      contains: "## Architecture"
    - path: "DEPLOY-SUBWORKFLOWS.md"
      provides: "Updated cross-references (no link to DEPLOYMENT_GUIDE.md)"
  key_links:
    - from: "README.md"
      to: "DEPLOY-SUBWORKFLOWS.md"
      via: "markdown link"
      pattern: "DEPLOY-SUBWORKFLOWS\\.md"
---

<objective>
Overhaul README.md to follow modern documentation standards and consolidate documentation by removing the outdated DEPLOYMENT_GUIDE.md.

Purpose: Phase 12 satisfied the formal requirements (DEBT-01, ENV-01, ENV-02), but the README still lacks dedicated architecture, configuration, and troubleshooting sections. DEPLOYMENT_GUIDE.md (written in Phase 10-05 for 3 sub-workflows and 199 nodes) is outdated and fully superseded by DEPLOY-SUBWORKFLOWS.md.

Output: A comprehensive README.md and a clean documentation structure with no redundant files.
</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/STATE.md
@.planning/ROADMAP.md
@README.md
@DEPLOYMENT_GUIDE.md
@DEPLOY-SUBWORKFLOWS.md
@.planning/phases/13-documentation-overhaul/13-RESEARCH.md
@.planning/phases/12-polish-audit/12-01-SUMMARY.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Overhaul README with architecture, configuration, troubleshooting, and v1.2 feature docs</name>
  <files>README.md</files>
  <action>
Restructure README.md to follow modern documentation standards. Keep all existing accurate content (installation steps, prerequisites, command table, security section) but reorganize and expand.

**Add Architecture section (after Installation, before Usage):**
- ASCII diagram showing: Telegram -> n8n main workflow -> 7 sub-workflows -> docker-socket-proxy -> Docker
- Brief explanation: main workflow handles auth/routing, sub-workflows handle domain logic
- Link to DEPLOY-SUBWORKFLOWS.md for detailed contracts and node analysis
- Mention the 166-node main workflow + 7 sub-workflows totaling ~120 additional nodes

**Separate Configuration section (after Installation):**
- Move environment variable explanation out of installation steps into dedicated section
- Document TELEGRAM_BOT_TOKEN (both credential AND env var, explain why)
- Document User ID (hardcoded in IF nodes, how to change)
- Document docker-socket-proxy allowed operations (CONTAINERS=1, POST=1, dangerous ops blocked)
- Keep installation steps linear and action-only (do X, do Y) without configuration explanation

**Expand Usage section with v1.2 features:**
- Add "Inline Keyboard" subsection explaining the interactive UI workflow:
  - `/status` opens container list with pagination (6 per page)
  - Click container for submenu (start/stop/restart/update/logs)
  - "Batch" button to enter batch selection mode
  - Select/deselect containers with checkmarks, then "Stop Selected"/"Restart Selected"
  - "Update All :latest" button updates all containers with :latest tag
- Add "Batch Operations" subsection:
  - Text: `update all` command sends confirmation, then updates all :latest containers
  - Keyboard: batch selection via toggle buttons, with "Update All :latest" shortcut
  - Infrastructure containers (n8n, socket-proxy) are excluded from batch updates
  - Progress messages show per-container update status
- Keep existing command table as-is (already accurate from Phase 12)

**Add Troubleshooting section (before License):**
- "Workflow not found" errors: Verify sub-workflow IDs match, ensure sub-workflows are Active
- "Cannot connect to Docker": Check docker-socket-proxy is running and on same network
- Bot not responding: Check main workflow is Active, verify Telegram credential
- Unraid shows "apply update" badge: Expected behavior, one-click fix (link to Known Limitations in DEPLOY-SUBWORKFLOWS.md)
- Batch operations not working: Check all 8 workflows imported and active

**Target: ~200-250 lines** (up from ~165). Do NOT exceed 300 lines per research guidance.
  </action>
  <verify>
Verify the README structure:
- grep -c "## Architecture" README.md returns 1
- grep -c "## Configuration" README.md returns 1
- grep -c "## Troubleshooting" README.md returns 1
- grep -c "Update All" README.md returns at least 2 (command table + inline keyboard docs)
- grep -c "Batch" README.md returns at least 2
- grep -c "DEPLOYMENT_GUIDE" README.md returns 0 (link removed)
- grep -c "DEPLOY-SUBWORKFLOWS" README.md returns at least 1
- wc -l README.md shows between 200-300 lines
  </verify>
  <done>README.md has dedicated Architecture, Configuration, and Troubleshooting sections. Batch selection workflow and inline keyboard Update All button are documented. No link to removed DEPLOYMENT_GUIDE.md. Total length between 200-300 lines.</done>
</task>

<task type="auto">
  <name>Task 2: Remove outdated DEPLOYMENT_GUIDE.md and update cross-references</name>
  <files>DEPLOYMENT_GUIDE.md, DEPLOY-SUBWORKFLOWS.md</files>
  <action>
**Remove DEPLOYMENT_GUIDE.md:**
- `git rm DEPLOYMENT_GUIDE.md` — this file is outdated (Phase 10-05, references 3 sub-workflows and 199 nodes, now 7 sub-workflows and 166 nodes)
- DEPLOY-SUBWORKFLOWS.md (725 lines, current) fully supersedes it with all sub-workflow contracts, IDs, and architecture

**Update cross-references in DEPLOY-SUBWORKFLOWS.md:**
- Check for any references to DEPLOYMENT_GUIDE.md and remove/update them
- Verify no other files reference DEPLOYMENT_GUIDE.md (grep the repo)

**Verify DEPLOY-SUBWORKFLOWS.md accuracy:**
- Confirm sub-workflow count is 7 (should already be correct per Phase 12 updates)
- Confirm main workflow node count says 166 or 168 (should already be correct)
- Do NOT make content changes to DEPLOY-SUBWORKFLOWS.md unless fixing broken cross-references

Note: README.md link update is handled in Task 1 (README already points to DEPLOY-SUBWORKFLOWS.md as of Phase 12, but verify and remove any DEPLOYMENT_GUIDE.md references).
  </action>
  <verify>
- DEPLOYMENT_GUIDE.md does not exist: `! test -f DEPLOYMENT_GUIDE.md`
- No references to DEPLOYMENT_GUIDE in any tracked file: `git grep -l "DEPLOYMENT_GUIDE" -- '*.md'` returns empty
- DEPLOY-SUBWORKFLOWS.md still exists and is unchanged (or only cross-ref fixes)
  </verify>
  <done>DEPLOYMENT_GUIDE.md is removed from the repository. No markdown file references the removed file. DEPLOY-SUBWORKFLOWS.md remains the single comprehensive technical reference.</done>
</task>

</tasks>

<verification>
Overall phase verification:
1. README.md structure: Architecture, Configuration, Troubleshooting sections exist
2. All v1.2 features documented: update all (text + keyboard), batch selection, inline keyboard workflow
3. No broken cross-references between documentation files
4. DEPLOYMENT_GUIDE.md removed, DEPLOY-SUBWORKFLOWS.md is sole technical reference
5. README between 200-300 lines (comprehensive but not over-documented)
6. Setup instructions remain linear and actionable for clean install
</verification>

<success_criteria>
1. README documents docker-socket-proxy architecture in dedicated Architecture section
2. README documents all v1.2 features (update all text + keyboard, batch selection, inline keyboard)
3. README has dedicated Configuration section (separated from installation)
4. README has Troubleshooting section covering 5 common issues
5. DEPLOYMENT_GUIDE.md removed (outdated, superseded)
6. All documentation cross-references valid
7. Setup instructions verified accurate (no references to removed files)
</success_criteria>

<output>
After completion, create `.planning/phases/13-documentation-overhaul/13-01-SUMMARY.md`
</output>