[odehsamuel]

Summary

Resolves #1006
Resolves #1008

This PR improves documentation accessibility and navigation across the repository by:

1. Ensuring every fenced code block declares an explicit language annotation (e.g., text, bash) for syntax highlighting and screen reader semantics (Fix the docs so code blocks declare their language for syntax highlighting #1006).
2. Ensuring consistent heading hierarchy across all documentation with exactly one h1 per file, no skipped levels, and documenting the hierarchy conventions in CONTRIBUTING.md (Ensure the docs use one consistent heading level per section with no skipped levels #1008).

Key Changes

1. Code Block Language Annotations (Fix the docs so code blocks declare their language for syntax highlighting #1006):

   • Annotated all unannotated code blocks across the documentation with appropriate language tags:
     • ASCII architecture & flow diagrams: tagged text in contracts/README.md, docs/CONTRACTS.md, and docs/SECURITY_AUDIT_CHECKLIST.md.
     • Directory tree in docs/COMPREHENSIVE_API_DOCS.md: tagged text.
     • Communication and maintenance templates in docs/COMMUNICATION_TEMPLATES.md: tagged text.
     • Command-line flags description in docs/DEPLOYMENT_CONFIGURATION.md: tagged text.
     • Event topic tuples & correlation schema in docs/EVENTS.md: tagged text.
     • Fee resolution and split calculation formulas in docs/FEES.md: tagged text.
     • Environment variable configuration in docs/OPERATIONAL_RUNBOOK.md: tagged bash.
     • Terminal output transcript for make deny and make audit in docs/STORAGE.md: tagged text.
     • Video chapter timestamps in docs/videos/commission-flow-walkthrough.md, docs/videos/dispute-resolution-walkthrough.md, and docs/videos/escrow-contract-walkthrough.md: tagged text.
     • Report template generator in scripts/verify_deployment.sh: tagged output blocks with text.
   • Verified that doc comments across contracts continue to use ignore / no_run / text conventions so that cargo test --doc remains unaffected.
   • Preserved all code contents inside blocks without reformatting.

2. Heading Level Consistency & Documentation Standards (Ensure the docs use one consistent heading level per section with no skipped levels #1008):

   • Audited all 62 markdown files in the repository: confirmed exactly one h1 per file and zero skipped heading levels (e.g., no jumps from h1 directly to h3).
   • Documented the heading hierarchy and code block language annotation conventions in CONTRIBUTING.md under a new ## Documentation Standards section.
   • Verified that document generation templates (in scripts/verify_deployment.sh) preserve heading hierarchy without skipping levels.

Acceptance Criteria Checklist

• Every fenced code block has a language annotation
• Indented diagram block in docs/architecture.md is converted to a tagged fence
• Illustrative Rust blocks are marked ignore or no_run and are not compiled as doctests
• Terminal output blocks are tagged text
• The audit covers README.md, docs/, CONTRIBUTING.md, SDK readmes, and contract rustdoc
• Code inside the blocks is unchanged
• Every markdown file has exactly one h1
• No heading level is skipped anywhere in the repository
• README.md's heading hierarchy is clean with a single h1 and no skipped levels
• The hierarchy convention is documented in CONTRIBUTING.md
• Generated documents emit correct heading structure and tagged fences

[drips-wave]

@odehsamuel Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits