The bug widget — your support channel

Reading time: 5 minutes. Hands-on time: 2 minutes. What you'll have at the end: Confidence in how to file bugs that get fixed fast, and an understanding of how the bug-report loop benefits every customer at once.

What the bug widget actually is

A 🐛 button at the bottom-right of every page. Click it, drag in a screenshot or take one with the screenshot tool, type one sentence describing what's wrong, click submit. That's it.

What happens behind the scenes:

1. You file the bug
2. Gemini Flash triages it — assigns severity (low / medium / high / critical), category (bug / feature-request / docs / question / feedback), one-line synopsis
3. Lands in /admin/bug-reports within ~5 seconds
4. Tom (or whoever's on call) sees it on phone (push notification) or laptop
5. The fix ships — either same-day for critical, or in a weekly batch for everything else
6. You get notified when the fix lands — by email, in-app, or via the dashboard's "Resolved bugs" section

The bug widget is not a feature. It's the architecture of how this product gets better. Every bug a customer hits gets fixed for every customer. There's no per-customer special handling.

When to file a bug

Honestly: when in doubt, file it. The cost of a false-positive bug report is 30 seconds of Tom's time. The cost of a missed bug is a feature that's broken for every customer until someone else complains.

Specifically, file a bug when:

• ❗ Something crashes, errors, or returns 500
• ❗ A button does nothing
• ❗ A page renders but is missing content
• ⚠ A copy / image / email looks wrong (AI mis-output)
• ⚠ A workflow takes way longer than the time estimates promised
• 💡 Something is unclear, confusing, or made you go "wait what does this do?"
• 💡 Something is correct but you'd improve it

Don't worry about formatting, severity, or whether it's "really a bug." The AI triages all that. Just describe what you saw and what you expected.

How to file the perfect bug report

Three things, in order of importance:

1. Screenshot of the moment it happened

The widget has a built-in 📸 Capture screen button that grabs the page you're on. Drag any other image in too.

A picture beats 500 words. If you don't include a screenshot, we have to imagine your dashboard's state. With a screenshot, half the bugs are diagnosable in 30 seconds.

2. One sentence: "I expected X, but I got Y"

Bad bug description:

"The thing isn't working"

Good bug description:

"Clicked Generate on the ad creator. Expected an ad to appear in the gallery. Got a red toast saying 'failed' but no detail. Screenshot attached."

The structure: action → expectation → reality. Even one line of that beats five paragraphs of context.

3. Optional: how to reproduce

If you can repeat the bug, write the steps:

1. Connected Shopify with valid token
2. Clicked /products
3. Clicked any product
4. Page is blank, console error: TypeError: Cannot read properties of undefined

Reproducible bugs get fixed first. If you can't reproduce, say so ("only happened once, may have been my flaky wifi") — that's still useful information.

What the AI auto-fills

When you submit, Gemini Flash reads your description + the screenshot (yes, multimodal — it actually looks at the image) and fills in:

You can override any of these. But honestly the AI is right ~85% of the time, so most users just submit and trust the triage.

What happens after you submit

You see a green toast:

✓ Bug submitted — bug ID bug-x7q2… · severity: high · we'll get on it

Click the toast to track the bug:

• Status updates: triaged → in-progress → fixed → released
• Operator comments (if Tom has questions): you'll see them here
• Release tag when fixed: e.g. "Fixed in v1.2.3 — released 2026-04-30"

You also get an email if you have notificationEmail set in your profile.

The operator side (what Tom sees)

If you're curious what happens on Tom's end:

1. Bug arrives in /admin/bug-reports with AI-triaged metadata
2. Tom skims the screenshot + description in 10 seconds
3. He clicks Add operator proposal — a dialog opens for him to write a proposed fix:

   Title: Fix blank product page
   Why this happened: undefined property access on missing brief
   Files to change: /lib/product-context.ts line 47
   Test plan: load /products with no curated briefs, page should render
   

4. At end of day / end of week, Tom clicks Export punch list — gets a markdown file with all proposed fixes formatted as a Claude-task brief
5. Pastes into a Claude task → Claude ships fixes → Tom tags a release → Watchtower or manual update pushes the new image to all customers

This whole loop is designed so that one customer's bug becomes everyone's fix in <72 hours.

Best-practice patterns (from heavy users)

File while you're frustrated

The widget is fastest when the frustration is fresh. Don't think "I'll file this later" — you'll forget the exact symptom. 30 seconds now beats 5 minutes of "wait, what was happening again?" tomorrow.

Use it for compliments too

Filing as category: feedback with a positive note is genuinely useful. We can't tell what's working without that data. "The brand voice four-path chooser was great — picked the interview path and the doc was 80% there" is more useful than no message.

Stack-trace screenshots beat text

If you see a JavaScript error in the browser console (F12), screenshot the full stack trace, not just the error line. Stack frames tell us which file + line. We can fix in minutes vs. hours.

Don't sanitise

If you hit a bug at 11pm in your pyjamas after three glasses of wine, the bug report is allowed to say "tried to generate an ad and it shit the bed." We're not Apple Support. Direct language gets better fixes.

What we DON'T use bug reports for

To set expectations:

• ❌ Personal support questions — "How do I do X?" should go to /help (the AI help inbox), not bug reports
• ❌ Feature requests we'd never build — "Make Scarif One generate Klingon ad copy" — fine to file but expect the polite "won't fix"
• ❌ Marketing brand voice questions — "Why isn't my AI sounding more like Steve Jobs?" → tutorial 05 or /setup brand voice

Bug reports are about things that are wrong. Help requests + feature requests + brand-strategy questions go through different channels (covered in tutorial 11 — the dashboard tour).

Privacy + what we store

The bug report you file is stored under your tenant in /data/tenants/{your-slug}/bug-reports/{bug-id}.json. It does NOT leave your install unless you opt in to phone-home telemetry (/admin/telemetry).

• Self-host customers: bug reports stay on your server. To get them to Tom, you have to actively send him the export from /admin/bug-reports/{id}/export. We respect your data sovereignty.
• Hosted customers: bug reports are visible to us automatically (you're on our infra). If you want to redact something before submitting, edit the description before clicking Submit.

In neither case does your screenshot get sent off-device for anything except the AI triage step (which calls Gemini with the image attached). Gemini's API doesn't retain inputs after generation per Google's enterprise policy.

The recursion: file bugs about the bug widget

If the bug widget itself breaks, file a bug about it through the bug widget. If the bug widget can't reach the API to file a bug about itself being broken, you have a ⏳ fallback: open /admin/bug-reports/manual — a plain HTML form that posts to the same backend but uses no JavaScript.

If even that's broken, email support@scarifone.com with the screenshot. We'll plumb it back into the system manually.

The point: there's always a path. We don't lose bug reports.

Where to next

• Tutorial 11 — The dashboard tour (the bug widget is one of ~30 dashboard surfaces — see what else is there)
• Tutorial 09 — Spend caps + approval gate (also safety surfaces — file a bug if either misbehaves)
• Bookmark /admin/bug-reports — once you've filed a few, this is your status page