@agent-native/core 0.153.9 → 0.154.0

package/corpus/README.md

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

package/corpus/templates/analytics/AGENTS.md

@@ -1,11 +1,8 @@
 # Analytics — Agent Guide
 
 Analytics is an agent-native BI workspace for sources, queries, dashboards,
-charts, and warehouse integrations. Dashboards are canonical; legacy analyses
-remain readable for compatibility.
-
-Use connected sources and MCP tools; reason over fetched data here, not via
-another AI tool.
+charts, and warehouse integrations; dashboards are canonical and legacy
+analyses remain readable.
 
 ## Skills
 
@@ -27,49 +24,42 @@ Read the relevant skill before deeper work:
 
 ## How To Answer A Data Question
 
-1. **Search existing work first.** Call `search-analytics-query-catalog`, adapt
-   the closest saved SQL to the requested filters/window, run it once, and stop.
+1. **Search existing work first.** For a metric question, call
+   `search-analytics-query-catalog`; for dashboard replication or adaptation,
+   call `search-dashboard-references` first. Inspect each returned reference
+   with `get-sql-dashboard` or `get-explorer-dashboard` by its `kind`; a match
+   is context, not authoritative source data. Then adapt the closest saved SQL
+   to the requested filters/window, run it once, and stop.
 2. **One bounded call.** List/filter/count/cohort questions are one SQL statement
    or one server-side `run-code` script; never page or fan out per item.
 3. **Escalate on a miss.** If the catalog has no usable result, make one discovery
    pass (`list-data-dictionary`, `search-bigquery-schema`, `data-source-status`),
    then query; don't cross-check or add unasked breakdowns.
-4. **Answer in chat.** Return a short table or inline chart, not a dashboard
-   pointer. Native widgets show summarized data (≤50 rows); above that, state the
-   total and top rows.
+4. **Answer in chat.** Return a short table or inline chart, not only a
+   dashboard pointer; for >50 rows, state the total and top rows.
 5. **Deliver exports in chat.** See `analysis-workspace`; don't return only a path.
 6. **Chunk only reading.** Group 5-10 only for 30+ qualitative items when a query
    cannot answer; don't chunk queryable questions. See `adhoc-analysis`.
 
 ## Core Rules
 
-- A sibling app asking over A2A sends a question or shaped input, never SQL.
-  Raw-query actions (`sql`, `code`, `script`, `expression`) are not
-  sibling-invocable because this app owns schema, source selection, and tools.
-  Prefer natural-language delegation; shaped reads are stable contracts, not
-  delegation workarounds.
+- A sibling app sends natural-language or shaped input over A2A, never SQL; this
+  app owns schema, source selection, and tools. Prefer natural-language
+  delegation; shaped reads are stable contracts.
 - Analytics owns first-party product usage, app/template events, agent-native
   signups, conversions, and other curated product metrics. Answer sibling-app
   delegations with the built-in source and query catalog; sibling agents should
   send a natural-language question, never SQL.
 - For open-ended delegated requests, choose a safe default and label partial.
 - Data integrity first. Never invent numbers, dimensions, filters, or source
-  semantics; only present values you actually retrieved, and state uncertainty.
-- Every analytical answer carries audit context: source(s), time window,
-  filters, row count/sample size, join method, caveats.
+  semantics; present only retrieved values with source, window, filters,
+  row-count/sample-size, join method, and caveats.
 - Use actions for sources, queries, charts, dashboards, and sharing. Don't bypass
   access checks with raw SQL for ownable resources.
 - Provider actions are bounded shortcuts, not limits. For broad or
-  absence-sensitive Gong work, stage raw API data and use
-  `query-staged-dataset` or a Data Program; use `provider-corpus-job` for raw
-  transcript bodies. See `provider-api`, `data-programs`, and `gong`.
-- Custom APIs use `provider-api-register` for public HTTPS provider metadata and
-  `test-custom-api-connection` for bounded GET previews. Store credential values
-  in Settings, pass only key names to provider actions, and hand successful
-  endpoint tests to `save-data-program` for refreshable panels.
-- Hosted Analytics cannot reach localhost or private network APIs. Use a
-  deployed HTTPS endpoint or an explicitly supported secure tunnel; never
-  weaken the provider runtime's SSRF boundary.
+  absence-sensitive Gong work, stage raw API data and use `query-staged-dataset`
+  or a Data Program; see `provider-api`, `data-programs`, and `gong` for secure
+  provider and hosted-endpoint boundaries.
 - Create dashboards, panels, or saved artifacts only when explicitly asked;
   suggest and wait otherwise. Scope them to the question, avoid decorative
   metrics, and never modify existing dashboards without a directive.
@@ -87,8 +77,8 @@ Read the relevant skill before deeper work:
 - External MCP callers default to `ask_app` for interpretation, source choice,
   analysis, or multi-step work. Direct reads require exact, complete input;
   writes stay `ask_app`-only.
-- Dashboard email reports and alert rules are SQL-backed, self-describing action
-  surfaces — don't hand-wire routes around them. Reports cap at five recipients.
+- Dashboard reports and alert rules use their SQL-backed action surfaces; reports
+  cap at five recipients.
 
 ## Application State
 

package/corpus/templates/analytics/actions/search-dashboard-references.ts

@@ -0,0 +1,58 @@
+import { defineAction } from "@agent-native/core";
+import {
+  buildDeepLink,
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { searchDashboardReferences } from "../server/lib/dashboards-store";
+
+export default defineAction({
+  description:
+    "Find a bounded set of accessible saved SQL or explorer dashboards whose id, name, description, or config matches the search text. Use this when the user wants to replicate or adapt an existing dashboard. These are references only: inspect the returned dashboard with the getter for its kind before copying it, and do not assume a first-party Analytics dashboard is the authoritative source for a new question.",
+  schema: z.object({
+    search: z
+      .string()
+      .trim()
+      .min(2)
+      .describe("Focused dashboard name, metric, provider, or config terms"),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(24)
+      .optional()
+      .default(8)
+      .describe("Maximum dashboard references to return"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  link: ({ result }) => {
+    const first = Array.isArray(result) ? result[0] : null;
+    const id =
+      first && typeof first === "object"
+        ? (first as { id?: string }).id
+        : undefined;
+    if (!id) return null;
+    return {
+      url: buildDeepLink({
+        app: "analytics",
+        view: "adhoc",
+        params: { dashboardId: id },
+      }),
+      label: "Open dashboard reference in Analytics",
+      view: "adhoc",
+    };
+  },
+  run: async ({ search, limit }) => {
+    const email = getRequestUserEmail();
+    if (!email) throw new Error("no authenticated user");
+    return searchDashboardReferences(
+      { email, orgId: getRequestOrgId() || null },
+      search,
+      limit,
+    );
+  },
+});

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

@@ -2158,7 +2158,7 @@ export function Sidebar({ mobile }: { mobile?: boolean } = {}) {
       </TooltipTrigger>
       <TooltipContent side="top">
         {t("sidebar.searchShortcut", {
-          shortcut: `${shortcutModifierLabel()}+K`,
+          shortcut: `${shortcutModifierLabel()} K`,
         })}
       </TooltipContent>
     </Tooltip>

package/corpus/templates/analytics/app/lib/utils.ts

@@ -8,5 +8,5 @@ export function isMacPlatform(): boolean {
 }
 
 export function shortcutModifierLabel(): string {
-  return isMacPlatform() ? "\u2318" : "Ctrl";
+  return isMacPlatform() ? "Cmd" : "Ctrl";
 }

package/corpus/templates/analytics/app/pages/DataSources.tsx

@@ -16,6 +16,7 @@ import {
   getDefaultMcpIntegrations,
   McpIntegrationLogo,
 } from "@agent-native/core/client/resources";
+import { docsUrl } from "@agent-native/core/shared";
 import {
   IconCheck,
   IconChevronDown,
@@ -1903,7 +1904,7 @@ function FirstPartyAnalyticsCard() {
                 each one happened.
               </p>
               <a
-                href="https://www.agent-native.com/docs/tracking#error-capture"
+                href={docsUrl("tracking", { hash: "posthog-error-tracking" })}
                 target="_blank"
                 rel="noreferrer"
                 className="mt-2 inline-flex items-center gap-1 font-medium text-primary hover:underline"

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

@@ -236,7 +236,7 @@ export function ViewSqlPopover({
           <p className="text-[11px] text-muted-foreground mt-1.5">
             {t("sqlDashboard.filterInterpolationHelp", {
               example: "{{varName}}",
-              shortcut: `${isMac ? "⌘" : "Ctrl"}+Enter`,
+              shortcut: `${isMac ? "Cmd" : "Ctrl"} Enter`,
             })}
           </p>
         ) : null}

package/corpus/templates/analytics/app/pages/monitoring/errors/IssueList.tsx

@@ -1,4 +1,5 @@
 import { CodeSurface } from "@agent-native/core/blocks";
+import { docsUrl } from "@agent-native/core/shared";
 import {
   IconAlertTriangle,
   IconBug,
@@ -28,8 +29,9 @@ import {
   useStatusLabel,
 } from "./utils";
 
-const ERROR_CAPTURE_DOCS_URL =
-  "https://www.agent-native.com/docs/tracking#error-capture";
+const ERROR_CAPTURE_DOCS_URL = docsUrl("tracking", {
+  hash: "posthog-error-tracking",
+});
 
 const ERROR_CAPTURE_SNIPPET = `// Agent Native templates already call configureTracking().
 import { configureTracking, captureException } from "@agent-native/core/client/observability";

package/corpus/templates/analytics/app/pages/sessions/SessionsPage.tsx

@@ -6,6 +6,7 @@ import {
   useBuilderConnectFlow,
   useBuilderStatus,
 } from "@agent-native/core/client/settings";
+import { docsUrl } from "@agent-native/core/shared";
 import {
   IconCheck,
   IconChevronDown,
@@ -58,8 +59,9 @@ import { cn } from "@/lib/utils";
 
 type ReplayRange = "24h" | "7d" | "30d" | "90d" | "all";
 
-const SESSION_REPLAY_DOCS_URL =
-  "https://www.agent-native.com/docs/tracking#session-replay";
+const SESSION_REPLAY_DOCS_URL = docsUrl("tracking", {
+  hash: "session-replay",
+});
 
 const S3_STORAGE_FIELDS = [
   {

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

@@ -22,6 +22,7 @@ export const INITIAL_TOOL_NAMES = [
   // build request should not stop at inspection or an empty extension shell
   // while the agent lazily discovers the next mutating action.
   "get-sql-dashboard",
+  "get-explorer-dashboard",
   "list-sql-dashboards",
   "list-extensions",
   "get-extension",
@@ -33,6 +34,7 @@ export const INITIAL_TOOL_NAMES = [
   "extension-data-set",
   "generate-chart",
   "search-analytics-query-catalog",
+  "search-dashboard-references",
   "query-agent-native-analytics",
   "bigquery",
   "search-bigquery-schema",

package/corpus/templates/analytics/server/lib/dashboards-store.ts

@@ -28,7 +28,16 @@ import {
   resolveAccess,
   type ShareRole,
 } from "@agent-native/core/sharing";
-import { and, desc, eq, inArray, isNotNull, isNull, sql } from "drizzle-orm";
+import {
+  and,
+  desc,
+  eq,
+  inArray,
+  isNotNull,
+  isNull,
+  or,
+  sql,
+} from "drizzle-orm";
 
 import { getDb, schema } from "../db/index.js";
 
@@ -78,6 +87,19 @@ export interface DashboardSummaryRecord {
   hiddenBy: string | null;
 }
 
+/** Compact, access-scoped reference returned by dashboard discovery. */
+export interface DashboardReferenceRecord {
+  id: string;
+  kind: DashboardKind;
+  name: string;
+  description: string | null;
+  ownerEmail: string;
+  orgId: string | null;
+  visibility: "private" | "org" | "public";
+  updatedAt: string;
+  matchedFields: Array<"id" | "name" | "description" | "config">;
+}
+
 /** Hydrated dashboard row for catalog ranking only. */
 export interface DashboardCatalogRecord {
   id: string;
@@ -147,9 +169,23 @@ interface AccessCtx {
 
 const SQL_PREFIX = "sql-dashboard-";
 const EXPLORER_PREFIX = "dashboard-";
+
+/**
+ * `EXPLORER_PREFIX` also prefixes per-dashboard preference keys such as
+ * `dashboard-filters:<id>`, so an unqualified prefix match reads every saved
+ * filter set back as an "Untitled" explorer dashboard. Settings sub-namespaces
+ * are the only thing that puts a separator inside the remainder, encoded or
+ * not, and no dashboard id contains one.
+ */
+function isLegacyDashboardId(id: string): boolean {
+  return id.length > 0 && !/:|%3a/i.test(id);
+}
 const ANALYSIS_PREFIX = "adhoc-analysis-";
 const DASHBOARD_REVISION_LIMIT = 50;
 const ANALYSIS_REVISION_LIMIT = 30;
+const MAX_DASHBOARD_REFERENCE_RESULTS = 24;
+const MAX_DASHBOARD_REFERENCE_CANDIDATES = 200;
+const OUT_OF_SCOPE_REFERENCE_PROBE_LIMIT = 5;
 
 export function normalizeDashboardName(value: string): string {
   return value.trim().replace(/\s+/g, " ").toLowerCase();
@@ -159,6 +195,138 @@ function nowIso(): string {
   return new Date().toISOString();
 }
 
+function escapeLikeLiteral(value: string): string {
+  return value.replace(/[\\%_]/g, "\\$&");
+}
+
+type DashboardReferenceSearchQuery = {
+  phrase: string;
+  terms: string[];
+};
+
+function dashboardReferenceSearchQuery(
+  search: string,
+): DashboardReferenceSearchQuery {
+  const phrase = search.trim().replace(/\s+/g, " ").toLowerCase();
+  return {
+    phrase,
+    terms: phrase.split(" ").filter(Boolean).slice(0, 8),
+  };
+}
+
+function dashboardReferenceFieldText(value: unknown): string {
+  if (typeof value === "string") return value.toLowerCase();
+  if (!value || typeof value !== "object") return "";
+  const serialized = JSON.stringify(value);
+  return typeof serialized === "string" ? serialized.toLowerCase() : "";
+}
+
+function dashboardReferenceMatch(
+  row: {
+    id?: unknown;
+    kind?: unknown;
+    name?: unknown;
+    description?: unknown;
+    config?: unknown;
+    ownerEmail?: unknown;
+    orgId?: unknown;
+    visibility?: unknown;
+    updatedAt?: unknown;
+  },
+  query: DashboardReferenceSearchQuery,
+): { record: DashboardReferenceRecord; score: number } | null {
+  const fields = {
+    id: dashboardReferenceFieldText(row.id),
+    name: dashboardReferenceFieldText(row.name),
+    description: dashboardReferenceFieldText(row.description),
+    config: dashboardReferenceFieldText(row.config),
+  } satisfies Record<DashboardReferenceRecord["matchedFields"][number], string>;
+  const matchedFields = Object.entries(fields)
+    .filter(([, value]) => query.terms.some((term) => value.includes(term)))
+    .map(
+      ([field]) => field as DashboardReferenceRecord["matchedFields"][number],
+    );
+  const matchedTerms = query.terms.filter((term) =>
+    Object.values(fields).some((value) => value.includes(term)),
+  ).length;
+  if (matchedTerms !== query.terms.length) return null;
+
+  let score = matchedTerms * 100;
+  for (const [field, value] of Object.entries(fields)) {
+    const weight =
+      field === "name"
+        ? 80
+        : field === "description"
+          ? 45
+          : field === "id"
+            ? 30
+            : 10;
+    if (value.includes(query.phrase)) score += 100 + weight;
+    if (field === "name" && value === query.phrase) score += 300;
+    if (field === "name" && value.startsWith(query.phrase)) score += 40;
+  }
+
+  return {
+    record: {
+      id: String(row.id ?? ""),
+      kind: row.kind === "explorer" ? "explorer" : "sql",
+      name: String(row.name ?? "Untitled dashboard"),
+      description: typeof row.description === "string" ? row.description : null,
+      ownerEmail: String(row.ownerEmail ?? ""),
+      orgId: typeof row.orgId === "string" ? row.orgId : null,
+      visibility:
+        row.visibility === "public" || row.visibility === "org"
+          ? row.visibility
+          : "private",
+      updatedAt: String(row.updatedAt ?? ""),
+      matchedFields,
+    },
+    score,
+  };
+}
+
+function legacyDashboardReferenceScope(
+  key: string,
+  ctx: AccessCtx,
+): {
+  id: string;
+  kind: DashboardKind;
+  ownerEmail: string;
+  orgId: string | null;
+  visibility: DashboardReferenceRecord["visibility"];
+} | null {
+  if (ctx.orgId && key.startsWith(`o:${ctx.orgId}:${SQL_PREFIX}`)) {
+    return {
+      id: key.slice(`o:${ctx.orgId}:${SQL_PREFIX}`.length),
+      kind: "sql",
+      ownerEmail: ctx.email,
+      orgId: ctx.orgId,
+      visibility: "org",
+    };
+  }
+  if (ctx.email && key.startsWith(`u:${ctx.email}:${SQL_PREFIX}`)) {
+    return {
+      id: key.slice(`u:${ctx.email}:${SQL_PREFIX}`.length),
+      kind: "sql",
+      ownerEmail: ctx.email,
+      orgId: null,
+      visibility: "private",
+    };
+  }
+  if (ctx.email && key.startsWith(`u:${ctx.email}:${EXPLORER_PREFIX}`)) {
+    const id = key.slice(`u:${ctx.email}:${EXPLORER_PREFIX}`.length);
+    if (!isLegacyDashboardId(id)) return null;
+    return {
+      id,
+      kind: "explorer",
+      ownerEmail: ctx.email,
+      orgId: null,
+      visibility: "private",
+    };
+  }
+  return null;
+}
+
 function nanoidFallback(): string {
   return (
     Math.random().toString(36).slice(2, 10) +
@@ -518,7 +686,7 @@ export async function listDashboards(
         key.startsWith(`u:${ctx.email}:${EXPLORER_PREFIX}`)
       ) {
         id = key.slice(`u:${ctx.email}:${EXPLORER_PREFIX}`.length);
-        kind = "explorer";
+        kind = isLegacyDashboardId(id) ? "explorer" : null;
       }
       if (!id || !kind) continue;
       if (filter?.kind && filter.kind !== kind) continue;
@@ -665,7 +833,7 @@ export async function listDashboardSummaries(
         key.startsWith(`u:${ctx.email}:${EXPLORER_PREFIX}`)
       ) {
         id = key.slice(`u:${ctx.email}:${EXPLORER_PREFIX}`.length);
-        kind = "explorer";
+        kind = isLegacyDashboardId(id) ? "explorer" : null;
       }
       if (!id || !kind || seen.has(id)) continue;
       if (filter?.kind && filter.kind !== kind) continue;
@@ -707,6 +875,201 @@ export async function listDashboardSummaries(
   return out;
 }
 
+/**
+ * Find active saved dashboards by metadata or serialized config.
+ *
+ * This is deliberately separate from the query catalog: a matching saved
+ * dashboard is a replication reference, not proof that its source is
+ * authoritative for the question being asked.
+ */
+export async function searchDashboardReferences(
+  ctx: AccessCtx,
+  search: string,
+  limit = 8,
+  dbOverride?: any,
+): Promise<DashboardReferenceRecord[]> {
+  const query = dashboardReferenceSearchQuery(search);
+  if (!query.phrase || query.terms.length === 0) return [];
+  const boundedLimit = Math.min(
+    Math.max(Number.isFinite(limit) ? Math.trunc(limit) : 8, 1),
+    MAX_DASHBOARD_REFERENCE_RESULTS,
+  );
+  const db = (dbOverride ?? getDb()) as any;
+  const access = accessFilter(schema.dashboards, schema.dashboardShares, {
+    userEmail: ctx.email,
+    orgId: ctx.orgId ?? undefined,
+  });
+  const wildcardMatches = (term: string) => {
+    const pattern = `%${escapeLikeLiteral(term)}%`;
+    return or(
+      sql<boolean>`lower(${schema.dashboards.id}) LIKE ${pattern} ESCAPE '\\'`,
+      sql<boolean>`lower(${schema.dashboards.title}) LIKE ${pattern} ESCAPE '\\'`,
+      sql<boolean>`lower(coalesce(${schema.dashboards.config}, '')) LIKE ${pattern} ESCAPE '\\'`,
+    );
+  };
+  const phraseMatch = wildcardMatches(query.phrase);
+  const tokenMatch =
+    query.terms.length === 1
+      ? wildcardMatches(query.terms[0]!)
+      : and(...query.terms.map(wildcardMatches));
+  const where = and(
+    access,
+    isNull(schema.dashboards.archivedAt),
+    isNull(schema.dashboards.hiddenAt),
+    or(phraseMatch, tokenMatch),
+  );
+  // guard:allow-heavy-dashboard-list-read — bounded wildcard candidates need serialized config to rank references.
+  const rows = await db
+    .select({
+      id: schema.dashboards.id,
+      kind: schema.dashboards.kind,
+      name: schema.dashboards.title,
+      description: isPostgres()
+        ? sql<
+            string | null
+          >`(${schema.dashboards.config}::jsonb ->> 'description')`
+        : sql<
+            string | null
+          >`json_extract(${schema.dashboards.config}, '$.description')`,
+      config: schema.dashboards.config,
+      ownerEmail: schema.dashboards.ownerEmail,
+      orgId: schema.dashboards.orgId,
+      visibility: schema.dashboards.visibility,
+      updatedAt: schema.dashboards.updatedAt,
+    })
+    .from(schema.dashboards)
+    .where(where)
+    .orderBy(desc(schema.dashboards.updatedAt))
+    .limit(MAX_DASHBOARD_REFERENCE_CANDIDATES);
+
+  const ranked: Array<{
+    record: DashboardReferenceRecord;
+    score: number;
+  }> = rows
+    .map((row: any) => dashboardReferenceMatch(row, query))
+    .filter(
+      (
+        match: { record: DashboardReferenceRecord; score: number } | null,
+      ): match is {
+        record: DashboardReferenceRecord;
+        score: number;
+      } => match !== null,
+    );
+
+  // Older Analytics deployments still have dashboards in settings KV. Search
+  // that scoped fallback too, but keep SQL rows authoritative when an id has
+  // already been migrated.
+  const seen = new Set(
+    ranked.map(({ record }) => `${record.kind}:${record.id}`),
+  );
+  const allSettings = await getAllSettings();
+  for (const [key, value] of Object.entries(allSettings)) {
+    const scope = legacyDashboardReferenceScope(key, ctx);
+    if (
+      !scope ||
+      !scope.id ||
+      typeof value !== "object" ||
+      value === null ||
+      Array.isArray(value)
+    ) {
+      continue;
+    }
+    const { title, config } = configFromSettings(
+      value as Record<string, unknown>,
+    );
+    const match = dashboardReferenceMatch(
+      {
+        id: scope.id,
+        kind: scope.kind,
+        name: title,
+        description: configDescriptionFromValue(config),
+        config,
+        ownerEmail: scope.ownerEmail,
+        orgId: scope.orgId,
+        visibility: scope.visibility,
+        updatedAt:
+          typeof config.updatedAt === "string"
+            ? config.updatedAt
+            : typeof config.createdAt === "string"
+              ? config.createdAt
+              : "",
+      },
+      query,
+    );
+    if (!match || seen.has(`${match.record.kind}:${match.record.id}`)) {
+      continue;
+    }
+    seen.add(`${match.record.kind}:${match.record.id}`);
+    ranked.push(match);
+  }
+
+  if (ranked.length === 0) {
+    await assertNoOwnedReferenceHiddenByScope(db, ctx, search, query);
+  }
+
+  return ranked
+    .sort(
+      (a, b) =>
+        b.score - a.score ||
+        b.record.updatedAt.localeCompare(a.record.updatedAt),
+    )
+    .slice(0, boundedLimit)
+    .map(({ record }) => record);
+}
+
+/**
+ * With no active organization, `ownerScopeFilter` narrows the owner clause to
+ * `org_id IS NULL` and drops the `visibility = 'org'` clause entirely, so every
+ * dashboard the caller owns under an organization vanishes from this search.
+ * An empty result then reads as "no such dashboard" and the agent answers by
+ * querying raw event tables instead of the dashboard the user named. Probe on
+ * the empty path only, so an ordinary miss stays one query.
+ */
+async function assertNoOwnedReferenceHiddenByScope(
+  db: any,
+  ctx: AccessCtx,
+  search: string,
+  query: ReturnType<typeof dashboardReferenceSearchQuery>,
+): Promise<void> {
+  if (ctx.orgId || !ctx.email) return;
+  const nameMatches = (term: string) => {
+    const pattern = `%${escapeLikeLiteral(term)}%`;
+    return or(
+      sql<boolean>`lower(${schema.dashboards.id}) LIKE ${pattern} ESCAPE '\\'`,
+      sql<boolean>`lower(${schema.dashboards.title}) LIKE ${pattern} ESCAPE '\\'`,
+    );
+  };
+  const rows = await db
+    .select({
+      id: schema.dashboards.id,
+      name: schema.dashboards.title,
+      orgId: schema.dashboards.orgId,
+    })
+    .from(schema.dashboards)
+    .where(
+      and(
+        sql<boolean>`lower(${schema.dashboards.ownerEmail}) = ${ctx.email.toLowerCase()}`,
+        isNotNull(schema.dashboards.orgId),
+        isNull(schema.dashboards.archivedAt),
+        isNull(schema.dashboards.hiddenAt),
+        or(
+          nameMatches(query.phrase),
+          query.terms.length === 1
+            ? nameMatches(query.terms[0]!)
+            : and(...query.terms.map(nameMatches)),
+        ),
+      ),
+    )
+    .limit(OUT_OF_SCOPE_REFERENCE_PROBE_LIMIT);
+  if (!rows?.length) return;
+  const named = rows
+    .map((row: any) => `"${row.name ?? row.id}" (id ${row.id})`)
+    .join(", ");
+  throw new Error(
+    `No dashboard readable in this session matches "${search}", but ${rows.length} organization-scoped dashboard(s) owned by ${ctx.email} do: ${named}. This session resolved no active organization, so they cannot be read. Tell the user their organization context is missing and that the dashboard exists — do not answer from a different data source.`,
+  );
+}
+
 /**
  * Hydrate a bounded set of dashboard ids for catalog ranking.
  *