diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index 9e519ac..64dc2fe 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -154,10 +154,10 @@ Plans:
**Requirements:** DEBT-01
-**Plans:** 0 plans
+**Plans:** 1 plan
Plans:
-- [ ] TBD (run /gsd:plan-phase 13 to break down)
+- [ ] 13-01-PLAN.md — README overhaul (architecture, configuration, troubleshooting, v1.2 features) + remove outdated DEPLOYMENT_GUIDE.md
**Success Criteria:**
1. README documents docker-socket-proxy architecture (not direct socket mount)
diff --git a/.planning/phases/13-documentation-overhaul/13-01-PLAN.md b/.planning/phases/13-documentation-overhaul/13-01-PLAN.md
new file mode 100644
index 0000000..b1b5357
--- /dev/null
+++ b/.planning/phases/13-documentation-overhaul/13-01-PLAN.md
@@ -0,0 +1,167 @@
+---
+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"
+---
+
+
+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.
+
+
+
+@/home/luc/.claude/get-shit-done/workflows/execute-plan.md
+@/home/luc/.claude/get-shit-done/templates/summary.md
+
+
+
+@.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
+
+
+
+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)
+
+
+