diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9ca2d1a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,23 @@
+# AGENTS.md
+
+Repo-scope guidance for coding agents.
+
+## Defaults
+- Keep diffs small/reviewable.
+- Preserve existing patterns and naming.
+- Add regression tests for bug fixes and behavior changes.
+- Update docs when API/CLI behavior changes.
+
+## Validation
+- Run before handoff:
+  - `cargo fmt --all`
+  - `cargo test`
+  - `cargo test --features blocking`
+
+## Git Safety
+- Avoid destructive git/file ops unless explicitly requested.
+- Do not rewrite user changes you did not make.
+
+## Commits
+- Commit messages MUST follow Conventional Commits:
+  - https://www.conventionalcommits.org/en/v1.0.0/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..6214292
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,23 @@
+# Contributing
+
+This repository requires Conventional Commits.
+
+## Commit Message Policy (Required)
+- All commits MUST follow the Conventional Commits 1.0.0 spec:
+  - https://www.conventionalcommits.org/en/v1.0.0/
+- Allowed types in this repo:
+  - `feat`, `fix`, `refactor`, `build`, `ci`, `chore`, `docs`, `style`, `perf`, `test`
+
+Examples:
+- `feat(client): expose via layer span in typed model`
+- `fix(cli): parse board-origin --type drill correctly`
+- `test(client): cover via padstack layer decoding`
+
+## Before Opening a PR
+- Run:
+  - `cargo fmt --all`
+  - `cargo test`
+  - `cargo test --features blocking`
+
+## Maintainer Notes
+- Proto regeneration workflow lives in `CONTRIBUTIONS.md`.