Reporting Bugs

Use the floating Report a Bug button in the web or mobile app to send a report without leaving the screen you are on.

How to Open It

You can open the bug report panel in two ways:

• Click the floating bug button in the bottom-right corner.
• Use the keyboard shortcut:
• Ctrl+Shift+B on Windows
• Cmd+Shift+B on Mac

This opens a right-side panel where you can describe the issue and send the report.

In the mobile app, tap the floating bug button. It appears on every signed-in staff screen, stays above the persistent bottom navigation even on job and other detail pages, and opens a phone-sized report form.

What Gets Captured Automatically

When you submit a report, CleanEstimate Pro automatically captures:

• The current page URL
• Page title
• Recent page history
• Browser and operating system
• Viewport and screen size
• Last detected action
• Recent console errors
• Recent failed network requests
• Session and app version details
• A screenshot of the current app window

The automatic screenshot captures the page state you were looking at when you opened the report form. Mobile reports also include the installed version, native build, OTA update, device model, connection type, recent screens, app errors, and failed requests.

Note: The screenshot is taken automatically on submit, so you do not need to attach one manually for most reports. If automatic capture fails, the form now tells you right away so you can still send the report or attach one yourself.

Replacing the Automatic Screenshot

The Screenshot section still lets you attach your own image.

Use that if you want to:

• Replace the automatic capture with a cropped or annotated image
• Upload a screenshot from another device
• Share a screenshot taken before the issue changed state

Images over 2MB are compressed before upload. Final upload size is capped at 5MB.

Filling Out the Report

The most useful reports include:

• What went wrong?
• What were you trying to do?
• What did you expect to happen?
• Severity
• Category

If you are short on time, the description is the only required field. The diagnostic context and screenshot do a lot of the rest automatically.

Owners and managers are no longer capped at only five reports per hour. The app still applies a server-side abuse limit, but it is set high enough for real bug sweeps.

Offline Behavior

If you are offline when you submit a report:

• The report is queued locally
• The app keeps the captured details
• The report submits automatically when the browser comes back online

On mobile, queued reports are stored in app files rather than the normal business-data sync queue. They submit in the background after the same user reconnects to the same workspace. On web, an expired session restores the draft after you sign back in.

Who Can Review Reports

Submitted reports are reviewed from Admin --> Bug Reports. That review page is limited to owner accounts, and the owner inbox now stays tied to the owner's accessible org scope instead of disappearing or shrinking down to only the currently switched child workspace.

That view is where your team can:

• Open the full report
• Track the report by its bug number, such as BUG-0042
• Review the screenshot
• Read diagnostics and reproduction notes
• Update the report status
• Track whether the issue is new, acknowledged, in progress, resolved, or won't fix
• Review the automated intake verdict before escalating it
• Open the linked GitHub issue when bug-duty sync is enabled

GitHub Bug Duty

When GitHub bug sync is configured, CleanEstimate Pro can push strong bug reports directly into your repository as bug issues.

The app does not blindly sync every report. It first scores each submission for signal quality using the report details, reproduction notes, and captured diagnostics.

• Accepted reports sync automatically to GitHub.
• Needs review reports stay in Admin --> Bug Reports until an owner decides to push them
• Rejected reports are treated as likely training or low-signal submissions and stay out of the repo by default

Trusted owner reports from the native mobile app can also receive the codex:approved label at creation. That label starts the hosted Codex repair workflow without requiring the owner to repost the issue in a chat. Reports from other roles and workspaces still require approval so untrusted report text cannot start a code-writing agent.

The report creation endpoint accepts either the authenticated web session or the native app's bearer session plus selected-workspace header. The mobile app does not need a browser cookie to submit a report.

If GitHub is unavailable, or if an owner wants to override the automatic gate, the bug report detail page includes a manual Sync to GitHub action.

If sync fails, the bug report detail page now shows the sync error instead of looking like a silent no-op.

The admin review page keeps the report and smaller screenshot preview in the main column, with a sticky action rail for intake results, GitHub sync, status, and internal notes. Technical diagnostics start collapsed; open Technical Details only when logs, route state, or captured metadata are needed.

To enable GitHub bug-duty sync, configure the production app with:

• GITHUB_BUG_REPORTS_REPO
• GITHUB_BUG_REPORTS_TOKEN
• BUG_REPORT_AUTO_DISPATCH_ORG_IDS as a comma-separated allowlist of

workspace IDs whose native-app owner reports may start the repair runner

The repair workflow uses GitHub-hosted Ubuntu workers and the official Codex GitHub Action. It does not depend on an office computer or self-hosted runner. Configure the repository with:

• the OPENAI_API_KEY GitHub Actions secret
• the EXPO_TOKEN GitHub Actions secret for native-app OTA releases
• the repository-scoped DOCS_DEPLOY_KEY GitHub Actions secret
• Allow GitHub Actions to create and approve pull requests enabled under

Settings --> Actions --> General --> Workflow permissions

• .github/workflows/codex-bug-repair.yml
• .github/codex/prompts/fix-bug-report.md

The runner listens for issues with all of these labels:

• bug
• triage:accepted
• codex:approved

The workflow adds codex:started, checks out the application and documentation repositories, and gives Codex a sanitized report context that is explicitly treated as untrusted evidence. Codex diagnoses the issue, changes code, adds regression coverage, and updates the relevant documentation and changelog. The documentation checkout is moved outside the application workspace before the release gate runs so application linting and typechecking cannot scan the separate docs project. Automated commits use the connected repository owner identity so Vercel can verify the author as a project member and allow the production deployment.

When Codex produces a patch, the workflow opens a traceable pull request and runs the complete release gate: lint, typecheck, production build, web tests, mobile tests, database migration checks, database authorization tests, and the documentation build. It refuses to merge if main changed while those checks were running. It also blocks automated changes to the runner, release configuration, dependency manifests, and database migrations. After every gate passes, it pushes the matching documentation, fast-forwards the exact tested repair into main, and closes the report. The merge triggers the Vercel production deployment, and the workflow waits for Vercel to confirm it. If mobile files changed, the workflow also publishes an Expo production OTA for iOS and Android.

Every 10 minutes, a recovery pass finds approved reports that never started. Production repairs run one at a time so two agents cannot race to merge. A successful repair receives codex:completed; a report with no patch receives codex:needs-review; a failed release gate receives codex:failed; and a failure after merge receives codex:deploy-failed. Failure comments include a link to the Actions log. Failed runs require a manual retry so a broken report cannot consume API credits forever.

The previous OpenClaw workflow used runs-on: self-hosted even though the repository had no registered runner. Jobs waited and were eventually cancelled. That workflow and its local dispatcher script have been removed.

Best Practices

• Submit the report as soon as the bug happens so the automatic screenshot reflects the right state.
• Add one sentence describing what you clicked just before the problem started.
• If pricing, totals, or customer data look wrong, mark the severity accurately so the team can triage it faster.
• If the issue blocks work entirely, use High or Critical.