docs: contributor experience — priorities, paths, templates, receipts, first issues

[TheSmokeDev]

What and why

Three outside contributors arrived in one day (@kvnloo, @TheAngryPit, @webdevtodayjason) and met a CONTRIBUTING.md that covered setup and lint but not what we want first, where each kind of change starts, or what a PR has to carry to land. This PR makes the next thirty obvious. Markdown and YAML only — no Python changes.

• CONTRIBUTING.md rewrite (every existing fact kept — setup, the ruff pin, the test: host-summary and capabilities tests fail on any box where hermes-agent is importable #93 baseline, the module table, the adversarial-review paragraph, the SHA-pinned-actions and BLE001/RUF100 rules):
  • ranked priorities for this repo: live-lane bug fixes > provider/host compatibility > security hardening (auth store, token routing, redaction) > cross-platform > new providers behind the contract > new surfaces > docs
  • a common contribution paths table — new realtime provider, new surface, new talk tool, bug fix, docs — each naming the files it touches and what it ships with (talk_realtime.py contract → talk_core_provider.py lane → talk_config / talk_cli / talk_doctor wiring → pyproject py-modules; the DuplexAudio method set a surface implements; the _HANDLERS entry plus READ_ONLY_TALK_TOOLS / MUTATING_TALK_TOOLS classification a tool needs)
  • dev setup: why uv run --extra dev, node for the two dashboard JS tests, hermes talk check as the live proof, and how to run a branch live (hermes plugins install --force --ref <sha> <you>/hermes-talk)
  • PR process: branch names, Conventional-Commit scopes derived from the last 200 commits, the description contract, the merge bar, a first-response-within-24h review promise, and how credit works
• .github/PULL_REQUEST_TEMPLATE.md carrying the same contract (what/why, how to test, platforms, a check --json receipt when a lane is touched, Fixes #N, a checklist that repeats the merge bar).
• Issue forms: new feature_request.yml (problem first, proposal second, which surfaces and providers); new provider_compatibility_report.yml (PASS / PARTIAL / FAIL, provider, model, credential lane, versions, which of SessionReady / SpeechStarted / FunctionCall round-trip / barge-in were observed, the check --json report, the wire error verbatim — no audio, transcripts, or secrets); bug_report.yml gains the core-contract lane and the check/doctor/diagnostics commands as places a bug can happen, plus a pointer to the provider form; config.yml links private security reporting and Discussions first.
• docs/PROVIDER-RECEIPT.md: the two-minute procedure (check --json, then one short call with a five-row tick list), the table the form mirrors, and how maintainers act on each verdict — the unticked event names the adapter function; the wire error becomes the regression fixture. Ported idea from bielcarpi/hermes-live-voice's compatibility receipt (MIT) — idea only, no text.
• README: Contributing shortened to the pointer plus the promise; a Contributors line crediting @kvnloo (fix(audio): preserve speech through echo cancellation #81 merged; feat(realtime): adapt semantic endpointing controls #107 in review), @TheAngryPit (feat(desktop): add renderer-owned Realtime Talk transport #80 in review), @webdevtodayjason (second-consumer field feedback on upstream feat(plugins): add a realtime voice provider contract NousResearch/hermes-agent#81404, the contract our lanes register on). CHANGELOG [Unreleased] → Added.

Repo settings done alongside (not in this diff): labels provider, surface, security, docs created; good first issue + help wanted on #93; help wanted on #90 and #51. Discussions were already enabled.

How to test

# every relative link in the changed files resolves
for f in CONTRIBUTING.md README.md CHANGELOG.md docs/PROVIDER-RECEIPT.md .github/PULL_REQUEST_TEMPLATE.md .github/ISSUE_TEMPLATE/*.yml; do
  d=$(dirname "$f"); grep -oE '\]\([^) ]+\)' "$f" | sed -E 's/^\]\(//; s/\)$//' | grep -vE '^(https?:|mailto:|#)' | sed -E 's/#.*$//' | sort -u |
  while read -r t; do [ -z "$t" ] || [ -e "$d/$t" ] || echo "MISSING in $f: $t"; done; done
# whitespace-only rewrites: the two stats are identical (687+/18-)
git diff --stat origin/main...HEAD; git diff --ignore-all-space --stat origin/main...HEAD

Also verified: the four issue forms parse as YAML and every field has the shape GitHub's issue-form schema requires (unique ids, options on every dropdown/checkbox); the suite is untouched and stays green in a project-local venv on this box (uv run --extra dev pytest -q → 1561 passed, 40 skipped, 5 xfailed; ruff check . clean on the pinned 0.16.5).

Platforms

• Windows 11 (authored and link-checked here)
• Linux — CI
• macOS — n/a, docs only

Live receipt

Not applicable — no provider lane, credential path, or delegation path is touched.

Checklist

• One logical change; docs only
• pytest -q and ruff check . pass locally on the pinned ruff
• Commit follows Conventional Commits (docs: …)
• No auth-store writes; no tokens anywhere
• Nothing secret in the diff — the templates instruct reporters to paste nothing but the redacted reports
• Every relative link resolves
• CHANGELOG.md [Unreleased] entry added

— SmokeDev