diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cd077e60..6bd41528 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -47,6 +47,9 @@ jobs:
           python-version: "3.12"
       - run: uv lock
       - run: uv sync --all-packages
+      # Not bare `mypy .`: the per-package `tests/conftest.py` files collide under mypy's module
+      # resolution, which aborts the run before anything is checked. `make typecheck` runs this
+      # same command.
       - run: uv run mypy packages/*/src
 
   # ─── Test ───────────────────────────────────────────────────────────────────
diff --git a/AGENTS.md b/AGENTS.md
index 321ae4a8..4485e398 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -64,6 +64,11 @@ The mypy config uses `strict = true`, which enforces:
 
 When adding new functions or methods, always include full type annotations. Run `make typecheck` to verify before pushing.
 
+`make typecheck` checks `packages/*/src` — the same invocation CI runs. Do not change it to bare
+`mypy .`: the per-package `tests/conftest.py` files all resolve to the module name `conftest`, and
+mypy aborts on that clash before checking anything. Test suites are not type-checked today; making
+them mypy-clean under `strict` is a separate piece of work.
+
 #### `Generic[T]` syntax is intentionally kept (UP046 is ignored)
 
 The `UP046` rule (PEP 695 `type` statement syntax for generic classes) is **ignored** in `pyproject.toml`. Do not convert `class Foo(Generic[T]):` to PEP 695 syntax — it is a deliberate migration decision.
diff --git a/Makefile b/Makefile
index 7043b559..71630ad9 100644
--- a/Makefile
+++ b/Makefile
@@ -9,8 +9,13 @@ test:
 	uv run pytest
 
 # Type-check all packages (uv run mypy)
+# Not bare `mypy .`: the per-package `tests/conftest.py` files all resolve to the module name
+# `conftest`, and mypy aborts on that clash (`Duplicate module named "conftest"`) before checking
+# anything, so the command gives no signal at all. CI type-checks package sources only — both
+# `.github/workflows/ci.yml` and `.github/actions/ci/action.yml` — and this mirrors that exactly so
+# local and CI agree. The test suites are not currently mypy-clean under `strict`.
 typecheck:
-	uv run mypy .
+	uv run mypy packages/*/src
 
 # Check for lint errors
 lint:
diff --git a/README.md b/README.md
index 89ae9440..e57c2fb5 100644
--- a/README.md
+++ b/README.md
@@ -580,7 +580,7 @@ A `Makefile` is provided as a consistent interface alongside the `uv` commands.
 |---|---|---|
 | `make start` | `uv run python main.py` | Run `main.py` |
 | `make test` | `uv run pytest` | Run all tests |
-| `make typecheck` | `uv run mypy .` | Type-check all packages |
+| `make typecheck` | `uv run mypy packages/*/src` | Type-check all package sources (the same invocation CI runs) |
 
 ### Running the examples