# Story 1.2 Implementation Checklist ## 📋 **Quick Stats** - **Files to Update:** 4 - **Total URL Fixes:** ~16 occurrences - **Estimated Time:** 3-4 hours - **Dependencies:** Story 1.1 must be completed first --- ## ✅ **Pre-Implementation Checklist** - [ ] Story 1.1 is completed and merged - [ ] You have write access to all documentation files - [ ] You have a markdown preview tool ready - [ ] You have a JSON validator ready (https://jsonlint.com/) --- ## 📁 **File Update Checklist** ### 1. README.md (6 occurrences) **Lines to Update:** - [ ] Line 80: Remove `/api/v1/` from production example - [ ] Line 84: Remove `/api/v1/` from staging example - [ ] Line 88: Remove `/api/v1/` from development example - [ ] Line 335: Remove `/api/v1/` from migration example 1 - [ ] Line 348: Remove `/api/v1/` from migration example 2 - [ ] Line 352: Remove `/api/v1/` from migration example 3 **New Sections to Add:** - [ ] Add "Configuration Best Practices" section after Installation Guide - [ ] Add "Migrating from Old Configuration" section - [ ] Update Troubleshooting section with "URL Configuration Issues" **Search Pattern:** ```bash grep -n '"n8n_host".*api/v1' README.md ``` --- ### 2. docs/multi-instance-architecture.md (7 occurrences) **Lines to Update:** - [ ] Line 28: First example - production - [ ] Line 32: First example - staging - [ ] Line 79: Second example - production - [ ] Line 83: Second example - staging - [ ] Line 87: Second example - development - [ ] Line 98: .env fallback example - [ ] Line 107: Migration example **Search Pattern:** ```bash grep -n 'n8n_host.*api/v1\|N8N_HOST.*api/v1' docs/multi-instance-architecture.md ``` --- ### 3. examples/setup_with_claude.md (3 occurrences) **Lines to Update:** - [ ] Line 33: .env configuration example - [ ] Line 51: Claude Desktop config (npm installed) - [ ] Line 81: Claude Desktop config (cloned repo) **Search Pattern:** ```bash grep -n 'N8N_HOST.*api/v1' examples/setup_with_claude.md ``` --- ### 4. CHANGELOG.md (1 new entry) **Task:** - [ ] Add version 0.9.1 entry at the top - [ ] Include bug fix description - [ ] Note backward compatibility - [ ] Credit user bug report - [ ] Document new features (smart URL detection, debug logging) - [ ] List documentation updates **Template:** See full story for complete CHANGELOG entry template --- ## ⚠️ **Files Already Completed** ### ✅ CLAUDE.md - NO ACTION NEEDED - [x] Line 72: Already correct (`"n8n_host": "https://n8n.example.com"`) - [x] Line 321: Already correct (`"N8N_HOST": "https://n8n.example.com"`) - [x] Line 81: Explanatory note already added **Status:** 100% complete before story began --- ## 🔍 **Verification Checklist** ### After Each File Update: - [ ] Run JSON validator on all JSON examples - [ ] Check markdown renders correctly - [ ] Verify no broken links - [ ] Ensure consistent formatting ### Final Verification: ```bash # Should return NO results (all /api/v1 references removed from config examples) grep -r '"n8n_host".*api/v1\|N8N_HOST.*api/v1' README.md docs/ examples/ | grep -v openapi # Validate all JSON examples find . -name "*.md" -exec grep -l "n8n_host" {} \; | xargs -I {} sh -c 'echo "Checking {}" && cat {} | grep -A5 "n8n_host"' # Check markdown links npx markdown-link-check README.md ``` --- ## 📝 **Search & Replace Commands** ### Safe Automated Replacements **For README.md:** ```bash sed -i.bak 's|"n8n_host": "https://n8n.example.com/api/v1/"|"n8n_host": "https://n8n.example.com"|g' README.md sed -i.bak 's|"n8n_host": "https://staging-n8n.example.com/api/v1/"|"n8n_host": "https://staging-n8n.example.com"|g' README.md sed -i.bak 's|"n8n_host": "http://localhost:5678/api/v1/"|"n8n_host": "http://localhost:5678"|g' README.md ``` **For docs/multi-instance-architecture.md:** ```bash sed -i.bak 's|/api/v1/||g' docs/multi-instance-architecture.md # Then manually review and fix any OpenAPI spec references if present ``` **For examples/setup_with_claude.md:** ```bash sed -i.bak 's|N8N_HOST=https://your-n8n-instance.com/api/v1/|N8N_HOST=https://your-n8n-instance.com|g' examples/setup_with_claude.md sed -i.bak 's|"N8N_HOST": "https://your-n8n-instance.com/api/v1/"|"N8N_HOST": "https://your-n8n-instance.com"|g' examples/setup_with_claude.md ``` **⚠️ Warning:** Always create backups and review changes before committing! --- ## 📚 **Content Templates** ### Configuration Best Practices Section Location: README.md, after "Installation Guide" section **Template:** See full story file for complete markdown template Key elements: - ✅ Correct URL examples - ❌ Incorrect URL examples with warnings - Explanation of why it matters - Backward compatibility note - Links to official n8n docs --- ### Migration Guide Section Location: README.md, new section **Template:** See full story file for complete markdown template Key elements: - Option 1: Continue using old format (backward compatible) - Option 2: Update to new format (recommended) - Before/after examples - Step-by-step migration instructions --- ### Troubleshooting Addition Location: README.md, existing Troubleshooting section **Template:** See full story file for complete markdown template Key elements: - Symptom description - Possible causes - 4-step solution process - Debug logging instructions - URL verification commands --- ### CHANGELOG Entry Location: CHANGELOG.md, top of file **Template:** See full story file for complete markdown template Version: **0.9.1** (PATCH release) Sections: - 🐛 Bug Fixes - 📚 Documentation - ✨ Features - 🔧 Technical Changes --- ## ⏱️ **Estimated Time Breakdown** | Task | Time | Notes | |------|------|-------| | README.md updates | 90 min | 6 replacements + 3 new sections | | multi-instance-architecture.md | 30 min | 7 replacements | | setup_with_claude.md | 15 min | 3 replacements | | CHANGELOG.md | 15 min | 1 new entry | | Verification & testing | 45 min | JSON validation, link checking | | Final review | 15 min | Consistency check | | **TOTAL** | **3.5 hrs** | | --- ## 🎯 **Definition of Done** Story 1.2 is complete when: - [x] All 6 URL occurrences in README.md corrected - [x] Configuration Best Practices section added to README.md - [x] Migration Guide section added to README.md - [x] Troubleshooting section updated in README.md - [x] All 7 URL occurrences in multi-instance-architecture.md corrected - [x] All 3 URL occurrences in setup_with_claude.md corrected - [x] CHANGELOG.md updated with version 0.9.1 - [x] All JSON examples validated - [x] All markdown renders correctly - [x] No broken links found - [x] Consistent formatting across all files - [x] Examples align with Story 1.1 code changes - [x] Final verification commands pass with no issues --- ## 🚨 **Common Pitfalls** 1. **Don't touch OpenAPI specs:** `examples/n8n-openapi-markdown.md` should NOT be modified 2. **Watch for localhost:** Remove `/api/v1` from localhost URLs too 3. **Trailing slashes:** Remove both `/api/v1` AND trailing `/` 4. **Version number:** Use 0.9.1 (patch), not 0.10.0 5. **JSON validation:** Always validate JSON after edits --- ## 📞 **Need Help?** - Full story details: `docs/stories/1.2.documentation-updates.CORRECTED.md` - Epic context: `docs/epic-1-url-configuration-fix.md` - Story 1.1 (code): `docs/stories/1.1.url-normalization-implementation.md` --- **Created:** 2025-12-25 **Story:** 1.2 - Documentation Updates **Status:** Blocked - Waiting for Story 1.1