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

why: Establish structured logging conventions for tmuxp and libtmux,
enabling OTel interop, pytest assertions on extra fields, and
aggregator-friendly message templates.
what:
- Add Logging Standards section between Code Style and Doctests
- 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

@@ -116,6 +116,106 @@ windows:
 - **Type imports**: Use `import typing as t` and access via namespace (e.g., `t.Optional`)
 - **Development workflow**: Format → Test → Commit → Lint/Type Check → Test → Final Commit
 
+## 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 |
+| `tmux_config_path` | `str` | workspace config file path |
+| `tmux_layout` | `str` | window layout string |
+
+**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, config expansion | tmux command + stdout, trickle-down steps |
+| `INFO` | Session lifecycle, user-visible operations | Session created, window added, workspace loaded |
+| `WARNING` | Recoverable issues, deprecation, user-actionable config | Deprecated key, missing optional program |
+| `ERROR` | Failures that stop an operation | tmux command failed, config validation error |
+
+Config discovery noise belongs in `DEBUG`; only surprising/user-actionable config issues → `WARNING`.
+
+### 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`)
+
 ## Doctests
 
 **All functions and methods MUST have working doctests.** Doctests serve as both documentation and tests.