# AGENTS.md: Rust library crate

## Commands
`cargo build` · `cargo test --all-features` · `cargo clippy --all-targets --all-features -- -D warnings` · `cargo fmt --check` · `cargo doc --no-deps` · `cargo semver-checks` (before releases)

## API design
- Keep the public surface small and intentional; re-export from `lib.rs`. Mark exhaustive-looking enums/structs `#[non_exhaustive]` if they may grow.
- Accept generic, borrowed inputs (`impl AsRef<Path>`, `&str`, `impl IntoIterator`) and return owned, concrete types.
- Errors: a crate `Error` enum with `thiserror`; implement `std::error::Error` and keep sources. Don't expose `anyhow` in public APIs, and never panic on bad input; `unwrap` only on proven invariants with a comment.
- Builders for types with many optional settings.
- Implement common traits where they make sense: `Debug`, `Clone`, `PartialEq`, `Default`, `Display`, `serde` behind a `serde` feature.

## Crate hygiene
- `#![warn(missing_docs)]`; every public item has rustdoc with an example that compiles as a doc test.
- Optional dependencies behind features; default features minimal. Features must be additive.
- Declare `rust-version` (MSRV) in `Cargo.toml` and don't use newer std APIs without bumping it.
- No `unsafe` unless necessary; each block gets a `// SAFETY:` comment.
- Update `CHANGELOG.md` for user-visible changes.

## Never
Run `cargo publish` or bump the major version without approval.