diff --git a/.mailmap b/.mailmap
new file mode 100644
index 0000000..3b38ebb
--- /dev/null
+++ b/.mailmap
@@ -0,0 +1,8 @@
+# .mailmap — consolidate contributor identities for `git shortlog` and the
+# GitHub contributors graph. See: https://git-scm.com/docs/gitmailmap
+#
+# Salil Mhatre committed under four name/email combinations
+# (two emails, three display names). Map them all to one canonical identity.
+Salil Mhatre <32305505+Deadpool2000@users.noreply.github.com> <d2kyt@protonmail.com>
+Salil Mhatre <32305505+Deadpool2000@users.noreply.github.com> Salil <32305505+Deadpool2000@users.noreply.github.com>
+Salil Mhatre <32305505+Deadpool2000@users.noreply.github.com> Salil M <32305505+Deadpool2000@users.noreply.github.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2770c1b..51e4d16 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -150,7 +150,11 @@ pytest tests/test_data.py::test_detect_alpaca_format -v
 pytest tests/ --cov=soup_cli --cov-report=html
 ```
 
-### Test Files (86 files)
+### Test Files (275 files)
+
+> A representative sample of the suite below. The full table lives in
+> [`.claude/CLAUDE.md`](.claude/CLAUDE.md); run `pytest tests/ -v` for the complete list.
+
 
 | File | Covers |
 |------|--------|
@@ -441,6 +445,17 @@ The project follows semantic versioning: `MAJOR.MINOR.PATCH`
 5. Tag: `git tag v0.X.0 && git push --tags`
 6. GitHub Actions auto-publishes to PyPI on the `v*` tag (Trusted Publisher / OIDC)
 
+## Recognition
+
+We credit every contributor — recognition is free and you earned it.
+
+- **[CONTRIBUTORS.md](CONTRIBUTORS.md):** every merged (or in-tree-adopted) PR adds you here, with your work and PR number.
+- **CHANGELOG.md:** from the release that ships your change, the entry is tagged `(#NNN by @you)`.
+- **Commit trailers:** PRs land with a `Co-Authored-By:` line for you, so the GitHub
+  contributors graph reflects your work even after a squash merge.
+
+If you contributed and aren't credited somewhere, that's a bug — open a PR or an issue and we'll fix it.
+
 ## Community
 
 - **Issues:** Report bugs and request features on [GitHub Issues](https://github.com/MakazhanAlpamys/Soup/issues)
diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
new file mode 100644
index 0000000..13c5bea
--- /dev/null
+++ b/CONTRIBUTORS.md
@@ -0,0 +1,43 @@
+# Contributors
+
+Soup is built by its community. Thank you to everyone who has contributed code,
+tests, docs, and ideas. ❤️
+
+This list is maintained by hand alongside the GitHub
+[contributors graph](https://github.com/MakazhanAlpamys/Soup/graphs/contributors).
+Merged a PR and don't see yourself here? Open a PR adding your line — that counts too.
+
+## Maintainer
+
+- **Alpamys** ([@MakazhanAlpamys](https://github.com/MakazhanAlpamys)) — creator & lead maintainer
+
+## Contributors
+
+Listed by first contribution. PR numbers link the work.
+
+- **Salil Mhatre** ([@Deadpool2000](https://github.com/Deadpool2000))
+  - `soup version --json` for machine-readable CI output ([#6](https://github.com/MakazhanAlpamys/Soup/pull/6))
+  - RAM + disk-space checks in `soup doctor` ([#7](https://github.com/MakazhanAlpamys/Soup/pull/7))
+  - `soup runs clean` for smart checkpoint space management ([#9](https://github.com/MakazhanAlpamys/Soup/pull/9))
+  - Official Docker support for easier onboarding ([#20](https://github.com/MakazhanAlpamys/Soup/pull/20))
+  - `soup bench` — model speed + VRAM measurement ([#25](https://github.com/MakazhanAlpamys/Soup/pull/25))
+  - `--prompts-file` option for `soup bench` ([#30](https://github.com/MakazhanAlpamys/Soup/pull/30))
+  - Happy-path + CPU-warning tests for `soup bench` ([#31](https://github.com/MakazhanAlpamys/Soup/pull/31))
+  - `soup cost` — cloud GPU training cost estimation ([#42](https://github.com/MakazhanAlpamys/Soup/pull/42))
+  - `--nccl` flag for `soup doctor` multi-GPU bandwidth checks ([#178](https://github.com/MakazhanAlpamys/Soup/pull/178))
+- **Chinmaya Sahu** ([@csking101](https://github.com/csking101))
+  - DPO example config, sample data, and tests ([#48](https://github.com/MakazhanAlpamys/Soup/pull/48))
+  - FP8 `rowwise` + `rowwise_with_gw_hp` scaling recipes ([#62](https://github.com/MakazhanAlpamys/Soup/pull/62))
+- **Yixuan Xu** ([@mzl2233](https://github.com/mzl2233))
+  - Guard diagnose-gate on distributed worker ranks ([#169](https://github.com/MakazhanAlpamys/Soup/pull/169))
+- **dreamer0129** ([@dreamer0129](https://github.com/dreamer0129))
+  - Rich-markup escape fix in legacy `soup adapters` commands ([#175](https://github.com/MakazhanAlpamys/Soup/pull/175), adopted in-tree as [#174](https://github.com/MakazhanAlpamys/Soup/issues/174))
+- **Vivaan Dhawan** ([@VIVAAN-DHAWAN](https://github.com/VIVAAN-DHAWAN))
+  - Reject pickle/zip streams renamed to `.safetensors` via magic-byte check ([#198](https://github.com/MakazhanAlpamys/Soup/pull/198))
+- **Shivam** ([@shivam2931120](https://github.com/shivam2931120))
+  - Tokenizer-aware repetition scoring for the echo-trap detector ([#242](https://github.com/MakazhanAlpamys/Soup/pull/242))
+
+---
+
+Want to join this list? See [CONTRIBUTING.md](CONTRIBUTING.md) — good first issues are
+labelled in the [issue tracker](https://github.com/MakazhanAlpamys/Soup/labels/good%20first%20issue).