# 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. No account is needed to start collecting. Docs: https://analytics.capless.sh/llms.txt

## 1. Get a snippet

If the user already gave you a snippet (`<script … data-key="cs_…">`), use it and skip to step 2. Otherwise:

```sh
curl -s https://analytics.capless.sh/new -H 'accept: application/json'
```

The JSON response contains:

* `snippet`: the script tag to install. Its `cs_…` key is public and write-only.
* `claimUrl` (`https://app.capless.sh/claim#csk_…`) and `claimSecret` (`csk_…`): proof of ownership. Give `claimUrl` to the user. Never commit either of them, never put them on a page, and do not print the secret anywhere but your message to the user.
* `unclaimedDays`: the project is deleted after this many days unless the user claims it.

The project is created by the snippet's first event. Until the user claims it, it collects up to 250,000 events and 2,500 replays and has no SQL, API keys or members.

## 2. Add the snippet

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

```html
<script async src="https://c.capless.sh/c.js" data-key="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-key="…"></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`.

One snippet works on every domain of the site (production, staging, localhost). 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). Then check that events arrived, using the claim secret as a read-only token:

```sh
export CAPLESS_CLAIM_SECRET=csk_…   # in your shell only; do not write it to a file
curl -s 'https://api.capless.sh/v1/streams/$web.events' -H "authorization: Bearer $CAPLESS_CLAIM_SECRET"
# "entryCount" > 0 means it works
curl -s 'https://api.capless.sh/v1/streams/$web.events/read' -H "authorization: Bearer $CAPLESS_CLAIM_SECRET" -d '{"limitResultEntries":3}'
```

Keep the single quotes around URLs that contain `$web.events`; otherwise the shell expands `$web`. Commits are batched, so events can take up to about 30 seconds to appear. If nothing arrives: confirm the tag is in the served HTML and the browser console shows no CSP or network errors for `c.capless.sh`. `401 project_claimed` means the user has already claimed the project; use an API key from their dashboard instead.

## 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).
* The claim link (`claimUrl`). Opening it shows the data without an account; claiming it with an email keeps the data, starts a 14-day free trial without a credit card, and gives them the dashboard, SQL and API keys. Unclaimed projects are deleted after 14 days.

## Optional: create the account now

If the user wants an account and an API key immediately (for example so you can use the API or MCP), call the signup API with their email and the claim secret:

```sh
curl -s https://api.capless.sh/v1/signup \
  -d '{"email":"USER_EMAIL","claimSecret":"csk_…"}'
```

On `201`, the 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.
* `web.snippet`: the same snippet as before.
* `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. Give them the claim link; they claim the project after logging in.
* `409 already_claimed`: the project already belongs to an account.
* `429 rate_limited`: wait a minute and retry once. Do not loop.
* Anything else: show the user the error `code` and `message` and stop.

Then connect MCP:

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

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