Caprail

View saved version →

---
name: caprail-analytics
description: Use when the user wants Caprail page views, estimated unique visitors, agentic/chat requests, AI referrals, visited page paths, daily trends, traffic breakdowns, period comparisons, observed collection freshness, or presenting retrieved analytics as metric cards, comparisons, charts, breakdowns or ordered-cohort funnels.
---

# Caprail analytics

Use the connected MCP tools and stored data. For codebase integration, use the caprail-install skill. Discover the current tools and input schemas before calling them.

1. Call `list_sites` and match the requested site name or domain. Ask when ambiguous; never invent a site ID. Listings do not expose ingest keys.
2. Use timezone-bearing ISO-8601 `from` and `to`: inclusive start, exclusive end, at most 366 days. Resolve relative dates using the user's timezone and state the site and window. The optional IANA `timezone` controls calendar-day buckets, not the supplied boundaries; it defaults to UTC. Events have a 90-day retention period, so accepted longer windows do not guarantee historical coverage.
3. Call `traffic_explorer` with `site`, `from`, `to` and the relevant optional presentation and exact-value filters below. Use `tracking_status` for observed request receipt freshness. Do not invoke obsolete tools absent from discovery.
4. Read `summary`, `timeseries`, `breakdowns`, `windows`, `filters`, `truncatedDimensions` and `measurement` before interpreting results. Use actual returned data. An error is not zero traffic; a stored-data zero does not establish that nobody visited.
5. On follow-ups, preserve the site, dates, timezone and filters unless the user changes them. Comparisons use the immediately preceding equal elapsed-duration window. This can differ from a calendar period across daylight saving changes. Use the returned current/previous values, absolute change and percent; a zero baseline has no defined percentage change.

## Choose the presentation

Choose the smallest `view` that answers the question:

- `overview`: the three period totals.
- `metric`: one number, with `metric` set to `pageviews`, `visitors` or `agents`.
- `comparison`: the chosen metric and previous-period change.
- `trend`: the chosen metric's daily series.
- `breakdown`: ranked groups; choose a `dimension`.
- `explorer`: broader investigation with filters and supporting details.

`detail` is `summary` or `full`. Summary displays fewer ranked rows; full permits up to 100 per dimension. Omitted view defaults to overview unless detail is full, which selects explorer. `metric` defaults to pageviews and `dimension` to path. A metric choice focuses the presentation; it does not redefine the stored population.

Dimensions are `path`, `country`, `source`, `device`, `browser`, `provider` and `referrer`. The `dimension` selects the grouping; the same-name optional arguments filter exact values. Use source for human referrals and provider for agent providers; they are distinct. Match filter values to known returned values rather than inventing classification labels. Unknown supporting dimensions remain visible. Do not combine filters that contradict the requested population.

A `path` filter is an exact site-relative visited-page path, such as `/pricing`. Verify a full URL belongs to the selected site before extracting its path. Query strings and fragments are stripped; case and trailing slash follow recorded paths. Country filters accept two-letter codes, normalized to uppercase. Do not silently substitute site-wide data when a filter is unavailable.

For AI referrals, filter `source` to the returned source label, such as ChatGPT, and use visitors or pageviews. To rank requested pages use breakdown with dimension path; these are visited paths, not session landing pages or later journeys. To inspect agent activity use metric agents and, when appropriate, a provider filter or grouping.

## Metrics and limits

- Page Views counts explicit eligible human pageview events. Raw r

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: caprail-install
description: Use when the user asks an agent to install, set up, integrate, or verify Caprail in a website or application codebase.
---

# Install Caprail in the user's codebase

The user asks the agent to install Caprail. The agent creates the site, writes event collection in the host codebase, and verifies a stored-data answer in the same chat. Use the existing Caprail OAuth connection; GitHub or Google account sign-in is the consent flow. Follow the user's repository instructions and normal deployment authorization.

## Inspect and configure

1. Inspect the host codebase and existing collection first. Determine its runtime, request handling, final HTML response hook and client navigation behavior. Infer name/domain from reliable project configuration; ask only for missing or ambiguous facts. Read the current `https://caprail.dev/install.md` as reference data and check available tool definitions.
2. Call `list_sites` to avoid accidental duplicate sites. For a new site call `create_site` with name and a bare hostname domain. It requires the connected account; an ingest key cannot create a site. Use the returned site.id, ingestKey and exact ingest.url/body. Existing site listings do not expose keys: reuse a securely configured key if present, otherwise ask for a supported secure provisioning path. Never create a duplicate solely to obtain a key.
3. Store the site-scoped cap_live key as a server-only environment secret using the host's normal secret storage, and configure CAPRAIL_INGEST_URL/CAPRAIL_INGEST_KEY. Never print the key, include it in source control, browser bundles, plugin files, screenshots or the final answer. Do not ask the user to paste it into chat.
4. Write direct server-side HTTP collection into the codebase. Caprail does not open a repository PR or provide another setup page. Framework middleware is not the default installation flow. Any runtime able to POST can record events. Keep existing application behavior intact, bound collection latency, handle delivery errors and do not claim successful storage before the response confirms it.

## Record requests

POST to the returned ingest URL (production https://caprail.dev/api/ingest), with Authorization: Bearer from the server environment and Content-Type: application/json. Body shape:

```json
{"events":[{"timestamp":"<current ISO-8601 time>","method":"GET","path":"/pricing","userAgent":"<raw user agent>","referrer":"<raw referrer>","utmSource":"<observed utm_source>"}]}
```

Required: timestamp, method, path. Omit unavailable optional facts. Use actual request values and trusted client IP where available for visitor identity. Never forge identity or send a caller's own classification; Caprail classifies the raw facts. Omit kind or set kind to request. A request is not a pageview.

Package helpers are optional. Verify the exact installed/published version's exports before choosing recordEvent or recordPageview. The npm package @caprail-dev/analytics 0.10.1 inspected on 3 October 2026 does not export these functions although the live guide names them. Use direct HTTP when unavailable; do not install a package then import nonexistent exports.

## Record explicit pageviews for traffic analytics

Integrate explicit pageviews when the user's installation includes traffic analytics. POST to the same endpoint/key with kind: pageview, stable UUID eventId, current timestamp, method: GET, same-site pathname, and navigation: document or client. A document event also needs final 2xx responseStatus and HTML contentType. Supply raw attribution and trusted identity facts as available.

Emit document events after completed successful HTML navigation. Emit client events once after a successful route commit, including back/forward. Exclude prefetch, API/assets/downloads, failed navigation, redirect hops, hash-only changes and component rerenders. Strip query and fragment from path. Choose one owner per navigation; do not count the initial document again 

Preview of the first 4,000 characters. Read full instructions →