# Cirlo Widget - Integration

Cirlo collects bug reports and feedback from your app's users, then diagnoses,
fixes, and drafts replies. The widget is a single script tag.

## Install

Add this before the closing </body> tag (or, in a React/Next.js app, load it via
the framework's script mechanism in the root layout):

<script src="https://cirlo.dev/widget.js" data-key="YOUR_WIDGET_KEY" data-accent="#4f46e5" data-position="bottom-right" data-lang="de" defer></script>

- data-key (required): your project's widget key, starts with `w_`.
- data-accent (optional): the app's accent color as a hex value.
- data-position (optional): `bottom-right` (default) or `bottom-left`.
- data-lang (optional): `de` (default) or `en`.
- data-repro (optional): set to `off` to disable browser capture entirely.

No further code is needed. The widget renders a floating "Feedback" button,
isolates its own styles in a shadow DOM, and phones home on first load so the
project's install status turns green.

## What the widget captures

With a bug report (never with an idea or praise) the widget sends a repro
package: the last 40 events before the report, kept in memory only.

- clicks: element description (tag, id or first class, visible text). For form
  fields only the field name is recorded, never the entered value.
- navigation: pathname only, without query strings.
- JS errors: message and source location (console.error, uncaught errors,
  unhandled promise rejections).
- failed requests: method, URL without query string, status code, duration.
  Only responses with status >= 400 or network failures.

Never captured: keystrokes, input values, request or response bodies, headers,
cookies, screenshots, video. Secret-looking strings are stripped server-side.
The whole package is capped at 8 KB. Customers can turn it off per project.

## Identify a logged-in user (optional)

If your app knows who the user is, attach their email so replies can reach them:

window.cirlo.identify({ email: "user@example.com", name: "Alex" });

## Notes for AI coding agents

- Insert the script tag once. It self-initializes and guards against double init.
- Do not inline or reimplement the widget code - always load widget.js from the src above.
- The accent color should match the host app's primary color.

## Crash reports from Sentry

Cirlo can take a second intake besides the widget and the support inbox: a
Sentry alert rule pointed at the project's Sentry webhook URL. A crash nobody
reported still becomes a diagnosed issue with a fix brief. If a user later
reports the same error, Cirlo attaches their report to the same issue and
mails them once it is fixed. The webhook URL is created in the project
settings; one crash counts once against the quota no matter how often Sentry
alerts about it.

## Connecting a coding agent

Cirlo is an MCP server at /api/mcp (streamable HTTP, bearer token). Tools:
list_issues, get_issue, get_fix_prompt, resolve_issue. See /docs/mcp.