ai(rules[AGENTS]): Add logging standard conventions

why: Establish structured logging conventions,
enabling OTel interop, pytest assertions on extra fields, and
aggregator-friendly message templates.
what:
- Add Logging Standards section to AGENTS.md
- Define doctest_/sphinx_ prefixed key vocabulary
- Document lazy formatting, stacklevel patterns
- Specify log levels, message style, exception logging rules
- Add testing guidance (caplog.records over caplog.text)

Author: tony

AGENTS.md

@@ -262,6 +262,86 @@ True
 3. Keep doctests simple and focused on demonstrating usage
 4. Add blank lines between test sections for improved readability
 
+### Logging Standards
+
+These rules guide future logging changes; existing code may not yet conform.
+
+#### Logger setup
+
+- Use `logging.getLogger(__name__)` in every module
+- Add `NullHandler` in library `__init__.py` files
+- Never configure handlers, levels, or formatters in library code — that's the application's job
+
+#### Structured context via `extra`
+
+Pass structured data on every log call where useful for filtering, searching, or test assertions.
+
+**Core keys** (stable, scalar, safe at any log level):
+
+| Key | Type | Context |
+|-----|------|---------|
+| `doctest_source_file` | `str` | doctest source path (.rst, .md, .py) |
+| `doctest_block_type` | `str` | block type (doctest_block, code fence) |
+| `sphinx_extension` | `str` | Sphinx extension name |
+
+Treat established keys as compatibility-sensitive — downstream users may build dashboards and alerts on them. Change deliberately.
+
+#### Key naming rules
+
+- `snake_case`, not dotted; project-specific prefixes (`doctest_`, `sphinx_`)
+- Prefer stable scalars; avoid ad-hoc objects
+
+#### Lazy formatting
+
+`logger.debug("msg %s", val)` not f-strings. Two rationales:
+- Deferred string interpolation: skipped entirely when level is filtered
+- Aggregator message template grouping: `"Running %s"` is one signature grouped ×10,000; f-strings make each line unique
+
+When computing `val` itself is expensive, guard with `if logger.isEnabledFor(logging.DEBUG)`.
+
+#### stacklevel for wrappers
+
+Increment for each wrapper layer so `%(filename)s:%(lineno)d` and OTel `code.filepath` point to the real caller. Verify whenever call depth changes.
+
+#### Log levels
+
+| Level | Use for | Examples |
+|-------|---------|----------|
+| `DEBUG` | Internal mechanics | Doctest parsing, node traversal steps |
+| `INFO` | Lifecycle, user-visible operations | Extension loaded, document processed |
+| `WARNING` | Recoverable issues, deprecation | Deprecated directive, missing optional dependency |
+| `ERROR` | Failures that stop an operation | Parse error, invalid configuration |
+
+#### Message style
+
+- Lowercase, past tense for events: `"extension loaded"`, `"parse error"`
+- No trailing punctuation
+- Keep messages short; put details in `extra`, not the message string
+
+#### Exception logging
+
+- Use `logger.exception()` only inside `except` blocks when you are **not** re-raising
+- Use `logger.error(..., exc_info=True)` when you need the traceback outside an `except` block
+- Avoid `logger.exception()` followed by `raise` — this duplicates the traceback. Either add context via `extra` that would otherwise be lost, or let the exception propagate
+
+#### Testing logs
+
+Assert on `caplog.records` attributes, not string matching on `caplog.text`:
+- Scope capture: `caplog.at_level(logging.DEBUG, logger="doctest_docutils")`
+- Filter records rather than index by position: `[r for r in caplog.records if hasattr(r, "doctest_source_file")]`
+- Assert on schema: `record.sphinx_extension == "doctest_docutils"` not `"doctest_docutils" in caplog.text`
+- `caplog.record_tuples` cannot access extra fields — always use `caplog.records`
+
+#### Avoid
+
+- f-strings/`.format()` in log calls
+- Unguarded logging in hot loops (guard with `isEnabledFor()`)
+- Catch-log-reraise without adding new context
+- `print()` for diagnostics
+- Logging secret env var values (log key names only)
+- Non-scalar ad-hoc objects in `extra`
+- Requiring custom `extra` fields in format strings without safe defaults (missing keys raise `KeyError`)
+
 ### Git Commit Standards
 
 See `.cursor/rules/git-commits.mdc` for detailed commit message standards.