@happyvertical/smrt-analytics 0.55.6 → 0.55.8

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-analytics",
-  "packageVersion": "0.55.6",
+  "packageVersion": "0.55.8",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "6843fb6ad33d0daa60c575a458952203a42517927ed7676a8251af51d0beba49",
-    "packageJson": "7777d7403e847ac67dd327c58de9bde41bd46ecc923a6a98661950298b22da84",
-    "agents": "baaeb44320f95dc5dc86925318e791369681ad80acfbb82a0f667f2aed0e511c"
+    "manifest": "13e06c4864f1626ead1e71361caa78ea17d36759f93466401b89777a837f7840",
+    "packageJson": "555165f082315ad6ae43e615f456c7b855b2a1faf9d3275c2646926427eef1fd",
+    "agents": "52d16fea29774e6ac50038329c1c644f2f25d2b02df4fc75c96effe7ce477713"
   },
   "exports": [
     ".",
@@ -25,6 +25,7 @@
     "@happyvertical/smrt-tenancy": "workspace:*",
     "@happyvertical/smrt-types": "workspace:*",
     "@happyvertical/smrt-ui": "workspace:*",
+    "@happyvertical/smrt-scanner": "workspace:*",
     "@happyvertical/smrt-vitest": "workspace:*",
     "@happyvertical/sql": "catalog:",
     "@sveltejs/package": "^2.5.8",
@@ -39,6 +40,7 @@
   "smrtDependencies": [
     "@happyvertical/smrt-core",
     "@happyvertical/smrt-prompts",
+    "@happyvertical/smrt-scanner",
     "@happyvertical/smrt-tenancy",
     "@happyvertical/smrt-types",
     "@happyvertical/smrt-ui",
@@ -1524,6 +1526,7 @@
       "name": "AnalyticsDataStream",
       "qualifiedName": "@happyvertical/smrt-analytics:AnalyticsDataStream",
       "collection": "analyticsdatastreams",
+      "description": "AnalyticsDataStream represents a data stream (web, iOS, Android) for an analytics property.",
       "tableName": "analytics_data_streams",
       "packageName": "@happyvertical/smrt-analytics",
       "extends": "SmrtObject",
@@ -1826,6 +1829,7 @@
       "name": "AnalyticsEvent",
       "qualifiedName": "@happyvertical/smrt-analytics:AnalyticsEvent",
       "collection": "analyticsevents",
+      "description": "AnalyticsEvent represents a tracked analytics event (server-side tracking log).",
       "tableName": "analytics_events",
       "packageName": "@happyvertical/smrt-analytics",
       "extends": "SmrtObject",
@@ -2258,6 +2262,7 @@
       "qualifiedName": "@happyvertical/smrt-analytics:AnalyticsProperty",
       "displayLabelField": "name",
       "collection": "analyticsproperties",
+      "description": "AnalyticsProperty represents an analytics property (GA4 property, Plausible site, or Matomo site).",
       "tableName": "analytics_properties",
       "packageName": "@happyvertical/smrt-analytics",
       "extends": "SmrtObject",
@@ -2292,48 +2297,55 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The name people see for this website or app."
         },
         {
           "name": "provider",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "Which analytics service tracks it: Google Analytics 4, Plausible or Matomo."
         },
         {
           "name": "externalId",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The id the analytics service gives the property, such as properties/123456789 or a Matomo site id."
         },
         {
           "name": "measurementId",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The tracking id for a web stream, such as G-XXXXXXXXXX."
         },
         {
           "name": "siteDomain",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The website address, used by Plausible and Matomo."
         },
         {
           "name": "timeZone",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "America/Los_Angeles"
+          "default": "America/Los_Angeles",
+          "description": "The time zone the figures are reported in."
         },
         {
           "name": "currencyCode",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "USD"
+          "default": "USD",
+          "description": "The currency used for revenue figures, such as USD."
         },
         {
           "name": "industryCategory",
@@ -2353,13 +2365,15 @@
           "name": "status",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "Whether tracking is active, inactive or still being set up."
         },
         {
           "name": "lastSyncAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When the property was last synced with the analytics service."
         }
       ],
       "relationships": [],
@@ -2620,6 +2634,7 @@
       "qualifiedName": "@happyvertical/smrt-analytics:AnalyticsReport",
       "displayLabelField": "name",
       "collection": "analyticsreports",
+      "description": "AnalyticsReport represents a saved report configuration with optional scheduling.",
       "tableName": "analytics_reports",
       "packageName": "@happyvertical/smrt-analytics",
       "extends": "SmrtObject",
@@ -2647,49 +2662,56 @@
           "type": "foreignKey",
           "required": false,
           "related": "AnalyticsProperty",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The website or app this report is about."
         },
         {
           "name": "name",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A short name for the report, such as Weekly traffic."
         },
         {
           "name": "description",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What the report is for."
         },
         {
           "name": "dimensions",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "[]"
+          "default": "[]",
+          "description": "What to break the figures down by, such as country or device, as a list."
         },
         {
           "name": "metrics",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "[]"
+          "default": "[]",
+          "description": "What to count, such as active users or sessions, as a list."
         },
         {
           "name": "dateRangeStart",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "7daysAgo"
+          "default": "7daysAgo",
+          "description": "Where the period begins: a date, or a relative value such as 7daysAgo."
         },
         {
           "name": "dateRangeEnd",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "today"
+          "default": "today",
+          "description": "Where the period ends: a date, or a relative value such as today."
         },
         {
           "name": "dimensionFilter",
@@ -2723,25 +2745,29 @@
           "name": "status",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "Where the report stands: draft, scheduled, running, completed or failed."
         },
         {
           "name": "frequency",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "How often the report repeats: once, daily, weekly or monthly."
         },
         {
           "name": "lastRunAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When the report last ran."
         },
         {
           "name": "nextRunAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When the report is next due to run."
         },
         {
           "name": "resultData",
@@ -2755,14 +2781,16 @@
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "How many rows the last run returned."
         },
         {
           "name": "lastError",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Why the last run failed. Empty when it worked."
         }
       ],
       "relationships": [
@@ -4629,5 +4657,145 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 22
   },
-  "agentDoc": "# @happyvertical/smrt-analytics\n\nGA4/Plausible/Matomo analytics integration with server-side event tracking and AI-powered reporting.\n\n## Models\n\n- **AnalyticsProperty**: GA4 property, Plausible site, or Matomo site. Provider metadata, status, sync timestamps.\n- **AnalyticsDataStream**: web/iOS/Android data streams. Measurement IDs (G-XXXXXX for GA4, Firebase app ID for mobile).\n- **AnalyticsEvent**: tracked events with params (JSON), retry queue, conversion classification.\n- **AnalyticsReport**: saved report configs with dimensions/metrics (JSON), scheduling (daily/weekly/monthly), result caching.\n\nAll models use STI (`tableStrategy: 'sti'`).\n\nAll four persisted models are `@TenantScoped({ mode: 'optional' })` with a nullable `tenantId` (#1410), matching the framework convention used by sibling domain packages (ads/jobs/commerce). **When a tenant context is active**, the interceptor auto-filters `list`/`get`/raw reads and binds `create`/`save` writes to that tenant, keeping one tenant's properties, data streams, events (end-user PII), and cached report rows from reaching another. Because the mode is `optional`, the interceptor intentionally passes **through unfiltered when no tenant context is established** — so a surface is only safe insofar as it establishes tenant context first. Generated SvelteKit routes do this (#1540); the CLI/MCP code paths do not yet, which is a known framework-level residual (fail-closed tenant context for CLI/MCP) tracked outside this package, not an analytics-specific gap.\n\n## Key Collection Methods\n\n`findByExternalId()`, `findByProvider()`, `findNeedingSync()`, `findGA4Properties()`, `findPlausibleSites()`, `findMatomoSites()`\n\n## AI Operations\n\n`analyzePerformance()`, `analyzeResults()`, `hasPositiveTrends()` route through registered prompts (see Prompt Registry below) so tenant overrides apply via `resolvePrompt()`. `isPerformingWell()` still uses the inline `is()` shortcut.\n\n## Prompt Registry\n\nThree prompts are registered at module-load time via `definePrompt()` from `@happyvertical/smrt-prompts`. Re-exported from the package root for tenant override targeting.\n\n| Key | Method | Variables (PII-conscious) |\n|-----|--------|---------------------------|\n| `smrtAnalytics.property.analyzePerformance` | `AnalyticsProperty.analyzePerformance()` | `period`, `propertyDisplayName`, `propertyProvider` |\n| `smrtAnalytics.report.analyzeResults` | `AnalyticsReport.analyzeResults()` | `reportName`, `reportDimensions`, `reportMetrics`, `dateRangeStart`, `dateRangeEnd`, `rowCount`, `reportData` |\n| `smrtAnalytics.report.hasPositiveTrends` | `AnalyticsReport.hasPositiveTrends()` | `reportMetrics`, `reportData` |\n\n**Excluded from variables (never reach the AI provider):**\n- `id`, `propertyId`, `tenantId`, `externalId` — internal foreign keys / UUIDs that link to identifying records.\n- `apiSecret`, `measurementId`, `siteDomain` — provider credentials and platform-specific identifiers (GA4 API secrets, Matomo `idSite`, custom `G-XXXX` measurement IDs).\n- `providerMetadata` — extensible JSON blob that may contain credentials, account IDs, or other configuration secrets.\n- `lastError`, raw `dimensionFilter` / `metricFilter` JSON — internal error strings (may contain auth tokens) and filter expressions that may reference cookie IDs, user-pseudo-IDs, or IP-derived geos.\n\n**`resultData` is forwarded verbatim.** This package does not — and cannot — strip PII from result rows, because the row schema is determined by the dimensions/metrics the caller asked the analytics provider to return. If the caller persists rows containing a `userPseudoId`, `clientId`, IP-derived geolocation, or any other identifier, those fields WILL reach the AI provider. Callers must:\n\n- exclude PII-bearing dimensions before persisting `resultData` (e.g. don't request `userPseudoId` as a GA4 dimension), or\n- apply a column allowlist at the call site before invoking `analyzeResults()`, or\n- override the prompt template via `PromptOverride` to redact rows.\n\nThe forwarding contract is pinned by a regression test in `src/__tests__/analytics-report-prompt.test.ts`.\n\nSee `src/prompts.ts` for the full rationale block.\n\n## UI Registry\n\nSvelte components live in `src/svelte/` and auto-register with `ModuleUIRegistry` from `@happyvertical/smrt-ui/registry` when `@happyvertical/smrt-analytics/svelte` is imported.\n\nSlot declarations live in `src/ui.ts`, exported via the `./ui` package subpath. The slots are: `analytics-summary`, `events-table`, `property-info`, `property-status-badge`, `stat-card`, `trend-badge` (see `ANALYTICS_UI_SLOTS` for icons / categories / display order).\n\n```typescript\nimport '@happyvertical/smrt-analytics/svelte'; // side-effect: registers slots\nimport { ModuleUIRegistry } from '@happyvertical/smrt-ui/registry';\nconst StatCard = ModuleUIRegistry.get('@happyvertical/smrt-analytics', 'stat-card');\n```\n\n## Gotchas\n\n- **`apiSecret` / `providerMetadata` stripped from API/MCP**: marked `@field({ sensitive: true })` (#1540) so they never appear in generated responses or `where` filters. They are still stored at rest **unencrypted** — envelope encryption via `@happyvertical/smrt-secrets` is a separate, breaking follow-up (tracked, not done here).\n- **Event retry at model level**: no background job integration\n- **JSON fields**: params, dimensions, metrics use string storage with getter/setter helpers\n- **Measurement IDs differ per platform**: G-XXXXXX (GA4 web) vs Firebase app ID (mobile)\n- **`analyzeResults` is now a single AI call**: previously issued a second freeform `do()` to summarize \"top 3 insights\"; folded into the registered template, and `insights` mirrors `analysis` in the response shape.\n"
+  "agentDoc": "# @happyvertical/smrt-analytics\n\nGA4/Plausible/Matomo analytics integration with server-side event tracking and AI-powered reporting.\n\n## Models\n\n- **AnalyticsProperty**: GA4 property, Plausible site, or Matomo site. Provider metadata, status, sync timestamps.\n- **AnalyticsDataStream**: web/iOS/Android data streams. Measurement IDs (G-XXXXXX for GA4, Firebase app ID for mobile).\n- **AnalyticsEvent**: tracked events with params (JSON), retry queue, conversion classification.\n- **AnalyticsReport**: saved report configs with dimensions/metrics (JSON), scheduling (daily/weekly/monthly), result caching.\n\nAll models use STI (`tableStrategy: 'sti'`).\n\nAll four persisted models are `@TenantScoped({ mode: 'optional' })` with a nullable `tenantId` (#1410), matching the framework convention used by sibling domain packages (ads/jobs/commerce). **When a tenant context is active**, the interceptor auto-filters `list`/`get`/raw reads and binds `create`/`save` writes to that tenant, keeping one tenant's properties, data streams, events (end-user PII), and cached report rows from reaching another. Because the mode is `optional`, the interceptor intentionally passes **through unfiltered when no tenant context is established** — so a surface is only safe insofar as it establishes tenant context first. Generated SvelteKit routes do this (#1540); the CLI/MCP code paths do not yet, which is a known framework-level residual (fail-closed tenant context for CLI/MCP) tracked outside this package, not an analytics-specific gap.\n\n## Key Collection Methods\n\n`findByExternalId()`, `findByProvider()`, `findNeedingSync()`, `findGA4Properties()`, `findPlausibleSites()`, `findMatomoSites()`\n\n## AI Operations\n\n`analyzePerformance()`, `analyzeResults()`, `hasPositiveTrends()` route through registered prompts (see Prompt Registry below) so tenant overrides apply via `resolvePrompt()`. `isPerformingWell()` still uses the inline `is()` shortcut.\n\n## Prompt Registry\n\nThree prompts are registered at module-load time via `definePrompt()` from `@happyvertical/smrt-prompts`. Re-exported from the package root for tenant override targeting.\n\n| Key | Method | Variables (PII-conscious) |\n|-----|--------|---------------------------|\n| `smrtAnalytics.property.analyzePerformance` | `AnalyticsProperty.analyzePerformance()` | `period`, `propertyDisplayName`, `propertyProvider` |\n| `smrtAnalytics.report.analyzeResults` | `AnalyticsReport.analyzeResults()` | `reportName`, `reportDimensions`, `reportMetrics`, `dateRangeStart`, `dateRangeEnd`, `rowCount`, `reportData` |\n| `smrtAnalytics.report.hasPositiveTrends` | `AnalyticsReport.hasPositiveTrends()` | `reportMetrics`, `reportData` |\n\n**Excluded from variables (never reach the AI provider):**\n- `id`, `propertyId`, `tenantId`, `externalId` — internal foreign keys / UUIDs that link to identifying records.\n- `apiSecret`, `measurementId`, `siteDomain` — provider credentials and platform-specific identifiers (GA4 API secrets, Matomo `idSite`, custom `G-XXXX` measurement IDs).\n- `providerMetadata` — extensible JSON blob that may contain credentials, account IDs, or other configuration secrets.\n- `lastError`, raw `dimensionFilter` / `metricFilter` JSON — internal error strings (may contain auth tokens) and filter expressions that may reference cookie IDs, user-pseudo-IDs, or IP-derived geos.\n\n**`resultData` is forwarded verbatim.** This package does not — and cannot — strip PII from result rows, because the row schema is determined by the dimensions/metrics the caller asked the analytics provider to return. If the caller persists rows containing a `userPseudoId`, `clientId`, IP-derived geolocation, or any other identifier, those fields WILL reach the AI provider. Callers must:\n\n- exclude PII-bearing dimensions before persisting `resultData` (e.g. don't request `userPseudoId` as a GA4 dimension), or\n- apply a column allowlist at the call site before invoking `analyzeResults()`, or\n- override the prompt template via `PromptOverride` to redact rows.\n\nThe forwarding contract is pinned by a regression test in `src/__tests__/analytics-report-prompt.test.ts`.\n\nSee `src/prompts.ts` for the full rationale block.\n\n## UI Registry\n\nSvelte components live in `src/svelte/` and auto-register with `ModuleUIRegistry` from `@happyvertical/smrt-ui/registry` when `@happyvertical/smrt-analytics/svelte` is imported.\n\nSlot declarations live in `src/ui.ts`, exported via the `./ui` package subpath. The slots are: `analytics-summary`, `events-table`, `property-info`, `property-status-badge`, `stat-card`, `trend-badge` (see `ANALYTICS_UI_SLOTS` for icons / categories / display order).\n\n```typescript\nimport '@happyvertical/smrt-analytics/svelte'; // side-effect: registers slots\nimport { ModuleUIRegistry } from '@happyvertical/smrt-ui/registry';\nconst StatCard = ModuleUIRegistry.get('@happyvertical/smrt-analytics', 'stat-card');\n```\n\n## Recipes (#3719)\n\n`src/recipes.ts` declares `analytics.reports` (`AnalyticsReportsRecipe`:\n`AnalyticsProperty` and `AnalyticsReport`), emitted into the built\n`manifest.json` and `smrt-knowledge.json` `recipes`. `AnalyticsEvent` and\n`AnalyticsDataStream` are left out: event tracking and stream setup are separate\nconcerns. User-facing help is `src/reports.recipe.md` (#3591); keep it and the\n`@field({ description })` text on the two models in plain language, and never\nreference a `sensitive` field (`apiSecret`, `providerMetadata`) in help.\n\n- **Runtime is `server`.** Reports and their rows live in the app database, the\n  AI summary needs a server-held key, and provider credentials sit on the\n  property row (so no `providers` are declared: there are no env secrets to name).\n- **One route, deliberately.** `/analytics/summary` mounts\n  `@happyvertical/smrt-analytics/svelte#AnalyticsSummary`, which renders an empty\n  state without data. `PropertyInfo` and `EventsTable` take required row props\n  and throw with none, so they are not routes; a host places them in its own\n  pages. Add a route only for a component that survives being mounted bare.\n- **No demo seed.** The playground sample data is module-local, not an export.\n- **What the assistant can do.** Generated MCP exposes `list` and `get` on\n  `AnalyticsReport` only; `analyzeResults()` is a model method the app calls,\n  not a tool. The help says so and points at `reports.query` (declared reports,\n  `@happyvertical/smrt-reports`) and `reports.runtime.*` (runtime reports,\n  `@happyvertical/smrt-chat`) for aggregates over the app's own data.\n\n`src/__tests__/recipes.test.ts` runs the real scan, manifest and generation\npasses in memory and renders the help. See\n[core recipes](../core/agents/recipes.md).\n\n## Gotchas\n\n- **`apiSecret` / `providerMetadata` stripped from API/MCP**: marked `@field({ sensitive: true })` (#1540) so they never appear in generated responses or `where` filters. They are still stored at rest **unencrypted** — envelope encryption via `@happyvertical/smrt-secrets` is a separate, breaking follow-up (tracked, not done here).\n- **Event retry at model level**: no background job integration\n- **JSON fields**: params, dimensions, metrics use string storage with getter/setter helpers\n- **Measurement IDs differ per platform**: G-XXXXXX (GA4 web) vs Firebase app ID (mobile)\n- **`analyzeResults` is now a single AI call**: previously issued a second freeform `do()` to summarize \"top 3 insights\"; folded into the registered template, and `insights` mirrors `analysis` in the response shape.\n",
+  "recipes": [
+    {
+      "id": "analytics.reports",
+      "className": "AnalyticsReportsRecipe",
+      "label": "Analytics",
+      "summary": "Save traffic reports for your websites and apps and get a plain-language read on the results.",
+      "synonyms": [
+        "analytics",
+        "traffic",
+        "pageviews",
+        "visitors",
+        "web stats",
+        "google analytics",
+        "plausible",
+        "matomo"
+      ],
+      "models": [
+        "@happyvertical/smrt-analytics:AnalyticsProperty",
+        "@happyvertical/smrt-analytics:AnalyticsReport"
+      ],
+      "nav": [
+        {
+          "label": "Analytics properties",
+          "model": "@happyvertical/smrt-analytics:AnalyticsProperty",
+          "icon": "home",
+          "description": "The websites and apps you track, and who tracks them."
+        },
+        {
+          "label": "Analytics reports",
+          "model": "@happyvertical/smrt-analytics:AnalyticsReport",
+          "icon": "fileText",
+          "description": "Saved reports, how often they run and what they found."
+        }
+      ],
+      "requires": [],
+      "section": {
+        "id": "analytics",
+        "label": "Analytics",
+        "icon": "layers",
+        "description": "How your websites and apps are doing."
+      },
+      "options": {
+        "@happyvertical/smrt-analytics:AnalyticsProperty": {
+          "fields": {
+            "name": {
+              "visibility": "hidden"
+            },
+            "industryCategory": {
+              "visibility": "advanced"
+            },
+            "serviceLevel": {
+              "visibility": "advanced"
+            },
+            "lastSyncAt": {
+              "locked": true
+            }
+          }
+        },
+        "@happyvertical/smrt-analytics:AnalyticsReport": {
+          "fields": {
+            "dimensionFilter": {
+              "visibility": "advanced"
+            },
+            "metricFilter": {
+              "visibility": "advanced"
+            },
+            "orderBy": {
+              "visibility": "advanced"
+            },
+            "maxResults": {
+              "visibility": "advanced"
+            },
+            "resultData": {
+              "visibility": "hidden",
+              "locked": true
+            },
+            "rowCount": {
+              "locked": true
+            },
+            "lastRunAt": {
+              "locked": true
+            },
+            "nextRunAt": {
+              "locked": true
+            },
+            "lastError": {
+              "locked": true
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nAnalytics keeps the traffic reports you care about for your websites and apps.\nAdd a property for each site or app you track in Google Analytics 4, Plausible\nor Matomo. Save a report on it that says what to count, what to break the\nfigures down by, and over which dates. The rows each run returns are stored\nwith the report, and the assistant can read them back to you in plain words.\n\nProperties and reports are kept on your server. Provider secrets are stored on\nthe property and never sent to the assistant or returned in responses, but they\nare not encrypted in the database.\n\n## Tasks\n\n### Add a property\n\n1. Create a new property.\n2. Enter the **{field:AnalyticsProperty.displayName}** and pick the\n   **{field:AnalyticsProperty.provider}**.\n3. Enter the **{field:AnalyticsProperty.externalId}** the analytics service\n   gives it.\n4. For Google Analytics, enter the **{field:AnalyticsProperty.measurementId}**.\n   For Plausible or Matomo, enter the **{field:AnalyticsProperty.siteDomain}**.\n5. Keep **{field:AnalyticsProperty.status}** on active while you want it\n   tracked.\n\n### Save a report\n\n1. Create a new report and choose the property in\n   **{field:AnalyticsReport.propertyId}**.\n2. Give it a **{field:AnalyticsReport.name}**.\n3. List what to break the figures down by in\n   **{field:AnalyticsReport.dimensions}** and what to count in\n   **{field:AnalyticsReport.metrics}**.\n4. Set the period with **{field:AnalyticsReport.dateRangeStart}** and\n   **{field:AnalyticsReport.dateRangeEnd}**.\n5. Pick **{field:AnalyticsReport.frequency}** to repeat it daily, weekly or\n   monthly.\n\n### Check what a report found\n\n1. **{field:AnalyticsReport.status}** says where the report stands, and\n   **{field:AnalyticsReport.lastRunAt}** when it last ran.\n2. **{field:AnalyticsReport.rowCount}** shows how many rows came back.\n3. If a run failed, **{field:AnalyticsReport.lastError}** says why.\n\n### Ask the assistant\n\n1. Ask about a saved report by name, for example \"how did last week's traffic\n   report look?\". When your app has the analytics tools switched on, the\n   assistant can list your saved reports and open one to read its figures.\n2. A written summary of a report comes from your app, which sends the stored\n   rows to the AI provider as they are. Leave out dimensions that identify a\n   person.\n3. For totals your own app calculates, such as orders or signups, ask for a\n   refreshed report. The assistant reads those with `reports.query`; see\n   Reports.\n4. For a one-off question those reports do not answer, the assistant can\n   propose a report with `reports.runtime.define`. Nothing is saved until you\n   confirm it.\n",
+        "fieldRefs": [
+          "AnalyticsProperty.displayName",
+          "AnalyticsProperty.externalId",
+          "AnalyticsProperty.measurementId",
+          "AnalyticsProperty.provider",
+          "AnalyticsProperty.siteDomain",
+          "AnalyticsProperty.status",
+          "AnalyticsReport.dateRangeEnd",
+          "AnalyticsReport.dateRangeStart",
+          "AnalyticsReport.dimensions",
+          "AnalyticsReport.frequency",
+          "AnalyticsReport.lastError",
+          "AnalyticsReport.lastRunAt",
+          "AnalyticsReport.metrics",
+          "AnalyticsReport.name",
+          "AnalyticsReport.propertyId",
+          "AnalyticsReport.rowCount",
+          "AnalyticsReport.status"
+        ]
+      },
+      "surfaces": [
+        {
+          "kind": "route",
+          "path": "/analytics/summary",
+          "export": "@happyvertical/smrt-analytics/svelte#AnalyticsSummary",
+          "label": "Traffic summary"
+        }
+      ],
+      "runtime": "server",
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "The recipe declares runtime \"server\".",
+          "Needs a server because its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3624)."
+        ]
+      }
+    }
+  ],
+  "browser": {
+    "status": "server-only",
+    "issues": [
+      "#3624"
+    ],
+    "via": [
+      "@happyvertical/smrt-tenancy"
+    ]
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-analytics",
-  "version": "0.55.6",
+  "version": "0.55.8",
   "smrtJsdoc": "strict",
   "description": "Analytics integration models for SMRT framework",
   "type": "module",
@@ -33,11 +33,11 @@
     }
   },
   "dependencies": {
-    "@happyvertical/smrt-core": "0.55.6",
-    "@happyvertical/smrt-prompts": "0.55.6",
-    "@happyvertical/smrt-tenancy": "0.55.6",
-    "@happyvertical/smrt-types": "0.55.6",
-    "@happyvertical/smrt-ui": "0.55.6"
+    "@happyvertical/smrt-core": "0.55.8",
+    "@happyvertical/smrt-prompts": "0.55.8",
+    "@happyvertical/smrt-tenancy": "0.55.8",
+    "@happyvertical/smrt-types": "0.55.8",
+    "@happyvertical/smrt-ui": "0.55.8"
   },
   "peerDependencies": {
     "svelte": "^5.57.0"
@@ -48,8 +48,9 @@
     }
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.55.6",
-    "@happyvertical/sql": "^0.102.4",
+    "@happyvertical/smrt-scanner": "0.55.8",
+    "@happyvertical/smrt-vitest": "0.55.8",
+    "@happyvertical/sql": "^0.103.1",
     "@sveltejs/package": "^2.5.8",
     "@types/node": "24.13.6",
     "fast-glob": "3.3.3",