# AGENTS.md

This file is guidance for agentic coding assistants working in this repo.
It summarizes the build/lint/test commands and the local style rules.

Sources in this repo:
- `llm/code_style.md`
- `llm/python_toolbox.md`
- `llm/textual_toolbox.md`
- `llm/agent_executor_instructions_v_1.md`

No Cursor rules were found in `.cursor/rules/` or `.cursorrules`.
No Copilot rules were found in `.github/copilot-instructions.md`.

-------------------------------------------------------------------------------
Build, lint, and test commands
-------------------------------------------------------------------------------

Environment
- Python: 3.13 (see `.python-version` and `pyproject.toml`)
- Environment manager: `uv` (do not use `pip`, `venv`, or `conda`)

Install / run
- Install deps: `uv add <package>` or `uv add --dev <package>`
- Run a command: `uv run <command>`

Build
- Build sdist and wheel: `uv build`
- Publish (only if explicitly requested): `uv publish`

Formatting
- Formatter: Black
- Run formatting: `uv run black .`

Linting
- Linter: Ruff (policy level; fix warnings unless explicitly justified)
- Run lint (if configured): `uv run ruff check .`

Type checking
- Type checker: mypy
- Run types (if configured): `uv run mypy .`

Tests
- Test runner: pytest
- Run all tests: `uv run pytest`
- Run a file: `uv run pytest tests/test_example.py`
- Run a single test: `uv run pytest tests/test_example.py::test_name`
- Run tests by keyword: `uv run pytest -k "keyword"`

Textual UI testing (when applicable)
- Preferred: Textual Pilot tests
- Secondary: snapshots + visual inspection
- Last resort: asciinema `.cast` review

If any of the above tools are not yet configured in `pyproject.toml`, add the
configuration when introducing the tool (do not invent settings silently).

-------------------------------------------------------------------------------
Code style and conventions
-------------------------------------------------------------------------------

Guiding principles
- Prefer explicit, readable code over cleverness.
- Keep functions small and testable.
- Avoid reflection or string-based wiring for core logic.
- Document boundaries and assumptions for public APIs and domain logic.

Imports
- Prefer standard library, then third-party, then local imports.
- Keep import lists explicit (no wildcard imports).

Formatting
- Black-compatible formatting only.
- Avoid manual alignment or style debates; rely on tooling.

Type hints
- Required for new code and for edited code.
- Public functions and methods must have full type hints.
- Avoid `Any` unless justified and localized.

Naming
- Functions: verbs and explicit intent (`extract_*`, `load_*`, `render_*`).
- Private helpers: prefix with `_`.
- Constants: `UPPER_SNAKE_CASE`.
- Include units in names when ambiguity exists (`time_s`, `freq_hz`).

Docstrings
- Required for:
  - Public API functions/classes
  - Domain/math functions (assumptions + units)
  - IO boundaries (read/write/parse/serialize)
  - Any function with non-obvious conventions or edge cases
- Optional for tiny internal helpers with obvious behavior.
- Content should include: purpose, parameters (units), returns (units), key
  assumptions, and meaningful failure modes.

Error handling
- Validate inputs early (types, ranges, shapes).
- Raise explicit exceptions with actionable messages.
- For CLI/TUI, convert internal exceptions into user-facing messages.

Project structure
- Separate pure logic from UI (Textual) and from IO.
- Keep CLI entry points thin: parse args -> call core -> format output.
- Prefer small modules organized by concept over large monolith files.

Testing conventions
- Use pytest.
- Prefer deterministic tests; seed randomness.
- Cover core correctness, edge cases, and regressions.
- For Textual UI: prefer Pilot tests first.

Agent execution rules (from `llm/agent_executor_instructions_v_1.md`)
- Follow the handoff file as the sole contract.
- Do not invent requirements or redesign scope.
- Run required tests; do not claim completion if tests fail or are missing.

-------------------------------------------------------------------------------
Repository status notes
-------------------------------------------------------------------------------

- `src/textual_everforest/` contains the theme definitions and demo app.
- `tests/` includes Textual Pilot tests for theme registration and snapshots.
- `main.py` remains a minimal entry point (not used by the package).
- `pyproject.toml` includes Textual dependency and hatchling build config.

When adding or changing tooling, update `pyproject.toml` accordingly and
document the new commands here.
