feedback.md

Dashboard feedback

The spoke dashboard has a Feedback button in the avatar menu, a top-bar 🐛 button, and a Report an Issue item in the left sidebar. Use it to report a bug or request a feature; each submission becomes a GitHub issue in hivecommons/hive, or hivecommons/docs when you choose Documentation.

Submissions include the title, description, feedback type, target repository, the submitting dashboard identity, and optional pasted or uploaded screenshots. Diagnostics are optional and previewed before submit. Tokens, bearer values, emails, and secret-like key/value text are redacted before sending.

When Include diagnostics is checked, the dashboard discloses the collected fields in the modal before submit and adds the same "Diagnostics included" table to the GitHub issue:

• Version — so maintainers can reproduce on the same dashboard release build.
• Commit — so maintainers can inspect the exact code revision.
• Release channel — so maintainers know which update stream you are running.
• ACMM level — so maintainers can match the dashboard policy mode.
• Hive ID — so hub operators can correlate this report with this hive only.
• Hosted flag — so maintainers know whether this is a hosted or self-managed dashboard.
• Hub-linked flag — so maintainers can follow the same relay path.
• Agent count — so maintainers can spot empty or unexpectedly large agent sets.
• Agent names, backend, model, and state — so maintainers can reproduce the affected agent configuration.
• Whether project org/repos were included — so the report shows if the optional project context was shared.
• Browser user-agent — so maintainers can reproduce browser-specific rendering bugs.
• Browser platform — so maintainers know the operating system/browser platform family.
• Browser language — so maintainers can reproduce locale-sensitive formatting.
• Screen size — so maintainers can reproduce layout issues at the same display size.
• Window size — so maintainers can reproduce the dashboard viewport.
• Dashboard section/path — so maintainers know where you opened the form.
• Optional project repo for each agent — only when Include project org/repos in diagnostics is checked.
• Optional project org for each agent — only when Include project org/repos in diagnostics is checked.
• Recent browser console errors — so maintainers can see client-side failures that happened before submit.
• Recent failed /api calls — so maintainers can see backend requests that failed before submit.

Before submit, the modal shows which credential path will open the issue and who it is being opened for: Will be opened as @<credential-login> on behalf of @<user> · hive <hive-id> (<hub-linked: hub name | hub-less>). Hub-linked spokes show the hub until the hub records its actual GitHub App credential in the created issue body. If Hive must fall back to opening a prefilled GitHub URL in the browser and cannot resolve the submitter's GitHub login, it requires a GitHub username and remembers it in browser local storage for the next report. The username is used only to attribute the submitter on the issue.

The GitHub issue body always starts with Opened by @<credential-login> on behalf of @<user> from hive <hive-id> (<hub name | hub-less>) and includes a Submitted by diagnostics row. If the issue is opened manually through the fallback GitHub URL, the first line is Opened manually on GitHub on behalf of @<user> from hive <hive-id> (<hub name | hub-less>). If the dashboard knows a GitHub OAuth login or the submitter enters one, the row uses an @login mention and adds /cc @login; otherwise it records an unidentified dashboard user.

Issue authorship depends on the deployment shape:

• When the dashboard session has a GitHub OAuth token with public_repo (or repo) scope, the spoke creates the issue with that submitter token. GitHub shows the submitter as the issue author and the body starts Opened by @<submitter> from hive ....
• If no usable submitter token is available, hub-less spokes use the configured GitHub App installation token when it can be minted, regardless of hub.hive_type. The issue appears from the App bot and the body says it opened on behalf of the submitter.
• Hub-linked spokes relay feedback to the hub, and the hub creates issues only with the spoke's GitHub App installation token. It does not use the hub operator's PAT for authoring feedback issues.
• The dashboard never uses /data/gh-user-token or github.token to author feedback issues. /data/gh-user-token is the spoke owner's dashboard-login identity token: Hive validates that identity at most hourly and does not spend the owner's personal GitHub quota on background identity polling. If neither a submitter token nor an App installation token is available, it opens a prefilled GitHub issue URL. In that fallback path, GitHub authors the issue as the browser user who submits the form on github.com, and the modal requires the submitter's GitHub username before opening it.

Screenshots must decode to a real PNG or JPEG image (the bytes are sniffed; the data-URI media type alone is not trusted). Accepted images are committed to a dedicated feedback-screenshots branch of the target repository — never its default branch — under feedback-screenshots/<issue>/, and linked from an issue comment. The branch is created from the default-branch head the first time it is needed.

The 🐛 button also shows a notification pill for feedback filed from this hive. The spoke stores created issue references in /data/feedback-submissions.json, polls GitHub activity through the hub relay or the signed-in user's token, and counts issues whose updated_at is newer than the last time the My reports tab was viewed. Fallback-URL submissions are not tracked until GitHub issue creation succeeds through the dashboard.