# AGENTS.md
# Guidance for AI coding agents (Codex/ChatGPT) working in this repository.
# Follow these instructions as higher priority than general preferences.

## Operating principles
- 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.

## Dependencies (STRICT)
- 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.

## Tests and verification (REQUIRED)
- 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.

## Commands and environment safety
- 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.

## Implementation approach
- 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.

## Coding standards
- 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.

## Documentation and changelog
- 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.

## When uncertain
- Ask a direct question or present two options with tradeoffs.
- Do not make breaking changes based on guesswork.