# Install Capless (instructions for coding agents)

You are adding Capless web analytics and session replay to the user's website. Follow these steps in order. Ask the user only for what you cannot find yourself (their email address). Docs: https://capless.sh/llms.txt

## 1. Create the account

Ask the user for their email address, then call the signup API. Use the site's production origin(s) in `allowedOrigins` if you know them (e.g. from the project's config or deployment settings); otherwise omit the field.

```sh
curl -s https://api.capless.sh/v1/signup \
  -d '{"email":"USER_EMAIL","siteName":"SITE_NAME","allowedOrigins":["https://example.com"]}'
```

On `201`, the JSON response contains:

* `apiKey` (`cpl_…`): secret, shown once. Store it in the project's secret store or an untracked env file as `CAPLESS_API_KEY`. Never commit it, never put it in client code, never print it in full in chat.
* `site.snippet`: the script tag to install (its `cs_…` key is public).
* `dashboardUrl`: one-time sign-in link for the user, valid 15 minutes.
* `mcp`: an MCP server config (`url` + `headers`) you can install for yourself.

Errors:

* `409 email_taken`: the user already has an account. Ask them to sign in at https://app.capless.sh/login, create a site there (or give you an API key) and continue at step 2 with that snippet.
* `429 rate_limited`: wait a minute and retry once. Do not loop.
* Anything else: show the user the error `code` and `message` and stop.

## 2. Add the snippet

Insert `site.snippet` immediately before `</head>` so it loads on every page:

```html
<script async src="https://c.capless.sh/c.js" data-site="cs_…"></script>
```

* Plain HTML: every page's `<head>` (or the shared layout/template).
* Next.js (App Router): `app/layout.tsx`, as a plain `<script async src="…" data-site="…"></script>` inside `<head>`, or `next/script` with `strategy="afterInteractive"` and the same attributes.
* Other frameworks: the root HTML template or layout component (`index.html`, `app.html`, `_document`, base layout).
* If the site sends a Content Security Policy, add `https://c.capless.sh` to `script-src` and `connect-src`.

Single-page-app navigation is tracked automatically. Do not add other analytics code. Optional custom events: `capless("track", "event_name", { key: "value" })`; user identification after login: `capless("identify", userId)`.

## 3. Verify

Load the site in a browser (dev server or deployed URL; the origin must be in `allowedOrigins` if you set it). Then check that events arrived:

```sh
curl -s https://api.capless.sh/v1/streams/web.events -H "authorization: Bearer $CAPLESS_API_KEY"
# "entryCount" > 0 means it works
curl -s https://api.capless.sh/v1/streams/web.events/read -H "authorization: Bearer $CAPLESS_API_KEY" -d '{"limitResultEntries":3}'
```

Or, with the MCP server installed, call the `get_started` tool. If nothing arrives: confirm the tag is in the served HTML, the browser console shows no CSP or network errors for `c.capless.sh`, and the page's origin matches `allowedOrigins`.

## 4. Hand over to the user

Tell the user, briefly:

* Capless is installed and events are arriving (or what is left to do, e.g. deploy).
* Their dashboard: the `dashboardUrl` link (valid 15 minutes; afterwards https://app.capless.sh/login).
* A verification email was sent to them; the 14-day free trial needs no credit card.
* Where you stored `CAPLESS_API_KEY`.

## Optional: connect MCP

```sh
claude mcp add --transport http capless https://mcp.capless.sh/mcp --header "Authorization: Bearer $CAPLESS_API_KEY"
```

Then you can answer questions such as "which pages have the most rage clicks?" with the `read_stream` and `run_sql` tools. Reference: https://capless.sh/docs/mcp.md