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

phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	must_haves
13-documentation-overhaul	01	execute	1		README.md DEPLOYMENT_GUIDE.md DEPLOY-SUBWORKFLOWS.md	true	truths artifacts key_links 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) path provides contains README.md Complete user-facing documentation with architecture, configuration, and troubleshooting sections ## Architecture path provides DEPLOY-SUBWORKFLOWS.md Updated cross-references (no link to DEPLOYMENT_GUIDE.md) from to via pattern README.md DEPLOY-SUBWORKFLOWS.md markdown link DEPLOY-SUBWORKFLOWS.md

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.

<execution_context> @/home/luc/.claude/get-shit-done/workflows/execute-plan.md @/home/luc/.claude/get-shit-done/templates/summary.md </execution_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 Task 1: Overhaul README with architecture, configuration, troubleshooting, and v1.2 feature docs README.md 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. 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 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.

Task 2: Remove outdated DEPLOYMENT_GUIDE.md and update cross-references DEPLOYMENT_GUIDE.md, DEPLOY-SUBWORKFLOWS.md **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).

• 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) DEPLOYMENT_GUIDE.md is removed from the repository. No markdown file references the removed file. DEPLOY-SUBWORKFLOWS.md remains the single comprehensive technical reference.

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

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

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