The platforms documentation had RST formatting issues that affected the
table of contents structure. 📌 A leftover "Default paths" header in the
preamble with no corresponding section content has been removed to clean
up the introduction.

Platform-specific sections (macOS, Windows, Linux/Unix, Android) were
using dashes (`---`) which render as level-2 headers, incorrectly
appearing as main sections in the TOC. ✨ These are now level-3 headers
(using `~~~`) to align them logically with "User directories" and
"Shared directories" subsections they precede.

The result is a cleaner, more intuitive table of contents that better
reflects the actual documentation structure.

The documentation previously mixed learning material, task recipes,
background explanations, and API reference in the same files. A new user
trying to get started would land in `usage.rst` alongside advanced
platform conventions and real-world project examples, making it hard to
follow a clear learning path. Similarly, someone looking for a quick
recipe had to skim past explanatory prose to find the code they needed.

This restructures the docs into the four quadrants of the [Diataxis
framework](https://diataxis.fr/): a step-by-step `tutorial.rst` for
newcomers, a recipe-focused `howto.rst` for practitioners, an
`explanation.rst` gathering all platform conventions and design
rationale, and the existing `api.rst`/`platforms.rst` as pure reference.
The tutorial uses first-person plural and imperative steps with
verifiable output at each stage. The how-to guides are action-first with
minimal explanation, including new recipes for config merging via
`iter_config_paths`, testing with mocks, and environment variable
overrides. Platform convention prose that was duplicated between
`platforms.rst` and `howto.rst` now lives in one place in
`explanation.rst`.

Beyond the restructure, this adds several Sphinx extensions
(`sphinx-copybutton`, `sphinx-design`, `sphinx-sitemap`,
`sphinxcontrib-mermaid`, `sphinxext-opengraph`) and a `docstrfmt`
pre-commit hook for consistent RST and docstring formatting. The ruff
config is adjusted to defer to `docstrfmt` for docstring style (`D213`
ignored, `E501` ignored in favor of formatters). The `api.rst` now
documents the `iter_*` methods and the `AppDirs` backwards-compatibility
alias. The release workflow script is updated to match the new RST
heading style used by `docstrfmt`.