| name | file-issue |
| description | File a Neru bug report or feature request that matches the repo's issue forms: duplicate check first, every required field filled with real diagnostics, correct labels. Use when asked to open, file, or draft a GitHub issue for Neru. Not for pull requests. |
Filing an issue in Neru
Blank issues are disabled (.github/ISSUE_TEMPLATE/config.yml) — everything
goes through a form, and an agent-filed issue must contain the same fields the
form enforces. gh issue create bypasses form validation, so you are the
validator.
Always, before filing
- Search for duplicates — the forms make humans attest to this, so do it
for real:
gh issue list --search "<keywords>" --state all, plus
discussions for feature ideas. Found one? Comment there instead of filing.
- Route non-issues away. Questions and config help belong in
Discussions; Linux porting talk belongs in discussion #559; "is this
supported yet" is answered by the Platform Support matrix in the README
and
docs/CROSS_PLATFORM.md. Filing an issue for these is wrong even if
the user asked for an issue — say so and offer the right venue.
Bug report (--label bug)
Mirror bug_report.yml's fields as markdown sections, all of them:
- Neru version — real output of
neru version, never guessed.
- Operating system and OS version (
sw_vers on macOS; distro +
compositor on Linux, since behavior differs across X11/wlroots/KDE/GNOME).
- Navigation mode — hints / grid / recursive grid / scroll / n.a.
- What happened / What did you expect — observed vs expected, concrete.
- Steps to reproduce — numbered, from
neru launch, minimal.
- Config (relevant sections) — only the TOML sections involved, fenced as
toml. Strip anything personal (macro contents, exec commands).
- Screenshots / recordings and Additional context when they help;
neru doctor output is gold for capability/permission-shaped bugs.
Linux/Windows caveat from the form: many features are intentionally
unimplemented there. If neru doctor reports the capability as stub, it is
a roadmap item, not a bug — check the matrix before filing.
Feature request (--label enhancement)
Mirror feature_request.yml:
- Category — one of: Navigation, Mouse actions, Configuration, CLI / IPC,
UI / Overlays, Performance, Platform support (Linux / Windows), Other.
- Target platform — All platforms / macOS / Linux / Windows.
- Problem or use case — the need, not the mechanism. This is the section
maintainers judge; write it first and best.
- Proposed solution, Alternatives considered, optional
Screenshots / mockups.
- Contribution — state plainly whether a PR will follow.
Filing
Draft the body, show it to the user before creating (an issue posts publicly
under their account), then:
gh issue create --title "<concise, user-facing summary>" --label bug --body-file <draft>
Title style matches the tracker: plain sentence, no conventional-commit
prefix, no trailing period.
The forms apply bug / enhancement automatically; gh does not, so pass it
yourself — and add the axes the forms never cover: platform: macOS /
platform: linux / platform: windows or cross-platform, the matching
area: * (overlays, event-tap, hotkeys, accessibility, cli,
config, domain, ipc, ui, infra), and stub implementation when the
ask is replacing a CodeNotSupported stub. gh label list is the authority.
