docs(AGENTS): Add doctest guidelines and requirements

why: Prevent workarounds that bypass doctest execution
what:
- All functions/methods MUST have working doctests
- Never comment out asyncio.run() or similar calls
- Never convert to code-blocks (they don't run)
- Stop and ask for help if doctests can't be made to work
- Document available doctest_namespace fixtures
- Add async doctest pattern examples

Author: tony

AGENTS.md

@@ -213,6 +213,43 @@ type
 """
 ```
 
+### Doctests
+
+**All functions and methods MUST have working doctests.** Doctests serve as both documentation and tests.
+
+**CRITICAL RULES:**
+- Doctests MUST actually execute - never comment out `asyncio.run()` or similar calls
+- Doctests MUST NOT be converted to `.. code-block::` as a workaround (code-blocks don't run)
+- If you cannot create a working doctest, **STOP and ask for help**
+
+**Available tools for doctests:**
+- `doctest_namespace` fixtures: `tmp_path`, `asyncio`, `create_git_remote_repo`, `create_hg_remote_repo`, `create_svn_remote_repo`, `example_git_repo`
+- Ellipsis for variable output: `# doctest: +ELLIPSIS`
+- Skip for truly un-runnable examples: `# doctest: +SKIP` (use sparingly)
+- Update `pytest_plugin.py` to add new fixtures to `doctest_namespace`
+
+**Async doctest pattern:**
+```python
+>>> async def example():
+...     result = await some_async_function()
+...     return result
+>>> asyncio.run(example())
+'expected output'
+```
+
+**Using fixtures in doctests:**
+```python
+>>> git = Git(path=tmp_path)  # tmp_path from doctest_namespace
+>>> git.run(['status'])
+'...'
+```
+
+**When output varies, use ellipsis:**
+```python
+>>> git.clone(url=f'file://{create_git_remote_repo()}')  # doctest: +ELLIPSIS
+'Cloning into ...'
+```
+
 ### Git Commit Standards
 
 Format commit messages as: