Lucas Berger
168 lines
8.4 KiB
Markdown
168 lines
8.4 KiB
Markdown
---
|
|
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>
|