npm - @agent-native/core - Versions diffs - 0.121.2 → 0.122.1 - Mend

@agent-native/core 0.121.2 → 0.122.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (588) hide show

package/corpus/core/src/vite/agents-bundle-plugin.ts CHANGED Viewed

@@ -118,10 +118,12 @@ export function agentsBundlePlugin(): Plugin {
         const rel = path.relative(projectRoot, file);
         if (!rel.startsWith("..")) {
           if (rel === "AGENTS.md") return true;
-          if (rel.endsWith("SKILL.md")) {
-            for (const skillsDir of TEMPLATE_SKILLS_DIRS) {
-              if (rel.startsWith(skillsDir + path.sep)) return true;
-            }
+          for (const skillsDir of TEMPLATE_SKILLS_DIRS) {
+            // Any file under a skills directory can affect the bundle now —
+            // `readSkillsDir` reads reference sub-files (not just SKILL.md)
+            // into `Skill.files`, so dev HMR must match that or reference
+            // edits go stale until a manual restart.
+            if (rel.startsWith(skillsDir + path.sep)) return true;
           }
         }
         // Workspace-core files
@@ -130,8 +132,7 @@ export function agentsBundlePlugin(): Plugin {
         }
         if (
           workspaceSkillsDir &&
-          file.startsWith(workspaceSkillsDir + path.sep) &&
-          file.endsWith("SKILL.md")
+          file.startsWith(workspaceSkillsDir + path.sep)
         ) {
           return true;
         }

package/corpus/core/src/vite/client.ts CHANGED Viewed

@@ -872,6 +872,7 @@ const CORE_CLIENT_SUBPATHS = [
   // entry.client.tsx imports from here so it never pulls the full client barrel
   // (and its transitive ~650-700 KB gzip chat stack) onto the critical path.
   "@agent-native/core/client/api-path",
+  "@agent-native/core/client/clipboard",
   "@agent-native/core/blocks",
   "@agent-native/core/blocks/server",
   "@agent-native/core/client/extensions",
@@ -1265,6 +1266,10 @@ function getCoreSourceAliases(
       coreSrc,
       "client/api-path.ts",
     ),
+    "@agent-native/core/client/clipboard": path.join(
+      coreSrc,
+      "client/clipboard.ts",
+    ),
     "@agent-native/core/blocks": path.join(coreSrc, "client/blocks/index.ts"),
     "@agent-native/core/blocks/server": path.join(
       coreSrc,
@@ -2409,6 +2414,10 @@ type NitroModuleGraph = {
 const NITRO_STARTUP_SETTLE_MS = 1_000;
 const NITRO_STARTUP_TIMEOUT_MS = 30_000;
+const NITRO_STARTUP_RETRY_KEY = "__agent_native_nitro_startup_retry";
+const NITRO_STARTUP_RETRY_MAX = 5;
+const NITRO_STARTUP_RETRY_DELAY_MS = 1_000;
+const NITRO_STARTUP_RETRY_RESET_MS = 15_000;
 function nitroModuleGraphSignature(environment: unknown): string | null {
   const graph = (environment as { moduleGraph?: NitroModuleGraph } | undefined)
@@ -2451,9 +2460,66 @@ function sendNitroStartingResponse(
     res.end();
     return;
   }
-  res.end(
-    '<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0.25"><title>Starting…</title></head><body></body></html>',
-  );
+  res.end(`<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Dev server restarting…</title>
+    <style>
+      body { margin: 0; min-height: 100vh; display: grid; place-items: center; font: 16px/1.5 system-ui, sans-serif; color: #171717; background: #fafafa; }
+      main { width: min(560px, calc(100vw - 48px)); }
+      h1 { margin: 0 0 8px; font-size: 1.25rem; }
+      p { margin: 0; color: #737373; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Dev server is restarting…</h1>
+      <p id="agent-native-nitro-retry-status">Checking again shortly.</p>
+    </main>
+    <script>
+      (() => {
+        const key = ${JSON.stringify(NITRO_STARTUP_RETRY_KEY)};
+        const maxRetries = ${NITRO_STARTUP_RETRY_MAX};
+        const resetAfterMs = ${NITRO_STARTUP_RETRY_RESET_MS};
+        const retryDelayMs = ${NITRO_STARTUP_RETRY_DELAY_MS};
+        const status = document.getElementById("agent-native-nitro-retry-status");
+        const now = Date.now();
+        let count = 0;
+        let lastAttemptAt = 0;
+        try {
+          const stored = JSON.parse(sessionStorage.getItem(key) || "null");
+          if (stored && typeof stored === "object") {
+            count = Number.isFinite(stored.count) ? stored.count : 0;
+            lastAttemptAt = Number.isFinite(stored.at) ? stored.at : 0;
+          }
+        } catch (error) {
+          // A blocked session store is handled below by showing a manual retry.
+        }
+        if (now - lastAttemptAt > resetAfterMs) count = 0;
+        if (count >= maxRetries) {
+          if (status) status.textContent = "The server is still unavailable. Refresh when it is ready.";
+          return;
+        }
+        const nextState = JSON.stringify({ count: count + 1, at: now });
+        try {
+          sessionStorage.setItem(key, nextState);
+          if (sessionStorage.getItem(key) !== nextState) throw new Error("unavailable");
+        } catch (error) {
+          if (status) status.textContent = "Refresh manually when the server is ready.";
+          return;
+        }
+        if (status) status.textContent = "Retrying in one second…";
+        setTimeout(() => window.location.reload(), retryDelayMs);
+      })();
+    </script>
+  </body>
+</html>`);
 }
 function nitroStartupGate(

package/corpus/templates/analytics/.agents/skills/adhoc-analysis/SKILL.md CHANGED Viewed

@@ -68,11 +68,10 @@ Use the available actions to pull data. Read the relevant `.agents/skills/<provi
   associated companies/contacts/tickets/notes/emails, Gong call detail, compact
   transcript excerpts, coverage counts, and gaps. Use targeted `hubspot-records`
   or `gong-calls` follow-ups only when that bundle leaves a specific gap.
-- Structure named deal/account reports like Fusion Analytics: executive summary,
-  company/deal overview, key contacts and roles, dated timeline, Gong evidence
-  with call dates/titles, current state, risks/blockers, recommended next steps,
-  and methodology/gaps. Do not answer from an all-deals dump or Gong metadata
-  alone.
+- Structure named deal/account reports as: executive summary, company/deal
+  overview, key contacts and roles, dated timeline, Gong evidence with call
+  dates/titles, current state, risks/blockers, recommended next steps, and
+  methodology/gaps. Do not answer from an all-deals dump or Gong metadata alone.
 - Use action filters such as `query`, `properties`, `objectType`, `company`, and
   `limit` to narrow results before cross-referencing
 - For HubSpot deal cohorts, use `hubspot-deals` structured filters (`product`,

package/corpus/templates/analytics/.agents/skills/admin-surfaces/SKILL.md ADDED Viewed

@@ -0,0 +1,55 @@
+---
+name: admin-surfaces
+description: >-
+  The /agents admin home for Analytics: fleet feature-flag control plane,
+  dashboard usage audit, and connected-app database admin. Use when an admin
+  asks about feature flags/rollouts, dashboard usage stats, or connecting
+  another agent-native app's database.
+---
+# Admin Surfaces (`/agents`)
+`/agents` is the Analytics home for admin surfaces. The default Monitoring
+view embeds the shared observability dashboard for traces, conversations,
+evals, agent experiments, and feedback.
+## Feature Flags (`?view=flags`)
+`/agents?view=flags` is the sole admin-only fleet feature-flag control plane.
+- Call `list-workspace-feature-flags` before changing a flag.
+- Preserve each app's explicit state: `unsupported`, `unreachable`,
+  `forbidden`, and `unknown-legacy` are unknown states, **never** synonyms for
+  off. Do not collapse them to a disabled toggle.
+- Use `set-workspace-feature-flag` for app-qualified changes; target apps
+  remain the source of truth and are resolved only through the trusted
+  organization directory.
+- Treat only a versioned mutation response whose key, org scope, and
+  requested rules match as success. Report a failed target mutation instead
+  of claiming the rollout changed.
+- Flags are source-declared booleans; do not create variants, metrics,
+  exposure tracking, or per-app management panels.
+## Dashboard Usage (`?view=dashboards`)
+`/agents?view=dashboards` shows the admin-only dashboard usage audit. Call
+`list-dashboard-usage-stats` when admins ask about dashboard created/modified
+dates, owners, last tracked modifier, views, edits, engagements, saved views,
+or cleanup candidates. The dashboard overflow menu shows created/updated
+timestamps and their tracked actors for both SQL and Explorer dashboards.
+## Connected Database Admin (`?view=database`)
+The Advanced menu opens `/agents?view=database`, where organization
+owners/admins can connect other agent-native app databases and use the
+shared database admin tool for table browsing, row editing, and SQL
+inspection. This surface is for connected target app databases, not broad
+access to all Analytics data.
+Keep future admin additions inside this route instead of adding many
+top-level sidebar tabs.
+## Related Skills
+- Root **feature-flags** (dev-scope) — how to declare and register a flag in
+  app code; this skill covers only the Analytics fleet control-plane UI/actions.

package/corpus/templates/analytics/.agents/skills/dashboard-management/SKILL.md CHANGED Viewed

@@ -615,6 +615,16 @@ state or tracker context, but docs traffic is not app usage and should not appea
 as an app/template series. Use a minimum cohort-size threshold for retention
 rates so one or two identities cannot create misleading 100% or 0% spikes.
+## Template Catalog And Demo Dashboards
+`list-dashboard-templates` / `install-dashboard-template` install shipped
+dashboard templates (Node Exporter, the canonical Agent Native observability
+dashboard, etc.), and `ensure-demo-dashboards` auto-installs a per-user demo
+on first app open. See
+`references/template-catalog-and-demo.md` for the canonical-dashboard panel
+rule, Node Exporter template specifics, and the full demo-dashboard lifecycle
+(source routing, env var overrides, tombstoning, reset).
 ## Building Large First-Party Dashboards (compose-dashboard)
 For a **first-party analytics** dashboard, prefer `compose-dashboard` over hand-authoring a big `update-dashboard` config. You name the metrics; the SERVER expands each into a full, validated panel (SQL + chart config) from the shipped metric catalog and saves them in ONE atomic call. This avoids the failure mode where the agent must stream a giant multi-panel `update-dashboard` argument inside the ~40s budget — that big tool-call can't be resumed mid-stream and is all-or-nothing on validation, so the agent thrashes (repeated update-dashboard + tool-search, never landing).

package/corpus/templates/analytics/.agents/skills/dashboard-management/references/template-catalog-and-demo.md ADDED Viewed

@@ -0,0 +1,62 @@
+# Template Catalog And Demo Dashboards
+## Listing And Installing Templates
+- `list-dashboard-templates` lists source-controlled dashboard templates with
+  `id`, category, data sources, panel count, and installed dashboard IDs.
+- `install-dashboard-template` installs a catalog template into normal
+  SQL-backed dashboards. Required: `templateId`. Optional: `dashboardId`,
+  `name`, `overwrite`, `forceNew`, and `mergePanels` (see "Reliable Bulk
+  Edits" in the main skill for the `mergePanels` append behavior).
+## Canonical Agent Native Dashboard
+Keep the canonical Agent Native dashboard (`agent-native-templates-first-party`)
+focused: it includes one explicit feedback-sentiment-by-model chart and one
+optional inferred-message-sentiment chart, not the broader LLM cost, token,
+latency, or error suite.
+- Explicit feedback uses content-free `$ai_feedback` events with `sentiment`
+  (`positive` or `negative`) and model in `$ai_model` or `model`.
+- Inferred sentiment uses `$ai_sentiment` events with `method = 'llm'` and
+  `sentiment` (`positive`, `neutral`, or `negative`).
+Keep these panels in the canonical dashboard and do not recreate a separately
+installable observability template.
+## Node Exporter Templates
+Node Exporter ships as `node-exporter-macos` (Darwin/Homebrew `node_exporter`
+scrapes) and `node-exporter-full` (the Linux-focused Grafana 1860 revision 45
+dashboard converted into native Analytics panels, plus Prometheus
+Observability Demo app metrics — `demo_http_*`, `demo_chaos_mode`, synthetic
+CPU/disk/memory workload metrics). See the `prometheus` skill for the full
+panel/field breakdown and local Homebrew setup.
+Keep the first-open `App / Overview` tab light: it should show the Request
+Latency highlight plus current app state, while Traffic, Latency, and
+Workload details stay split across their own `App / *` tabs.
+## Demo Dashboard
+- `ensure-demo-dashboards` installs one private per-user demo on first app
+  open: `demo-node-exporter`. The Analytics root route calls this before
+  honoring local last-opened state; when the action creates the demo, the
+  user should land directly on the Node Exporter demo's `App / Overview` tab
+  without visiting the template catalog or data-source setup.
+- The demo dashboard is generated from the same `node-exporter-full` seed as
+  the catalog template. Its Prometheus panels keep the same PromQL
+  descriptors and use `source: "demo"` so queries route to the demo
+  Prometheus endpoint instead of the user's `PROMETHEUS_*` credential slot.
+- The demo Prometheus endpoint defaults to the public read-only
+  `https://prometheus.agent-native.foo`, so cloud and local MPX installs work
+  without user setup. Deployments can override it with
+  `ANALYTICS_DEMO_PROMETHEUS_URL` and optional
+  `ANALYTICS_DEMO_PROMETHEUS_USERNAME`, `ANALYTICS_DEMO_PROMETHEUS_PASSWORD`,
+  or `ANALYTICS_DEMO_PROMETHEUS_BEARER_TOKEN`. Do not put credential values
+  in source, docs, fixtures, tests, prompts, or dashboard seeds.
+- Demo dashboards are ordinary SQL dashboard rows, so rename, share, archive,
+  and delete flows apply. Deleted demo IDs are tombstoned in SQL settings and
+  are not recreated unless the user explicitly asks to reset demos.
+- Use `ensure-demo-dashboards --reset=true` only when the user asks to
+  restore a deleted or changed demo dashboard.

package/corpus/templates/analytics/.agents/skills/dashboard-ops/SKILL.md ADDED Viewed

@@ -0,0 +1,85 @@
+---
+name: dashboard-ops
+description: >-
+  Deployment and runtime internals for dashboard email reports and analytics
+  alert rules: Playwright/Chromium capture, serverless timing budgets, cron
+  wiring, and notification delivery env vars. Use when configuring, deploying,
+  or debugging report/alert delivery infrastructure — not when just creating a
+  report subscription or alert rule via the action surface.
+scope: dev
+---
+# Dashboard Reports & Alerts Ops
+Dashboard email reports (`dashboard-report-subscriptions` actions) and
+analytics alert rules (`analytics-alert-rules` actions) are SQL-backed action
+surfaces. This skill covers the deployment/runtime machinery behind them —
+the agent chatting with an end user does not need this; it only needs the
+action names and the user-facing constraints already in `AGENTS.md`.
+## Dashboard Email Report Capture
+- Report PNGs are Playwright captures of the real dashboard route in
+  `reportScreenshot=1` mode, authenticated by a short-lived embed-session
+  token, and embedded inline in the email as ordered CID images.
+- Complete dashboards are captured sequentially in four-panel windows matching
+  the browser's four-query concurrency limit. Every window must match the
+  panel ids snapshotted at the start; a failed or mismatched window
+  invalidates the entire image set so the scheduler retries instead of
+  sending a partial report.
+- Capture is capped at 10 windows and 14 MiB of raw PNG data. Subscriptions
+  are capped at five distinct recipients — recommend a mailing-list address
+  for larger audiences.
+- The serverless capture deadline reserves 90 seconds of the 300-second
+  worker budget for cleanup and delivery.
+- The ten-minute retry delay is an eligibility floor, not a guarantee; the
+  `*/15` sweep runs the retry on its first tick after that floor.
+- PNG rendering uses local Chrome in development and `playwright-core` plus
+  `@sparticuz/chromium-min` in serverless runtimes. Set
+  `DASHBOARD_REPORT_CHROMIUM_PACK_URL` only when overriding the default
+  Chromium pack location.
+## Cron Wiring
+- Netlify builds emit a scheduled trigger plus a background worker from
+  `scripts/emit-netlify-dashboard-report-cron.ts`, using a per-deploy internal
+  token and disabling the in-process interval scheduler on Netlify to avoid
+  duplicate sends.
+- External cron callers can sweep due reports by POSTing
+  `/api/dashboard-reports/run` with
+  `Authorization: Bearer $DASHBOARD_REPORTS_CRON_SECRET`.
+- The same `scripts/emit-netlify-dashboard-report-cron.ts` script also emits
+  the alert-rule cron trigger plus background worker, running every five
+  minutes on Netlify. Long-lived runtimes use the in-process scheduler unless
+  `ANALYTICS_ALERT_JOBS=0` is set.
+- External cron callers can run due alerts by POSTing
+  `/api/analytics-alerts/run` with
+  `Authorization: Bearer $ANALYTICS_ALERTS_CRON_SECRET`.
+## Alert Notification Delivery
+Alert notifications use the shared notification channel registry
+(`channels` can include `inbox`, `email`, `slack`, `webhook`, or any custom
+registered channel):
+- Slack/webhook delivery prefers per-rule `metadata.delivery.slackWebhookUrl`
+  / `metadata.delivery.webhookUrl` (uptime monitors store these on the
+  monitor row), then falls back to `NOTIFICATIONS_SLACK_WEBHOOK_URL` /
+  `NOTIFICATIONS_WEBHOOK_URL`. Optional `NOTIFICATIONS_SLACK_WEBHOOK_AUTH`
+  configures Slack auth.
+- Email delivery needs `RESEND_API_KEY` or `SENDGRID_API_KEY` plus
+  `EMAIL_FROM`. Per-rule `emailRecipients` fall back to
+  `NOTIFICATIONS_EMAIL_RECIPIENTS`. Saving explicit `emailRecipients` also
+  remembers them as the current user's defaults for the next alert rule
+  created in Settings.
+Users can also view and manage report subscriptions and alert rules in
+Settings; that UI uses the same action surface as the agent, so no separate
+implementation is needed there.
+## Related Skills
+- **dashboard-management** — the dashboard artifact model these features
+  attach to.
+- **integration-webhooks** (root) — the general queue-and-processor pattern
+  for outbound webhook delivery.

package/corpus/templates/analytics/.agents/skills/data-querying/SKILL.md CHANGED Viewed

@@ -34,12 +34,37 @@ Convert the user's requested local date/timezone to UTC before querying. For
 example, May 1, 2026 in America/New_York is `2026-05-01T04:00:00Z`
 through `2026-05-02T04:00:00Z`.
-## Showing Charts In Chat
+## Inline Charts In Chat
-For an in-chat answer, **emit a live `/chart` embed** — never `generate-chart`. The embed mounts a live `SqlChart` that re-queries when its source changes, and it doesn't choke on rigid JSON params the way the PNG action does. Full shape in `AGENTS.md` ("Inline Charts in Chat" section). Reach for `generate-chart` only when you're building a dashboard artifact that needs a persisted report image.
+For an in-chat answer, **emit a live `/chart` embed** — never `generate-chart`. The embed mounts a live `SqlChart` that re-queries when its source changes, and it doesn't choke on rigid JSON params the way the PNG action does. Reach for `generate-chart` only when you're building a dashboard artifact that needs a persisted report image.
 If `generate-chart` returns an error in any chat-answering flow, the recovery is to switch to the live embed, not to retry with reformatted params.
+**How it renders.** The core chat markdown renderer turns any fenced block tagged `embed` into a sandboxed, same-origin iframe. Emit:
+````markdown
+```embed
+src: /chart?panel=<base64url-encoded panel JSON>
+title: Daily pageviews
+height: 320
+```
+````
+Fence keys: `src` (required, same-origin path), `title`, and either `height` (px) or `aspect` (`16/9`, `4/3`, `1/1`, `21/9`, `3/2`, `2/1`; default `16/9`). A cross-origin `src` renders an "Embed blocked" notice instead of a chart.
+**Panel JSON.** The `/chart` route decodes `panel` into a `SqlPanel` (`app/pages/adhoc/sql-dashboard/types.ts`):
+- `sql` — required, non-empty.
+- `source` — required, one of `bigquery`, `ga4`, `amplitude`, `first-party`, `demo`, `prometheus`. `program` is deliberately **not** embeddable.
+- `chartType` — required, one of `line`, `area`, `bar`, `metric`, `table`, `pie`. Dashboard-layout types (`section`, `heatmap`, `callout`, `extension`) are rejected.
+- `id` (defaults `"embed"`), `title` (rendered above the chart), `width` (dashboard-only, ignored here), `config` (passed through unvalidated — `xKey`/`yKeys`, `colors`, `yFormatter`, `columns`, `stacked`, `legend`, …).
+An unknown `source`/`chartType` or blank `sql` renders an error card, not a chart.
+**Encoding.** JSON-stringify the panel, base64-encode it, then make it URL-safe: `+` → `-`, `/` → `_`, strip `=` padding. No further URL-encoding is needed. Keep the SQL short — it rides in a query string; if it's long, save it as a dashboard panel and link to the dashboard instead.
+Full details (per-field validation, `config` keys, a verified round-trip example, and how this differs from `generate-chart`) are in `references/inline-chart-embeds.md` — read it with `docs-search --slug "skill-data-querying--references-inline-chart-embeds"`.
 ## Script Patterns
 ### Reusing Existing Actions

package/corpus/templates/analytics/.agents/skills/data-querying/references/inline-chart-embeds.md ADDED Viewed

@@ -0,0 +1,139 @@
+# Inline Chart Embeds (the live `/chart` embed)
+For an in-chat answer, emit a fenced ` ```embed ` block whose `src` points at
+the app's own `/chart` route with a base64url-encoded panel in the `panel`
+query param. The chat renderer mounts that route in a sandboxed same-origin
+iframe, which renders a live `SqlChart` that re-queries when its source
+changes. This is a different mechanism from `generate-chart` (a static
+PNG/SVG render) — see "How This Differs From `generate-chart`" below.
+## The Two Layers
+1. **The chat markdown embed fence** — this lives in core, not in the
+   template. Analytics chat renders through `AgentChatSurface` →
+   `MarkdownText` (`packages/core/src/client/chat/markdown-renderer.tsx`),
+   whose `markdownComponents.pre` handler intercepts any code block tagged
+   `language-embed` and renders `IframeEmbed`
+   (`packages/core/src/client/IframeEmbed.tsx`) instead of a `<pre>`.
+   `parseEmbedBody` there reads `key: value` lines:
+   - `src` (required) — the iframe URL.
+   - `title` (optional) — shown in the embed's "Preview" header bar and used
+     as the iframe `title`. Defaults to "Embedded content".
+   - `aspect` (optional) — one of `16/9`, `4/3`, `1/1`, `21/9`, `3/2`, `2/1`;
+     anything else falls back to `16/9`. Ignored when `height` is set.
+   - `height` (optional) — pixels; overrides `aspect`.
+   `isSameOriginSrc` only allows same-origin URLs: a path starting with `/`
+   (but not `//`), `./`, or `../`, or an absolute URL whose origin matches the
+   app's. Anything cross-origin renders an "Embed blocked" notice instead of
+   an iframe. The iframe itself is sandboxed
+   (`allow-scripts allow-same-origin allow-forms allow-popups`),
+   `referrerPolicy="same-origin"`, and lazy-loaded. An embedded page can call
+   `postNavigate()` from `@agent-native/core/client/embed` to pop the user out
+   into the parent window at the same path.
+   The template also ships its own `embed`-fence implementation in
+   `templates/analytics/app/components/Markdown.tsx`, but that one renders
+   **saved analysis bodies** (`app/pages/analyses/AnalysisDetail.tsx`), not
+   chat. It is stricter: relative `src` only (no absolute same-origin URL) and
+   `height` clamped to 2000. Keep embeds relative and they work in both.
+2. **The `/chart` route** — `templates/analytics/app/routes/chart.tsx`. It
+   reads the `panel` search param and decodes it with `decodePanel`
+   (`chart.tsx:31-73`), then renders `<SqlChart panel={result} />`
+   (`chart.tsx:115`), the same live chart component dashboards use
+   (`templates/analytics/app/components/dashboard/SqlChart.tsx:1111`).
+So the full pattern the agent must emit is:
+```embed
+src: /chart?panel=<base64url-encoded-panel-json>
+title: Daily pageviews
+height: 320
+```
+## The Panel JSON Shape (validated by `decodePanel`, `chart.tsx:31-73`)
+| Field       | Required | Type / allowed values                                                                     | Notes                                                                                                                                                                                                             |
+| ----------- | -------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sql`       | yes      | non-empty string                                                                          | The query to run.                                                                                                                                                                                                 |
+| `source`    | yes      | `"bigquery"` \| `"ga4"` \| `"amplitude"` \| `"first-party"` \| `"demo"` \| `"prometheus"` | `chart.tsx:22-29`. This is every `DataSourceType` (`app/pages/adhoc/sql-dashboard/types.ts:1-8`) **except `"program"`** — data-program-backed sources cannot be embedded this way.                                |
+| `chartType` | yes      | `"line"` \| `"area"` \| `"bar"` \| `"metric"` \| `"table"` \| `"pie"`                     | `chart.tsx:12-19`. This is every `ChartType` (`types.ts:10-20`) **except `"section"`, `"heatmap"`, `"callout"`, `"extension"`** — those are dashboard-layout-only types and are not valid for a standalone embed. |
+| `id`        | no       | string                                                                                    | Defaults to `"embed"`.                                                                                                                                                                                            |
+| `title`     | no       | string                                                                                    | Defaults to `""`. Shown above the chart in `ChartRoute` (`chart.tsx:109-113`) — separate from the outer `embed` fence's own `title:` line, which only sets the iframe's `title` attribute.                        |
+| `width`     | no       | number ≥ 1, floored                                                                       | Defaults to `1`. Legacy dashboard row-layout field; has no effect on the standalone `/chart` page.                                                                                                                |
+| `config`    | no       | `SqlPanelConfig` object (`types.ts`)                                                      | Passed through as-is — `decodePanel` only checks `typeof === "object"`, it does not validate individual keys.                                                                                                     |
+Any other `source`/`chartType` value, or a missing/blank `sql`, makes
+`decodePanel` return an error and the route renders `ChartError`
+(`chart.tsx:75-92`) instead of a chart.
+### Useful `config` keys (from `SqlPanelConfig`, `types.ts`)
+- `xKey`, `yKey` / `yKeys` — column names for the x-axis and series. If
+  omitted, `SqlChart`'s `detectKeys` (`SqlChart.tsx:1013-1060`) auto-picks a
+  date/string-like column for `xKey` and all remaining numeric columns for
+  `yKeys`, so these are usually only needed to override the guess. Prefer
+  writing SQL that already returns unambiguous column names over relying on
+  auto-detection.
+- `colors` / `color` — series colors.
+- `yFormatter` — `"number"` | `"currency"` | `"percent"`.
+- `columns` — `table` chartType only: `{ key, label?, format?, linkKey?, hidden? }[]`.
+- `stacked`, `legend`, `pivot`, `limit`, `valueLabels`, `description` — see
+  `SqlPanelConfig` in `types.ts` for the full list.
+## Encoding The `panel` Param
+`decodePanel` un-does a URL-safe, unpadded base64 encoding
+(`chart.tsx:33-35`): it replaces `-` back to `+` and `_` back to `/`, then
+pads with `=` before `atob`-decoding and `JSON.parse`-ing. To encode, do the
+reverse — base64-encode the JSON, then replace `+` with `-`, `/` with `_`,
+and strip any trailing `=` padding.
+Worked example (verified round-trip):
+Panel JSON:
+```json
+{
+  "title": "Daily pageviews",
+  "sql": "SELECT date_trunc('day', timestamp) AS day, COUNT(*) AS pageviews FROM analytics_events WHERE event_name = 'pageview' GROUP BY 1 ORDER BY 1",
+  "source": "first-party",
+  "chartType": "line"
+}
+```
+Resulting embed:
+```embed
+src: /chart?panel=eyJ0aXRsZSI6IkRhaWx5IHBhZ2V2aWV3cyIsInNxbCI6IlNFTEVDVCBkYXRlX3RydW5jKCdkYXknLCB0aW1lc3RhbXApIEFTIGRheSwgQ09VTlQoKikgQVMgcGFnZXZpZXdzIEZST00gYW5hbHl0aWNzX2V2ZW50cyBXSEVSRSBldmVudF9uYW1lID0gJ3BhZ2V2aWV3JyBHUk9VUCBCWSAxIE9SREVSIEJZIDEiLCJzb3VyY2UiOiJmaXJzdC1wYXJ0eSIsImNoYXJ0VHlwZSI6ImxpbmUifQ
+title: Daily pageviews
+height: 320
+```
+Since it's a plain query-string param, keep the SQL reasonably short — it
+rides in a URL that also has to survive markdown fencing and the iframe's
+`src` attribute. It does not need extra URL-encoding beyond the base64url
+step above (base64url output contains only `A-Za-z0-9-_`, which is
+URL-safe).
+## How This Differs From `generate-chart`
+`generate-chart` (`templates/analytics/actions/generate-chart.ts`) renders a
+**static** PNG (or SVG fallback) file to the media directory:
+- Params are separate top-level fields (`title`, `labels`, `data`, `type`,
+  `subtitle`, `width`, `height`, `theme`, `color`), where `labels` and `data`
+  are **pre-stringified JSON arrays** the caller must have already computed —
+  there is no `sql`/`source` and no live query.
+- Only three chart types: `bar`, `line`, `area` (no `pie`, `metric`, `table`).
+- The output is a saved image file, not a live component — it never
+  re-queries if the underlying data changes.
+- It exists for `save-analysis` artifacts and other places that need a
+  persisted image (exports, archived reports), not for in-chat answers.
+The `/chart` embed instead re-runs `sql` against `source` live through
+`SqlChart`/`useSqlQuery`, so it always reflects current data and supports the
+full `pie`/`metric`/`table` chart types dashboards use. Prefer it for every
+in-chat data answer; reach for `generate-chart` only when building a
+save-analysis artifact that needs a static image.

package/corpus/templates/analytics/.agents/skills/monitoring/SKILL.md ADDED Viewed

@@ -0,0 +1,77 @@
+---
+name: monitoring
+description: >-
+  Implementation map for the Monitoring tab (uptime checks, public status
+  pages, error triage): component/server file locations, schema, jobs, and
+  scheduler wiring. Use when building or debugging Monitoring UI, uptime
+  checks, status pages, or error capture/grouping — not when just calling the
+  monitoring actions from chat.
+scope: dev
+---
+# Monitoring Implementation Map
+`/monitoring` is a thin shell (`app/routes/monitoring._index.tsx` →
+`app/pages/monitoring/MonitoringPage.tsx`) hosting two independently-owned
+panels selected by `?view=uptime|errors` (defaults to uptime). `navigation`
+mirrors it as `view="monitoring"` with `monitoringView` (plus
+`monitorId`/`errorIssueId` when a row is open); each panel also writes richer
+selection to the `monitoring` application-state key.
+## Uptime
+- UI: `app/pages/monitoring/UptimePanel.tsx`, `app/pages/monitoring/uptime/**`.
+- Server: `server/lib/uptime-monitors.ts` (checks/alerting), sweep job
+  `server/jobs/uptime-monitors.ts`, scheduler
+  `server/plugins/uptime-monitor-jobs.ts`, schema
+  `server/db/schema-monitoring.ts`.
+- Actions: `list-monitors`, `get-monitor`, `save-monitor`, `run-monitor-check`,
+  `delete-monitor`.
+- Production serverless/Netlify-style runtimes skip the in-process interval
+  scheduler and rely on the generated scheduled/background worker or external
+  cron instead.
+- Deep links: list `?view=uptime`, detail `?view=uptime&monitor=<id>`, create
+  `?view=uptime&monitor=new`, edit `?view=uptime&monitor=<id>&edit=1`.
+- See `docs/uptime-monitoring.md`.
+## Status Pages
+- UI: `app/pages/monitoring/uptime/status-pages/**`, a config sub-view under
+  Uptime that bundles chosen monitors under a public `/status/<slug>` page.
+- Server: owner-scoped CRUD and the sanitized public projection live in
+  `server/lib/status-pages.ts` over `server/db/schema-monitoring.ts`.
+- Actions: `list-status-pages`, `get-status-page`, `save-status-page`,
+  `delete-status-page`, `add-status-page-monitor`,
+  `remove-status-page-monitor`, `reorder-status-page-monitors`, plus the
+  unauthenticated `get-public-status-page`.
+- Deep links: index `?view=uptime&statuspage=list`, create
+  `?view=uptime&statuspage=new`, edit `?view=uptime&statuspage=<id>`.
+## Errors
+- UI: `app/pages/monitoring/ErrorsPanel.tsx`, `app/pages/monitoring/errors/**`
+  — Sentry-style exception triage grouped into issues by fingerprint.
+- Server: ingest/grouping in `server/lib/error-capture.ts` over
+  `server/db/schema-errors.ts`.
+- Actions: `list-error-issues`, `get-error-issue`, `resolve-error-issue`,
+  `capture-test-error`, `match-error-issues`.
+- Browser capture uses the SDK from `@agent-native/core/client`
+  (`captureException` / `captureMessage` / `addErrorBreadcrumb`),
+  auto-enabled by `configureTracking` and transported through the first-party
+  analytics ingest as a `$exception` event.
+- Deep link: `?view=errors&issue=<id>`. Issue detail includes recent
+  frequency, parsed/raw stack traces, source code snippets when available,
+  breadcrumbs, tags, occurrence history, and session replay links.
+- See `docs/error-capture.md`.
+## Session Replay ↔ Errors
+A recording's devtools Console error lines link to the grouped issue at
+`/monitoring?view=errors&issue=<id>`, resolved by `match-error-issues` (exact
+fingerprint match, no heuristics); issues link back to the originating
+recording at `/sessions/<recordingId>`.
+## Related Skills
+- **session-replay** — replay storage, capture, and the Dev Tools panel this
+  feature links to.