diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 4cd7abda..b734000e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -29,6 +29,13 @@ repos:
     rev: "v3.8.1"
     hooks:
       - id: prettier
+  - repo: https://github.com/LilSpazJoekp/docstrfmt
+    rev: v2.0.2
+    hooks:
+      - id: docstrfmt
+        args: ["-l", "120"]
+        additional_dependencies: ["sphinx>=9.1"]
+        exclude: ^docs/index\.rst$ # https://github.com/LilSpazJoekp/docstrfmt/issues/176
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.15.4
     hooks:
diff --git a/.readthedocs.yml b/.readthedocs.yml
index 47a4b9e6..a9114b78 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,11 +1,9 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
-  tools:
-    python: "3.12"
+  os: ubuntu-lts-latest
+  tools: {}
   commands:
-    - asdf plugin add uv
-    - asdf install uv latest
-    - asdf global uv latest
-    - uv run --no-dev --group docs sphinx-build -T -b html -d docs/_build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html
+    - curl -LsSf https://astral.sh/uv/install.sh | sh
+    - ~/.local/bin/uv tool install tox --with tox-uv -p 3.14 --managed-python
+    - ~/.local/bin/tox run -e docs --
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 3677f2e4..165114fa 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -1,237 +1,173 @@
-+++++++++
-Changelog
-+++++++++
-
-1.4.0 (2026-01-08)
-==================
-
-- Add ``--quiet`` flag
-  (:pr:`947`)
-- Add option to dump PEP 517 metadata with ``--metadata``
-  (:pr:`940`, :pr:`943`)
-- Support ``UV`` environment variable
-  (:pr:`971`)
-- Remove a workaround for 3.14b1
-  (:pr:`960`)
-- In 3.14 final release, ``color`` defaults to ``True`` already
-  (:pr:`962`)
-- Pass sp-repo-review
-  (:pr:`942`)
-- In pytest configuration, ``log_level`` is better than ``log_cli_level``
-  (:pr:`950`)
-- Split up typing and mypy
-  (:pr:`944`)
-- Use ``types-colorama``
-  (:pr:`945`)
-- In docs, first argument for ``_has_dependency`` is a name
-  (PR :pr:`970`)
-- Fix test failure when ``flit-core`` is installed
-  (PR :pr:`921`)
-
-
-1.3.0 (2025-08-01)
-==================
-
-- Add ``--config-json``
-  (PR :pr:`916`, fixes issue :issue:`900`)
-- Drop Python 3.8
-  (PR :pr:`891`)
-- Test on Python 3.14, colorful help on 3.14+
-  (PR :pr:`895`)
-- Fix ``ModuleNotFoundError`` when ``pip`` is not installed
-  (PR :pr:`898`)
-- Disable use of ``pip install --python`` for debundled pip
-  (PR :pr:`861`)
-- Don't pass no-wheel to virtualenv if it would warn
-  (PR :pr:`892`)
-- Optimize our tests to run faster
-  (PR :pr:`871`, :pr:`872`, :pr:`738`)
-- Allow running our tests without virtualenv
-  (PR :pr:`911`)
-- Fix issues in our tests
-  (PR :pr:`824`, :pr:`918`, :pr:`870`, :pr:`915`, :pr:`862`, :pr:`863`, :pr:`899`, :pr:`896`, :pr:`854`)
-- Use SPDX identifiers for our license metadata
-  (PR :pr:`914`)
-- Use dependency-groups for our development
-  (PR :pr:`880`)
-- Mention conda and update uv mention in README/docs
-  (PR :pr:`842`, :pr:`816`, :pr:`917`)
-
-1.2.2 (2024-09-06)
-==================
-
-- Add editable to ``builder.get_requires_for_build``'s static types
-  (PR :pr:`764`, fixes issue :issue:`763`)
-- Include artifact attestations in our release
-  (PR :pr:`782`)
-- Fix typing compatibility with typed ``pyproject-hooks``
-  (PR :pr:`788`)
-- Mark more tests with ``network``
-  (PR :pr:`808`)
-- Add more intersphinx links to docs
-  (PR :pr:`804`)
-- Make ``uv`` optional for tests
-  (PR :pr:`807` and :pr:`813`)
-
-1.2.1 (2024-03-28)
-==================
-
-- Avoid error when terminal width is undetectable on Python < 3.11
-  (PR :pr:`761`)
-
-1.2.0 (2024-03-27)
-==================
-
-- Add ``--installer`` option, supporting ``pip`` and ``uv``. Added ``uv``
-  extra.
-  (PR :pr:`751`)
-- Improve console output and provide ``-v`` for dependency installation
-  (PR :pr:`749`)
-- Avoid compiling unused bytecode when using ``pip``
-  (PR :pr:`752`)
-- Dropped support for Python 3.7
-  (PR :pr:`743`)
-
-
-1.1.1 (2024-02-29)
-==================
-
-- Fixed invoking outer pip from user site packages
-  (PR :pr:`746`, fixes issue :issue:`745`)
-- Corrected the minimum pip version required to use an outer pip
-  (PR :pr:`746`, fixes issue :issue:`745`)
-
-
-1.1.0 (2024-02-29)
-==================
-
-- Use external pip if available instead of installing, speeds up environment
-  setup with virtualenv slightly and venv significantly.
-  (PR :pr:`736`)
-- Stopped injecting ``wheel`` as a build dependency automatically, in the
-  case of missing ``pyproject.toml`` -- by :user:`webknjaz`.
-  (PR :pr:`716`)
-- Use ``importlib_metadata`` on Python <3.10.2 for bugfixes not present in
-  those CPython standard libraries (not required when bootstrapping) -- by
-  :user:`GianlucaFicarelli`.
-  (PR :pr:`693`, fixes issue :issue:`692`)
-
-
-1.0.3 (2023-09-06)
-==================
-
-- Avoid CPython 3.8.17, 3.9.17, 3.10.12, and 3.11.4 tarfile symlink bug
-  triggered by adding ``data_filter`` in 1.0.0.
+###########
+ Changelog
+###########
+
+********************
+ 1.4.0 (2026-01-08)
+********************
+
+- Add ``--quiet`` flag (:pr:`947`)
+- Add option to dump PEP 517 metadata with ``--metadata`` (:pr:`940`, :pr:`943`)
+- Support ``UV`` environment variable (:pr:`971`)
+- Remove a workaround for 3.14b1 (:pr:`960`)
+- In 3.14 final release, ``color`` defaults to ``True`` already (:pr:`962`)
+- Pass sp-repo-review (:pr:`942`)
+- In pytest configuration, ``log_level`` is better than ``log_cli_level`` (:pr:`950`)
+- Split up typing and mypy (:pr:`944`)
+- Use ``types-colorama`` (:pr:`945`)
+- In docs, first argument for ``_has_dependency`` is a name (PR :pr:`970`)
+- Fix test failure when ``flit-core`` is installed (PR :pr:`921`)
+
+********************
+ 1.3.0 (2025-08-01)
+********************
+
+- Add ``--config-json`` (PR :pr:`916`, fixes issue :issue:`900`)
+- Drop Python 3.8 (PR :pr:`891`)
+- Test on Python 3.14, colorful help on 3.14+ (PR :pr:`895`)
+- Fix ``ModuleNotFoundError`` when ``pip`` is not installed (PR :pr:`898`)
+- Disable use of ``pip install --python`` for debundled pip (PR :pr:`861`)
+- Don't pass no-wheel to virtualenv if it would warn (PR :pr:`892`)
+- Optimize our tests to run faster (PR :pr:`871`, :pr:`872`, :pr:`738`)
+- Allow running our tests without virtualenv (PR :pr:`911`)
+- Fix issues in our tests (PR :pr:`824`, :pr:`918`, :pr:`870`, :pr:`915`, :pr:`862`, :pr:`863`, :pr:`899`, :pr:`896`,
+  :pr:`854`)
+- Use SPDX identifiers for our license metadata (PR :pr:`914`)
+- Use dependency-groups for our development (PR :pr:`880`)
+- Mention conda and update uv mention in README/docs (PR :pr:`842`, :pr:`816`, :pr:`917`)
+
+********************
+ 1.2.2 (2024-09-06)
+********************
+
+- Add editable to ``builder.get_requires_for_build``'s static types (PR :pr:`764`, fixes issue :issue:`763`)
+- Include artifact attestations in our release (PR :pr:`782`)
+- Fix typing compatibility with typed ``pyproject-hooks`` (PR :pr:`788`)
+- Mark more tests with ``network`` (PR :pr:`808`)
+- Add more intersphinx links to docs (PR :pr:`804`)
+- Make ``uv`` optional for tests (PR :pr:`807` and :pr:`813`)
+
+********************
+ 1.2.1 (2024-03-28)
+********************
+
+- Avoid error when terminal width is undetectable on Python < 3.11 (PR :pr:`761`)
+
+********************
+ 1.2.0 (2024-03-27)
+********************
+
+- Add ``--installer`` option, supporting ``pip`` and ``uv``. Added ``uv`` extra. (PR :pr:`751`)
+- Improve console output and provide ``-v`` for dependency installation (PR :pr:`749`)
+- Avoid compiling unused bytecode when using ``pip`` (PR :pr:`752`)
+- Dropped support for Python 3.7 (PR :pr:`743`)
+
+********************
+ 1.1.1 (2024-02-29)
+********************
+
+- Fixed invoking outer pip from user site packages (PR :pr:`746`, fixes issue :issue:`745`)
+- Corrected the minimum pip version required to use an outer pip (PR :pr:`746`, fixes issue :issue:`745`)
+
+********************
+ 1.1.0 (2024-02-29)
+********************
+
+- Use external pip if available instead of installing, speeds up environment setup with virtualenv slightly and venv
+  significantly. (PR :pr:`736`)
+- Stopped injecting ``wheel`` as a build dependency automatically, in the case of missing ``pyproject.toml`` -- by
+  :user:`webknjaz`. (PR :pr:`716`)
+- Use ``importlib_metadata`` on Python <3.10.2 for bugfixes not present in those CPython standard libraries (not
+  required when bootstrapping) -- by :user:`GianlucaFicarelli`. (PR :pr:`693`, fixes issue :issue:`692`)
+
+********************
+ 1.0.3 (2023-09-06)
+********************
+
+- Avoid CPython 3.8.17, 3.9.17, 3.10.12, and 3.11.4 tarfile symlink bug triggered by adding ``data_filter`` in 1.0.0.
   (PR :pr:`675`, fixes issue :issue:`674`)
 
-
-1.0.0 (2023-09-01)
-==================
-
-- Removed the ``toml`` library fallback; ``toml`` can no longer be used
-  as a substitute for ``tomli``
-  (PR :pr:`567`)
-- Added ``runner`` parameter to ``util.project_wheel_metadata``
-  (PR :pr:`566`, fixes issue :issue:`553`)
-- Modified ``ProjectBuilder`` constructor signature, added alternative
-  ``ProjectBuilder.from_env`` constructor, redefined ``env.IsolatedEnv``
-  interface, and exposed ``env.DefaultIsolatedEnv``, replacing
-  ``env.IsolatedEnvBuilder``.  The aim has been to shift responsibility for
-  modifying the environment from the project builder to the ``IsolatedEnv``
-  entirely and to ensure that the builder will be initialised from an
-  ``IsolatedEnv`` in a consistent manner.  Mutating the project builder is no
-  longer supported.
-  (PR :pr:`537`)
-- ``virtualenv`` is no longer imported when using ``-n``, for faster builds
-  (PR :pr:`636`, fixes issue :issue:`510`)
-- The SDist now contains the repository contents, including tests. Flit-core
-  3.8+ required.
-  (PR :pr:`657`, :pr:`661`, fixes issue :issue:`656`)
-- The minimum version of ``importlib-metadata`` has been increased to 4.6 and
-  Python 3.10 due to a bug in the standard library version with URL
-  requirements in extras. This is still not required for 3.8 when bootstrapping
-  (as long as you don't have URL requirements in extras).
-  (PR :pr:`631`, fixes issue :issue:`630`)
-- Docs now built with Sphinx 7
-  (PR :pr:`660`)
-- Tests now contain a ``network`` marker
-  (PR :pr:`649`, fixes issue :issue:`648`)
-- Config-settings are now passed to ``get_requires*`` hooks, fixing a long
-  standing bug. If this affects your setuptools build, you can use
-  ``-C--build-option=<cmd> -C--build-option=<option>`` to workaround an issue
-  with Setuptools not allowing unrecognised build options when running this
-  hook.
-  (PR :pr:`627`, fixes issue :issue:`#264`)
-- Test on Python 3.12 betas/RCs
-  (PR :pr:`624`)
-- Filter out malicious files when extracting tar archives when Python supports it
-  (PR :pr:`609`)
-- Specify encoding, fixing issues when ``PYTHONWARNDEFAULTENCODING`` is set.
-  (PR :pr:`587`, fixes issue :issue:`577`)
+********************
+ 1.0.0 (2023-09-01)
+********************
+
+- Removed the ``toml`` library fallback; ``toml`` can no longer be used as a substitute for ``tomli`` (PR :pr:`567`)
+- Added ``runner`` parameter to ``util.project_wheel_metadata`` (PR :pr:`566`, fixes issue :issue:`553`)
+- Modified ``ProjectBuilder`` constructor signature, added alternative ``ProjectBuilder.from_env`` constructor,
+  redefined ``env.IsolatedEnv`` interface, and exposed ``env.DefaultIsolatedEnv``, replacing ``env.IsolatedEnvBuilder``.
+  The aim has been to shift responsibility for modifying the environment from the project builder to the ``IsolatedEnv``
+  entirely and to ensure that the builder will be initialised from an ``IsolatedEnv`` in a consistent manner. Mutating
+  the project builder is no longer supported. (PR :pr:`537`)
+- ``virtualenv`` is no longer imported when using ``-n``, for faster builds (PR :pr:`636`, fixes issue :issue:`510`)
+- The SDist now contains the repository contents, including tests. Flit-core 3.8+ required. (PR :pr:`657`, :pr:`661`,
+  fixes issue :issue:`656`)
+- The minimum version of ``importlib-metadata`` has been increased to 4.6 and Python 3.10 due to a bug in the standard
+  library version with URL requirements in extras. This is still not required for 3.8 when bootstrapping (as long as you
+  don't have URL requirements in extras). (PR :pr:`631`, fixes issue :issue:`630`)
+- Docs now built with Sphinx 7 (PR :pr:`660`)
+- Tests now contain a ``network`` marker (PR :pr:`649`, fixes issue :issue:`648`)
+- Config-settings are now passed to ``get_requires*`` hooks, fixing a long standing bug. If this affects your setuptools
+  build, you can use ``-C--build-option=<cmd> -C--build-option=<option>`` to workaround an issue with Setuptools not
+  allowing unrecognised build options when running this hook. (PR :pr:`627`, fixes issue :issue:`#264`)
+- Test on Python 3.12 betas/RCs (PR :pr:`624`)
+- Filter out malicious files when extracting tar archives when Python supports it (PR :pr:`609`)
+- Specify encoding, fixing issues when ``PYTHONWARNDEFAULTENCODING`` is set. (PR :pr:`587`, fixes issue :issue:`577`)
 - Ruff is now used for linting.
 
+*********************
+ 0.10.0 (2023-01-11)
+*********************
 
-0.10.0 (2023-01-11)
-===================
-
-- Replace ``pep517`` dependency with ``pyproject_hooks``,
-  into which ``pep517`` has been renamed
-  (PR :pr:`539`, Fixes :issue:`529`)
-- Change build backend from ``setuptools`` to ``flit``
-  (PR :pr:`470`, Fixes :issue:`394`)
+- Replace ``pep517`` dependency with ``pyproject_hooks``, into which ``pep517`` has been renamed (PR :pr:`539`, Fixes
+  :issue:`529`)
+- Change build backend from ``setuptools`` to ``flit`` (PR :pr:`470`, Fixes :issue:`394`)
 - Dropped support for Python 3.6 (PR :pr:`532`)
 
-
-
-0.9.0 (2022-10-27)
-==================
+********************
+ 0.9.0 (2022-10-27)
+********************
 
 - Hide a Python 3.11.0 unavoidable warning with venv (PR :pr:`527`)
-- Fix infinite recursion error in ``check_dependency`` with circular
-  dependencies (PR :pr:`512`, Fixes :issue:`511`)
+- Fix infinite recursion error in ``check_dependency`` with circular dependencies (PR :pr:`512`, Fixes :issue:`511`)
 - Only import colorama on Windows (PR :pr:`494`, Fixes :issue:`493`)
 - Flush output more often to reduce interleaved output (PR :pr:`494`)
 - Small API cleanup, like better ``__all__`` and srcdir being read only. (PR :pr:`477`)
 - Only use ``importlib_metadata`` when needed (PR :pr:`401`)
 - Clarify in printout when build dependencies are being installed (PR :pr:`514`)
 
+********************
+ 0.8.0 (2022-05-22)
+********************
 
-
-0.8.0 (2022-05-22)
-==================
-
-- Accept ``os.PathLike[str]`` in addition to ``str`` for paths in public
-  API (PR :pr:`392`, Fixes :issue:`372`)
-- Add schema validation for ``build-system`` table to check conformity
-  with PEP 517 and PEP 518 (PR :pr:`365`, Fixes :issue:`364`)
-- Better support for Python 3.11 (sysconfig schemes PR :pr:`434`,  PR :pr:`463`, tomllib PR :pr:`443`, warnings PR :pr:`420`)
+- Accept ``os.PathLike[str]`` in addition to ``str`` for paths in public API (PR :pr:`392`, Fixes :issue:`372`)
+- Add schema validation for ``build-system`` table to check conformity with PEP 517 and PEP 518 (PR :pr:`365`, Fixes
+  :issue:`364`)
+- Better support for Python 3.11 (sysconfig schemes PR :pr:`434`, PR :pr:`463`, tomllib PR :pr:`443`, warnings PR
+  :pr:`420`)
 - Improved error printouts (PR :pr:`442`)
 - Avoid importing packaging unless needed (PR :pr:`395`, Fixes :issue:`393`)
 
 Breaking Changes
-----------------
-
-- Failure to create a virtual environment in the ``build.env`` module now raises
-  ``build.FailedProcessError`` (PR :pr:`442`)
-
+================
 
+- Failure to create a virtual environment in the ``build.env`` module now raises ``build.FailedProcessError`` (PR
+  :pr:`442`)
 
-0.7.0 (2021-09-16)
-==================
+********************
+ 0.7.0 (2021-09-16)
+********************
 
 - Add ``build.util`` module with a high-level utility API (PR :pr:`340`)
 
-
-
-0.6.0.post1 (2021-08-05)
-========================
+**************************
+ 0.6.0.post1 (2021-08-05)
+**************************
 
 - Fix compatibility with Python 3.6 and 3.7 (PR :pr:`339`, Fixes :issue:`338`)
 
-
-
-0.6.0 (2021-08-02)
-==================
+********************
+ 0.6.0 (2021-08-02)
+********************
 
 - Improved output (PR :pr:`333`, Fixes :issue:`142`)
 - The CLI now honors ``NO_COLOR`` (PR :pr:`333`)
@@ -240,39 +176,38 @@ Breaking Changes
 - Switch to a TOML v1 compliant parser (PR :pr:`336`, Fixes :issue:`308`)
 
 Breaking Changes
-----------------
+================
 
 - Dropped support for Python 2 and 3.5.
 
-
-
-0.5.1 (2021-06-22)
-==================
+********************
+ 0.5.1 (2021-06-22)
+********************
 
 - Fix invoking the backend on an inexistent output directory with multiple levels (PR :pr:`318`, Fixes :issue:`316`)
 - When building wheels via sdists, use an isolated temporary directory (PR :pr:`321`, Fixes :issue:`320`)
 
-
-
-0.5.0 (2021-06-19)
-==================
+********************
+ 0.5.0 (2021-06-19)
+********************
 
 - Add ``ProjectBuilder.metadata_path`` helper (PR :pr:`303`, Fixes :issue:`301`)
 - Added a ``build.__main__.build_package_via_sdist`` method (PR :pr:`304`)
 - Use appropriate installation scheme for Apple Python venvs (PR :pr:`314`, Fixes :issue:`310`)
 
 Breaking Changes
-----------------
-
-- Binary distributions are now built via the sdist by default in the CLI (PR :pr:`304`, Fixes :issue:`257`)
-  - ``python -m build`` will now build a sdist, extract it, and build a wheel from the source
-- As a side-effect of PR :pr:`304`, ``build.__main__.build_package`` no longer does CLI error handling (print nice message and exit the program)
-- Importing ``build.__main__`` no longer has any side-effects, it no longer overrides ``warnings.showwarning`` or runs ``colorama.init`` on import (PR :pr:`312`)
+================
 
+- Binary distributions are now built via the sdist by default in the CLI (PR :pr:`304`, Fixes :issue:`257`) - ``python
+  -m build`` will now build a sdist, extract it, and build a wheel from the source
+- As a side-effect of PR :pr:`304`, ``build.__main__.build_package`` no longer does CLI error handling (print nice
+  message and exit the program)
+- Importing ``build.__main__`` no longer has any side-effects, it no longer overrides ``warnings.showwarning`` or runs
+  ``colorama.init`` on import (PR :pr:`312`)
 
-
-0.4.0 (2021-05-23)
-==================
+********************
+ 0.4.0 (2021-05-23)
+********************
 
 - Validate that the supplied source directory is valid (PR :pr:`260`, Fixes :issue:`259`)
 - Set and test minimum versions of build's runtime dependencies (PR :pr:`267`, Fixes :issue:`263`)
@@ -283,63 +218,67 @@ Breaking Changes
 - Try to use ``colorama`` to fix colors on Windows (PR :pr:`300`)
 
 Breaking Changes
-----------------
+================
 
-- As a side-effect of PR :pr:`260`, projects not containing either a ``pyproject.toml`` or ``setup.py`` will be reported as invalid. This affects projects specifying only a ``setup.cfg``, such projects are recommended to add a ``pyproject.toml``. The new behavior is on par with what pip currently does, so if you are affected by this, your project should not be pip installable.
+- As a side-effect of PR :pr:`260`, projects not containing either a ``pyproject.toml`` or ``setup.py`` will be reported
+  as invalid. This affects projects specifying only a ``setup.cfg``, such projects are recommended to add a
+  ``pyproject.toml``. The new behavior is on par with what pip currently does, so if you are affected by this, your
+  project should not be pip installable.
 - The ``--skip-dependencies`` option has been renamed to ``--skip-dependency-check`` (PR :pr:`297`)
-- The ``skip_dependencies`` argument of ``build.__main__.build_package`` has been renamed to ``skip_dependency_check`` (PR :pr:`297`)
+- The ``skip_dependencies`` argument of ``build.__main__.build_package`` has been renamed to ``skip_dependency_check``
+  (PR :pr:`297`)
 - ``build.ConfigSettings`` has been renamed to ``build.ConfigSettingsType`` (PR :pr:`298`)
-- ``build.ProjectBuilder.build_dependencies`` to ``build.ProjectBuilder.build_system_requires`` (PR :pr:`284`, Fixes :issue:`182`)
-- ``build.ProjectBuilder.get_dependencies`` to ``build.ProjectBuilder.get_requires_for_build`` (PR :pr:`284`, Fixes :issue:`182`)
-
+- ``build.ProjectBuilder.build_dependencies`` to ``build.ProjectBuilder.build_system_requires`` (PR :pr:`284`, Fixes
+  :issue:`182`)
+- ``build.ProjectBuilder.get_dependencies`` to ``build.ProjectBuilder.get_requires_for_build`` (PR :pr:`284`, Fixes
+  :issue:`182`)
 
-
-0.3.1 (2021-03-09)
-==================
+********************
+ 0.3.1 (2021-03-09)
+********************
 
 - Support direct usage from pipx run in 0.16.1.0+ (PR :pr:`247`)
 - Use UTF-8 encoding when reading pyproject.toml (PR :pr:`251`, Fixes :issue:`250`)
 
+********************
+ 0.3.0 (2021-02-19)
+********************
 
-
-0.3.0 (2021-02-19)
-==================
-
-- Upgrade pip based on venv pip version, avoids error on Debian Python 3.6.5-3.8 or issues installing wheels on Big Sur (PR :pr:`229`, PR :pr:`230`, Fixes :issue:`228`)
+- Upgrade pip based on venv pip version, avoids error on Debian Python 3.6.5-3.8 or issues installing wheels on Big Sur
+  (PR :pr:`229`, PR :pr:`230`, Fixes :issue:`228`)
 - Build dependencies in isolation, instead of in the build environment (PR :pr:`232`, Fixes :issue:`231`)
 - Fallback on venv if virtualenv is too old (PR :pr:`241`)
 - Add metadata preparation hook (PR :pr:`217`, Fixes :issue:`130`)
 
-
-
-0.2.1 (2021-02-09)
-==================
+********************
+ 0.2.1 (2021-02-09)
+********************
 
 - Fix error from unrecognised pip flag on Python 3.6.0 to 3.6.5 (PR :pr:`227`, Fixes :issue:`226`)
 
-
-
-0.2.0 (2021-02-07)
-==================
+********************
+ 0.2.0 (2021-02-07)
+********************
 
 - Check dependencies recursively (PR :pr:`183`, Fixes :issue:`25`)
-- Build wheel and sdist distributions in separate environments, as they may have different dependencies (PR :pr:`195`, Fixes :issue:`194`)
+- Build wheel and sdist distributions in separate environments, as they may have different dependencies (PR :pr:`195`,
+  Fixes :issue:`194`)
 - Add support for pre-releases in ``check_dependency`` (PR :pr:`204`, Fixes :issue:`191`)
 - Fixes console scripts not being available during build (PR :pr:`221`, Fixes :issue:`214`)
-- Do not add the default backend requirements to ``requires`` when no backend is specified (PR :pr:`177`, Fixes :issue:`107`)
+- Do not add the default backend requirements to ``requires`` when no backend is specified (PR :pr:`177`, Fixes
+  :issue:`107`)
 - Return the sdist name in ``ProjectBuild.build`` (PR :pr:`197`)
 - Improve documentation (PR :pr:`178`, PR :pr:`203`)
 - Add changelog (PR :pr:`219`, Fixes :issue:`169`)
 
 Breaking changes
-----------------
+================
 
 - Move ``config_settings`` argument to the hook calls (PR :pr:`218`, Fixes :issue:`216`)
 
-
-
-0.1.0 (2020-10-29)
-==================
+********************
+ 0.1.0 (2020-10-29)
+********************
 
 - Moved the upstream to PyPA
 - Fixed building with isolation in a virtual environment
@@ -355,7 +294,7 @@ Breaking changes
 - Updated the CoC to the PSF CoC, which PyPA has adopted
 
 Breaking changes
-----------------
+================
 
 - Renamed the entrypoint script to pyproject-build
 - Removed default arguments from all paths in ProjectBuilder
@@ -364,10 +303,9 @@ Breaking changes
 - Changed the default outdir value to {srcdir}/dest
 - Removed env.IsolatedEnvironment
 
-
-
-0.0.4 (2020-09-08)
-==================
+********************
+ 0.0.4 (2020-09-08)
+********************
 
 - Packages are now built in isolation by default
 - Added --no-isolation/-n flag to build in the current environment
@@ -380,33 +318,29 @@ Breaking changes
 - Automatically detect typos in the build system table
 - Minor documentation improvements
 
-
-
-0.0.3.1 (2020-06-10)
-====================
+**********************
+ 0.0.3.1 (2020-06-10)
+**********************
 
 - Fix bug preventing the CLI from being invoked
 - Improved documentation
 
-
-
-0.0.3 (2020-06-09)
-==================
+********************
+ 0.0.3 (2020-06-09)
+********************
 
 - Misc improvements
 - Added documentation
 
-
-
-0.0.2 (2020-05-29)
-==================
+********************
+ 0.0.2 (2020-05-29)
+********************
 
 - Add setuptools as a default fallback backend
 - Fix extras handling in requirement strings
 
-
-
-0.0.1 (2020-05-17)
-==================
+********************
+ 0.0.1 (2020-05-17)
+********************
 
 - Initial release
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
new file mode 100644
index 00000000..436dbbb0
--- /dev/null
+++ b/docs/_static/custom.css
@@ -0,0 +1,14 @@
+.sidebar-brand-text {
+  text-align: center;
+  margin-top: 0;
+  padding-top: 0;
+}
+
+.sidebar-logo-container {
+  margin-bottom: 0;
+  padding-bottom: 0;
+}
+
+.sidebar-brand {
+  gap: 0;
+}
diff --git a/docs/_static/logo.svg b/docs/_static/logo.svg
new file mode 100644
index 00000000..79a813c2
--- /dev/null
+++ b/docs/_static/logo.svg
@@ -0,0 +1,24 @@
+<svg width="400" height="400" viewBox="0 0 400 400" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="200" cy="200" r="190" fill="#fcfcfc" />
+
+  <g stroke="#1a3650" stroke-width="10" stroke-linejoin="round">
+    <path d="M200 60 L330 135 L200 210 L70 135 Z" fill="#ffd43b" />
+    <path d="M70 135 L200 210 L200 350 L70 275 Z" fill="#2b5b84" />
+    <path d="M200 210 L330 135 L330 275 L200 350 Z" fill="#3776ab" />
+  </g>
+
+  <g transform="translate(200, 148) rotate(-35) scale(-1.58, 1.58) translate(-2.5, -17.5)" fill="white">
+    <path d="M-4 10 L4 10 L6 45 L-6 45 Z" rx="1" />
+
+    <g>
+      <rect x="-22" y="-12" width="44" height="24" rx="2" />
+
+      <rect x="18" y="-12" width="4" height="24" rx="1" fill="#eeeeee" />
+      <rect x="-22" y="-12" width="4" height="24" rx="1" fill="#eeeeee" />
+
+      <rect x="-6" y="-12" width="12" height="24" fill="white" stroke="#1a3650" stroke-width="1" opacity="0.1" />
+    </g>
+  </g>
+
+  <text x="200" y="275" font-family="Arial Black, sans-serif" font-size="76" fill="#ffd43b" text-anchor="middle" letter-spacing="-4">BUILD</text>
+</svg>
diff --git a/docs/api.rst b/docs/api.rst
deleted file mode 100644
index 254db235..00000000
--- a/docs/api.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-API Documentation
-=================
-
-``build`` module
-----------------
-
-.. automodule:: build
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-``build.env`` module
---------------------
-
-.. automodule:: build.env
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-``build.util`` module
----------------------
-
-.. automodule:: build.util
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/conf.py b/docs/conf.py
index 7810cafe..fcddb1da 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -10,9 +10,15 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
+import warnings
+
 import build
 
 
+if hasattr(__builtins__, 'EncodingWarning'):
+    warnings.filterwarnings('ignore', category=EncodingWarning, module='sphinx_copybutton')  # noqa: F821
+
+
 # -- Project information -----------------------------------------------------
 
 project = 'build'
@@ -35,7 +41,10 @@
     'sphinx.ext.intersphinx',
     'sphinx_autodoc_typehints',
     'sphinx_argparse_cli',
+    'sphinx_copybutton',
+    'sphinx_inline_tabs',
     'sphinx_issues',
+    'sphinxcontrib.mermaid',
 ]
 
 intersphinx_mapping = {
@@ -59,12 +68,19 @@
 # a list of builtin themes.
 #
 html_theme = 'furo'
-html_title = f'build {version}'
+html_title = f'build - {version}'
+html_show_sourcelink = False
+html_favicon = '_static/logo.svg'
+html_theme_options = {
+    'light_logo': 'logo.svg',
+    'dark_logo': 'logo.svg',
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named 'default.css' will overwrite the builtin 'default.css'.
-# html_static_path = ['_static']
+html_static_path = ['_static']
+html_css_files = ['custom.css']
 
 autoclass_content = 'both'
 
@@ -76,3 +92,8 @@
 
 
 issues_github_path = 'pypa/build'
+
+copybutton_prompt_text = r'>>> |\.\.\. |\$ '
+copybutton_prompt_is_regexp = True
+copybutton_only_copy_prompt_lines = False
+copybutton_remove_prompts = True
diff --git a/docs/development/contributing.rst b/docs/development/contributing.rst
new file mode 100644
index 00000000..73885ee0
--- /dev/null
+++ b/docs/development/contributing.rst
@@ -0,0 +1,169 @@
+##############
+ Contributing
+##############
+
+build welcomes contributions from the community. This guide explains how to contribute to the project.
+
+*******************
+ Development Setup
+*******************
+
+To contribute to build, you need a development environment set up on your local machine. Start by forking the
+`repository on GitHub <https://github.com/pypa/build>`_ and cloning your fork to your local machine. Once cloned,
+navigate to the project directory and install build in development mode along with all development dependencies.
+
+The project uses `tox <https://tox.wiki/>`_ for managing development environments and running tests. Install tox
+globally or in a virtual environment, then use it to run tests and other development tasks. The tox configuration
+includes environments for testing across multiple Python versions, running linters, building documentation, and more.
+
+**********************
+ Development Workflow
+**********************
+
+The typical development workflow begins with creating a new branch for your changes. Branch names should be descriptive
+of the feature or fix you're implementing. Make your changes in this branch, ensuring you add or update tests to cover
+your modifications.
+
+Before committing, run the test suite locally to verify your changes don't break existing functionality. The project
+uses `pytest <https://docs.pytest.org/>`_ for testing, and you can run tests using tox. After ensuring tests pass,
+commit your changes with a clear, descriptive commit message following the project's commit conventions.
+
+When your changes are ready, push your branch to your fork on GitHub and open a pull request against the main build
+repository. The pull request description should clearly explain what changes you've made and why. Reference any related
+issues using GitHub's issue linking syntax.
+
+***************
+ Running Tests
+***************
+
+Due to its nature, build has a somewhat complex test suite with two sets of tests: unit tests and integration tests.
+Unit tests verify the actual code implementation, while integration tests run build on real world projects as a sanity
+check. Integration tests take a long time to run and are not very helpful for tracking down issues, so they are disabled
+by default. They can be enabled by passing either ``--run-integration`` or ``--only-integration`` arguments to pytest,
+where the latter will disable unit tests and only run integration tests. Even though these tests are disabled by
+default, they will be run in CI where test suite run durations are not a big issue.
+
+To run the test suite, use tox which automates running tests on different environments. Simply run ``tox`` in the
+project directory to execute the full test suite. The project has a fairly large environment matrix, running tests for
+all supported Python versions and implementations, and with the module being invoked directly from path, sdist install,
+or wheel install. Additionally, there are environments for type checking and documentation building, plus extras like
+checking code with minimum versions of dependencies.
+
+Some example commands for this project include running type checking with ``tox -e type``, running only unit tests
+against Python 3.9 with ``tox -e py39``, running both unit and integration tests with ``tox -- --run-integration``,
+running only integration tests with ``tox -- --only-integration``, or running only integration tests with parallel tasks
+using ``tox -- -n auto --only-integration``. You can also run unit tests against a specific Python version with wheel
+installation using ``tox -e py39-wheel``.
+
+Code coverage is tracked to ensure all code paths are tested. Aim for complete coverage of any new code you add. The CI
+system will report coverage metrics on your pull request and runs the test suite across all supported operating systems.
+
+************************
+ Code Style and Linting
+************************
+
+build follows modern Python code style conventions enforced by `ruff <https://docs.astral.sh/ruff/>`_. Before submitting
+a pull request, run the linter to ensure your code meets the project's style guidelines. The ruff configuration is
+defined in the pyproject.toml file and includes both formatting and linting rules.
+
+The project also uses type annotations throughout the codebase. All new code should include appropriate type hints, and
+changes to existing code should preserve or improve type annotations. Use `pyright
+<https://microsoft.github.io/pyright/>`_ for type checking to verify your type annotations are correct.
+
+***************
+ Documentation
+***************
+
+Good documentation is essential for build's users and contributors. If your contribution adds new features or changes
+existing behavior, update the relevant documentation files. The documentation is written in `reStructuredText
+<https://docutils.sourceforge.io/rst.html>`_ and built using `Sphinx <https://www.sphinx-doc.org/>`_.
+
+The documentation follows the `Diataxis framework <https://diataxis.fr/>`_, organizing content into tutorials, how-to
+guides, technical reference, and explanations. Place your documentation in the appropriate section based on its purpose.
+Tutorial content teaches beginners, how-to guides solve specific problems, reference sections document details, and
+explanations provide context and design rationale.
+
+Build the documentation locally to verify your changes render correctly. The tox configuration includes an environment
+for building docs. Review the rendered output to ensure formatting, links, and code examples appear as intended.
+
+**********************
+ Pull Request Process
+**********************
+
+When you open a pull request, maintainers will review your changes and may request modifications. Be responsive to
+feedback and make requested changes in additional commits on your branch. The pull request will be merged once approved
+by a maintainer and all CI checks pass.
+
+The CI system runs the full test suite across all supported Python versions, verifies code style compliance, builds the
+documentation, and performs other checks. All CI checks must pass before a pull request can be merged. If CI fails,
+review the output to understand what went wrong and push fixes to your branch.
+
+****************
+ Issue Tracking
+****************
+
+Before starting work on a significant feature or change, check the issue tracker to see if it's already been discussed.
+If not, consider opening an issue to discuss your proposed changes with maintainers. This helps ensure your contribution
+aligns with the project's direction and avoids duplicate effort.
+
+When reporting bugs, include detailed information about the issue. Provide the full error message and traceback,
+describe what you expected to happen versus what actually happened, list the steps to reproduce the problem, and include
+information about your environment such as Python version and operating system.
+
+For feature requests, explain the use case and why the feature would benefit build's users. Include examples of how the
+feature would be used if implemented.
+
+*****************
+ Release Process
+*****************
+
+build uses a structured release process managed by maintainers. Releases follow `semantic versioning
+<https://semver.org/>`_, with version numbers indicating the level of changes. The changelog documents all changes in
+each release, organized by type such as features, bug fixes, and deprecations.
+
+As a contributor, you don't need to worry about creating releases, but understanding the process can help you write
+better changelog entries and commit messages. Maintainers release the project by first bumping the version in
+``src/build/__init__.py`` and updating ``CHANGELOG.rst`` with the new version and current date. They then make a release
+commit with these changes using the format ``release X.Y.Z`` for the commit message. Next, they create a signed tag with
+``git tag --sign X.Y.Z`` where the tag title follows the ``build X.Y.Z`` format and the tag body contains a plaintext
+version of the changelog for the current release. Finally, they push both the commit and tag to the repository using
+``git push`` and ``git push --tags``, then make a release on GitHub or with the gh CLI tool, copying the release notes
+into the release. If you have questions about the release process, look at previous releases or reach out to other
+maintainers.
+
+**********************
+ Community Guidelines
+**********************
+
+build is part of the `PyPA (Python Packaging Authority) <https://www.pypa.io/>`_ ecosystem and follows the PyPA Code of
+Conduct. Be respectful and constructive in all interactions with other contributors. Focus feedback on the code and
+ideas, not on individuals.
+
+The project values clear communication, thorough testing, and well-documented code. Take time to explain your changes
+clearly in commit messages and pull requests. Write tests that future contributors can understand. Document not just
+what your code does, but why you made particular design choices.
+
+**************
+ Getting Help
+**************
+
+If you have questions about contributing, several resources are available. The issue tracker can be used for questions,
+though complex discussions may be better suited to other venues. The project's documentation includes extensive
+information about build's design and implementation.
+
+For real-time discussion, consider joining the `PyPA Discord server <https://discord.gg/pypa>`_ where many packaging
+tool maintainers and contributors participate. You can also ask questions on the `Python Packaging Discourse forum
+<https://discuss.python.org/c/packaging/14>`_.
+
+**********
+ See also
+**********
+
+- `PyPA Code of Conduct <https://www.pypa.io/en/latest/code-of-conduct/>`_
+- `Issue Tracker <https://github.com/pypa/build/issues>`_
+- `tox documentation <https://tox.wiki/>`_
+- `pytest documentation <https://docs.pytest.org/>`_
+- `ruff documentation <https://docs.astral.sh/ruff/>`_
+- `Sphinx documentation <https://www.sphinx-doc.org/>`_
+- `PyPA Discord <https://discord.gg/pypa>`_
+- `Python Packaging Discourse <https://discuss.python.org/c/packaging/14>`_
diff --git a/docs/differences.rst b/docs/differences.rst
deleted file mode 100644
index 6fbc401a..00000000
--- a/docs/differences.rst
+++ /dev/null
@@ -1,30 +0,0 @@
-============================
-Differences from other tools
-============================
-
-``pep517.build``
-----------------
-
-build implements a CLI tailored to end users.
-
-``pep517.build`` contained a proof-of-concept of a :pep:`517`
-frontend. It *"implement[ed] essentially the simplest possible frontend
-tool, to exercise and illustrate how the core functionality can be
-used"*. It has since been `deprecated and is scheduled for removal`_.
-
-``setup.py sdist bdist_wheel``
-------------------------------
-
-build is roughly the equivalent of ``setup.py sdist bdist_wheel`` but
-with :pep:`517` support, allowing use with projects that don't use setuptools.
-
-.. _deprecated and is scheduled for removal: https://github.com/pypa/pep517/pull/83
-
-Custom Behaviors
-----------------
-
-Fallback Backend
-^^^^^^^^^^^^^^^^
-
-As recommended in :pep:`517`, if no backend is specified, ``build`` will
-fallback to ``setuptools.build_meta:__legacy__``.
diff --git a/docs/explanation/build-backends.rst b/docs/explanation/build-backends.rst
new file mode 100644
index 00000000..d7bcddc2
--- /dev/null
+++ b/docs/explanation/build-backends.rst
@@ -0,0 +1,395 @@
+################
+ Build Backends
+################
+
+This document explains what build backends are, how they work with build, and how to choose the right one for your
+project.
+
+**************************
+ What is a Build Backend?
+**************************
+
+A **build backend** is a Python package that knows how to build your project into `distributable formats
+<https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ (`source distributions
+<https://packaging.python.org/en/latest/specifications/source-distribution-format/>`_ and `wheels
+<https://packaging.python.org/en/latest/specifications/binary-distribution-format/>`_). The backend implements a
+standardized interface defined in :PEP:`517`, which build (the **frontend**) uses to create your package distributions.
+
+When you run ``python -m build``, the frontend (build) reads your `pyproject.toml
+<https://packaging.python.org/en/latest/specifications/pyproject-toml/>`_ to determine which backend to use, then
+invokes that backend to perform the actual building. The separation between frontend and backend allows different
+projects to use different build systems (like `setuptools <https://setuptools.pypa.io/>`_, `hatchling
+<https://hatch.pypa.io/latest/>`_, or `flit <https://flit.pypa.io/>`_) while all working with the same frontend tool.
+
+******************************
+ How Backends Work with build
+******************************
+
+The relationship between build and backends follows a clear contract:
+
+.. mermaid::
+
+    %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#4051b5','primaryTextColor':'#fff','primaryBorderColor':'#2c3e8f','lineColor':'#5468c4','secondaryColor':'#7c8fd6','tertiaryColor':'#e8eaf6'}}}%%
+    flowchart TD
+        subgraph Frontend["Build Frontend (build)"]
+            A[CLI Interface]
+            B[Read pyproject.toml]
+            C[Create Isolation]
+            D[Invoke Hooks]
+        end
+
+        subgraph Backend["Build Backend (setuptools/hatchling/flit/...)"]
+            E[Package Discovery]
+            F[File Inclusion]
+            G[Metadata Generation]
+            H[Create Distributions]
+        end
+
+        A --> B
+        B --> C
+        C --> D
+        D -->|PEP 517 Hooks| E
+        E --> F
+        F --> G
+        G --> H
+        H -->|sdist & wheel| I[dist/]
+
+        style Frontend fill:#e8eaf6,stroke:#4051b5,color:#000
+        style Backend fill:#fff3e0,stroke:#f57c00,color:#000
+        style I fill:#2e7d32,stroke:#1b5e20,color:#fff
+
+Your ``pyproject.toml`` specifies which backend to use in the ``[build-system]`` section. For example, using hatchling
+as the backend looks like this:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["hatchling"]
+    build-backend = "hatchling.build"
+
+The ``requires`` field lists the packages needed to perform a build, which build installs in an isolated environment.
+The ``build-backend`` field specifies the Python import path to the backend object that implements the PEP 517
+interface.
+
+When building, build creates an isolated environment, installs the required packages, imports the backend module, and
+calls standardized hook functions like ``build_wheel()`` or ``build_sdist()``. The backend then creates the distribution
+files and returns their filenames.
+
+**************************
+ Available Build Backends
+**************************
+
+Several build backends are available, each with different features and philosophies.
+
+setuptools
+==========
+
+setuptools is the traditional and most widely used build backend. It has extensive features and backwards compatibility
+with older packaging standards, making it suitable for complex projects and projects that need to maintain compatibility
+with older tooling.
+
+To use setuptools, configure your ``pyproject.toml`` like this:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["setuptools>=61.0", "wheel"]
+    build-backend = "setuptools.build_meta"
+
+setuptools excels at handling complex build requirements including C extensions, namespace packages, and entry points.
+However, it can be complex to configure correctly and has many legacy features that may be confusing.
+
+See the `setuptools documentation <https://setuptools.pypa.io/>`_ for details.
+
+hatchling
+=========
+
+hatchling is the build backend from the Hatch project. It provides a modern, user-friendly interface with sensible
+defaults and good performance.
+
+To use hatchling:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["hatchling"]
+    build-backend = "hatchling.build"
+
+hatchling works well for pure Python packages and has excellent plugin support for extending functionality. It
+emphasizes convention over configuration and includes built-in support for common patterns like src-layout and editable
+installs. The main limitation is that it's newer and may have less community documentation than setuptools.
+
+See the `hatchling documentation <https://hatch.pypa.io/latest/config/build/>`_ for details.
+
+flit-core
+=========
+
+flit-core is a minimalist build backend that focuses on simplicity for pure Python packages.
+
+To use flit-core:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["flit-core>=3.2"]
+    build-backend = "flit_core.buildapi"
+
+flit-core works best for simple, pure Python packages without complex build requirements. It has minimal configuration
+and fast build times. By default, it includes all files tracked by git in the source distribution. The trade-off is
+limited support for complex scenarios like C extensions or non-standard package layouts.
+
+See the `flit documentation <https://flit.pypa.io/>`_ for details.
+
+pdm-backend
+===========
+
+pdm-backend is the build backend from the PDM project, offering modern features and good integration with PEP 621
+metadata.
+
+To use pdm-backend:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["pdm-backend"]
+    build-backend = "pdm.backend"
+
+pdm-backend provides strong PEP 621 support, good handling of dynamic metadata, and support for both pure Python and
+extension modules. It's actively developed and includes features like SCM versioning and custom build hooks.
+
+See the `pdm-backend documentation <https://pdm-backend.fming.dev/>`_ for details.
+
+poetry-core
+===========
+
+poetry-core is the build backend extracted from Poetry. It's designed primarily for use with the Poetry tool but can be
+used standalone.
+
+To use poetry-core:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["poetry-core"]
+    build-backend = "poetry.core.masonry.api"
+
+poetry-core handles pure Python packages well and integrates tightly with Poetry's ecosystem. However, configuration is
+done through Poetry's custom ``[tool.poetry]`` section rather than standard ``[project]`` metadata, which can reduce
+interoperability with other tools.
+
+See the `poetry documentation <https://python-poetry.org/>`_ for details.
+
+scikit-build-core
+=================
+
+scikit-build-core is a build backend specifically designed for projects with CMake-based C/C++ extensions.
+
+To use scikit-build-core:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["scikit-build-core"]
+    build-backend = "scikit_build_core.build"
+
+scikit-build-core provides excellent CMake integration, cross-platform compilation support, and modern PEP 621 metadata
+support. It's the recommended backend for projects using CMake for extension modules, replacing the older scikit-build.
+
+See the `scikit-build-core documentation <https://scikit-build-core.readthedocs.io/>`_ for details.
+
+meson-python
+============
+
+meson-python is a build backend for projects using the Meson build system, particularly useful for compiled extensions.
+
+To use meson-python:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["meson-python"]
+    build-backend = "mesonpy"
+
+meson-python offers fast builds, excellent cross-platform support, and good integration with Meson's dependency
+management. It's especially strong for projects with complex compiled components and is increasingly popular in the
+scientific Python ecosystem.
+
+See the `meson-python documentation <https://meson-python.readthedocs.io/>`_ for details.
+
+********************
+ Choosing a Backend
+********************
+
+The right backend depends on your project's needs. For simple pure Python packages, flit-core or hatchling provide
+straightforward configuration and fast builds. Projects that need extensive customization or have complex requirements
+often benefit from setuptools' mature feature set and extensive documentation.
+
+If your project includes C or C++ extensions built with CMake, scikit-build-core is the natural choice. For projects
+using Meson for compilation, meson-python provides the best integration. Projects already using Poetry might prefer
+poetry-core for consistency, though this limits interoperability with other tools.
+
+New projects without special requirements should consider hatchling or flit-core for their modern approach and
+simplicity. Existing projects using setuptools can continue doing so, as it remains well-maintained and
+feature-complete.
+
+**********************
+ Configuring Backends
+**********************
+
+Each backend has its own configuration approach. Modern backends use the ``[project]`` section of ``pyproject.toml`` for
+metadata following PEP 621. Backend-specific settings go in a ``[tool.backend-name]`` section.
+
+For example, with hatchling you might have:
+
+.. code-block:: toml
+
+    [project]
+    name = "mypackage"
+    version = "1.0.0"
+
+    [tool.hatch.build]
+    include = ["src/**/*.py"]
+
+With setuptools:
+
+.. code-block:: toml
+
+    [project]
+    name = "mypackage"
+    version = "1.0.0"
+
+    [tool.setuptools.packages.find]
+    where = ["src"]
+
+Always consult your backend's documentation for configuration options. Common configuration needs include specifying
+which files to include, where to find packages, how to handle version numbers, and how to process extension modules.
+
+*****************************
+ Passing Options to Backends
+*****************************
+
+build allows passing configuration settings to backends via the ``--config-setting`` or ``-C`` flag. The syntax and
+available options depend entirely on the backend.
+
+For example, with setuptools you might pass build options:
+
+.. code-block:: console
+
+    $ python -m build -C--build-option=--build-number=123
+
+With scikit-build-core, you can configure CMake:
+
+.. code-block:: console
+
+    $ python -m build -Ccmake.define.BUILD_TESTING=OFF
+
+Each backend interprets these settings differently. See :doc:`../how-to/config-settings` for backend-specific examples.
+
+******************
+ Dynamic Metadata
+******************
+
+Some backends support generating metadata dynamically at build time. Common use cases include reading version numbers
+from git tags, generating file lists from directory contents, or computing dependencies based on environment.
+
+Most backends support version from SCM (source control management). For example, with hatchling using hatch-vcs:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["hatchling", "hatch-vcs"]
+    build-backend = "hatchling.build"
+
+    [tool.hatch.version]
+    source = "vcs"
+
+The backend reads version information from git tags during the build. This keeps version numbers in sync between git and
+your package without manual updates.
+
+Dynamic metadata is powerful but has trade-offs. It can make builds less reproducible if not carefully managed, and it
+may prevent installation from sdists if the dynamic information source (like git) isn't available.
+
+********************************
+ Backend Extensions and Plugins
+********************************
+
+Many backends support plugins to extend functionality. setuptools has an extensive plugin ecosystem including plugins
+for namespace packages, entry points, and custom build steps. hatchling has a plugin system for custom build hooks,
+version sources, and metadata providers.
+
+When choosing a backend, consider whether you need extensibility through plugins. If your project has unique build
+requirements, a backend with a strong plugin system may be beneficial even if it's more complex to configure initially.
+
+********************
+ Switching Backends
+********************
+
+Switching from one backend to another is possible but requires care. The main steps involve updating your
+``[build-system]`` section in ``pyproject.toml``, migrating configuration from the old backend's format to the new one,
+and testing that the built distributions are equivalent.
+
+When migrating, always build and inspect both sdist and wheel to verify all files are included correctly. Test
+installation from both distribution types. Check that metadata (version, dependencies, entry points) is correctly
+preserved.
+
+Most migrations involve moving from setuptools to a modern backend. The new backend's documentation typically includes
+migration guides. Common challenges include differences in how package discovery works, how data files are included, and
+how version numbers are specified.
+
+*********************
+ Backend Development
+*********************
+
+For most users, using an existing backend is the right choice. However, if you have unique requirements not met by any
+existing backend, you can implement your own PEP 517 backend.
+
+A minimal backend must implement these functions in a Python module:
+
+.. code-block:: python
+
+    def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
+        # Build wheel, return filename
+        pass
+
+
+    def build_sdist(sdist_directory, config_settings=None):
+        # Build sdist, return filename
+        pass
+
+Implementing a full-featured backend requires handling metadata extraction, dependency specification, editable installs,
+and error handling. Unless you have very specialized needs, contributing to an existing backend or using its plugin
+system is usually more practical than creating a new one.
+
+***********************************************
+ Why setuptools commands don't work with build
+***********************************************
+
+If you're migrating from ``setup.py``, you may be used to running commands like:
+
+.. code-block:: console
+
+    $ python setup.py clean
+    $ python setup.py test
+    $ python setup.py develop
+
+**These commands do not work with build**: build uses the PEP 517 interface, which only defines hooks for building
+distributions (``build_wheel`` and ``build_sdist``). It does not support arbitrary setuptools commands.
+
+**Modern alternatives**:
+
+- **clean**: Remove the ``dist/`` directory manually or let your CI do it
+- **test**: Use ``pytest`` directly or via ``tox``
+- **develop**: Use ``pip install --editable .`` for editable installs
+- **sdist/bdist_wheel**: Use ``python -m build``
+
+If you need custom build steps, implement them in your build backend's hooks or use a plugin system. For example,
+setuptools supports ``setup.py`` with custom build steps that run during the PEP 517 build process.
+
+**********
+ See also
+**********
+
+- :doc:`how-it-works` for how build invokes backends
+- :doc:`../how-to/config-settings` for backend-specific configuration examples
+- `PEP 517 <https://peps.python.org/pep-0517/>`_ for the backend interface specification
+- `PEP 621 <https://peps.python.org/pep-0621/>`_ for standard project metadata
diff --git a/docs/explanation/how-it-works.rst b/docs/explanation/how-it-works.rst
new file mode 100644
index 00000000..2f20f14b
--- /dev/null
+++ b/docs/explanation/how-it-works.rst
@@ -0,0 +1,369 @@
+##############
+ How it Works
+##############
+
+This document explains how build works internally and the build process flow.
+
+*******************
+ The Build Process
+*******************
+
+When you run ``python -m build``, the following happens:
+
+.. mermaid::
+
+    %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#4051b5','primaryTextColor':'#fff','primaryBorderColor':'#2c3e8f','lineColor':'#5468c4','secondaryColor':'#7c8fd6','tertiaryColor':'#e8eaf6'}}}%%
+    flowchart TD
+        A[Run python -m build] --> B[Read pyproject.toml]
+        B --> C{Isolated build?}
+        C -->|Yes default| D[Create temporary venv]
+        C -->|--no-isolation| E[Use current environment]
+        D --> F[Install build dependencies]
+        E --> F
+        F --> G[Invoke build backend hooks]
+        G --> H{Build what?}
+        H -->|Default| I[Build sdist]
+        I --> J[Extract sdist to temp dir]
+        J --> K[Build wheel from sdist]
+        H -->|--sdist| L[Build sdist only]
+        H -->|--wheel| M[Build wheel from source]
+        K --> N[Output to dist/]
+        L --> N
+        M --> N
+        N --> O[Cleanup temporary environment]
+        O --> P[Done]
+
+        style A fill:#4051b5,stroke:#2c3e8f,color:#fff
+        style P fill:#2e7d32,stroke:#1b5e20,color:#fff
+        style N fill:#f57c00,stroke:#e65100,color:#fff
+        style D fill:#7c8fd6,stroke:#5468c4,color:#fff
+        style G fill:#7c8fd6,stroke:#5468c4,color:#fff
+
+The process in detail:
+
+1. **Read pyproject.toml**
+
+   build reads your project's `pyproject.toml <https://packaging.python.org/en/latest/specifications/pyproject-toml/>`_
+   to determine:
+
+   - Which **build backend** to use (from ``[build-system]`` section)
+   - What dependencies the backend needs (``requires`` list)
+   - Build backend configuration (``backend-path`` if specified)
+
+2. **Create isolated environment** (default behavior)
+
+   build creates a temporary `virtual environment <https://docs.python.org/3/tutorial/venv.html>`_ to ensure
+   reproducible builds:
+
+   - Creates a fresh virtualenv in a temporary directory
+   - Sets ``VIRTUAL_ENV`` `environment variable <https://docs.python.org/3/library/venv.html#how-venvs-work>`_
+   - Installs the build backend and its dependencies via `pip <https://pip.pypa.io/>`_
+
+   This isolation ensures your build doesn't depend on what's installed in your development environment, making builds
+   reproducible across different machines.
+
+3. **Invoke build backend hooks**
+
+   build calls standardized hooks (functions) in your **build backend**:
+
+   - For source distributions: calls ``build_sdist(sdist_directory, config_settings=None)``
+   - For wheels: calls ``build_wheel(wheel_directory, config_settings=None, metadata_directory=None)``
+
+   These hooks are defined in :PEP:`517` (the build system interface standard).
+
+4. **Build artifacts**
+
+   The backend creates `distribution files
+   <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_:
+
+   - **Source distribution (sdist)**: A `tarball
+     <https://packaging.python.org/en/latest/specifications/source-distribution-format/>`_ (``package-version.tar.gz``)
+     containing your source code
+   - **Wheel**: A `zip file <https://packaging.python.org/en/latest/specifications/binary-distribution-format/>`_
+     (``package-version-py3-none-any.whl``) that can be installed directly
+
+5. **Cleanup**
+
+   build removes the temporary isolated environment, leaving only the distribution files in ``dist/``.
+
+************************
+ Default Build Strategy
+************************
+
+By default, ``python -m build`` creates both sdist and wheel following this strategy:
+
+1. Build sdist from source directory
+2. Extract sdist to temporary directory
+3. Build wheel from the extracted sdist
+
+This "build wheel from sdist" strategy ensures your sdist is complete. If files are missing from the sdist, the wheel
+build will fail, alerting you to the problem.
+
+***************************
+ Build Isolation Explained
+***************************
+
+Why isolation matters
+=====================
+
+Without isolation, builds can be non-reproducible. Different developers have different packages installed, and CI
+environments may have different packages than local development. Upgrading a package in your dev environment could break
+builds, and you might accidentally depend on a package that's not declared. Isolation solves this by creating a clean
+environment for every build.
+
+How isolation works
+===================
+
+1. build creates a temporary virtual environment using Python's ``venv`` module
+2. Installs only the packages listed in ``[build-system] requires``
+3. Runs the build backend in this isolated environment
+4. Deletes the environment after building
+
+The isolated environment has access to the Python standard library, the build backend and its dependencies, and nothing
+from your development environment except environment variables.
+
+When to disable isolation
+=========================
+
+Use ``--no-isolation`` only when:
+
+- You're in an offline/air-gapped environment and have pre-installed dependencies
+- You're debugging build issues and need to inspect the environment
+- You're a Linux distribution packager providing dependencies externally
+- You understand the reproducibility implications
+
+See :doc:`../how-to/basic-usage` for usage.
+
+***********************************
+ Build Frontends vs Build Backends
+***********************************
+
+build is a **build frontend** that reads ``pyproject.toml``, creates isolated environments, invokes build backends, and
+handles the command-line interface. It does NOT know how to build your specific package.
+
+Your **build backend** (setuptools, hatchling, flit, etc.) knows how to build your package by implementing PEP 517
+hooks. The backend handles package discovery, file inclusion, metadata generation, and creates the actual sdist and
+wheel files.
+
+This separation of concerns allows different backends for different project needs, ensures frontend improvements benefit
+all backends, and allows backend improvements to work with all frontends.
+
+See :doc:`build-backends` for more details.
+
+*********************
+ PEP 517 Integration
+*********************
+
+build implements :PEP:`517` (the standardized build system interface that defines how build tools communicate with
+backends). The key concepts:
+
+Build system table
+==================
+
+Your `pyproject.toml <https://packaging.python.org/en/latest/specifications/pyproject-toml/>`_ must have a
+``[build-system]`` section:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["hatchling"]
+    build-backend = "hatchling.build"
+
+- ``requires``: Packages needed to build (installed in isolated environment)
+- ``build-backend``: Python import path to backend object
+
+Backend hooks
+=============
+
+build calls these standardized hooks in your backend:
+
+- ``get_requires_for_build_sdist(config_settings)`` - Returns additional dependencies needed for sdist
+- ``build_sdist(sdist_directory, config_settings)`` - Creates sdist, returns filename
+- ``get_requires_for_build_wheel(config_settings)`` - Returns additional dependencies needed for wheel
+- ``build_wheel(wheel_directory, config_settings, metadata_directory)`` - Creates wheel, returns filename
+
+Optional hooks:
+
+- ``prepare_metadata_for_build_wheel(metadata_directory, config_settings)`` - Generates wheel metadata without full
+  build
+
+Config settings
+===============
+
+The ``config_settings`` parameter in hooks receives settings from ``--config-setting`` / ``-C`` flags.
+
+build converts:
+
+.. code-block:: console
+
+    $ python -m build -C key=value
+
+Into:
+
+.. code-block:: python
+
+    config_settings = {"key": "value"}
+
+The backend interprets these settings. See :doc:`../how-to/config-settings` for examples.
+
+*********************
+ Metadata Extraction
+*********************
+
+build can extract package metadata without a full build:
+
+.. code-block:: console
+
+    $ python -m build --metadata
+
+This:
+
+1. Creates isolated environment
+2. Calls ``prepare_metadata_for_build_wheel()`` if available
+3. Otherwise, calls ``build_wheel()`` and extracts metadata
+4. Outputs metadata in JSON format to stdout
+
+Useful for tools that need package metadata without building the full package.
+
+****************
+ Error Handling
+****************
+
+build performs minimal error handling:
+
+- Validates ``pyproject.toml`` exists and is valid TOML
+- Checks ``[build-system]`` section exists
+- Verifies backend is importable
+- Checks hook return values are valid
+
+Most error handling is delegated to the backend. If the backend fails, build reports the error and exits.
+
+This keeps build simple and focused on its role as a frontend.
+
+*********************
+ Installer Selection
+*********************
+
+By default, build uses pip to install dependencies in isolated environments. You can use a different installer:
+
+.. code-block:: console
+
+    $ python -m build --installer=uv
+
+Requirements for custom installers:
+
+- Must accept ``install`` command
+- Must accept package specifications as arguments
+- Must support ``--no-deps`` flag
+
+Currently, pip and uv are the primary supported installers.
+
+*****************************
+ Virtual Environment Backend
+*****************************
+
+build can use different virtual environment implementations:
+
+- ``venv`` (default): Python's built-in venv module
+- ``virtualenv``: Third-party virtualenv package
+
+To use virtualenv:
+
+.. code-block:: console
+
+    $ pip install build[virtualenv]
+    $ python -m build
+
+virtualenv provides better SSL support on older Python versions, faster environment creation, and more features (though
+build uses only basic functionality).
+
+See :doc:`../how-to/corporate-environments` for when this matters.
+
+****************************
+ Output Directory Structure
+****************************
+
+By default, build places files in ``dist/`` within your source directory:
+
+.. code-block:: text
+
+    myproject/
+    ├── dist/
+    │   ├── myproject-1.0.0.tar.gz      # sdist
+    │   └── myproject-1.0.0-py3-none-any.whl  # wheel
+    ├── src/
+    │   └── myproject/
+    │       └── __init__.py
+    └── pyproject.toml
+
+Use ``--outdir`` to change the output location:
+
+.. code-block:: console
+
+    $ python -m build --outdir /tmp/build-output
+
+*******************************
+ Environment Variable Handling
+*******************************
+
+build passes most environment variables to the build backend:
+
+**Always passed**:
+
+- ``PATH`` - For finding executables
+- ``PYTHONPATH`` - For Python module discovery
+- HTTP/HTTPS proxy variables
+- SSL certificate variables
+- Custom pip variables (``PIP_*``)
+
+**Set by build**:
+
+- ``VIRTUAL_ENV`` - Points to isolated environment (when using isolation)
+
+**When using ``--no-isolation``**:
+
+- All environment variables from your shell are passed through unchanged
+
+This behavior allows corporate environments to configure pip via environment variables, build backends to use custom
+environment variables, and proxy and SSL configuration to work transparently.
+
+See :doc:`../reference/environment-variables` for details.
+
+*********************
+ Reproducible Builds
+*********************
+
+build aims for reproducible builds by:
+
+1. **Isolated environments**: Same dependencies every time
+2. **Declared dependencies**: ``[build-system] requires`` is explicit
+3. **Standardized interface**: PEP 517 hooks are well-defined
+4. **Minimal intervention**: build doesn't modify your code or backend behavior
+
+However, full reproducibility also requires pinned backend versions in ``requires``, reproducible builds in your backend
+(some backends support ``SOURCE_DATE_EPOCH``), consistent Python version, and consistent platform for platform-specific
+wheels.
+
+****************************
+ Performance Considerations
+****************************
+
+Build time is dominated by:
+
+1. **Environment creation**: Creating virtualenv (1-2 seconds)
+2. **Dependency installation**: Installing backend and dependencies (varies)
+3. **Backend build**: Actual package building (varies greatly)
+
+Ways to speed up builds include using ``--installer=uv`` for faster dependency installation, using ``--no-isolation`` if
+dependencies are pre-installed (loses reproducibility), installing ``build[virtualenv]`` for faster environment
+creation, and using ``--wheel`` to skip sdist when not needed.
+
+The default (isolation with pip) prioritizes reproducibility over speed.
+
+**********
+ See also
+**********
+
+- :doc:`build-backends` for choosing and configuring backends
+- `PEP 517 <https://peps.python.org/pep-0517/>`_ for the build system specification
+- `PEP 518 <https://peps.python.org/pep-0518/>`_ for the ``pyproject.toml`` specification
diff --git a/docs/how-to/basic-usage.rst b/docs/how-to/basic-usage.rst
new file mode 100644
index 00000000..ddcddeb2
--- /dev/null
+++ b/docs/how-to/basic-usage.rst
@@ -0,0 +1,321 @@
+#############
+ Basic Usage
+#############
+
+This guide covers the most common build commands and workflows.
+
+********************************************************
+ Building both source and wheel distributions (default)
+********************************************************
+
+By default, build creates both a `source distribution
+<https://packaging.python.org/en/latest/specifications/source-distribution-format/>`_ (often called "sdist") and a
+`wheel <https://packaging.python.org/en/latest/specifications/binary-distribution-format/>`_:
+
+.. code-block:: console
+
+    $ python -m build
+
+The process:
+
+1. Builds the source distribution from your source code
+2. Extracts the source distribution to a temporary directory
+3. Builds the wheel from the extracted source distribution
+
+This two-step process ensures your source distribution contains all necessary files to build your package. If files are
+missing, the wheel build will fail, alerting you to the problem.
+
+This is different from ``python -m build --sdist --wheel``, which builds both directly from source. The default behavior
+is preferable because it verifies your sdist is complete.
+
+***********************
+ Building only a wheel
+***********************
+
+.. code-block:: console
+
+    $ python -m build --wheel
+
+Or the short form:
+
+.. code-block:: console
+
+    $ python -m build -w
+
+This builds the `wheel <https://packaging.python.org/en/latest/specifications/binary-distribution-format/>`_
+(installable package) directly from your source directory, skipping the source distribution step. This is faster but
+doesn't verify your source distribution is complete.
+
+*************************************
+ Building only a source distribution
+*************************************
+
+.. code-block:: console
+
+    $ python -m build --sdist
+
+Or the short form:
+
+.. code-block:: console
+
+    $ python -m build -s
+
+*********************************
+ Specifying the source directory
+*********************************
+
+Build defaults to the current directory. To build from a different location:
+
+.. code-block:: console
+
+    $ python -m build path/to/project
+
+Or explicitly:
+
+.. code-block:: console
+
+    $ python -m build --srcdir path/to/project
+
+*********************************
+ Specifying the output directory
+*********************************
+
+By default, distributions are placed in ``dist/`` within the source directory. To use a different location:
+
+.. code-block:: console
+
+    $ python -m build --outdir /path/to/output
+
+Or the short form:
+
+.. code-block:: console
+
+    $ python -m build -o /path/to/output
+
+***********************
+ Controlling verbosity
+***********************
+
+Increase verbosity to see more details:
+
+.. code-block:: console
+
+    $ python -m build -v
+
+Or even more verbose:
+
+.. code-block:: console
+
+    $ python -m build -vv
+
+Decrease verbosity for quieter output:
+
+.. code-block:: console
+
+    $ python -m build -q
+
+**************************
+ Using a faster installer
+**************************
+
+By default, build uses `pip <https://pip.pypa.io/>`_ to install build dependencies. For faster builds, use `uv
+<https://docs.astral.sh/uv/>`_ (a faster alternative to pip):
+
+.. code-block:: console
+
+    $ python -m build --installer=uv
+
+This requires uv to be installed:
+
+.. code-block:: console
+
+    $ pip install uv
+
+****************************
+ Building without isolation
+****************************
+
+By default, build creates an `isolated environment
+<https://packaging.python.org/en/latest/glossary/#term-Isolated-Build>`_ (a clean temporary `virtual environment
+<https://docs.python.org/3/tutorial/venv.html>`_) to ensure reproducible builds. To skip this and use your current
+environment:
+
+.. code-block:: console
+
+    $ python -m build --no-isolation
+
+Or the short form:
+
+.. code-block:: console
+
+    $ python -m build -n
+
+.. warning::
+
+    When using ``--no-isolation``, you must manually install all build dependencies. This is mainly useful for:
+
+    - Offline or air-gapped environments (no internet access)
+    - Debugging build issues
+    - Linux distribution packaging where dependencies are provided externally
+
+****************************
+ Skipping dependency checks
+****************************
+
+To skip checking if build dependencies are installed (requires ``--no-isolation``):
+
+.. code-block:: console
+
+    $ python -m build --no-isolation --skip-dependency-check
+
+Or:
+
+.. code-block:: console
+
+    $ python -m build -nx
+
+******************
+ Common workflows
+******************
+
+Development build
+=================
+
+Quick build during development:
+
+.. code-block:: console
+
+    $ python -m build --wheel --installer=uv
+
+Fast CI build
+=============
+
+In CI where dependencies are pre-installed:
+
+.. code-block:: console
+
+    $ pip install build build-backend-here
+    $ python -m build --no-isolation
+
+Release build
+=============
+
+For uploading to `PyPI <https://pypi.org/>`_, build both sdist and wheel:
+
+.. tab:: uv
+
+    .. code-block:: console
+
+        $ python -m build
+        $ uv publish
+
+    `uv publish <https://docs.astral.sh/uv/guides/publish/>`_ is a modern option that handles uploading to PyPI with built-in support for trusted publishing.
+
+.. tab:: twine
+
+    .. code-block:: console
+
+        $ python -m build
+        $ twine check dist/*
+        $ twine upload dist/*
+
+    See the `twine documentation <https://twine.readthedocs.io/>`_ for upload options.
+
+.. tip::
+
+    Use the ``hynek/build-and-inspect-python-package`` GitHub Action which handles this workflow including verification.
+    See :doc:`ci-cd`.
+
+Testing the sdist
+=================
+
+Build from the sdist to ensure it's complete:
+
+.. code-block:: console
+
+    $ python -m build --sdist
+    $ python -m build --wheel dist/mypackage-1.0.0.tar.gz
+
+Or test installation:
+
+.. code-block:: console
+
+    $ python -m build
+    $ python -m pip install dist/mypackage-1.0.0.tar.gz
+    $ python -c "import mypackage; print(mypackage.__version__)"
+
+***********************
+ Cleaning before build
+***********************
+
+There's no built-in clean command. To ensure a fresh build, manually remove the dist directory:
+
+.. code-block:: console
+
+    $ rm -rf dist/
+    $ python -m build
+
+Or to avoid stale artifacts, use a unique output directory:
+
+.. code-block:: console
+
+    $ python -m build --outdir dist/v1.0.0
+
+***********************************
+ Getting metadata without building
+***********************************
+
+To extract package metadata without building the full package:
+
+.. code-block:: console
+
+    $ python -m build --metadata
+
+This outputs the wheel metadata in JSON format to stdout.
+
+****************************
+ Checking the build version
+****************************
+
+To see which version of build you're using:
+
+.. code-block:: console
+
+    $ python -m build --version
+
+************************************
+ Installing build dependencies only
+************************************
+
+For specialized workflows like static analysis or linting, you may want to install just the build dependencies without
+actually building:
+
+.. code-block:: python
+
+    from build import ProjectBuilder
+
+    builder = ProjectBuilder(".")
+
+    # Get all build dependencies
+    requires = builder.build_system_requires
+    for dist in ["sdist", "wheel"]:
+        requires.extend(builder.get_requires_for_build(dist))
+
+    # Install them
+    import subprocess
+
+    subprocess.run(["pip", "install", *requires])
+
+This is useful when you need the same environment that build would create, but want to run other tools (like mypy, ruff,
+or custom linters) instead of building the package.
+
+See :doc:`../reference/api` for more programmatic usage examples.
+
+**********
+ See also
+**********
+
+- :doc:`config-settings` for passing options to your build backend
+- :doc:`corporate-environments` for using build with private indexes
+- :doc:`troubleshooting` for common problems
+- :doc:`../reference/cli` for all command-line options
diff --git a/docs/how-to/choosing-tools.rst b/docs/how-to/choosing-tools.rst
new file mode 100644
index 00000000..8f3d973a
--- /dev/null
+++ b/docs/how-to/choosing-tools.rst
@@ -0,0 +1,312 @@
+######################
+ build vs Other Tools
+######################
+
+The Python packaging ecosystem has several tools that work together. This guide helps you understand when to use build
+versus other tools.
+
+*******************
+ When to use build
+*******************
+
+Use build when you want to:
+
+- Create distribution packages (`source distributions
+  <https://packaging.python.org/en/latest/specifications/source-distribution-format/>`_ and/or `wheels
+  <https://packaging.python.org/en/latest/specifications/binary-distribution-format/>`_) for your project
+- Build for your **current Python version and platform** only
+- Create packages to upload to `PyPI <https://pypi.org/>`_
+- Test that your package builds correctly
+- Build as part of a development workflow
+
+Build is a **build frontend** - it knows how to invoke :std:term:`build backends <Build Backend>` (`setuptools
+<https://setuptools.pypa.io/>`_, `hatchling <https://hatch.pypa.io/latest/>`_, `flit <https://flit.pypa.io/>`_, etc.)
+but doesn't handle testing, multi-version builds, or task automation.
+
+.. code-block:: console
+
+    $ python -m build
+
+This builds your package for the currently active Python interpreter.
+
+**************************
+ When to use cibuildwheel
+**************************
+
+Use `cibuildwheel <https://cibuildwheel.readthedocs.io/>`_ when you need to build `wheels
+<https://packaging.python.org/en/latest/specifications/binary-distribution-format/>`_ for **multiple Python versions and
+platforms**:
+
+- Building wheels for distribution on `PyPI <https://pypi.org/>`_
+- Supporting Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14
+- Supporting multiple operating systems (Linux, macOS, Windows)
+- Building `manylinux <https://peps.python.org/pep-0513/>`_/`musllinux <https://peps.python.org/pep-0656/>`_ wheels
+  (standardized Linux wheel formats)
+- Building wheels with compiled extensions (C, C++, Rust, etc.)
+
+cibuildwheel uses build under the hood but handles all the complexity of:
+
+- Running builds in `manylinux containers <https://github.com/pypa/manylinux>`_
+- Testing wheels after building
+- Handling platform-specific quirks
+- Proper `ABI tagging <https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/>`_
+
+Example ``.github/workflows/build.yml``:
+
+.. code-block:: yaml
+
+    name: Build
+
+    on: [push, pull_request]
+
+    jobs:
+      build_wheels:
+        name: Build wheels on ${{ matrix.os }}
+        runs-on: ${{ matrix.os }}
+        strategy:
+          matrix:
+            os: [ubuntu-latest, windows-latest, macos-latest]
+
+        steps:
+          - uses: actions/checkout@v4
+          - uses: pypa/cibuildwheel@v2.17
+          - uses: actions/upload-artifact@v4
+            with:
+              name: wheels
+              path: ./wheelhouse/*.whl
+
+See `cibuildwheel documentation <https://cibuildwheel.readthedocs.io/>`_ for complete details.
+
+*****************
+ When to use tox
+*****************
+
+Use `tox <https://tox.wiki/>`_ when you need to:
+
+- Test your package across multiple Python versions (e.g., 3.9, 3.10, 3.11)
+- Run tests in `isolated environments <https://packaging.python.org/en/latest/glossary/#term-Virtual-Environment>`_
+- Automate testing workflows
+- Run linters (code checkers), formatters, type checkers
+- Build documentation
+- Orchestrate multiple development tasks
+
+Example ``tox.toml``:
+
+.. code-block:: toml
+
+    [env_run_base]
+    description = "run test suite with {basepython}"
+    deps = [
+        "pytest",
+        "pytest-cov",
+    ]
+    commands = [
+        ["pytest", "tests"],
+    ]
+
+    [env.build]
+    description = "build the package"
+    deps = ["build"]
+    commands = [["python", "-m", "build"]]
+
+    [env.lint]
+    description = "run linters and type checkers"
+    deps = [
+        "ruff",
+        "mypy",
+    ]
+    commands = [
+        ["ruff", "check", "."],
+        ["mypy", "src"],
+    ]
+
+Tox can call build to create distributions, but its main purpose is test automation.
+
+See `tox documentation <https://tox.wiki/>`_ for complete details.
+
+*****************
+ When to use nox
+*****************
+
+Use `nox <https://nox.thea.codes/>`_ when you want tox-like functionality but prefer Python over INI:
+
+Example ``noxfile.py``:
+
+.. code-block:: python
+
+    import nox
+
+
+    @nox.session(python=["3.8", "3.9", "3.10", "3.11", "3.12"])
+    def tests(session):
+        session.install("pytest", "pytest-cov")
+        session.run("pytest", "tests")
+
+
+    @nox.session
+    def build(session):
+        session.install("build")
+        session.run("python", "-m", "build")
+
+See `nox documentation <https://nox.thea.codes/>`_ for complete details.
+
+****************
+ When to use uv
+****************
+
+Use `uv <https://docs.astral.sh/uv/>`_ when you want:
+
+- Fast package installation (faster than pip)
+- Workspace management (monorepos with multiple packages)
+- Combined dependency resolution and installation
+- Modern Python packaging workflows
+
+uv can also build packages:
+
+.. code-block:: console
+
+    $ uv build
+
+This is equivalent to ``python -m build --installer=uv``.
+
+See `uv documentation <https://docs.astral.sh/uv/>`_ for complete details.
+
+*****************
+ When to use pip
+*****************
+
+Use pip when you need to:
+
+- **Install** packages (not build them)
+- Install from PyPI or other indexes
+- Install in editable mode for development
+- Manage dependencies in your environment
+
+pip can build packages as a side effect of installation, but for explicit building, use build.
+
+.. code-block:: console
+
+    # Installing (use pip)
+    $ pip install mypackage
+
+    # Installing in editable mode (use pip)
+    $ pip install -e .
+
+    # Building distributions (use build)
+    $ python -m build
+
+************************
+ How they work together
+************************
+
+A typical complete workflow might use all these tools:
+
+Development workflow
+====================
+
+.. code-block:: console
+
+    # Install your package in editable mode
+    $ pip install -e .[dev]
+
+    # Run tests across Python versions
+    $ tox
+
+    # Build distributions
+    $ python -m build
+
+    # Upload to PyPI
+    $ twine upload dist/*
+
+CI/CD workflow
+==============
+
+.. code-block:: yaml
+
+    name: CI
+
+    on: [push, pull_request]
+
+    jobs:
+      test:
+        runs-on: ubuntu-latest
+        strategy:
+          matrix:
+            python: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        steps:
+          - uses: actions/checkout@v4
+          - uses: actions/setup-python@v5
+            with:
+              python-version: ${{ matrix.python }}
+          - run: pip install tox
+          - run: tox -e py
+
+      build:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+          - uses: hynek/build-and-inspect-python-package@v2
+
+      build_wheels:
+        runs-on: ${{ matrix.os }}
+        strategy:
+          matrix:
+            os: [ubuntu-latest, windows-latest, macos-latest]
+        steps:
+          - uses: actions/checkout@v4
+          - uses: pypa/cibuildwheel@v2.17
+
+This workflow:
+
+1. Uses **tox** to test across Python versions
+2. Uses **build** (via hynek's action) to create sdist
+3. Uses **cibuildwheel** to create wheels for all platforms
+
+***************
+ Decision tree
+***************
+
+.. mermaid::
+
+    %%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#4051b5','primaryTextColor':'#fff','primaryBorderColor':'#2c3e8f','lineColor':'#5468c4','secondaryColor':'#7c8fd6','tertiaryColor':'#e8eaf6'}}}%%
+    flowchart TD
+        A[What do you need to do?] --> B{Build a package?}
+        B -->|Yes| C{For how many platforms?}
+        B -->|No, just testing| D{Multiple Python versions?}
+        B -->|No, just installing| E[Use pip or uv]
+
+        C -->|Current platform only| F[Use python -m build]
+        C -->|Multiple platforms/versions| G[Use cibuildwheel]
+
+        D -->|Yes| H[Use tox or nox]
+        D -->|No| I[Use pytest or your test runner]
+
+        style F fill:#4051b5,stroke:#2c3e8f,color:#fff
+        style G fill:#4051b5,stroke:#2c3e8f,color:#fff
+        style H fill:#7c8fd6,stroke:#5468c4,color:#fff
+        style I fill:#7c8fd6,stroke:#5468c4,color:#fff
+        style E fill:#f57c00,stroke:#e65100,color:#fff
+
+*****************
+ Quick reference
+*****************
+
+============ ================================ ==============================
+Tool         Purpose                          Use for
+============ ================================ ==============================
+build        Build sdist/wheel for one Python Creating distributions
+cibuildwheel Build wheels for all platforms   Distributing on PyPI
+tox          Test across Python versions      CI/testing automation
+nox          Like tox, but Python-based       CI/testing automation
+uv           Fast package manager             Installing + optional building
+pip          Package installer                Installing packages
+twine        Upload to PyPI                   Publishing
+============ ================================ ==============================
+
+**********
+ See also
+**********
+
+- :doc:`basic-usage` for build command examples
+- :doc:`ci-cd` for CI/CD integration
+- :doc:`../explanation/build-backends` to understand build vs backend
diff --git a/docs/how-to/ci-cd.rst b/docs/how-to/ci-cd.rst
new file mode 100644
index 00000000..b91bc69b
--- /dev/null
+++ b/docs/how-to/ci-cd.rst
@@ -0,0 +1,590 @@
+###################
+ CI/CD Integration
+###################
+
+This guide shows how to integrate build into your continuous integration and deployment workflows.
+
+****************
+ GitHub Actions
+****************
+
+Using hynek's build-and-inspect-python-package
+==============================================
+
+The recommended way to build and verify packages in `GitHub Actions <https://docs.github.com/en/actions>`_ is using the
+`hynek/build-and-inspect-python-package <https://github.com/hynek/build-and-inspect-python-package>`_ action. This
+action builds your package, inspects it for common issues, and provides the built artifacts.
+
+.. code-block:: yaml
+
+    name: Build
+
+    on: [push, pull_request]
+
+    jobs:
+      build:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+          - uses: hynek/build-and-inspect-python-package@v2
+
+This action automatically:
+
+- Builds both sdist and wheel
+- Verifies the sdist contains all necessary files
+- Checks for common packaging issues
+- Uploads artifacts for download
+- Works with any PEP 517 build backend
+
+For more details, see the `action documentation <https://github.com/hynek/build-and-inspect-python-package>`_.
+
+Manual build with isolation
+===========================
+
+If you need more control, use build directly with isolated environments. ``pipx`` is pre-installed on all GitHub Actions
+runners:
+
+.. code-block:: yaml
+
+    name: Build
+
+    on: [push, pull_request]
+
+    jobs:
+      build:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+
+          - uses: actions/setup-python@v5
+            with:
+              python-version: "3.12"
+
+          - name: Build package
+            run: pipx run build
+
+          - name: Upload artifacts
+            uses: actions/upload-artifact@v4
+            with:
+              name: dist
+              path: dist/
+
+Fast builds with pre-installed dependencies
+===========================================
+
+For faster CI builds, pre-install build dependencies and use ``--no-isolation``:
+
+.. code-block:: yaml
+
+    name: Fast Build
+
+    on: [push, pull_request]
+
+    jobs:
+      build:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+
+          - uses: actions/setup-python@v5
+            with:
+              python-version: "3.12"
+
+          - name: Install dependencies
+            run: |
+              pip install build hatchling  # Replace hatchling with your backend
+
+          - name: Build package
+            run: python -m build --no-isolation
+
+Using uv for faster builds
+==========================
+
+Use uv as the installer for faster dependency installation:
+
+.. code-block:: yaml
+
+    name: Build with uv
+
+    on: [push, pull_request]
+
+    jobs:
+      build:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+
+          - uses: actions/setup-python@v5
+            with:
+              python-version: "3.12"
+
+          - name: Install uv and build
+            run: pip install uv build
+
+          - name: Build package
+            run: python -m build --installer=uv
+
+Matrix builds across Python versions
+====================================
+
+Test building with multiple Python versions:
+
+.. code-block:: yaml
+
+    name: Build Matrix
+
+    on: [push, pull_request]
+
+    jobs:
+      build:
+        runs-on: ubuntu-latest
+        strategy:
+          matrix:
+            python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+
+        steps:
+          - uses: actions/checkout@v4
+
+          - uses: actions/setup-python@v5
+            with:
+              python-version: ${{ matrix.python-version }}
+
+          - name: Install build
+            run: pip install build
+
+          - name: Build package
+            run: python -m build
+
+Building wheels for multiple platforms
+======================================
+
+For packages with C extensions or platform-specific code, use cibuildwheel:
+
+.. code-block:: yaml
+
+    name: Build Wheels
+
+    on: [push, pull_request]
+
+    jobs:
+      build_wheels:
+        name: Build wheels on ${{ matrix.os }}
+        runs-on: ${{ matrix.os }}
+        strategy:
+          matrix:
+            os: [ubuntu-latest, windows-latest, macos-13, macos-14]
+
+        steps:
+          - uses: actions/checkout@v4
+
+          - uses: pypa/cibuildwheel@v2.17
+
+          - uses: actions/upload-artifact@v4
+            with:
+              name: wheels-${{ matrix.os }}
+              path: ./wheelhouse/*.whl
+
+      build_sdist:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+          - uses: hynek/build-and-inspect-python-package@v2
+
+See :doc:`choosing-tools` for when to use build vs cibuildwheel.
+
+Publishing to PyPI
+==================
+
+Combine building and publishing in a release workflow using the `PyPA publish action
+<https://github.com/pypa/gh-action-pypi-publish>`_:
+
+.. code-block:: yaml
+
+    name: Publish
+
+    on:
+      release:
+        types: [published]
+
+    jobs:
+      build:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+          - uses: hynek/build-and-inspect-python-package@v2
+
+      publish:
+        needs: build
+        runs-on: ubuntu-latest
+        permissions:
+          id-token: write
+        steps:
+          - uses: actions/download-artifact@v4
+            with:
+              name: Packages
+              path: dist
+
+          - uses: pypa/gh-action-pypi-publish@release/v1
+
+***********
+ GitLab CI
+***********
+
+Basic build
+===========
+
+.. code-block:: yaml
+
+    build:
+      image: python:3.12
+      script:
+        - pip install build
+        - python -m build
+      artifacts:
+        paths:
+          - dist/
+
+With caching
+============
+
+Cache pip packages to speed up builds:
+
+.. code-block:: yaml
+
+    build:
+      image: python:3.12
+      cache:
+        paths:
+          - .cache/pip
+      variables:
+        PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+      script:
+        - pip install build
+        - python -m build
+      artifacts:
+        paths:
+          - dist/
+
+Fast builds with pre-installed dependencies
+===========================================
+
+.. code-block:: yaml
+
+    build:
+      image: python:3.12
+      script:
+        - pip install build hatchling
+        - python -m build --no-isolation
+      artifacts:
+        paths:
+          - dist/
+
+Matrix builds
+=============
+
+.. code-block:: yaml
+
+    .build_template:
+      script:
+        - pip install build
+        - python -m build
+      artifacts:
+        paths:
+          - dist/
+
+    build:py38:
+      extends: .build_template
+      image: python:3.8
+
+    build:py39:
+      extends: .build_template
+      image: python:3.9
+
+    build:py312:
+      extends: .build_template
+      image: python:3.12
+
+**********
+ CircleCI
+**********
+
+Basic build
+===========
+
+.. code-block:: yaml
+
+    version: 2.1
+
+    jobs:
+      build:
+        docker:
+          - image: cimg/python:3.12
+        steps:
+          - checkout
+          - run:
+              name: Install build
+              command: pip install build
+          - run:
+              name: Build package
+              command: python -m build
+          - store_artifacts:
+              path: dist/
+
+    workflows:
+      build_workflow:
+        jobs:
+          - build
+
+***********
+ Travis CI
+***********
+
+Basic build
+===========
+
+.. code-block:: yaml
+
+    language: python
+    python:
+      - "3.8"
+      - "3.9"
+      - "3.10"
+      - "3.11"
+      - "3.12"
+
+    install:
+      - pip install build
+
+    script:
+      - python -m build
+
+*****************
+ Azure Pipelines
+*****************
+
+Basic build
+===========
+
+.. code-block:: yaml
+
+    trigger:
+      - main
+
+    pool:
+      vmImage: 'ubuntu-latest'
+
+    strategy:
+      matrix:
+        Python38:
+          python.version: '3.8'
+        Python312:
+          python.version: '3.12'
+
+    steps:
+    - task: UsePythonVersion@0
+      inputs:
+        versionSpec: '$(python.version)'
+
+    - script: |
+        pip install build
+        python -m build
+      displayName: 'Build package'
+
+    - task: PublishBuildArtifacts@1
+      inputs:
+        pathToPublish: 'dist'
+        artifactName: 'dist'
+
+*********
+ Jenkins
+*********
+
+Declarative pipeline
+====================
+
+.. code-block:: groovy
+
+    pipeline {
+        agent any
+
+        stages {
+            stage('Build') {
+                steps {
+                    sh '''
+                        python3 -m pip install build
+                        python3 -m build
+                    '''
+                }
+            }
+            stage('Archive') {
+                steps {
+                    archiveArtifacts artifacts: 'dist/*', fingerprint: true
+                }
+            }
+        }
+    }
+
+********
+ Docker
+********
+
+Multi-stage build
+=================
+
+Build packages in a Docker container:
+
+.. code-block:: dockerfile
+
+    FROM python:3.12-slim AS builder
+
+    WORKDIR /app
+
+    COPY pyproject.toml README.md ./
+    COPY src/ src/
+
+    RUN pip install build && python -m build
+
+    # Runtime image
+    FROM python:3.12-slim
+
+    COPY --from=builder /app/dist/*.whl /tmp/
+    RUN pip install /tmp/*.whl && rm /tmp/*.whl
+
+    CMD ["python"]
+
+*****************
+ tox Integration
+*****************
+
+Using build within tox environments:
+
+.. code-block:: toml
+
+    [env_run_base]
+    description = "run test suite"
+    deps = ["pytest"]
+    commands = [["pytest", "tests"]]
+
+    [env.build]
+    description = "build the package"
+    deps = ["build"]
+    commands = [["python", "-m", "build"]]
+
+    [env."build-check"]
+    description = "build and check the package"
+    deps = [
+        "build",
+        "twine",
+    ]
+    commands = [
+        ["python", "-m", "build"],
+        ["twine", "check", "dist/*"],
+    ]
+
+Run the build environment:
+
+.. code-block:: console
+
+    $ tox -e build
+
+******************
+ Verifying Builds
+******************
+
+Always verify your built packages before publishing:
+
+.. code-block:: yaml
+
+    - name: Check package
+      run: |
+        pip install twine
+        twine check dist/*
+
+Or use hynek's action which includes verification automatically.
+
+********************
+ Conditional Builds
+********************
+
+Only build on specific events:
+
+.. code-block:: yaml
+
+    name: Build
+
+    on:
+      push:
+        branches: [main]
+        tags: ['v*']
+      pull_request:
+        branches: [main]
+
+    jobs:
+      build:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+          - uses: hynek/build-and-inspect-python-package@v2
+
+      publish:
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+        needs: build
+        runs-on: ubuntu-latest
+        permissions:
+          id-token: write
+        steps:
+          - uses: actions/download-artifact@v4
+          - uses: pypa/gh-action-pypi-publish@release/v1
+
+This builds on every push and PR, but only publishes when pushing a version tag.
+
+***************************
+ Troubleshooting CI Builds
+***************************
+
+Enable verbose output
+=====================
+
+Add ``-vv`` flag for debugging:
+
+.. code-block:: yaml
+
+    - name: Build package
+      run: python -m build -vv
+
+Preserve build artifacts
+========================
+
+Upload the dist directory even on failure:
+
+.. code-block:: yaml
+
+    - name: Upload artifacts
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+Cache build environments
+========================
+
+For repeated builds, cache pip's download cache:
+
+.. code-block:: yaml
+
+    - uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+
+**********
+ See also
+**********
+
+- :doc:`troubleshooting` for build-specific issues
+- :doc:`corporate-environments` for private indexes and proxies
+- :doc:`choosing-tools` for when to use build vs other tools
+- `hynek/build-and-inspect-python-package <https://github.com/hynek/build-and-inspect-python-package>`_ - Recommended
+  GitHub Action
+- `cibuildwheel <https://cibuildwheel.readthedocs.io/>`_ - For multi-platform wheel builds
diff --git a/docs/how-to/config-settings.rst b/docs/how-to/config-settings.rst
new file mode 100644
index 00000000..205750f3
--- /dev/null
+++ b/docs/how-to/config-settings.rst
@@ -0,0 +1,238 @@
+#######################
+ Backend Configuration
+#######################
+
+The ``--config-setting`` (or ``-C``) flag allows you to pass options to your **build backend**. The syntax and available
+options depend entirely on which backend you're using (e.g., `setuptools <https://setuptools.pypa.io/>`_, hatchling,
+`flit <https://flit.pypa.io/>`_).
+
+.. important::
+
+    The ``--config-setting`` flag passes options to the **build backend** that actually builds your package, not to
+    build itself. Different backends accept different options. Check your backend's documentation for available
+    settings.
+
+**************
+ Basic syntax
+**************
+
+The basic syntax is:
+
+.. code-block:: console
+
+    $ python -m build -C KEY=VALUE
+
+Or for options without values (equivalent to ``-C KEY=""``):
+
+.. code-block:: console
+
+    $ python -m build -C KEY
+
+.. note::
+
+    The ``-C KEY`` syntax (without ``=``) is supported by build but not by pip. For maximum compatibility, use ``-C
+    KEY=""`` explicitly when you need an empty value.
+
+Multiple settings can be provided:
+
+.. code-block:: console
+
+    $ python -m build -C KEY1=VALUE1 -C KEY2=VALUE2
+
+************
+ Setuptools
+************
+
+Setuptools requires a special ``--build-option`` wrapper for most settings.
+
+Build numbers
+=============
+
+To add a build number to your wheel:
+
+.. code-block:: console
+
+    $ python -m build --wheel \
+        -C--build-option=bdist_wheel \
+        -C--build-option=--build-number \
+        -C--build-option=123
+
+This creates a wheel named ``package-1.0.0-123-py3-none-any.whl``.
+
+Compiler selection
+==================
+
+To specify a compiler on Windows:
+
+.. code-block:: console
+
+    $ python -m build \
+        -C--build-option=build_ext \
+        -C--build-option=--compiler \
+        -C--build-option=mingw32
+
+.. note::
+
+    Each argument must be a separate ``-C`` flag. Setuptools processes these as separate command-line arguments.
+
+Getting help
+============
+
+To see available setuptools build options:
+
+.. code-block:: console
+
+    $ python -m build -C--build-option=--help
+
+*******************
+ scikit-build-core
+*******************
+
+scikit-build-core uses a more intuitive dotted syntax.
+
+CMake options
+=============
+
+.. code-block:: console
+
+    $ python -m build \
+        -Ccmake.define.BUILD_TESTING=OFF \
+        -Ccmake.define.CMAKE_BUILD_TYPE=Release
+
+Logging
+=======
+
+.. code-block:: console
+
+    $ python -m build -Clogging.level=INFO
+
+Install target
+==============
+
+.. code-block:: console
+
+    $ python -m build -Cinstall.strip=false
+
+Multiple options:
+
+.. code-block:: console
+
+    $ python -m build \
+        -Clogging.level=DEBUG \
+        -Ccmake.define.USE_CUDA=ON \
+        -Cinstall.components=runtime
+
+**************
+ meson-python
+**************
+
+Meson-python passes options directly to meson.
+
+Setup options
+=============
+
+.. code-block:: console
+
+    $ python -m build -Csetup-args=-Doption=value
+
+Compile options
+===============
+
+.. code-block:: console
+
+    $ python -m build \
+        -Csetup-args=-Dbuildtype=release \
+        -Csetup-args=-Db_ndebug=true
+
+***********
+ hatchling
+***********
+
+Hatchling supports various build options.
+
+Reproducible builds
+===================
+
+.. code-block:: console
+
+    $ python -m build -Creproducible=true
+
+Shared data
+===========
+
+.. code-block:: console
+
+    $ python -m build -Cshared-data=/custom/path
+
+***********
+ flit-core
+***********
+
+Flit-core has minimal configuration options as it focuses on simplicity.
+
+*************
+ poetry-core
+*************
+
+Poetry-core currently does not support configuration settings via the command line.
+
+*************************
+ Using ``--config-json``
+*************************
+
+For complex nested configuration, use ``--config-json`` instead:
+
+.. code-block:: console
+
+    $ python -m build --config-json='{"cmake": {"define": {"VAR1": "value1", "VAR2": "value2"}}}'
+
+This is particularly useful in CI/CD scripts where configuration can be generated programmatically.
+
+.. note::
+
+    ``--config-setting`` and ``--config-json`` cannot be used together.
+
+***************
+ Common Issues
+***************
+
+Options starting with hyphens
+=============================
+
+If your option starts with a hyphen, you must use the ``=`` syntax to prevent build from interpreting it as its own
+flag:
+
+.. code-block:: console
+
+    $ python -m build -C=--my-setting
+
+Not ``-C --my-setting`` which would fail.
+
+Backend not recognizing options
+===============================
+
+If your backend doesn't recognize an option:
+
+1. Check your backend's documentation for the correct syntax
+2. Verify you're using the latest version of the backend
+3. Some backends only support certain options in newer versions
+
+*******************************
+ Finding backend documentation
+*******************************
+
+- `Setuptools <https://setuptools.pypa.io/>`_
+- `scikit-build-core <https://scikit-build-core.readthedocs.io/>`_
+- `meson-python <https://meson-python.readthedocs.io/>`_
+- `hatchling <https://hatch.pypa.io/latest/config/build/>`_
+- `flit-core <https://flit.pypa.io/>`_
+- `poetry-core <https://python-poetry.org/docs/>`_
+- `pdm-backend <https://pdm-backend.fming.dev/>`_
+
+**********
+ See also
+**********
+
+- :doc:`basic-usage` for general build commands
+- :doc:`../reference/cli` for all command-line options
+- :doc:`../explanation/build-backends` to understand how backends work
diff --git a/docs/how-to/corporate-environments.rst b/docs/how-to/corporate-environments.rst
new file mode 100644
index 00000000..b48aee6e
--- /dev/null
+++ b/docs/how-to/corporate-environments.rst
@@ -0,0 +1,320 @@
+########################
+ Corporate Environments
+########################
+
+This guide covers common scenarios when using build behind corporate firewalls, with private package indexes (custom
+package repositories), or in restricted network environments.
+
+*************************
+ Private package indexes
+*************************
+
+Using a private PyPI mirror
+===========================
+
+Set the ``PIP_INDEX_URL`` `environment variable
+<https://pip.pypa.io/en/stable/topics/configuration/#environment-variables>`_ to point to your private `package index
+<https://packaging.python.org/en/latest/glossary/#term-Package-Index>`_ (an alternative to `PyPI <https://pypi.org/>`_):
+
+.. code-block:: console
+
+    $ export PIP_INDEX_URL=https://pypi.company.com/simple
+    $ python -m build
+
+Or for a single command:
+
+.. code-block:: console
+
+    $ PIP_INDEX_URL=https://pypi.company.com/simple python -m build
+
+Additional indexes
+==================
+
+To use both PyPI and a private index:
+
+.. code-block:: console
+
+    $ export PIP_INDEX_URL=https://pypi.org/simple
+    $ export PIP_EXTRA_INDEX_URL=https://pypi.company.com/simple
+    $ python -m build
+
+.. warning::
+
+    Using ``PIP_EXTRA_INDEX_URL`` has security implications. A malicious package on any index can shadow packages from
+    other indexes. Use ``PIP_INDEX_URL`` exclusively when possible.
+
+****************
+ Authentication
+****************
+
+Embedded credentials
+====================
+
+You can embed credentials directly in the index URL:
+
+.. code-block:: console
+
+    $ PIP_INDEX_URL=https://username:password@pypi.company.com/simple python -m build
+
+.. warning::
+
+    Be careful with embedded credentials in shell history and CI logs. Use environment variable substitution when
+    possible:
+
+.. code-block:: console
+
+    $ PIP_INDEX_URL=https://${PYPI_USER}:${PYPI_TOKEN}@pypi.company.com/simple python -m build
+
+Using keyring
+=============
+
+Install the keyring package to store credentials securely:
+
+.. code-block:: console
+
+    $ pip install keyring
+
+Build will automatically use keyring when available. Configure it with:
+
+.. code-block:: console
+
+    $ keyring set https://pypi.company.com username
+
+Build will prompt for the password when needed, or you can use:
+
+.. code-block:: console
+
+    $ export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring  # Disable keyring if needed
+
+Using .netrc
+============
+
+Create a ``~/.netrc`` file (``~/_netrc`` on Windows) with your credentials:
+
+.. code-block:: text
+
+    machine pypi.company.com
+    login username
+    password your-password
+
+Ensure the file has restricted permissions:
+
+.. code-block:: console
+
+    $ chmod 600 ~/.netrc
+
+**********************
+ SSL/TLS certificates
+**********************
+
+Custom CA certificates
+======================
+
+If your company uses a custom CA certificate:
+
+.. code-block:: console
+
+    $ export REQUESTS_CA_BUNDLE=/path/to/company-ca-bundle.crt
+    $ python -m build
+
+Or use pip's certificate option:
+
+.. code-block:: console
+
+    $ export PIP_CERT=/path/to/company-ca-bundle.crt
+    $ python -m build
+
+Self-signed certificates
+========================
+
+For development environments with self-signed certificates (not recommended for production):
+
+.. code-block:: console
+
+    $ export PIP_TRUSTED_HOST=pypi.company.com
+    $ python -m build
+
+Using virtualenv for better SSL support
+=======================================
+
+If you encounter SSL/TLS errors with Python's built-in venv, install virtualenv:
+
+.. code-block:: console
+
+    $ pip install build[virtualenv]
+
+This provides a more recent version of pip with better SSL support and truststore capabilities.
+
+.. note::
+
+    Python 3.11.8+ and 3.12.2+ have improved SSL support and may not need this workaround.
+
+***************
+ Proxy servers
+***************
+
+HTTP/HTTPS proxies
+==================
+
+Configure proxy environment variables:
+
+.. code-block:: console
+
+    $ export HTTP_PROXY=http://proxy.company.com:8080
+    $ export HTTPS_PROXY=http://proxy.company.com:8080
+    $ python -m build
+
+With authentication:
+
+.. code-block:: console
+
+    $ export HTTP_PROXY=http://user:pass@proxy.company.com:8080
+    $ export HTTPS_PROXY=http://user:pass@proxy.company.com:8080
+
+No proxy for certain hosts
+==========================
+
+.. code-block:: console
+
+    $ export NO_PROXY=localhost,127.0.0.1,.company.com
+    $ python -m build
+
+*************************
+ pip configuration files
+*************************
+
+Global configuration
+====================
+
+Instead of environment variables, you can create a pip configuration file.
+
+On Linux/macOS (``~/.config/pip/pip.conf``):
+
+.. code-block:: ini
+
+    [global]
+    index-url = https://pypi.company.com/simple
+    trusted-host = pypi.company.com
+    cert = /path/to/company-ca-bundle.crt
+
+On Windows (``%APPDATA%\\pip\\pip.ini``):
+
+.. code-block:: ini
+
+    [global]
+    index-url = https://pypi.company.com/simple
+    trusted-host = pypi.company.com
+    cert = C:\\path\\to\\company-ca-bundle.crt
+
+Per-project configuration
+=========================
+
+Create a ``pip.conf`` file in your project directory. This is useful for team settings.
+
+*************************
+ Air-gapped environments
+*************************
+
+For completely offline builds, you must manually install dependencies first:
+
+.. code-block:: console
+
+    $ pip install setuptools wheel your-build-backend
+    $ python -m build --no-isolation
+
+The ``--no-isolation`` flag tells build to use your current environment instead of creating an isolated one.
+
+.. warning::
+
+    When using ``--no-isolation``, ensure all build dependencies are installed and compatible.
+
+********************
+ CI/CD environments
+********************
+
+GitHub Actions
+==============
+
+.. code-block:: yaml
+
+    - name: Build package
+      run: python -m build
+      env:
+        PIP_INDEX_URL: ${{ secrets.PYPI_INDEX_URL }}
+        PIP_CERT: /path/to/cert.crt
+
+GitLab CI
+=========
+
+.. code-block:: yaml
+
+    build:
+      script:
+        - export PIP_INDEX_URL=$PYPI_INDEX_URL
+        - python -m build
+
+***************************
+ Catching backend warnings
+***************************
+
+To catch deprecation warnings from your build backend (useful in CI):
+
+.. code-block:: console
+
+    $ PYTHONWARNINGS=error::DeprecationWarning python -m build
+
+Or for setuptools specifically:
+
+.. code-block:: console
+
+    $ PYTHONWARNINGS=error:::setuptools.config.setupcfg python -m build
+
+See :doc:`troubleshooting` for more details on warnings.
+
+***************
+ Common issues
+***************
+
+Build hangs waiting for input
+=============================
+
+If build appears to hang, it may be waiting for authentication. This happens when pip prompts for credentials but the
+prompt is hidden.
+
+Solution: Use one of the authentication methods above (embedded credentials, keyring, or .netrc).
+
+401/403 errors
+==============
+
+Authentication failed. Verify your credentials and ensure they have access to the required packages.
+
+SSL verification failed
+=======================
+
+Your system doesn't trust the certificate. Use ``REQUESTS_CA_BUNDLE`` or ``PIP_CERT`` to provide the CA certificate, or
+install ``build[virtualenv]`` for better SSL support.
+
+Conda environment conflicts
+===========================
+
+If you're in a conda environment and experiencing venv creation issues:
+
+.. code-block:: console
+
+    $ conda deactivate
+    $ python -m build
+
+Or use virtualenv:
+
+.. code-block:: console
+
+    $ pip install build[virtualenv]
+    $ python -m build
+
+**********
+ See also
+**********
+
+- :doc:`troubleshooting` for more problem-solving tips
+- :doc:`../reference/environment-variables` for a complete list of environment variables
+- `pip documentation <https://pip.pypa.io/>`_ for more pip configuration options
diff --git a/docs/how-to/install.rst b/docs/how-to/install.rst
new file mode 100644
index 00000000..174aad73
--- /dev/null
+++ b/docs/how-to/install.rst
@@ -0,0 +1,106 @@
+##############
+ Installation
+##############
+
+******************
+ Installing build
+******************
+
+The recommended way to install build is using `uv <https://docs.astral.sh/uv/>`_, but you can also install it via `pip
+<https://pip.pypa.io/>`_ or `pipx <https://pipx.pypa.io/>`_:
+
+.. tab:: uv
+
+    .. code-block:: console
+
+        $ uv tool install build
+
+.. tab:: pipx
+
+    .. code-block:: console
+
+        $ pipx install build
+
+.. tab:: pip
+
+    .. code-block:: console
+
+        $ pip install build
+
+Optional Dependencies
+=====================
+
+build supports optional extras for different use cases:
+
+- ``build[virtualenv]`` - Use `virtualenv <https://virtualenv.pypa.io/>`_ for isolation instead of `venv
+  <https://docs.python.org/3/library/venv.html>`_. This can be useful when using automation tools that rely on
+  virtualenv (such as `tox <https://tox.wiki/>`_), or when your operating system's Python package does not include venv
+  in the standard installation.
+
+  .. code-block:: console
+
+      $ pip install 'build[virtualenv]'
+
+- ``build[uv]`` - Bundle `uv <https://docs.astral.sh/uv/>`_ for use with ``--installer=uv`` if you don't have another
+  install of uv available.
+
+  .. code-block:: console
+
+      $ pip install 'build[uv]'
+
+************************
+ Verifying Attestations
+************************
+
+`Attestations <https://github.com/pypa/build/attestations>`_ are available after 1.2.1 and can be verified with the
+``gh`` CLI tool:
+
+.. code-block:: sh
+
+    $ python -m pip --no-cache-dir download --no-deps build
+    $ gh attestation verify build*.whl --repo pypa/build
+
+`PEP 740 <https://peps.python.org/pep-0740/>`_ has been accepted. Support for PEP 740 attestations in build is being
+tracked in :issue:`987`.
+
+**********************
+ Installing via conda
+**********************
+
+On conda-forge, this package is called python-build_, therefore it can be installed via conda_ or an equivalent:
+
+.. code-block:: sh
+
+    $ conda install conda-forge::python-build
+
+***************
+ Bootstrapping
+***************
+
+This package can build itself only with the `tomli <https://github.com/hukkin/tomli>`_ (can be omitted in Python 3.11+)
+and `pyproject-hooks <https://github.com/pypa/pyproject-hooks>`_ dependencies. The ``--skip-dependency-check`` flag
+should be used in this case.
+
+***************
+ Compatibility
+***************
+
+``build`` is verified to be compatible with the following Python versions:
+
+- 3.9
+- 3.10
+- 3.11
+- 3.12
+- 3.13
+- 3.14
+- PyPy 3.9
+- PyPy 3.10
+- PyPy 3.11
+
+.. _conda: https://github.com/conda/conda
+
+.. _python-build: https://github.com/conda-forge/python-build-feedstock
+
+.. |3DCE51D60930EBA47858BA4146F633CBB0EB4BF2| replace:: ``3DCE51D60930EBA47858BA4146F633CBB0EB4BF2``
+
+.. _3dce51d60930eba47858ba4146f633cbb0eb4bf2: https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x3dce51d60930eba47858ba4146f633cbb0eb4bf2
diff --git a/docs/how-to/troubleshooting.rst b/docs/how-to/troubleshooting.rst
new file mode 100644
index 00000000..223ef76a
--- /dev/null
+++ b/docs/how-to/troubleshooting.rst
@@ -0,0 +1,440 @@
+#################
+ Troubleshooting
+#################
+
+This guide helps you resolve common issues when using build.
+
+***************************************
+ Build fails with missing dependencies
+***************************************
+
+**Symptom**: Build fails with errors like "ModuleNotFoundError" or "No module named 'X'".
+
+**Cause**: Your build backend or its dependencies aren't installed in the isolated environment.
+
+**Solution 1**: Let build handle it automatically (default):
+
+.. code-block:: console
+
+    $ python -m build
+
+Build will read your ``pyproject.toml`` and install all required dependencies.
+
+**Solution 2**: If using ``--no-isolation``, manually install dependencies:
+
+.. code-block:: console
+
+    $ pip install setuptools your-build-backend
+    $ python -m build --no-isolation
+
+*******************************
+ Build hangs or appears frozen
+*******************************
+
+**Symptom**: Build command runs but produces no output for a long time.
+
+**Possible causes**:
+
+1. **Waiting for authentication**: If you're using a private package index, build may be waiting for credentials.
+
+   See :doc:`corporate-environments` for authentication setup.
+
+2. **Large download**: Build backend dependencies are being downloaded.
+
+   Use ``-v`` or ``-vv`` for verbose output:
+
+   .. code-block:: console
+
+       $ python -m build -vv
+
+3. **Build backend is actually running**: Some backends (especially for C extensions) can take time.
+
+   Check system monitor for CPU/disk activity to confirm work is happening.
+
+*************************************
+ SSL certificate verification failed
+*************************************
+
+**Symptom**: Errors like "SSL: CERTIFICATE_VERIFY_FAILED" or "certificate verify failed".
+
+**Cause**: Your system doesn't trust the SSL certificate of the package index.
+
+**Solution 1**: Provide the CA certificate (recommended):
+
+.. code-block:: console
+
+    $ export PIP_CERT=/path/to/company-ca-bundle.crt
+    $ python -m build
+
+**Solution 2**: Use build with virtualenv for better SSL support:
+
+.. code-block:: console
+
+    $ pip install build[virtualenv]
+    $ python -m build
+
+**Solution 3**: For development only, disable verification (not recommended):
+
+.. code-block:: console
+
+    $ export PIP_TRUSTED_HOST=pypi.company.com
+    $ python -m build
+
+See :doc:`corporate-environments` for more details.
+
+**************************
+ Permission denied errors
+**************************
+
+**Symptom**: "PermissionError" or "Access is denied" when creating directories or files.
+
+**Common causes**:
+
+1. **Output directory is protected**: The ``dist/`` directory is owned by another user or process.
+
+   Solution: Remove the directory first or use a different output location:
+
+   .. code-block:: console
+
+       $ rm -rf dist/
+       $ python -m build
+
+   Or:
+
+   .. code-block:: console
+
+       $ python -m build --outdir /tmp/my-build
+
+2. **Running inside a read-only directory**: The source directory is on a read-only filesystem.
+
+   Solution: Copy the source to a writable location first.
+
+3. **Antivirus software**: Some antivirus tools block Python from creating virtual environments.
+
+   Solution: Add Python and your project directory to antivirus exclusions.
+
+********************************************
+ Wheel is not compatible with this platform
+********************************************
+
+**Symptom**: "is not a supported wheel on this platform" when trying to install the built wheel.
+
+**Cause**: The wheel was built for a different Python version or platform.
+
+**Solution**: Build on the same platform and Python version where you'll install, or use cibuildwheel for multi-platform
+builds.
+
+See :doc:`choosing-tools` for when to use cibuildwheel vs build.
+
+*********************************************
+ Build succeeds but package is missing files
+*********************************************
+
+**Symptom**: After building, the package installs but is missing source files, data files, or modules.
+
+**Cause**: Files aren't included in the source distribution manifest.
+
+**Solution**: The fix depends on your build backend:
+
+**For setuptools** (`setuptools documentation <https://setuptools.pypa.io/>`_):
+
+Add a ``MANIFEST.in`` file or use ``package_data`` in ``pyproject.toml``:
+
+.. code-block:: toml
+
+    [tool.setuptools.package-data]
+    mypackage = ["data/*.json", "templates/*.html"]
+
+**For hatchling** (`hatchling documentation <https://hatch.pypa.io/latest/config/build/>`_):
+
+Use the ``include`` and ``exclude`` options:
+
+.. code-block:: toml
+
+    [tool.hatch.build.targets.wheel]
+    include = [
+        "src/**/*.py",
+        "src/**/*.json",
+    ]
+
+**For flit** (`flit documentation <https://flit.pypa.io/>`_):
+
+Flit includes all files tracked by `git <https://git-scm.com/>`_ by default. Ensure files are committed.
+
+**Test your sdist**: Always verify the sdist contains all necessary files:
+
+.. code-block:: console
+
+    $ python -m build --sdist
+    $ tar -tzf dist/mypackage-1.0.0.tar.gz
+
+****************************************
+ ModuleNotFoundError in the built wheel
+****************************************
+
+**Symptom**: The wheel installs successfully, but importing the package fails with "ModuleNotFoundError".
+
+**Cause**: The package structure in your source doesn't match what the build backend expects.
+
+**Common issues**:
+
+1. **Missing ``__init__.py``**: Ensure every package directory has an ``__init__.py`` file (not needed for namespace
+   packages).
+2. **Wrong directory structure**: For src-layout, ensure you have ``src/packagename/`` not just ``packagename/``.
+3. **Not configuring package discovery**: Tell your build backend where to find packages.
+
+   For setuptools with src-layout:
+
+   .. code-block:: toml
+
+       [tool.setuptools.packages.find]
+       where = ["src"]
+
+*********************************************
+ Version conflict between build dependencies
+*********************************************
+
+**Symptom**: Build fails with errors about conflicting package versions.
+
+**Cause**: Build dependencies have incompatible version requirements.
+
+**Solution 1**: Update your build backend and its dependencies:
+
+.. code-block:: console
+
+    $ pip install --upgrade pip setuptools
+
+Then try building again:
+
+.. code-block:: console
+
+    $ python -m build
+
+**Solution 2**: If using ``--no-isolation``, create a fresh virtual environment:
+
+.. code-block:: console
+
+    $ python -m venv fresh-env
+    $ source fresh-env/bin/activate  # On Windows: fresh-env\\Scripts\\activate
+    $ pip install build
+    $ python -m build
+
+The isolated build (without ``--no-isolation``) avoids this issue by creating a clean environment each time.
+
+*************************************
+ Build works locally but fails in CI
+*************************************
+
+**Common causes**:
+
+1. **Different Python versions**: CI may use a different Python version than your local environment.
+
+   Solution: Specify Python version in CI config, test locally with that version.
+
+2. **Missing system dependencies**: C extensions may need system libraries.
+
+   Solution: Install required libraries in CI before building:
+
+   .. code-block:: yaml
+
+       # GitHub Actions example
+       - name: Install system dependencies
+         run: |
+           sudo apt-get update
+           sudo apt-get install -y libffi-dev
+
+3. **File path issues**: Windows vs Unix path separators.
+
+   Solution: Use ``pathlib.Path`` in ``pyproject.toml`` configurations and build scripts.
+
+4. **Git not available**: Some backends use git for version detection.
+
+   Solution: Ensure git is installed in CI, or use explicit versioning in ``pyproject.toml``.
+
+See :doc:`ci-cd` for CI-specific guidance.
+
+*******************************
+ Catching deprecation warnings
+*******************************
+
+To catch warnings from your build backend in CI:
+
+.. code-block:: console
+
+    $ PYTHONWARNINGS=error::DeprecationWarning python -m build
+
+Or for setuptools specifically:
+
+.. code-block:: console
+
+    $ PYTHONWARNINGS=error:::setuptools.config.setupcfg python -m build
+
+This fails the build if deprecated features are used, helping you catch issues early.
+
+*************************
+ Build backend not found
+*************************
+
+**Symptom**: "Backend 'X' is not available" or "No module named 'X'".
+
+**Cause**: The build backend specified in ``pyproject.toml`` isn't installed.
+
+**Solution**: This shouldn't happen with isolated builds (the default). If you see this:
+
+1. Check your ``pyproject.toml`` ``[build-system]`` section is correct:
+
+   .. code-block:: toml
+
+       [build-system]
+       requires = ["hatchling"]
+       build-backend = "hatchling.build"
+
+2. If using ``--no-isolation``, install the backend:
+
+   .. code-block:: console
+
+       $ pip install hatchling
+       $ python -m build --no-isolation
+
+*******************************************
+ No build-system section in pyproject.toml
+*******************************************
+
+**Symptom**: Build succeeds but you're not sure which backend is being used.
+
+**Cause**: No ``[build-system]`` section is specified in ``pyproject.toml``.
+
+**Solution**: As recommended in :PEP:`517`, if no backend is specified, build will fallback to
+``setuptools.build_meta:__legacy__``. This is for backward compatibility with older projects. For new projects,
+explicitly specify your build backend:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["hatchling"]
+    build-backend = "hatchling.build"
+
+This makes your build configuration explicit and avoids relying on the fallback behavior.
+
+***************************************
+ Build installed in user site-packages
+***************************************
+
+**Symptom**: Virtual environment creation fails with errors like "executable /usr/local/bin/python missing".
+
+**Cause**: When build is installed in the user site-packages (``pip install --user build``), it can interfere with
+isolated environment creation.
+
+**Solution**: Install build in a virtual environment instead:
+
+.. code-block:: console
+
+    $ python -m venv build-env
+    $ source build-env/bin/activate  # On Windows: build-env\\Scripts\\activate
+    $ pip install build
+    $ python -m build
+
+Or use ``pipx`` to install build in isolation:
+
+.. code-block:: console
+
+    $ pipx install build
+    $ pipx run build
+
+***************************************************
+ Package name has dashes but wheel has underscores
+***************************************************
+
+**Symptom**: Your package is named ``my-package`` but the wheel is ``my_package-1.0.0-py3-none-any.whl``.
+
+**This is expected behavior**: According to `PEP 427 <https://peps.python.org/pep-0427/>`_, wheel filenames normalize
+package names by replacing dashes with underscores. This is not a bug.
+
+Your users can still install with either name:
+
+.. code-block:: console
+
+    $ pip install my-package    # Works
+    $ pip install my_package    # Also works
+
+The package metadata preserves your original name, only the filename is normalized.
+
+**************************
+ Getting more information
+**************************
+
+Verbose output
+==============
+
+Use ``-v`` or ``-vv`` for detailed output:
+
+.. code-block:: console
+
+    $ python -m build -v      # Verbose
+    $ python -m build -vv     # Very verbose
+
+This shows what build is doing and can help identify where failures occur.
+
+Check your configuration
+========================
+
+Verify your ``pyproject.toml`` is valid:
+
+.. code-block:: console
+
+    $ python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb')))"
+
+Test the build backend directly
+===============================
+
+You can test if your build backend works independently:
+
+.. code-block:: console
+
+    $ pip install your-build-backend
+    $ python -m your_build_backend
+
+Preserve build logs and temporary directories
+=============================================
+
+By default, build cleans up the temporary build directory after completion. To control where the temporary directory is
+created (useful for debugging or placing it on a specific filesystem):
+
+.. code-block:: console
+
+    $ TMPDIR=/tmp/debug-build python -m build
+
+The build will create its temporary environment inside ``/tmp/debug-build``. The directory is automatically cleaned up
+after a successful build, but persists if the build fails, allowing you to inspect the environment for debugging. On
+Windows, use ``TEMP`` instead of ``TMPDIR``:
+
+.. code-block:: console
+
+    $ set TEMP=C:\debug-build
+    $ python -m build
+
+To see backend logs in real-time, use verbose output:
+
+.. code-block:: console
+
+    $ python -m build -vv
+
+This shows all output from the build backend, including compilation logs for C extensions and detailed error messages.
+
+**********************
+ Still having issues?
+**********************
+
+If your issue isn't covered here:
+
+1. Check the `issue tracker <https://github.com/pypa/build/issues>`_ for similar problems
+2. Enable verbose output (``-vv``) and include the full output when reporting issues
+3. Include your ``pyproject.toml`` and Python version when asking for help
+
+**********
+ See also
+**********
+
+- :doc:`corporate-environments` for proxy, SSL, and authentication issues
+- :doc:`ci-cd` for CI/CD-specific problems
+- :doc:`../reference/environment-variables` for environment variables that affect build
diff --git a/docs/index.rst b/docs/index.rst
index 1ce74d96..93e0d413 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,57 +1,108 @@
-:hide-toc:
-
 *****
 build
 *****
 
-A simple, correct Python packaging :std:term:`build frontend <Build Frontend>`.
+A simple, correct `Python packaging <https://packaging.python.org/>`_ **build frontend**.
+
+build reads your project's `pyproject.toml configuration file <https://packaging.python.org/en/latest/specifications/pyproject-toml/>`_ and invokes **build backends** to create `distribution packages <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_—the files you upload to `PyPI <https://pypi.org/>`_ or install with pip. It focuses solely on building packages and does not manage dependencies or virtual environments.
+
+Mission Statement
+=================
+
+Many Python tools combine multiple capabilities into one project. For example, pip_ both installs packages and can build them. While convenient, this tight coupling isn't always desirable. Some users need standalone build tools for custom environments (outside PyPI_), or they manage packages themselves (like Linux distributions do).
+
+This project fills that gap by providing a standalone build tool following modern Python packaging standards for how build tools communicate with backends and how ``pyproject.toml`` defines build requirements.
+
+We keep dependencies minimal to make build easy to install and use in restricted environments.
+
+Differences from other tools
+=============================
+
+Thanks to standardization, all compliant build frontends produce the same outputs (`source distributions <https://packaging.python.org/en/latest/specifications/source-distribution-format/>`_ and `wheels <https://packaging.python.org/en/latest/specifications/binary-distribution-format/>`_) from the same project. The differences are mainly in scope, dependencies, and extra features.
+
+``uv build``
+------------
+
+`uv build <https://docs.astral.sh/uv/>`_ is essentially equivalent to ``python -m build --installer=uv``. Both follow packaging standards. build offers features like ``--config-json`` for passing complex nested configuration to backends, and the pip installer works on systems that don't have pre-compiled uv wheels.
+
+``setup.py sdist bdist_wheel``
+-------------------------------
+
+build is the modern equivalent of ``setup.py sdist bdist_wheel``, supporting any backend — not just `setuptools <https://setuptools.pypa.io/>`_.
+
+``hatch build``
+---------------
+
+`hatch build <https://hatch.pypa.io/>`_ is the build command from the Hatch project management tool. It provides a convenient wrapper around the build process as part of the larger Hatch ecosystem for managing Python projects, while build is a standalone tool focused solely on building.
 
-build manages ``pyproject.toml``-based builds, invoking
-:std:term:`build-backend <Build Backend>` hooks as appropriate to build a
-:std:term:`distribution package <Distribution Package>`.
-It is a simple build tool and does not perform any dependency management.
+``flit build``
+--------------
 
-.. sphinx_argparse_cli::
-  :module: build.__main__
-  :func: main_parser
-  :prog: python -m build
-  :title: python -m build
-  :usage_width: 97
+`flit build <https://flit.pypa.io/>`_ is the build command from the Flit project. One important difference: flit-core produces slightly different source distributions when built by flit itself compared to other frontends. Using build (or any standards-compliant frontend) ensures consistent outputs regardless of the backend.
 
-.. note::
+``cibuildwheel``
+----------------
 
-   A ``pyproject-build`` CLI script is also available, so that tools such as pipx_
-   can use it.
+`cibuildwheel <https://cibuildwheel.pypa.io/>`_ is a different kind of tool. While build creates a single wheel for the current platform, cibuildwheel orchestrates building wheels across many platforms and Python versions in CI. It actually calls a build frontend (like build or pip) internally for each platform. Use build to create a pure-Python wheel or a single native wheel; use cibuildwheel when you need to produce native wheels for many platforms.
 
-By default build will build the package in an isolated
-environment, but this behavior can be disabled with ``--no-isolation``.
+Where to start
+==============
+
+**First time using build?** Start with the :doc:`tutorial/getting-started` to create your first package.
+
+**Need to solve a specific problem?** Check the :doc:`how-to/basic-usage` for common workflows, or browse the how-to guides below for your specific scenario.
+
+**Looking for technical details?** The :doc:`reference/cli` documents all command-line options, and the :doc:`reference/api` covers the Python API.
+
+**Want to understand how it works?** Read :doc:`explanation/how-it-works` to learn about the build process and isolation.
 
 .. toctree::
+   :caption: Tutorial
    :hidden:
 
-   mission
-   differences
+   tutorial/getting-started
 
 .. toctree::
-   :caption: Usage
+   :caption: How-to Guides
    :hidden:
 
-   installation
-   changelog
-   api
+   how-to/install
+   how-to/basic-usage
+   how-to/choosing-tools
+   how-to/ci-cd
+   how-to/corporate-environments
+   how-to/config-settings
+   how-to/troubleshooting
+
+.. toctree::
+   :caption: Reference
+   :hidden:
+
+   reference/cli
+   reference/api
+   reference/environment-variables
 
 .. toctree::
-   :caption: Contributing
+   :caption: Explanation
    :hidden:
 
-   test_suite
-   release
+   explanation/how-it-works
+   explanation/build-backends
 
 .. toctree::
-   :caption: Project Links
+   :caption: Development
    :hidden:
 
+   development/contributing
+
+.. toctree::
+   :caption: Project
+   :hidden:
+
+   changelog
    Source Code <https://github.com/pypa/build/>
    Issue Tracker <https://github.com/pypa/build/issues>
 
+.. _pip: https://github.com/pypa/pip
+.. _PyPI: https://pypi.org/
 .. _pipx: https://github.com/pipxproject/pipx
diff --git a/docs/installation.rst b/docs/installation.rst
deleted file mode 100644
index 7137f8eb..00000000
--- a/docs/installation.rst
+++ /dev/null
@@ -1,93 +0,0 @@
-============
-Installation
-============
-
-Installing via pip
-==================
-
-``build`` can be installed via `pip`_ or an equivalent:
-
-.. code-block:: sh
-
-   $ pip install build
-
-You can also check out the latest `git tag`_, download a tarball_ from GitHub, or
-manually fetch the artifacts from the `project page`_ on PyPI. `Attestations
-<https://github.com/pypa/build/attestations>`_ are available after 1.2.1 and
-can be verified with the ``gh`` CLI tool:
-
-.. code-block:: sh
-
-   $ python -m pip --no-cache-dir download --no-deps build
-   $ gh attestation verify build*.whl --repo pypa/build
-
-Build plans to support `PEP 740 <https://peps.python.org/pep-0740>`_ if
-accepted.
-
-.. tip::
-   If you prefer, or are already using virtualenv_ in your workflow, you can
-   install ``build`` with the optional ``virtualenv`` dependency:
-
-   .. code-block:: sh
-
-      $ pip install 'build[virtualenv]'
-
-   this way, ``build`` will use virtualenv_ for isolation, instead of venv_.
-   This can be particularly useful, for example, when using automation tools
-   that rely on virtualenv_, such as tox_, or when your operating system's
-   Python package does not include venv_ in the standard installation (such as
-   some versions of Ubuntu).
-
-   There is also a ``uv`` extra, which can be used for ``--installer=uv`` if
-   you don't have another install of ``uv`` available.
-
-Installing via conda
-====================
-
-On conda-forge, this package is called python-build_, therefore it can be installed via `conda`_ or an equivalent:
-
-.. code-block:: sh
-
-   $ conda install conda-forge::python-build
-
-Bootstrapping
-=============
-
-This package can build itself only with the ``tomli`` (can be omitted in Python 3.11+)
-and ``pyproject-hooks`` dependencies.
-The ``--skip-dependency-check`` flag should be used in this case.
-
-Compatibility
-=============
-
-``build`` is verified to be compatible with the following Python
-versions:
-
-- 3.9
-- 3.10
-- 3.11
-- 3.12
-- 3.13
-- PyPy3
-
-
-.. _pipx: https://github.com/pipxproject/pipx
-.. _pip: https://github.com/pypa/pip
-.. _PyPI: https://pypi.org/
-
-.. _tox: https://tox.readthedocs.org/
-.. _virtualenv: https://virtualenv.pypa.io
-.. _venv: https://docs.python.org/3/library/venv.html
-
-.. _python-build: https://github.com/conda-forge/python-build-feedstock
-.. _conda: https://github.com/conda/conda
-
-.. _tarball: https://github.com/pypa/build/releases
-.. _git tag: https://github.com/pypa/build/tags
-.. _project page: https://pypi.org/project/build/
-
-.. _tomli: https://github.com/hukkin/tomli
-
-
-.. |3DCE51D60930EBA47858BA4146F633CBB0EB4BF2| replace:: ``3DCE51D60930EBA47858BA4146F633CBB0EB4BF2``
-.. _3DCE51D60930EBA47858BA4146F633CBB0EB4BF2: https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x3dce51d60930eba47858ba4146f633cbb0eb4bf2
diff --git a/docs/mission.rst b/docs/mission.rst
deleted file mode 100644
index bffaf550..00000000
--- a/docs/mission.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-=================
-Mission Statement
-=================
-
-In the Python ecosystem, the build system tools and the package management
-are very intertwined. While it might be useful for users to be able to access
-all these capabilities in a single project (such as pip_), there are several
-use cases where this is not desirable. The main being custom environments
-(outside PyPI_) or situations where users do their own package management,
-such as Linux distributions.
-
-This project aims to fit the "building packages hole" for such use-cases in
-:pep:`517`/:pep:`518` workflows.
-
-As it is intended to be used by users that do their own package management,
-we will try to keep dependencies to a minimum, in order to try make
-bootstrapping easier.
-
-.. _pip: https://github.com/pypa/pip
-.. _PyPI: https://pypi.org/
diff --git a/docs/reference/api.rst b/docs/reference/api.rst
new file mode 100644
index 00000000..003400fb
--- /dev/null
+++ b/docs/reference/api.rst
@@ -0,0 +1,123 @@
+###################
+ API Documentation
+###################
+
+build provides a Python API for programmatic use in build tools, CI systems, and automation scripts.
+
+.. note::
+
+    Most API examples below require the build backend to be installed in the current environment. Either install the
+    backend manually (for ``--no-isolation`` workflows) or use isolated environments as shown in the examples.
+
+*************
+ Basic Usage
+*************
+
+Building a package programmatically:
+
+.. code-block:: python
+
+    from build import ProjectBuilder
+
+    builder = ProjectBuilder("path/to/project")
+    builder.build("wheel", "dist/")
+
+Building both sdist and wheel:
+
+.. code-block:: python
+
+    from build import ProjectBuilder
+
+    builder = ProjectBuilder(".")
+    builder.build("sdist", "dist/")
+    builder.build("wheel", "dist/")
+
+Using isolated environments (default):
+
+.. code-block:: python
+
+    from build import ProjectBuilder
+    from build.env import IsolatedEnvBuilder
+
+    with IsolatedEnvBuilder() as env:
+        builder = ProjectBuilder(".", runner=env.runner)
+        builder.build("wheel", "dist/")
+
+Disabling isolation:
+
+.. code-block:: python
+
+    from build import ProjectBuilder
+
+    builder = ProjectBuilder(".", runner=lambda cmd, **kwargs: None)
+    builder.build("wheel", "dist/")
+
+Getting package metadata without building:
+
+.. code-block:: python
+
+    from build import ProjectBuilder
+    import tempfile
+
+    builder = ProjectBuilder(".")
+    with tempfile.TemporaryDirectory() as tmpdir:
+        metadata_dir = builder.metadata_path(tmpdir)
+        # Read METADATA file from metadata_dir to extract package info
+
+Accessing build dependencies:
+
+.. code-block:: python
+
+    from build import ProjectBuilder
+
+    builder = ProjectBuilder(".")
+    requires = builder.build_system_requires
+    print(f"Build requires: {requires}")
+
+    # Get additional dependencies for building a wheel
+    wheel_requires = builder.get_requires_for_build("wheel")
+    print(f"Wheel build requires: {wheel_requires}")
+
+Handling errors:
+
+.. code-block:: python
+
+    from build import ProjectBuilder
+    from build import BuildException
+
+    try:
+        builder = ProjectBuilder(".")
+        builder.build("wheel", "dist/")
+    except BuildException as e:
+        print(f"Build failed: {e}")
+
+***********
+ Reference
+***********
+
+******************
+ ``build`` module
+******************
+
+.. automodule:: build
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+**********************
+ ``build.env`` module
+**********************
+
+.. automodule:: build.env
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+***********************
+ ``build.util`` module
+***********************
+
+.. automodule:: build.util
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst
new file mode 100644
index 00000000..db992789
--- /dev/null
+++ b/docs/reference/cli.rst
@@ -0,0 +1,57 @@
+########################
+ Command-Line Interface
+########################
+
+A simple, correct Python build frontend.
+
+By default, a `source distribution (sdist)
+<https://packaging.python.org/en/latest/specifications/source-distribution-format/>`_ is built from the project root and
+a `binary distribution (wheel) <https://packaging.python.org/en/latest/specifications/binary-distribution-format/>`_ is
+built from the sdist. If this is undesirable, you can pass ``--sdist`` and/or ``--wheel`` to build distributions
+independently of each other.
+
+.. sphinx_argparse_cli::
+    :module: build.__main__
+    :func: main_parser
+    :prog: python -m build
+    :title: python -m build
+    :usage_width: 97
+
+********************
+ Isolation Behavior
+********************
+
+By default build will build the package in an isolated environment, but this behavior can be disabled with
+``--no-isolation``. When using isolation, build creates a temporary virtual environment, installs the build dependencies
+specified in your ``pyproject.toml``, runs the build, and then cleans up the environment. This ensures reproducible
+builds regardless of what packages are installed in your development environment.
+
+************************
+ Alternative CLI Script
+************************
+
+A ``pyproject-build`` CLI script is also available, which is functionally identical to ``python -m build``. This is
+useful for tools like pipx_ that prefer direct script entry points.
+
+.. code-block:: console
+
+    $ pyproject-build
+    $ pyproject-build --help
+
+Both commands accept the same options and behave identically.
+
+*****************
+ Common Patterns
+*****************
+
+For practical usage examples and workflows, see :doc:`../how-to/basic-usage`.
+
+**********
+ See Also
+**********
+
+- :doc:`../how-to/basic-usage` for common workflows
+- :doc:`../how-to/config-settings` for passing options to backends
+- :doc:`environment-variables` for environment variables that affect build
+
+.. _pipx: https://github.com/pipxproject/pipx
diff --git a/docs/reference/environment-variables.rst b/docs/reference/environment-variables.rst
new file mode 100644
index 00000000..f4ff9da7
--- /dev/null
+++ b/docs/reference/environment-variables.rst
@@ -0,0 +1,314 @@
+#######################
+ Environment Variables
+#######################
+
+This reference documents environment variables that affect build's behavior. You can use these to configure private
+package indexes, proxies, SSL certificates, and other settings.
+
+************************
+ Variables Set by build
+************************
+
+``VIRTUAL_ENV``
+===============
+
+build sets this variable when creating `isolated environments
+<https://packaging.python.org/en/latest/glossary/#term-Isolated-Build>`_. It contains the absolute path to the temporary
+`virtual environment <https://docs.python.org/3/tutorial/venv.html>`_ that build creates for installing dependencies.
+Build backends can use this to detect they're running in an isolated environment.
+
+*****************************
+ Package Index Configuration
+*****************************
+
+By default, build uses `pip <https://pip.pypa.io/>`_ to install build dependencies in isolated environments. Configure
+pip using these environment variables to work with private package indexes or mirrors. For detailed examples, see
+:doc:`../how-to/corporate-environments`.
+
+.. note::
+
+    These ``PIP_*`` variables only apply when using the default pip installer. When using ``--installer=uv``, configure
+    uv through its own `environment variables <https://docs.astral.sh/uv/configuration/environment/>`_ instead (e.g.,
+    ``UV_INDEX_URL``, ``UV_EXTRA_INDEX_URL``).
+
+``PIP_INDEX_URL``
+=================
+
+Sets the primary `package index <https://packaging.python.org/en/latest/glossary/#term-Package-Index>`_ URL where pip
+looks for packages. Use this to point to private package repositories or PyPI mirrors. Defaults to
+``https://pypi.org/simple``.
+
+.. code-block:: console
+
+    $ export PIP_INDEX_URL=https://pypi.company.com/simple
+    $ python -m build
+
+``PIP_EXTRA_INDEX_URL``
+=======================
+
+Adds additional package indexes to search beyond the primary index. This allows using both `PyPI <https://pypi.org/>`_
+and a private index simultaneously.
+
+.. code-block:: console
+
+    $ export PIP_EXTRA_INDEX_URL=https://pypi.company.com/simple
+    $ python -m build
+
+.. warning::
+
+    A malicious package on any extra index can shadow packages from other indexes. Use ``PIP_INDEX_URL`` exclusively
+    when possible for better security.
+
+``PIP_CERT``
+============
+
+Path to a custom CA certificate bundle for SSL/TLS verification. Use this when your organization uses self-signed
+certificates or a custom certificate authority. Defaults to system certificates.
+
+.. code-block:: console
+
+    $ export PIP_CERT=/path/to/company-ca-bundle.crt
+    $ python -m build
+
+``PIP_TRUSTED_HOST``
+====================
+
+Disables SSL verification for the specified host. Only use this in secure development environments where SSL
+certificates aren't available.
+
+.. code-block:: console
+
+    $ export PIP_TRUSTED_HOST=pypi.company.com
+    $ python -m build
+
+.. warning::
+
+    Disabling SSL verification is insecure. Prefer using ``PIP_CERT`` with proper certificates.
+
+***********************
+ Network Configuration
+***********************
+
+``PIP_TIMEOUT``
+===============
+
+Sets the timeout in seconds for network operations. Increase this on slow or unreliable network connections. Defaults to
+15 seconds.
+
+.. code-block:: console
+
+    $ export PIP_TIMEOUT=60
+    $ python -m build
+
+``PIP_RETRIES``
+===============
+
+Number of times pip retries failed downloads. Increase this on unstable network connections. Defaults to 5 retries.
+
+.. code-block:: console
+
+    $ export PIP_RETRIES=10
+    $ python -m build
+
+``PIP_NO_CACHE_DIR``
+====================
+
+Disables pip's package cache directory, forcing fresh downloads every time. Useful in CI environments to ensure
+completely clean builds, though this makes builds slower.
+
+.. code-block:: console
+
+    $ export PIP_NO_CACHE_DIR=1
+    $ python -m build
+
+*********************
+ Proxy Configuration
+*********************
+
+If you're behind a corporate proxy, configure these variables to route pip's network requests through your proxy server.
+Both uppercase and lowercase versions are recognized.
+
+``HTTP_PROXY`` / ``http_proxy``
+===============================
+
+Proxy server for HTTP requests. Specify the proxy URL including protocol and port.
+
+.. code-block:: console
+
+    $ export HTTP_PROXY=http://proxy.company.com:8080
+    $ python -m build
+
+``HTTPS_PROXY`` / ``https_proxy``
+=================================
+
+Proxy server for HTTPS requests. Even though the proxy URL uses ``http://``, this handles HTTPS traffic.
+
+.. code-block:: console
+
+    $ export HTTPS_PROXY=http://proxy.company.com:8080
+    $ python -m build
+
+``NO_PROXY`` / ``no_proxy``
+===========================
+
+Comma-separated list of hosts that should bypass the proxy. Use this for internal servers that don't require proxy
+access.
+
+.. code-block:: console
+
+    $ export NO_PROXY=localhost,127.0.0.1,.company.com
+    $ python -m build
+
+***********************************
+ SSL/TLS Certificate Configuration
+***********************************
+
+These variables configure SSL/TLS certificates for secure connections. Use them when your organization uses self-signed
+certificates or custom certificate authorities.
+
+``REQUESTS_CA_BUNDLE``
+======================
+
+Path to custom CA certificate bundle. The `requests <https://requests.readthedocs.io/>`_ library (which `pip
+<https://pip.pypa.io/>`_ depends on) uses this variable. Alternative to ``PIP_CERT``.
+
+.. code-block:: console
+
+    $ export REQUESTS_CA_BUNDLE=/path/to/company-ca-bundle.crt
+    $ python -m build
+
+``SSL_CERT_FILE``
+=================
+
+Another variable for specifying a custom CA certificate bundle. Recognized by various Python libraries.
+
+.. code-block:: console
+
+    $ export SSL_CERT_FILE=/path/to/company-ca-bundle.crt
+    $ python -m build
+
+******************************
+ Python Runtime Configuration
+******************************
+
+``PYTHONWARNINGS``
+==================
+
+Controls `Python's warning filters <https://docs.python.org/3/library/warnings.html>`_. Use this in CI to catch
+deprecated features or potential issues in your build configuration by turning warnings into errors.
+
+Catch deprecation warnings:
+
+.. code-block:: console
+
+    $ PYTHONWARNINGS=error::DeprecationWarning python -m build
+
+Catch setuptools-specific warnings:
+
+.. code-block:: console
+
+    $ PYTHONWARNINGS=error:::setuptools.config.setupcfg python -m build
+
+``PYTHONUTF8``
+==============
+
+Enables `UTF-8 mode <https://docs.python.org/3/library/os.html#utf-8-mode>`_ on Windows. Use this when building packages
+with non-ASCII characters in filenames or file content on Windows systems.
+
+.. code-block:: console
+
+    $ set PYTHONUTF8=1
+    $ python -m build
+
+``TMPDIR`` / ``TEMP`` / ``TMP``
+===============================
+
+Controls where build creates the temporary isolated build environment. Useful for debugging or when you need the
+temporary directory on a specific filesystem (e.g., for ccache or compilation caching).
+
+On Unix-like systems, use ``TMPDIR``:
+
+.. code-block:: console
+
+    $ TMPDIR=/path/to/custom/tmp python -m build
+
+On Windows, use ``TEMP``:
+
+.. code-block:: console
+
+    $ set TEMP=C:\path\to\custom\tmp
+    $ python -m build
+
+The temporary directory persists after build completes, allowing you to inspect build artifacts, logs, and the isolated
+environment for debugging. By default, build uses the system's default temporary directory and cleans it up after the
+build.
+
+**Common use cases**:
+
+- **Debugging**: Keep temp directory to inspect build logs
+- **ccache**: Place builds on a filesystem where ccache can cache compilation
+- **Disk space**: Use a different filesystem with more available space
+- **Performance**: Use faster storage (e.g., tmpfs on Linux)
+
+See :doc:`../how-to/troubleshooting` for debugging examples.
+
+****************************
+ Backend-Specific Variables
+****************************
+
+Each **build backend** may define its own environment variables for configuration. Check your backend's documentation:
+
+- `Setuptools <https://setuptools.pypa.io/en/latest/userguide/index.html>`_
+- `Hatchling <https://hatch.pypa.io/latest/config/build/>`_
+- `PDM-Backend <https://pdm-backend.fming.dev/>`_
+- `Flit <https://flit.pypa.io/en/stable/>`_
+- `Poetry-Core <https://python-poetry.org/docs/pyproject/>`_
+- `scikit-build-core <https://scikit-build-core.readthedocs.io/en/latest/configuration.html>`_
+- `meson-python <https://meson-python.readthedocs.io/en/latest/reference/config-settings.html>`_
+
+*********************
+ Non-Isolated Builds
+*********************
+
+When using ``--no-isolation``, build skips creating an `isolated environment
+<https://packaging.python.org/en/latest/glossary/#term-Isolated-Build>`_. All environment variables from your current
+shell pass directly to the build backend, including:
+
+- ``PYTHONPATH`` - Affects Python module discovery
+- ``PATH`` - Determines which executables are found
+- Any custom variables your build backend uses
+
+build does not set ``VIRTUAL_ENV`` in this mode. You're responsible for installing build dependencies yourself. See
+:doc:`../how-to/basic-usage` for appropriate use cases.
+
+**********************************
+ Alternative: Configuration Files
+**********************************
+
+Instead of environment variables, you can configure `pip <https://pip.pypa.io/>`_ using persistent configuration files.
+This is convenient if you always use the same settings.
+
+**Linux/macOS**: ``~/.config/pip/pip.conf``
+
+**Windows**: ``%APPDATA%\\pip\\pip.ini``
+
+Example configuration:
+
+.. code-block:: ini
+
+    [global]
+    index-url = https://pypi.company.com/simple
+    trusted-host = pypi.company.com
+    cert = /path/to/company-ca-bundle.crt
+
+For more details and examples, see :doc:`../how-to/corporate-environments` and the `pip configuration documentation
+<https://pip.pypa.io/en/stable/topics/configuration/>`_.
+
+**********
+ See also
+**********
+
+- :doc:`../how-to/corporate-environments` for proxy and SSL configuration
+- :doc:`../how-to/troubleshooting` for common issues
+- :doc:`cli` for command-line options
+- `pip documentation <https://pip.pypa.io/en/stable/topics/configuration/>`_ for pip configuration
diff --git a/docs/release.rst b/docs/release.rst
deleted file mode 100644
index 62c556d5..00000000
--- a/docs/release.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-***************
-Release Process
-***************
-
-You may release the project by following these steps:
-
-#. Bump the version in ``src/build/__init__.py``
-#. Update ``CHANGELOG.rst`` with the new version and current date
-#. Make a release commit with the changes made above
-    - The commit message should follow the ``release X.Y.Z`` format
-#. Make a signed tag (``git tag --sign X.Y.Z``)
-    - The tag title should follow the ``build X.Y.Z`` format
-    - The tag body should be a plaintext version of the changelog for the current
-      release
-#. Push the commit and tag to the repository (``git push`` and ``git push --tags``)
-#. Make a release on GitHub or with the ``gh`` CLI tool. Copy the release notes
-   into the release.
-
-If you have any questions, please look at previous releases and/or ping the
-other maintainers.
diff --git a/docs/test_suite.rst b/docs/test_suite.rst
deleted file mode 100644
index 8bea97e3..00000000
--- a/docs/test_suite.rst
+++ /dev/null
@@ -1,51 +0,0 @@
-**********
-Test Suite
-**********
-
-Due to its nature, ``build`` has a somewhat complex test suite, which we will
-try to go through in this document.
-
-Firstly, there are two sets of tests, unit tests and integration tests. In unit
-tests, we test the actual code implementation. In integration tests, we test
-``build`` on a few real world projects; this is mostly a sanity test.
-
-Integration tests take a long time to run, and are not very helpful tracking
-down issues, so they are **disabled by default**. They can be enabled by passing
-either ``--run-integration`` or ``--only-integration`` arguments to pytest,
-where the latter will disable the unit tests and only run the integration ones.
-Even though these tests are disabled by default, they will be run in CI,
-where test suite run durations are not a big issue.
-
-To run the test suite we use ``tox``, which automates running the test suite on
-different environments:
-
-
-.. code-block:: console
-
-     tox
-
-
-You can find out more about how to run ``tox`` and its arguments in the
-`tox documentation`_.
-
-We have a fairly large environment matrix. We run tests for all supported Python
-versions and implementations, and with the module being invoked directly from path,
-sdist install, or wheel install. Additionally, we have an environment for type
-checking, and one to produce the documentation. There are some other extra
-environments, like checking the code with the minimum version of each
-dependency.
-
-Some example commands for this project:
-  - Run type checking: ``tox -e type``
-  - Only run unit tests against Python 3.9: ``tox -e py39``
-  - Run both unit and integration tests: ``tox -- --run-integration``
-  - Only run integration tests: ``tox -- --only-integration``
-  - Only run integration tests with parallel tasks: ``tox -- -n auto --only-integration``
-  - Only run unit tests against Python 3.9 with the module installed via wheel: ``tox -e py39-wheel``
-
-
-We have CI testing, where we run the test suite across all supported operating
-systems, and have test coverage reports.
-
-
-.. _tox documentation: https://tox.readthedocs.io/
diff --git a/docs/tutorial/getting-started.rst b/docs/tutorial/getting-started.rst
new file mode 100644
index 00000000..90d5f693
--- /dev/null
+++ b/docs/tutorial/getting-started.rst
@@ -0,0 +1,160 @@
+#################
+ Getting Started
+#################
+
+This tutorial will guide you through installing build and creating your first Python package ready for distribution.
+
+.. note::
+
+    New to Python packaging? Start with the `Python Packaging User Guide tutorial
+    <https://packaging.python.org/en/latest/tutorials/packaging-projects/>`_ to learn how to structure a Python project.
+    This tutorial assumes you already have a project with a ``pyproject.toml`` file.
+
+***************
+ Prerequisites
+***************
+
+You need Python 3.9 or later installed on your system. Check your Python version:
+
+.. code-block:: console
+
+    $ python --version
+    Python 3.11.0
+
+**************
+ Installation
+**************
+
+The recommended way to install build is using pip:
+
+.. code-block:: console
+
+    $ pip install build
+
+Or, if you prefer to install it in an isolated environment using pipx:
+
+.. code-block:: console
+
+    $ pipx install build
+
+For corporate environments or systems with restricted internet access, see :doc:`../how-to/corporate-environments`.
+
+***************************
+ Creating a simple package
+***************************
+
+Let's create a minimal Python package to demonstrate how build works.
+
+1. Create a project directory:
+
+.. code-block:: console
+
+    $ mkdir mypackage
+    $ cd mypackage
+
+2. Create a ``pyproject.toml`` file:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["hatchling"]
+    build-backend = "hatchling.build"
+
+    [project]
+    name = "mypackage"
+    version = "0.1.0"
+    description = "A simple example package"
+    readme = "README.md"
+    requires-python = ">=3.8"
+
+3. Create a ``README.md`` file:
+
+.. code-block:: markdown
+
+    # My Package
+
+    This is a simple example package.
+
+4. Create your Python package:
+
+.. code-block:: console
+
+    $ mkdir src/mypackage
+    $ touch src/mypackage/__init__.py
+
+5. Add some code to ``src/mypackage/__init__.py``:
+
+.. code-block:: python
+
+    def hello():
+        return "Hello from mypackage!"
+
+***********************
+ Building your package
+***********************
+
+Now you're ready to build your package:
+
+.. code-block:: console
+
+    $ python -m build
+
+You should see output like:
+
+.. code-block:: console
+
+    * Creating isolated environment: venv+pip...
+    * Installing packages in isolated environment:
+      - hatchling
+    * Getting build dependencies for sdist...
+    * Building sdist...
+    * Building wheel from sdist
+    * Creating isolated environment: venv+pip...
+    * Installing packages in isolated environment:
+      - hatchling
+    * Getting build dependencies for wheel...
+    * Building wheel...
+    Successfully built mypackage-0.1.0.tar.gz and mypackage-0.1.0-py3-none-any.whl
+
+The built packages are now in the ``dist/`` directory:
+
+.. code-block:: console
+
+    $ ls dist/
+    mypackage-0.1.0-py3-none-any.whl
+    mypackage-0.1.0.tar.gz
+
+*****************************
+ Understanding what happened
+*****************************
+
+Build created two `distribution files <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_
+(packages ready for distribution):
+
+1. **Source distribution**: ``mypackage-0.1.0.tar.gz``
+
+   This `tarball <https://en.wikipedia.org/wiki/Tar_(computing)>`_ (compressed archive) contains your source code.
+   Anyone can download it and build your package on their system. Learn more in the `source distribution specification
+   <https://packaging.python.org/en/latest/specifications/source-distribution-format/>`_.
+
+2. **Wheel**: ``mypackage-0.1.0-py3-none-any.whl``
+
+   This `wheel <https://packaging.python.org/en/latest/specifications/binary-distribution-format/>`_ is a pre-built
+   package that `pip <https://pip.pypa.io/>`_ can install directly without needing to build anything. This makes
+   installation much faster.
+
+Build used an **isolated environment** to ensure your package builds consistently regardless of what you have installed
+on your computer. It:
+
+1. Created a temporary `virtual environment <https://docs.python.org/3/tutorial/venv.html>`_
+2. Installed only your build dependencies (`hatchling <https://hatch.pypa.io/latest/>`_)
+3. Invoked the **build backend** to create the distribution files
+4. Cleaned up the temporary environment when done
+
+************
+ Next steps
+************
+
+- Learn about :doc:`../how-to/basic-usage` for common build workflows
+- Understand :doc:`../explanation/how-it-works` for details on the build process
+- See :doc:`../how-to/config-settings` to customize your build
diff --git a/pyproject.toml b/pyproject.toml
index e60e973e..9f348aae 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -63,11 +63,16 @@ extra = [
   "virtualenv >= 20.0.35",
 ]
 docs = [
-  "furo >= 2023.08.17",
-  "sphinx ~= 7.0",
-  "sphinx-argparse-cli >= 1.5",
-  "sphinx-autodoc-typehints >= 1.10",
-  "sphinx-issues >= 3.0.0",
+  "furo >= 2025.12.19",
+  "pre-commit >= 3.0",
+  "proselint >= 0.16",
+  "sphinx >= 8.1",
+  "sphinx-argparse-cli >= 1.17",
+  "sphinx-autodoc-typehints >= 2.3",
+  "sphinx-copybutton >= 0.5.2",
+  "sphinx-inline-tabs >= 2025.12.21",
+  "sphinx-issues >= 5.0",
+  "sphinxcontrib-mermaid >= 2.0",
 ]
 test = [
   "filelock >= 3",
diff --git a/tests/packages/legacy/legacy/__init__.py b/tests/packages/legacy/legacy/__init__.py
index d1fc44d6..93416d30 100644
--- a/tests/packages/legacy/legacy/__init__.py
+++ b/tests/packages/legacy/legacy/__init__.py
@@ -1,7 +1,5 @@
 # SPDX-License-Identifier: MIT
 
-"""
-legacy - Example legacy package
-"""
+"""legacy - Example legacy package"""
 
 __version__ = '1.0.0'
diff --git a/tests/packages/test-flit/test_flit/__init__.py b/tests/packages/test-flit/test_flit/__init__.py
index 1feaceb1..c6867ac3 100644
--- a/tests/packages/test-flit/test_flit/__init__.py
+++ b/tests/packages/test-flit/test_flit/__init__.py
@@ -1,7 +1,5 @@
 # SPDX-License-Identifier: MIT
 
-"""
-test_flit - Example flit package
-"""
+"""test_flit - Example flit package"""
 
 __version__ = '1.0.0'
diff --git a/tests/test_projectbuilder.py b/tests/test_projectbuilder.py
index ae7c70e3..95071268 100644
--- a/tests/test_projectbuilder.py
+++ b/tests/test_projectbuilder.py
@@ -387,9 +387,7 @@ def demo_pkg_inline(tmp_path_factory):
 @pytest.mark.contextvars
 @pytest.mark.isolated
 def test_build_with_dep_on_console_script(tmp_path, demo_pkg_inline, capfd, mocker):
-    """
-    All command-line scripts provided by the build-required packages must be present in the build environment's PATH.
-    """
+    """All command-line scripts provided by the build-required packages must be present in the build environment's PATH."""
     # we first install demo pkg inline as build dependency (as this provides a console script we can check)
     # to validate backend invocations contain the correct path we use an inline backend that will fail, but first
     # provides the PATH information (and validates shutil.which is able to discover the executable - as PEP states)
diff --git a/tests/test_self_packaging.py b/tests/test_self_packaging.py
index b23d798f..55c1e601 100644
--- a/tests/test_self_packaging.py
+++ b/tests/test_self_packaging.py
@@ -35,6 +35,8 @@
 
 sdist_patterns = {
     'docs/*.rst',
+    'docs/*/*.rst',
+    'docs/_static/*',
     'src/build/*.py',
     'src/build/_compat/*.py',
     'tests/*.py',
diff --git a/tox.ini b/tox.ini
index 7823ebcc..e2d484b1 100644
--- a/tox.ini
+++ b/tox.ini
@@ -58,10 +58,14 @@ dependency_groups =
 
 [testenv:docs]
 description = build documentations
-base_python = python3.12
+base_python = python3.14
+set_env =
+    PYTHONUTF8 = 1
 commands =
-    sphinx-build -n docs {envtmpdir} {posargs:-W}
-    python -c 'print("Documentation available under file://{envtmpdir}/index.html")'
+    pre-commit run docstrfmt --all-files
+    proselint check docs
+    sphinx-build -W -n -b html docs {env:READTHEDOCS_OUTPUT:{envtmpdir}}/html
+    python -c 'import os; print("Documentation available under file://" + os.environ.get("READTHEDOCS_OUTPUT", "{envtmpdir}") + "/html/index.html")'
 dependency_groups =
     docs