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

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -16,6 +16,11 @@ body:
         and host facts, and every `hermes talk doctor` outcome — no values, no
         logs, no prompts, no transcripts, no audio. Nothing else in this
         template is worth more than that one file.
+
+        If the session connected fine before and a provider now refuses,
+        drops events, or changed shape under us, the
+        [provider compatibility report](https://github.com/TheSmokeDev/hermes-talk/issues/new?template=provider_compatibility_report.yml)
+        is the better form — it asks for exactly the events that pin the break.
   - type: textarea
     id: diagnostics_bundle
     attributes:
@@ -33,6 +38,8 @@ body:
         - /talk inside a session
         - Discord voice channel
         - Dashboard tab
+        - hermes realtime --provider hermes-talk/… (the core contract lane)
+        - hermes talk check / doctor / diagnostics / setup
     validations:
       required: true
   - type: textarea

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,11 @@
 blank_issues_enabled: true
 contact_links:
+  - name: Security vulnerability — report privately
+    url: https://github.com/TheSmokeDev/hermes-talk/security/advisories/new
+    about: Credential leakage, auth-store writes, tool-authority bypass, redaction failures, supply chain. Never in a public issue — SECURITY.md has the classes and the 72-hour acknowledgement promise.
+  - name: Questions, ideas, design sketches — Discussions
+    url: https://github.com/TheSmokeDev/hermes-talk/discussions
+    about: Not sure it is a bug, or want to talk through a provider, surface, or tool before writing it? Start here.
   - name: Make a diagnostics bundle first (hermes talk diagnostics --bundle)
     url: https://github.com/TheSmokeDev/hermes-talk/blob/main/docs/OPERATING.md#7-hermes-talk-diagnostics--the-redacted-support-bundle
     about: One redacted file — versions, variable names, device/host facts, doctor outcomes — turns "it doesn't work" into something reproducible.
@@ -9,3 +15,6 @@ contact_links:
   - name: Operating manual — install, upgrade, verify, every knob, troubleshooting
     url: https://github.com/TheSmokeDev/hermes-talk/blob/main/docs/OPERATING.md
     about: Most "is this broken?" questions are answered by the verify runbook.
+  - name: Contributing guide — priorities, paths, setup, the merge bar
+    url: https://github.com/TheSmokeDev/hermes-talk/blob/main/CONTRIBUTING.md
+    about: Read before opening a PR. First response within 24 hours.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,81 @@
+name: Feature request
+description: Something the voice should be able to do, hear, or reach that it cannot today.
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The problem first, the proposal second. The ranked list of what we
+        take first is in
+        [CONTRIBUTING.md](https://github.com/TheSmokeDev/hermes-talk/blob/main/CONTRIBUTING.md#what-we-want-most);
+        a new provider or a new surface has a mapped path there. Check the
+        [open issues](https://github.com/TheSmokeDev/hermes-talk/issues) and
+        the [Current boundaries](https://github.com/TheSmokeDev/hermes-talk#current-boundaries)
+        section of the README first — several gaps are already named and
+        tracked.
+  - type: textarea
+    id: problem
+    attributes:
+      label: What you are trying to do that you cannot today
+      description: The situation on the call, in your words. What did you say or want to say, and what happened instead?
+      placeholder: |
+        On a Discord call I want to hand a task to an agent and have it
+        answer in the channel's text chat instead of out loud, because…
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behaviour
+      description: What the voice should do, say, or reach. If a spoken sentence is involved, write the sentence — the wording is part of the design here.
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - A new realtime provider (behind talk_realtime.py)
+        - A new surface (another room the session can be in)
+        - A new or changed talk tool
+        - Session / relay behaviour (turn-taking, barge-in, announcements)
+        - Delegation, steering, approvals (background work)
+        - Auth / credentials
+        - Dashboard tab
+        - doctor / check / diagnostics / setup
+        - Docs
+        - Other
+    validations:
+      required: true
+  - type: checkboxes
+    id: surfaces
+    attributes:
+      label: Surfaces it applies to
+      options:
+        - label: Terminal (hermes talk)
+        - label: /talk inside a session
+        - label: Discord voice channel
+        - label: Dashboard tab
+        - label: hermes realtime (core contract lane)
+  - type: checkboxes
+    id: providers
+    attributes:
+      label: Providers it applies to
+      options:
+        - label: OpenAI Realtime
+        - label: xAI Grok
+        - label: Gemini Live
+        - label: All of them / provider-neutral
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you considered
+      description: Including "do it in Hermes core instead" — some things belong upstream, and saying so early saves a PR.
+    validations:
+      required: false
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I would like to build this myself and open the PR

.github/ISSUE_TEMPLATE/provider_compatibility_report.yml

@@ -0,0 +1,111 @@
+name: Provider compatibility report
+description: A live provider works — or stopped working — on your setup. A pass is as useful as a fail.
+title: "[provider] <provider> / <model> on hermes-talk <version>: PASS | FAIL"
+labels: [provider]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The test suite is offline by design, so a provider changing its wire
+        under us reaches us through you. This form collects the evidence in
+        a fixed shape. The how-to, and the table it mirrors, is
+        [docs/PROVIDER-RECEIPT.md](https://github.com/TheSmokeDev/hermes-talk/blob/main/docs/PROVIDER-RECEIPT.md).
+
+        **Do not paste audio, transcripts, prompts, task results, or any
+        credential.** `hermes talk check --json` and `hermes talk doctor --json`
+        redact by construction and are all the detail a report needs.
+  - type: dropdown
+    id: verdict
+    attributes:
+      label: Verdict
+      options:
+        - PASS — a full turn worked (connect, SessionReady, a spoken reply, a tool round-trip)
+        - PARTIAL — connected, but one or more events below failed
+        - FAIL — the session never reached SessionReady
+    validations:
+      required: true
+  - type: dropdown
+    id: provider
+    attributes:
+      label: Provider
+      options:
+        - openai
+        - grok
+        - gemini
+    validations:
+      required: true
+  - type: input
+    id: model
+    attributes:
+      label: Model
+      description: As `hermes talk doctor` reports it (the `model` check), e.g. `gpt-realtime-2.1`, `grok-voice-latest`, `gemini-3.1-flash-live-preview`.
+    validations:
+      required: true
+  - type: dropdown
+    id: auth_lane
+    attributes:
+      label: Credential lane
+      description: Which lane the doctor's `auth` check names — never the credential itself.
+      options:
+        - Codex CLI OAuth (ChatGPT subscription)
+        - xAI OAuth (SuperGrok / X Premium+)
+        - API key (TALK_*_API_KEY or the shared variable)
+        - Not sure — the doctor `auth` check is pasted below
+    validations:
+      required: true
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Surface
+      options:
+        - Terminal (hermes talk)
+        - /talk inside a session
+        - Discord voice channel
+        - Dashboard tab
+        - hermes realtime --provider hermes-talk/… (the core contract lane)
+        - hermes talk check only
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: "hermes-talk version, Hermes host version, Python, OS — e.g. `hermes-talk 0.16.0 · hermes 0.21.0 · Python 3.12.6 · Windows 11`. `hermes plugins list` and `hermes --version` have the first two."
+    validations:
+      required: true
+  - type: checkboxes
+    id: events
+    attributes:
+      label: Events observed
+      description: Tick what you saw happen. Leave unticked what did not — that is the finding.
+      options:
+        - label: Connected (the session opened; `check` reports `session_ready`)
+        - label: SessionReady (the provider acknowledged the session setup)
+        - label: SpeechStarted (the provider heard you start talking)
+        - label: A spoken reply came back (ResponseStarted → OutputAudio → ResponseFinished)
+        - label: FunctionCall round-trip (say "status report" — the tool ran and the reply used its result)
+        - label: Barge-in (you spoke over the reply and playback cut)
+        - label: A clean hang-up (Ctrl+C / leave ended the session without an error)
+  - type: textarea
+    id: check_json
+    attributes:
+      label: hermes talk check --json (or doctor --json)
+      description: Paste the report. `check` proves the live path with per-step pass/fail; `doctor --json` if the session cannot be reached at all. Both carry no tokens and no paths — still read what you paste.
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: wire_error
+    attributes:
+      label: The provider's error, verbatim (if any)
+      description: The error TYPE and MESSAGE the provider or the plugin printed — e.g. a close code, an HTTP status, a `ProviderFailure` reason. Redact anything that looks like a key or a session id.
+      render: text
+    validations:
+      required: false
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else
+      description: "Last version it worked on, if you know it. Regional or account-tier facts that might matter (free-tier key, enterprise account, a proxy in the path). Names of knobs you have set — never their values."
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,52 @@
+<!--
+Thanks for the PR. Fill the sections that apply and delete the ones that
+do not. The guide behind every question: CONTRIBUTING.md.
+Never paste a credential, a transcript, or audio into a PR.
+-->
+
+## What and why
+
+<!-- The symptom or the gap, and why this approach. If a spoken sentence
+changes, quote it before and after — the wording is a contract here. -->
+
+Fixes #
+
+## How to test
+
+<!-- The command(s) and the expected output, so a reviewer reproduces it
+without asking. For a bug: the reproduction on main, then the proof. -->
+
+```bash
+
+```
+
+## Platforms
+
+<!-- Where you ran it. CI covers ubuntu + windows × Python 3.11–3.13; say so if that is all you have. -->
+
+- [ ] Windows
+- [ ] Linux
+- [ ] macOS
+
+## Live receipt (required when a provider lane, credential resolution, or the delegation path is touched)
+
+<!-- Paste the relevant part of `hermes talk check --json` — provider, plugin
+and host versions, and each step's status. If the change cannot reach a
+live turn, `hermes talk doctor --json` instead. Both redact by construction;
+still read what you paste. A new or changed provider lane also wants a
+filled-in docs/PROVIDER-RECEIPT.md table. -->
+
+```json
+
+```
+
+## Checklist
+
+- [ ] One logical change; tests ride with it, not behind it
+- [ ] `pytest -q` and `ruff check .` pass locally on the pinned ruff (`pip install -e ".[dev]"` or `uv run --extra dev …`)
+- [ ] Commits follow Conventional Commits with a hermes-talk scope (`fix(audio): …`, `feat(realtime): …`, `docs: …`)
+- [ ] No auth-store writes outside the documented Codex refresh; tokens reach only the provider's own host
+- [ ] Nothing secret in logs, receipts, spoken sentences, or test fixtures
+- [ ] Every spoken sentence I added or changed claims only what an artifact proves
+- [ ] Docs updated where behaviour changed (README, `docs/OPERATING.md`, `docs/VOICE-COMMANDS.md`) — or N/A
+- [ ] `CHANGELOG.md` `[Unreleased]` entry added (name yourself — merged work is credited)

CHANGELOG.md

@@ -14,6 +14,35 @@ named rather than smoothed.
 ## [Unreleased]
 
 ### Added
+- The contributor experience, written down. `CONTRIBUTING.md` now ranks
+  what we take first (bug fixes on live lanes, then provider and host
+  compatibility, security hardening, cross-platform, new providers behind
+  the contract, new surfaces, docs), maps the common paths — a new realtime
+  provider, a new surface, a new talk tool, a fix, a docs change — to the
+  exact files each one touches and ships with, and states the merge bar
+  (live-verified before merge on a provider wire; offline tests and fake
+  sessions otherwise; no auth-store writes; tokens only to the provider's
+  own host; nothing secret in logs or receipts), the branch and
+  Conventional-Commit scope conventions derived from the history, a
+  first-response-within-24-hours review promise, and how merged work is
+  credited. A pull request template carries the same contract (what and
+  why, how to test, platforms, a `check --json` receipt when a lane is
+  touched, `Fixes #N`). Two new issue forms — a feature request that asks
+  for the problem before the proposal and which surfaces and providers it
+  reaches, and a **provider compatibility report** that collects a
+  provider's PASS/PARTIAL/FAIL as a fixed table (provider, model,
+  credential lane, versions, which of `SessionReady` / `SpeechStarted` /
+  `FunctionCall` round-trip / barge-in were observed, the `check --json`
+  report, the wire error verbatim) with no audio, transcripts, or secrets;
+  `docs/PROVIDER-RECEIPT.md` is the how-to behind it and says how
+  maintainers act on each verdict. The bug form gained the core-contract
+  lane and the check/doctor/diagnostics commands as places a bug can
+  happen, and the issue chooser now links private security reporting and
+  Discussions. Labels `provider`, `surface`, `security`, and `docs` join
+  `good first issue` / `help wanted`. The README credits the people who
+  showed up: @kvnloo, @TheAngryPit, @webdevtodayjason. Ported idea from
+  bielcarpi/hermes-live-voice's provider-compatibility receipt (MIT) — idea
+  only, no text.
 - `SECURITY.md`: supported versions (the latest PyPI release and `main`),
   private reporting through GitHub security advisories (private vulnerability
   reporting is enabled on the repository), a 72-hour acknowledgement target,