docs: define cross-platform support tiers

CHANGELOG.md

@@ -13,6 +13,8 @@ and versions are tracked in the repo-root `VERSION` file.
 - Make terminal detection tolerate closed streams and record `COMSPEC` when
   Windows has no `SHELL` environment variable.
 - Add Linux distribution and WSL2 validation guidance for the generic package.
+- Document the Linux, WSL2, macOS, and native Windows support tiers and add
+  matching operating-system package classifiers.
 
 ## [0.2.0] - 2026-08-01
 

README.md

@@ -460,6 +460,11 @@ On POSIX, base-cli enforces owner-only `0600`/`0700` modes. On Windows, the
 default user-local cache root relies on inherited user-profile ACLs; consumers
 using a custom cache root must provide the appropriate ACL themselves.
 
+See [Platform support](docs/platform-support.md) for the supported Linux,
+WSL2, macOS, and native Windows boundaries. Native Windows support covers the
+generic `base-cli` framework; it does not imply native Windows support for
+Base or `basectl`.
+
 Use `ctx.on_cleanup()` for cleanup work that should happen even when helper code
 does not own the main command wrapper:
 

docs/platform-support.md

@@ -5,6 +5,26 @@ and is validated on Ubuntu, Debian, and Fedora-family environments. The
 package does not install or manage operating-system packages; consumers remain
 responsible for Python and any external tools their commands need.
 
+## Support matrix
+
+| Environment | Support level | Boundary |
+| --- | --- | --- |
+| macOS | Supported | Generic Python CLI framework and runtime helpers |
+| Ubuntu/Debian | Supported | Representative Linux distributions in CI |
+| Fedora/RHEL family | Supported | Representative Fedora-family validation in CI |
+| WSL2 | Supported | Python runs inside the Linux distribution |
+| Native Windows 10/11 | Supported for `base-cli` core | Click apps, runtime state, logging, history, and test helpers |
+
+Native Windows support applies to the generic Python package. It does not make
+Base or `basectl` natively Windows-compatible; those consumers have their own
+Unix-tooling and shell boundaries. The package does not provide package-manager
+integration, shell startup management, or WSL/Windows path translation.
+
+The supported Python range is Python 3.10 through 3.14. Bug reports should
+include the operating system, distribution or WSL version when relevant,
+Python version, and whether paths live on the native filesystem or a mounted
+filesystem.
+
 ## WSL2
 
 WSL2 is supported when Python runs inside the Linux distribution. Validate a

pyproject.toml

@@ -18,6 +18,9 @@ classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
   "License :: OSI Approved :: Apache Software License",
+  "Operating System :: MacOS",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX :: Linux",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
   "Programming Language :: Python :: 3.10",