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)

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

1.2 Duplication (QR)

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

1.3 Visual / search (ER – Critical)

• Network Topology Diagram: Added to NETWORK_ARCHITECTURE (Mermaid: topology + VLAN + Proxmox cluster) — DONE 2026-01-31
• VLAN Architecture Diagram: Added to NETWORK_ARCHITECTURE (Mermaid: selected VLANs) — DONE 2026-01-31
• Cloudflare Routing Flow Diagram: Added to CLOUDFLARE_TUNNEL_ROUTING_ARCHITECTURE (Mermaid sequence) — DONE 2026-01-31
• 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)

• 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
• MASTER_INDEX directory tree: Optionally expand or label 02-architecture/ and 04-configuration/ as "(selected)" (tree is subset). — Deferred: optional; current tree sufficient
• docs/README.md directory tree: Add 00-meta/; change finalize-token.md to FINALIZE_TOKEN.md in 04-configuration — DONE 2026-01-31
• 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)

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

2.3 Inconsistencies (QR)

• 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).
• 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.
• 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)

• Consolidate Cloudflare routing: CLOUDFLARE_ROUTING_MASTER designated authoritative; CLOUDFLARE_TUNNEL_ROUTING_ARCHITECTURE and CENTRAL_NGINX_ROUTING_SETUP reference it — DONE 2026-01-31
• Add missing cross-references: PHYSICAL_HARDWARE_INVENTORY and DOMAIN_STRUCTURE referenced in NETWORK_ARCHITECTURE; ORCHESTRATION_DEPLOYMENT_GUIDE already had refs — DONE 2026-01-31
• 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)

• 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
• Configuration Templates: Add templates (e.g. ER605, Proxmox network, Cloudflare tunnel, Besu node) with placeholders. — Done: docs/04-configuration/CONFIGURATION_TEMPLATES.md
• 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)
• Troubleshooting Flow Diagram: Add "Is service down?" → check logs → network → etc. — Done: docs/09-troubleshooting/TROUBLESHOOTING_FAQ.md (Mermaid flowchart)
• Proxmox Cluster Architecture Diagram: Add diagram (nodes, storage, bridges, VM/container distribution). — Done: docs/02-architecture/NETWORK_ARCHITECTURE.md (Proxmox cluster Mermaid)
• 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
• 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)

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

3.2 Inconsistencies and gaps (QR)

• IP address references: IP reference format documented in NETWORK_CONFIGURATION_MASTER; link to VMID_ALLOCATION_FINAL — DONE 2026-01-31
• Cross-reference format: TROUBLESHOOTING_FAQ Related section paths fixed to correct dirs (03-deployment, 02-architecture, etc.) — DONE 2026-01-31
• DOMAIN_STRUCTURE.md: Referenced in NETWORK_ARCHITECTURE (Related); 05-network CLOUDFLARE_TUNNEL already had DOMAIN_STRUCTURE in Related — DONE 2026-01-31
• 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)

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

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

4.2 Gaps (QR)

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

• Glossary: UDM Pro and NPMplus added to 11-references/GLOSSARY.md; VLAN, NAT, QBFT, CCIP, VMID already present — DONE 2026-01-31
• FAQ expansion: Four new questions in TROUBLESHOOTING_FAQ (VMID lookup, public vs private RPC, Cloudflare tunnel, storage) — DONE 2026-01-31
• Quick Reference Cards: Print-friendly or PDF version of key docs (optional). — DONE: DOCUMENTATION_STYLE_GUIDE "Optional: Accessibility and output formats" (print/PDF)
• Mobile-friendly formatting: Ensure key docs render well on small screens. — DONE: Style guide guidelines (mobile-friendly)
• Dark mode: Optional dark mode styling for rendered docs. — DONE: Style guide (optional dark mode)
• Screenshots: Add screenshots where they materially help (e.g. UI, dashboards). — DONE: Style guide "Optional: Screenshots and Images" (when/where/naming)
• Service state machines: Optional state diagrams for key services. — DONE: DOCUMENT_RELATIONSHIP_MAP.md has example (container lifecycle); style guide references stateDiagram-v2
• ASCII art diagrams: Simple diagrams where Mermaid not used. — DONE: Style guide + DOCUMENT_RELATIONSHIP_MAP ASCII summary
• Visual table of contents: Priority/status indicators in TOC (optional). — DONE: Style guide "Optional: Diagrams and Visual Aids" (visual TOC)
• 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 – Full review methodology and findings
• DOCUMENTATION_QUALITY_REVIEW.md – Duplicates, gaps, inconsistencies
• DOCUMENTATION_ENHANCEMENTS_RECOMMENDATIONS.md – Content, visual, organization, usability
• DOCUMENTATION_STYLE_GUIDE.md – Standards for headers, naming, markdown
• DOCUMENTATION_FIXES_COMPLETE.md – Previously completed fixes
• ../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.