docs: add generic agent onboarding and handoff guidance

CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# CONTRIBUTING
+
+Guidelines for humans and agents proposing changes.
+
+## Change principles
+
+- Keep changes focused and minimal.
+- Explain why a change is needed, not only what changed.
+- Preserve generic behavior unless implementing explicit repo-specific requirements.
+
+## Before opening a PR
+
+1. Confirm instructions in `AGENTS.md` and `CLAUDE.md` were followed.
+2. Run relevant checks/tests.
+3. Update docs affected by behavior changes.
+4. If you discovered reusable information, add/update a note under `docs/agent-handoffs/`.
+
+## Commit guidance
+
+- Use clear, descriptive commit messages.
+- Keep unrelated edits in separate commits.
+- Avoid committing temporary debug code or local-only artifacts.
+
+## PR guidance
+
+Include:
+
+- Summary of what changed
+- Why it changed
+- Validation performed
+- Any known follow-ups
+
+If no tests were run, state why.
+
+## Documentation maintenance
+
+When changing workflows:
+
+- Update `KNOWN_ISSUES.md` for new known limitations/workarounds.
+- Add a learning note if the change uncovered a reusable pattern.