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

why: Establish structured logging conventions for libtmux,
enabling OTel interop, pytest assertions on extra fields, and
aggregator-friendly message templates.
what:
- Add Logging Standards section between Doctests and Git Commit Standards
- Define tmux_ prefixed key vocabulary (core + heavy/optional)
- Document lazy formatting, stacklevel, LoggerAdapter patterns
- Specify log levels, message style, exception logging rules
- Add testing guidance (caplog.records over caplog.text)

Author: tony

AGENTS.md

@@ -282,6 +282,102 @@ Window(@... ...:my_window, Session($... ...))
 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 |
+|-----|------|---------|
+| `tmux_cmd` | `str` | tmux command line |
+| `tmux_subcommand` | `str` | tmux subcommand (e.g. `new-session`) |
+| `tmux_target` | `str` | tmux target specifier (e.g. `mysession:1.2`) |
+| `tmux_exit_code` | `int` | tmux process exit code |
+| `tmux_session` | `str` | session name |
+| `tmux_window` | `str` | window name or index |
+| `tmux_pane` | `str` | pane identifier |
+
+**Heavy/optional keys** (DEBUG only, potentially large):
+
+| Key | Type | Context |
+|-----|------|---------|
+| `tmux_stdout` | `list[str]` | tmux stdout lines (truncate or cap; `%(tmux_stdout)s` produces repr) |
+| `tmux_stderr` | `list[str]` | tmux stderr lines (same caveats) |
+
+Treat established keys as compatibility-sensitive — downstream users may build dashboards and alerts on them. Change deliberately.
+
+#### Key naming rules
+
+- `snake_case`, not dotted; `tmux_` prefix
+- Prefer stable scalars; avoid ad-hoc objects
+- Heavy keys (`tmux_stdout`, `tmux_stderr`) are DEBUG-only; consider companion `tmux_stdout_len` fields or hard truncation (e.g. `stdout[:100]`)
+
+#### 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.
+
+#### LoggerAdapter for persistent context
+
+For objects with stable identity (Session, Window, Pane), use `LoggerAdapter` to avoid repeating the same `extra` on every call. Lead with the portable pattern (override `process()` to merge); `merge_extra=True` simplifies this on Python 3.13+.
+
+#### Log levels
+
+| Level | Use for | Examples |
+|-------|---------|----------|
+| `DEBUG` | Internal mechanics, tmux I/O | tmux command + stdout, format queries |
+| `INFO` | Object lifecycle, user-visible operations | Session created, window added |
+| `WARNING` | Recoverable issues, deprecation | Deprecated method, missing optional program |
+| `ERROR` | Failures that stop an operation | tmux command failed, invalid target |
+
+#### Message style
+
+- Lowercase, past tense for events: `"session created"`, `"tmux command failed"`
+- 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="libtmux.common")`
+- Filter records rather than index by position: `[r for r in caplog.records if hasattr(r, "tmux_cmd")]`
+- Assert on schema: `record.tmux_exit_code == 0` not `"exit code 0" 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
 
 Format commit messages as: