Client Debug Reporter

Overview

The client debug reporter is the pinned bottom-right bug icon in the admin and client portal shells. It is off by default and can be enabled per-environment.

Environment Setup

On the API service:

GITHUB_ISSUE_TOKEN=github_pat_with_issues_write
CLIENT_DEBUG_REPORTER_ENABLED=true
# Optional when REDIRECT_URL is not the public API origin used by GitHub.
CLIENT_DEBUG_PUBLIC_API_URL=https://api.v2.affinitydesign.ca
CLIENT_DEBUG_SCREENSHOT_TTL_DAYS=90

On the web service:

NEXT_PUBLIC_CLIENT_DEBUG_TOOL=true

Restart or redeploy both services after changing the values.

Runtime Behavior

• Authenticated admin, user, and client sessions can submit reports to POST /debug/client-report.
• Browser errors and unhandled promise rejections open the reporter automatically. Recoverable render errors that React's own error boundary already recovered from (error #185 "Maximum update depth exceeded" and the boundary-recovery log) are still captured in the console log buffer and increment the badge, but no longer auto-open the panel.
• Manual reports can be submitted from the pinned bug icon.
• Reports include the note, current page, viewport, user agent, recent clicks and navigation events, recent console warnings/errors, and a compressed page screenshot.
• Screenshots are stored in MongoDB with a random token and linked into the GitHub issue as a normal HTTPS image URL. GitHub does not render inline data:image/... URLs in issue bodies.
• Sensitive values such as bearer tokens, JWTs, API keys, passwords, secrets, and email addresses are redacted before the issue is created.
• The GitHub issue is labelled auto-reported, client-reported, and client-debug, so the existing Copilot auto-fix workflow can pick it up.
• The reporter tries to create the required labels automatically. If GitHub rejects label creation, create bug, auto-reported, client-reported, and client-debug manually in the repository labels page.

Agent Assignment

The issue creation token and the Copilot assignment token are separate:

• GITHUB_ISSUE_TOKEN lives on the API service and only creates issues.
• COPILOT_AGENT_TOKEN lives in GitHub repository secrets and lets the workflow assign Copilot cloud agent.

See Self-Healing Agent Loop for the full loop setup.

Validation Checklist

1. Confirm the API has GITHUB_ISSUE_TOKEN and CLIENT_DEBUG_REPORTER_ENABLED=true.
2. Confirm the web bundle was built with NEXT_PUBLIC_CLIENT_DEBUG_TOOL=true.
3. Sign in to the portal or admin app.
4. Click the bottom-right bug icon, add a short note, and submit.
5. Confirm a new issue appears in Affinity-Design/af-gemini-connect with the client-debug label.
6. Confirm the screenshot section renders an image and the Open screenshot link points at the public API host.