docs: replace the markdown bug template with GitHub issue forms

[cliffhall]

Closes #1844

What this does

Replaces the single legacy markdown issue template with GitHub issue forms, so the fields triage needs are actually enforced rather than being prose headings a reporter can delete.

File	Purpose
.github/ISSUE_TEMPLATE/1-bug_report.yml	new — replaces bug_report.md. Auto-labels bug.
.github/ISSUE_TEMPLATE/2-feature_request.yml	new — auto-labels enhancement.
.github/ISSUE_TEMPLATE/config.yml	new — blank_issues_enabled: false + contact links.
.github/ISSUE_TEMPLATE/bug_report.md	removed — superseded by the form.

Bug report requires: version line (v1 / v2), client (web / cli / tui / shared core), Inspector version, Node version, transport (stdio / Streamable HTTP / SSE), the MCP server under inspection, repro steps, expected, and actual. OS/browser, logs, and screenshots are optional. Its intro states that maintainers implement the fix, so a prompt plus screenshots beats a diff — and there's a field for exactly that. Two required acknowledgement checkboxes cover duplicate-search and "this is not a security report".

Feature request puts the problem first and marks the solution optional, on the grounds that the problem is what survives when a particular solution turns out not to fit, and says plainly that maintainers do the implementation.

The security template is deliberately a contact link, not a form

The issue asks for a "v1 security issue" template that redirects to the advisory process rather than collecting details in public. A .yml template can't do that — it still opens a public issue, which is precisely what a vulnerability report must not do. GitHub's mechanism for a chooser entry that leaves the issue flow entirely is a contact link, so that is what this uses:

• 🔒 Security vulnerability (v1 or v2) — report privately → /security/advisories/new (private vulnerability reporting is enabled on this repo, so it's a working route)
• 📜 Security policy → SECURITY.md

The link copy names v1 explicitly, since v1 is deprecated and security fixes are the only thing it takes.

The remaining contact links deflect the recurring misfiled classes: the specification repo and the TypeScript SDK for reports that aren't about this tool, the docs site, the contribution policy (CONTRIBUTING.md — why there is no "New pull request"), and #inspector-dev on Discord.

Why neither form applies a v1/v2 label

GitHub can't map a form answer to a label — labels: is static. So the version line is a required dropdown and a maintainer still applies the version label at triage, per AGENTS.md. Routing that answer early is the point: a v1 report needs a different answer than a v2 one.

Drive-by link fix

The #1884 rename (CONTRIBUTORS.md → CONTRIBUTING.md) left three dangling links on this branch — two in .github/pull_request_template.md, one in SECURITY.md. Fixed here; a policy nobody can open is the same as no policy.

Docs

Per the AGENTS.md documentation rule: CONTRIBUTING.md now points at the chooser and notes blank issues are disabled, and AGENTS.md's Contributing section documents the forms, the no-auto-version-label constraint, why there's no security template, and the schema gotchas for future edits. README.md needed no change (its layout tree doesn't cover .github/), and .github/copilot-instructions.md needed none either — issue templates aren't a rule a reviewer cites against a diff, which AGENTS.md lists as the mirror's scope test.

Verification

⚠️ Issue forms cannot be previewed before merge. GitHub renders the chooser and the forms from the default branch only, so nothing on this branch (or on v2/main after merge) is visible in the UI until it reaches main at the next milestone merge. There is no "preview this template" affordance on a PR.

So the forms were validated against the schema instead: every file parses as YAML, type: values are all in {markdown, input, textarea, dropdown, checkboxes}, all ids are unique per file, markdown blocks carry no id and no validations (both rejected by GitHub), checkboxes mark required per option rather than under validations, every attribute is one the field type allows, and each contact link has all three of name/url/about with an absolute URL.

npm run validate passes. This diff touches only .md and .github/**/*.yml — no extension in any prettier glob, and outside verify:format-coverage's SOURCE_EXTENSIONS, so npm run format is a no-op on it and the heavier gates (coverage, verify:build-gate, smoke, Storybook) have nothing to exercise.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YAt8rqxysNbhYWLhoRm3fU

[Copilot]

Pull request overview

Replaces the legacy Markdown bug-report template with GitHub Issue Forms and configures the issue chooser to enforce required triage fields, while updating repo docs to point contributors at the new flow and fixing a few renamed-file links.

Changes:

• Added two Issue Forms (bug report + feature request) and an issue-chooser config.yml with contact links (including private security reporting).
• Removed the old .github/ISSUE_TEMPLATE/bug_report.md Markdown template.
• Updated contribution/security docs and templates to reference CONTRIBUTING.md and the new issue-forms flow.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
SECURITY.md	Updates the contribution-policy link to CONTRIBUTING.md.
CONTRIBUTING.md	Adds guidance pointing users to the issue chooser/forms.
AGENTS.md	Documents the new issue forms + chooser behavior for future maintenance.
.github/pull_request_template.md	Fixes renamed-file references in the PR template copy.
.github/ISSUE_TEMPLATE/config.yml	Disables blank issues and adds contact links (security, policy, redirects).
.github/ISSUE_TEMPLATE/1-bug_report.yml	New bug-report issue form with required triage fields.
.github/ISSUE_TEMPLATE/2-feature_request.yml	New feature-request issue form emphasizing problem-first reports.
.github/ISSUE_TEMPLATE/bug_report.md	Removes the legacy Markdown issue template.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (1)

CONTRIBUTING.md:74

• In this new paragraph the line break splits the phrase "The same chooser" across two lines ("The" at end of one line), which makes the raw Markdown harder to read/edit and is likely accidental. Consider re-wrapping so the sentence isn't broken mid-phrase.

(GitHub serves the chooser from the repository's **default branch**, so what
you see when filing is whatever has reached `main`; a form added on `v2/main`
appears at the next milestone merge.) The
same chooser links out to the private security-advisory process, to this

[cliffhall]

Round 2: Copilot reviewed all 8 files and generated no new comments. The one suppressed nit (a dangling The at end of line in the new CONTRIBUTING.md paragraph) is fixed in 88f098f — re-wrapped, no wording change.

Round 1's four comments are all resolved in 4d32c2d: PR-template base branch corrected to v2/main, the Node floor on the bug form scoped to the v2 line, and both CONTRIBUTING.md and AGENTS.md now state that the chooser is served from the default branch. The only thing declined was making a path inside an HTML comment a markdown link — it never renders, and the visible blockquote below it already carries the clickable link.

npm run validate passes; the forms re-validate clean against the issue-forms schema after every edit.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (1)

.github/ISSUE_TEMPLATE/1-bug_report.yml:96

• The MCP server description says "protocol era (legacy / modern) if you selected one", but this form doesn't have any protocol-era selection. That phrase is confusing; suggest removing it and just asking the reporter to include the protocol era if relevant.

      description: >
        Which server, and how it is configured — the command or URL, the
        protocol era (legacy / modern) if you selected one, and whether OAuth
        is involved. Redact tokens and secrets.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (3)

CONTRIBUTING.md:68

• This paragraph implies both issue forms require version line + transport fields, but the Feature request form doesn’t ask for either (it’s v2-only and focuses on the problem statement). Tighten the wording so it only claims those required fields for the bug report form.

offers a **Bug report** and a **Feature request** form. Blank issues are
disabled, so pick one of the two — the required fields (which client, which
version line, which transport) are exactly the facts triage needs first.

AGENTS.md:123

• This sentence says “Neither form applies a v1/v2 label — the version line is a required dropdown…”, but only the Bug report form has a version-line dropdown; the Feature request form is v2-only. Reword so it doesn’t imply both forms share the same version-line field.

**Issues are filed through the forms in [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE) — blank issues are disabled.** GitHub serves the chooser from the **default branch** only, so a form edited here on `v2/main` has no effect on the live chooser until the next milestone merge into `main` — and it cannot be previewed before then, which is why the schema notes below matter. There are two forms, **Bug report** (`1-bug_report.yml`, auto-labels `bug`) and **Feature request** (`2-feature_request.yml`, auto-labels `enhancement`); `config.yml` holds the chooser's contact links. Neither form applies a `v1`/`v2` label — the version line is a required *dropdown*, since GitHub can't map a form answer to a label, so a maintainer still applies the version label at triage per [Label by version](#issue-driven-work-style). **There is deliberately no security template**: a vulnerability report must not open a public issue, so the chooser routes it to the private advisory form as a contact link instead (see [`SECURITY.md`](./SECURITY.md)). When adding or changing a form, validate it against GitHub's issue-forms schema (`markdown` blocks take no `id` and no `validations`; `checkboxes` mark `required` per option, not under `validations`).

.github/ISSUE_TEMPLATE/config.yml:4

• The header comment says every report lands in a form with required fields including “version line” and “transport”, but that’s only true for the bug report form (the feature request form doesn’t capture those). Update the comment to avoid misleading future editors.

# Blank issues are disabled so every report lands in a form with the fields
# triage actually needs (client, version line, transport).

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (1)

AGENTS.md:123

• This paragraph contradicts itself: it says neither form can apply a v1/v2 label because labels: is static, but then claims the feature form “is always labeled v2”. The feature-request form currently only auto-labels enhancement, so this sentence is incorrect/misleading.

**Issues are filed through the forms in [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE) — blank issues are disabled.** GitHub serves the chooser from the **default branch** only, so a form edited here on `v2/main` has no effect on the live chooser until the next milestone merge into `main` — and it cannot be previewed before then, which is why the schema notes below matter. There are two forms, **Bug report** (`1-bug_report.yml`, auto-labels `bug`) and **Feature request** (`2-feature_request.yml`, auto-labels `enhancement`); `config.yml` holds the chooser's contact links. Neither form applies a `v1`/`v2` label, because GitHub can't map a form answer to a label — `labels:` is static. The **bug** form therefore carries a required version-line *dropdown* and a maintainer applies the matching label at triage per [Label by version](#issue-driven-work-style); the **feature** form has no such dropdown, since v1 takes security fixes only and cannot receive a feature, so it states up front that it targets v2 and is always labeled `v2`. **There is deliberately no security template**: a vulnerability report must not open a public issue, so the chooser routes it to the private advisory form as a contact link instead (see [`SECURITY.md`](./SECURITY.md)). When adding or changing a form, validate it against GitHub's issue-forms schema (`markdown` blocks take no `id` and no `validations`; `checkboxes` mark `required` per option, not under `validations`).

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

[cliffhall]

Review loop closed — round 6 is clean on the current head (a9c76874): no comments, and no suppressed comments either.

Rounds 3–6 all reviewed commits pushed after an earlier clean round, so nothing on this branch is unreviewed. Summary of what the later rounds turned up, since none of it was cosmetic:

Round	Head	Verdict
1	e67ff318	4 comments — all answered inline (3 fixed, 1 declined with reason)
2	4d32c2de	no new comments; 1 suppressed nit fixed
3	88f098f7	no new comments; 1 suppressed nit fixed
4	20c51277	no new comments; 3 suppressed nits, all one real error
5	a2ba194b	no new comments; 1 suppressed nit — a real contradiction
6	a9c76874	clean, nothing suppressed

Two of those were worth more than the "suppressed" tier suggests:

• Round 4 caught that I had described "client, version line, transport" as the required set for both forms, in three places. The feature form has neither a version-line dropdown nor a transport field. Fixed in a2ba194b — each of the three now distinguishes the forms instead of generalizing from the bug form.
• Round 5 caught a self-contradiction in AGENTS.md: no form can apply a version label, yet the feature form "is always labeled v2". Resolved in the direction that makes the claim true (a9c76874): labels: being static is only an obstacle when the value depends on a reporter's answer, and it doesn't here — v1 takes security fixes only, so a feature request is v2 by construction. The feature form now declares ["enhancement", "v2"] outright, which also satisfies the label-at-create-time rule with no triage step. The bug form still can't, and shouldn't — its version line is genuinely the reporter's to answer.

npm run validate passes. Forms re-validated against the issue-forms schema after every edit.