diff --git a/docs/contributing.md b/docs/contributing.md
index 89c5c86..96f3d1f 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -106,9 +106,12 @@ only because an outdated sphinx plugin pins an older version.
 To initalize a virtual environment in the `.venv` directory of your project, simply run
 
 ```bash
-uv sync --all-extras
+uv sync --all-extras --all-groups
 ```
 
+`--all-extras` pulls in the provider layers (openai, anthropic, gemini, …);
+`--all-groups` pulls in the `dev`, `test`, and `doc` PEP 735 dependency groups.
+
 The `.venv` directory is typically automatically discovered by IDEs such as VS Code.
 
 ::::
@@ -122,11 +125,17 @@ we describe how you can manage environments manually using `pip`:
 ```bash
 python3 -m venv .venv
 source .venv/bin/activate
-pip install -e ".[dev,test,doc]"
+pip install --group dev --group test --group doc -e ".[test]"
 ```
 
 The `.venv` directory is typically automatically discovered by IDEs such as VS Code.
 
+Note: `pip install --group` requires pip >= 25.1 ([PEP 735][]).
+The `-e ".[test]"` extra pulls in the provider layers the test suite
+exercises; `--group` pulls in the dev / test / doc Python packages.
+
+[PEP 735]: https://peps.python.org/pep-0735/
+
 ::::
 :::::
 
diff --git a/pyproject.toml b/pyproject.toml
index 5c20224..307eb40 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -45,27 +45,6 @@ optional-dependencies.anthropic = [
 optional-dependencies.colors = [
   "colorspacious>=1.1",
 ]
-# Development dependencies
-optional-dependencies.dev = [
-  "pre-commit",
-  "twine>=4.0.2",
-]
-optional-dependencies.doc = [
-  "docutils>=0.8,!=0.18.*,!=0.19.*",
-  "ipykernel",
-  "ipython",
-  "myst-nb>=1.1",
-  "pandas",
-  # Until pybtex >0.24.0 releases: https://bitbucket.org/pybtex-devs/pybtex/issues/169/
-  "setuptools",
-  "sphinx>=8.1",
-  "sphinx-autodoc-typehints",
-  "sphinx-book-theme>=1",
-  "sphinx-copybutton",
-  "sphinx-tabs",
-  "sphinxcontrib-bibtex>=1",
-  "sphinxext-opengraph",
-]
 optional-dependencies.gemini = [
   "google-genai>=1.27",
 ]
@@ -76,13 +55,12 @@ optional-dependencies.gpu = [
 optional-dependencies.openai = [
   "openai>=1.90",
 ]
+# Thin pointer so `pip install cell-annotator[test]` pulls in the provider extras
+# that the test suite exercises. Python test dependencies live in
+# [dependency-groups] test below and are pulled in by hatch / `uv sync --group test`.
 optional-dependencies.test = [
-  "cell-annotator[all-providers]", # tests use all providers
-  "cell-annotator[colors]",        # tests use color validation
-  "coverage>=7.10",
-  "flaky",
-  "pytest",
-  "pytest-cov",                    # For VS Code's coverage functionality
+  "cell-annotator[all-providers]",
+  "cell-annotator[colors]",
 ]
 optional-dependencies.tutorials = [
   "squidpy>=1.6",
@@ -92,15 +70,47 @@ urls.Documentation = "https://cell-annotator.readthedocs.io/"
 urls.Homepage = "https://cell-annotator.readthedocs.io/"
 urls.Source = "https://github.com/quadbio/cell-annotator"
 
+[dependency-groups]
+dev = [
+  "pre-commit",
+  "twine>=4.0.2",
+]
+test = [
+  "coverage>=7.10",
+  "flaky",
+  "pytest",
+  "pytest-cov",     # For VS Code's coverage functionality
+]
+doc = [
+  "docutils>=0.8,!=0.18.*,!=0.19.*",
+  "ipykernel",
+  "ipython",
+  "myst-nb>=1.1",
+  "pandas",
+  # Until pybtex >0.24.0 releases: https://bitbucket.org/pybtex-devs/pybtex/issues/169/
+  "setuptools",
+  "sphinx>=8.1",
+  "sphinx-autodoc-typehints",
+  "sphinx-book-theme>=1",
+  "sphinx-copybutton",
+  "sphinx-tabs",
+  "sphinxcontrib-bibtex>=1",
+  "sphinxext-opengraph",
+]
+
 [tool.hatch]
 envs.default.installer = "uv"
-envs.default.features = [ "dev" ]
-envs.docs.features = [ "doc" ]
+envs.default.dependency-groups = [ "dev" ]
+envs.docs.dependency-groups = [ "doc" ]
 envs.docs.dev-mode = true
 envs.docs.scripts.build = "sphinx-build -M html docs docs/_build {args}"
 envs.docs.scripts.open = "python -m webbrowser -t docs/_build/html/index.html"
 envs.docs.scripts.clean = "git clean -fdX -- {args:docs}"
-envs.hatch-test.features = [ "dev", "test" ]
+# hatch-test needs both:
+#   - dependency-groups: Python test packages (pytest, coverage, flaky, ...)
+#   - features: provider extras via optional-dependencies.test thin pointer
+envs.hatch-test.dependency-groups = [ "dev", "test" ]
+envs.hatch-test.features = [ "test" ]
 envs.hatch-test.matrix = [
   # Test the lowest and highest supported Python versions with normal deps
   { deps = [ "stable" ], python = [ "3.11", "3.13" ] },