npm - @agent-native/core - Versions diffs - 0.120.0 → 0.120.2 - Mend

@agent-native/core 0.120.0 → 0.120.2

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 (207) hide show

package/corpus/core/src/server/analytics.ts CHANGED Viewed

@@ -2,16 +2,21 @@
  * Opt-in analytics injection for SSR streams.
  * Supported environment variables:
  * - `GA_MEASUREMENT_ID` — Google Analytics 4 measurement ID
+ * - `GTM_CONTAINER_ID` — Google Tag Manager web container ID
  *
  * Netlify configuration-file env vars are build-time only for serverless
  * functions, so the Vite/Nitro build paths also bake this public value into
  * SSR bundles.
  *
  * Amplitude and Sentry are initialized client-side via their npm packages
- * (see `packages/core/src/client/analytics.ts`). Only GA requires script
- * tag injection because the gtag.js loader must be a `<script src>`.
+ * (see `packages/core/src/client/analytics.ts`). GTM and GA require script
+ * tag injection because their loaders must be `<script>` elements.
  *
- * When set, the corresponding script tags are injected before `</head>`.
+ * When GTM is set, its head bootstrap is injected before `</head>` and its
+ * noscript fallback immediately after `<body>`. GTM takes precedence over GA
+ * so pageviews are not double-counted; configure the GA tag inside GTM.
+ * When only GA is set, the corresponding script tags are injected before
+ * `</head>`.
  * When not set, the stream passes through untouched (zero overhead).
  *
  * Usage in entry.server.tsx:
@@ -22,6 +27,7 @@
  */
 declare const __AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID__: string | undefined;
+declare const __AGENT_NATIVE_BUILD_GTM_CONTAINER_ID__: string | undefined;
 function normalizeMeasurementId(value: string | undefined): string | null {
   const trimmed = value?.trim();
@@ -34,6 +40,25 @@ function getViteBakedGaMeasurementId(): string | undefined {
     : undefined;
 }
+function normalizeContainerId(value: string | undefined): string | null {
+  const trimmed = value?.trim().toUpperCase();
+  return trimmed && /^GTM-[A-Z0-9]+$/.test(trimmed) ? trimmed : null;
+}
+function getViteBakedGtmContainerId(): string | undefined {
+  return typeof __AGENT_NATIVE_BUILD_GTM_CONTAINER_ID__ === "string"
+    ? __AGENT_NATIVE_BUILD_GTM_CONTAINER_ID__
+    : undefined;
+}
+function getGtmContainerId(): string | null {
+  return (
+    normalizeContainerId(process.env.GTM_CONTAINER_ID) ||
+    normalizeContainerId(process.env.AGENT_NATIVE_BUILD_GTM_CONTAINER_ID) ||
+    normalizeContainerId(getViteBakedGtmContainerId())
+  );
+}
 function getGaMeasurementId(): string | null {
   return (
     normalizeMeasurementId(process.env.GA_MEASUREMENT_ID) ||
@@ -74,32 +99,151 @@ function getGaScript(): string | null {
   );
 }
-export function wrapWithAnalytics(body: ReadableStream): ReadableStream {
-  const scripts = [getGaScript()].filter(Boolean).join("");
-  if (!scripts) return body;
+function getGtmHeadScript(containerId: string): string {
+  const jsId = JSON.stringify(containerId);
+  return `<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer',${jsId});</script>`;
+}
+function getGtmBodyFallback(containerId: string): string {
+  const src = encodeURIComponent(containerId);
+  return `<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=${src}" height="0" width="0" style="display:none;visibility:hidden" title="Google Tag Manager"></iframe></noscript>`;
+}
+type AnalyticsInjection = {
+  head: string;
+  body: string;
+};
+function getAnalyticsInjection(): AnalyticsInjection | null {
+  const containerId = getGtmContainerId();
+  if (containerId) {
+    return {
+      head: getGtmHeadScript(containerId),
+      body: getGtmBodyFallback(containerId),
+    };
+  }
+  const gaScript = getGaScript();
+  return gaScript ? { head: gaScript, body: "" } : null;
+}
+const HEAD_CLOSE_PATTERN = /<\/head>/i;
+const BODY_OPEN_PATTERN = /<body\b[^>]*>/i;
+/**
+ * Add the configured analytics scripts to a complete HTML document.
+ *
+ * The normal app document is streamed through `wrapWithAnalytics`, but
+ * framework-owned documents such as `/signup` are returned as strings by the
+ * auth guard and need the same injection path.
+ */
+export function injectAnalyticsIntoHtml(html: string): string {
+  const injection = getAnalyticsInjection();
+  if (!injection) return html;
+  const headCloseMatch = HEAD_CLOSE_PATTERN.exec(html);
+  if (!headCloseMatch || headCloseMatch.index === undefined) return html;
+  let output =
+    html.slice(0, headCloseMatch.index) +
+    injection.head +
+    html.slice(headCloseMatch.index);
+  if (injection.body) {
+    const bodyOpenMatch = BODY_OPEN_PATTERN.exec(output);
+    if (bodyOpenMatch && bodyOpenMatch.index !== undefined) {
+      const bodyEnd = bodyOpenMatch.index + bodyOpenMatch[0].length;
+      output =
+        output.slice(0, bodyEnd) + injection.body + output.slice(bodyEnd);
+    }
+  }
+  return output;
+}
+export function wrapWithAnalytics(
+  body: ReadableStream<Uint8Array>,
+): ReadableStream<Uint8Array> {
+  const injection = getAnalyticsInjection();
+  if (!injection) return body;
   const decoder = new TextDecoder();
   const encoder = new TextEncoder();
-  let injected = false;
+  let pending = "";
+  let headInjected = false;
+  let bodyInjected = !injection.body;
   return body.pipeThrough(
-    new TransformStream({
+    new TransformStream<Uint8Array, Uint8Array>({
       transform(chunk, controller) {
-        if (injected) {
-          controller.enqueue(chunk);
-          return;
+        pending += decoder.decode(chunk, { stream: true });
+        if (!headInjected) {
+          const headCloseMatch = HEAD_CLOSE_PATTERN.exec(pending);
+          if (!headCloseMatch || headCloseMatch.index === undefined) return;
+          const headEnd = headCloseMatch.index + headCloseMatch[0].length;
+          controller.enqueue(
+            encoder.encode(
+              pending.slice(0, headCloseMatch.index) +
+                injection.head +
+                pending.slice(headCloseMatch.index, headEnd),
+            ),
+          );
+          pending = pending.slice(headEnd);
+          headInjected = true;
         }
-        const text = decoder.decode(chunk, { stream: true });
-        const headCloseIdx = text.indexOf("</head>");
-        if (headCloseIdx !== -1) {
-          const modified =
-            text.slice(0, headCloseIdx) + scripts + text.slice(headCloseIdx);
-          controller.enqueue(encoder.encode(modified));
-          injected = true;
-        } else {
-          controller.enqueue(chunk);
+        if (!bodyInjected) {
+          const bodyOpenMatch = BODY_OPEN_PATTERN.exec(pending);
+          if (!bodyOpenMatch || bodyOpenMatch.index === undefined) return;
+          const bodyEnd = bodyOpenMatch.index + bodyOpenMatch[0].length;
+          controller.enqueue(
+            encoder.encode(pending.slice(0, bodyEnd) + injection.body),
+          );
+          pending = pending.slice(bodyEnd);
+          bodyInjected = true;
+        }
+        if (pending) {
+          controller.enqueue(encoder.encode(pending));
+          pending = "";
         }
       },
+      flush(controller) {
+        pending += decoder.decode();
+        if (!headInjected) {
+          const headCloseMatch = HEAD_CLOSE_PATTERN.exec(pending);
+          if (headCloseMatch && headCloseMatch.index !== undefined) {
+            const headEnd = headCloseMatch.index + headCloseMatch[0].length;
+            controller.enqueue(
+              encoder.encode(
+                pending.slice(0, headCloseMatch.index) +
+                  injection.head +
+                  pending.slice(headCloseMatch.index, headEnd),
+              ),
+            );
+            pending = pending.slice(headEnd);
+            headInjected = true;
+          }
+        }
+        if (headInjected && !bodyInjected) {
+          const bodyOpenMatch = BODY_OPEN_PATTERN.exec(pending);
+          if (bodyOpenMatch && bodyOpenMatch.index !== undefined) {
+            const bodyEnd = bodyOpenMatch.index + bodyOpenMatch[0].length;
+            controller.enqueue(
+              encoder.encode(pending.slice(0, bodyEnd) + injection.body),
+            );
+            pending = pending.slice(bodyEnd);
+            bodyInjected = true;
+          }
+        }
+        if (pending) controller.enqueue(encoder.encode(pending));
+      },
     }),
   );
 }

package/corpus/core/src/server/auth.ts CHANGED Viewed

@@ -98,6 +98,7 @@ import {
   type WorkspaceAppAudience,
 } from "../shared/workspace-app-audience.js";
 import { isValidWorkspaceAppIdFormat } from "../shared/workspace-app-id.js";
+import { injectAnalyticsIntoHtml } from "./analytics.js";
 import { signupAttributionFromCookieHeader } from "./attribution.js";
 import { getBetterAuth, getBetterAuthSync } from "./better-auth-instance.js";
 import type { BetterAuthConfig } from "./better-auth-instance.js";
@@ -1646,20 +1647,23 @@ function injectLoginSocialImageMeta(loginHtml: string, event: H3Event): string {
 }
 function loginHtmlResponse(loginHtml: string, event: H3Event): Response {
-  return new Response(injectLoginSocialImageMeta(loginHtml, event), {
-    status: 200,
-    headers: {
-      "Content-Type": "text/html; charset=utf-8",
-      // The sign-in document is part of the public server shell. Keep it on the
-      // same long-fresh/long-SWR CDN policy as React Router SSR so hosted
-      // template roots do not invoke origin just to render anonymous login UI.
-      // The login HTML is env-INDEPENDENT (a Google-only app always renders a
-      // working button), so a cached copy is never "wrong" — never downgrade
-      // this to private/no-store.
-      ...DEFAULT_SSR_CACHE_HEADERS,
-      "X-Robots-Tag": "noindex, nofollow",
+  return new Response(
+    injectAnalyticsIntoHtml(injectLoginSocialImageMeta(loginHtml, event)),
+    {
+      status: 200,
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        // The sign-in document is part of the public server shell. Keep it on the
+        // same long-fresh/long-SWR CDN policy as React Router SSR so hosted
+        // template roots do not invoke origin just to render anonymous login UI.
+        // The login markup is env-INDEPENDENT (a Google-only app always renders
+        // a working button); the analytics script is public build configuration,
+        // not user/session state. Never downgrade this to private/no-store.
+        ...DEFAULT_SSR_CACHE_HEADERS,
+        "X-Robots-Tag": "noindex, nofollow",
+      },
     },
-  });
+  );
 }
 function isHtmlDocumentRequest(event: H3Event, pathname: string): boolean {

package/corpus/core/src/server/better-auth-instance.ts CHANGED Viewed

@@ -1109,6 +1109,18 @@ async function createBetterAuthInstance(
   return auth as unknown as BetterAuthInstance;
 }
+/**
+ * Configure the local auth connection with the same write contention settings
+ * as the shared app connection. Better Auth uses its own SQLite handle, so the
+ * app connection's busy timeout does not protect first-run account creation.
+ */
+export function configureLocalSqlite(sqlite: {
+  pragma(statement: string): unknown;
+}): void {
+  sqlite.pragma("busy_timeout = 10000");
+  sqlite.pragma("journal_mode = WAL");
+}
 async function buildDatabaseConfig(
   dialect: string,
 ): Promise<BetterAuthOptions["database"]> {
@@ -1182,7 +1194,7 @@ async function buildDatabaseConfig(
     const { default: Database } = await import("better-sqlite3");
     const filePath = url.replace(/^file:/, "");
     const sqlite = new Database(filePath);
-    sqlite.pragma("journal_mode = WAL");
+    configureLocalSqlite(sqlite);
     const { drizzle } = await import("drizzle-orm/better-sqlite3");
     const db = drizzle(sqlite, { schema: sqliteAuthSchema });
     const { drizzleAdapter } = await import("better-auth/adapters/drizzle");

package/corpus/core/src/templates/chat/app/components/layout/Sidebar.tsx CHANGED Viewed

@@ -4,7 +4,6 @@ import {
   type ChatThreadSummary,
 } from "@agent-native/core/client/agent-chat";
 import { appPath } from "@agent-native/core/client/api-path";
-import { ExtensionsSidebarSection } from "@agent-native/core/client/extensions";
 import { useT } from "@agent-native/core/client/i18n";
 import { OrgSwitcher } from "@agent-native/core/client/org";
 import { FeedbackButton } from "@agent-native/core/client/ui";
@@ -38,6 +37,9 @@ const navItems = [
     href: "/",
     view: "chat",
   },
+];
+const bottomNavItems = [
   {
     icon: IconHierarchy2,
     labelKey: "settings.agentTitle",
@@ -419,11 +421,38 @@ export function Sidebar({
       </nav>
       <div className={cn("mt-auto shrink-0", collapsed && "py-2")}>
-        {!collapsed ? (
-          <div className="px-2 py-1">
-            <ExtensionsSidebarSection />
-          </div>
-        ) : null}
+        <nav
+          className={cn(
+            "grid",
+            collapsed ? "gap-0 px-1 py-1" : "gap-1 px-2 py-1",
+          )}
+        >
+          {bottomNavItems.map((item) => {
+            const Icon = item.icon;
+            const isActive = location.pathname.startsWith(item.href);
+            const link = (
+              <Link
+                to={item.href}
+                className={navClass({ isActive })}
+                aria-current={isActive ? "page" : undefined}
+                aria-label={collapsed ? t(item.labelKey) : undefined}
+              >
+                <Icon className="size-4 shrink-0" />
+                <span className={collapsed ? "sr-only" : "truncate"}>
+                  {t(item.labelKey)}
+                </span>
+              </Link>
+            );
+            return collapsed ? (
+              <Tooltip key={item.href}>
+                <TooltipTrigger asChild>{link}</TooltipTrigger>
+                <TooltipContent side="right">{t(item.labelKey)}</TooltipContent>
+              </Tooltip>
+            ) : (
+              <div key={item.href}>{link}</div>
+            );
+          })}
+        </nav>
         <div className={cn(collapsed ? "px-1 py-1" : "px-3 py-2")}>
           <OrgSwitcher

package/corpus/core/src/templates/chat/app/routes/extensions._index.tsx CHANGED Viewed

@@ -1,4 +1,4 @@
-import { ExtensionsListPage } from "@agent-native/core/client/extensions";
+import { Navigate } from "react-router";
 import { APP_TITLE } from "@/lib/app-config";
@@ -7,5 +7,5 @@ export function meta() {
 }
 export default function ExtensionsRoute() {
-  return <ExtensionsListPage />;
+  return <Navigate to="/settings#extensions" replace />;
 }

package/corpus/core/src/templates/chat/netlify.toml CHANGED Viewed

@@ -6,5 +6,6 @@ functions = "templates/chat/.netlify/functions-internal"
 [build.environment]
 GA_MEASUREMENT_ID = "G-ESF7FYXGN9"
+GTM_CONTAINER_ID = "GTM-N3WSTXZ"
 NITRO_PRESET = "netlify"
 NPM_CONFIG_PRODUCTION = "false"

package/corpus/core/src/templates/workspace-core/.agents/skills/extensions/SKILL.md CHANGED Viewed

@@ -76,6 +76,22 @@ Full source-code customization is a core Agent Native capability. Extensions
 are the fast, sandboxed, no-deploy layer—not the limit of what the app can
 become.
+Use this decision rule when either path could solve the request:
+- Start with an extension for a self-contained, relatively one-off widget,
+  custom visualization or interaction, dashboard tile, standalone utility, or
+  add-on in an existing slot.
+- Use app code for a core template feature, native UI/layout/routes/business
+  logic, a new slot, or behavior that should be reused broadly across dashboards
+  or users.
+- If the same extension keeps getting rebuilt, promote it into app code as one
+  reusable native feature instead of maintaining copies.
+As a rule of thumb, if an extension can solve the problem, generally start
+there. An isolated custom dashboard visualization belongs in an extension; a
+new chart type that should be available across dashboards belongs in the
+template code.
 **When a user asks to "make an extension", "create an extension", or "build
 a ... extension" (or the older phrasings "make a tool" / "create a tool"):**

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

@@ -3066,6 +3066,12 @@ function createAgentNativeConfig(
       "process.env.AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID": JSON.stringify(
         process.env.GA_MEASUREMENT_ID?.trim() || "",
       ),
+      __AGENT_NATIVE_BUILD_GTM_CONTAINER_ID__: JSON.stringify(
+        process.env.GTM_CONTAINER_ID?.trim() || "",
+      ),
+      "process.env.AGENT_NATIVE_BUILD_GTM_CONTAINER_ID": JSON.stringify(
+        process.env.GTM_CONTAINER_ID?.trim() || "",
+      ),
       // Framework route warmup controls how SSR `.data` routes are fetched:
       // ordinary fetches keep them CDN-cacheable, while native prefetch headers
       // can be refused before the CDN/origin sees the request. Keep this value

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

@@ -2,12 +2,12 @@
 name: adhoc-analysis
 description: >-
   How to conduct ad-hoc analyses: gather data from multiple sources, synthesize
-  findings, save reusable analysis artifacts that anyone can re-run for fresh results.
+  findings, and save durable results as dashboard artifacts that anyone can re-run.
 ---
 # Ad-Hoc Analysis
-Ad-hoc analyses are deep-dive investigations that cross-reference multiple data sources and produce a written report with findings. Saving a reusable artifact is optional: answer in chat first unless the user explicitly asks to save the analysis, create a reusable artifact, or re-run/update an existing saved analysis.
+Ad-hoc analyses are deep-dive investigations that cross-reference multiple data sources and produce a written report with findings. The durable user-facing result is a dashboard. Answer in chat first unless the user explicitly asks to save the result, create a reusable artifact, or re-run/update an existing saved analysis.
 ## When to Use
@@ -17,21 +17,20 @@ Use the ad-hoc analysis workflow when:
 - The investigation involves cross-referencing (e.g., CRM deals matched against call recordings)
 - The user explicitly asks for an "analysis" or "deep dive"
-Save a reusable analysis only when:
+Save a reusable dashboard artifact when:
 - The user explicitly asks to save, create, publish, or re-run a saved analysis
 - The user is already viewing or re-running an existing saved analysis
 - The output needs a durable artifact because it includes generated chart images or a reusable refresh workflow
-For one-off questions and exploratory deep dives, query the data and answer in chat. Do not call `save-analysis` just because the user said "analysis" or "deep dive".
+For one-off questions and exploratory deep dives, query the data and answer in chat. Do not create a dashboard or call the legacy `save-analysis` action just because the user said "analysis" or "deep dive".
 If the user asks for an analysis output that needs a bespoke interactive
 surface, custom visualization, multi-step workflow, or UI that cannot be
-faithfully represented as saved-analysis Markdown, generated chart images, and
-structured `resultData`, create an extension instead of forcing the request into
-the saved-analysis format. In production mode, call `create-extension`
-automatically and tell the user the requested analysis needed bespoke UI/code, so
-you built it as an extension.
+faithfully represented by native dashboard panels, create an extension and
+immediately embed it in the dashboard as one or more `chartType: "extension"`
+panels with `config.extensionId`. Never leave the extension as a standalone
+Analytics result or direct the user to an Extensions page.
 ## Workflow
@@ -159,46 +158,33 @@ Time range: Jan 1 – Mar 31, 2026
 Filters: S1+ pipeline, closed-lost only
 ```
-### Step 6: Save the Analysis (only when requested)
+### Step 6: Save the Dashboard Artifact (only when requested)
-Call `save-analysis` with all required fields only when the user asked for a saved/re-runnable analysis or this turn is updating an existing saved analysis:
+Call `update-dashboard` with a complete dashboard config when the user asks for a saved/re-runnable analysis or this turn is creating a durable report. If the requested report needs bespoke UI, create the extension first and include its id in an extension panel.
 ```
-save-analysis
-  --id "closed-lost-q1-2026"
-  --name "Q1 2026 Closed-Lost Analysis"
-  --description "Deep dive into 54 Fusion deals closed-lost in Q1, cross-referenced with Gong calls and Slack activity"
-  --question "Why are we losing deals in Q1? Cross-reference with Gong calls and Slack."
-  --dataSources '["hubspot", "gong", "slack"]'
-  --instructions "1. Fetch closed-lost S1+ deals from HubSpot (pipeline: Fusion, close date: Q1 2026)
-2. For each deal, fetch associated contacts and their emails
-3. Search Gong calls matching those contact emails (lookback: 6 months before close date)
-4. For top 15 deals by amount, search Slack for '{company name} fusion'
-5. Calculate: total deals, avg deal size, win rate, Gong coverage rate
-6. Break down by: lost reason, stage reached, deal size tier
-7. Highlight deals with no Gong coverage (blind spots)
-8. Save results with save-analysis using id='closed-lost-q1-2026'"
-  --resultMarkdown "[the full markdown report]"
-  --resultData '{"deals": [...], "metrics": {...}}'
+update-dashboard
+  --dashboardId "closed-lost-q1-2026"
+  --config '{"name":"Q1 2026 Closed-Lost Analysis","panels":[{"id":"findings","title":"Findings","source":"first-party","chartType":"table","width":2,"sql":"...","config":{"description":"Evidence-backed report for the requested cohort."}}]}'
 ```
-`resultData` is required. Fill it with compact structured evidence from the real data-source action results you used: row samples, aggregate metrics, match decisions, call/message IDs, short transcript/message excerpts, coded themes, sentiment labels, and explicit provider errors for any gaps. Do not include full Gong transcripts, full tool outputs, or raw provider payload dumps. If you cannot query a source, do not save a guessed analysis; report the unavailable/error result instead.
+The dashboard config must preserve compact evidence from the real data-source action results you used: row samples, aggregate metrics, match decisions, call/message IDs, short transcript/message excerpts, coded themes, sentiment labels, and explicit provider errors for any gaps. Do not include full Gong transcripts, full tool outputs, or raw provider payload dumps. If you cannot query a source, do not save guessed dashboard content; report the unavailable/error result instead.
-**Critical: Write good instructions.** The `instructions` field is what gets sent to the agent on re-run. Be specific:
+**Critical: Write good dashboard definitions.** The dashboard description/config is what the agent uses on re-run. Be specific:
 - Which actions to call with which parameters
 - What filters to apply
 - How to match records across sources
 - What metrics to calculate
 - What structure the output should have
-- End with "Save results with save-analysis using id='...'"
+- End with "Update dashboard with id='...'"
 ### Step 7: Navigate to the Result
-After saving, navigate the user to see the saved analysis:
+After saving, navigate the user to see the saved dashboard:
 ```
-navigate --view=analyses --analysisId=closed-lost-q1-2026
+navigate --view=adhoc --dashboardId=closed-lost-q1-2026
 ```
 ## Re-Running an Analysis
@@ -209,7 +195,7 @@ When a user clicks "Re-run" on a saved analysis, the agent receives:
 - The saved instructions (step-by-step)
 - The analysis ID to update
-Follow the instructions to gather fresh data, then call `save-analysis` with the same `id` to update the results. The `createdAt` timestamp is preserved; `updatedAt` is refreshed.
+Follow the instructions to gather fresh data, then call `update-dashboard` with the same `dashboardId` to update the panels/report. Existing legacy analysis deep links remain readable, but new durable results must be written to dashboards.
 If the user challenges the coverage of a chat answer or saved analysis ("why
 aren't you pulling more deals?", "where is the updated response?"), rerun the
@@ -221,21 +207,19 @@ showing it or saving it.
 | Action            | Purpose                                                          |
 | ----------------- | ---------------------------------------------------------------- |
-| `save-analysis`   | Save or update an analysis (id, name, instructions, results)     |
-| `get-analysis`    | Retrieve a saved analysis by ID                                  |
-| `list-analyses`   | List all saved analyses (id, name, description, timestamps)      |
-| `delete-analysis` | Delete a saved analysis                                          |
-| `navigate`        | Navigate to analyses view: `--view=analyses [--analysisId=<id>]` |
+| `update-dashboard` | Save or update the dashboard artifact and its panels             |
+| `get-sql-dashboard` | Retrieve a dashboard by ID                                      |
+| `list-sql-dashboards` | List dashboard artifacts                                       |
+| `navigate`        | Navigate to a dashboard: `--view=adhoc --dashboardId=<id>`       |
 ## Storage
-Analyses are stored in the SQL settings table with key prefix `adhoc-analysis-{id}`. They respect org/user scoping — org-scoped analyses are visible to all org members.
+Dashboard artifacts are stored in SQL and respect the normal dashboard access model. Legacy analyses remain in their existing SQL tables for compatibility and should not be used for new artifacts.
 API endpoints (for UI consumption):
-- `GET /api/analyses` — list all
-- `GET /api/analyses/{id}` — get one
-- `DELETE /api/analyses/{id}` — delete one
+- `GET /api/sql-dashboards` — list dashboard artifacts
+- `GET /api/sql-dashboards/{id}` — get one
 ## Best Practices
@@ -257,7 +241,7 @@ hold everything in one pass:
    from the primary source (HubSpot, BigQuery, etc.).
 2. **Chunk and persist** — process 5-10 items per iteration. For each chunk,
    write a short per-item findings note (key signals, gaps, theme tags) as an
-   intermediate result to `save-analysis` or agent scratch.
+   intermediate result to the dashboard definition or agent scratch.
 3. **Synthesize** — after all chunks are complete, read the intermediate notes
    back in and produce the final cross-item synthesis (patterns, rankings,
    themes, recommendations).

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

@@ -7,7 +7,7 @@ description: >-
 # Dashboard Management
-Dashboards are SQL-backed resources. New dashboards and analyses live in the template tables, not in settings KV rows.
+Dashboards are the canonical SQL-backed Analytics resources. New dashboards, saved analyses, reports, and bespoke extensions are represented as dashboard artifacts—not as separate user-facing Analytics objects. Legacy analysis tables and actions remain available only for compatibility.
 ## Storage
@@ -25,6 +25,15 @@ Current storage:
 Legacy settings keys such as `u:<email>:dashboard-*`, `u:<email>:sql-dashboard-*`, `o:<orgId>:sql-dashboard-*`, and `adhoc-analysis-*` are still read as a fallback and copied into SQL on access. Do not create new dashboard settings rows.
+For organization-wide consolidation, use `migrate-analytics-artifacts` first
+with `dryRun: true`. The write requires an organization owner/admin and the
+exact confirmation token `MIGRATE_ANALYTICS_ARTIFACTS`. It materializes
+organization-scoped legacy settings, creates dashboard blocks for saved
+analyses and standalone extensions, archives exact duplicates, copies shares,
+and removes legacy settings keys only after SQL rows are materialized. Source
+rows remain recoverable. Private member-only rows are intentionally outside
+this organization-scoped operation.
 Use `mutate-dashboard` for existing dashboard edits. It resolves the current
 user/org context, validates the resulting config, writes the SQL-backed record,
 syncs collab, and returns compact proof. Use `update-dashboard` for new
@@ -104,13 +113,15 @@ standard panels, supported chart types, filters, variables, sections, and grid
 layout.
 If the user asks for a dashboard or analytical surface that needs bespoke UI or
-code beyond the dashboard JSON/component model, create an extension instead.
-Examples include custom interaction flows, non-standard visualizations, complex
-multi-step workflows, highly custom layouts, custom client-side state, or a
-dashboard-like app that needs behavior the built-in renderer cannot express. In
-production mode, call `create-extension` automatically and then tell the user
-that the request needed a bespoke surface, so you built it as an extension
-rather than forcing it into a native dashboard config.
+code beyond the dashboard JSON/component model, create an extension and embed it
+in the dashboard. Examples include custom interaction flows, non-standard
+visualizations, complex multi-step workflows, highly custom layouts, custom
+client-side state, or a dashboard-like app that needs behavior the built-in
+renderer cannot express. In production mode, call `create-extension`
+automatically, then call `update-dashboard` with one or more
+`chartType: "extension"` panels using `config.extensionId`. Never leave the
+extension as a standalone Analytics result or direct the user to the Extensions
+page.
 ## Embedding An Extension As A Panel

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

@@ -36,7 +36,7 @@ through `2026-05-02T04:00:00Z`.
 ## Showing 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 `save-analysis` artifact whose markdown will render outside the app.
+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.
 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.
@@ -136,7 +136,7 @@ future analyses.
 - Before finalizing an analytics answer, make the evidence trail explicit enough
   to audit: source(s), time window, filters, sample size or row count, join or
   match method, caveats/gaps, and what action to take next when useful.
-- Data-source status, data-dictionary reads, dashboard dry-runs, `update-dashboard`, `generate-chart`, and `save-analysis` are not data queries. For analyses and dashboards, run at least one provider query action and preserve the result evidence in the final answer or `resultData`.
+- Data-source status, data-dictionary reads, dashboard dry-runs, `update-dashboard`, and `generate-chart` are not data queries. For dashboard artifacts, run at least one provider query action and preserve the result evidence in the final answer or dashboard config/description.
 - Use action arguments such as `query`, `objectType`, `properties`, `owner`, `limit`, or provider-specific filters to narrow output; if an action returns a broad batch, filter it in your analysis and cite the records used.
 - Update the relevant `.agents/skills/<provider>/SKILL.md` when you discover new patterns.
 - For BigQuery queries, check `.agents/skills/bigquery/SKILL.md` first; if the data dictionary does not contain the exact table/columns, call `search-bigquery-schema`.