The documentation mixed learning material, task recipes, background explanations, and API reference within the same files. A newcomer landing in usage.rst had to wade through platform conventions and production examples just to find how to call user_data_dir. Someone looking for a quick recipe had to skim past explanatory prose to reach the code. 📚 This made it harder than necessary to find the right information for the task at hand.

This restructures everything into the four quadrants of the Diataxis framework. A proper tutorial.rst walks new users through installation to a working example with verifiable output at each step. howto.rst is stripped to action-first recipes including new ones for config merging via iter_config_paths, mocking in tests, and environment variable overrides. All platform convention prose — macOS ~/Library behavior, Windows WIN_PD_OVERRIDE_* variables, XDG details, Android detection — is consolidated into explanation.rst instead of being scattered across three files. The reference pages (api.rst, platforms.rst) stay austere, with api.rst now surfacing the iter_* methods and the AppDirs backwards-compatibility alias.

This also adds docstrfmt as a pre-commit hook for consistent RST and docstring formatting, along with Sphinx extensions (sphinx-copybutton, sphinx-design, sphinxcontrib-mermaid, sphinxext-opengraph, sphinx-sitemap) that improve the rendered docs. The ruff config is adjusted to defer to docstrfmt for docstring style, and the release workflow script is fixed to produce docstrfmt-compatible changelog entries — it was missing a blank line after section underlines and generating overlines one character too short.