Development

.mailmap

@@ -0,0 +1,2 @@
+# Canonical contributor identities for local Git reports.
+air17 <18901596+air17@users.noreply.github.com> air17 <air17@github.com>

CHANGELOG.md

@@ -4,6 +4,9 @@ All notable public changes to Nexus Unity are documented here.
 
 ## [Unreleased]
 
+### Changed
+- Added a repository mailmap entry for `air17` so local Git contributor reports resolve historical `air17@github.com` commits to the GitHub account's canonical no-reply identity.
+
 ## [1.4.1] - 2026-06-12
 
 ### Fixed

CONTRIBUTING.md

@@ -25,6 +25,10 @@ Contributor pull requests must target `development`.
 - Direct pushes to `main` and `development` are blocked for everyone, including maintainers.
 - Trusted maintainers merge approved pull requests through GitHub; external contributors do not need direct repository write access.
 
+## Commit Attribution
+
+Author commits with an email address verified on your GitHub account, preferably the GitHub no-reply address from account email settings. Pull requests can merge even when commit author emails are not account-linked, but GitHub contributor statistics may not credit those commits. The repository `.mailmap` records known historical identity mappings for local Git reports; it is not a substitute for fixing your local `git config user.email` before future commits.
+
 ## Development Rules
 
 - Keep the server local-only. Do not add non-loopback binding without an explicit security design.

DOCUMENTATION.MD

@@ -159,6 +159,8 @@ Contributor pull requests target `development`. The `main` branch is release-onl
 
 Direct pushes to `main` and `development` are blocked for everyone, including maintainers. Trusted maintainers merge pull requests through GitHub; release changes reach `main` only through a release pull request from `development` or `release/*`. External fork pull requests currently emit a `PR target policy` warning and continue through the same CI pipeline; maintainers should review forked code carefully before merge. When an internal rerun is needed, the manual `Approve external PR for CI` workflow can copy a reviewed fork PR to a trusted `trusted/pr-N` branch and trigger validation there.
 
+Commit authors should use an email address verified on their GitHub account, preferably the GitHub no-reply address shown in account email settings. GitHub contributor statistics depend on account-linked commit identities, so commits made with placeholder or unverified emails may not be attributed even when the pull request is merged. The repository `.mailmap` records known historical identity mappings for local Git reporting; future commits should still be made with the correct verified email.
+
 The local runner must have `self-hosted`, `macOS`, `ARM64`, and `nexus-unity-ci` labels. The AI documentation job additionally requires `nexus-doc-ai`. The runner environment must provide `python3`, `dotnet`, Unity `6000.4.3f1` at `/Applications/Unity/Hub/Editor/6000.4.3f1/Unity.app/Contents/MacOS/Unity`, and Ollama on `http://127.0.0.1:11434`. Workflow-level `concurrency` uses group `nexus-unity-ci` with `queue: max`, so trusted CI runs are processed one at a time and up to 100 pending runs can wait instead of being canceled.
 
 For local feedback, contributors can run `bash scripts/install-git-hooks.sh` once per checkout. This configures Git to use the tracked `.githooks/pre-push` hook, which runs `scripts/prepush-validate.sh --quick` before push. The quick hook always performs package metadata validation, Python bridge compilation, Unity `.meta` pairing checks, Python bridge unit tests, `NexusQualityGate` tests, and the deterministic Roslyn quality gate. It uses `NEXUS_UNITY_HOOK_LIVE=auto` by default: reachable Unity servers run the read-only live smoke check, while temporary server timeouts print `NOTICE` and do not block the push. Use `NEXUS_UNITY_HOOK_LIVE=required` when a live server must be enforced, or `NEXUS_UNITY_HOOK_LIVE=off` for static-only local feedback.

README.md

@@ -201,6 +201,8 @@ Contributor pull requests should target `development`. The `main` branch is rele
 
 Direct pushes to `main` and `development` are blocked for everyone. Trusted maintainers merge pull requests in GitHub. External fork pull requests currently receive a policy warning and continue through CI; maintainers should review forked code carefully before merge and can use the manual `Approve external PR for CI` workflow to replay a reviewed fork PR on a trusted `trusted/pr-N` branch when an internal rerun is needed.
 
+Contributors should author commits with an email address verified on their GitHub account, preferably the GitHub no-reply address from account email settings. Commits made with placeholder or unverified author emails can merge successfully but may not appear in GitHub contributor statistics. The repository `.mailmap` keeps local Git reports aligned for known historical identities, but it does not replace fixing local Git email configuration before future commits.
+
 Contributors can also install the optional local pre-push hook for faster feedback:
 
 ```bash