@agent-native/core 0.121.2 → 0.122.0

package/corpus/templates/analytics/_gitignore

@@ -37,3 +37,4 @@ data/.sessions.json
 learnings.md
 
 .vercel/
+.agent-native/

package/corpus/templates/analytics/actions/bigquery.ts

@@ -96,10 +96,18 @@ export default defineAction({
           "BigQuery isn't connected for this workspace yet. Open Settings -> Data sources and add BIGQUERY_PROJECT_ID + GOOGLE_APPLICATION_CREDENTIALS_JSON (a service-account JSON key).",
         );
       }
-      if (
-        /BigQuery (API|poll) error/i.test(msg) ||
-        /BigQuery query timed out/i.test(msg)
-      ) {
+      // A timeout means the SQL was valid but slow. Routing it through the schema-error
+      // branch below told the model to go re-inspect the schema and rerun, which turns
+      // one slow query into a loop of 60-second attempts.
+      if (/BigQuery query timed out/i.test(msg)) {
+        return {
+          error: "bigquery_query_timeout",
+          message: extractBigQueryMessage(msg),
+          recoverable: true,
+          hint: "The SQL was valid but exceeded the 60-second warehouse budget. Do NOT inspect the schema and do NOT rerun this query as-is. Make it cheaper: narrow the date range, add a LIMIT, aggregate in SQL instead of returning raw rows, or filter on a partition/cluster column. If the full scan is genuinely required, run it through run-code with background: true instead of retrying here.",
+        };
+      }
+      if (/BigQuery (API|poll) error/i.test(msg)) {
         // Recoverable: hand the real error back to the model so it can inspect
         // the schema and self-correct, instead of force-ending the turn.
         return {

package/corpus/templates/analytics/actions/generate-chart.ts

@@ -303,16 +303,16 @@ export function renderStaticChartSvg({
  * user's chair, the chat said "I'll do something else" and no chart appeared.
  *
  * For in-chat data questions the right answer is always the live `/chart`
- * embed (see AGENTS.md "Inline Charts in Chat"). Only `save-analysis`
- * artifacts need a static image, and those flows have full data in hand
- * before they call here.
+ * embed (see the `data-querying` skill's "Inline Charts In Chat" section for
+ * the full shape). Only `save-analysis` artifacts need a static image, and
+ * those flows have full data in hand before they call here.
  */
 const CHART_FALLBACK_HINT =
-  "If you're answering an in-chat data question, do not retry generate-chart. Switch to the live /chart embed described in AGENTS.md ('Inline Charts in Chat') — it accepts a SqlPanel object directly and doesn't require pre-stringified JSON params. Only use generate-chart when you're building a save-analysis artifact.";
+  "If you're answering an in-chat data question, do not retry generate-chart. Switch to the live /chart embed instead — it accepts a SqlPanel object directly and doesn't require pre-stringified JSON params. See the data-querying skill's \"Inline Charts In Chat\" section for the embed syntax. Only use generate-chart when you're building a save-analysis artifact.";
 
 export default defineAction({
   description:
-    "Render a static chart image to the media directory **for save-analysis artifacts only**. Uses PNG when the native renderer is available and a portable SVG fallback otherwise. For an in-chat answer to a data question, do NOT call this — emit a live `/chart` embed instead (see AGENTS.md 'Inline Charts in Chat'). The static image path exists for analyses that need to render outside this app (exports, archived reports). If validation here fails, switch to the live embed rather than retrying.",
+    'Render a static chart image to the media directory **for save-analysis artifacts only**. Uses PNG when the native renderer is available and a portable SVG fallback otherwise. For an in-chat answer to a data question, do NOT call this — emit a live `/chart` embed instead (see the data-querying skill\'s "Inline Charts In Chat" section for the embed syntax). The static image path exists for analyses that need to render outside this app (exports, archived reports). If validation here fails, switch to the live embed rather than retrying.',
   schema: z.object({
     title: z.string().optional().describe("Chart title (required)"),
     labels: z.string().optional().describe("JSON array of x-axis labels"),

package/corpus/templates/analytics/app/components/dashboard/SqlChart.tsx

@@ -119,6 +119,9 @@ const CHART_LEGEND_PROPS = {
 } as const;
 
 const CHART_RESIZE_DEBOUNCE_MS = 50;
+// Recharts' default series animation duration, plus room for the debounced
+// resize callback that follows a lazy-loaded panel's first layout pass.
+const CHART_ENTRY_ANIMATION_MS = 1500 + CHART_RESIZE_DEBOUNCE_MS * 2;
 const LEGEND_ACTION_CLOSE_DELAY_MS = 600;
 
 type ChartSize = {
@@ -136,12 +139,38 @@ export function hasChartSizeChanged(
   );
 }
 
+export function shouldDisableChartAnimation(
+  entryAnimationSettled: boolean,
+  previous: ChartSize | null,
+  next: ChartSize,
+): boolean {
+  return entryAnimationSettled && hasChartSizeChanged(previous, next);
+}
+
 function useChartResizeAnimation() {
   const [isAnimationActive, setIsAnimationActive] = useState(true);
   const firstSizeRef = useRef<ChartSize | null>(null);
+  // Switching Recharts to isAnimationActive=false mid-flight freezes the line's
+  // stroke-dasharray at whatever partial length it reached, leaving the series
+  // invisible forever. Lazy-loaded panels reflow right after mounting, so the
+  // entry animation has to be allowed to finish before a resize can disable it.
+  const entryAnimationSettledRef = useRef(false);
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      entryAnimationSettledRef.current = true;
+    }, CHART_ENTRY_ANIMATION_MS);
+    return () => clearTimeout(timer);
+  }, []);
+
   const handleResize = useCallback((width: number, height: number) => {
     const nextSize = { width, height };
-    if (hasChartSizeChanged(firstSizeRef.current, nextSize)) {
+    if (
+      shouldDisableChartAnimation(
+        entryAnimationSettledRef.current,
+        firstSizeRef.current,
+        nextSize,
+      )
+    ) {
       setIsAnimationActive(false);
     }
     firstSizeRef.current = nextSize;

package/corpus/templates/analytics/app/pages/adhoc/sql-dashboard/DashboardFilterBar.tsx

@@ -259,6 +259,9 @@ export function DashboardFilterBar({
         className="group rounded-lg bg-card px-3 py-2"
       >
         <div className="flex flex-wrap items-end justify-between gap-3">
+          <span className="self-center text-xs font-medium text-muted-foreground group-data-[state=open]:hidden">
+            {t("sqlDashboard.filters")}
+          </span>
           <CollapsibleContent className="min-w-0 flex-1">
             <div className="flex flex-wrap gap-3 items-end">
               {uniqueFilters.map((f) => (

package/corpus/templates/analytics/app/pages/adhoc/sql-dashboard/SqlChartCard.tsx

@@ -272,7 +272,7 @@ export function SqlChartCard({
         data-dragging={isDragSource ? "true" : undefined}
         className="dashboard-section-card group relative mt-2 first:mt-0"
       >
-        <div className="flex items-center gap-2 border-b border-border pb-2">
+        <div className="flex items-center gap-2 pb-2">
           <h2 className="text-base font-semibold flex-1">{panel.title}</h2>
           {editable ? (
             <div className="flex items-center gap-1 opacity-0 group-hover:opacity-100">

package/corpus/templates/analytics/app/pages/adhoc/sql-dashboard/index.tsx

@@ -1538,6 +1538,7 @@ function SqlDashboardPageContent({
             resourceId={dashboardId}
             resourceTitle={dashboard.name}
             variant="compact"
+            triggerClassName="border-0 bg-accent text-accent-foreground hover:bg-accent/80 hover:text-accent-foreground"
             shareUrl={dashboardShareUrl}
             shareTabs={{
               tabs: [

package/corpus/templates/analytics/changelog/2026-07-24-analytics-finds-saved-dashboards-and-queries-far-more-reliab.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-24
+---
+
+Analytics finds saved dashboards and queries far more reliably, and answers list and cohort questions in one query instead of grinding for minutes

package/corpus/templates/analytics/changelog/2026-07-24-notion-access-errors-now-explain-that-a-page-needs-sharing-w.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-24
+---
+
+Notion access errors now explain that a page needs sharing with the integration, instead of naming an unrelated integration label

package/corpus/templates/analytics/server/lib/agent-chat-plan-mode.ts

@@ -35,6 +35,13 @@ export const INITIAL_TOOL_NAMES = [
   "bigquery",
   "search-bigquery-schema",
   "list-data-dictionary",
+  // Bulk/cohort readers. Without these on the first surface a "list X excluding Y"
+  // question cannot reach any tool that answers it in one call, so the agent pays a
+  // tool-search round trip (~15 KB of results) before it can even start — or worse,
+  // enumerates the cohort page by page through whatever it can already see.
+  "provider-api-request",
+  "query-staged-dataset",
+  "hubspot-records",
   "navigate",
 ];
 

package/corpus/templates/analytics/server/lib/analytics-query-catalog.ts

@@ -68,7 +68,8 @@ export type AnalyticsQueryCatalogCandidate =
       panelTitle: string;
       panelDescription?: string;
       source?: string;
-      query: string | Record<string, unknown>;
+      /** Absent for extension/embed panels, which are matched on title and description. */
+      query?: string | Record<string, unknown>;
       timeScope?: string;
     }
   | {
@@ -105,43 +106,135 @@ function compactQuery(value: unknown): string | Record<string, unknown> | null {
   return null;
 }
 
-function searchTerms(search: string): string[] {
-  const normalized = search
+// Analytics vocabulary the corpus spells out but users abbreviate (or vice versa).
+// Expansions match at reduced weight so they break ties without outranking a literal hit.
+const SYNONYM_EXPANSIONS: Record<string, string[]> = {
+  account: ["company", "customer", "org"],
+  active: ["engaged"],
+  arr: ["annual", "recurring", "revenue"],
+  churn: ["cancel", "attrition", "downgrade"],
+  csql: ["sale", "qualified", "lead", "opportunity"],
+  customer: ["account", "company"],
+  dau: ["daily", "active", "user"],
+  deal: ["opportunity", "pipeline"],
+  error: ["5xx", "4xx", "exception", "failure", "fault"],
+  icp: ["ideal", "customer", "profile"],
+  mau: ["monthly", "active", "user"],
+  mql: ["marketing", "qualified", "lead"],
+  mrr: ["monthly", "recurring", "revenue"],
+  pageview: ["page", "view", "traffic", "session"],
+  pipeline: ["deal", "opportunity", "forecast"],
+  poc: ["proof", "concept", "trial", "pilot"],
+  revenue: ["bookings", "arr", "mrr", "won"],
+  signup: ["registration", "created", "onboard"],
+  traffic: ["pageview", "session", "visit"],
+  usage: ["active", "engagement"],
+  user: ["member", "person", "seat"],
+  wau: ["weekly", "active", "user"],
+};
+
+// Metric-shaped words that appear in a large share of titles and so discriminate
+// almost nothing on their own. Scored down rather than dropped: "error rate" must
+// still beat "rate", but four unrelated "... Rate" entries must not tie above the
+// panel that actually matches "error".
+const LOW_INFORMATION_TERMS = new Set([
+  "average",
+  "percent",
+  "percentage",
+  "rate",
+  "ratio",
+  "score",
+  "value",
+  "volume",
+]);
+
+// Cheap plural folding. The corpus writes "Template"/"Deal" while users type
+// "templates"/"deals"; exact substring matching missed every one of those.
+function stem(token: string): string {
+  if (token.length > 4 && token.endsWith("ies"))
+    return `${token.slice(0, -3)}y`;
+  if (token.length > 4 && token.endsWith("sses")) return token.slice(0, -2);
+  if (token.length > 3 && token.endsWith("s") && !token.endsWith("ss")) {
+    return token.slice(0, -1);
+  }
+  return token;
+}
+
+// Splits camelCase and snake_case so warehouse identifiers are searchable:
+// `dim_hs_deals` -> dim, hs, deal.
+function tokenize(value: string): string[] {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, " ")
-    .trim();
-  if (!normalized) return [];
-  const meaningful = normalized
+    .trim()
     .split(/\s+/)
-    .filter((term) => term.length > 1 && !STOP_WORDS.has(term));
-  return meaningful.length ? Array.from(new Set(meaningful)) : [normalized];
+    .filter(Boolean)
+    .map(stem);
+}
+
+function searchTerms(search: string): string[] {
+  const tokens = tokenize(search);
+  if (!tokens.length) return [];
+  const meaningful = tokens.filter(
+    (term) => term.length > 1 && !STOP_WORDS.has(term),
+  );
+  return Array.from(new Set(meaningful.length ? meaningful : tokens));
+}
+
+function expandedTerms(primary: string[]): string[] {
+  const primarySet = new Set(primary);
+  const expanded = new Set<string>();
+  for (const term of primary) {
+    for (const synonym of SYNONYM_EXPANSIONS[term] ?? []) {
+      const stemmed = stem(synonym);
+      if (!primarySet.has(stemmed)) expanded.add(stemmed);
+    }
+  }
+  return [...expanded];
 }
 
+// SQL bodies run to 12k chars; scoring only needs the leading identifiers.
+const MAX_SCORED_FIELD_CHARS = 4_000;
+
 function matchScore(
   search: string,
   weightedFields: Array<{ value: unknown; weight: number }>,
 ): { score: number; matchedTerms: string[] } {
   const terms = searchTerms(search);
   if (!terms.length) return { score: 0, matchedTerms: [] };
+  const synonyms = expandedTerms(terms);
 
   const normalizedSearch = search.toLowerCase().trim();
   const matched = new Set<string>();
   let score = 0;
   for (const field of weightedFields) {
-    const value = text(field.value).toLowerCase();
-    if (!value) continue;
-    if (normalizedSearch.length > 2 && value.includes(normalizedSearch)) {
+    const raw = text(field.value).slice(0, MAX_SCORED_FIELD_CHARS);
+    if (!raw) continue;
+    const lowered = raw.toLowerCase();
+    const tokens = new Set(tokenize(raw));
+
+    if (normalizedSearch.length > 2 && lowered.includes(normalizedSearch)) {
       score += field.weight * 4;
     }
     for (const term of terms) {
-      if (!value.includes(term)) continue;
+      if (!tokens.has(term) && !lowered.includes(term)) continue;
       matched.add(term);
-      score += field.weight;
+      score += field.weight * (LOW_INFORMATION_TERMS.has(term) ? 0.3 : 1);
+    }
+    for (const synonym of synonyms) {
+      if (!tokens.has(synonym)) continue;
+      score += field.weight * 0.4;
     }
   }
 
-  if (matched.size === terms.length) score += 40;
-  return { score, matchedTerms: [...matched] };
+  // Proportional, not all-or-nothing: a 7-word question could never hit the old
+  // full-coverage bonus, so long real questions collapsed to near-random scores.
+  // Damped for short queries — at full strength every one-of-one-token match tied
+  // at the same score, so generic "... Rate" entries mass-tied above exact panels.
+  const coverageWeight = Math.min(terms.length, 3) / 3;
+  score += 40 * (matched.size / terms.length) * coverageWeight;
+  return { score: Math.round(score), matchedTerms: [...matched] };
 }
 
 function dashboardPanelCandidates(args: {
@@ -156,9 +249,15 @@ function dashboardPanelCandidates(args: {
     ? (args.config.panels as DashboardPanel[])
     : [];
 
+  const wantsDemo = /\bdemo\b|node exporter/i.test(args.search);
+
   return panels.flatMap((panel) => {
+    // 38k of the ~39k indexed panels are clones of the demo Node Exporter dashboard.
+    // They drown real saved work and are never the answer to a real data question.
+    if (!wantsDemo && text(panel.source) === "demo") return [];
+    // Panels without SQL (extensions, embeds) used to be dropped outright, which hid
+    // 61% of real dashboards from search even when their titles matched exactly.
     const query = compactQuery(panel.sql);
-    if (!query) return [];
     const panelConfig =
       panel.config &&
       typeof panel.config === "object" &&
@@ -174,20 +273,49 @@ function dashboardPanelCandidates(args: {
       { value: args.dashboardDescription, weight: 6 },
       { value: panel.source, weight: 5 },
       {
-        value: typeof query === "string" ? query : JSON.stringify(query),
-        weight: 2,
+        // Weighted 2 against a title's 24, this 12x discount hid every panel whose
+        // match lived only in its SQL — the majority of them.
+        value: query
+          ? typeof query === "string"
+            ? query
+            : JSON.stringify(query)
+          : "",
+        weight: 8,
       },
     ]);
+    // Prefer the general panel over a narrower variant ("Signups" over "Clip Share
+    // Signups 30d"), but cap it: the original uncapped -12/token buried long,
+    // well-named panels under short vague ones.
     const requestedTerms = new Set(searchTerms(args.search));
-    const titleSpecificityPenalty =
-      searchTerms(panelTitle).filter((term) => !requestedTerms.has(term))
-        .length * 12;
+    const unmatchedTitleTerms = searchTerms(panelTitle).filter(
+      (term) => !requestedTerms.has(term),
+    ).length;
+    const titleSpecificityPenalty = Math.min(unmatchedTitleTerms, 4) * 4;
+    // A panel with no SQL costs the agent another call to become useful, so it must
+    // not outrank an equally-relevant runnable one. Waived when the title is clearly
+    // on-topic: real questions carry clause words no title contains, so requiring
+    // full coverage here never fires and buries exact-topic panels.
+    const titleMatchedTerms = matchScore(args.search, [
+      { value: panelTitle, weight: 1 },
+    ]).matchedTerms;
+    const strongTitleTerms = titleMatchedTerms.filter(
+      (term) => !LOW_INFORMATION_TERMS.has(term),
+    ).length;
+    const titleIsOnTopic =
+      requestedTerms.size > 0 &&
+      (strongTitleTerms >= 2 ||
+        titleMatchedTerms.length / requestedTerms.size >= 0.6);
+    const missingQueryPenalty = query || titleIsOnTopic ? 0 : 10;
     const aggregateIntent =
       /\b(how many|count|number|total)\b/i.test(args.search) &&
       text(panel.chartType) === "metric"
         ? 20
         : 0;
-    const score = rawScore - titleSpecificityPenalty + aggregateIntent;
+    const score =
+      rawScore -
+      titleSpecificityPenalty -
+      missingQueryPenalty +
+      aggregateIntent;
     if (score <= 0) return [];
 
     return [
@@ -205,7 +333,7 @@ function dashboardPanelCandidates(args: {
         panelTitle,
         ...(panelDescription ? { panelDescription } : {}),
         ...(text(panel.source) ? { source: text(panel.source) } : {}),
-        query,
+        ...(query ? { query } : {}),
         ...(text(panelConfig.timeScope)
           ? { timeScope: text(panelConfig.timeScope) }
           : {}),
@@ -270,6 +398,26 @@ function dictionaryCandidates(
   });
 }
 
+function candidateIsRunnable(
+  candidate: AnalyticsQueryCatalogCandidate,
+): boolean {
+  return candidate.kind === "dashboard-panel"
+    ? Boolean(candidate.query)
+    : Boolean(candidate.queryTemplate);
+}
+
+function candidateDedupeKey(candidate: AnalyticsQueryCatalogCandidate): string {
+  if (candidate.kind === "data-dictionary") return `dict:${candidate.id}`;
+  const query =
+    typeof candidate.query === "string"
+      ? candidate.query
+      : JSON.stringify(candidate.query ?? "");
+  return `panel:${candidate.panelTitle.toLowerCase()}:${query
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLowerCase()}`;
+}
+
 export function rankAnalyticsQueryCatalog(args: {
   search: string;
   dashboards: Array<{
@@ -296,13 +444,26 @@ export function rankAnalyticsQueryCatalog(args: {
     ...dictionaryCandidates(args.dictionaryEntries, args.search),
   ];
 
-  return candidates
-    .sort((a, b) => {
-      if (b.score !== a.score) return b.score - a.score;
-      if (a.kind !== b.kind) return a.kind === "data-dictionary" ? -1 : 1;
-      return JSON.stringify(a).localeCompare(JSON.stringify(b));
-    })
-    .slice(0, args.limit);
+  const ranked = candidates.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    // Prefer something the agent can run over something it must look up again.
+    const aRunnable = candidateIsRunnable(a);
+    const bRunnable = candidateIsRunnable(b);
+    if (aRunnable !== bRunnable) return aRunnable ? -1 : 1;
+    if (a.kind !== b.kind) return a.kind === "data-dictionary" ? -1 : 1;
+    return JSON.stringify(a).localeCompare(JSON.stringify(b));
+  });
+
+  // Cloned dashboards produce near-identical panels that otherwise eat every slot.
+  const seen = new Set<string>();
+  const deduped: AnalyticsQueryCatalogCandidate[] = [];
+  for (const candidate of ranked) {
+    if (deduped.length >= args.limit) break;
+    if (seen.has(candidateDedupeKey(candidate))) continue;
+    seen.add(candidateDedupeKey(candidate));
+    deduped.push(candidate);
+  }
+  return deduped;
 }
 
 async function listDictionaryEntries(args: {

package/corpus/templates/analytics/server/lib/bigquery.ts

@@ -239,6 +239,8 @@ export interface QueryResult {
   schema: { name: string; type: string }[];
   bytesProcessed: number;
   cached?: boolean;
+  /** True when BigQuery matched more rows than this first page returned. */
+  truncated?: boolean;
 }
 
 export interface RunQueryOptions {
@@ -516,11 +518,19 @@ export async function runQuery(
   const rows = data.rows ? rowsToObjects(data.rows, fields) : [];
   const bytesProcessed = parseInt(data.totalBytesProcessed || "0", 10);
 
+  // BigQuery reports the full match count; `rows` only holds the first page. Reporting
+  // rows.length as the total made every partial result look complete to the agent.
+  const reportedTotal = Number.parseInt(data.totalRows || "", 10);
+  const totalRows = Number.isFinite(reportedTotal)
+    ? reportedTotal
+    : rows.length;
+
   const result: QueryResult = {
     rows,
-    totalRows: rows.length,
+    totalRows,
     schema,
     bytesProcessed,
+    ...(totalRows > rows.length ? { truncated: true } : {}),
   };
 
   setL1(cacheKey, result);

package/corpus/templates/analytics/server/lib/notion.ts

@@ -39,6 +39,19 @@ async function getApiKey(): Promise<string> {
   return credential.value;
 }
 
+// The name Notion reports for a token is whatever label its creator typed in, so it
+// routinely names an unrelated product. Never restate it as the current workspace.
+const NOTION_ACCESS_HINT =
+  "This usually means the page or database was never shared with the Notion integration behind NOTION_API_KEY, not that the id is wrong. Fix it in Notion: open the page, then ••• → Connections → add the integration. The integration's Notion-side label may not match this app or workspace.";
+
+function notionApiError(status: number, body: string): Error {
+  const suffix =
+    status === 401 || status === 403 || status === 404
+      ? ` ${NOTION_ACCESS_HINT}`
+      : "";
+  return new Error(`Notion API error ${status}: ${body}${suffix}`);
+}
+
 async function notionGet(path: string): Promise<unknown> {
   const res = await fetch(`${NOTION_API}${path}`, {
     headers: {
@@ -47,8 +60,7 @@ async function notionGet(path: string): Promise<unknown> {
     },
   });
   if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`Notion API error ${res.status}: ${text}`);
+    throw notionApiError(res.status, await res.text());
   }
   return res.json();
 }
@@ -64,8 +76,7 @@ async function notionPost(path: string, body: unknown): Promise<unknown> {
     body: JSON.stringify(body),
   });
   if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`Notion API error ${res.status}: ${text}`);
+    throw notionApiError(res.status, await res.text());
   }
   return res.json();
 }

package/corpus/templates/analytics/server/plugins/agent-chat.ts

@@ -73,6 +73,11 @@ export const NON_ANALYTICS_FALLBACK_FINAL_MESSAGE =
 export function analyticsSourceGuidanceOpening(): string {
   return (
     "<data-source-guidance>\n" +
+    // Measured in production: this ran in under 1% of data threads while the
+    // equivalent instruction sat ~7000 words deep. Threads that did call it used
+    // roughly a third the tool calls. Keep it first and keep it imperative.
+    "START HERE — For any question about a metric, cohort, list, count, or trend, your FIRST tool call is `search-analytics-query-catalog`. This is the analytics equivalent of grepping a codebase before writing new code: someone has very likely already built and saved the query you need, and its saved SQL tells you the exact source, table, and column names so you do not have to discover them. Adapt the closest saved query to the requested filters and time window, run it once, and stop. Only fall back to schema discovery or provider catalogs when the catalog search returns nothing usable — and never run more than one schema-discovery pass before querying. " +
+    'ONE BOUNDED CALL — List, filter, count, and cohort questions ("which X, excluding Y") are a single query, not a loop. Express the include filter, the exclude filter, and the aggregation in one SQL statement or one `run-code` script that filters server-side. Never page through a cohort across separate tool calls and never fan out per item to apply a filter; that is what turns a ten-second answer into a twenty-minute one. ' +
     "Apply real-data requirements only when presenting analytics results, source records, or derived metrics. Do not call data-source tools for workflow migration, recurring-job setup, UI/code fixes, settings help, conceptual planning, or other non-data tasks unless the user explicitly asks for data. " +
     NON_ANALYTICS_REQUEST_GUIDANCE +
     BOUNDED_STRUCTURED_LOOKUP_GUIDANCE +
@@ -734,6 +739,11 @@ export default createAgentChatPlugin({
       "Analytics has one user-facing artifact type: dashboards. Dashboards are JSON configs rendered by the built-in dashboard components, and an extension is a dashboard block—not a separate Analytics result. " +
       'If the user\'s requested dashboard, saved analysis/report, visualization, interaction model, custom layout, or bespoke workflow cannot be faithfully represented within the native dashboard components/config fields, do not hand-wave, force an approximate JSON dashboard, or route to source-code changes. In production mode, automatically create a sandboxed extension with `create-extension`, then immediately call `update-dashboard` to embed it as one or more `chartType: "extension"` panels with `config.extensionId`. ' +
       "After creating the dashboard, briefly tell the user that a dashboard block uses an embedded extension because the request needed bespoke UI/code. Never leave a newly created extension standalone, never create a separate saved analysis for the same request, and never direct the user to an Extensions page from Analytics. Legacy analyses may be read or updated only for compatibility with an existing deep link.\n" +
+      // The extension-first default above is deliberate, but it must not swallow
+      // an explicit ask for a code change: without this carve-out the agent
+      // silently substitutes an extension for "open a PR adding a dual-axis
+      // chart type" and the user never learns the handoff exists.
+      "That extension-first default governs what you build on your own initiative. It does not override an explicit request for a source-code change: when the user asks for the capability natively in the product, asks to change app chrome or a shared component, or asks for a PR, branch, or code change in so many words, call `connect-builder` with their request verbatim instead of substituting an extension. When you have just built an extension for something that plainly belongs in the product — a chart type or interaction other dashboards would reuse — add one sentence offering the `connect-builder` handoff, and only call it if they take you up on it.\n" +
       "</analytics-artifact-guidance>";
 
     return `${sourceGuidance}\n\n${artifactGuidance}\n\n${analyticsDataDictionaryRoutingContext()}`;

package/corpus/templates/assets/.agents/skills/upgrade-agent-native/SKILL.md

@@ -56,7 +56,29 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    - Runs `skills update scaffold --project`
    - Runs `typecheck` when the project has that script
 
-3. **If upgrade or typecheck fails**
+3. **Pull upstream template changes (optional, separate from the bump)**
+
+   `agent-native upgrade` moves package versions. It never touches files that
+   were copied out of a template at scaffold time, so template fixes and
+   improvements do not arrive with a bump.
+
+   ```bash
+   agent-native template status        # recorded ref vs latest, drift counts
+   agent-native template diff          # what upstream changed, read-only
+   agent-native template sync          # 3-way merge it into the app
+   ```
+
+   `sync` defaults to the ref matching the installed `@agent-native/core`, so
+   run it after `upgrade`. It merges per file against a pristine baseline
+   stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
+   did not touch are left alone, and real collisions get conflict markers.
+   After resolving markers, run `agent-native template accept` — the baseline
+   deliberately does not advance past an unresolved merge.
+
+   Apps scaffolded before provenance existed have no baseline. Create one
+   with `agent-native template baseline` before the first sync.
+
+4. **If upgrade or typecheck fails**
 
    - Read the concrete error
    - Fix **app** source, actions, config, or env — not framework packages
@@ -68,7 +90,7 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    copied component; do not use that path to reproduce framework runtime
    behavior or hide version skew.
 
-4. **Dry-run / partial runs**
+5. **Dry-run / partial runs**
 
    ```bash
    agent-native upgrade --dry-run

package/corpus/templates/brain/.agents/skills/upgrade-agent-native/SKILL.md

@@ -56,7 +56,29 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    - Runs `skills update scaffold --project`
    - Runs `typecheck` when the project has that script
 
-3. **If upgrade or typecheck fails**
+3. **Pull upstream template changes (optional, separate from the bump)**
+
+   `agent-native upgrade` moves package versions. It never touches files that
+   were copied out of a template at scaffold time, so template fixes and
+   improvements do not arrive with a bump.
+
+   ```bash
+   agent-native template status        # recorded ref vs latest, drift counts
+   agent-native template diff          # what upstream changed, read-only
+   agent-native template sync          # 3-way merge it into the app
+   ```
+
+   `sync` defaults to the ref matching the installed `@agent-native/core`, so
+   run it after `upgrade`. It merges per file against a pristine baseline
+   stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
+   did not touch are left alone, and real collisions get conflict markers.
+   After resolving markers, run `agent-native template accept` — the baseline
+   deliberately does not advance past an unresolved merge.
+
+   Apps scaffolded before provenance existed have no baseline. Create one
+   with `agent-native template baseline` before the first sync.
+
+4. **If upgrade or typecheck fails**
 
    - Read the concrete error
    - Fix **app** source, actions, config, or env — not framework packages
@@ -68,7 +90,7 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    copied component; do not use that path to reproduce framework runtime
    behavior or hide version skew.
 
-4. **Dry-run / partial runs**
+5. **Dry-run / partial runs**
 
    ```bash
    agent-native upgrade --dry-run

package/corpus/templates/brain/_gitignore

@@ -10,3 +10,4 @@ data/*.db-shm
 data/*.db-wal
 .env
 .env.local
+.agent-native/