Windows Store Python (MSIX) uses kernel-level filesystem virtualization
that redirects AppData writes to a per-package sandbox location. This
causes confusion when paths returned by platformdirs are passed to
external processes that run outside the sandbox.

The returned logical paths are correct for the calling process, so this
is not something platformdirs should resolve. Added a note explaining
the behavior and the os.path.realpath() workaround for cross-process
path sharing.

Closes #90

Every other directory type (data, config, cache, runtime) has both a
`user_*` and `site_*` variant, but `user_log_dir` had no `site_log_dir`
counterpart. This made it impossible for services and daemons to
determine the system-wide log directory through `platformdirs`. ✨ The
new `site_log_dir` follows each platform's conventions for system-wide
logs, with matching `site_log_path`, `iter_log_dirs`, and
`iter_log_paths`.

Platform paths were chosen to align with each ecosystem's documented
conventions:

- **Linux** — `/var/log/$appname`: per the [Filesystem Hierarchy
Standard
§5.11](https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch05s11.html),
`/var/log` is the standard location for system-wide log files. Since
`/var/log` is inherently a log directory, the `opinion` parameter has no
effect (unlike `user_log_dir` which appends `/log`).
- **macOS** — `/Library/Logs/$appname`: per [Apple's File System
Programming
Guide](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html),
the `Logs` directory contains "log files for the console and specific
system services", mirroring `user_log_dir` at `~/Library/Logs`
- **Windows** — `C:\ProgramData\$appauthor\$appname\Logs`: Windows has
no dedicated system-wide log Known Folder ([KNOWNFOLDERID
reference](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid)),
so this mirrors the existing `user_log_dir` pattern of deriving from
`site_data_dir` (`CSIDL_COMMON_APPDATA`) with an opinionated `Logs`
subfolder
- **Android** — same as `user_log_dir`: follows the established pattern
where all `site_*` methods return `user_*` values since Android has no
true system-wide directories

Closes #215.

Libraries and daemons that manage persistent state shared across users
currently have no `platformdirs` API for resolving the correct
system-wide location. While `user_state_dir` exists for per-user state,
its `site_*` counterpart was missing — unlike `site_cache_dir` and
`site_log_dir` which already have both user and site variants. 🧩 This
gap forced consumers to hardcode platform-specific paths or repurpose
`site_data_dir`.

Each platform's path was chosen to align with its official filesystem
guidelines. On Linux, `/var/lib` is the canonical location for variable
state information per [FHS
§5.8](https://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch05s08.html). ✨
macOS and Windows delegate to `site_data_dir` (`/Library/Application
Support` and `C:\ProgramData` respectively) because neither platform
distinguishes state from data at the system level — per [Apple's File
System Programming
Guide](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html)
and [Microsoft's KNOWNFOLDERID
reference](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid).
Android delegates to `user_state_dir` since its app-centric security
model has no system-wide state concept.

Like `site_log_dir` and `site_cache_dir`, the Linux path is fixed at
`/var/lib` regardless of environment variables — there is no
`XDG_STATE_DIRS` equivalent. The full API surface mirrors the existing
pattern: `site_state_dir`, `site_state_path`, `iter_state_dirs`, and
`iter_state_paths`.

Closes #214

System daemons, package managers, and installers running as root
currently get user directories under `/root/.local/...`, which is rarely
the intended behavior. Callers have to manually detect uid 0 and switch
to `site_*_dir` themselves, duplicating logic that belongs in the
library. Closes #213.

✨ The new `use_site_for_root` constructor parameter (defaulting to
`False`) redirects all six `user_*_dir` properties to their `site_*_dir`
equivalents when the process is running as root (uid 0) on Unix. The
redirect bypasses XDG user environment variables like `XDG_DATA_HOME`
entirely, since those are typically inherited from the calling user via
`sudo` and would defeat the purpose of writing to system-wide paths. The
parameter follows the same cross-platform pattern as `roaming` —
accepted everywhere, but only meaningful on Unix.

Media directories (`user_documents_dir`, `user_downloads_dir`, etc.) are
not redirected because no `site_*` counterpart exists for them. The
parameter is also exposed on all 12 affected standalone functions
(`user_data_dir`, `user_data_path`, etc.) for convenience. 🔧 Default
behavior is completely unchanged — the feature is strictly opt-in.

On Windows the Shell Folder APIs (ctypes/registry) provide no mechanism
for users to redirect directories at runtime. This matters when large
data — ML models, package caches, build artifacts — should live on a
different drive without changing the system-wide `APPDATA` /
`LOCALAPPDATA` variables that every other application relies on. On
Linux/macOS `XDG_*` variables solve this naturally, but Windows has no
equivalent convention. Fixes #347.

`get_win_folder` now checks for a `PLATFORMDIRS_*` environment variable
(e.g. `PLATFORMDIRS_LOCAL_APPDATA`) before falling back to the existing
resolution. The prefix avoids colliding with the real Windows variables
while making the provenance obvious. The previous `lru_cache` on
`get_win_folder` is removed so overrides are picked up dynamically at
each access.

The platforms documentation now includes a full reference table of the
nine supported override variables with an example showing how to
redirect cache to a separate drive.

On Windows the Shell Folder APIs (ctypes/registry) provide no mechanism
for users to redirect directories at runtime. This matters when large
data — ML models, package caches, build artifacts — should live on a
different drive without changing the system-wide `APPDATA` /
`LOCALAPPDATA` variables that every other application relies on. On
Linux/macOS `XDG_*` variables solve this naturally, but Windows has no
equivalent convention. Fixes #347.

`get_win_folder` now checks for a `WIN_PD_OVERRIDE_*` environment
variable (e.g. `WIN_PD_OVERRIDE_LOCAL_APPDATA`) before falling back to
the existing resolution. The `WIN_PD_OVERRIDE_` prefix avoids colliding
with real Windows variables while making it clear this is a
platformdirs-specific override, and the `WIN_` prefix signals it only
applies on Windows. The previous `lru_cache` on `get_win_folder` is
removed so overrides are picked up dynamically at each access.

The platforms documentation now includes a full reference table of the
nine supported override variables with an example showing how to
redirect cache to a separate drive.

On macOS, `iter_data_dirs()` and `iter_config_dirs()` were falling back
to the base class implementation which yields `site_data_dir` as a
single string. When `XDG_DATA_DIRS` is set with multiple paths (common
on NixOS and similar setups) or under Homebrew where multiple site
directories exist, this produced a colon-joined string like
`/path1:/path2` instead of yielding each directory individually. 🐛

The Unix platform already overrides both methods to `yield from
self._site_data_dirs` / `self._site_config_dirs`, correctly producing
individual paths. macOS has the same `_site_data_dirs` and
`_site_config_dirs` properties (Homebrew-aware + XDG mixin) but was
missing the matching overrides. This adds the identical overrides to
`_MacOSDefaults`, consistent with the existing Unix approach.

Windows is unaffected since it only has single-value site directories
with no `_site_data_dirs` property.

Fixes #377

Applications that install user-facing executables (CLI tools, helper
scripts) need a platform-correct directory that's typically on PATH.
Currently there's no way to ask platformdirs for this location, so every
tool reinvents the logic. ✨ The new `user_bin_dir` and `user_bin_path`
properties provide the standard answer per platform: `~/.local/bin` on
Unix/macOS (per XDG spec and pip/pipx convention),
`%LOCALAPPDATA%\Programs` on Windows (`FOLDERID_UserProgramFiles`), and
`<android_folder>/files/bin` on Android.

Like other media directories (`user_documents_dir`,
`user_downloads_dir`, etc.), `user_bin_dir` does not append `appname` or
`version` since bin directories are shared across applications. No XDG
environment variable override is provided because the XDG spec does not
define one for this directory.

Closes #331

Applications have platform-specific installation directories that users
need to discover programmatically — `.desktop` files on Linux, the user
`Applications` folder on macOS, and Start Menu shortcuts on Windows.
This adds `user_applications_dir` and `user_applications_path` across
all platforms, following the same pattern as other media directories (no
`appname`/`version` appending).

Platform paths are `~/.local/share/applications` on Linux (per XDG
spec), `~/Applications` on macOS, `Start Menu\Programs` via
`FOLDERID_Programs` on Windows, and `user_data_dir` on Android as a
reasonable fallback. The `XDGMixin` respects `$XDG_DATA_HOME` when set,
deriving `$XDG_DATA_HOME/applications` before falling back to platform
defaults.

This follows the same design as `user_bin_dir` — a shared,
non-app-specific directory that doesn't append `appname` or `version`.
On Windows the full CSIDL infrastructure is wired up: ctypes via
`SHGetKnownFolderPath`, registry fallback, and env-var fallback through
`APPDATA`.

Closes #235

Users periodically ask for a home directory property (#235). Rather than
adding a wrapper around stdlib, this adds a "Directories not covered"
section to the usage docs pointing to `pathlib.Path.home()` and
`os.path.expanduser()` so the answer is discoverable without filing
issues.

Partially addresses #235 (the home directory part only).