AGENTS.md

Guidance for AI coding agents (Codex/ChatGPT) working in this repository.

Optimize for correctness, safety, and maintainability over cleverness.
Keep changes small and reviewable. Prefer multiple small commits/PRs over one large refactor.
Preserve existing style, architecture, and public APIs unless explicitly asked to change them.

Do NOT add new external dependencies (runtime or dev) without explicit approval.
- This includes package manager installs, new requirements, new npm/pip packages, new system packages, new containers/images.
Prefer using the standard library or existing dependencies already in the repo.
If you believe a new dependency is truly necessary:
1. explain why,
2. propose at least one no-new-deps alternative,
3. estimate blast radius and maintenance risk,
4. STOP and ask for approval before adding it.

For any bug fix: add/adjust a unit test that reproduces the issue and prevents regressions.
For any new feature: add unit tests for the “happy path” and at least 1–2 edge cases.
Prefer unit tests over integration tests unless the change is inherently integration-level.
Run the smallest relevant test command(s) after changes:
- First: targeted tests for the changed modules.
- Then (if time/CI expectations): full unit test suite.
If tests cannot be run in the current environment, clearly state what you would run and why.

Before running commands that could modify the environment or take a long time (e.g., installs, migrations, DB changes), explain what you intend to run and ask for approval.
Avoid destructive operations (deleting files, dropping DBs, resetting environments) unless explicitly requested.
Never print, log, or exfiltrate secrets. If you detect a likely secret, redact it and point it out.

Start by understanding existing patterns:
- find similar code paths,
- follow established naming and folder conventions,
- reuse existing utilities/helpers.
When making non-trivial changes:
1. propose a short plan (3–7 bullets),
2. list the files you expect to touch,
3. call out risks/unknowns,
4. then proceed.

Prefer clear, boring code over abstractions.
Add types/annotations where the repo uses them.
Add docstrings/comments only where they clarify intent, invariants, or tricky logic.
Handle errors explicitly; don’t swallow exceptions.

Update relevant docs when behavior changes (README, module docs, inline docs).
Summarize changes at the end:
- What changed (bullets),
- Why,
- How to test (exact commands),
- Any follow-ups/todos.