Reporting a problem

/bug prepares a problem report inside Mercury and files it in the repository through your own signed-in GitHub CLI, gh. By hand, the repository takes reports through its issue templates, and security problems through its Security tab.

Report routes

/bug <what happened>: Shows the exact report, then files it through your own signed-in gh.
Local draft: Without gh, the report stays a local draft under the config home, and Mercury names the repository's issues page.
Issue templates: The repository accepts a bug report, a provider or model report, or a feature request. Blank issues are disabled, and the template chooser links to the documentation index.
Security tab: A security problem goes through the repository's Security tab, never an issue.

Report a bug from Mercury

To report a bug from Mercury, follow these steps:

Enter /bug <what happened> with a description of the problem.
Review the exact report that Mercury shows.

/bug <what happened> shows the exact report, then files it through the signed-in gh, or keeps it as a local draft under the config home when gh is unavailable, and names the issues page.

Report a problem through an issue template

To report a problem through an issue template, follow these steps:

Open the repository's issues page.
Select the bug report, the provider or model report, or the feature request template.
Fill in the version line.
Fill in the operating system and terminal, with versions.
Describe the exact steps, one step per line.
Paste the doctor output for a bug or provider report.
Submit the issue.

The repository receives a report carrying the template's requested facts.

Requested information

Version: Every template asks for the --version line, as node dist/mercury.mjs --version or mercury --version prints it.
Environment: Every template asks for the operating system and the terminal host, with versions.
Steps: Every template asks for the exact steps, one per line.
Diagnostics: The bug and provider templates ask for the output of doctor --json, which carries no credentials.
Bug report: Also asks how Mercury was installed, what was expected and what happened instead. A pasted transcript of the failing screen helps; text is preferred over an image.
Provider or model report: Also asks for the provider family, the model row as /model shows it, where it happened, and the exact refusal or warning text pasted verbatim. Never paste an API key or a token.
Feature request: Asks for the task in your own words, what happens today, the behaviour wanted and where it belongs, and the steps to reach the gap.

Collect diagnostics

To collect diagnostics, follow these steps:

Run mercury doctor --json on a release install, or node dist/mercury.mjs doctor --json on a built source copy.
Paste the output into the bug or provider report.

The report carries the doctor certificate the templates ask for.

During the beta the repository takes issues, not pull requests: a pull request from outside the collaborator set is closed with a pointer to an issue, and a change proposal goes in an issue with the diff pasted in. The repository's contribution guide states this and covers building and checking a change.

Report a security problem

To report a security problem, follow these steps:

Open the repository's Security tab.
Select Report a vulnerability.
Include the --version line, the output of doctor --json, the operating system and terminal, the exact steps with what was expected and what happened instead, and for a provider problem the provider family and the model row.

The private report thread is where the conversation continues.

A security problem is never reported as a public issue or through any other channel. The latest release is the supported one; older releases receive no fixes, and the remedy is mercury update or a rebuild from the current source.

Health check, Command-line reference, Install and update, Providers and sign-in