@agent-native/core 0.122.4 → 0.123.1

package/corpus/core/docs/content/skills-guide.mdx

@@ -79,29 +79,51 @@ Every skill's frontmatter `name` and `description` are always injected into the
 
 </Diagram>
 
+### Reference sub-files {#reference-subfiles}
+
+A skill directory can hold more than `SKILL.md` — extra Markdown, text, or JSON files under a `references/` (or similar) subfolder that the main file points to instead of inlining everything. The agent always sees the list of extra files in a skill's directory. Text sub-files under a size cap (64KB per file, 256KB total per skill) are also inlined and independently readable through `docs-search`, at a `skill-<name>--<subpath>` slug — a `references/api.md` file inside `my-skill` resolves as `skill-my-skill--references-api`. Sub-files over the cap, or non-text files (images, scripts), are still listed but not inlined; read them from the filesystem directly in Code mode.
+
+```text
+.agents/skills/my-skill/
+  SKILL.md
+  references/
+    api.md          # inlined — readable via docs-search as skill-my-skill--references-api
+    diagram.png     # listed only — not readable via docs-search
+```
+
 ## Framework skills {#framework-skills}
 
 These are the skills bundled with the **default template**. The exact set available in any given app depends on the template you scaffolded from — check that template's `.agents/skills/` directory for what it actually ships.
 
-| Skill                  | When to use                                                        |
-| ---------------------- | ------------------------------------------------------------------ |
-| `storing-data`         | Adding data models, reading/writing config or state                |
-| `real-time-sync`       | Wiring polling sync, debugging UI not updating                     |
-| `delegate-to-agent`    | Delegating AI work from UI or actions to the agent                 |
-| `actions`              | Creating or running agent actions                                  |
-| `self-modifying-code`  | Editing app source, components, or styles                          |
-| `create-skill`         | Adding new skills for the agent                                    |
-| `capture-learnings`    | Recording corrections and patterns                                 |
-| `frontend-design`      | Building or styling any web UI, components, or pages               |
-| `adding-a-feature`     | The four-area checklist: UI, actions, skills, app-state            |
-| `internationalization` | Updating localized UI copy, language catalogs, and RTL-safe styles |
-| `shadcn-ui`            | Using shadcn/ui primitives and components                          |
-| `security`             | Auth, access control, and secret handling                          |
-| `real-time-collab`     | Multi-user collaborative editing                                   |
-| `agent-engines`        | Swapping or configuring the underlying agent engine                |
-| `notifications`        | In-app and push notification patterns                              |
-| `progress`             | Tracking and surfacing background task progress                    |
-| `inline-embeds`        | Embedding apps or iframes inside the agent chat                    |
+| Skill                      | When to use                                                              |
+| -------------------------- | ------------------------------------------------------------------------ |
+| `storing-data`             | Adding data models, reading/writing config or state                      |
+| `real-time-sync`           | Wiring polling sync, debugging UI not updating                           |
+| `delegate-to-agent`        | Delegating AI work from UI or actions to the agent                       |
+| `actions`                  | Creating or running agent actions                                        |
+| `self-modifying-code`      | Editing app source, components, or styles                                |
+| `create-skill`             | Adding new skills for the agent                                          |
+| `capture-learnings`        | Recording corrections and patterns                                       |
+| `frontend-design`          | Building or styling any web UI, components, or pages                     |
+| `adding-a-feature`         | The four-area checklist: UI, actions, skills, app-state                  |
+| `internationalization`     | Updating localized UI copy, language catalogs, and RTL-safe styles       |
+| `shadcn-ui`                | Using shadcn/ui primitives and components                                |
+| `security`                 | Auth, access control, and secret handling                                |
+| `real-time-collab`         | Multi-user collaborative editing                                         |
+| `agent-engines`            | Swapping or configuring the underlying agent engine                      |
+| `notifications`            | In-app and push notification patterns                                    |
+| `progress`                 | Tracking and surfacing background task progress                          |
+| `inline-embeds`            | Embedding apps or iframes inside the agent chat                          |
+| `agent-native-docs`        | Finding version-matched framework docs and source in `node_modules`      |
+| `agent-native-toolkit`     | Ownership rules for shared workspace UI (chrome, settings, nav, sharing) |
+| `app-branding`             | Renaming or rebranding the app consistently across every surface         |
+| `app-permissions`          | Enabling browser permissions (camera, mic, geolocation, etc.)            |
+| `customizing-agent-native` | Configuring, composing, or ejecting framework features into app code     |
+| `feature-flags`            | Declaring, evaluating, and removing framework feature flags              |
+| `integration-webhooks`     | Handling messaging integration webhooks on serverless hosts              |
+| `onboarding`               | Registering setup steps for the sidebar setup checklist                  |
+| `secrets`                  | Registering API keys/credentials for the settings UI and onboarding      |
+| `upgrade-agent-native`     | Updating `@agent-native/core` or fixing a broken upgrade                 |
 
 `context-awareness` and `a2a-protocol` are framework-level skills available in the `.agents/skills/` directory at the repo root — see each template's own `.agents/skills/` for what it inherits.
 
@@ -210,6 +232,27 @@ scope: dev
 
 When `scope` is absent (or set to an unrecognized value) it defaults to `both`, so every existing skill keeps loading at runtime — this field is fully backward compatible. A `scope: dev` skill is invisible to the runtime agent everywhere: it is excluded from the skills block injected into the system prompt and from `docs-search` results.
 
+### Hiding a skill from the `/` picker {#user-invocable}
+
+A separate `user-invocable` frontmatter field controls whether a skill shows up in the `/`-command picker — independent of `scope`, which controls whether the runtime agent loads the skill at all.
+
+```markdown
+---
+name: learn
+description: >-
+  Review the conversation and save structured memories for future sessions.
+user-invocable: true
+---
+```
+
+| `user-invocable`   | Appears in the `/` picker? | Still loaded and usable by the agent?                     |
+| ------------------ | -------------------------- | --------------------------------------------------------- |
+| _(unset, default)_ | Yes                        | Yes                                                       |
+| `true`             | Yes                        | Yes                                                       |
+| `false`            | No                         | Yes — the agent can still invoke it on its own initiative |
+
+Use `user-invocable: false` for a skill that should stay fully loaded and available to the agent, but isn't something a user should type `/skill-name` to trigger directly.
+
 ### Exposing a dev-only skill to your coding agent {#dev-only-skills}
 
 The agent-native runtime reads skills from `.agents/skills/`. Claude Code reads skills from `.claude/skills/` independently. To make a skill available to your coding agent but hidden from the runtime agent:

package/corpus/core/docs/content/syncing-template-changes.mdx

@@ -157,3 +157,12 @@ It diffs your app against its baseline so only your own changes are candidates,
 | `agent-native eject`         | a framework component into app-owned source, with provenance   |
 
 `upgrade` and `template sync` are complementary and safe to run together. `eject` is the opposite move — it takes ownership of a file deliberately, and ejected files are tracked separately in `agent-native.ejections.json`.
+
+## What's next
+
+- [**Creating Templates**](/docs/creating-templates) — how `agent-native
+create` scaffolds a template in the first place, and the provenance this
+  command later syncs against.
+- [**Package Lifecycle**](/docs/package-lifecycle) — `agent-native eject` and
+  `agent-native package`, the other half of taking ownership of
+  framework-provided code.

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

@@ -0,0 +1,75 @@
+---
+title: "Analytics: Connecting and Extending Data Sources"
+description: "The full data-source catalog for Analytics, reusable workspace integrations, and the provider-API and data-program escape hatches for anything a canned action doesn't cover."
+---
+
+# Connecting and Extending Data Sources
+
+This page lists every data source Analytics connects to today, and the escape hatches available once a question needs more than a canned action provides. Anyone connecting a new source can follow the first half; the escape-hatch sections get more technical.
+
+## The full source catalog
+
+Open the **Data Sources** page (`/data-sources`) from the sidebar — every source below gets a walkthrough and a **Test Connection** button there. Nothing here needs code; connect credentials or link a workspace integration and ask the agent a question.
+
+| Source                        | Category           | What you need                               |
+| ----------------------------- | ------------------ | ------------------------------------------- |
+| First-party events (built-in) | Warehouse          | Nothing — always on                         |
+| BigQuery                      | Warehouse          | Google service-account JSON + project ID    |
+| Google Analytics (GA4)        | Product analytics  | Google service-account JSON + property ID   |
+| Amplitude                     | Product analytics  | API key + secret key                        |
+| Mixpanel                      | Product analytics  | Project ID + service account                |
+| PostHog                       | Product analytics  | API key + project ID                        |
+| PostgreSQL                    | Warehouse          | Connection URL                              |
+| Prometheus                    | Observability      | Endpoint URL (+ optional basic/bearer auth) |
+| Grafana                       | Observability      | URL + API token                             |
+| Stripe                        | Billing            | Secret key                                  |
+| HubSpot                       | CRM                | Private app token                           |
+| Gong                          | Sales calls        | Access key + secret                         |
+| Apollo                        | Sales intelligence | API key                                     |
+| Pylon                         | Support            | API key                                     |
+| Clay                          | GTM enrichment     | Public API key                              |
+| Slack                         | Community/comms    | Bot token                                   |
+| Notion                        | Docs               | API key                                     |
+| Common Room                   | Community          | API token                                   |
+| X / Twitter                   | Social             | Bearer token                                |
+| GitHub                        | Dev                | Access token                                |
+| Jira                          | Dev/support        | Base URL + email + API token                |
+| Sentry                        | Errors             | Auth token                                  |
+| DataForSEO                    | SEO                | Login + password                            |
+
+Each row's credentials are stored through the framework's settings/env layer — never in git. Adding a new action that needs an API key registers a new row on this page automatically through the template's onboarding registration; see [Extending Analytics](/docs/template-analytics-developers) for how.
+
+## Reusable workspace integrations vs. per-app credentials
+
+If Analytics is running inside a multi-app workspace, some providers (Slack, HubSpot, Notion, GitHub, and others) can be connected once at the workspace level and **granted** to Analytics instead of configuring another copy of the same key. The Data Sources page shows the shared state directly: ready via workspace, needs a grant, needs credentials, or local credentials only.
+
+The split of responsibility: the shared workspace connection stores provider identity, account metadata, and credential references once; Analytics keeps its own app-specific interpretation — which sources are enabled, data-dictionary entries, dashboard SQL, and analysis history. See [Integrations Directory](/docs/integrations) for the workspace-connection model in general.
+
+## The provider-API escape hatch
+
+Every source above ships as a canned action for the common case (list HubSpot deals, query a BigQuery table, and so on). When a question needs an endpoint, filter, or pagination mode a canned action doesn't expose, the agent can call the same providers directly:
+
+- **provider-api-catalog** — lists supported providers, credential key names, and docs/spec links (no secrets returned).
+- **provider-api-docs** — inspects a provider's registered docs/spec when the exact payload shape is uncertain.
+- **provider-api-request** — makes the actual authenticated HTTP call, constrained to the provider's own hosts, with credentials injected server-side. For large result sets it can stage the response into a scratch dataset instead of returning it raw, and fetch every page server-side in one call.
+- **query-staged-dataset** — filters, aggregates, and projects over a staged dataset without pulling every row into context.
+
+This is a framework-wide pattern, not an Analytics-specific one — see [Integrations Directory](/docs/integrations) for the full shape.
+
+## Data programs: turning a one-off pull into a live panel
+
+Sometimes a question that provider-api-request can answer once needs to become something other people see, refreshed on its own — a cohort defined by an arbitrary CRM property filter, or a join across two providers no canned action anticipates. That's a **data program**: a small, named, agent-authored script that fetches/joins/aggregates data and is bound to a dashboard panel like any other source.
+
+Analytics ships a worked example of this exact pattern — a "Risk Meeting" dashboard that joins a configurable HubSpot deal cohort against Pylon account sentiment by company domain, entirely through two saved data programs. See [Data Programs](/docs/data-programs) for the full authoring contract, caching model, and that worked example in detail.
+
+## Public write keys for first-party tracking
+
+If you want another one of your own apps (or a marketing site) to send events into this Analytics instance's first-party event store, generate a **public write key**. It's intentionally write-only — it can create events for your account but grants no read or admin access — and gets dropped into the emitting app's `VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEY` environment variable. This is unrelated to sharing a dashboard or embedding a chart; it's purely about getting more first-party data flowing in.
+
+## What's next
+
+- [**Dashboards, Analyses, and the Data Dictionary**](/docs/template-analytics-dashboards) — what you build once a source is connected
+- [**Monitoring, Errors, and Session Replay**](/docs/template-analytics-monitoring-and-sessions) — DataForSEO-powered traffic/SEO reporting
+- [**Extending Analytics**](/docs/template-analytics-developers) — adding a brand-new data source as a template extension
+- [**Integrations Directory**](/docs/integrations) — the framework-wide connection model
+- [**Analytics overview**](/docs/template-analytics) — back to the app summary

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

@@ -0,0 +1,106 @@
+---
+title: "Analytics: Dashboards, Analyses, and the Data Dictionary"
+description: "How SQL and Explorer dashboards, ad-hoc analyses, and the data dictionary work in Analytics, plus scheduling email reports and alert rules."
+---
+
+# Dashboards, Analyses, and the Data Dictionary
+
+This page covers the surfaces you'll use most in [Analytics](/docs/template-analytics): building dashboards, running one-off investigations, and keeping the agent's vocabulary of metrics accurate. It's written for anyone using the app, not just developers.
+
+## SQL dashboards vs. Explorer dashboards
+
+Analytics has two kinds of dashboard, and they're built differently:
+
+| Kind                   | How it's built                                                                                                                                                 | Best for                                                                                                          |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| **SQL dashboard**      | You (or the agent) write the panel queries in plain English, and the agent turns them into SQL. Supports filters, saved views, sections, and every chart type. | Recurring metrics you check often, and anything cross-source (BigQuery + HubSpot + first-party in one dashboard). |
+| **Explorer dashboard** | You click through your BigQuery tables and columns — pick a metric, a group-by, a filter, and a chart type — with no SQL required.                             | Quick, self-serve exploration of a warehouse table you already know, without waiting on a query.                  |
+
+Both are dashboards in the same list, shareable the same way. Ask the agent to build one, or open either editor directly from the sidebar.
+
+<Diagram id="doc-block-analytics1" title="A dashboard question, start to finish" summary={"The agent checks the data dictionary before writing SQL, then every BigQuery panel is dry-run validated against the warehouse before the dashboard saves."}>
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-node">
+    "Build a dashboard for<br />weekly signups by plan"
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">Data dictionary</span
+    ><small class="diagram-muted">real table + column names</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">Agent writes panel SQL</div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-pill ok">Dry-run validate</div>
+    <small class="diagram-muted">rejects bad columns before saving</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">
+    Dashboard saved<br /><small class="diagram-muted"
+      >shareable, schedulable</small
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-flow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  align-items: center;
+}
+.diagram-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+.diagram-flow .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Ad-hoc analyses
+
+Not every question deserves a permanent dashboard panel. For a one-off investigation — "why did churn spike in March," "which accounts are at risk this quarter" — ask the agent to dig in across whatever sources are relevant. Ask it to save the analysis and it keeps the original question, the sources it used, its findings in full, and step-by-step instructions for re-running it later with fresh data. Come back weeks later and say "re-run the churn analysis with this month's data" instead of re-explaining the whole investigation.
+
+## The data dictionary
+
+The data dictionary is the app's shared vocabulary of metrics, tables, columns, and SQL recipes. The agent consults it before writing any dashboard SQL, so it uses your warehouse's real column names and knows about caveats like "excludes internal emails" or "this table dedupes at the account level." Without a dictionary entry, the agent has to guess or ask — with one, it gets the query right the first time, every time.
+
+Seed it by asking the agent directly: "import our dbt definitions" or "pull the metric definitions from our Notion handbook," and it does the work. You can also document a metric yourself after the fact: "document this metric in the data dictionary" on any panel or chart the agent just built.
+
+## Sharing dashboards and analyses
+
+Dashboards and analyses are private by default. Share one with a teammate or your whole organization as a **viewer**, **editor**, or **admin** — the same sharing model used across every Agent-Native app. See [Sharing & Privacy](/docs/sharing) for the full model.
+
+Deleting a dashboard archives it by default (recoverable) rather than deleting it outright — look for "permanently delete" if you really mean it.
+
+## Dashboard email reports and alert rules
+
+Two ways to have Analytics come to you instead of you going to it:
+
+- **Scheduled email reports.** Subscribe a dashboard to a daily email snapshot — charts render as images, tables and metrics render as real email content. Reports go to up to **five recipients** (use a mailing-list address for a bigger audience); pick a time of day and timezone. If a panel fails to load, the report says so rather than silently sending an incomplete dashboard.
+- **Alert rules.** Define a condition over first-party events — an event count or a distinct-count threshold within a time window — and Analytics notifies you (inbox, email, Slack, or a webhook) when it fires, then waits out a cooldown period before alerting again for the same condition.
+
+Ask the agent for either directly: "email me this dashboard every morning at 9am" or "alert the team in Slack if signup errors exceed 50 in 10 minutes."
+
+## What's next
+
+- [**Monitoring, Errors, and Session Replay**](/docs/template-analytics-monitoring-and-sessions) — the other place Analytics watches your product for you
+- [**Connecting and Extending Data Sources**](/docs/template-analytics-connectors) — what's available to build dashboards and analyses from
+- [**Extending Analytics**](/docs/template-analytics-developers) — the data model and action reference behind this page
+- [**Analytics overview**](/docs/template-analytics) — back to the app summary

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

@@ -0,0 +1,287 @@
+---
+title: "Analytics: Extending the Template"
+description: "The data model, action reference, and customization points for forking and extending the Analytics template — dashboards, monitoring, errors, session replay, and the /agents admin surface."
+---
+
+# Extending Analytics
+
+This page is for anyone forking the Analytics template or building on it directly: the data model, the action surface, and the places meant to be extended.
+
+## Quick start
+
+Create a new Analytics app 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, and the rest — see [Connecting and Extending Data Sources](/docs/template-analytics-connectors) for the full catalog and required env vars.
+
+## Data model
+
+All data lives in SQL via Drizzle. Dashboards and analyses are the primary resources; monitoring, errors, and session replay each own their schema file (`schema-monitoring.ts`, `schema-errors.ts`) but join the same Drizzle namespace via `schema.ts`.
+
+<DataModel
+  id="doc-block-analytics5"
+  title="Analytics data model"
+  summary={
+    "Dashboards and analyses are the resources users share; monitoring, errors, and session replay each add their own owner-scoped tables alongside them."
+  }
+  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",
+        },
+        { name: "archived_at", type: "text", nullable: true },
+      ],
+    },
+    {
+      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: "result_markdown", type: "text" },
+      ],
+    },
+    {
+      id: "monitors",
+      name: "monitors",
+      note: "One uptime check per row",
+      fields: [
+        { name: "id", type: "text", pk: true },
+        { name: "url", type: "text" },
+        { name: "interval_seconds", type: "integer" },
+        {
+          name: "last_status",
+          type: "text",
+          note: "up | down | degraded | error",
+        },
+      ],
+    },
+    {
+      id: "error_issues",
+      name: "error_issues",
+      note: "Grouped browser exceptions by fingerprint",
+      fields: [
+        { name: "id", type: "text", pk: true },
+        { name: "fingerprint", type: "text" },
+        { name: "title", type: "text" },
+        {
+          name: "status",
+          type: "text",
+          note: "unresolved | resolved | ignored",
+        },
+        {
+          name: "last_session_recording_id",
+          type: "text",
+          nullable: true,
+          fk: "session_recordings.id",
+        },
+      ],
+    },
+    {
+      id: "session_recordings",
+      name: "session_recordings",
+      note: "Session replay summaries; chunks live separately",
+      fields: [
+        { name: "id", type: "text", pk: true },
+        { name: "session_id", type: "text" },
+        { name: "duration_ms", type: "integer", nullable: true },
+        { name: "error_count", type: "integer" },
+      ],
+    },
+    {
+      id: "bigquery_cache",
+      name: "bigquery_cache",
+      note: "Result cache keyed by SQL hash",
+      fields: [
+        { name: "key", type: "text", pk: true },
+        { name: "bytes_processed", type: "integer" },
+      ],
+    },
+  ]}
+  relations={[
+    {
+      from: "dashboards",
+      to: "dashboard_views",
+      kind: "1-n",
+      label: "saved views",
+    },
+    {
+      from: "session_recordings",
+      to: "error_issues",
+      kind: "1-n",
+      label: "linked replay",
+    },
+  ]}
+/>
+
+Additional tables not pictured above, grouped by feature:
+
+- **Dashboards** — `dashboard_shares`, `dashboard_revisions` (bounded undo history), `dashboard_report_subscriptions` (scheduled email reports, capped at 5 `recipients`).
+- **Analyses** — `analysis_shares`, `analysis_revisions`.
+- **First-party events** — `analytics_events` (the `/track` event store), `analytics_public_keys` (write-only ingestion keys), `first_party_analytics_cache`.
+- **Alerts** — `analytics_alert_rules`, `analytics_alert_incidents`.
+- **Monitoring** — `monitor_check_results` (bounded probe history), `monitor_incidents`, `status_pages` (public `/status/<slug>` pages).
+- **Errors** — `error_issue_shares`, `error_events` (individual occurrences, pruned to a bounded retention per issue).
+- **Session replay** — `session_recording_shares`, `session_replay_chunks` (raw rrweb data — never read directly; always through scoped server helpers), `session_replay_ingests`.
+- **Admin** — `analytics_db_admin_connections` (org-scoped registry of connected external app databases for the `/agents?view=database` admin tool).
+
+Plus the org tables (`organizations`, `org_members`, `org_invitations`) from `@agent-native/core/org`. The data dictionary itself lives in the framework's `settings` table under scoped keys — see `list-data-dictionary` / `save-data-dictionary-entry` for the shape.
+
+## Key actions by group
+
+Every operation is a TypeScript file in `templates/analytics/actions/`, auto-mounted at `POST /_agent-native/actions/:name`.
+
+**Dashboards & panels** — `update-dashboard` (new/full-config saves), `mutate-dashboard` (existing-dashboard edits via a small typed script API), `compose-dashboard` (build a large first-party dashboard from a metric-key catalog in one atomic call), `get-sql-dashboard`, `list-sql-dashboards`, `archive-dashboard`, `delete-sql-dashboard` / `delete-explorer-dashboard`, `reorder-dashboard-panels`, `install-dashboard-template` / `list-dashboard-templates`.
+
+**Analyses** — `save-analysis`, `get-analysis`, `list-analyses`, `rename-analysis`, `hide-analysis`, `list-analysis-revisions` / `restore-analysis-revision`.
+
+**Data dictionary** — `save-data-dictionary-entry`, `list-data-dictionary`, `delete-data-dictionary-entry`, `search-analytics-query-catalog` (search existing saved queries before writing a new one).
+
+**Reports & alerts** — `save-dashboard-report-subscription`, `list-dashboard-report-subscriptions`, `send-dashboard-report-now`, `delete-dashboard-report-subscription`, `save-analytics-alert-rule`, `list-analytics-alert-rules`, `run-analytics-alerts`, `delete-analytics-alert-rule`.
+
+**Monitoring** — `save-monitor`, `list-monitors`, `get-monitor`, `get-monitor-stats`, `run-monitor-check`, `delete-monitor`, plus `save-status-page` / `get-public-status-page` / `add-status-page-monitor` for public status pages.
+
+**Errors** — `list-error-issues`, `get-error-issue`, `resolve-error-issue`, `match-error-issues`, `capture-test-error`.
+
+**Session replay** — `list-session-recordings`, `get-session-replay-summary`, `get-session-replay-timeline`, `get-session-replay-events`, `create-session-replay-agent-link` (mints the two-hour tokenized agent link).
+
+**Data programs** — this app registers `list-data-programs` and `get-data-program`; the mutating `save-data-program` / `preview-data-program` / `run-data-program` / `delete-data-program` actions come from the shared `@agent-native/core` data-programs primitive — see [Data Programs](/docs/data-programs).
+
+**Provider escape hatch & sources** — `provider-api-catalog`, `provider-api-docs`, `provider-api-request`, `query-staged-dataset`, plus one action per built-in source (`bigquery`, `hubspot-deals`, `gong-calls`, `prometheus`, `grafana`, `stripe`, `slack-messages`, and so on) and `data-source-status` to check what's configured.
+
+**Traffic & SEO** — `open-traffic-dashboard`, `seo-top-keywords`, `seo-page-keywords`, `seo-blog-pages` (all backed by DataForSEO; the target domain is a placeholder in `server/lib/dataforseo.ts` — swap it for your own before relying on these).
+
+**Public keys** — `create-analytics-public-key`, `list-analytics-public-keys`, `revoke-analytics-public-key` (write-only first-party ingestion keys — see [Connecting and Extending Data Sources](/docs/template-analytics-connectors)). There's also an unauthenticated `/chart?panel=<base64-encoded-panel-config>` route that renders a single chart standalone for embedding on an external page.
+
+**Context & admin** — `view-screen` / `navigate` for agent context awareness, `list-workspace-feature-flags` / `set-workspace-feature-flag`, `list-dashboard-usage-stats`, `list-db-admin-connections` / `save-db-admin-connection`.
+
+## The /agents admin surface
+
+`/agents` is the Analytics home for admin-only tooling, split by `?view=`:
+
+- **`?view=flags`** — the fleet feature-flag control plane. Call `list-workspace-feature-flags` before changing anything; preserve `unsupported` / `unreachable` / `forbidden` / `unknown-legacy` as their own states rather than collapsing them to "off." Use `set-workspace-feature-flag` for app-qualified changes.
+- **`?view=dashboards`** — the dashboard usage audit: created/modified dates, owners, views, edits, and cleanup candidates across every dashboard, via `list-dashboard-usage-stats`.
+- **`?view=database`** — connected-app database admin. Organization owners/admins can register another agent-native app's database (`save-db-admin-connection`) and browse its tables, edit rows, and run inspection SQL through the shared database admin tool — scoped to the connected target app's database, not broad access to Analytics' own data.
+
+Keep future admin additions inside this route instead of adding more top-level sidebar tabs.
+
+## Adding a new data source or chart type
+
+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 through a server handler. Register its credential keys in `server/lib/credential-keys.ts` so it appears automatically on the Data Sources page.
+
+To add a new chart type, extend the `ChartType` union in `app/pages/adhoc/sql-dashboard/types.ts` and handle it in `SqlChartCard.tsx` — the agent can use it in any panel from then on.
+
+<FileTree
+  id="doc-block-analytics6"
+  title="Where things live"
+  entries={[
+    {
+      path: "templates/analytics/AGENTS.md",
+      note: "the agent's top-level guide",
+    },
+    {
+      path: "templates/analytics/actions/update-dashboard.ts",
+      note: "full-config dashboard saves",
+    },
+    {
+      path: "templates/analytics/actions/mutate-dashboard.ts",
+      note: "typed script API for existing-dashboard edits",
+    },
+    {
+      path: "templates/analytics/actions/compose-dashboard.ts",
+      note: "build a large first-party dashboard from metric keys",
+    },
+    {
+      path: "templates/analytics/server/db/schema.ts",
+      note: "dashboards, analyses, alerts, public keys, first-party events",
+    },
+    {
+      path: "templates/analytics/server/db/schema-monitoring.ts",
+      note: "monitors, incidents, status pages",
+    },
+    {
+      path: "templates/analytics/server/db/schema-errors.ts",
+      note: "error_issues, error_events",
+    },
+    {
+      path: "templates/analytics/server/lib/dashboards-store.ts",
+      note: "dashboard read/write, scope resolution, legacy KV migration",
+    },
+    {
+      path: "templates/analytics/server/lib/uptime-monitors.ts",
+      note: "uptime check + alerting logic",
+    },
+    {
+      path: "templates/analytics/server/lib/error-capture.ts",
+      note: "exception ingest and fingerprint grouping",
+    },
+    {
+      path: "templates/analytics/server/lib/credential-keys.ts",
+      note: "the full connected-source catalog",
+    },
+    {
+      path: "templates/analytics/app/pages/adhoc/sql-dashboard/",
+      note: "SQL dashboard renderer, panel editor, filter bar",
+    },
+    {
+      path: "templates/analytics/app/pages/adhoc/explorer/",
+      note: "the point-and-click Explorer dashboard builder",
+    },
+    {
+      path: "templates/analytics/app/pages/monitoring/",
+      note: "UptimePanel, ErrorsPanel, status page editor",
+    },
+    {
+      path: "templates/analytics/.agents/skills/",
+      note: "dashboard-management, monitoring, session-replay, data-programs, provider-api, and more",
+    },
+  ]}
+/>
+
+## Customizing it
+
+Ask the agent for shipped behavior first:
+
+- "Add an uptime check for our staging environment."
+- "Build a dashboard that joins our HubSpot pipeline with Stripe revenue."
+- "Add a data program that cohorts users by an arbitrary product event property."
+- "Schedule this dashboard as a weekly email to the leadership team."
+
+For new capabilities — a new chart type, a new provider, a new admin view — treat them as template extensions: add the SQL shape, actions, UI, and agent instructions together. See [Creating Templates](/docs/creating-templates) for the current build pattern.
+
+## What's next
+
+- [**Analytics overview**](/docs/template-analytics) — back to the app summary
+- [**Dashboards, Analyses, and the Data Dictionary**](/docs/template-analytics-dashboards) — the user-facing surface this data model backs
+- [**Monitoring, Errors, and Session Replay**](/docs/template-analytics-monitoring-and-sessions) — the user-facing surface for monitors, errors, and replay
+- [**Connecting and Extending Data Sources**](/docs/template-analytics-connectors) — the full connector catalog
+- [**Actions**](/docs/actions) — the action system this template is built on
+- [**Data Programs**](/docs/data-programs) — the full data-program authoring contract
+- [**Sharing**](/docs/sharing) — the share-grant model dashboards, analyses, and error issues build on