@agent-native/core 0.154.4 → 0.155.0

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 8212
+- template files: 8236

package/corpus/templates/analytics/.agents/skills/account-health/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: account-health
+description: >-
+  How to produce a trustworthy named-customer account health, QBR, renewal, or
+  contract-usage readout. Use when a prompt names an organization or account.
+---
+
+# Account Health
+
+Use these checks for named customer, organization, account-health, QBR,
+renewal, risk, expansion, contract-utilization, or adoption questions. This is
+not an ordinary metric lookup: a wrong identity or metric definition can put
+another customer's data into a customer-facing decision.
+
+## Identity lock
+
+Treat an organization ID supplied in a prompt as a lookup key, not as proof that
+the rows returned by a warehouse query belong to that customer.
+
+1. Resolve the ID through the canonical CRM or contract source first.
+2. Record the resolved customer name, organization ID, root organization ID,
+   and any canonical account key.
+3. Carry the same resolved identity through every usage query and check the
+   returned rows against it.
+4. Stop and report an identity mismatch if a result contains another customer,
+   mixed organization IDs, or an unresolved ID. Do not summarize the rows or
+   silently choose the most plausible customer.
+
+## Source order and completeness
+
+1. Use the catalog and organization data dictionary before writing warehouse
+   SQL. Approved definitions and saved query shapes outrank a table name that
+   merely sounds right.
+2. Gather available CRM, contract, support, and conversation evidence. Treat
+   that context as complementary, not as a complete usage result.
+3. For account health, product usage is mandatory: query approved definitions
+   for each requested product or feature dimension separately, using an explicit
+   window (default 90 days for adoption unless the user asks for another one).
+4. Report source, window, filters, row counts, identity join, freshness, and
+   gaps. A missing source is a gap, not a reason to fill in a plausible value.
+
+## Metric contracts
+
+- **Contract metric** - distinguish the contracted measure from similarly named
+  platform, web, content, or event metrics. Do not use a familiar synonym when
+  comparing against a contract.
+- **Completed-month usage** - “last month” excludes the current partial month.
+  Verify the month/as-of field and freshness before using a reporting table;
+  a single current-month snapshot is not last month's completed value.
+- **Seats** - use the total distinct contracted/eligible users for the stated
+  period when comparing with a seat contract. Do not substitute DAU, WAU, or a
+  point-in-time daily active count, and label active users separately.
+- **Capacity usage** - report actual usage, contracted capacity, and utilization.
+  Explicitly flag utilization at or above 100% as an overage risk and potential
+  renewal/expansion signal.
+- **Adoption** - keep separate products or feature dimensions separate. Include
+  feature adoption, active-user/session counts, and last activity only when the
+  source query returns them; absence claims require complete coverage for the
+  stated window.
+
+## Known source traps
+
+- If a saved query or dictionary entry is marked deprecated or retired, do not
+  run it; use the current approved replacement and note the stale reference.
+- A source that returns only one current partial-period snapshot is not proof of
+  a completed-period value. Verify the period/as-of field and freshness first.
+- If the dictionary does not define the requested contract metric or the
+  replacement source cannot be verified, ask or report the gap instead of
+  guessing from a similarly named table.
+
+## Answer shape
+
+Lead with the identity check, then provide a compact table of contract versus
+actual usage, followed by product/feature adoption signals, account context,
+risks, and next steps. Make every number traceable to one source and explicitly
+say when the readout is partial.

package/corpus/templates/analytics/.agents/skills/bigquery/SKILL.md

@@ -69,6 +69,9 @@ answers the question.
 -- Or for TIMESTAMP columns: WHERE event_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
 ```
 
+For account health, verify the reporting period, as-of field, and freshness.
+Never label a current partial-month snapshot as last month's completed usage.
+
 ## Actions
 
 | Action                                  | Use                                                                 |

package/corpus/templates/analytics/.agents/skills/cross-source-analysis/SKILL.md

@@ -29,7 +29,8 @@ For any question about a specific customer account, follow this source order:
 Not every source is needed for every question — start with the primary source
 and add secondary sources only when the question requires them. But do not
 stop at one source for a "deep dive" — at minimum pull CRM + Gong + product
-usage for any account health question.
+usage for any account health question. Read `account-health` for the identity
+lock and contract-metric rules before querying the warehouse.
 
 ## 1. Plan Before You Query (Catalog-First)
 

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

@@ -12,11 +12,12 @@ The analytics app connects to multiple data sources. This skill covers general p
 ## Approach
 
 0. **Orient catalog-first** — before querying, consult what already exists: the injected `<data-dictionary>` and data-source status tell you which sources are configured and which table/columns/join paths to use. Use them to pick the one source that owns the fact instead of fanning out blind queries.
-1. **Read the relevant provider skill first** — check `.agents/skills/<provider>/SKILL.md` for table names, column mappings, auth, and gotchas. For BigQuery, read `.agents/skills/bigquery/SKILL.md` and use `search-bigquery-schema` before guessing table or column names.
-2. **Clarify if ambiguous** — if the metric definition, date range, or grain is unclear and a wrong guess would change the numbers, use the `ask-question` clarifying tool (multiple-choice) before querying. Ask at most once per turn; skip it when the dictionary or the user already answered.
-3. **Use existing actions or connected provider MCP tools** — call the provider action/tool with structured arguments, then filter or aggregate the returned records in your answer
-4. **Write ad-hoc scripts** — if no existing script covers the question, create one in `actions/`
-5. **Present data in chat** — don't just say "check the dashboard" — actually query, get the data, and present it. Only present numbers you actually retrieved; never report a value you did not query.
+1. **Route named account health deliberately** — for a customer/org health, QBR, renewal, contract-utilization, risk, or adoption request, read `account-health` before writing SQL. It adds identity-lock and metric-definition checks that an ordinary lookup does not need.
+2. **Read the relevant provider skill first** — check `.agents/skills/<provider>/SKILL.md` for table names, column mappings, auth, and gotchas. For BigQuery, read `.agents/skills/bigquery/SKILL.md` and use `search-bigquery-schema` before guessing table or column names.
+3. **Clarify if ambiguous** — if the metric definition, date range, or grain is unclear and a wrong guess would change the numbers, use the `ask-question` clarifying tool (multiple-choice) before querying. Ask at most once per turn; skip it when the dictionary or the user already answered.
+4. **Use existing actions or connected provider MCP tools** — call the provider action/tool with structured arguments, then filter or aggregate the returned records in your answer
+5. **Write ad-hoc scripts** — if no existing script covers the question, create one in `actions/`
+6. **Present data in chat** — don't just say "check the dashboard" — actually query, get the data, and present it. Only present numbers you actually retrieved; never report a value you did not query.
 
 For events recorded by the analytics template itself via its `/track` endpoint, use `pnpm action query-agent-native-analytics --sql "SELECT ... FROM analytics_events ..."`. This includes pageviews, site/app traffic, template usage, app usage, and event counts collected by this analytics app. Pageviews and traffic can also live in GA4, BigQuery/warehouse tables, Mixpanel, PostHog, Amplitude, or another configured provider, so choose the source from the user's wording, connected-source status, existing dashboards, data dictionary, and user/org resources. Ask one concise clarification if multiple configured sources are plausible. Do not use `db-query` for data-source analysis; `db-query` is only for internal app tables and will confuse analytics questions. The shipped `agent-native-templates-first-party` SQL dashboard is the template engagement dashboard for the first-party collector source.
 

package/corpus/templates/analytics/AGENTS.md

@@ -11,6 +11,8 @@ Read the relevant skill before deeper work:
 - `data-querying` for source inspection, SQL generation, result handling, and
   `/chart` embeds; `bigquery`, `hubspot`, `gong`, `prometheus` for provider
   specifics.
+- `account-health` for named customer health, QBR, renewal, contract usage,
+  identity, and product adoption.
 - `cross-source-analysis` for questions spanning sources (identity stitching,
   de-duplication).
 - `dashboard-management` for dashboard/panel storage, layout, extensions,
@@ -64,6 +66,7 @@ Read the relevant skill before deeper work:
   suggest and wait otherwise. Scope them to the question, avoid decorative
   metrics, and never modify existing dashboards without a directive.
 - For named account/deal deep dives, call `account-deep-dive` first.
+- For named account health, read `account-health` before querying.
 - When the user challenges coverage or asks why records are missing, rerun from
   the source cohort and include the updated answer directly — never claim a
   revision you didn't produce.

package/corpus/templates/analytics/actions/account-deep-dive.ts

@@ -362,7 +362,7 @@ async function loadGongEvidence(options: {
 
 export default defineAction({
   description:
-    "Build a Fusion-quality account/deal deep-dive evidence bundle from HubSpot and Gong in one bounded read-only call. Use this first for named account, customer, deal, opportunity, renewal, risk, or 'deep dive' prompts before synthesizing the answer.",
+    "Build a bounded CRM/Gong account or deal evidence bundle from HubSpot and Gong. Use this first for named account, customer, deal, opportunity, renewal, risk, or deep-dive prompts. This is not a complete account-health result: for account health, follow it with verified product-usage queries for the resolved customer using the account-health skill.",
   schema: z.object({
     query: z
       .string()
@@ -602,10 +602,11 @@ export default defineAction({
         emailCount: emails.length,
         gongCallCount: gong.calls.length,
         transcriptCount: gong.transcripts.length,
+        productUsageIncluded: false,
         gaps,
       },
       guidance:
-        "Synthesize a Fusion-style deal deep dive from this evidence. Include: executive summary, company/deal overview, key contacts and roles, dated timeline, Gong conversation evidence with call dates/titles, current state and risk assessment, likely blockers, recommended next steps, and methodology/gaps. Attribute every claim to HubSpot or Gong evidence and distinguish customer statements from internal notes.",
+        "Synthesize a CRM/Gong deal deep dive from this evidence. Include: executive summary, company/deal overview, key contacts and roles, dated timeline, Gong conversation evidence with call dates/titles, current state and risk assessment, likely blockers, recommended next steps, and methodology/gaps. Attribute every claim to HubSpot or Gong evidence and distinguish customer statements from internal notes. This bundle does not include product usage, contract utilization, adoption, or cross-source identity validation; for account health, run the account-health checks and report those gaps until verified usage evidence is present.",
     };
   },
 });

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

@@ -69,7 +69,7 @@ function stopForBigQueryCancellation(): never {
 
 export default defineAction({
   description:
-    "Query the user-configured BigQuery data warehouse. Use this when the user asks for warehouse SQL, BigQuery, or a data-dictionary metric/table that lives in BigQuery. If the user names a provider action such as Jira or Pylon, use that provider action first and do not use BigQuery unless the user explicitly asks for a warehouse copy. Pass standard SQL via the `sql` arg. Do NOT use `db-query` for warehouse data (it only reaches the app's own SQL database). If a query fails with a schema or SQL error (unknown dataset/table/column, syntax), treat it as a normal debugging signal: inspect the real schema with `search-bigquery-schema` (or query INFORMATION_SCHEMA), correct the query based on the error, and run it again — a few corrective attempts are expected. Surface the error to the user only if it still fails after a few attempts or is non-recoverable (missing credentials, permission, quota). Never rerun identical failing SQL, and never substitute made-up numbers for data you could not query.",
+    "Query the user-configured BigQuery data warehouse. Use this when the user asks for warehouse SQL, BigQuery, or a data-dictionary metric/table that lives in BigQuery. If the user names a provider action such as Jira or Pylon, use that provider action first and do not use BigQuery unless the user explicitly asks for a warehouse copy. For a named customer or organization ID, resolve the canonical CRM/contract identity first and verify the returned rows carry the same customer and org/root-org identifiers. For account health, distinguish completed-month usage from current partial snapshots, contract metrics from similarly named platform metrics, total distinct contracted users from DAU/WAU, and actual usage from contracted capacity. Pass standard SQL via the `sql` arg. Do NOT use `db-query` for warehouse data (it only reaches the app's own SQL database). If a query fails with a schema or SQL error (unknown dataset/table/column, syntax), treat it as a normal debugging signal: inspect the real schema with `search-bigquery-schema` (or query INFORMATION_SCHEMA), correct the query based on the error, and run it again — a few corrective attempts are expected. Surface the error to the user only if it still fails after a few attempts or is non-recoverable (missing credentials, permission, quota). Never rerun identical failing SQL, and never substitute made-up numbers for data you could not query.",
   schema: z.object({
     sql: z.string().describe("SQL query to execute"),
   }),

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

@@ -231,6 +231,9 @@ export function formatSqlChartError(error: unknown): string {
   if (/inactivity timeout|too much time has passed/i.test(readableMessage)) {
     return "This chart took too long to load. Try again.";
   }
+  if (/abort(?:ed|ing)?|signal is aborted/i.test(readableMessage)) {
+    return "This chart load was interrupted. Try again.";
+  }
   if (/internal server error/i.test(readableMessage)) {
     return "This chart could not be loaded. Try again.";
   }
@@ -1381,7 +1384,7 @@ export function SqlChart({
         className={`flex flex-1 flex-col items-center justify-center gap-3 px-4 ${placeholderPadY} ${placeholderMinH}`}
         role="alert"
       >
-        <p className="text-center text-sm text-red-400 break-all">
+        <p className="text-center text-sm text-destructive break-words">
           {formatSqlChartError(error)}
         </p>
         <Button

package/corpus/templates/analytics/app/components/layout/NewDashboardDialog.tsx

@@ -79,6 +79,7 @@ export function NewDashboardDialog({
         <PromptComposer
           autoFocus
           disabled={isGenerating}
+          layoutVariant="compact"
           placeholder={t("dialogs.newDashboardPlaceholder")}
           draftScope="analytics:new-dashboard"
           onSubmit={handleSubmit}

package/corpus/templates/analytics/app/pages/adhoc/explorer/components/PropertyCombobox.tsx

@@ -19,6 +19,7 @@ import {
 import { Skeleton } from "@/components/ui/skeleton";
 import { cn } from "@/lib/utils";
 
+import { formatExplorerPropertyLabel } from "../property-label";
 import { KNOWN_PROPERTIES, ENRICHED_PROPERTY_MAP } from "../types";
 import { useDynamicProperties } from "../use-dynamic-schema";
 
@@ -66,6 +67,11 @@ export function PropertyCombobox({
     setOpen(false);
   };
 
+  const displayLabel = useMemo(() => {
+    if (!value) return null;
+    return formatExplorerPropertyLabel(value);
+  }, [value]);
+
   return (
     <Popover open={open} onOpenChange={setOpen}>
       <PopoverTrigger asChild>
@@ -77,12 +83,12 @@ export function PropertyCombobox({
           size="sm"
         >
           <span className="truncate">
-            {value || triggerLabel || t("explorer.selectProperty")}
+            {displayLabel || triggerLabel || t("explorer.selectProperty")}
           </span>
           <IconSelector className="ml-1 h-3 w-3 shrink-0 opacity-50" />
         </Button>
       </PopoverTrigger>
-      <PopoverContent className="w-[280px] p-0" align="start">
+      <PopoverContent className="w-[320px] p-0" align="start">
         <Command shouldFilter={true}>
           <CommandInput
             placeholder={t("explorer.searchOrTypeProperty")}
@@ -137,7 +143,7 @@ export function PropertyCombobox({
                           value === prop ? "opacity-100" : "opacity-0",
                         )}
                       />
-                      {enriched?.label ?? prop}
+                      {enriched?.label ?? formatExplorerPropertyLabel(prop)}
                       {enriched && (
                         <span className="ml-auto text-[9px] bg-primary/10 text-primary px-1.5 py-0.5 rounded">
                           {t("explorer.joined")}
@@ -166,7 +172,9 @@ export function PropertyCombobox({
                         value === p.name ? "opacity-100" : "opacity-0",
                       )}
                     />
-                    <span className="truncate">{p.name}</span>
+                    <span className="truncate">
+                      {formatExplorerPropertyLabel(p.name)}
+                    </span>
                     <span className="ml-auto text-[10px] text-muted-foreground">
                       {p.count.toLocaleString()}
                     </span>

package/corpus/templates/analytics/app/pages/adhoc/explorer/components/PropertyValueCombobox.tsx

@@ -19,6 +19,7 @@ import {
 import { Skeleton } from "@/components/ui/skeleton";
 import { cn } from "@/lib/utils";
 
+import { formatExplorerPropertyLabel } from "../property-label";
 import { usePropertyValues } from "../use-dynamic-schema";
 
 interface PropertyValueComboboxProps {
@@ -61,7 +62,7 @@ export function PropertyValueCombobox({
           )}
         </Button>
       </PopoverTrigger>
-      <PopoverContent className="w-[240px] p-0" align="start">
+      <PopoverContent className="w-[280px] p-0" align="start">
         <Command shouldFilter={true}>
           <CommandInput
             placeholder={t("explorer.searchOrTypeValue")}
@@ -96,7 +97,9 @@ export function PropertyValueCombobox({
             </CommandEmpty>
             {values.length > 0 && (
               <CommandGroup
-                heading={t("explorer.topValuesForProperty", { property })}
+                heading={t("explorer.topValuesForProperty", {
+                  property: formatExplorerPropertyLabel(property),
+                })}
               >
                 {values.map((v) => (
                   <CommandItem

package/corpus/templates/analytics/app/pages/adhoc/explorer/property-label.ts

@@ -0,0 +1,32 @@
+const PROPERTY_ACRONYMS: Record<string, string> = {
+  api: "API",
+  fbclid: "FBCLID",
+  gclid: "GCLID",
+  id: "ID",
+  url: "URL",
+  utm: "UTM",
+};
+
+export function formatExplorerPropertyLabel(property: string): string {
+  const trimmed = property.trim();
+  if (!trimmed) return property;
+
+  const spaced = trimmed
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (!spaced) return property;
+
+  return spaced
+    .split(" ")
+    .map((word, index) => {
+      const lower = word.toLowerCase();
+      return (
+        PROPERTY_ACRONYMS[lower] ??
+        (index === 0 ? lower.charAt(0).toUpperCase() + lower.slice(1) : lower)
+      );
+    })
+    .join(" ");
+}

package/corpus/templates/analytics/changelog/2026-08-13-account-health-readouts-verify-customer-scope-and-contract-metrics.md

@@ -0,0 +1,7 @@
+---
+type: fixed
+date: 2026-08-13
+---
+
+Account health readouts now verify customer identity, completed usage periods,
+contract metrics, and product adoption before summarizing.

package/corpus/templates/analytics/server/jobs/analytics-bigquery-backfill.ts

@@ -20,8 +20,8 @@ const DEFAULT_MAX_BATCHES_PER_SWEEP = 4;
 const MAX_BATCHES_PER_SWEEP = 4;
 const DEFAULT_PARALLELISM = 8;
 const MAX_PARALLELISM = 8;
-const DEFAULT_MAX_ACTIVE_SESSIONS = 80;
 const DEFAULT_MAX_TOTAL_SESSIONS = 250;
+const PRESSURE_RETRY_MS = 60 * 1000;
 
 type Query =
   | string
@@ -813,7 +813,7 @@ export async function queueFirstPartyAnalyticsBigQueryBackfill(
 
 async function pressureSnapshot(
   db: Executor,
-): Promise<{ paused: boolean; reason?: string }> {
+): Promise<{ paused: boolean; degraded?: boolean; reason?: string }> {
   if (!isPostgres()) return { paused: false };
   try {
     const result = await db.execute({
@@ -833,15 +833,11 @@ async function pressureSnapshot(
     const active = numberValue(row, "active_sessions");
     const waiting = numberValue(row, "waiting_sessions");
     const lockWaiters = numberValue(row, "lock_waiters");
-    const maxActive = positiveEnvNumber(
-      "ANALYTICS_BIGQUERY_BACKFILL_MAX_ACTIVE_SESSIONS",
-      DEFAULT_MAX_ACTIVE_SESSIONS,
-    );
     const maxTotal = positiveEnvNumber(
       "ANALYTICS_BIGQUERY_BACKFILL_MAX_TOTAL_SESSIONS",
       DEFAULT_MAX_TOTAL_SESSIONS,
     );
-    if (lockWaiters > 0 || active >= maxActive || total >= maxTotal) {
+    if (lockWaiters > 0 || waiting >= 8 || total >= maxTotal) {
       return {
         paused: true,
         reason: `database pressure: total=${total}, active=${active}, waiting=${waiting}, lockWaiters=${lockWaiters}`,
@@ -850,20 +846,51 @@ async function pressureSnapshot(
     return { paused: false };
   } catch (error) {
     return {
-      paused: true,
+      paused: false,
+      degraded: true,
       reason: `pressure probe failed: ${error instanceof Error ? error.message : String(error)}`,
     };
   }
 }
 
+async function recordPressurePause(
+  db: Executor,
+  jobId: string | null,
+  reason: string,
+): Promise<void> {
+  if (!jobId) return;
+  const retryAt = new Date(Date.now() + PRESSURE_RETRY_MS).toISOString();
+  await db.execute({
+    sql: `UPDATE ${JOB_TABLE}
+             SET last_error = ?, next_run_at = ?, updated_at = ?
+           WHERE id = ? AND status <> 'completed'`,
+    args: [reason.slice(0, 1_000), retryAt, new Date().toISOString(), jobId],
+    timeoutMs: 5_000,
+    maxAttempts: 1,
+  });
+}
+
 export async function runFirstPartyAnalyticsBigQueryBackfillOnce(): Promise<BigQueryBackfillSweepResult> {
   if (process.env.ANALYTICS_BIGQUERY_BACKFILL_JOBS?.trim() === "0") {
     return { status: "disabled", batches: 0, copied: 0, remaining: 0 };
   }
 
   const db = executor();
+  const coordinator = await getNextFirstPartyAnalyticsBigQueryBackfillJob(
+    db,
+    new Date().toISOString(),
+  );
+  if (!coordinator) {
+    return { status: "idle", batches: 0, copied: 0, remaining: 0 };
+  }
+
   const initialPressure = await pressureSnapshot(db);
   if (initialPressure.paused) {
+    await recordPressurePause(
+      db,
+      coordinator.id,
+      initialPressure.reason ?? "database pressure",
+    );
     return {
       status: "paused-pressure",
       batches: 0,
@@ -873,21 +900,19 @@ export async function runFirstPartyAnalyticsBigQueryBackfillOnce(): Promise<BigQ
     };
   }
 
-  const coordinator = await getNextFirstPartyAnalyticsBigQueryBackfillJob(
-    db,
-    new Date().toISOString(),
-  );
-  if (!coordinator) {
-    return { status: "idle", batches: 0, copied: 0, remaining: 0 };
-  }
-
   await ensureBackfillShards(db, coordinator);
 
   let batches = 0;
   let copied = 0;
+  let degraded = initialPressure.degraded === true;
   for (let index = 0; index < maxBatchesPerSweep(); index += 1) {
     const pressure = await pressureSnapshot(db);
     if (pressure.paused) {
+      await recordPressurePause(
+        db,
+        coordinator.id,
+        pressure.reason ?? "database pressure",
+      );
       return {
         status: "paused-pressure",
         batches,
@@ -896,10 +921,11 @@ export async function runFirstPartyAnalyticsBigQueryBackfillOnce(): Promise<BigQ
         reason: pressure.reason,
       };
     }
+    degraded ||= pressure.degraded === true;
 
     const claimed = (
       await Promise.all(
-        Array.from({ length: parallelism() }, () =>
+        Array.from({ length: degraded ? 1 : parallelism() }, () =>
           claimNextShard(db, coordinator.id, new Date().toISOString()),
         ),
       )

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

@@ -11,6 +11,12 @@ import {
 const DATA_DICTIONARY_KEY_PREFIX = "data-dict-";
 const MAX_QUERY_LENGTH = 12_000;
 const MAX_CATALOG_DASHBOARD_HYDRATION = 24;
+const RETIRED_CATALOG_STATES = new Set([
+  "deprecated",
+  "obsolete",
+  "removed",
+  "retired",
+]);
 const STOP_WORDS = new Set([
   "a",
   "all",
@@ -61,6 +67,15 @@ const STOP_WORDS = new Set([
 type DictionaryEntry = Record<string, unknown>;
 type DashboardPanel = Record<string, unknown>;
 
+function isRetiredCatalogReference(value: Record<string, unknown>): boolean {
+  if (value.deprecated === true) return true;
+  return [value.status, value.lifecycle, value.state].some(
+    (candidate) =>
+      typeof candidate === "string" &&
+      RETIRED_CATALOG_STATES.has(candidate.trim().toLowerCase()),
+  );
+}
+
 export type AnalyticsQueryCatalogCandidate =
   | {
       kind: "dashboard-panel";
@@ -296,6 +311,7 @@ function dashboardPanelCandidates(args: {
   const wantsDemo = /\bdemo\b|node exporter/i.test(args.search);
 
   return panels.flatMap((panel) => {
+    if (isRetiredCatalogReference(panel)) return [];
     // 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 [];
@@ -391,6 +407,7 @@ function dictionaryCandidates(
   search: string,
 ): AnalyticsQueryCatalogCandidate[] {
   return entries.flatMap((entry) => {
+    if (isRetiredCatalogReference(entry)) return [];
     const { score, matchedTerms } = matchScore(search, [
       { value: entry.metric, weight: 28 },
       { value: entry.commonQuestions, weight: 16 },

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

@@ -105,6 +105,9 @@ function hasPartialDashboardBuild(
 export const BOUNDED_STRUCTURED_LOOKUP_GUIDANCE =
   "BOUNDED STRUCTURED LOOKUP FAST PATH — Treat existing analytics work like an engineer treats existing code: grep before writing. For an ordinary count, aggregate, grouped metric, trend, or record lookup, first call `search-analytics-query-catalog` once with focused metric/entity terms. It searches accessible dashboard names, chart titles/descriptions/saved queries, shipped dashboard patterns, and data-dictionary definitions together. Prefer the strongest approved dictionary or saved-chart match, preserve its source and business logic, adapt only the requested filters and explicit time window, then run one bounded query against that source. A user-named source wins, but still use a matching saved definition when it supplies the source's proven query shape. If there is no useful match, inspect only the most likely source schema or ask one clarification; do not fan out across providers. Do not separately list every dashboard, call data-source status, browse the whole dictionary, load provider catalogs/corpus tools, or query a second source after a strong match. Once the query succeeds, answer immediately with its source, time window, filters, row count, and only necessary caveats. Do not enrich, cross-check, retry, or add breakdowns unless the user requested them, the first query failed, or its result conflicts with the known definition. The words `all`, `total`, or `exact` in a structured aggregate do not by themselves make it a corpus investigation. Never repeat an identical invalid or failed tool call; correct its arguments once or surface the error. This does not waive the real-data requirement: never answer from a guess, stale value, or unverified result. ";
 
+export const ANALYTICS_ACCOUNT_HEALTH_GUIDANCE =
+  "ACCOUNT HEALTH / CUSTOMER SCOPE GUARD — Use this for a named customer, organization ID, account-health, QBR, renewal, contract-usage, risk, or adoption request. Treat a prompt-supplied org ID as a lookup key, not proof of row ownership: resolve it against canonical account data first, carry the resolved customer name plus organization/root-organization identifiers through every usage query, and stop if results contain a different customer, mixed IDs, or an unresolved identity. Use the account-health skill. Account health is incomplete until verified usage queries cover each requested product or feature dimension separately. Before warehouse SQL, use the catalog/dictionary and schema metadata. Do not run definitions marked deprecated or retired, or use a source whose freshness cannot be verified; use the current approved definition instead. Do not call a current partial-period snapshot a completed period without proving the period/as-of row and freshness. Distinguish contract metrics from similarly named platform metrics, total distinct contracted users from DAU/WAU, and actual usage from contracted capacity. Always surface utilization at or above 100%, report adoption window and coverage, and state gaps instead of inferring them. ";
+
 export const DASHBOARD_REFERENCE_GUIDANCE =
   "DASHBOARD REFERENCE DISCOVERY — When the user asks to replicate, clone, or adapt an existing dashboard, this branch takes precedence over the ordinary metric fast path: call `search-dashboard-references` with focused terms before creating, editing, or querying anything. It searches accessible active saved dashboard ids, names, descriptions, and serialized config with bounded SQL wildcard matches, including legacy saved dashboards. Treat each result as a reference to inspect with `get-sql-dashboard` when `kind` is `sql` or `get-explorer-dashboard` when `kind` is `explorer`, not as proof that its source is authoritative for the new request. Do not automatically route a replication request to first-party Analytics or copy its source semantics without checking the user's requested provider and scope. ";
 
@@ -156,6 +159,7 @@ export function analyticsSourceGuidanceOpening(): string {
     NON_ANALYTICS_REQUEST_GUIDANCE +
     DASHBOARD_REFERENCE_GUIDANCE +
     BOUNDED_STRUCTURED_LOOKUP_GUIDANCE +
+    ANALYTICS_ACCOUNT_HEALTH_GUIDANCE +
     BUILT_IN_FIRST_PARTY_SOURCE_GUIDANCE +
     ANALYTICS_OBSERVABILITY_INCIDENT_GUIDANCE +
     `DATA-SOURCE SETUP UX — Chat remains available when no external data source is connected. For a live-data request that needs an unavailable external provider, explain what is missing in the context of the user's question and guide them naturally to [Connect data sources](${ANALYTICS_DATA_SOURCES_LINK}). Use that real link from the app; do not emit a generic canned no-data sentence. For general conversation, conceptual questions, and questions the built-in first-party source can answer, continue helping normally. ` +

package/corpus/templates/calendar/AGENTS.md

@@ -24,6 +24,8 @@ Detailed event, availability, booking, storage, and UI rules live in
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Use actions for events, availability, booking links, settings, navigation,
   Google Calendar connection, and sharing. Do not bypass app access checks.
+- The `get-settings` and `update-settings` actions expose the General week-start
+  setting as `weekStart`: `sunday` or `monday`.
 - Use `connect-google-calendar` when the user asks to connect or reconnect
   Google Calendar. Return its link to the user; do not `fetch`
   `/_agent-native/google/auth-url` from the agent backend because that route

package/corpus/templates/calendar/DEVELOPING.md

@@ -99,10 +99,10 @@ Structured data lives in SQL. Use `@agent-native/core/db/schema` helpers for sch
 
 Configuration lives in the SQL `settings` table, accessed via the settings API:
 
-| Key                     | Contents                                     |
-| ----------------------- | -------------------------------------------- |
-| `calendar-settings`     | App settings (timezone, booking page config) |
-| `calendar-availability` | Availability schedule configuration          |
+| Key                     | Contents                                                 |
+| ----------------------- | -------------------------------------------------------- |
+| `calendar-settings`     | App settings (timezone, week start, booking page config) |
+| `calendar-availability` | Availability schedule configuration                      |
 
 ### OAuth Tokens (via `@agent-native/core/oauth-tokens`)
 

package/corpus/templates/calendar/actions/get-settings.ts

@@ -3,14 +3,7 @@ import { getRequestUserEmail } from "@agent-native/core/server";
 import { getUserSetting } from "@agent-native/core/settings";
 import { z } from "zod";
 
-import type { Settings } from "../shared/api.js";
-
-const DEFAULT_SETTINGS: Settings = {
-  timezone: "America/New_York",
-  bookingPageTitle: "Book a Meeting",
-  bookingPageDescription: "Select a time that works for you.",
-  defaultEventDuration: 30,
-};
+import { normalizeCalendarSettings } from "../shared/settings.js";
 
 export default defineAction({
   description: "Get calendar settings",
@@ -19,8 +12,8 @@ export default defineAction({
   run: async () => {
     const email = getRequestUserEmail();
     if (!email) throw new Error("no authenticated user");
-    const settings =
-      (await getUserSetting(email, "calendar-settings")) || DEFAULT_SETTINGS;
-    return settings;
+    return normalizeCalendarSettings(
+      await getUserSetting(email, "calendar-settings"),
+    );
   },
 });

package/corpus/templates/calendar/actions/update-availability.ts

@@ -8,16 +8,27 @@ import {
   updateBookingUsername,
 } from "../server/handlers/booking-usernames.js";
 import type { AvailabilityConfig } from "../shared/api.js";
+import { availabilitySlotsOverlap } from "../shared/availability-schedule.js";
 
 const timeSlotSchema = z.object({
   start: z.string(),
   end: z.string(),
 });
 
-const dayScheduleSchema = z.object({
-  enabled: z.boolean(),
-  slots: z.array(timeSlotSchema),
-});
+const dayScheduleSchema = z
+  .object({
+    enabled: z.boolean(),
+    slots: z.array(timeSlotSchema),
+  })
+  .superRefine((day, ctx) => {
+    if (availabilitySlotsOverlap(day.slots)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["slots"],
+        message: "Availability windows must not overlap",
+      });
+    }
+  });
 
 const availabilitySchema = z.object({
   timezone: z.string(),