Add AGENTS.md

AGENTS.md

@@ -0,0 +1,58 @@
+# Repository instructions
+
+This is a Rust 2024 crate. Keep changes focused, preserve the safety comments
+around unsafe code, and add tests for every behavior or control-flow path that
+changes.
+
+## Validation
+
+Run the ordinary test suite with:
+
+```sh
+cargo test
+```
+
+`cargo nextest` is also installed in this environment and is available for a
+faster unit-test run:
+
+```sh
+cargo nextest run
+```
+
+Nextest does not run doctests, so use `cargo test` when validating the complete
+ordinary suite, including the compile-fail documentation tests.
+
+### Miri
+
+Miri is installed for the nightly toolchain, not the default stable toolchain.
+The agent environment cannot write to the normal cache under
+`/home/soruh/.cache`, so point the cache at the writable `/tmp` directory:
+
+```sh
+XDG_CACHE_HOME=/tmp/type-erased-vec-miri-cache cargo +nightly miri test
+```
+
+Run this command after changes to unsafe code or vector ownership/layout logic.
+It exercises both the unit tests and the compile-fail doctests.
+
+### Code coverage
+
+`cargo-llvm-cov` is installed. Branch coverage requires nightly in this
+environment. The crate is expected to retain 100% region, function, line,
+and branch coverage:
+
+```sh
+cargo +nightly llvm-cov \
+  --workspace \
+  --all-features \
+  --branch \
+  --show-missing-lines \
+  --fail-under-regions 100 \
+  --fail-under-functions 100 \
+  --fail-under-lines 100
+```
+
+The installed `cargo-llvm-cov` has no separate `--fail-under-branches` option,
+so also verify that the report's `TOTAL` row shows `100.00%` under `Branches`.
+Do not consider a change complete if any reported coverage category drops below
+100%.