diff --git a/CHANGELOG.md b/CHANGELOG.md
index a075f6f..8a0f345 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Track `.ai/ideas/implemented/` docs referenced by `decisions.md`
 
+### Changed
+
+- `mypy` excludes `build/` (avoids duplicate-module errors after `python -m build`)
+- Maintainer setup notes CI Python 3.11 and that workflow validate needs
+  `./scripts/setup-ai-workflow.sh` first
+
 ## [1.1.1] - 2026-08-09
 
 ### Fixed
diff --git a/docs/ai-workflow-setup.md b/docs/ai-workflow-setup.md
index 2c51c9b..e3d62a8 100644
--- a/docs/ai-workflow-setup.md
+++ b/docs/ai-workflow-setup.md
@@ -25,6 +25,11 @@ diffrat product files under `.ai/project/`, `.ai/docs/project-requirements.md`,
 and related paths. Tracked `.ai/ideas/` overlays product entries; template
 `implemented/` wins on rematerialize.
 
+CI runs on **Python 3.11**. Local development needs **Python ≥ 3.11** (3.12+ is
+fine). Before `./scripts/validate-ai-workflow.sh` or
+`python ci/validate-workflow-contracts.py --mode project`, run
+`./scripts/setup-ai-workflow.sh` so materialized `.ai/` path references resolve.
+
 ## Full workflow validation (local)
 
 ```bash
diff --git a/pyproject.toml b/pyproject.toml
index 327738d..e7cd198 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -55,7 +55,7 @@ select = ["E", "F", "I", "UP"]
 python_version = "3.11"
 strict = true
 packages = ["diffrat"]
-exclude = ["ci/"]
+exclude = ["ci/", "build/"]
 
 [tool.diffrat.checks]
 ci_validator = "python ci/validate-workflow-contracts.py --mode project"