# Repository Guidelines

## Project Structure & Module Organization

- `src/`: Rust source for the `pfs-tftp` binary (entrypoint: `src/main.rs`).
- `tests/`: Integration tests (create as needed; Cargo auto-discovers `tests/*.rs`).
- `rfc1350.txt`: TFTP protocol reference (RFC 1350).
- `Cargo.toml` / `Cargo.lock`: Cargo manifest and locked dependency graph.

Keep modules cohesive: protocol parsing/encoding in a dedicated module (e.g., `src/tftp.rs`), I/O and CLI wiring in `src/main.rs`.

## Build, Test, and Development Commands

- `cargo build`: Compile the project.
- `cargo run`: Build and run the local binary.
- `cargo test`: Run unit and integration tests.
- `cargo +nightly fmt`: Format code using `rustfmt.toml`.
- `cargo clippy --all-targets --all-features -D warnings`: Lint and fail on warnings.
- `cargo check`: Fast type-check without producing binaries.

## Coding Style & Naming Conventions

- Use Rust defaults: 4-space indentation, no tabs, and let `rustfmt` decide layout.
- Follow naming conventions: `snake_case` (modules/functions), `PascalCase` (types/traits), `SCREAMING_SNAKE_CASE` (consts).
- Prefer small, testable functions and explicit error handling (`Result<T, E>` with meaningful error messages).

## Testing Guidelines

- Unit tests: colocate under `#[cfg(test)] mod tests { ... }` in the relevant module.
- Integration tests: add `tests/<area>.rs` (e.g., `tests/packet_roundtrip.rs`).
- Target behaviors: packet encode/decode round-trips, error cases, and RFC compliance edge cases.

## Commit & Pull Request Guidelines

- Git history is currently minimal; use a consistent convention going forward (recommended: Conventional Commits like `feat: ...`, `fix: ...`, `test: ...`).
- Keep commits focused and avoid mixing refactors with behavior changes.
- Commit messages should be clear and descriptive. They should always include enough context so that someone reading them in 5 years can still comprehend the intent, the why, how and everything.

## Agent-Specific Notes

- Prefer small, reviewable diffs and update this file when commands or structure change.
- Avoid adding dependencies unless needed; justify new crates in the PR description.