docs(AGENTS.md): Add documentation standards for code blocks

why: Ensure code examples in documentation are individually copyable.
what:
- Add Documentation Standards section
- Require one command per code block
- Require explanations outside code blocks, not as comments

Author: tony

AGENTS.md

@@ -309,6 +309,40 @@ EOF
 )"
 ```
 
+## Documentation Standards
+
+### Code Blocks in Documentation
+
+When writing documentation (README, CHANGES, docs/), follow these rules for code blocks:
+
+**One command per code block.** This makes commands individually copyable.
+
+**Put explanations outside the code block**, not as comments inside.
+
+Good:
+
+Run the tests:
+
+```console
+$ uv run pytest
+```
+
+Run with coverage:
+
+```console
+$ uv run pytest --cov
+```
+
+Bad:
+
+```console
+# Run the tests
+$ uv run pytest
+
+# Run with coverage
+$ uv run pytest --cov
+```
+
 ## Debugging Tips
 
 See `.cursor/rules/avoid-debug-loops.mdc` for detailed debugging guidance.