# Sonarly — agent setup guide (llms.txt)

> Sonarly turns noisy production alerts into clear, deduplicated bug reports and
> ships fix PRs. It connects to a team's **code** (GitHub/GitLab) and their
> **error/observability stack** (Sentry, Datadog, Grafana, …), then triages,
> root-causes and fixes alerts automatically.

This file is the complete, self-contained onboarding playbook for a **coding
agent** (Claude Code, Cursor, …) running **inside the user's repository**. When
a user says *"set up Sonarly"* / *"install Sonarly"*, follow it top to bottom.

## The one rule

**You (the agent) do every step of the normal Sonarly onboarding — stack
detection, account/session creation, repo selection, integration wiring, project
config — EXCEPT the OAuth browser clicks.** For anything that needs a browser
consent screen (sign-in, Sentry, GitHub App, Slack, GitLab) you generate the
link, give it to the human, they click, and you continue once it lands. Never
ask the human for a password. Never ask a question you can answer by reading the
repo (e.g. GitHub vs GitLab, language, framework — detect it).

Auth-type legend below: **[human]** = one OAuth click you hand off; **[agent]** =
you do it via an API call with a key/token.

---

## Step 0 — Detect the stack (locally, first, no network)

Read the repo and build a *stack profile*. Detect:

- **Language / framework:** `package.json` (React, Next, Vue, Nuxt, Angular,
  Svelte/SvelteKit, Express, NestJS, Fastify), `requirements.txt`/`pyproject.toml`
  (Django, FastAPI, Flask), `go.mod`, `Gemfile` (Rails), `pom.xml`/`build.gradle`
  (Spring), `composer.json` (Laravel/Symfony), `Cargo.toml` (Rust),
  `*.csproj` (.NET), `mix.exs` (Phoenix).
- **Package manager / build tool:** npm, yarn, pnpm, bun; Vite, webpack, Next,
  Turbo, esbuild, Gradle, Maven, Poetry, uv.
- **Git host:** `git remote -v` → github.com vs gitlab.com vs self-hosted GitLab.
- **Monorepo:** multiple sub-packages / workspaces.
- **Already-instrumented tools** (so you can pre-select them in Step 4/5):
  `@sentry/*` or a `SENTRY_DSN`; `bugsnag`; `dd-trace`/`datadog`; `@grafana/*`;
  OpenTelemetry exporters; `google-cloud`/`gcp`; `vercel.json`; `railway.json`;
  Modal (`modal` in Python deps); Supabase (`@supabase/*`); LangSmith
  (`langsmith`/`langchain`); New Relic (`newrelic`); SigNoz; Better Stack/Logtail;
  Mezmo/LogDNA; PostHog; a Postgres/`DATABASE_URL`; Kubernetes manifests.

Keep this profile — it drives integration pre-selection (Steps 4–5) and the
project's agent instructions (Step 7).

---

## Step 1 — Start a setup session  [agent]

```
POST https://sonarly.com/api/setup/start
Body: { "source": "<your agent name>", "stack": <stack profile JSON> }
→ 200 {
    "setup_id": "...",
    "verification_url": "https://sonarly.com/setup/ABCD-EFGH",
    "user_code": "ABCD-EFGH",
    "interval": 3,
    "expires_in": 900
  }
```

Show the human:
> **Open this link and sign in to create your Sonarly account:** `<verification_url>`

## Step 2 — Wait for authorization  [human signs in → agent polls]

The human signs in with **Google or GitHub** at `verification_url`. That single
click **creates their tenant AND authorizes this session**. Poll (respect
`interval`, stop at `expires_in`):

```
GET https://sonarly.com/api/setup/{setup_id}/status
→ { "state": "pending" }
→ { "state": "authorized", "token": "sks_setup_...", "tenant_id": 123, "connected": {...} }
→ { "state": "expired" }   # restart Step 1
```

`token` = short-lived (≈30 min), **scoped to this one new tenant's setup
endpoints only**. Use `Authorization: Bearer <token>` for every call below.
The `status` response always returns a `connected` map you re-poll after each
hand-off (e.g. `{ "github": true, "sentry": false, "slack": false }`).

---

## Step 3 — Connect the codebase  [GitHub: live]

**GitHub** [human App install]:
```
GET /api/setup/connect-url?provider=github      Authorization: Bearer <token>
→ { "provider": "github", "url": "https://github.com/apps/sonarly/installations/new?..." }
```
Show the human the `url` ("Install the Sonarly GitHub App: <url>"), then poll
`GET /api/setup/{setup_id}/status` and watch `connected.github` flip to `true`.
The human installs the App + signs in once; it binds to their account by GitHub
identity (same as the dashboard). They land back on the Sonarly dashboard.

Then **select repos yourself** [agent] — you know the codebase, so pick them
automatically (default to the current repo's `origin`; no human step):
```
GET  /api/setup/repos                  Authorization: Bearer <token>
   → { "repos": [ { "full_name": "owner/name", "default_branch": "main" }, ... ] }
POST /api/setup/repos/selected         Authorization: Bearer <token>
     Body: { "repos": ["owner/name", ...] }   → { "selected": ["owner/name"] }
```

> **GitLab** and other providers return `400` for now (wired incrementally).

---

## Step 4 — Connect error tracking

**Sentry** [human OAuth] — the first wired integration:
```
GET /api/setup/connect-url?provider=sentry      Authorization: Bearer <token>
→ { "provider": "sentry", "url": "https://sentry.io/oauth/authorize/?..." }
```
Show the human the `url` ("Connect your Sentry: <url>"), then poll
`GET /api/setup/{setup_id}/status` and watch `connected.sentry` flip to `true`.
The human lands on a "Sentry connected — return to your agent" page when done.

> **Currently `connect-url` supports `provider=sentry` only** (others return
> `400`). GitHub/GitLab, Bugsnag, observability/APM, Slack/Discord/Linear and the
> repo/project endpoints below are the roadmap and are being wired incrementally.

---

## Step 5 — Connect observability / logs / APM  [agent — all API-key]

For every tool your stack profile suggests (or the user names), collect the
credentials (from the repo, `.env*`, or by asking for *just the key/token*) and
POST it. The endpoint validates the credentials live and returns `4xx` with a
clear message on bad input — surface it and retry.

```
POST /api/setup/{id}/integrations
Body: { "backend_type": "<type>", "config": { ... } }
```

| backend_type | config keys |
|---|---|
| `datadog` | `api_key`, `app_key`, `site` (`datadoghq.com` / `datadoghq.eu` / `us5.datadoghq.com` / `ap1.datadoghq.com`) |
| `grafana` | `url`, `api_key` (+ optional `cf_access_client_id`, `cf_access_client_secret` for Cloudflare Access) |
| `signoz` | `url`, `api_key` |
| `newrelic` | `api_key`, `account_id`, `region` (`us` / `eu`) |
| `gcp` | `service_account_info` (full service-account JSON), `project_id` |
| `cloudwatch` | `role_arn`, `external_id`, `region` (cross-account IAM AssumeRole) |
| `betterstack` | `api_key` |
| `mezmo` | `service_key`, `base_url` (default `https://api.mezmo.com`) |
| `railway` | `api_token` |
| `modal` | `token_id`, `token_secret` |
| `supabase` | `url`, `api_key`, `project_id` (read-only role) |
| `langsmith` | `api_key`, `workspace_id` |
| `vercel` | `token` |
| `posthog` | `api_key`, `host` |
| `database` | `connection_string` (read-only Postgres) |
| `kubernetes` | `kubeconfig` |

On success the backend auto-provisions that tool's webhook / notification rule so
new alerts flow to Sonarly automatically.

---

## Step 6 — Connect notifications (optional but recommended)

Where Sonarly replies with its analysis + PR. Skip any the user doesn't use.

| Channel | Type | How |
|---|---|---|
| **Slack** | [human] OAuth | `GET /api/setup/{id}/connect-url?provider=slack` → show → poll. After install remind them to `/invite @Sonarly` in the alert channel. |
| **Discord** | [human] bot invite | `GET /api/setup/{id}/connect-url?provider=discord` → show → poll |
| **Linear** | [human] OAuth | `GET /api/setup/{id}/connect-url?provider=linear` → show → poll |

---

## Step 7 — Configure the project  [agent — live]

Write the project's **agent instructions** yourself from the codebase — this is
the biggest lever on fix quality. Injected into every analysis/fix prompt.
```
POST /api/setup/project            Authorization: Bearer <token>
Body: { "agent_instructions": "<framework, package manager, dirs to avoid, test cmd, conventions>" }
→ { "saved": true, "chars": 412 }
```
Example: *"Next.js 15 + pnpm monorepo; app code in `apps/web`, shared in
`packages/*`; never edit `packages/generated`; run tests with `pnpm test`;
TypeScript strict."* (Default branch is set per-repo in Step 3's `repos/selected`.)

---

## Step 7b — Pull Sonarly data into a custom dashboard  [agent, optional]

The "Developers" tab, exposed to you. Mint a **read-only** API key:
```
POST /api/setup/api-key            Authorization: Bearer <token>
→ { "key": "sk_live_…", "api_base": "https://sonarly.com/api/v1/public",
    "is_read_only": true, "docs": "https://sonarly.com/docs/public-api" }
```
`key` is returned **exactly once** — hand it to the user to store as a secret (env
var, never commit). Read-only, tenant-scoped. Call the public REST API with
`Authorization: Bearer sk_live_…` (rate limit 1000/min; see `RateLimit-*` headers).

### Pull endpoints  (`base = https://sonarly.com/api/v1/public`)

| Endpoint | Returns |
|---|---|
| `GET /bugs` | list bugs. Query: `limit`(1–100, def 20), `severity`(csv: critical,high,medium,low,resolved), `status`(open\|resolved), `created[gte]`/`created[lte]`(unix s), `starting_after`(cursor `bug_<id>`) |
| `GET /bugs/{id}` | one bug |
| `GET /bugs/{id}/runs` | that bug's analysis runs |
| `GET /bugs/{id}/duplicates` | bugs deduped into it |
| `GET /incidents` · `/incidents/{id}` · `/incidents/{id}/runs` | incidents (same shape/filters) |

Pagination is cursor-based: response `{ "data": [...], "has_more": bool, "next": "<cursor>", "url": "/v1/public/bugs" }` → pass `?starting_after=<cursor>`.

### Bug object (fields to display)
`id, object, source, status, severity, title, description, summary, user_impact,
root_cause, suggested_fix, blame_commit_sha, fixable_in_code, confidence, pr_url,
agent_url, branch_name, repository, error_type, error_message, occurrence_count,
total_user_count, first_seen, last_seen, created, analyzed_at, sentry_issue_id,
sentry_url, github_issue_url, parent_bug_id, sonarly_url`.
Agent-run object: `id, mode, status, trigger_source, bug_id, repository,
branch_name, pr_url, pr_merged, analysis{title,severity,summary,user_impact,
root_cause,suggested_fix,fixable_in_code}, created, started_at, completed_at`.
Times are **unix seconds**; `null` = absent; fields are v1-stable (never renamed/removed).

### Live push (webhooks) — alternative to polling

**Register the receiver yourself** [agent]:
```
POST /api/setup/webhook-endpoint   Authorization: Bearer <token>
Body: { "url": "https://your-app.com/webhooks/sonarly", "events": ["*"] }
→ { "id": "...", "secret": "whsec_…", "event_types": ["*"] }
```
`secret` is shown **once** — hand it to the user to set on their receiver (e.g.
`wrangler secret put SONARLY_WEBHOOK_SECRET`). The URL is SSRF-checked. (The user
can also add it in the Developers tab.) Sonarly then POSTs a signed JSON envelope
on each subscribed event:
- **Events**: `bug.created, bug.analyzed, bug.deduped, bug.reappeared, bug.resolved,
  bug.pr_created, bug.pr_merged, incident.created, incident.analyzed,
  incident.resolved` (or subscribe `["*"]`).
- **Envelope**: `{ "id":"evt_…", "type":"bug.analyzed", "api_version":"2026-04-30",
  "created":<unix>, "tenant_id":N, "data":{ "object": <full Bug/Incident>,
  "previous_attributes": null } }`.
- **Headers**: `Sonarly-Signature: t=<unix>,v1=<hmac_sha256_hex>`, `Sonarly-Event-Id: evt_…`, `Sonarly-Event-Type`, `Sonarly-Delivery-Id`.
- **Verify — do ALL of these (security-critical):**
  1. Capture the **raw body BEFORE JSON-parsing** — re-serialization changes
     whitespace/key order and breaks the signature (Express: `express.raw`; Next.js:
     `await req.text()`; Workers: `await req.text()`).
  2. Recompute `HMAC-SHA256(secret, "{t}.{rawBody}")` and compare to `v1` with a
     **constant-time** compare (`crypto.timingSafeEqual` / `hmac.compare_digest`).
  3. **Reject if `|now - t| > 300s`** (replay protection; tolerance is 300s).
  4. **Dedupe on `Sonarly-Event-Id`** (= envelope `id`) — stable across the
     8-attempt retry schedule (`INSERT … ON CONFLICT DO NOTHING`).
  Return `2xx` fast (<10s) or Sonarly retries; persistent failures disable the
  endpoint after 3 days.

Full reference: `https://sonarly.com/docs/public-api`.

---

## Step 8 — Plan / trial  [human]

Surface the plan so they can start the trial (Stripe checkout is a browser flow):
```
GET /api/setup/{id}/checkout-url?plan=startup   → { "url": "https://checkout.stripe.com/..." }
```
Plans mirror sonarly.com: Free ($0, 5 bugs/mo), Teams ($79, 50 bugs/mo),
Startup ($195, 150 bugs/mo, 14-day trial), Enterprise (custom). Free needs no
checkout — only show this if they want a paid tier.

## Step 9 — Finish & hand off  [agent]

```
POST /api/setup/complete        Authorization: Bearer <token>
→ { "completed": true, "dashboard_url": "https://sonarly.com/issues" }
```
This marks onboarding done and, if an error tracker is connected, pulls a recent
issue as a **test analysis** so the user sees Sonarly work end-to-end.

**Always finish by giving the user the `dashboard_url`** (exactly like the manual
onboarding ends): *"You're all set — open your Sonarly dashboard: <dashboard_url>"*.

---

## Final human checklist (always print at the end)

- [ ] Signed in — **Step 1 link**
- [ ] Error tracker connected — Sentry **[link]**
- [ ] Code host connected — GitHub App **[link]** (repos auto-selected by the agent)
- [ ] 👉 **Open your dashboard: `dashboard_url`**
- [ ] Everything else — **handled by the agent**

---

## API

Full public REST API (read bugs/incidents/runs, outbound webhooks):
`https://sonarly.com/docs/public-api`.

### Notes for maintainers
The `/api/setup/*` endpoints are the **setup-session API** (device-code style):
`start` issues a session + user code; the human authorizes by signing in at
`verification_url` (which creates their tenant); `status` returns a setup-scoped
bearer token once authorized. `connect-url` mints OAuth/install links bound to
the session `state`; `integrations` reuses the `logs-analysis` validation +
auto-provisioning; all `/api/setup/*` writes are scoped to the single tenant
created by that session and expire with it.