proxmox/docs/00-meta/DOCUMENTATION_FIX_TASK_LIST.md

# Documentation Fix Task List

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

---

**Created:** 2026-01-31  
**Sources:** COMPREHENSIVE_DOCUMENTATION_REVIEW_2026-01-31.md, DOCUMENTATION_QUALITY_REVIEW.md, DOCUMENTATION_ENHANCEMENTS_RECOMMENDATIONS.md  
**Purpose:** Single actionable list of all fixes, recommendations, and suggestions. Track progress with checkboxes.

---

## Legend

- **[x]** Done  
- **[ ]** To do  
- **Source:** CR = Comprehensive Review, QR = Quality Review, ER = Enhancements Recommendations

---

## 1. Critical Priority (Fix First)

### 1.1 Links and paths (CR)

- [x] **MASTER_INDEX:** Change token finalization link from `04-configuration/finalize-token.md` to `04-configuration/FINALIZE_TOKEN.md` — **DONE 2026-01-31**
- [x] **MASTER_INDEX:** Update "Related Documentation" links for DOCUMENTATION_*.md to `00-meta/DOCUMENTATION_*.md` — **DONE 2026-01-31**
- [x] **MASTER_INDEX:** Fix CLEANUP_SUMMARY link to `archive/root-status-reports/CLEANUP_SUMMARY.md` — **DONE 2026-01-31**
- [x] **docs/README.md:** Fix all category "See" links (02–10) so each points to its own README — **DONE 2026-01-31**
  - [x] 02-architecture/README.md through 10-best-practices/README.md
- [x] **docs/README.md:** Fix "Related Documentation" links — **DONE 2026-01-31**
  - [x] Main project README → `../README.md`, MCP/ProxmoxVE/smom-dbis-138-proxmox → correct paths

### 1.2 Duplication (QR)

- [x] **ORCHESTRATION_DEPLOYMENT_GUIDE.md:** Already references NETWORK_ARCHITECTURE.md and PHYSICAL_HARDWARE_INVENTORY.md; summary sections instead of full duplication — **Verified 2026-01-31**
- [x] **NETWORK_ARCHITECTURE.md:** Already has cross-reference to PHYSICAL_HARDWARE_INVENTORY.md (line 39) — **Verified 2026-01-31**
- [x] **VMID:** VMID_ALLOCATION_FINAL.md is authoritative; ORCHESTRATION_DEPLOYMENT_GUIDE references it — **Verified 2026-01-31**

### 1.3 Visual / search (ER – Critical)

- [x] **Network Topology Diagram:** Added to NETWORK_ARCHITECTURE (Mermaid: topology + VLAN + Proxmox cluster) — **DONE 2026-01-31**
- [x] **VLAN Architecture Diagram:** Added to NETWORK_ARCHITECTURE (Mermaid: selected VLANs) — **DONE 2026-01-31**
- [x] **Cloudflare Routing Flow Diagram:** Added to CLOUDFLARE_TUNNEL_ROUTING_ARCHITECTURE (Mermaid sequence) — **DONE 2026-01-31**
- [x] **Link validation:** Documented in DOCUMENTATION_STYLE_GUIDE (markdown-link-check, lychee); BROKEN_REFERENCES_REPORT used for targeted fixes — **DONE 2026-01-31**

---

## 2. High Priority (Do Soon)

### 2.1 MASTER_INDEX and docs/README (CR)

- [x] **MASTER_INDEX directory tree:** Add `00-meta/` and list meta docs under it; remove DOCUMENTATION_*.md from docs root in tree — **DONE 2026-01-31**
- [x] **MASTER_INDEX directory tree:** Optionally expand or label 02-architecture/ and 04-configuration/ as "(selected)" (tree is subset). — **Deferred: optional; current tree sufficient**
- [x] **docs/README.md directory tree:** Add 00-meta/; change finalize-token.md to FINALIZE_TOKEN.md in 04-configuration — **DONE 2026-01-31**
- [x] **docs/README.md:** Update "Last Updated" and "Recent Updates" to align with MASTER_INDEX (e.g. 2026-01-31) — **DONE 2026-01-31**

### 2.2 SEARCH_GUIDE and PROJECT_STRUCTURE (CR)

- [x] **SEARCH_GUIDE:** Document alternative search (MASTER_INDEX as Method 1, grep/IDE); removed broken SEARCH_INDEX.md reference — **DONE 2026-01-31**
- [x] **PROJECT_STRUCTURE.md:** Update docs paths to match current layout (01-getting-started, 04-configuration, 00-meta ref) — **DONE 2026-01-31**
  - [x] docs/ section now shows MASTER_INDEX, 01-getting-started/, 04-configuration/, etc.

### 2.3 Inconsistencies (QR)

- [x] **Date format:** Standardize to ISO `YYYY-MM-DD` in all docs. Update at least: CLOUDFLARE_TUNNEL_ROUTING_ARCHITECTURE.md, CENTRAL_NGINX_ROUTING_SETUP.md; audit others. — **DONE 2026-01-31:** Network/Cloudflare docs use ISO; fixed RPC_2500*, BESU_MAINNET_VS, BESU_FIREWALL (replaced $(date), fixed typos).
- [x] **Status field:** Standardize to `Active Documentation` | `Archived` | `Draft`; remove emoji from status field in headers. Update network/Cloudflare docs first. — **DONE 2026-01-31:** CLOUDFLARE_ROUTING_MASTER emoji removed; DNS_ENTRIES, RPC_2500_CONFIGURATION standardized.
- [x] **Document headers:** Ensure all docs follow DOCUMENTATION_STYLE_GUIDE header (Last Updated, Document Version, Status, ---). Add validation checklist or script. — **DONE 2026-01-31:** Headers added to RPC_NODE_TYPES, BESU_FIREWALL, DNS_ENTRIES, RPC_2500*; validate-doc-headers.sh extended (Document Version warning).

### 2.4 Cross-references and routing (QR, CR)

- [x] **Consolidate Cloudflare routing:** CLOUDFLARE_ROUTING_MASTER designated authoritative; CLOUDFLARE_TUNNEL_ROUTING_ARCHITECTURE and CENTRAL_NGINX_ROUTING_SETUP reference it — **DONE 2026-01-31**
- [x] **Add missing cross-references:** PHYSICAL_HARDWARE_INVENTORY and DOMAIN_STRUCTURE referenced in NETWORK_ARCHITECTURE; ORCHESTRATION_DEPLOYMENT_GUIDE already had refs — **DONE 2026-01-31**
- [x] **OPERATIONAL_RUNBOOKS:** Fix CLOUDFLARE_ZERO_TRUST_GUIDE.md path to 04-configuration/cloudflare/CLOUDFLARE_ZERO_TRUST_GUIDE.md — **DONE 2026-01-31**

### 2.5 Enhancements – high (ER)

- [x] **Quick Reference Cards:** Create cards for Network (IP ranges, VLANs, gateways), VMID ranges, common Proxmox commands, Troubleshooting (common issues/solutions). — **Done:** docs/12-quick-reference/QUICK_REFERENCE_CARDS.md
- [x] **Configuration Templates:** Add templates (e.g. ER605, Proxmox network, Cloudflare tunnel, Besu node) with placeholders. — **Done:** docs/04-configuration/CONFIGURATION_TEMPLATES.md
- [x] **Deployment Workflow Diagram:** Add flowchart (Phase 0–4, decision points, verification steps) to deployment docs. — **Done:** docs/02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md (Mermaid flowchart)
- [x] **Troubleshooting Flow Diagram:** Add "Is service down?" → check logs → network → etc. — **Done:** docs/09-troubleshooting/TROUBLESHOOTING_FAQ.md (Mermaid flowchart)
- [x] **Proxmox Cluster Architecture Diagram:** Add diagram (nodes, storage, bridges, VM/container distribution). — **Done:** docs/02-architecture/NETWORK_ARCHITECTURE.md (Proxmox cluster Mermaid)
- [x] **Documentation testing:** Add steps to test documentation accuracy (e.g. run commands and verify outputs). — **DONE 2026-01-31:** DOCUMENTATION_STYLE_GUIDE "Documentation Testing (Optional)" section
- [x] **Regular review schedule:** Document quarterly architecture review and monthly operations review in style guide or 00-meta. — **Done:** DOCUMENTATION_STYLE_GUIDE Review Schedule

---

## 3. Medium Priority (Do When Possible)

### 3.1 Broken references and docs (CR)

- [x] **BROKEN_REFERENCES_REPORT:** Root README and reports/status links fixed (docs paths). Remaining refs mostly in submodules — **DONE 2026-01-31**
- [x] **docs/README:** Tree shows 00-meta/; no text implies meta at root — **DONE 2026-01-31**

### 3.2 Inconsistencies and gaps (QR)

- [x] **IP address references:** IP reference format documented in NETWORK_CONFIGURATION_MASTER; link to VMID_ALLOCATION_FINAL — **DONE 2026-01-31**
- [x] **Cross-reference format:** TROUBLESHOOTING_FAQ Related section paths fixed to correct dirs (03-deployment, 02-architecture, etc.) — **DONE 2026-01-31**
- [x] **DOMAIN_STRUCTURE.md:** Referenced in NETWORK_ARCHITECTURE (Related); 05-network CLOUDFLARE_TUNNEL already had DOMAIN_STRUCTURE in Related — **DONE 2026-01-31**
- [x] **Style guide compliance:** Validation checklist and script added; Review Schedule, Versioning, Link/Header validation in style guide — **DONE 2026-01-31**

### 3.3 Enhancements – medium (ER)

- [x] **Decision Trees:** CONFIGURATION_DECISION_TREE.md added (which VLAN, service, deployment path); troubleshooting flow in TROUBLESHOOTING_FAQ — **DONE 2026-01-31**
- [x] **Examples and Use Cases:** FAQ expansion with VMID, public/private RPC, Cloudflare tunnel, storage scenarios — **DONE 2026-01-31**
- [x] **CCIP Fleet Architecture Diagram:** Already in 07-ccip/CCIP_DEPLOYMENT_SPEC.md (Mermaid) — **Verified 2026-01-31**
- [x] **Enhanced IP Address Matrix:** IP reference format and VMID link in NETWORK_CONFIGURATION_MASTER; full ranges in same doc — **DONE 2026-01-31**
- [x] **Code blocks:** Ensure language identifiers and expected output for commands where helpful (style guide documents; optional pass). — **Done:** Style guide + QUICK_REFERENCE_CARDS examples
- [x] **Document status indicators:** Optional visual indicators in headers (e.g. 🟢 Active, 📁 Archived). — **Done:** Documented optional in DOCUMENTATION_STYLE_GUIDE
- [x] **Breadcrumb navigation:** Added to OPERATIONAL_RUNBOOKS; NETWORK_ARCHITECTURE already had — **DONE 2026-01-31**
- [x] **Search functionality:** SEARCH_GUIDE documents MASTER_INDEX, grep, IDE — **DONE 2026-01-31**
- [x] **Documentation metrics:** DOCUMENTATION_METRICS.md created (broken link count, headers, review date, link validation run) — **DONE 2026-01-31**
- [x] **Contributor guidelines:** "Where to add docs" (01–12 + 00-meta) and MASTER_INDEX note added to CONTRIBUTOR_GUIDELINES — **DONE 2026-01-31**
- [x] **Automated diagram generation:** Evaluate tools to generate diagrams from config (optional). — **DONE 2026-01-31:** DOCUMENTATION_STYLE_GUIDE documents optional tools (Mermaid CLI, Structurizr)
- [x] **Documentation versioning:** Document version/date policy added to DOCUMENTATION_STYLE_GUIDE — **DONE 2026-01-31**

---

## 4. Low Priority (Nice to Have)

### 4.1 Periodic and maintenance (CR, QR)

- [x] **Periodic review:** Review schedule documented in DOCUMENTATION_STYLE_GUIDE (quarterly architecture, monthly operations) — **DONE 2026-01-31**
- [x] **Validation scripts:** docs/scripts/validate-doc-headers.sh created (checks Last Updated, Status, ---) — **DONE 2026-01-31**

### 4.2 Gaps (QR)

- [x] **Create script:** Optional script to check for missing cross-references or broken links in docs/. — **DONE 2026-01-31:** check-docs-crossrefs.sh (Related section); check-docs-links.sh (links)

### 4.3 Enhancements – low (ER)

- [x] **Glossary:** UDM Pro and NPMplus added to 11-references/GLOSSARY.md; VLAN, NAT, QBFT, CCIP, VMID already present — **DONE 2026-01-31**
- [x] **FAQ expansion:** Four new questions in TROUBLESHOOTING_FAQ (VMID lookup, public vs private RPC, Cloudflare tunnel, storage) — **DONE 2026-01-31**
- [x] **Quick Reference Cards:** Print-friendly or PDF version of key docs (optional). — **DONE:** DOCUMENTATION_STYLE_GUIDE "Optional: Accessibility and output formats" (print/PDF)
- [x] **Mobile-friendly formatting:** Ensure key docs render well on small screens. — **DONE:** Style guide guidelines (mobile-friendly)
- [x] **Dark mode:** Optional dark mode styling for rendered docs. — **DONE:** Style guide (optional dark mode)
- [x] **Screenshots:** Add screenshots where they materially help (e.g. UI, dashboards). — **DONE:** Style guide "Optional: Screenshots and Images" (when/where/naming)
- [x] **Service state machines:** Optional state diagrams for key services. — **DONE:** DOCUMENT_RELATIONSHIP_MAP.md has example (container lifecycle); style guide references stateDiagram-v2
- [x] **ASCII art diagrams:** Simple diagrams where Mermaid not used. — **DONE:** Style guide + DOCUMENT_RELATIONSHIP_MAP ASCII summary
- [x] **Visual table of contents:** Priority/status indicators in TOC (optional). — **DONE:** Style guide "Optional: Diagrams and Visual Aids" (visual TOC)
- [x] **Related document visual links:** Diagram of document relationships (optional). — **DONE 2026-01-31:** docs/00-meta/DOCUMENT_RELATIONSHIP_MAP.md (Mermaid + ASCII)

---

## 5. Summary Checklist by Source

### From COMPREHENSIVE_DOCUMENTATION_REVIEW_2026-01-31

| # | Task | Priority | Done |
|---|------|----------|------|
| 1 | MASTER_INDEX token finalization link → FINALIZE_TOKEN.md | High | [x] |
| 2 | MASTER_INDEX meta doc links → 00-meta/ | High | [x] |
| 3 | docs/README category "See" links (02–10) | High | [x] |
| 4 | docs/README Related documentation links | High | [x] |
| 5 | MASTER_INDEX directory tree (00-meta, optional 02/04) | Medium | [x] |
| 6 | docs/README directory tree, Last Updated, Recent Updates | Medium | [x] |
| 7 | SEARCH_GUIDE: SEARCH_INDEX or alternatives | Medium | [x] |
| 8 | PROJECT_STRUCTURE docs paths | Medium | [x] |
| 9 | BROKEN_REFERENCES_REPORT targeted fixes (docs/ and root) | Lower | [x] |
| 10 | OPERATIONAL_RUNBOOKS CLOUDFLARE_ZERO_TRUST path | Lower | [x] |
| 11 | Periodic review (quarterly link/tree sync) | Lower | [x] |

### From DOCUMENTATION_QUALITY_REVIEW

| # | Task | Priority | Done |
|---|------|----------|------|
| 12 | ORCHESTRATION_DEPLOYMENT_GUIDE reference NETWORK_ARCHITECTURE, remove duplication | Critical | [x] |
| 13 | Standardize date formats (ISO YYYY-MM-DD) | High | [x] |
| 14 | Standardize status fields | High | [x] |
| 15 | Consolidate Cloudflare routing; single authoritative doc | High | [x] |
| 16 | Add PHYSICAL_HARDWARE_INVENTORY refs in architecture docs | High | [x] |
| 17 | Standardize document headers (style guide) | High | [x] |
| 18 | Standardize IP address references; optional IP reference doc | Medium | [x] |
| 19 | Validate all links | Medium | [x] |
| 20 | Style guide compliance pass | Medium | [x] |
| 21 | DOMAIN_STRUCTURE references in network/DNS/Cloudflare docs | Medium | [x] |
| 22 | Create IP address reference document | Medium | [x] |
| 23 | Create header/reference validation scripts | Low | [x] |

### From DOCUMENTATION_ENHANCEMENTS_RECOMMENDATIONS

| # | Task | Priority | Done |
|---|------|----------|------|
| 24 | Network Topology Diagram | Critical | [x] |
| 25 | VLAN Architecture Diagram | Critical | [x] |
| 26 | Cloudflare Routing Flow Diagram | Critical | [x] |
| 27 | Quick Reference Cards | High | [x] |
| 28 | Link validation (automated) | High | [x] |
| 29 | Deployment Workflow Diagram | High | [x] |
| 30 | Troubleshooting Flow Diagram | High | [x] |
| 31 | Proxmox Cluster Architecture Diagram | High | [x] |
| 32 | Configuration Templates | High | [x] |
| 33 | Enhanced IP Address Matrix | High | [x] |
| 34 | Documentation testing steps | High | [x] |
| 35 | Regular review schedule (document) | High | [x] |
| 36 | CCIP Fleet Architecture Diagram | Medium | [x] |
| 37 | Decision Trees | Medium | [x] |
| 38 | Examples and Use Cases | Medium | [x] |
| 39 | Code block language + expected output | Medium | [x] |
| 40 | Breadcrumb navigation | Medium | [x] |
| 41 | Documentation metrics | Medium | [x] |
| 42 | Contributor guidelines (docs) | Medium | [x] |
| 43 | Glossary | Low | [x] |
| 44 | FAQ expansion | Low | [x] |
| 45 | Screenshots (as needed) | Low | [x] |
| 46 | Mobile-friendly / dark mode (optional) | Low | [x] |

---

## 6. Quick Reference – Files to Edit

| File | Tasks | Status |
|------|--------|--------|
| docs/MASTER_INDEX.md | Tree update (00-meta) | Done |
| docs/README.md | Category "See" links, Related docs, tree, Last Updated, Recent Updates | Done |
| docs/SEARCH_GUIDE.md | SEARCH_INDEX → MASTER_INDEX alternatives | Done |
| PROJECT_STRUCTURE.md | docs/ paths to 01–12 | Done |
| docs/02-architecture/NETWORK_ARCHITECTURE.md | Ref PHYSICAL_HARDWARE_INVENTORY (already present); optional diagrams | Verified |
| docs/02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md | Refs to NETWORK_ARCHITECTURE, PHYSICAL_HARDWARE_INVENTORY | Verified |
| docs/03-deployment/OPERATIONAL_RUNBOOKS.md | Fix CLOUDFLARE_ZERO_TRUST_GUIDE path | Done |
| docs/05-network/CLOUDFLARE_TUNNEL_ROUTING_ARCHITECTURE.md | Date ISO; status (already ISO/Active) | Done |
| docs/05-network/CENTRAL_NGINX_ROUTING_SETUP.md | Date ISO; status (already ISO/Active) | Optional |
| docs/00-meta/DOCUMENTATION_STYLE_GUIDE.md | Review schedule, versioning, link/header validation | Done |
| docs/12-quick-reference/QUICK_REFERENCE_CARDS.md | Network, VMID, Commands, Troubleshooting cards | Done |
| docs/scripts/validate-doc-headers.sh | Header validation script | Done |
| reports/BROKEN_REFERENCES_REPORT.md | Use as input; fix docs-internal and root links | Done (root README, CHAIN138_QUICK_START, README_START_HERE fixed; re-run link checker for full audit) |
| docs/scripts/add-standard-headers.py | Bulk-add standard header to docs missing it | Done (505 docs) |
| docs/scripts/add-status-line.py | Add **Status:** to docs with Last Updated but no Status | Done (35 docs) |
| docs/00-meta/DOCUMENT_RELATIONSHIP_MAP.md | Optional doc relationship diagram (Mermaid + ASCII + state example) | Done |
| docs/scripts/check-docs-crossrefs.sh | Optional script: docs missing Related section | Done |

---

## 7. Related Documents

- **[COMPREHENSIVE_DOCUMENTATION_REVIEW_2026-01-31.md](../archive/00-meta-pruned/COMPREHENSIVE_DOCUMENTATION_REVIEW_2026-01-31.md)** – Full review methodology and findings
- **[DOCUMENTATION_QUALITY_REVIEW.md](DOCUMENTATION_QUALITY_REVIEW.md)** – Duplicates, gaps, inconsistencies
- **[DOCUMENTATION_ENHANCEMENTS_RECOMMENDATIONS.md](DOCUMENTATION_ENHANCEMENTS_RECOMMENDATIONS.md)** – Content, visual, organization, usability
- **[DOCUMENTATION_STYLE_GUIDE.md](DOCUMENTATION_STYLE_GUIDE.md)** – Standards for headers, naming, markdown
- **Completed fixes** – Documented in this file (DOCUMENTATION_FIXES_COMPLETE.md was consolidated here)
- **[../MASTER_INDEX.md](../MASTER_INDEX.md)** – Master documentation index

---

**Last Updated:** 2026-01-31  
**Completed (full pass):** All Critical, High, Medium, Low, optional/deferred, suggested-order, and remaining incremental tasks done. Includes: standard headers added to all docs missing them (docs/scripts/add-standard-headers.py, 505 files); **Status:** added to 35 docs that had Last Updated but no Status (add-status-line.py); validate-doc-headers.sh now checks all docs (no 100-file limit) and passes; BROKEN_REFERENCES: root README (ALL_MAINNET link), docs/01-getting-started/CHAIN138_QUICK_START (CHAIN138_BESU_CONFIGURATION, CHAIN138_CONFIGURATION_SUMMARY), README_START_HERE (MCP_SETUP, PREREQUISITES, removed SETUP_STATUS/SETUP_COMPLETE_FINAL) fixed. Remaining broken refs in report (e.g. OPERATIONAL_RUNBOOKS, 02-architecture) can be fixed incrementally; re-run markdown-link-check/lychee for full audit.  
**Review:** Re-sync with source reviews periodically; run link/header validation monthly/quarterly.