@agent-native/core 0.122.4 → 0.123.0

package/corpus/core/docs/content/template-analytics-monitoring-and-sessions.mdx

@@ -0,0 +1,109 @@
+---
+title: "Analytics: Monitoring, Errors, and Session Replay"
+description: "Uptime checks with a public status page, Sentry-style error triage, full session replay with a Dev Tools panel, and traffic/SEO reporting in Analytics."
+---
+
+# Monitoring, Errors, and Session Replay
+
+Analytics doesn't just chart your data — it watches your product. This page covers the Monitoring tab (uptime checks and error triage), session replay, and traffic/SEO reporting. It's useful to anyone using [Analytics](/docs/template-analytics), though a few sections get more technical toward the end.
+
+<WireframeBlock id="doc-block-analytics2">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='display:flex;flex-direction:column;min-height:480px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px;padding:14px 16px;border-bottom:1.4px solid var(--wf-line)'><strong>Monitoring</strong><div style='flex:1'></div><span class='wf-pill accent'>Uptime</span><span class='wf-pill'>Errors</span><button class='primary'>Add monitor</button></div><div style='display:flex;flex-direction:column;gap:8px;padding:14px 16px'><div class='wf-card' style='display:grid;grid-template-columns:16px 1fr auto auto;gap:12px;align-items:center'><span style='width:9px;height:9px;border-radius:50%;background:#3fb950'></span><span><strong>Production API</strong><br/><span class='wf-muted' style='font-size:11px'>api.example.com/health</span></span><span class='wf-muted' style='font-size:11px'>99.98% · 30d</span><span class='wf-pill accent'>up</span></div><div class='wf-card' style='display:grid;grid-template-columns:16px 1fr auto auto;gap:12px;align-items:center'><span style='width:9px;height:9px;border-radius:50%;background:#e5534b'></span><span><strong>Checkout webhook</strong><br/><span class='wf-muted' style='font-size:11px'>api.example.com/webhooks/checkout</span></span><span class='wf-muted' style='font-size:11px'>96.2% · 30d</span><span class='wf-pill'>down</span></div><div class='wf-card' style='display:grid;grid-template-columns:16px 1fr auto auto;gap:12px;align-items:center'><span style='width:9px;height:9px;border-radius:50%;background:#3fb950'></span><span><strong>Marketing site</strong><br/><span class='wf-muted' style='font-size:11px'>example.com</span></span><span class='wf-muted' style='font-size:11px'>100% · 30d</span><span class='wf-pill accent'>up</span></div></div><div class='wf-card' style='margin:0 16px 16px;display:flex;flex-direction:column;gap:8px'><strong>Recent error issues</strong><div style='display:flex;justify-content:space-between;gap:8px'><span>TypeError: cannot read 'id' of undefined</span><span class='wf-muted' style='font-size:11px'>42 events · 3 users</span></div><div style='display:flex;justify-content:space-between;gap:8px'><span>NetworkError: fetch failed (checkout)</span><span class='wf-muted' style='font-size:11px'>8 events · 1 user</span></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+## Uptime monitoring
+
+Add a monitor for any URL: pick the HTTP method, an interval (checked every few minutes), an expected status range or exact codes, and optional assertions (response body contains X, a header matches, latency stays under a threshold). When a check fails, Analytics opens an incident, applies a cooldown so it doesn't spam you on every retry, and notifies you through the inbox, email, Slack, or a webhook — configurable per monitor.
+
+Ask the agent directly: "add an uptime check for api.example.com/health every 5 minutes, alert Slack if it goes down" — no dashboard-building required.
+
+**Public status pages.** Bundle a set of your monitors under a public page at `/status/<your-slug>` — anyone with the link sees color-coded uptime bars and overall uptime percentages, never the underlying URLs, headers, or alert configuration, unless you explicitly opt a monitor in to show its URL. You control the layout: which of uptime bars, overall uptime, and response time show, plus a comfortable or compact density.
+
+## Error issue triage
+
+Browser exceptions captured from your app (or from Analytics itself) get grouped into **issues** by a stable fingerprint — one row per distinct error, not one row per occurrence. Each issue tracks its type, a human-readable title, severity (fatal down to debug), first-seen and last-seen times, a lifetime occurrence count, and roughly how many distinct users hit it.
+
+Open an issue to see recent frequency, a parsed stack trace (with source snippets where available), breadcrumbs leading up to the error, tags, and — when one exists — a link to the session recording where it happened. Mark an issue **resolved** or **ignored** once you've dealt with it; it reopens automatically if it recurs.
+
+<Diagram id="doc-block-analytics3" title="From a thrown error to a linked replay" summary={"An exception in the browser becomes a grouped issue, and the session it happened in is one click away."}>
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-box">
+    Browser throws<br /><small class="diagram-muted"
+      >console.error, unhandled rejection</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">Grouped by fingerprint</span
+    ><small class="diagram-muted">type + top stack frame</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">
+    Error issue<br /><small class="diagram-muted"
+      >stack, breadcrumbs, tags</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
+  <div class="diagram-box">
+    Session replay<br /><small class="diagram-muted"
+      >watch what the user did</small
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+.diagram-flow .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Session replay
+
+Every recorded session captures the page, a masked/privacy-aware view of user interactions, console output, and network activity, then plays it back frame by frame. Inputs are masked by default; mark any element `.an-mask` (hide the text) or `.an-block` (skip capture entirely) for anything more sensitive.
+
+The replay player has a **Dev Tools** toggle with Console and Network tabs — filter chips, search, an error-count badge, and click-to-jump so you can seek the playhead straight to the moment a request failed or an error logged. It's built for the exact workflow of debugging a user-reported bug: search their email on the Sessions list, open their recording, and jump straight to the failure.
+
+**Sharing a replay with an external agent.** Recordings stay private — Analytics never makes one public just so an agent can look at it. Instead, open the session and click **Copy for agent** to mint a two-hour tokenized link. Paste that link to any agent and it can read a bounded, redacted diagnostics feed (console and network entries, errors first) without ever seeing raw replay storage:
+
+```text
+GET /api/session-replay/agent-context.json?id=<recordingId>&agent_access=<token>
+GET /api/session-replay/agent-diagnostics.json?id=<recordingId>&agent_access=<token>&kind=console|network|all
+GET /api/session-replay/agent-events.json?id=<recordingId>&agent_access=<token>
+```
+
+## Traffic and SEO
+
+Two more read-only data surfaces round out this tab:
+
+- **SEO metrics**, once a DataForSEO connection is configured — top-ranked keywords across your blog, and ranked keywords for one page by slug.
+- **First-party marketing dashboards** built from the same event stream everything else in Analytics uses — signups, template/feature clicks, referral sources, and viral coefficient. Analytics ships a worked example dashboard demonstrating this pattern that you can open directly or copy as a starting point for your own.
+
+## What's next
+
+- [**Dashboards, Analyses, and the Data Dictionary**](/docs/template-analytics-dashboards) — the other place you'll spend time day to day
+- [**Connecting and Extending Data Sources**](/docs/template-analytics-connectors) — connecting DataForSEO and the rest of your stack
+- [**Extending Analytics**](/docs/template-analytics-developers) — the monitoring/error/session schema and action reference
+- [**Analytics overview**](/docs/template-analytics) — back to the app summary

package/corpus/core/docs/content/template-analytics.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Analytics"
-description: "Ask analytics questions in plain English, get charts and dashboards back — an open-source replacement for Amplitude, Mixpanel, and Looker that connects your own warehouse and event sources."
+description: "Ask analytics questions in plain English and get charts, dashboards, and alerts back — an open-source alternative to Amplitude, Mixpanel, and Looker that also covers uptime monitoring, error tracking, and session replay, all on your own data."
 ---
 
 # Analytics
 
-Ask analytics questions in plain English, get charts and dashboards back. The agent connects to BigQuery, GA4, Amplitude, the built-in first-party event collector, HubSpot, Jira, and a dozen other sources, writes the query for you, validates it, and renders the answer as a chart, table, or saved dashboard panel.
+Ask analytics questions in plain English, get charts and dashboards back. The agent picks the right data source, writes and validates the query, and renders the answer as a chart, table, or saved dashboard panel. Analytics also covers uptime monitoring, error tracking, and session replay — the surfaces a team would otherwise split across three or four separate tools.
 
 <WireframeBlock id="doc-block-s1fqmy">
   <Screen
@@ -70,15 +70,13 @@ It's an open-source replacement for Amplitude, Mixpanel, and Looker — for team
 ## What you can do with it
 
 - **Ask data questions in plain English.** "What percent of signups last month converted to paid?" or "Show me weekly active users for the past 6 months." The agent picks the right source, writes the SQL, and renders the chart.
-- **Build reusable SQL dashboards** with filters, saved views, and parametric queries.
+- **Build reusable dashboards** — either SQL dashboards the agent writes, or point-and-click Explorer dashboards over your BigQuery schema — with filters, saved views, and sections.
 - **Run ad-hoc analyses** that cross-reference multiple data sources — saved as re-runnable investigations with the original question, instructions, and findings.
 - **Maintain a living data dictionary** of metrics, tables, and SQL recipes so the agent uses the right column names every time (no more guessed `is_closed` when it's actually `hs_is_closed`).
+- **Watch uptime and triage errors.** Add an HTTP uptime check with alerting, publish a public status page, and triage browser exceptions grouped into issues — see [Monitoring, Errors, and Session Replay](/docs/template-analytics-monitoring-and-sessions).
+- **Watch a real session play back.** Every recorded session captures the page, console, and network activity, replayable frame by frame with a Chrome-style Dev Tools panel.
 - **Share dashboards** with your team — private by default, shareable per-user or per-org with viewer / editor / admin roles.
-- **Connect to many sources** out of the box: BigQuery, GA4, Mixpanel, Amplitude, PostHog, HubSpot, Jira, Apollo, Pylon, Gong, Common Room, Twitter, plus app-specific SEO sources.
-- **Reuse workspace integrations** when a workspace has already connected and
-  granted a provider to Analytics. The shared integration stores provider
-  identity and credential refs; Analytics keeps app-specific source selection,
-  data dictionary entries, dashboard SQL, and analysis history.
+- **Connect your stack.** BigQuery, GA4, Amplitude, Mixpanel, PostHog, HubSpot, Stripe, Slack, Prometheus, Grafana, and a dozen more — see the full catalog in [Connecting and Extending Data Sources](/docs/template-analytics-connectors).
 
 ## Getting started
 
@@ -86,7 +84,7 @@ Live demo: [analytics.agent-native.com](https://analytics.agent-native.com).
 
 When you first open the app:
 
-1. Sign in with Google.
+1. Sign in with Google. A demo dashboard installs automatically so there's something to look at right away.
 2. Open the **Data Sources** page from the sidebar.
 3. Each source has a walkthrough — connect the ones you need (start with one, like BigQuery, GA4, Amplitude, or first-party tracking).
 4. Open a new chat with the agent and ask a question: "How many signups did we get last week?"
@@ -100,277 +98,37 @@ The first question is enough to confirm the connection works. From there, ask th
 - "Add a chart comparing revenue by plan to this dashboard."
 - "Reorder the panels on this dashboard so the MRR metric comes first."
 - "Analyze our closed-lost deals from Q1 and save the analysis."
-- "Re-run the churn analysis with this month's data."
 - "Document this metric in the data dictionary."
+- "Add an uptime check for our production API and alert Slack if it goes down."
+- "Show me today's open error issues, worst first."
 
 The agent always knows what you're looking at — current dashboard, filters, view — so you can say "this dashboard" or "that panel" without being explicit.
 
-## Three things to know
+## Surfaces at a glance
 
-The app has three primary surfaces you'll spend time in:
+Analytics is more than dashboards and the dictionary — here's everywhere you'll spend time:
 
-- **SQL Dashboards** — reusable panels with filters and saved views. Best for metrics you check regularly.
-- **Ad-hoc Analyses** — long-form investigations that pull from multiple sources, with re-run instructions saved alongside. Best for one-off questions you might want to revisit.
-- **Data Dictionary** — the canonical catalog of metrics, tables, columns, and SQL recipes. The agent consults it before writing any SQL, so it uses real warehouse column names and knows about caveats like "excludes internal emails".
-
-The dictionary is seeded by asking the agent: "import our dbt definitions" or "pull the metrics from our Notion handbook" and it does the work.
+- **[Dashboards, analyses, and the data dictionary](/docs/template-analytics-dashboards)** — reusable SQL/Explorer dashboards, one-off investigations, the shared metric vocabulary, plus scheduled email reports and alert rules.
+- **[Monitoring, errors, and session replay](/docs/template-analytics-monitoring-and-sessions)** — uptime checks with a public status page, Sentry-style error triage, full session recordings with a Dev Tools panel, and traffic/SEO reporting.
+- **[Data sources](/docs/template-analytics-connectors)** — every connected provider, reusable workspace integrations, and the escape hatches for anything a canned action doesn't cover.
+- **Admin home (`/agents`)** — a fleet feature-flag control plane, a dashboard usage audit, and connected-app database admin for organization owners — see [Extending Analytics](/docs/template-analytics-developers).
 
 ## For developers
 
-The rest of this doc is for anyone forking the Analytics template or extending it.
-
-### Quick start
-
-Create a new Analytics app from the CLI:
+Fork the Analytics template from the CLI:
 
 ```bash
 npx @agent-native/core@latest create my-analytics --standalone --template analytics
-cd my-analytics
-pnpm install
-pnpm dev
 ```
 
-The Analytics template's dev script pins `DATABASE_URL` to the local SQLite
-file at `./data/app.db`, so a production `DATABASE_URL` in `.env` will not be
-used during local development. To intentionally point local dev at another
-database, run `ANALYTICS_DATABASE_URL=<your dev database url> pnpm dev`.
-
-The CLI prints the local dev URL. Sign in with Google, then open the **Data Sources** page to connect BigQuery, GA4, first-party tracking, HubSpot, Jira, and the rest.
-
-### Key features
-
-**Ask questions, get charts.** The agent picks a data source, writes and validates SQL, then renders a chart, table, metric, or saved panel.
-
-**Dashboards and investigations.** Reusable dashboards keep SQL panels, filters, saved views, and sharing; ad-hoc analyses save longer findings with re-run instructions.
-
-**Living data dictionary.** Metric definitions, owners, source tables, and known caveats give the agent the real warehouse vocabulary before it writes queries.
-
-**Broad connector surface.** BigQuery, GA4, product analytics, CRM, support, community, GitHub/Jira, SEO, and first-party `/track` events all come through actions the agent can call.
-
-**Session replay agent handoff.** Session recordings stay private, but the session detail page can mint a temporary **Copy for agent** link. The two-hour `agent_access` URL lets an external agent read replay summaries, timelines, and bounded event details without exposing blob/provider URLs or making the recording public.
-
-Implementation note: use the shared core agent-access helpers
-(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
-`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
-URL contract. Keep replay chunk authorization, diagnostics payloads, and the
-session detail UI local to Analytics.
-
-### Working with the agent
-
-The agent always knows what you're looking at. The current screen state is injected into every message as a `<current-screen>` block — it contains the active view, the open dashboard or analysis, and any selected filters.
-
-The agent's system prompt gets an injected `<data-dictionary>` block with the approved metric entries for the active org. When you ask for a dashboard, the agent consults the dictionary first and uses the documented `table` / `columns` / `queryTemplate` verbatim — it does not guess column names.
-
-**Context it has automatically:**
-
-- **Current view** — `overview`, `adhoc` (with `dashboardId`), `analyses` (with `analysisId`), `data-dictionary`, `data-sources`, or `settings`.
-- **Active org** — scopes all queries and writes.
-- **Approved dictionary entries** — for the active workspace.
-
-**Dashboard edits.** The agent uses the `update-dashboard` action to edit dashboards. It supports two modes:
-
-- `ops` — JSON-Pointer patches for surgical edits (move a panel, replace one SQL string, remove a filter).
-- `config` — full replacement of the dashboard config.
-
-Every BigQuery panel's SQL is dry-run against the warehouse before the dashboard saves. If a column is wrong, the save is rejected with the BigQuery error — the agent fixes the SQL and retries instead of persisting broken panels.
-
-### Connecting data sources
-
-Open the **Data Sources** page (`/data-sources`) to connect providers. Each
-source exposes an env-key list, a walkthrough, and a **Test Connection** button.
-When Analytics is running in a workspace, `data-source-status` also reports
-granted reusable workspace connections for `appId=analytics` so the agent can
-ask for an app grant instead of another copy of the same provider key.
-For reusable providers such as Slack, HubSpot, Notion, and GitHub, the Data
-Sources UI shows the shared integration state directly: ready via workspace,
-needs grant, needs credentials, or local credentials.
-
-Reusable workspace integrations are the runtime direction for shared providers:
-the framework stores provider identity, account metadata, credential refs, and
-per-app grants once; Analytics stores data-source interpretation, source of
-truth choices, metric definitions, dashboards, and analyses.
-
-Credentials are stored via the framework's settings/env layer — no secrets in git. Production requires:
-
-| Variable                                 | Purpose                                                 |
-| ---------------------------------------- | ------------------------------------------------------- |
-| `DATABASE_URL`                           | Persistent SQL connection URL                           |
-| `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL` | Auth                                                    |
-| `GOOGLE_SIGN_IN_CLIENT_ID` / `_SECRET`   | Preferred Google sign-in client (OAuth 2.0)             |
-| `GOOGLE_CLIENT_ID` / `_SECRET`           | Legacy sign-in fallback / Google API integration client |
-| `BIGQUERY_PROJECT_ID`                    | BigQuery project                                        |
-| `GOOGLE_APPLICATION_CREDENTIALS_JSON`    | BigQuery service-account JSON                           |
-| `ANTHROPIC_API_KEY`                      | Agent chat                                              |
-
-Provider-specific keys (HubSpot, Jira, Gong, Pylon, etc.) are documented in each source's walkthrough on the Data Sources page. If you add a new action that needs an API key, it appears as a new source on that page via the template's onboarding registration.
-
-Note: the BigQuery OAuth credential for Google sign-in is a **separate**
-credential from the BigQuery service account JSON. Create the sign-in client at
-GCP Console → APIs & Services → Credentials → OAuth client ID, and prefer the
-`GOOGLE_SIGN_IN_CLIENT_ID` / `GOOGLE_SIGN_IN_CLIENT_SECRET` env names so this
-low-scope login client stays separate from Google API integration clients.
-
-### Data model
-
-Core tables (see `templates/analytics/server/db/schema.ts`):
-
-<DataModel
-  id="doc-block-unvmkd"
-  title="Analytics data model"
-  summary={
-    "Dashboards and analyses are the resources; views, shares, and a query cache hang off them. Org tables come from @agent-native/core/org."
-  }
-  entities={[
-    {
-      id: "dashboards",
-      name: "dashboards",
-      note: "Explorer and SQL dashboards",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "kind",
-          type: "text",
-          note: '"explorer" or "sql"',
-        },
-        {
-          name: "config",
-          type: "text",
-          note: "JSON matching SqlDashboardConfig",
-        },
-      ],
-    },
-    {
-      id: "dashboard_views",
-      name: "dashboard_views",
-      note: "Saved filter presets per dashboard",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "dashboard_id",
-          type: "text",
-          fk: "dashboards.id",
-        },
-      ],
-    },
-    {
-      id: "analyses",
-      name: "analyses",
-      note: "Re-runnable ad-hoc investigations",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "question",
-          type: "text",
-        },
-        {
-          name: "instructions",
-          type: "text",
-          note: "Re-run steps",
-        },
-        {
-          name: "dataSources",
-          type: "text",
-          note: "Sources touched",
-        },
-        {
-          name: "resultMarkdown",
-          type: "text",
-        },
-        {
-          name: "resultData",
-          type: "text",
-          nullable: true,
-        },
-      ],
-    },
-    {
-      id: "bigquery_cache",
-      name: "bigquery_cache",
-      note: "Result cache keyed by SQL hash",
-      fields: [
-        {
-          name: "sql_hash",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "bytes_processed",
-          type: "integer",
-        },
-      ],
-    },
-  ]}
-  relations={[
-    {
-      from: "dashboards",
-      to: "dashboard_views",
-      kind: "1-n",
-      label: "saved views",
-    },
-  ]}
-/>
-
-Plus per-resource share tables (`dashboard_shares`, `analysis_shares`) and the org tables (`organizations`, `org_members`, `org_invitations`) provided by `@agent-native/core/org`. The data dictionary lives in the framework's `settings` table under scoped keys.
-
-- **`dashboards`** — both Explorer and SQL dashboards. `kind` is `"explorer"` or `"sql"`; `config` is a JSON blob matching `SqlDashboardConfig`.
-- **`dashboard_shares`** — per-resource share grants (principal, role).
-- **`dashboard_views`** — saved filter presets per dashboard.
-- **`analyses`** — ad-hoc investigations with `question`, `instructions`, `dataSources`, `resultMarkdown`, and optional `resultData`.
-- **`analysis_shares`** — per-resource share grants for analyses.
-- **`bigquery_cache`** — query result cache keyed by SQL hash with bytes-processed accounting.
-
-Plus the org tables (`organizations`, `org_members`, `org_invitations`) provided by `@agent-native/core/org`.
-
-The data dictionary lives in the framework's `settings` table under scoped keys; see the `list-data-dictionary` and `save-data-dictionary-entry` actions for the full shape.
-
-### Customizing it
-
-The Analytics template is meant to be forked and extended. Everything lives in `templates/analytics/`:
-
-- **`AGENTS.md`** — the agent's top-level guide. Documents views, actions, and workflows.
-- **`actions/`** — every agent-callable operation. Add a new file to add a new action. Notable ones:
-  - `update-dashboard.ts` — dashboard edits (ops + full-replace)
-  - `save-analysis.ts` / `list-analyses.ts` — ad-hoc analyses
-  - `save-data-dictionary-entry.ts` / `list-data-dictionary.ts` — dictionary
-  - `bigquery.ts` — raw BigQuery execution
-  - `view-screen.ts` / `navigate.ts` — context awareness
-- **`app/routes/`** — file-based routes. Each route is a thin wrapper around a page in `app/pages/`.
-- **`app/pages/adhoc/sql-dashboard/`** — the SQL dashboard renderer, panel editor, filter bar, saved views.
-- **`app/pages/analyses/`** — analyses list and detail view.
-- **`app/pages/DataSources.tsx`** — the data-source onboarding UI.
-- **`app/pages/DataDictionary.tsx`** — the dictionary browser and editor.
-- **`.agents/skills/`** — pattern guides the agent reads on demand:
-  - `dashboard-management` — storage, scope resolution, dashboard config shape
-  - `data-querying` — which script to reach for, filtering patterns
-  - `adhoc-analysis` — workflow for cross-source investigations
-  - `data-querying`, `real-time-sync`, `frontend-design`, `storing-data`, `self-modifying-code`
-- **`.builder/skills/<provider>/SKILL.md`** — provider-specific gotchas (BigQuery, HubSpot, Jira, GA4, etc.). Read before querying; update when you learn something new.
-- **`server/db/schema.ts`** — Drizzle schema for dashboards, shares, views, analyses, BigQuery cache.
-- **`server/lib/dashboards-store.ts`** — dashboard read/write with scope resolution and legacy KV migration.
-- **`server/lib/bigquery.ts`** — BigQuery client, dry-run validator, cache logic.
-
-To add a new data source, drop a script in `actions/` that calls the provider and returns results via the `output()` helper. It becomes available to the agent immediately and can be used inside dashboard panels (if you expose the result via a server handler).
-
-To add a new chart type, extend the `ChartType` union in `app/pages/adhoc/sql-dashboard/types.ts`, handle it in `SqlChartCard.tsx`, and the agent can use it in any panel.
-
-For the broader pattern on extending templates, see the [Skills guide](/docs/skills-guide) and [Actions](/docs/actions).
+See [Getting Started](/docs/getting-started) for the rest of the setup (installing dependencies, running the dev server, environment variables), and [Extending Analytics](/docs/template-analytics-developers) for the data model, action reference, and customization points.
 
 ## What's next
 
+- [**Dashboards, Analyses, and the Data Dictionary**](/docs/template-analytics-dashboards) — the day-to-day surfaces
+- [**Monitoring, Errors, and Session Replay**](/docs/template-analytics-monitoring-and-sessions) — uptime, error triage, and replay
+- [**Connecting and Extending Data Sources**](/docs/template-analytics-connectors) — the full connector catalog and the escape hatches
+- [**Extending Analytics**](/docs/template-analytics-developers) — data model, actions, and customizing the template
 - [**Templates**](/docs/cloneable-saas) — the clone-and-own model, and every other domain template to start from
 - [**Getting Started**](/docs/getting-started) — the framework fundamentals: actions, application state, and live sync
-- [**Actions**](/docs/actions) — the action system dashboards, analyses, and the dictionary are built on
 - [**Sharing**](/docs/sharing) — the share-grant model dashboards and analyses build on
-- [**Automations**](/docs/automations) — schedule recurring dashboard refreshes or alerts