docs-master

<success_criteria>

• Docs are accurate and verified against source code
• docs/index.md exists and lists every doc file in docs/
• README.md updated with links and references to new/changed docs
• Follows existing project documentation style
• Code examples are correct
• No existing documentation silently removed </success_criteria>