# AGENTS.md: Zig project

## Commands
`zig build` · `zig build test` · `zig build run` · `zig fmt --check .`
- Check `build.zig.zon` (`minimum_zig_version`) and use APIs for that version; Zig's std library changes between releases (e.g. the new `std.Io` reader/writer interfaces), so don't copy pre-0.15 examples blindly.

## Rules
- Functions that allocate take an `std.mem.Allocator` parameter. No hidden global allocators. In tests use `std.testing.allocator` so leaks fail the test.
- Pair every allocation with `defer allocator.free(x)` or `errdefer` right after it.
- Errors: return error unions (`!T`), propagate with `try`, handle with `catch |err| switch (err) {...}`. Define specific error sets for public APIs.
- No `catch unreachable` or `.?` on values that can actually fail at runtime.
- Prefer slices (`[]const u8`) over pointers + lengths; use `std.ArrayList`/`std.ArrayListUnmanaged` with explicit allocators.
- `comptime` for generics and compile-time checks; keep it readable.
- Dependencies via `zig fetch --save <url>` into `build.zig.zon`; wire them in `build.zig` with `b.dependency`.
- Keep `build.zig` options (`b.standardTargetOptions`, `standardOptimizeOption`) so users can choose target and mode.
- C interop via `@cImport` in one module, wrapped in Zig-friendly functions.

## Tests
`test "name" {}` blocks next to the code, using `std.testing.expectEqual` / `expectError`.

## Done
`zig fmt --check .` and `zig build test` pass, in Debug and ReleaseSafe.