diff --git a/planning/releases/3.1.1.md b/planning/releases/3.1.1.md
new file mode 100644
index 0000000..9c903e1
--- /dev/null
+++ b/planning/releases/3.1.1.md
@@ -0,0 +1,47 @@
+# modern-di-arq 3.1.1 — documentation catches up with modern-di 3.1
+
+**No code changes.** The installed package is byte-identical to 3.1.0; nothing
+in `modern_di_arq/` moved. This release exists to publish the corrected
+documentation, because the README a user reads on PyPI is rendered from the
+released distribution — so the fix below was invisible until now.
+
+## Fix
+
+- **The documented setup no longer passes `validate=True`.** modern-di 3.1 made
+  `Container(validate=...)` a deprecated no-op that emits
+  `ValidateArgumentWarning`. The README example therefore emitted a
+  `DeprecationWarning` on every construction, and — more quietly — silently
+  stopped validating anything, because that argument *was* the explicit opt-in
+  to graph validation. This package pins `modern-di>=3`, so users reached that
+  state on a routine upgrade.
+
+  The docs now build the container plain and call `container.validate()`
+  explicitly, after `setup_di`. That ordering matters and is unchanged:
+  `setup_di` registers this integration's providers, so validating first fails
+  any provider with a non-optional dependency on them.
+
+- **The test suite was red against modern-di 3.1.** Assertions written for 3.0's
+  mandatory-open lifecycle — where a freshly built container started *closed* —
+  fail now that containers are open from construction. Fixed while keeping each
+  test's subject: where the assertion was only a precondition it states the 3.1
+  one, and where the subject *was* the lifecycle transition, the container is
+  closed first so the transition stays observable instead of passing vacuously.
+
+## Features
+
+- **A runnable canonical example** under `examples/`, linked from the README, so
+  the integration can be adopted in one sitting.
+
+## Downstream
+
+Nothing is required of you. If you copied the old README snippet, drop
+`validate=True` — it does nothing on modern-di 3.1 and warns:
+
+```python
+container = Container(groups=[Dependencies])
+setup_di(...)
+container.validate()  # optional fail-fast, after setup_di registers its providers
+```
+
+Keeping it works, but a suite configured with `error::DeprecationWarning` will
+fail on it. The argument is removed in modern-di 4.0.