AGENTS.md

1# AGENTS.md
2 
3See [CONTRIBUTING.md](CONTRIBUTING.md) for how to open a pull request (CLA, dev setup, pre-PR checks).
4 
5## Tests
6 
7```bash
8make test                                       # Run all tests
9make test F="server"                            # Filter by substring
10TEST_FILTER="WebApi: #selector_all" make test   # Filter main + subtest (separator: #)
11TEST_VERBOSE=true make test
12TEST_FAIL_FIRST=true make test
13METRICS=true make test                          # Capture allocation/duration metrics as JSON
14```
15 
16The custom test runner (`src/test_runner.zig`) detects memory leaks in debug builds. **A test that allocates without freeing fails** — not just lints.
17 
18## Formatting
19 
20```bash
21zig fmt --check ./*.zig ./**/*.zig    # Exact command CI runs
22```
23 
24`zig build` depends on the fmt step, so a local build catches drift too.
25 
26## Conventions
27 
28Mirror the patterns in neighboring files. In particular:
29 
30- `@import` alias case follows the imported file's basename (`const Frame = @import("Frame.zig")`, `const ast = @import("ast.zig")`).
31- Prefer struct-init type inference (`.{ ... }`) where the expected type is known from the function signature or variable annotation.
32