@sprid/cli 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 sprid follows semver: a breaking change to a command's arguments, its output
 shape or its exit codes is a major release.
 
+## 0.1.5 - 2026-09-24
+
+- `sprid connect ga4|plausible|umami` saves a website-analytics key beside the
+  store and revenue ones. The four providers, PostHog included, count the same
+  visits, so Sprid reads exactly one of them and never adds them together;
+  `--use` names which one answers, and the others stay connected and idle.
+  `--property` on Google Analytics is the numeric property id, and a
+  measurement id (`G-…`) is refused by name rather than failing on the first
+  read. A self-hosted Umami gets `/api` appended to `--host` when it is
+  missing, which is the commonest setup mistake.
+- `sprid docs google-analytics|plausible|umami` are the three new connect
+  guides. `sprid connect` names all four providers as one choice, not four
+  separate gaps.
+
 ## 0.1.4 - 2026-09-23
 
 - `sprid whoami` warns when the credentials file is readable by other users

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprid/cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "The Sprid command line: connect your app, review results, prepare posts and store screenshots, and release mobile apps.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/commands/connect.mjs

@@ -26,6 +26,12 @@ export const SENSOR_SERVICES = [
   "play",
   "gsc",
   "posthog",
+  // Website analytics. These three are ALTERNATIVES - they count the same
+  // visits - so connecting a second one does not add visitors, it offers a
+  // different source. `--use` picks which one answers.
+  "ga4",
+  "plausible",
+  "umami",
   // The revenue rails. RevenueCat reads store sales; the other four read web
   // ones, and a customer may legitimately have two of them.
   "revenuecat",
@@ -44,6 +50,9 @@ export const SENSOR_KEYS = {
   play: ["playServiceAccountJson"],
   gsc: ["gscServiceAccountJson"],
   posthog: ["posthogApiKey"],
+  ga4: ["ga4ServiceAccountJson"],
+  plausible: ["plausibleApiKey"],
+  umami: ["umamiApiKey"],
   revenuecat: ["revenuecatApiKey"],
   stripe: ["stripeApiKey"],
   polar: ["polarApiKey"],
@@ -57,6 +66,9 @@ const SENSOR_LABEL = {
   play: "Google Play",
   gsc: "Search Console",
   posthog: "PostHog",
+  ga4: "Google Analytics",
+  plausible: "Plausible",
+  umami: "Umami",
   revenuecat: "RevenueCat",
   stripe: "Stripe",
   polar: "Polar",
@@ -124,7 +136,8 @@ async function wizard(ctx) {
   const optional = [];
   for (const p of profiles) {
     const opts = [];
-    if (!p.posthogProjectId) opts.push("PostHog");
+    // One website-analytics provider is enough; they measure the same visits.
+    if (!p.posthogProjectId && !p.ga4PropertyId && !p.plausibleSiteId && !p.umamiWebsiteId) opts.push("PostHog, Google Analytics, Plausible or Umami");
     if (!p.revenuecatProjectId) opts.push("RevenueCat");
     if (!p.gscProperty) opts.push("Search Console");
     if (!p.cloudflareZoneId) opts.push("Cloudflare");
@@ -301,6 +314,44 @@ export function sensorPatch(service, flags, cwd) {
       }
       return body;
     }
+    case "ga4": {
+      // The Data API takes the numeric property id. A measurement id
+      // (G-XXXXXXX) is the tag on the page and is refused, so say that here
+      // rather than letting the first read fail an hour later.
+      const property = String(need("property")).replace(/^properties\//, "");
+      if (!/^\d+$/.test(property)) {
+        throw new UsageError(
+          `--property must be the numeric GA4 property id, not "${property}". Google Analytics → Admin → Property details → Property ID.`,
+        );
+      }
+      const body = { ga4PropertyId: property, secrets: { ga4ServiceAccountJson: readKeyFile(need("key"), cwd) } };
+      if (flags.use) body.trafficProvider = "ga4";
+      return body;
+    }
+    case "plausible": {
+      const body = {
+        plausibleSiteId: String(need("site")).replace(/^https?:\/\//, "").replace(/\/+$/, ""),
+        secrets: { plausibleApiKey: fileOrValue(need("key"), cwd) },
+      };
+      if (flags.host && flags.host !== true) body.plausibleHost = String(flags.host).replace(/\/+$/, "");
+      if (flags.use) body.trafficProvider = "plausible";
+      return body;
+    }
+    case "umami": {
+      const body = {
+        umamiWebsiteId: String(need("site")),
+        secrets: { umamiApiKey: fileOrValue(need("key"), cwd) },
+      };
+      // A self-hosted Umami serves its API under /api. Leaving that off is the
+      // commonest setup mistake, and it fails as a 404 on every read, so add
+      // it here rather than explaining it in a guide nobody re-reads.
+      if (flags.host && flags.host !== true) {
+        const host = String(flags.host).replace(/\/+$/, "");
+        body.umamiHost = /\/api$/.test(host) ? host : `${host}/api`;
+      }
+      if (flags.use) body.trafficProvider = "umami";
+      return body;
+    }
     case "revenuecat":
       return { revenuecatProjectId: need("project"), secrets: { revenuecatApiKey: fileOrValue(need("key"), cwd) } };
     // Stripe and Paddle need no id: the key names the account. Polar takes an

package/src/docs/commands.mjs

@@ -67,6 +67,7 @@ export const COMMAND_GROUPS = [
     ['connect', 'sprid connect', 'Show missing connections and the commands to add them.'],
     ['connect', 'sprid connect <service> --app <slug> --key <file> …', 'Save a store or analytics key. Read sprid docs <service> for the required fields.'],
     ['connect', 'sprid connect <platform> --account <slug>', 'Connect a publishing account through the platform’s sign-in page.'],
+    ['connect', 'sprid connect ga4|plausible|umami --app <slug> --key <file> … [--use]', 'PostHog, Google Analytics, Plausible and Umami all count the same website visits, so Sprid reads one of them and never adds them together. --use makes this one the source the traffic card reports from.'],
     ['pinterest', 'sprid pinterest boards --account <slug> [--channel <id>] [--bookmark <token>]', 'List boards and sections for the exact connected Pinterest channel; a returned bookmark reads the next page.'],
     ['pinterest', 'sprid pinterest create --account <slug> --name <name> [--description <text>] [--privacy public|secret]', 'Create a board in the exact connected Pinterest account. Older connections must reconnect once to grant board creation permission.'],
     ['pinterest', 'sprid pinterest set <postId> --board <id> --link <url> [--section <id>] [--title "…"] [--description "…"] [--alt-text "…"] [--ai-disclosures AI_MODIFIED,SYNTHETIC_PERFORMER]', 'Save the reviewed Pin destination and searchable metadata on a draft.'],

package/src/docs/guides.generated.mjs

@@ -13,6 +13,9 @@ export const GUIDE_GROUPS = [
       "google-play",
       "search-console",
       "posthog",
+      "google-analytics",
+      "plausible",
+      "umami",
       "revenuecat",
       "stripe",
       "polar",
@@ -37,7 +40,10 @@ export const GUIDE_GROUPS = [
 export const GUIDE_ALIASES = {
   "asc": "app-store-connect",
   "play": "google-play",
-  "gsc": "search-console"
+  "gsc": "search-console",
+  "ga4": "google-analytics",
+  "ga": "google-analytics",
+  "google-analytics-4": "google-analytics"
 };
 export const METRIC_EVIDENCE = "# Metric evidence\n\nSprid’s review packet includes a versioned `dataset`: observations, checked results and hashes of the source receipts. The CLI saves complete review/query packets under `marketing-reports/evidence/` with immutable content-hash filenames and owner-only file permissions. The plugin runner preserves that dataset alongside its local evidence and git context. An explicit runner `--output` refuses to overwrite an existing file.\n\n## Read a number\n\n- `definition` names the entity, measurement kind, unit, calculation basis and implementation version. An active subscription is not a unique customer; a store download is not an activated person.\n- `window` uses an exclusive end and retains its calendar. `asOf` belongs to a snapshot; `fetchedAt` records collection. Historical revenue and current MRR are separate observations.\n- `quality` separates coverage, pagination, sampling, finality and trust. A successful HTTP request does not prove complete coverage. Unknown, pending, suppressed and unavailable values remain missing.\n- `value.kind: money` stores an exact decimal coefficient and scale with a currency and conversion policy. Do not assume every provider amount is cents. Keep gross, refunded revenue and proceeds separate.\n\n## Respond to a blocked calculation\n\n| Reason | Continue with |\n| --- | --- |\n| `currency_mismatch` | Separate currency rows; convert only with explicit dated FX evidence and a declared policy. |\n| `overlap_unresolved` | Source subtotals and the identity check. Do not add RevenueCat and a rail it already ingests. |\n| `definition_mismatch` | Name the provider definitions separately, including MRR policy and revenue basis. |\n| `window_mismatch` | Request matching periods/calendars. A daily Pacific aggregate cannot be relabeled UTC. |\n| `population_mismatch` | Verify numerator/denominator attribution with an actual identity mapping. All-app revenue cannot stand for website-cohort revenue. |\n| `incomplete_sources`, `incomplete_coverage` | Keep usable readings; complete pagination or narrow the period. Missing dates are not automatically zero. |\n| `unverified_calculation` | Inspect emitting code and the query’s population, ordering and exclusions. Preserve a local attestation for local database work. |\n| `non_additive` | Query period-level distinct people, select the relevant snapshot, or recompute a rate from compatible numerators and denominators. |\n\n## Investigate through Sprid\n\nRun `sprid marketing-review capabilities --app <slug>` to discover operations. The `revenuecat` / `revenue` operation reads an explicit period total, with `revenue_type` set to `revenue`, `revenue_net_of_taxes` or `proceeds`. Its scope is the bound RevenueCat project, which can contain multiple apps. Use `chart_options` before selecting chart dimensions. Cohort-chart period zero may describe customer count, not the month-zero metric.\n\nCustom query results carry `measurement` provenance and retain provider-native data. They remain investigative; the server does not certify arbitrary SQL’s business meaning. The shared calculation library supports sequential/strict ordered funnels and fixed elapsed-time retention from complete event evidence. These helpers are not additional public query operation names. For provider-side investigations, use the discovered custom query operation and preserve the exact SQL.\n\nStripe MRR is a current active/past-due price estimate before discounts. Paddle’s adapter reports gross completed transactions before adjustments. Lemon Squeezy combines orders with renewal/update invoices and excludes duplicate initial invoices; a complete priced schedule is required for MRR. Separate source readings survive when combined totals cannot be justified.\n\nRevenue observations and aggregate Search Console observations are normalized in the review dataset. Other source receipts retain native definitions and coverage; they are not silently converted into a universal business scorecard. App-specific activation, cross-source identity and attribution still require repository evidence. Local fallback results do not automatically inherit the server dataset’s verification.\n\nSave the full packet and exact query beside the report. Hashes identify evidence but cannot recreate it. Link corrected reports to their earlier dataset and retain the earlier packet; provider backfills and refund revisions must remain inspectable. Sprid does not upload repository database rows or provide hosted dataset-history storage through this contract.\n";
 export const GUIDES = [
@@ -330,7 +336,7 @@ export const GUIDES = [
         "id": "metric-definitions",
         "title": "Metric definitions",
         "kind": "detail",
-        "markdown": "In **Settings → Apps → your app → PostHog**, set the account-created event and the first UTC date from which tracking is complete.\n\n| Metric | What counts |\n|---|---|\n| Registrations | First `sprid_signup` event per PostHog person, across all surfaces |\n| New app users | First native app activity, including anonymous people |\n| Active app users | Distinct people with native activity in the period |\n| Web visitors | Distinct pageview visitors on the saved website hostname |\n\n**Registrations.** Send `sprid_signup` from your server after the account is created, with the account id as `distinct_id`, and identify that id in your clients. Never fire it on login, page load or install. An existing `posthogEvents.signup` mapping also works; `posthogConfig.registration.event` wins over it. No matching event history reads as unavailable; history with no new registrations reads as zero. Periods before the tracking start are unavailable, and comparisons crossing it, or with no confirmed start, are withheld. Backfill with the original creation timestamps.\n\n**App and web.** Native defaults need `posthog-react-native` on iOS, iPadOS or Android and reject explicit web surfaces: set `app_surface: 'web'` on Expo web and `'native'` on devices. Web counts need a browser and exclude reported bots and crawler user agents. Every metric excludes events or people with `is_internal`, `is_test` or `sprid_test = true`. What remains is observed identities, not guaranteed humans.\n\n### Custom properties\n\nAdvanced rules go under **Custom properties**:\n\n```json\n{\"registration\":{\"identity\":{\"scope\":\"event\",\"property\":\"account_id\"}},\"app\":{\"filters\":[{\"scope\":\"event\",\"property\":\"client_type\",\"operator\":\"in\",\"values\":[\"native\"]}]},\"exclude\":[{\"scope\":\"person\",\"property\":\"staff\",\"operator\":\"in\",\"values\":[true]}]}\n```\n\n- `app.filters` replaces SDK/OS matching with your own native rule; all filters must match.\n- `exclude` removes matching traffic from every metric.\n- `registration.filters` narrows the registration event, for example `result = success`.\n- `registration.identity` defaults to `person_id`. A configured property must be present and should never change, because it counts accounts.\n- Each rule takes `scope: event|person`, `operator: in|not_in` and string, number or boolean `values`. A missing property fails `in` and passes `not_in`. Property names are literal keys, dots included.\n\nThe same object is `posthogConfig` in REST `PATCH /api/app-profiles/:id`, MCP `upsert_app_profile` and the App Profile JSON used by `sprid init`, where `registration.event` and `registration.since` also live. No credentials or SQL belong in it. After saving, fetch Insights and check its registration notes and totals against your database before trusting a funnel."
+        "markdown": "In **Settings → Apps → your app → PostHog**, set the account-created event and the first UTC date from which tracking is complete.\n\n| Metric | What counts |\n|---|---|\n| Registrations | First `sprid_signup` event per PostHog person, across all surfaces |\n| New product users | First product activity, including anonymous people |\n| Active product users | Distinct people with product activity in the period |\n| Web visitors | Distinct pageview visitors on the saved website hostname, minus your product |\n\n**Registrations.** Send `sprid_signup` from your server after the account is created, with the account id as `distinct_id`, and identify that id in your clients. Never fire it on login, page load or install. An existing `posthogEvents.signup` mapping also works; `posthogConfig.registration.event` wins over it. No matching event history reads as unavailable; history with no new registrations reads as zero. Periods before the tracking start are unavailable, and comparisons crossing it, or with no confirmed start, are withheld. Backfill with the original creation timestamps.\n\n### What counts as your product\n\nSet this under **What counts as your product** on the same screen. It decides who is an active person, and it is the single setting most likely to make the people card wrong.\n\n| Your product is | Choose | Also give |\n|---|---|---|\n| An iOS or Android app | **A phone app** | Nothing. This is the default |\n| A web app on its own subdomain | **A website or web app** | The hostnames, such as `app.example.com` |\n| A web app under a path on your marketing domain | **A website or web app** | The paths, such as `/app`, `/dashboard` |\n| A phone app with a web client | **Both** | The web hostnames or paths |\n\n**A web product must say where it lives.** Your marketing pages and your product are the same PostHog events; without a hostname or a path there is nothing to tell them apart, and every visitor would be counted as someone using the product. Sprid refuses that configuration rather than reporting it.\n\nWhatever you name here is **subtracted from your website visitor numbers**, so a page inside the product is never also counted as a visit.\n\n**A phone app** needs `posthog-react-native` on iOS, iPadOS or Android and rejects explicit web surfaces: set `app_surface: 'web'` on Expo web and `'native'` on devices. Web counts need a browser and exclude reported bots and crawler user agents. Every metric excludes events or people with `is_internal`, `is_test` or `sprid_test = true`. What remains is observed identities, not guaranteed humans.\n\n### Custom properties\n\nAdvanced rules go under **Custom properties**:\n\n```json\n{\"registration\":{\"identity\":{\"scope\":\"event\",\"property\":\"account_id\"}},\"app\":{\"kind\":\"web\",\"hosts\":[\"app.example.com\"]},\"exclude\":[{\"scope\":\"person\",\"property\":\"staff\",\"operator\":\"in\",\"values\":[true]}]}\n```\n\n- `app.kind` is `native`, `web` or `both`, with `app.hosts` and `app.pathPrefixes` saying where a web product lives. This is what the screen above writes.\n- `app.filters` replaces the whole definition with your own rule; all filters must match. Choosing it shows as **Custom rules** on the screen, and the rule is subtracted from web visitors the same way.\n- `exclude` removes matching traffic from every metric.\n- `registration.filters` narrows the registration event, for example `result = success`.\n- `registration.identity` defaults to `person_id`. A configured property must be present and should never change, because it counts accounts.\n- Each rule takes `scope: event|person`, `operator: in|not_in` and string, number or boolean `values`. A missing property fails `in` and passes `not_in`. Property names are literal keys, dots included.\n\nThe same object is `posthogConfig` in REST `PATCH /api/app-profiles/:id`, MCP `upsert_app_profile` and the App Profile JSON used by `sprid init`, where `registration.event` and `registration.since` also live. No credentials or SQL belong in it. After saving, fetch Insights and check its registration notes and totals against your database before trusting a funnel."
       },
       {
         "id": "review-suspected-automated-traffic",
@@ -363,8 +369,179 @@ export const GUIDES = [
         "markdown": "Setup and live reads checked 2026-09-09.\n\n- [PostHog personal API keys](https://posthog.com/docs/api/personal-api-keys)\n- [Project identity endpoint](https://posthog.com/docs/api/projects)\n- [HogQL query endpoint](https://posthog.com/docs/api/query)\n- [SDK and framework guides](https://posthog.com/docs/libraries)\n- [React Native screen tracking](https://posthog.com/docs/libraries/react-native)\n- [Identifying users](https://posthog.com/docs/product-analytics/identify)\n- [Funnels](https://posthog.com/docs/product-analytics/funnels)"
       }
     ],
-    "markdown": "# PostHog\n\n**What Sprid does with this:** See how people use your app and where they stop.\n\n## You need\n\nAccess to your app’s PostHog project and permission to create a **personal API key**. Your app must already send events to PostHog; connecting Sprid adds no tracking. The public key inside your app does not work here.\n\n## Click path (us.posthog.com or eu.posthog.com)\n\n1. **Settings → Account → Personal API keys → Create personal API key**, named `Sprid <app name>`.\n2. Under access, select **Projects** and choose your app’s project. Leave **All access** off.\n3. Select **Query → Read** and **Project → Read**. Leave write access off.\n4. Copy the key before closing the dialog and save it to a private file such as `~/keys/posthog-myapp.txt`. Use a separate key per app.\n\n## Project id and host\n\n- **Project id:** the number after `/project/` in your PostHog address, such as `12345`.\n- **Host:** `eu` for `eu.posthog.com`, `us` for `us.posthog.com`, or your full self-hosted address, whichever you open the dashboard on.\n\n## Then run\n\n```sh\nsprid connect posthog --app myapp --key ~/keys/posthog-myapp.txt --project 12345 --host eu\n```\n\nUse your own app slug, file path, project id and host. Add `--workspace <slug>` if needed. Keep the key out of chat.\n\n## How to check it worked\n\nAsk your agent: “Check that Sprid can read recent PostHog events for this app, and confirm the project is correct.” The check reports recent activity or explains why there is none; a saved connection alone does not prove events arrive.\n\n## Metric definitions\n\nIn **Settings → Apps → your app → PostHog**, set the account-created event and the first UTC date from which tracking is complete.\n\n| Metric | What counts |\n|---|---|\n| Registrations | First `sprid_signup` event per PostHog person, across all surfaces |\n| New app users | First native app activity, including anonymous people |\n| Active app users | Distinct people with native activity in the period |\n| Web visitors | Distinct pageview visitors on the saved website hostname |\n\n**Registrations.** Send `sprid_signup` from your server after the account is created, with the account id as `distinct_id`, and identify that id in your clients. Never fire it on login, page load or install. An existing `posthogEvents.signup` mapping also works; `posthogConfig.registration.event` wins over it. No matching event history reads as unavailable; history with no new registrations reads as zero. Periods before the tracking start are unavailable, and comparisons crossing it, or with no confirmed start, are withheld. Backfill with the original creation timestamps.\n\n**App and web.** Native defaults need `posthog-react-native` on iOS, iPadOS or Android and reject explicit web surfaces: set `app_surface: 'web'` on Expo web and `'native'` on devices. Web counts need a browser and exclude reported bots and crawler user agents. Every metric excludes events or people with `is_internal`, `is_test` or `sprid_test = true`. What remains is observed identities, not guaranteed humans.\n\n### Custom properties\n\nAdvanced rules go under **Custom properties**:\n\n```json\n{\"registration\":{\"identity\":{\"scope\":\"event\",\"property\":\"account_id\"}},\"app\":{\"filters\":[{\"scope\":\"event\",\"property\":\"client_type\",\"operator\":\"in\",\"values\":[\"native\"]}]},\"exclude\":[{\"scope\":\"person\",\"property\":\"staff\",\"operator\":\"in\",\"values\":[true]}]}\n```\n\n- `app.filters` replaces SDK/OS matching with your own native rule; all filters must match.\n- `exclude` removes matching traffic from every metric.\n- `registration.filters` narrows the registration event, for example `result = success`.\n- `registration.identity` defaults to `person_id`. A configured property must be present and should never change, because it counts accounts.\n- Each rule takes `scope: event|person`, `operator: in|not_in` and string, number or boolean `values`. A missing property fails `in` and passes `not_in`. Property names are literal keys, dots included.\n\nThe same object is `posthogConfig` in REST `PATCH /api/app-profiles/:id`, MCP `upsert_app_profile` and the App Profile JSON used by `sprid init`, where `registration.event` and `registration.since` also live. No credentials or SQL belong in it. After saving, fetch Insights and check its registration notes and totals against your database before trusting a funnel.\n\n## Review suspected automated traffic\n\nRead [Check whether a traffic spike is real](https://sprid.studio/docs/traffic) (`sprid docs traffic`) before saving a rule: a spike or a shared fingerprint alone does not prove bots.\n\nOpen **Web visitors → Review traffic exclusions**, or **Settings → Apps → your app → PostHog → Review traffic**. Pick a UTC date range and a traffic group, preview the effect, then save. Agents use MCP `review_traffic` or `POST /api/app-profiles/:ref/traffic-review?workspaceId=…` with `{\"start\":\"2026-09-18\",\"end\":\"2026-09-19\"}`: end dates exclusive, UTC, at most 31 days. An optional `exclusion` previews a rule against this period and the one before. Save approved rules in `posthogConfig.trafficExclusions` through `upsert_app_profile` or the profile PATCH route, keeping the rest of the configuration. Sprid records who edited it and when.\n\nHow exclusions apply:\n\n- App-specific and date-bounded. Properties inside a rule are AND; enabled rules are OR.\n- Applied to website totals, charts, breakdowns, social attribution and weekly website counts, comparison period included. Remaining visitors are recounted as distinct people, never subtracted.\n- Native app activity and registrations are unchanged, and PostHog’s data is never changed or deleted. **Restore this traffic** disables a rule.\n- Raw connected queries and the marketing-review event inventory stay unfiltered as evidence; Insights shows the corrected figures.\n- Only PostHog is supported today.\n\n## Social traffic and clip comparisons\n\nSave the app’s website URL on its App Profile as well as connecting PostHog. Insights then compares completed-day website sessions with recorded social view gains. Shared bio traffic stays at channel level; only a dedicated tagged link identifies one publish. Older clips with metric activity stay candidates.\n\nCopy the stable bio link and dedicated clip links from Insights. Keep `utm_source`, `utm_medium`, `sprid_account` and, on dedicated links only, `sprid_publish` through any redirects. Never repoint the shared bio link to the newest publish. The optional bio-page HTML export records selections separately and keeps a direct app link; host it on the saved hostname with your existing PostHog setup.\n\nTo capture store-link clicks and website outcomes, add after your PostHog initialization:\n\n```html\n<script src=\"https://sprid.studio/sprid-attribution.js\" defer></script>\n```\n\nIt uses your PostHog client and consent state and sends nothing to Sprid. Call `window.spridAttribution?.track('signup')` or `.track('activation')` only after that action succeeds. `posthogEvents.signup` and `posthogEvents.activation` mappings also count when the event shares the arriving website session. It does not track a native app or join visits to purchases, and a store click is not an install. Missing outcomes stay unmeasured. Redirect-only flows need a beacon before navigating; redirect events are counted apart from sessions. `get_insights` and `sprid insights` return the same evidence as the dashboard.\n\n## If it fails\n\n- **Access denied:** check the key is active, grants your project and has both Read permissions. Reconnect with a corrected key file.\n- **Project not found:** check project number and host together. A US project needs the US host.\n- **Connected but no events:** check the dates and project, then ask your agent to check your app’s tracking is sending events.\n\n## Investigate with this connection\n\nReads `query` (HogQL), `events` and `properties` for the pinned project. Check instrumentation before interpreting events. Event-definition discovery also needs `event_definition:read`, property-definition discovery `property_definition:read`, both restricted to the same project.\n\n```sh\nsprid marketing-review capabilities --app <slug> --source posthog --json\n```\n\nSee [connected queries](https://sprid.studio/docs/queries).\n\n## Sources and verification\n\nSetup and live reads checked 2026-09-09.\n\n- [PostHog personal API keys](https://posthog.com/docs/api/personal-api-keys)\n- [Project identity endpoint](https://posthog.com/docs/api/projects)\n- [HogQL query endpoint](https://posthog.com/docs/api/query)\n- [SDK and framework guides](https://posthog.com/docs/libraries)\n- [React Native screen tracking](https://posthog.com/docs/libraries/react-native)\n- [Identifying users](https://posthog.com/docs/product-analytics/identify)\n- [Funnels](https://posthog.com/docs/product-analytics/funnels)\n",
-    "revision": "045b47b5e8256c17"
+    "markdown": "# PostHog\n\n**What Sprid does with this:** See how people use your app and where they stop.\n\n## You need\n\nAccess to your app’s PostHog project and permission to create a **personal API key**. Your app must already send events to PostHog; connecting Sprid adds no tracking. The public key inside your app does not work here.\n\n## Click path (us.posthog.com or eu.posthog.com)\n\n1. **Settings → Account → Personal API keys → Create personal API key**, named `Sprid <app name>`.\n2. Under access, select **Projects** and choose your app’s project. Leave **All access** off.\n3. Select **Query → Read** and **Project → Read**. Leave write access off.\n4. Copy the key before closing the dialog and save it to a private file such as `~/keys/posthog-myapp.txt`. Use a separate key per app.\n\n## Project id and host\n\n- **Project id:** the number after `/project/` in your PostHog address, such as `12345`.\n- **Host:** `eu` for `eu.posthog.com`, `us` for `us.posthog.com`, or your full self-hosted address, whichever you open the dashboard on.\n\n## Then run\n\n```sh\nsprid connect posthog --app myapp --key ~/keys/posthog-myapp.txt --project 12345 --host eu\n```\n\nUse your own app slug, file path, project id and host. Add `--workspace <slug>` if needed. Keep the key out of chat.\n\n## How to check it worked\n\nAsk your agent: “Check that Sprid can read recent PostHog events for this app, and confirm the project is correct.” The check reports recent activity or explains why there is none; a saved connection alone does not prove events arrive.\n\n## Metric definitions\n\nIn **Settings → Apps → your app → PostHog**, set the account-created event and the first UTC date from which tracking is complete.\n\n| Metric | What counts |\n|---|---|\n| Registrations | First `sprid_signup` event per PostHog person, across all surfaces |\n| New product users | First product activity, including anonymous people |\n| Active product users | Distinct people with product activity in the period |\n| Web visitors | Distinct pageview visitors on the saved website hostname, minus your product |\n\n**Registrations.** Send `sprid_signup` from your server after the account is created, with the account id as `distinct_id`, and identify that id in your clients. Never fire it on login, page load or install. An existing `posthogEvents.signup` mapping also works; `posthogConfig.registration.event` wins over it. No matching event history reads as unavailable; history with no new registrations reads as zero. Periods before the tracking start are unavailable, and comparisons crossing it, or with no confirmed start, are withheld. Backfill with the original creation timestamps.\n\n### What counts as your product\n\nSet this under **What counts as your product** on the same screen. It decides who is an active person, and it is the single setting most likely to make the people card wrong.\n\n| Your product is | Choose | Also give |\n|---|---|---|\n| An iOS or Android app | **A phone app** | Nothing. This is the default |\n| A web app on its own subdomain | **A website or web app** | The hostnames, such as `app.example.com` |\n| A web app under a path on your marketing domain | **A website or web app** | The paths, such as `/app`, `/dashboard` |\n| A phone app with a web client | **Both** | The web hostnames or paths |\n\n**A web product must say where it lives.** Your marketing pages and your product are the same PostHog events; without a hostname or a path there is nothing to tell them apart, and every visitor would be counted as someone using the product. Sprid refuses that configuration rather than reporting it.\n\nWhatever you name here is **subtracted from your website visitor numbers**, so a page inside the product is never also counted as a visit.\n\n**A phone app** needs `posthog-react-native` on iOS, iPadOS or Android and rejects explicit web surfaces: set `app_surface: 'web'` on Expo web and `'native'` on devices. Web counts need a browser and exclude reported bots and crawler user agents. Every metric excludes events or people with `is_internal`, `is_test` or `sprid_test = true`. What remains is observed identities, not guaranteed humans.\n\n### Custom properties\n\nAdvanced rules go under **Custom properties**:\n\n```json\n{\"registration\":{\"identity\":{\"scope\":\"event\",\"property\":\"account_id\"}},\"app\":{\"kind\":\"web\",\"hosts\":[\"app.example.com\"]},\"exclude\":[{\"scope\":\"person\",\"property\":\"staff\",\"operator\":\"in\",\"values\":[true]}]}\n```\n\n- `app.kind` is `native`, `web` or `both`, with `app.hosts` and `app.pathPrefixes` saying where a web product lives. This is what the screen above writes.\n- `app.filters` replaces the whole definition with your own rule; all filters must match. Choosing it shows as **Custom rules** on the screen, and the rule is subtracted from web visitors the same way.\n- `exclude` removes matching traffic from every metric.\n- `registration.filters` narrows the registration event, for example `result = success`.\n- `registration.identity` defaults to `person_id`. A configured property must be present and should never change, because it counts accounts.\n- Each rule takes `scope: event|person`, `operator: in|not_in` and string, number or boolean `values`. A missing property fails `in` and passes `not_in`. Property names are literal keys, dots included.\n\nThe same object is `posthogConfig` in REST `PATCH /api/app-profiles/:id`, MCP `upsert_app_profile` and the App Profile JSON used by `sprid init`, where `registration.event` and `registration.since` also live. No credentials or SQL belong in it. After saving, fetch Insights and check its registration notes and totals against your database before trusting a funnel.\n\n## Review suspected automated traffic\n\nRead [Check whether a traffic spike is real](https://sprid.studio/docs/traffic) (`sprid docs traffic`) before saving a rule: a spike or a shared fingerprint alone does not prove bots.\n\nOpen **Web visitors → Review traffic exclusions**, or **Settings → Apps → your app → PostHog → Review traffic**. Pick a UTC date range and a traffic group, preview the effect, then save. Agents use MCP `review_traffic` or `POST /api/app-profiles/:ref/traffic-review?workspaceId=…` with `{\"start\":\"2026-09-18\",\"end\":\"2026-09-19\"}`: end dates exclusive, UTC, at most 31 days. An optional `exclusion` previews a rule against this period and the one before. Save approved rules in `posthogConfig.trafficExclusions` through `upsert_app_profile` or the profile PATCH route, keeping the rest of the configuration. Sprid records who edited it and when.\n\nHow exclusions apply:\n\n- App-specific and date-bounded. Properties inside a rule are AND; enabled rules are OR.\n- Applied to website totals, charts, breakdowns, social attribution and weekly website counts, comparison period included. Remaining visitors are recounted as distinct people, never subtracted.\n- Native app activity and registrations are unchanged, and PostHog’s data is never changed or deleted. **Restore this traffic** disables a rule.\n- Raw connected queries and the marketing-review event inventory stay unfiltered as evidence; Insights shows the corrected figures.\n- Only PostHog is supported today.\n\n## Social traffic and clip comparisons\n\nSave the app’s website URL on its App Profile as well as connecting PostHog. Insights then compares completed-day website sessions with recorded social view gains. Shared bio traffic stays at channel level; only a dedicated tagged link identifies one publish. Older clips with metric activity stay candidates.\n\nCopy the stable bio link and dedicated clip links from Insights. Keep `utm_source`, `utm_medium`, `sprid_account` and, on dedicated links only, `sprid_publish` through any redirects. Never repoint the shared bio link to the newest publish. The optional bio-page HTML export records selections separately and keeps a direct app link; host it on the saved hostname with your existing PostHog setup.\n\nTo capture store-link clicks and website outcomes, add after your PostHog initialization:\n\n```html\n<script src=\"https://sprid.studio/sprid-attribution.js\" defer></script>\n```\n\nIt uses your PostHog client and consent state and sends nothing to Sprid. Call `window.spridAttribution?.track('signup')` or `.track('activation')` only after that action succeeds. `posthogEvents.signup` and `posthogEvents.activation` mappings also count when the event shares the arriving website session. It does not track a native app or join visits to purchases, and a store click is not an install. Missing outcomes stay unmeasured. Redirect-only flows need a beacon before navigating; redirect events are counted apart from sessions. `get_insights` and `sprid insights` return the same evidence as the dashboard.\n\n## If it fails\n\n- **Access denied:** check the key is active, grants your project and has both Read permissions. Reconnect with a corrected key file.\n- **Project not found:** check project number and host together. A US project needs the US host.\n- **Connected but no events:** check the dates and project, then ask your agent to check your app’s tracking is sending events.\n\n## Investigate with this connection\n\nReads `query` (HogQL), `events` and `properties` for the pinned project. Check instrumentation before interpreting events. Event-definition discovery also needs `event_definition:read`, property-definition discovery `property_definition:read`, both restricted to the same project.\n\n```sh\nsprid marketing-review capabilities --app <slug> --source posthog --json\n```\n\nSee [connected queries](https://sprid.studio/docs/queries).\n\n## Sources and verification\n\nSetup and live reads checked 2026-09-09.\n\n- [PostHog personal API keys](https://posthog.com/docs/api/personal-api-keys)\n- [Project identity endpoint](https://posthog.com/docs/api/projects)\n- [HogQL query endpoint](https://posthog.com/docs/api/query)\n- [SDK and framework guides](https://posthog.com/docs/libraries)\n- [React Native screen tracking](https://posthog.com/docs/libraries/react-native)\n- [Identifying users](https://posthog.com/docs/product-analytics/identify)\n- [Funnels](https://posthog.com/docs/product-analytics/funnels)\n",
+    "revision": "2b1d02d602ee3177"
+  },
+  {
+    "id": "google-analytics",
+    "title": "Google Analytics 4",
+    "summary": "See how many people visit your website, where they came from and which pages they land on. If your app uses Firebase Analytics, this is also how Sprid sees your app’s active and new users.",
+    "command": "sprid connect ga4 --key ~/Downloads/ga4-sa.json --property 493820184",
+    "url": "https://sprid.studio/docs/connect/google-analytics",
+    "sections": [
+      {
+        "id": "you-need",
+        "title": "You need",
+        "kind": "requirements",
+        "markdown": "**Editor** or **Administrator** on the GA4 property, and a Google service account. You can reuse the one from Sprid’s Google Play or Search Console connection."
+      },
+      {
+        "id": "click-path",
+        "title": "Click path",
+        "kind": "steps",
+        "markdown": "### A. Google Cloud\n\n1. Open [Google Cloud](https://console.cloud.google.com) and select your service account’s project.\n2. **APIs & Services → Library**: enable **Google Analytics Data API**.\n3. No service account yet? **IAM & Admin → Service Accounts → Create service account**, name it `sprid-analytics`, then **Done**.\n4. Open the account → **Keys → Add key → Create new key → JSON**. Save it as `ga4-sa.json` and copy the account’s email. Reusing an account? Use its existing key file and email.\n\n### B. Google Analytics\n\n5. Open [Google Analytics](https://analytics.google.com) and select the property.\n6. **Admin → Property access management → + → Add users**.\n7. Enter the service account’s email, choose **Viewer**, uncheck the notification email, then **Add**.\n\n### C. The property id\n\n8. **Admin → Property details**. Copy **Property ID**: digits only, such as `493820184`.\n\nA measurement id (`G-XXXXXXX`) is the tag on your page, not the property. The Data API refuses it, so Sprid rejects it when you type it."
+      },
+      {
+        "id": "then-run",
+        "title": "Then run",
+        "kind": "command",
+        "markdown": "```\nsprid connect ga4 --key ~/Downloads/ga4-sa.json --property 493820184\n```\n\nUse your own file path and property id. Keep the file private.\n\nAdd `--use` to make Google Analytics the source Sprid reports website traffic from. See **Only one provider answers** below."
+      },
+      {
+        "id": "only-one-provider-answers",
+        "title": "Only one provider answers",
+        "kind": "detail",
+        "markdown": "PostHog, Google Analytics and Plausible all count the same visits to the same site. Sprid reads **one** of them per app and never adds them together, because adding them would overstate your traffic by roughly the overlap, and the overlap is nearly everything.\n\nWith one connected, that one answers. With several, Sprid uses the one you chose with `--use` (PostHog by default, because it also answers the people and registration cards). The others stay connected and idle, and the traffic card says so."
+      },
+      {
+        "id": "how-to-check-it-worked",
+        "title": "How to check it worked",
+        "kind": "verify",
+        "markdown": "Run `sprid status`, then ask your agent: “Read this website’s visitors for the last 28 days through Sprid and say which provider answered.” A saved key confirms setup; only the live read confirms access."
+      },
+      {
+        "id": "if-it-fails",
+        "title": "If it fails",
+        "kind": "troubleshooting",
+        "markdown": "- **Permission denied:** access is granted on the property, not on the Google Cloud project. Check the service account’s email is in **Property access management** with at least Viewer.\n- **API not enabled:** enable **Google Analytics Data API** in the project the key came from, then wait a minute.\n- **Property not found:** you probably saved a measurement id or a stream id. Use **Admin → Property details → Property ID**.\n- **Numbers do not match the GA4 dashboard:** Google applies thresholding and its own bot filtering, and reports in the property’s time zone rather than UTC. Small differences on small properties are expected."
+      },
+      {
+        "id": "what-sprid-can-and-cannot-read-here",
+        "title": "What Sprid can and cannot read here",
+        "kind": "detail",
+        "markdown": "Visitors, pageviews, sessions, engaged sessions and engagement time, plus breakdowns by country, region, city, source, channel group, campaign, term, page, landing page, hostname, browser, operating system and device.\n\nTwo honest gaps. Google reports **no exit page**, so that breakdown is empty rather than estimated. And **channel** is Google’s own default channel group and **referrer** is the session source, neither of which is the raw referring domain another provider would show, so those rows do not compare like for like across providers."
+      },
+      {
+        "id": "sources",
+        "title": "Sources",
+        "kind": "sources",
+        "markdown": "- [Data API `runReport`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport)\n- [Batch limit of five reports](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/batchRunReports)\n- [Firebase reports into Google Analytics](https://firebase.google.com/docs/analytics)\n- [Linking a Firebase app to a GA4 property](https://support.google.com/analytics/answer/9289234)"
+      }
+    ],
+    "markdown": "# Google Analytics 4\n\n**What Sprid does with this:** See how many people visit your website, where they came from and which pages they land on. If your app uses Firebase Analytics, this is also how Sprid sees your app’s active and new users.\n\nFirebase Analytics **is** Google Analytics: a Firebase app reports into a linked GA4 property, and that property is what you connect here.\n\n## You need\n\n**Editor** or **Administrator** on the GA4 property, and a Google service account. You can reuse the one from Sprid’s Google Play or Search Console connection.\n\n## Click path\n\n### A. Google Cloud\n\n1. Open [Google Cloud](https://console.cloud.google.com) and select your service account’s project.\n2. **APIs & Services → Library**: enable **Google Analytics Data API**.\n3. No service account yet? **IAM & Admin → Service Accounts → Create service account**, name it `sprid-analytics`, then **Done**.\n4. Open the account → **Keys → Add key → Create new key → JSON**. Save it as `ga4-sa.json` and copy the account’s email. Reusing an account? Use its existing key file and email.\n\n### B. Google Analytics\n\n5. Open [Google Analytics](https://analytics.google.com) and select the property.\n6. **Admin → Property access management → + → Add users**.\n7. Enter the service account’s email, choose **Viewer**, uncheck the notification email, then **Add**.\n\n### C. The property id\n\n8. **Admin → Property details**. Copy **Property ID**: digits only, such as `493820184`.\n\nA measurement id (`G-XXXXXXX`) is the tag on your page, not the property. The Data API refuses it, so Sprid rejects it when you type it.\n\n## Then run\n\n```\nsprid connect ga4 --key ~/Downloads/ga4-sa.json --property 493820184\n```\n\nUse your own file path and property id. Keep the file private.\n\nAdd `--use` to make Google Analytics the source Sprid reports website traffic from. See **Only one provider answers** below.\n\n## Only one provider answers\n\nPostHog, Google Analytics and Plausible all count the same visits to the same site. Sprid reads **one** of them per app and never adds them together, because adding them would overstate your traffic by roughly the overlap, and the overlap is nearly everything.\n\nWith one connected, that one answers. With several, Sprid uses the one you chose with `--use` (PostHog by default, because it also answers the people and registration cards). The others stay connected and idle, and the traffic card says so.\n\n## How to check it worked\n\nRun `sprid status`, then ask your agent: “Read this website’s visitors for the last 28 days through Sprid and say which provider answered.” A saved key confirms setup; only the live read confirms access.\n\n## If it fails\n\n- **Permission denied:** access is granted on the property, not on the Google Cloud project. Check the service account’s email is in **Property access management** with at least Viewer.\n- **API not enabled:** enable **Google Analytics Data API** in the project the key came from, then wait a minute.\n- **Property not found:** you probably saved a measurement id or a stream id. Use **Admin → Property details → Property ID**.\n- **Numbers do not match the GA4 dashboard:** Google applies thresholding and its own bot filtering, and reports in the property’s time zone rather than UTC. Small differences on small properties are expected.\n\n## What Sprid can and cannot read here\n\nVisitors, pageviews, sessions, engaged sessions and engagement time, plus breakdowns by country, region, city, source, channel group, campaign, term, page, landing page, hostname, browser, operating system and device.\n\nTwo honest gaps. Google reports **no exit page**, so that breakdown is empty rather than estimated. And **channel** is Google’s own default channel group and **referrer** is the session source, neither of which is the raw referring domain another provider would show, so those rows do not compare like for like across providers.\n\n## Sources\n\n- [Data API `runReport`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport)\n- [Batch limit of five reports](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/batchRunReports)\n- [Firebase reports into Google Analytics](https://firebase.google.com/docs/analytics)\n- [Linking a Firebase app to a GA4 property](https://support.google.com/analytics/answer/9289234)\n",
+    "revision": "dfd97414267786dc"
+  },
+  {
+    "id": "plausible",
+    "title": "Plausible",
+    "summary": "See how many people visit your website, where they came from and which pages they land on.",
+    "command": "sprid connect plausible --key ~/Downloads/plausible-key.txt --site example.com",
+    "url": "https://sprid.studio/docs/connect/plausible",
+    "sections": [
+      {
+        "id": "you-need",
+        "title": "You need",
+        "kind": "requirements",
+        "markdown": "A **Business** plan or higher. The Stats API is a Business-plan feature, so a valid key on a cheaper plan is refused with a plan error rather than a key error. An API key also belongs to **one team**, so create it in the team that owns the site."
+      },
+      {
+        "id": "click-path",
+        "title": "Click path",
+        "kind": "steps",
+        "markdown": "1. Open [Plausible](https://plausible.io) and switch to the team that owns the site.\n2. **Settings → API keys → New API key**.\n3. Name it `sprid`, create it, and copy the key. Plausible shows it once.\n4. Save it to a file, such as `~/Downloads/plausible-key.txt`, so it never sits in your shell history.\n5. Your **site id** is the domain exactly as it was added to Plausible: no `https://`, no trailing slash. It is the last part of the site’s URL, `plausible.io/<site id>`."
+      },
+      {
+        "id": "then-run",
+        "title": "Then run",
+        "kind": "command",
+        "markdown": "```\nsprid connect plausible --key ~/Downloads/plausible-key.txt --site example.com\n```\n\nSelf-hosting? Add `--host https://analytics.example.com`. Add `--use` to make Plausible the source Sprid reports website traffic from."
+      },
+      {
+        "id": "only-one-provider-answers",
+        "title": "Only one provider answers",
+        "kind": "detail",
+        "markdown": "PostHog, Google Analytics and Plausible all count the same visits to the same site. Sprid reads **one** of them per app and never adds them together, because adding them would overstate your traffic by roughly the overlap, and the overlap is nearly everything.\n\nWith one connected, that one answers. With several, Sprid uses the one you chose with `--use` (PostHog by default, because it also answers the people and registration cards). The others stay connected and idle, and the traffic card says so."
+      },
+      {
+        "id": "how-to-check-it-worked",
+        "title": "How to check it worked",
+        "kind": "verify",
+        "markdown": "Run `sprid status`, then ask your agent: “Read this website’s visitors for the last 28 days through Sprid and say which provider answered.” A saved key confirms setup; only the live read confirms access."
+      },
+      {
+        "id": "if-it-fails",
+        "title": "If it fails",
+        "kind": "troubleshooting",
+        "markdown": "- **Business plan required:** the key is fine; the plan does not include the Stats API. Move to Business, or use PostHog or Google Analytics for this app instead. Nothing needs re-entering afterwards.\n- **Unauthorized:** the key belongs to a different team from the site. Create the key inside the team that owns the site.\n- **Site not found:** the site id is the domain as Plausible has it, with no scheme and no trailing slash.\n- **Rate limited:** Plausible allows 600 requests an hour per key. One reading is well inside that, so check whether another tool shares the key."
+      },
+      {
+        "id": "what-sprid-can-and-cannot-read-here",
+        "title": "What Sprid can and cannot read here",
+        "kind": "detail",
+        "markdown": "Visitors, pageviews, visits, bounce rate and visit duration, plus breakdowns by country, region, city, source, channel, campaign, term, page, entry page, exit page, hostname, browser, operating system and device.\n\nPlausible is **cookieless**: it has no person id, so a visitor is its own daily estimate rather than someone Sprid can follow between days. Window totals therefore come from Plausible directly and are never the daily numbers added up. Bounces and session time arrive as a rate and an average, and Sprid turns them back into counts, so they carry Plausible’s rounding. Days are the site’s own time zone, not UTC."
+      },
+      {
+        "id": "sources",
+        "title": "Sources",
+        "kind": "sources",
+        "markdown": "- [Stats API v2 `query`, and the Business-plan requirement](https://plausible.io/docs/stats-api)"
+      }
+    ],
+    "markdown": "# Plausible\n\n**What Sprid does with this:** See how many people visit your website, where they came from and which pages they land on.\n\n## You need\n\nA **Business** plan or higher. The Stats API is a Business-plan feature, so a valid key on a cheaper plan is refused with a plan error rather than a key error. An API key also belongs to **one team**, so create it in the team that owns the site.\n\n## Click path\n\n1. Open [Plausible](https://plausible.io) and switch to the team that owns the site.\n2. **Settings → API keys → New API key**.\n3. Name it `sprid`, create it, and copy the key. Plausible shows it once.\n4. Save it to a file, such as `~/Downloads/plausible-key.txt`, so it never sits in your shell history.\n5. Your **site id** is the domain exactly as it was added to Plausible: no `https://`, no trailing slash. It is the last part of the site’s URL, `plausible.io/<site id>`.\n\n## Then run\n\n```\nsprid connect plausible --key ~/Downloads/plausible-key.txt --site example.com\n```\n\nSelf-hosting? Add `--host https://analytics.example.com`. Add `--use` to make Plausible the source Sprid reports website traffic from.\n\n## Only one provider answers\n\nPostHog, Google Analytics and Plausible all count the same visits to the same site. Sprid reads **one** of them per app and never adds them together, because adding them would overstate your traffic by roughly the overlap, and the overlap is nearly everything.\n\nWith one connected, that one answers. With several, Sprid uses the one you chose with `--use` (PostHog by default, because it also answers the people and registration cards). The others stay connected and idle, and the traffic card says so.\n\n## How to check it worked\n\nRun `sprid status`, then ask your agent: “Read this website’s visitors for the last 28 days through Sprid and say which provider answered.” A saved key confirms setup; only the live read confirms access.\n\n## If it fails\n\n- **Business plan required:** the key is fine; the plan does not include the Stats API. Move to Business, or use PostHog or Google Analytics for this app instead. Nothing needs re-entering afterwards.\n- **Unauthorized:** the key belongs to a different team from the site. Create the key inside the team that owns the site.\n- **Site not found:** the site id is the domain as Plausible has it, with no scheme and no trailing slash.\n- **Rate limited:** Plausible allows 600 requests an hour per key. One reading is well inside that, so check whether another tool shares the key.\n\n## What Sprid can and cannot read here\n\nVisitors, pageviews, visits, bounce rate and visit duration, plus breakdowns by country, region, city, source, channel, campaign, term, page, entry page, exit page, hostname, browser, operating system and device.\n\nPlausible is **cookieless**: it has no person id, so a visitor is its own daily estimate rather than someone Sprid can follow between days. Window totals therefore come from Plausible directly and are never the daily numbers added up. Bounces and session time arrive as a rate and an average, and Sprid turns them back into counts, so they carry Plausible’s rounding. Days are the site’s own time zone, not UTC.\n\n## Sources\n\n- [Stats API v2 `query`, and the Business-plan requirement](https://plausible.io/docs/stats-api)\n",
+    "revision": "732c29e4661f1403"
+  },
+  {
+    "id": "umami",
+    "title": "Umami",
+    "summary": "See how many people visit your website, where they came from and which pages they land on.",
+    "command": "sprid connect umami --key ~/Downloads/umami-key.txt --site 8f2a1c90-4d1e-4b7a-9f33-2c0b5e7a1d44",
+    "url": "https://sprid.studio/docs/connect/umami",
+    "sections": [
+      {
+        "id": "you-need",
+        "title": "You need",
+        "kind": "requirements",
+        "markdown": "An **API key**. On Umami Cloud that is any plan. Self-hosting, you need a version new enough to have **Settings → API keys**; an older instance cannot be connected at all, whatever key you paste."
+      },
+      {
+        "id": "click-path",
+        "title": "Click path",
+        "kind": "steps",
+        "markdown": "1. Open [Umami](https://cloud.umami.is), or your own instance.\n2. **Settings → API keys → Create API key**. Name it `sprid` and copy the key. Umami shows it once.\n3. Save it to a file, such as `~/Downloads/umami-key.txt`, so it never sits in your shell history.\n4. **Settings → Websites →** the site **→ Details**. Copy the **Website ID**. It is a uuid such as `8f2a1c90-4d1e-4b7a-9f33-2c0b5e7a1d44`, **not** the domain."
+      },
+      {
+        "id": "then-run",
+        "title": "Then run",
+        "kind": "command",
+        "markdown": "```\nsprid connect umami --key ~/Downloads/umami-key.txt --site 8f2a1c90-4d1e-4b7a-9f33-2c0b5e7a1d44\n```\n\nSelf-hosting? Add `--host https://analytics.example.com`. Sprid appends the `/api` your instance serves under, so either form works. Add `--use` to make Umami the source Sprid reports website traffic from."
+      },
+      {
+        "id": "only-one-provider-answers",
+        "title": "Only one provider answers",
+        "kind": "detail",
+        "markdown": "PostHog, Google Analytics, Plausible and Umami all count the same visits to the same site. Sprid reads **one** of them per app and never adds them together, because adding them would overstate your traffic by roughly the overlap, and the overlap is nearly everything.\n\nWith one connected, that one answers. With several, Sprid uses the one you chose with `--use` (PostHog by default, because it also answers the people and registration cards). The others stay connected and idle, and the traffic card says so."
+      },
+      {
+        "id": "how-to-check-it-worked",
+        "title": "How to check it worked",
+        "kind": "verify",
+        "markdown": "Run `sprid status`, then ask your agent: “Read this website’s visitors for the last 28 days through Sprid and say which provider answered.” A saved key confirms setup; only the live read confirms access."
+      },
+      {
+        "id": "if-it-fails",
+        "title": "If it fails",
+        "kind": "troubleshooting",
+        "markdown": "- **Unauthorized:** the key cannot see this website, or your self-hosted Umami predates API keys. Check for the **Settings → API keys** screen; if there is none, upgrade first.\n- **Not found:** you probably saved the domain instead of the website id, or left `/api` off a self-hosted host. Sprid adds `/api` for you when you pass `--host`.\n- **Rate limited:** Umami Cloud is limiting requests. The next hourly read picks it up."
+      },
+      {
+        "id": "what-sprid-can-and-cannot-read-here",
+        "title": "What Sprid can and cannot read here",
+        "kind": "detail",
+        "markdown": "Visitors, pageviews, visits, bounces and total time, plus **every** breakdown this product draws: country, region, city, referrer, channel, campaign, term, page, entry page, exit page, hostname, browser, operating system and device. Umami is the only alternative provider that reports an exit page.\n\nUmami is **cookieless**, so window totals come from Umami directly and are never the daily numbers added up. The daily line counts **sessions** rather than distinct people, so it will not sum to the visitor total beside it."
+      }
+    ],
+    "markdown": "# Umami\n\n**What Sprid does with this:** See how many people visit your website, where they came from and which pages they land on.\n\nUmami is the one to reach for if Plausible's Business plan is more than you want to pay for an API, or if you self-host.\n\n## You need\n\nAn **API key**. On Umami Cloud that is any plan. Self-hosting, you need a version new enough to have **Settings → API keys**; an older instance cannot be connected at all, whatever key you paste.\n\n## Click path\n\n1. Open [Umami](https://cloud.umami.is), or your own instance.\n2. **Settings → API keys → Create API key**. Name it `sprid` and copy the key. Umami shows it once.\n3. Save it to a file, such as `~/Downloads/umami-key.txt`, so it never sits in your shell history.\n4. **Settings → Websites →** the site **→ Details**. Copy the **Website ID**. It is a uuid such as `8f2a1c90-4d1e-4b7a-9f33-2c0b5e7a1d44`, **not** the domain.\n\n## Then run\n\n```\nsprid connect umami --key ~/Downloads/umami-key.txt --site 8f2a1c90-4d1e-4b7a-9f33-2c0b5e7a1d44\n```\n\nSelf-hosting? Add `--host https://analytics.example.com`. Sprid appends the `/api` your instance serves under, so either form works. Add `--use` to make Umami the source Sprid reports website traffic from.\n\n## Only one provider answers\n\nPostHog, Google Analytics, Plausible and Umami all count the same visits to the same site. Sprid reads **one** of them per app and never adds them together, because adding them would overstate your traffic by roughly the overlap, and the overlap is nearly everything.\n\nWith one connected, that one answers. With several, Sprid uses the one you chose with `--use` (PostHog by default, because it also answers the people and registration cards). The others stay connected and idle, and the traffic card says so.\n\n## How to check it worked\n\nRun `sprid status`, then ask your agent: “Read this website’s visitors for the last 28 days through Sprid and say which provider answered.” A saved key confirms setup; only the live read confirms access.\n\n## If it fails\n\n- **Unauthorized:** the key cannot see this website, or your self-hosted Umami predates API keys. Check for the **Settings → API keys** screen; if there is none, upgrade first.\n- **Not found:** you probably saved the domain instead of the website id, or left `/api` off a self-hosted host. Sprid adds `/api` for you when you pass `--host`.\n- **Rate limited:** Umami Cloud is limiting requests. The next hourly read picks it up.\n\n## What Sprid can and cannot read here\n\nVisitors, pageviews, visits, bounces and total time, plus **every** breakdown this product draws: country, region, city, referrer, channel, campaign, term, page, entry page, exit page, hostname, browser, operating system and device. Umami is the only alternative provider that reports an exit page.\n\nUmami is **cookieless**, so window totals come from Umami directly and are never the daily numbers added up. The daily line counts **sessions** rather than distinct people, so it will not sum to the visitor total beside it.\n",
+    "revision": "e3527f9e20e023de"
   },
   {
     "id": "revenuecat",
@@ -1144,8 +1321,8 @@ export const CONTENT_GUIDES = [
     "title": "Review marketing from connected evidence",
     "summary": "Investigate acquisition, activation, retention and revenue through the services connected to Sprid, and say plainly what evidence is missing.",
     "url": "https://sprid.studio/docs/marketing-review",
-    "markdown": "# Review marketing from connected evidence\n\n**What this guide does:** Investigate acquisition, activation, retention and revenue through the services connected to Sprid, and say plainly what evidence is missing.\n\n## Start with the question\n\nName the app, the date range and the decision the review should inform.\n\n1. `list_apps` and `list_app_profiles` to find the app.\n2. `get_marketing_review_context` for shared definitions, required investigations, earlier decisions and corrections.\n3. `get_marketing_review` for the app over two comparable periods. The summary links to full evidence per source (`view: \"full\", sources: [<source>]`); omit `sources` to include social history, store reviews and milestones.\n4. Re-read an exact saved packet with `get_marketing_review_evidence` and its `evidence.id` (CLI: `sprid marketing-review evidence --id <id> --app <slug>`). It still works after a connection changes.\n\n`refresh: true` asks for live reads; `cachedOnly: true` reads only stored evidence. Keep returned errors, coverage, population definitions and sample counts in the report.\n\nIn a browser chat there is no repository. For a question about a shipped change, ask for a release summary or public changelog and label it as supplied. Never claim to have read a repository or private database. Local users can add repo diffs and database reads through their own tools.\n\n## Follow the evidence\n\n`list_marketing_queries` lists supported reads and their schemas; `query_marketing_source` runs them with Sprid’s saved credentials. Follow pagination and keep truncation visible. `get_documentation` with `metrics` covers definitions and refused calculations; with `queries`, source-specific reads.\n\n- Keep acquisition apart from activation, and people apart from events. A post impression is not an install; a download is not an activated user.\n- Compare equal windows and comparable populations.\n- No onboarding events means recommending instrumentation, not guessing a funnel.\n- Keep revenue sources separate until the overlap check says they can be added.\n\nFor each finding, test another explanation: tracking changes, traffic exclusions, attribution window, seasonality, a different audience mix. A before/after comparison doesn’t prove cause. If a difference is within normal variation or the sample is small, say so and don’t rank it.\n\n## Report and save\n\nLead with the decision, then the evidence, the limits and what would change the answer. Keep failed reads apart from reads that returned nothing. `next_actions` gives the follow-up. A missing credential goes to the secure App Profile form or a CLI key-file command; no provider MCP is needed for a supported query.\n\n- **Shared context:** when authorized, save non-secret definitions, investigations, decisions, corrections and release references with `save_marketing_review_context`, sending `baseRevision` from the latest read. A conflict returns both versions; reconcile before retrying. Saved context is a claim with references, not verification. CLI: `sprid marketing-review context --app <slug>` reads, `--file <context.json>` imports `{baseRevision,context}`. Private notes stay local.\n- **Changes:** log confirmed product or marketing changes with `add_event`, naming the areas they affect and why.\n- **The review itself:** save it as an app-scoped `kind: \"note\"` event with the date, conclusion, evidence references, coverage and next hypothesis in `meta`. Other clients read it with `list_events`.\n\nNever store secrets or signed attachment URLs in any of these.\n\n## Collection and coverage\n\n- Sprid refreshes two rolling 30-day windows daily for configured services on active plans, and re-reads late provider exports. No model calls, publishing or paid social reads. Other windows are read on demand.\n- Pause with the App Profile’s `metricsCollectionEnabled: false` or `sprid marketing-review collection --enabled false`. Stored evidence stays readable.\n- Snapshots are private to the app, tied to its configuration and kept 90 days. Save local evidence exports for a lasting archive.\n- Missing days stay unknown. Incomplete store or Search Console windows get no percentage change. Never sum daily unique people into a monthly count.\n- `configuration_only` means identifiers and a key are saved, not that access works. Errors return a safe code, the HTTP status when known, whether to retry and the next step. Retry transient errors before recommending a reconnect. Unsupported metrics and provider privacy thresholds are stated as limits.\n",
-    "revision": "f5e9475cb0f8636e"
+    "markdown": "# Review marketing from connected evidence\n\n**What this guide does:** Investigate acquisition, activation, retention and revenue through the services connected to Sprid, and say plainly what evidence is missing.\n\n## Start with the question\n\nName the app, the date range and the decision the review should inform.\n\n1. `list_apps` and `list_app_profiles` to find the app.\n2. `get_marketing_review_context` for shared definitions, required investigations, earlier decisions and corrections.\n3. `get_marketing_review` for the app over two comparable periods. The summary links to full evidence per source (`view: \"full\", sources: [<source>]`); omit `sources` to include social history, store reviews and milestones.\n4. Re-read an exact saved packet with `get_marketing_review_evidence` and its `evidence.id` (CLI: `sprid marketing-review evidence --id <id> --app <slug>`). It still works after a connection changes.\n\n`refresh: true` asks for live reads; `cachedOnly: true` reads only stored evidence. Keep returned errors, coverage, population definitions and sample counts in the report.\n\nIn a browser chat there is no repository. For a question about a shipped change, ask for a release summary or public changelog and label it as supplied. Never claim to have read a repository or private database. Local users can add repo diffs and database reads through their own tools.\n\n## Follow the evidence\n\n`list_marketing_queries` lists supported reads and their schemas; `query_marketing_source` runs them with Sprid’s saved credentials. Follow pagination and keep truncation visible. `get_documentation` with `metrics` covers definitions and refused calculations; with `queries`, source-specific reads.\n\n- Keep acquisition apart from activation, and people apart from events. A post impression is not an install; a download is not an activated user.\n- Compare equal windows and comparable populations.\n- No onboarding events means recommending instrumentation, not guessing a funnel.\n- Keep revenue sources separate until the overlap check says they can be added.\n\nFor each finding, test another explanation: tracking changes, traffic exclusions, attribution window, seasonality, a different audience mix. A before/after comparison doesn’t prove cause. If a difference is within normal variation or the sample is small, say so and don’t rank it.\n\n## Report and save\n\nLead with the decision, then the evidence, the limits and what would change the answer. Keep failed reads apart from reads that returned nothing. `next_actions` gives the follow-up. Check [remaining setup](../../../references/setup-continuation.md#keep-setup-current), including the saved app icon, voice and relevant connections. Recommend the next useful integration step without repeating completed or explicitly declined setup. A missing credential goes to the secure App Profile form or a CLI key-file command; no provider MCP is needed for a supported query.\n\n- **Shared context:** when authorized, save non-secret definitions, investigations, decisions, corrections and release references with `save_marketing_review_context`, sending `baseRevision` from the latest read. A conflict returns both versions; reconcile before retrying. Saved context is a claim with references, not verification. CLI: `sprid marketing-review context --app <slug>` reads, `--file <context.json>` imports `{baseRevision,context}`. Private notes stay local.\n- **Changes:** log confirmed product or marketing changes with `add_event`, naming the areas they affect and why.\n- **The review itself:** save it as an app-scoped `kind: \"note\"` event with the date, conclusion, evidence references, coverage and next hypothesis in `meta`. Other clients read it with `list_events`.\n\nNever store secrets or signed attachment URLs in any of these.\n\n## Collection and coverage\n\n- Sprid refreshes two rolling 30-day windows daily for configured services on active plans, and re-reads late provider exports. No model calls, publishing or paid social reads. Other windows are read on demand.\n- Pause with the App Profile’s `metricsCollectionEnabled: false` or `sprid marketing-review collection --enabled false`. Stored evidence stays readable.\n- Snapshots are private to the app, tied to its configuration and kept 90 days. Save local evidence exports for a lasting archive.\n- Missing days stay unknown. Incomplete store or Search Console windows get no percentage change. Never sum daily unique people into a monthly count.\n- `configuration_only` means identifiers and a key are saved, not that access works. Errors return a safe code, the HTTP status when known, whether to retry and the next step. Retry transient errors before recommending a reconnect. Unsupported metrics and provider privacy thresholds are stated as limits.\n",
+    "revision": "c2e55d715091dd81"
   },
   {
     "id": "traffic",