@agent-native/core 0.69.0 → 0.70.0

package/corpus/core/src/server/builder-browser.ts

@@ -1,7 +1,10 @@
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import type { H3Event } from "h3";
 import { getHeader } from "h3";
-import { getAuthSecret } from "./better-auth-instance.js";
+import {
+  getAuthSecret,
+  resolveSignupTrackingIdentity,
+} from "./better-auth-instance.js";
 import { getAppBasePath, getOrigin } from "./google-oauth.js";
 
 const DEFAULT_BUILDER_APP_HOST = "https://builder.io";
@@ -43,6 +46,8 @@ export const BUILDER_SIGNUP_SOURCE_PARAM = "signupSource";
 export const BUILDER_AGENT_NATIVE_FLOW_PARAM = "agentNativeFlow";
 export const BUILDER_AGENT_NATIVE_CONNECT_SOURCE_PARAM =
   "agentNativeConnectSource";
+export const BUILDER_AGENT_NATIVE_APP_PARAM = "agentNativeApp";
+export const BUILDER_AGENT_NATIVE_TEMPLATE_PARAM = "agentNativeTemplate";
 
 const BUILDER_STATE_TTL_MS = 10 * 60 * 1000;
 const BUILDER_SIGNUP_SOURCE = "agent-native";
@@ -51,6 +56,8 @@ export interface BuilderConnectTrackingParams {
   signupSource?: string;
   agentNativeFlow?: string;
   agentNativeConnectSource?: string;
+  agentNativeApp?: string;
+  agentNativeTemplate?: string;
 }
 
 function cleanTrackingParam(value: unknown): string | undefined {
@@ -72,6 +79,12 @@ export function getBuilderConnectTrackingParams(
     agentNativeConnectSource: cleanTrackingParam(
       params.get(BUILDER_AGENT_NATIVE_CONNECT_SOURCE_PARAM),
     ),
+    agentNativeApp: cleanTrackingParam(
+      params.get(BUILDER_AGENT_NATIVE_APP_PARAM),
+    ),
+    agentNativeTemplate: cleanTrackingParam(
+      params.get(BUILDER_AGENT_NATIVE_TEMPLATE_PARAM),
+    ),
   };
 }
 
@@ -86,6 +99,12 @@ export function builderConnectTrackingProperties(
   if (tracking.agentNativeConnectSource) {
     properties.agent_native_connect_source = tracking.agentNativeConnectSource;
   }
+  if (tracking.agentNativeApp) {
+    properties.agent_native_app = tracking.agentNativeApp;
+  }
+  if (tracking.agentNativeTemplate) {
+    properties.agent_native_template = tracking.agentNativeTemplate;
+  }
   return properties;
 }
 
@@ -101,6 +120,10 @@ function applyBuilderConnectTrackingParams(
   if (flow) params.set(BUILDER_AGENT_NATIVE_FLOW_PARAM, flow);
   const source = cleanTrackingParam(tracking.agentNativeConnectSource);
   if (source) params.set(BUILDER_AGENT_NATIVE_CONNECT_SOURCE_PARAM, source);
+  const app = cleanTrackingParam(tracking.agentNativeApp);
+  if (app) params.set(BUILDER_AGENT_NATIVE_APP_PARAM, app);
+  const template = cleanTrackingParam(tracking.agentNativeTemplate);
+  if (template) params.set(BUILDER_AGENT_NATIVE_TEMPLATE_PARAM, template);
 }
 
 export interface BuilderBrowserStatus {
@@ -524,8 +547,11 @@ export function buildBuilderCliAuthUrl(
   ) {
     callbackUrl.searchParams.set(BUILDER_OPENER_PARAM, requestedPreviewOrigin);
   }
+  const identity = resolveSignupTrackingIdentity();
   const tracking = {
     signupSource: BUILDER_SIGNUP_SOURCE,
+    agentNativeApp: identity.app,
+    agentNativeTemplate: identity.template,
     ...options.tracking,
   };
   applyBuilderConnectTrackingParams(callbackUrl.searchParams, tracking);

package/corpus/core/src/server/core-routes-plugin.ts

@@ -145,6 +145,7 @@ import { isEnvVarWriteAllowed } from "./env-var-writes.js";
 import { llmConnectionTrackingProperties } from "../shared/llm-connection.js";
 import { mountBrowserSessionRoutes } from "../browser-sessions/routes.js";
 import { mountDbAdminRoutes } from "../db-admin/routes.js";
+import { getDbExec } from "../db/client.js";
 import {
   DEFAULT_SSR_CACHE_HEADERS,
   EMPTY_SPECULATION_RULES,
@@ -158,6 +159,40 @@ import {
 export const FRAMEWORK_ROUTE_PREFIX = "/_agent-native";
 export const FRAMEWORK_EVENTS_ROUTE = `${FRAMEWORK_ROUTE_PREFIX}/events`;
 export const LEGACY_FRAMEWORK_EVENTS_ROUTE = `${FRAMEWORK_ROUTE_PREFIX}/poll-events`;
+
+/** Result of the `/_agent-native/health` liveness + DB-warmup probe. */
+export interface DbHealthProbeResult {
+  /** The serverless function is live and served the request. */
+  ok: true;
+  /** A trivial `SELECT 1` reached the database (false = no DB or unreachable). */
+  db: boolean;
+  /** Round-trip time of the probe in milliseconds. */
+  ms: number;
+}
+
+/**
+ * Run a trivial `SELECT 1` to confirm the database is reachable and, as a side
+ * effect, keep a scale-to-zero serverless database (e.g. Neon) warm. Touching
+ * the DB on a schedule prevents the multi-second cold-start that otherwise
+ * stalls the next real user request.
+ *
+ * Always resolves: an app with no database (or a momentarily unreachable one)
+ * is still live, so the probe reports `db: false` rather than throwing. The
+ * `exec` parameter is injectable purely for tests.
+ */
+export async function runDbHealthProbe(
+  exec: () => { execute: (sql: string) => Promise<unknown> } = getDbExec,
+): Promise<DbHealthProbeResult> {
+  const startedAt = Date.now();
+  let db = false;
+  try {
+    await exec().execute("SELECT 1");
+    db = true;
+  } catch {
+    // Live even when the DB is unreachable or the app has no database.
+  }
+  return { ok: true, db, ms: Date.now() - startedAt };
+}
 const DEFAULT_BUILDER_WAITLIST_FORM_ID = "DYTHuM0jlV";
 const DEFAULT_BUILDER_WAITLIST_FORMS_ORIGIN = "https://forms.agent-native.com";
 const BUILDER_WAITLIST_FORM_SOURCE = "connect_builder_card";
@@ -550,6 +585,8 @@ export interface CoreRoutesPluginOptions {
   disableSSE?: boolean;
   /** Disable the /_agent-native/ping health check. */
   disablePing?: boolean;
+  /** Disable the /_agent-native/health DB liveness + warmup probe. */
+  disableHealth?: boolean;
   /** Disable the /_agent-native/application-state routes. */
   disableAppState?: boolean;
   /** Disable the /_agent-native/open deep-link route. */
@@ -594,6 +631,7 @@ export interface CoreRoutesPluginOptions {
  *   GET    /_agent-native/poll                          — polling endpoint for change detection
  *   GET    /_agent-native/events (or custom)            — SSE endpoint for real-time sync
  *   GET    /_agent-native/ping                          — health check
+ *   GET    /_agent-native/health                        — DB liveness probe + scale-to-zero warmup
  *   GET    /_agent-native/env-status                    — env key configuration status (when envKeys provided)
  *   POST   /_agent-native/env-vars                      — save env vars to .env (when envKeys provided)
  *   GET    /_agent-native/application-state/:key        — read application state
@@ -925,6 +963,20 @@ export function createCoreRoutesPlugin(
         );
       }
 
+      // Health + DB warmup — liveness probe that touches the database so
+      // uptime monitors and the keep-warm cron prevent a scale-to-zero
+      // serverless DB (e.g. Neon) from cold-starting on the next real
+      // request. Public, side-effect free, and never cached.
+      if (!options.disableHealth) {
+        getH3App(nitroApp).use(
+          `${P}/health`,
+          defineEventHandler(async (event) => {
+            setResponseHeader(event, "cache-control", "no-store");
+            return runDbHealthProbe();
+          }),
+        );
+      }
+
       getH3App(nitroApp).use(
         `${P}/speculation-rules.json`,
         defineEventHandler((event) => {
@@ -1691,6 +1743,12 @@ export function createCoreRoutesPlugin(
                 agentNativeConnectSource:
                   connectTracking.agentNativeConnectSource ??
                   pending.tracking.agentNativeConnectSource,
+                agentNativeApp:
+                  connectTracking.agentNativeApp ??
+                  pending.tracking.agentNativeApp,
+                agentNativeTemplate:
+                  connectTracking.agentNativeTemplate ??
+                  pending.tracking.agentNativeTemplate,
               };
             }
             if (

package/corpus/core/src/server/google-oauth.ts

@@ -841,14 +841,27 @@ export function oauthCallbackResponse(
   // same-origin; Builder desktop workspace returns may point back to the
   // local loopback gateway and carry the short-lived `_session` bridge so
   // the local app can promote the newly created hosted OAuth session.
-  setResponseStatus(event, 302);
-  setResponseHeader(
-    event,
-    "Location",
-    appendSessionToOAuthReturnUrl(opts.returnUrl, opts.sessionToken),
+  const location = appendSessionToOAuthReturnUrl(
+    opts.returnUrl,
+    opts.sessionToken,
   );
+  setResponseStatus(event, 302);
+  setResponseHeader(event, "Location", location);
   setResponseHeader(event, "Referrer-Policy", "no-referrer");
-  return "";
+  // Return a real 302 so the browser lands on the clean return URL instead of
+  // lingering on the provider callback URL with its `code`/`state` query
+  // params. But h3 hands a non-2xx web `Response` straight back WITHOUT merging
+  // the `Set-Cookie` staged earlier in the callback (the framework session
+  // cookie), so mirror those staged cookies onto the redirect Response —
+  // otherwise the sign-in succeeds but the browser arrives back logged out.
+  const headers = new Headers({
+    Location: location,
+    "Referrer-Policy": "no-referrer",
+  });
+  for (const cookie of event.res?.headers?.getSetCookie?.() ?? []) {
+    headers.append("set-cookie", cookie);
+  }
+  return new Response(null, { status: 302, headers });
 }
 
 /** HTML error page for OAuth failures. The message is HTML-escaped — most

package/corpus/core/src/shared/mcp-embed-headers.ts

@@ -4,7 +4,7 @@ export const EMBED_TRANSPLANT_HEADER = "x-agent-native-embed-transplant";
 
 const CLAUDE_MCP_CONTENT_HOST_RE = /^[a-f0-9]{32}\.claudemcpcontent\.com$/i;
 const CHATGPT_MCP_SANDBOX_HOST_RE =
-  /^[^.]+\.web-sandbox\.oaiusercontent\.com$/i;
+  /^(?:[^.]+\.)?web-sandbox\.oaiusercontent\.com$/i;
 
 export function isLocalMcpEmbedOrigin(
   origin: string | null | undefined,

package/corpus/core/src/styles/agent-conversation.css

@@ -325,6 +325,27 @@
   font-size: 12px;
 }
 
+.agent-mcp-app__error {
+  flex-direction: column;
+  text-align: center;
+}
+
+.agent-mcp-app__open {
+  min-height: 28px;
+  border: 1px solid hsl(var(--destructive) / 0.35);
+  border-radius: calc(var(--radius) - 2px);
+  background: hsl(var(--background));
+  color: hsl(var(--foreground));
+  cursor: pointer;
+  font: inherit;
+  font-weight: 600;
+  padding: 0 10px;
+}
+
+.agent-mcp-app__open:hover {
+  background: hsl(var(--muted));
+}
+
 .agent-mcp-app__error,
 .agent-mcp-app--error {
   color: hsl(var(--destructive));

package/corpus/core/src/templates/workspace-core/.agents/skills/changelog/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: changelog
+description: >-
+  How to keep each app's user-facing changelog. Use when you ship a change a
+  user would notice (a new feature, a visible improvement, a bug fix), when
+  wiring the in-app "What's new" surface into a template, or when releasing
+  pending changelog entries.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Changelog — user-facing "What's new"
+
+Every template app keeps a `CHANGELOG.md` of **user-facing** changes that
+renders in-app via the command menu (Cmd+K → "What's new") and on the settings
+page. The flow mirrors changesets so it survives many agents working in
+parallel: each change drops a small **pending entry file**, and a later
+**release** rolls all pending files into a dated `CHANGELOG.md` section.
+
+## When to add an entry
+
+Add an entry whenever you ship something a user of that app would notice:
+
+- a new capability or surface,
+- a visible improvement (speed, layout, copy, defaults),
+- a bug fix that affects behavior they'd see.
+
+Do **not** add entries for refactors, internal tooling, tests, dependency
+bumps, or anything invisible to the end user. The changelog is product notes,
+not a commit log — write it the way you'd describe the change to a customer.
+
+## How to add an entry
+
+From the app directory (the template you changed):
+
+```bash
+agent-native changelog add "Recordings can be trimmed before sharing" --type added
+agent-native changelog add "Faster transcript search" --type improved
+agent-native changelog add "Fixed a crash when opening an empty folder" --type fixed
+```
+
+`--type` is one of `added`, `improved`, `fixed`, `changed`, `removed`,
+`security` (aliases like `feature`, `bugfix`, `enhancement` are accepted). This
+writes `changelog/<date>-<slug>.md` — one file per change, so parallel work
+never conflicts. You can also hand-write that file; the frontmatter is just:
+
+```md
+---
+type: added
+date: 2026-06-23
+---
+Recordings can be trimmed before sharing.
+```
+
+## Writing good entries
+
+- One user-facing sentence, present tense, no internal jargon or file names.
+- Lead with the benefit ("Recordings can be trimmed…"), not the mechanism.
+- Markdown is allowed (bold, links) but keep it short — it renders as a bullet.
+
+## Releasing
+
+`release` stamps every pending entry into `CHANGELOG.md` under a dated
+`## <date>` section (grouped by type) and deletes the pending files:
+
+```bash
+agent-native changelog release            # uses today's date
+agent-native changelog list               # preview pending + released
+```
+
+Releasing is usually done at deploy/merge time. The in-app surface reads
+`CHANGELOG.md`, so only released entries are visible to users — pending entries
+stay invisible until rolled up.
+
+## Wiring the in-app surface (once per template)
+
+Templates already get the rendering for free from `@agent-native/core`. To
+expose it in an app:
+
+1. **Command menu** — pass the app's own changelog to `CommandMenu`:
+
+   ```tsx
+   import changelog from "../CHANGELOG.md?raw";
+   // ...
+   <CommandMenu open={cmdkOpen} onOpenChange={setCmdkOpen} changelog={changelog}>
+     {/* existing groups */}
+   </CommandMenu>
+   ```
+
+   This adds a "What's new" entry with an unseen-release dot and an in-app
+   dialog — no other wiring needed.
+
+2. **Settings** (optional) — drop the card on the settings page:
+
+   ```tsx
+   import { ChangelogSettingsCard } from "@agent-native/core/client";
+   import changelog from "../CHANGELOG.md?raw";
+   // ...
+   <ChangelogSettingsCard markdown={changelog} />
+   ```
+
+`CHANGELOG.md?raw` is inlined by Vite at build time, so this works on every
+host with no server route or runtime file access.
+
+## Checklist
+
+- [ ] Shipped a user-visible change? Run `agent-native changelog add "…"`.
+- [ ] New template UI? Pass `changelog` to its `CommandMenu` and seed a
+      `CHANGELOG.md`.
+- [ ] Releasing/deploying? `agent-native changelog release` rolls pending → dated.

package/corpus/core/src/templates/workspace-core/.agents/skills/tracking/SKILL.md

@@ -31,7 +31,11 @@ Fire an analytics event.
 ```ts
 import { track } from "@agent-native/core/tracking";
 
-track("meal.logged", { mealName: "Salad", calories: 350 }, { userId: "user@example.com" });
+track(
+  "meal.logged",
+  { mealName: "Salad", calories: 350 },
+  { userId: "user@example.com" },
+);
 ```
 
 ### `identify(userId, traits?)`
@@ -73,13 +77,13 @@ Flush all providers (call before process exit).
 
 Set the env var and the provider auto-registers at startup. No SDK dependencies -- all providers use raw HTTP.
 
-| Provider   | Env vars                                                  |
-| ---------- | --------------------------------------------------------- |
-| PostHog    | `POSTHOG_API_KEY` (required), `POSTHOG_HOST` (optional, defaults to `https://us.i.posthog.com`) |
-| Mixpanel   | `MIXPANEL_TOKEN`                                          |
-| Amplitude  | `AMPLITUDE_API_KEY`                                       |
+| Provider               | Env vars                                                                                                                                           |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PostHog                | `POSTHOG_API_KEY` (required), `POSTHOG_HOST` (optional, defaults to `https://us.i.posthog.com`)                                                    |
+| Mixpanel               | `MIXPANEL_TOKEN`                                                                                                                                   |
+| Amplitude              | `AMPLITUDE_API_KEY`                                                                                                                                |
 | Agent Native Analytics | `AGENT_NATIVE_ANALYTICS_PUBLIC_KEY` (server), `AGENT_NATIVE_ANALYTICS_ENDPOINT` (optional, defaults to `https://analytics.agent-native.com/track`) |
-| Webhook    | `TRACKING_WEBHOOK_URL` (required), `TRACKING_WEBHOOK_AUTH` (optional, sent as `Authorization` header) |
+| Webhook                | `TRACKING_WEBHOOK_URL` (required), `TRACKING_WEBHOOK_AUTH` (optional, sent as `Authorization` header)                                              |
 
 Multiple providers can be active simultaneously. All receive every event.
 
@@ -106,10 +110,35 @@ Every browser-side `trackEvent()` POST to the Agent Native Analytics `/track` en
 
 These fields land in the `analytics_events.anonymous_id`, `analytics_events.session_id`, and `analytics_events.user_id` columns in the analytics template. Storage access is wrapped in try/catch — private-browsing / blocked-storage clients silently degrade to NULL rather than crashing the page.
 
+### Referral / viral attribution (first-touch)
+
+`configureTracking()` also captures an anonymous visitor's **first-touch** referral context once, on first page load, and persists it across the signup boundary so the server-side `signup` event records where the user came from. This powers virality metrics for every template (Clips share links, Plans public pages, etc.).
+
+**Share-link params** (set by whatever generates the link; read client-side only):
+
+- `ref` — referral source bucket, e.g. `clip_share`, `plan_share`
+- `via` — the referrer's stable user id (the clip/plan owner)
+- `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`
+
+**Client persistence** (first-write-wins — an existing value is never overwritten):
+
+- `localStorage` key `an_attribution` and first-party cookie `an_ft` (`path=/; max-age=2592000; SameSite=Lax`, not HttpOnly — non-sensitive, written by client JS).
+- Both store the same URL-encoded compact JSON (empty fields omitted, each value capped at 120 chars): `{ ref, via, utm_source, utm_medium, utm_campaign, utm_content, utm_term, landing_path, landing_referrer, landed_at }`. `landing_referrer` is the **host only** of `document.referrer` (scrubbed; same-origin referrers are dropped).
+- `getFirstTouchAttribution()` (from `@agent-native/core/client`) returns the parsed object or `null`.
+
+**Signup event enrichment** (server-side, from the `an_ft` cookie on the signup/OAuth-callback request, derived in `packages/core/src/server/attribution.ts`):
+
+- `referral_source` — `ref` if present, else derived: `/share/…` → `clip_share`; a plan public path (`/p/`, `/plan/`, `/share-plan/`) → `plan_share`; a non-empty external referring host → `external`; otherwise `direct`.
+- `referrer_user` (= `via`), `referral_medium` (= `utm_medium`), `referral_campaign` (= `utm_campaign`)
+- `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` (raw passthrough)
+- `first_touch_path` (= `landing_path`), `landing_referrer`
+
+Attribution parsing is fully defensive and never blocks signup — a missing/malformed cookie falls back to `referral_source: "direct"`.
+
 Other framework-level baseline events:
 
 - `session status` from `useSession()`, with `signed_in`
-- `signup` from Better Auth user creation, with `auth_provider` and `auth_user_id`
+- `signup` from Better Auth user creation, with `auth_provider`, `auth_user_id`, and first-touch referral attribution (`referral_source`, `referrer_user`, `referral_medium`, `referral_campaign`, `utm_*`, `first_touch_path`, `landing_referrer` — see "Referral / viral attribution" above)
 - `builder connect clicked` and `builder connect popup blocked` from browser Connect Builder CTAs
 - `builder connect started`, `builder connect succeeded`, `builder connect failed`, `builder disconnect succeeded`, and `builder disconnect failed` from the Builder connection routes, with LLM connection context when resolvable
 
@@ -121,7 +150,10 @@ For new lifecycle events, call `track()` server-side when the server is the sour
 interface TrackingProvider {
   name: string;
   track(event: TrackingEvent): void | Promise<void>;
-  identify?(userId: string, traits?: Record<string, unknown>): void | Promise<void>;
+  identify?(
+    userId: string,
+    traits?: Record<string, unknown>,
+  ): void | Promise<void>;
   flush?(): void | Promise<void>;
 }
 
@@ -142,11 +174,11 @@ interface TrackingEvent {
 
 ## Key Files
 
-| File                                           | Purpose                                     |
-| ---------------------------------------------- | ------------------------------------------- |
-| `packages/core/src/tracking/registry.ts`       | `track()`, `identify()`, `registerTrackingProvider()`, `flushTracking()` |
-| `packages/core/src/tracking/providers.ts`      | Built-in providers (PostHog, Mixpanel, Amplitude, Agent Native Analytics, Webhook) and `registerBuiltinProviders()` |
-| `packages/core/src/tracking/types.ts`          | `TrackingEvent` and `TrackingProvider` interfaces |
+| File                                      | Purpose                                                                                                             |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `packages/core/src/tracking/registry.ts`  | `track()`, `identify()`, `registerTrackingProvider()`, `flushTracking()`                                            |
+| `packages/core/src/tracking/providers.ts` | Built-in providers (PostHog, Mixpanel, Amplitude, Agent Native Analytics, Webhook) and `registerBuiltinProviders()` |
+| `packages/core/src/tracking/types.ts`     | `TrackingEvent` and `TrackingProvider` interfaces                                                                   |
 
 ## Related Skills
 

package/corpus/templates/analytics/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable user-facing changes to Agent-Native Analytics are documented here. Open it any
+time from the command menu (Cmd+K → "What's new") or from Settings.
+
+## 2026-06-23
+
+### Added
+
+- See what's new right inside Agent-Native Analytics — a changelog now lives in the command menu (Cmd+K) and in Settings.

package/corpus/templates/analytics/actions/install-dashboard-template.ts

@@ -100,7 +100,7 @@ export default defineAction({
         dashboardId: existingInstall.id,
         name: existingInstall.name,
         alreadyInstalled: true,
-        urlPath: `/adhoc/${existingInstall.id}`,
+        urlPath: `/dashboards/${existingInstall.id}`,
         deepLink: buildDeepLink({
           app: "analytics",
           view: "adhoc",
@@ -144,7 +144,7 @@ export default defineAction({
         name: dashboard.title,
         alreadyInstalled: false,
         overwritten: !!existing,
-        urlPath: `/adhoc/${dashboardId}`,
+        urlPath: `/dashboards/${dashboardId}`,
         deepLink: buildDeepLink({
           app: "analytics",
           view: "adhoc",

package/corpus/templates/analytics/actions/open-traffic-dashboard.ts

@@ -2,7 +2,7 @@ import { defineAction, embedApp } from "@agent-native/core";
 import { buildDeepLink } from "@agent-native/core/server";
 import { z } from "zod";
 
-const TRAFFIC_DASHBOARD_PATH = "/adhoc/agent-native-templates-first-party";
+const TRAFFIC_DASHBOARD_PATH = "/dashboards/agent-native-templates-first-party";
 const TRAFFIC_DASHBOARD_ID = "agent-native-templates-first-party";
 
 function trafficDashboardDeepLink(): string {

package/corpus/templates/analytics/actions/update-dashboard.ts

@@ -410,7 +410,9 @@ export default defineAction({
     "Edit a SQL dashboard config (scope-aware). Prefer this over raw db-patch on the settings table — " +
     "it resolves org vs. user scope correctly so the edit lands on the row the UI actually renders. " +
     "Use `ops` for structural changes (reorder/insert/remove panels, update field values via JSON Pointer paths). " +
-    "Use `config` to replace the entire dashboard config. The UI auto-refreshes after this action — do NOT call `refresh-screen`.",
+    "Use `config` to replace the entire dashboard config. " +
+    "For a large dashboard, build it up incrementally: save a small dashboard first, then add panels one at a time with `ops` rather than authoring the whole `config` in one call — a very large single `config` payload can get cut off mid-stream and stall the turn. " +
+    "The UI auto-refreshes after this action — do NOT call `refresh-screen`.",
   schema: z.object({
     dashboardId: z
       .string()
@@ -488,7 +490,7 @@ export default defineAction({
             ? args.config.name
             : args.dashboardId,
         config: args.config,
-        urlPath: `/adhoc/${args.dashboardId}`,
+        urlPath: `/dashboards/${args.dashboardId}`,
         deepLink: buildDeepLink({
           app: "analytics",
           view: "adhoc",
@@ -531,7 +533,7 @@ export default defineAction({
       dashboardId: args.dashboardId,
       name: typeof root.name === "string" ? root.name : args.dashboardId,
       config: root,
-      urlPath: `/adhoc/${args.dashboardId}`,
+      urlPath: `/dashboards/${args.dashboardId}`,
       deepLink: buildDeepLink({
         app: "analytics",
         view: "adhoc",