@agent-native/core 0.69.0 → 0.70.1

package/corpus/core/src/server/onboarding-html.ts

@@ -1191,6 +1191,7 @@ ${
       }
     }
     function __anFinishOAuthExchange(ret, flowId, sessionToken) {
+      __anGoogleSignInInFlight = false;
       if (__anIsBuilderPreview()) {
         if (sessionToken) {
           __anSetOAuthDebug('OAuth exchange redeemed; applying session bridge to embedded app', flowId);
@@ -1361,6 +1362,8 @@ ${identitySsoScript}
     }
     var __anOAuthPollTimer = null;
     var __anOAuthPollCount = 0;
+    var __anGoogleSignInInFlight = false;
+    var __anGoogleRecoverBound = false;
     function __anNewOAuthFlowId() {
       try {
         if (window.crypto && typeof window.crypto.randomUUID === 'function') {
@@ -1401,6 +1404,34 @@ ${identitySsoScript}
       err.textContent = message;
       err.classList.add('show');
       btn.disabled = false;
+      __anGoogleSignInInFlight = false;
+    }
+    function __anRecoverGoogleSignInAfterReturn() {
+      // The user left for the Google sign-in window and came back. If the flow
+      // never completed (e.g. they closed the window to switch profiles), the
+      // button is stuck disabled with no error path firing for up to 5 minutes.
+      // Re-enable it so they can retry. Wait briefly first so a genuinely
+      // in-flight exchange can still finish and navigate without a flicker.
+      if (!__anGoogleSignInInFlight) return;
+      setTimeout(function() {
+        if (!__anGoogleSignInInFlight) return;
+        var btn = document.getElementById('google-btn');
+        if (!btn || !btn.disabled) return;
+        if (__anOAuthPollTimer) {
+          clearInterval(__anOAuthPollTimer);
+          __anOAuthPollTimer = null;
+        }
+        btn.disabled = false;
+        __anGoogleSignInInFlight = false;
+      }, 1200);
+    }
+    function __anBindGoogleRecover() {
+      if (__anGoogleRecoverBound) return;
+      __anGoogleRecoverBound = true;
+      window.addEventListener('focus', __anRecoverGoogleSignInAfterReturn);
+      document.addEventListener('visibilitychange', function() {
+        if (document.visibilityState === 'visible') __anRecoverGoogleSignInAfterReturn();
+      });
     }
     function __anHandlePopupOAuthFailure(ret, btn, err, flowId, redirectReason, builderFrameMessage) {
       if (__anIsBuilderPreview() && __anIsInFrame()) {
@@ -2013,6 +2044,8 @@ ${
     var err = document.getElementById('google-err');
     var ret = __anGetReturnPath();
     btn.disabled = true;
+    __anGoogleSignInInFlight = true;
+    __anBindGoogleRecover();
     err.classList.remove('show');
     if (__anResolveAuthFlow() === 'popup') {
       __anStartPopupOAuth(ret, btn, err);
@@ -2037,11 +2070,13 @@ ${
         err.textContent = data.message || 'Google OAuth is not configured.';
         err.classList.add('show');
         btn.disabled = false;
+        __anGoogleSignInInFlight = false;
       }
     } catch (e) {
       err.textContent = 'Failed to connect. Please try again.';
       err.classList.add('show');
       btn.disabled = false;
+      __anGoogleSignInInFlight = false;
     }
   }`
     : ""

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/reliable-mutations/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: reliable-mutations
+description: >-
+  How the agent must perform writes so they actually persist under the hosted
+  ~40s run budget. Use whenever you create, update, delete, or batch-write app
+  data — especially "do this for many items" loops, or any task where the user
+  expects N things to end up saved.
+---
+
+# Reliable Mutations
+
+## Rule
+
+Make a change in **one atomic call** when the action supports it, then **verify
+the persisted end state and report concrete proof** (counts/ids). Never drive a
+multi-step change by looping many small writes, and never report success from a
+tool ✓ alone.
+
+## Why
+
+Hosted agent runs have a ~40s soft budget (it exists to hand off cleanly under
+the upstream gateway/function walls — it is correct and is not raisable; see the
+durable-agent-runs design doc). When you loop many sequential writes inside one
+turn, the budget can cut you off mid-loop. The run resumes in a new chunk, but
+the resume often re-does earlier steps instead of advancing, so the loop churns
+and the *saved* result ends up partial — or empty — even though each individual
+tool call appeared to succeed. The user gets told "done" while the data says
+otherwise. One atomic call commits or fails as a unit; verification turns a
+hopeful ✓ into a fact.
+
+## How
+
+1. **Prefer a single atomic call.** If an action accepts the whole set (add
+   many, set all, bulk update), pass the full batch in one call so it commits
+   atomically. Check the action surface for a batch/plural form before reaching
+   for a loop.
+2. **Do not loop many small writes under the run budget.** A sequence of N
+   per-item writes in one turn will race the ~40s cutoff and can leave partial
+   or no state. If no batch action exists, that is a gap in the action layer —
+   add or extend an action that accepts the batch (see the `actions` skill)
+   rather than papering over it with a loop.
+3. **Verify the end state after writing.** Re-read the data (a list/read action,
+   a count query) and confirm the result matches intent — the right number of
+   rows, the expected ids/fields. Do this before you tell the user it worked.
+4. **Report proof-of-done, not vibes.** State concrete evidence: "saved 12 of 12
+   panels (ids …)" or "updated 5 rows". Do not infer success from the presence
+   of a tool ✓ on an individual call.
+5. **On a time-budget cutoff, fail loud.** If the turn is cut before the change
+   is fully committed and verified, say so explicitly and report what *did*
+   persist (M of N) and what remains. Never round a partial or unverified write
+   up to "done".
+
+## Don't
+
+- Don't loop `for each item: write(item)` for a large set in a single hosted
+  turn.
+- Don't claim completion because every tool call returned ✓ — a ✓ on an aborted
+  chunk does not mean the row was committed.
+- Don't silently shrink the scope ("I added a few of them") and present it as the
+  finished task.
+- Don't try to "fix" this by asking for a longer run timeout — the budget is
+  correct; restructure the write instead.
+
+## Related
+
+- `actions` — define or extend a batch/atomic action when only per-item writes
+  exist.
+- `storing-data` — where app data lives and how reads/writes are scoped.
+- `performance` — avoid query waterfalls when verifying end state.
+- Design doc: `packages/core/docs/design/durable-agent-runs.md` — the real
+  ceiling fix (checkpointed and durable runs); this skill is the agent-facing
+  mitigation that reduces how often the ceiling is hit.

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/.agents/skills/dashboard-management/SKILL.md

@@ -174,6 +174,28 @@ pnpm action update-dashboard --dashboardId weekly-metrics --config '<full json>'
 
 After a mutation, navigate to the dashboard if the user is elsewhere. The app syncs through the framework's polling/query invalidation path.
 
+## Reliable Bulk Edits
+
+This is the dashboard-specific application of the framework-wide `reliable-mutations` skill — read that for the general rule (one atomic write, verify end state, report proof-of-done).
+
+Hosted agent runs have a **~40s budget**. Many sequential `update-dashboard` calls (one per panel, plus schema-discovery calls) will blow that budget and leave the dashboard in a partial state — earlier inserts looked like they succeeded (✓), but nothing actually persisted. Avoid this:
+
+- **Batch ALL changes into ONE `update-dashboard` call.** A single `update-dashboard` is atomic: it applies every op to an in-memory config, validates all panel SQL, then upserts once. Never loop the action.
+  - To add N panels, pass N ops in one call: `ops: [{op:"insert", path:"/panels/-", value:<panel>}, … ]` (`/panels/-` appends to the end).
+  - The `ops` format needs no discovery: each op is `{ op, path, from?, value? }`, `op ∈ set | replace | remove | insert | move | move-before`, and `path` is a JSON Pointer (e.g. `/panels/3`, `/panels/3/title`, `/name`).
+- **To add a shipped template's panels, prefer `install-dashboard-template` with `mergePanels: true`** and the existing `dashboardId`. It appends only the template panels whose id is not already present (preserving existing panels and order) in one atomic save — you don't author each panel yourself.
+- **Always verify the returned proof-of-done and report it.** `update-dashboard` returns `panelCount`, `appliedOps`, and a `summary` string; `install-dashboard-template --mergePanels` returns `addedPanelIds`, `skippedExistingIds`, and `panelCount`. Tell the user the resulting panel count instead of assuming success.
+
+```bash
+# Add several panels in ONE atomic call (never one call per panel)
+pnpm action update-dashboard --dashboardId weekly-metrics \
+  --ops '[{"op":"insert","path":"/panels/-","value":{"id":"p1","title":"A","source":"first-party","chartType":"metric","width":1,"sql":"SELECT COUNT(*) AS value FROM analytics_events"}},
+          {"op":"insert","path":"/panels/-","value":{"id":"p2","title":"B","source":"first-party","chartType":"metric","width":1,"sql":"SELECT COUNT(DISTINCT user_id) AS value FROM analytics_events"}}]'
+
+# Append a template's panels to an existing dashboard in one call
+pnpm action install-dashboard-template --templateId skills-cli-funnel --dashboardId weekly-metrics --mergePanels true
+```
+
 ## Archiving vs deleting
 
 Dashboards have a soft-delete state. The default user-facing destructive action is **Archive** (recoverable). Hard delete still exists, but lives behind a "Delete permanently" confirm in both the page header and the sidebar dropdown — and in the agent surface, behind the older `delete-dashboard` action. Archived rows stay in the `dashboards` table with `archived_at` set, are hidden from the default sidebar list, and remain accessible by id (so deep links in chat history keep working) until explicitly purged.

package/corpus/templates/analytics/AGENTS.md

@@ -87,7 +87,14 @@ details live in `.agents/skills/`.
   `id`, category, data sources, panel count, and installed dashboard IDs.
 - `install-dashboard-template` installs a catalog template into normal
   SQL-backed dashboards. Required: `templateId`. Optional: `dashboardId`,
-  `name`, `overwrite`, and `forceNew`.
+  `name`, `overwrite`, `forceNew`, and `mergePanels`.
+- To add a template's panels to an existing dashboard, call
+  `install-dashboard-template` with `mergePanels: true` and the existing
+  `dashboardId`. It appends only the template panels whose id is not already
+  present (preserving existing panels and order) in one atomic save and returns
+  `{ addedPanelIds, skippedExistingIds, panelCount }`. Prefer this over looping
+  `update-dashboard` to add many panels — sequential calls time out on the ~40s
+  hosted run budget.
 - Node Exporter ships as `node-exporter-macos` for Darwin/Homebrew
   `node_exporter` scrapes and `node-exporter-full` for the Linux-focused
   Grafana 1860 revision 45 full dashboard converted into native Analytics

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

@@ -43,7 +43,8 @@ function uniqueConstraintMessage(err: unknown): boolean {
 
 export default defineAction({
   description:
-    "Install a dashboard template from the Analytics catalog into the user's SQL-backed dashboards. Use list-dashboard-templates first when choosing a template.",
+    "Install a dashboard template from the Analytics catalog into the user's SQL-backed dashboards. Use list-dashboard-templates first when choosing a template. " +
+    "To ADD a template's panels to an EXISTING dashboard in ONE call (the preferred way to bulk-add panels), pass `mergePanels: true` with the `dashboardId` of the existing dashboard: it appends every template panel whose id is not already present, preserves all existing panels and their order, and saves once. This avoids looping update-dashboard, which times out on the ~40s hosted run budget.",
   schema: z.object({
     templateId: z
       .string()
@@ -52,7 +53,7 @@ export default defineAction({
       .string()
       .optional()
       .describe(
-        "Optional dashboard id to write. Omit to reuse an existing installed copy or create a unique id.",
+        "Optional dashboard id to write. Omit to reuse an existing installed copy or create a unique id. Required when mergePanels is true.",
       ),
     name: z
       .string()
@@ -70,6 +71,12 @@ export default defineAction({
       .describe(
         "If true, create another copy even when this template is installed.",
       ),
+    mergePanels: z
+      .boolean()
+      .optional()
+      .describe(
+        "If true AND a dashboard already exists at dashboardId, APPEND this template's panels (only the ones whose id is not already present) to the existing dashboard in one atomic save, preserving all existing panels and their order. Returns { addedPanelIds, skippedExistingIds, panelCount }. Non-destructive; does not change overwrite/forceNew behavior.",
+      ),
   }),
   mcpApp: {
     compactCatalog: true,
@@ -90,6 +97,94 @@ export default defineAction({
     if (!entry)
       throw new Error(`Unknown dashboard template: ${args.templateId}`);
 
+    // Append/merge mode: add this template's panels to an existing dashboard
+    // in ONE atomic save instead of looping update-dashboard (which times out
+    // on the ~40s hosted run budget). Non-destructive: existing panels and
+    // their order are preserved; only template panels with a new id are added.
+    if (args.mergePanels) {
+      const targetId = args.dashboardId?.trim();
+      if (!targetId) {
+        throw new Error(
+          "mergePanels=true requires dashboardId (the existing dashboard to append the template's panels to).",
+        );
+      }
+      const target = await getDashboard(targetId, ctx);
+      if (!target) {
+        throw new Error(
+          `Dashboard "${targetId}" not found (or you don't have access). mergePanels appends to an existing dashboard — install the template normally first, or omit mergePanels to create a new copy.`,
+        );
+      }
+
+      const targetConfig = target.config as Record<string, unknown>;
+      const existingPanels = Array.isArray(targetConfig.panels)
+        ? (targetConfig.panels as Array<Record<string, unknown>>)
+        : [];
+      const existingIds = new Set(
+        existingPanels
+          .map((panel) => (typeof panel?.id === "string" ? panel.id : null))
+          .filter((id): id is string => !!id),
+      );
+
+      const seedConfig = cloneDashboardConfig(entry);
+      const seedPanels = Array.isArray(seedConfig.panels)
+        ? (seedConfig.panels as unknown as Array<Record<string, unknown>>)
+        : [];
+
+      const addedPanelIds: string[] = [];
+      const skippedExistingIds: string[] = [];
+      const appended: Array<Record<string, unknown>> = [];
+      for (const panel of seedPanels) {
+        const id = typeof panel?.id === "string" ? panel.id : null;
+        if (id && existingIds.has(id)) {
+          skippedExistingIds.push(id);
+          continue;
+        }
+        appended.push(panel);
+        if (id) {
+          addedPanelIds.push(id);
+          existingIds.add(id);
+        }
+      }
+
+      const mergedConfig: Record<string, unknown> = {
+        ...targetConfig,
+        panels: [...existingPanels, ...appended],
+      };
+      const panelCount = (mergedConfig.panels as unknown[]).length;
+
+      if (appended.length > 0) {
+        const saved = await upsertDashboard(
+          targetId,
+          target.kind,
+          mergedConfig,
+          ctx,
+        );
+        await syncToCollab(targetId, mergedConfig);
+        targetConfig.name = saved.title;
+      }
+
+      return {
+        templateId: entry.id,
+        templateName: entry.name,
+        dashboardId: targetId,
+        name: target.title,
+        merged: true,
+        addedPanelIds,
+        skippedExistingIds,
+        panelCount,
+        urlPath: `/dashboards/${targetId}`,
+        deepLink: buildDeepLink({
+          app: "analytics",
+          view: "adhoc",
+          params: { dashboardId: targetId },
+        }),
+        message:
+          appended.length > 0
+            ? `Added ${addedPanelIds.length} panel(s) from "${entry.name}" to "${target.title}"; ${skippedExistingIds.length} already present. Dashboard now has ${panelCount} panel(s).`
+            : `No new panels to add from "${entry.name}" — all ${skippedExistingIds.length} template panel id(s) already present. Dashboard has ${panelCount} panel(s).`,
+      };
+    }
+
     const installed = (await listDashboardCatalog(ctx)).find(
       (template) => template.id === entry.id,
     );
@@ -100,7 +195,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 +239,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 {