diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..a9c065bec
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,24 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/` hosts compiler subsystems: `nimony/` (core pipeline), `nifc/` (IR + grammar), `hexer/` and `nifler/` (lexers), `hastur.nim`, and shared `lib/`. Keep related code together so incremental builds stay fast.
+- `tests/` mirrors each subsystem with `.nif` fixtures plus `.expected.*` outputs; `tests/tester.nim` drives the diff-based checks.
+- `doc/` contains specs (`design.md`, `language.md`, `nifc-spec.md`, `njvl-spec.md`), while `tools/` houses helper generators and `vendor/` holds pinned dependencies.
+
+## Build, Test, and Development Commands
+- `nim c -r src/hastur build all` compiles every tool (nimony, nifc, hexer, nifler, nifmake, nj, VL) into `bin/`.
+- `nim c -r src/hastur all` runs the full regression matrix; replace `all` with `nimony`, `nifc`, or another command to scope the suite.
+- `nim c -r src/hastur test tests/nimony/tracked/foo.nim` targets a single file or directory, forwarding extra flags to the compiler.
+- `nim c -r tests/tester` drives the fixture comparators (nifindexes, nifgram, hastur self-tests) and accepts `--overwrite` to refresh expected outputs.
+
+## Coding Style & Naming Conventions
+- Stick to Nim’s two-space indentation, UTF-8 files, and `lower_snake_case` module names. Types stay `PascalCase`, procs `camelCase`, and exported symbols need a trailing `*`.
+
+## Testing Guidelines
+- Refresh fixtures with `nim c -r src/hastur --overwrite test <path>` only when you fully understand the delta, because reviewers rely on `.expected` diffs.
+- Run `nim c -r src/hastur all` before pushing and call out skipped suites or flakes in the PR description.
+
+## Commit & Pull Request Guidelines
+- Follow the existing log style: `fixes #1582; adjust VL range typing (#1583)` — imperative summary plus issue references, PR number optional.
+- PRs should state motivation, identify touched subsystems, and list the exact test commands run; only add screenshots when visual proof is essential.
+- Keep commits focused and separate refactors from behavioral patches so bisecting remains straightforward.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 000000000..47dc3e3d8
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/README.md b/README.md
index 077a850e3..85556ef4b 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,11 @@ The current focus is on developing a compiler for a Nim dialect that offers:
 AI has created a good overview of our [compiler architecture](https://deepwiki.com/nim-lang/nimony).
 
 
+## Contributor Guide
+
+New contributors should read [AGENTS.md](AGENTS.md) for repository workflow, coding standards, and testing expectations.
+
+
 ## Getting started
 
 Clone Nimony:
diff --git a/config.nims b/config.nims
new file mode 100644
index 000000000..a08771d5e
--- /dev/null
+++ b/config.nims
@@ -0,0 +1,5 @@
+
+task build, "Build Hastur and Nimony bins":
+  exec "nim c -o:bin/hastur src/hastur.nim"
+  exec "./bin/hastur build all"
+