@agent-native/core 0.78.9 → 0.79.0

package/corpus/core/src/index.browser.ts

@@ -104,6 +104,7 @@ export {
   ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
   ACTION_CHAT_UI_DATA_TABLE_RENDERER,
   ACTION_CHAT_UI_DATA_WIDGET_RENDERER,
+  ACTION_CHAT_UI_INLINE_EXTENSION_RENDERER,
   type ActionChatUIConfig,
 } from "./action-ui.js";
 export {

package/corpus/core/src/index.ts

@@ -58,6 +58,7 @@ export {
   ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
   ACTION_CHAT_UI_DATA_TABLE_RENDERER,
   ACTION_CHAT_UI_DATA_WIDGET_RENDERER,
+  ACTION_CHAT_UI_INLINE_EXTENSION_RENDERER,
   type ActionChatUIConfig,
 } from "./action-ui.js";
 export {

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -3036,21 +3036,29 @@ function buildFrameworkPrompts(
     ? "source-code handoffs and app-created artifacts such as extensions, widgets, dashboards, calculators, mini-apps, documents, designs, slides, or videos"
     : "source-code handoffs and app-created artifacts such as documents, designs, slides, or videos";
   const planModeBlockedTools = extensionToolsEnabled
-    ? "`create-extension`, `update-extension`, `connect-builder`, or any action that creates, updates, deletes, sends, publishes, or persists data"
+    ? "`render-inline-extension`, `create-extension`, `update-extension`, `connect-builder`, or any action that creates, updates, deletes, sends, publishes, or persists data"
     : "`connect-builder`, or any action that creates, updates, deletes, sends, publishes, or persists data";
   const extensionConnectBuilderGuard = extensionToolsEnabled
-    ? "If the request matches the Extensions section above, use `create-extension` or `update-extension` instead — do NOT route it to `connect-builder`."
+    ? "If the request matches the Extensions section above, use `render-inline-extension`, `create-extension`, `show-extension-inline`, or `update-extension` instead — do NOT route it to `connect-builder`."
     : "Because extension tools are disabled, do NOT invent an extension workflow. Only use `connect-builder` when the request genuinely requires changing the host app's source code.";
   const extensionInstructionsFull = extensionToolsEnabled
-    ? `### Extensions (Mini-Apps) — Use \`create-extension\` for extensions / widgets / dashboards
+    ? `### Generative UI and Extensions (Mini-Apps)
 
-In Act mode, if the user asks you to create, build, or make an **extension**, **widget**, **dashboard**, **calculator**, **mini-app**, or any small self-contained interactive utility — call \`create-extension\` immediately with a self-contained Alpine.js HTML body. This is **NOT** a code change and does **NOT** go through \`connect-builder\`. Extensions are sandboxed mini-apps stored in the database — no source files are touched, no PR is opened, no build is required. The extension appears in the Extensions view and can be edited later via \`update-extension\`.
+In Act mode, if the user asks for generated interactive UI in chat, choose the smallest extension action that matches the lifetime:
+
+- For a **one-time inline UI** that answers the current chat turn (knobs, controls, pickers, calculators, temporary dashboards, visualizers), call \`render-inline-extension\` immediately with a self-contained Alpine.js HTML body. It renders inside the transcript and is not saved.
+- For a **reusable or saved UI** (an extension/widget/dashboard/calculator/mini-app the user can reopen from Extensions), call \`create-extension\` with a self-contained Alpine.js HTML body. It saves to the Extensions view and also renders inline in chat.
+- To **reuse an existing saved extension inline**, call \`show-extension-inline\` with its id, or a search string when the id is unknown.
+
+These are **NOT** source-code changes and do **NOT** go through \`connect-builder\`. Extensions are sandboxed mini-apps — no source files are touched, no PR is opened, no build is required. Saved extensions can be edited later via \`update-extension\`.
 
 Keep \`create-extension\` payloads compact enough to finish quickly. For complex extensions, create a useful working v1 first, then call \`update-extension\` with focused edits for refinements instead of trying to assemble one enormous initial tool input.
 
+Generated UI content can use appAction(), appFetch(), dbQuery(), dbExec(), extensionFetch(), extensionData, agentNative.ui.output(value, opts?), and agentNative.chat.send(...)/sendToAgentChat(...). It can receive chat inputs through slotContext/window.onSlotContext. Use agentNative.ui.output for passive current values from knobs, sliders, selections, and controls; it writes application state at \`inline-ui:<extensionId>:output\` scoped to the inline extension id returned by \`render-inline-extension\` or \`show-extension-inline\`. When the user later says "use that value", "apply the current setting", or similar, read it with \`readAppState("inline-ui:<id>:output")\` instead of asking them to send it again. Use agentNative.chat.send for visible submit/apply actions that should put a message into chat. Transient extensionData is browser-local and not agent-readable, synced, promoted, or garbage-collected; use application_state/appFetch, appAction, ui.output, or chat.send for anything the agent or app must observe. Use semantic Tailwind classes like bg-background, text-foreground, bg-primary, border-border, and text-muted-foreground so the UI inherits the parent app theme.
+
 If the user asks to change, edit, fix, style, rename, or add behavior to an existing extension/widget/dashboard/calculator/mini-app, use the current extension id from \`<current-screen>\` or \`<current-url>\` when present. Call \`get-extension\` only if you need to inspect its content, then \`update-extension\` with that id. Use \`list-extensions\` only when no current id/name is available. Existing extension edits are SQL data updates, not source-code changes, even when the request says "change the UI" or "fix this". Do **NOT** call \`connect-builder\` for existing extension edits.
 
-In Act mode, when in doubt — if the request mentions creating an extension, widget, dashboard, calculator, or asks for a new small interactive utility — choose \`create-extension\`. If it references an existing one or the current extension page, choose \`update-extension\`. Do **not** preface the call with planning text like "let me build the dashboard…" — just call the right extension action directly.
+In Act mode, when in doubt — if the request asks for a new small interactive utility and does not need reuse, choose \`render-inline-extension\`; if it mentions saving/reuse or asks for an extension/widget/dashboard/calculator/mini-app, choose \`create-extension\`. If it references an existing one or the current extension page, choose \`update-extension\`. Do **not** preface the call with planning text like "let me build the dashboard…" — just call the right extension action directly.
 
 Note: "extension" is the user-facing primitive (the sandboxed Alpine.js mini-app). Don't confuse it with the LLM concept of "tools" (function calls) — those are how you invoke ANY action, including \`create-extension\` itself.
 
@@ -3063,10 +3071,12 @@ Route by what the request changes, not how it is phrased. Extensions render in t
 <routing>
 | The request is for…                                              | Path                          |
 | ---------------------------------------------------------------- | ----------------------------- |
+| A one-off interactive answer inside chat (controls, picker, calculator, temporary visualizer) | \`render-inline-extension\` — inline only |
 | A new self-contained surface (widget, dashboard, calculator, viewer, list, tracker) | \`create-extension\` — ships instantly, no PR |
+| Loading a saved extension inside chat | \`show-extension-inline\` |
 | Editing an existing extension (fix, restyle, rename, add behavior) | \`update-extension\`           |
 | The host app's own chrome (nav bar, sidebar, layout, routes, shipped components, existing styles, business logic) | \`connect-builder\` — a real source-code change |
-| Ambiguous, satisfiable either way (e.g. "give me an unread view") | \`create-extension\` (prefer the instant path) |
+| Ambiguous, satisfiable either way (e.g. "give me an unread view") | \`render-inline-extension\` for chat-only, \`create-extension\` for reusable |
 </routing>
 
 Worked examples: "a widget showing unread emails grouped by sender", "a dashboard summarizing my pipeline", "a tracker for my newsletter subscriptions" → \`create-extension\`. "Add an Unread tab to the left navigation", "make the subject lines wrap", "change the inbox grouping logic", "add a field to the compose form" → \`connect-builder\`.`
@@ -3074,19 +3084,21 @@ Worked examples: "a widget showing unread emails grouped by sender", "a dashboar
 
 Extension creation and management tools are disabled for this app. Do not claim you can create, edit, hide, or delete Agent-Native extensions unless the template exposes its own typed action for that workflow. For requests that would otherwise be handled as an extension/widget/dashboard/calculator mini-app, explain that this app has disabled extension tools and use the app's available actions instead.`;
   const extensionInstructionsCompact = extensionToolsEnabled
-    ? `### Extensions (Mini-Apps) — Use \`create-extension\`
+    ? `### Generative UI and Extensions (Mini-Apps)
 
-In Act mode, if the user asks for an **extension**, **widget**, **dashboard**, **calculator**, or **mini-app**, call \`create-extension\` immediately with a self-contained Alpine.js HTML body. This is NOT a code change — extensions are sandboxed mini-apps stored in the database. Do not preface with "let me build…" — just call \`create-extension\`.
+In Act mode, if the user asks for generated interactive UI in chat, call \`render-inline-extension\` for one-time inline controls/knobs/calculators/visualizers that do not need saving. If the user asks for an **extension**, **widget**, **dashboard**, **calculator**, or **mini-app** that should be reusable or saved, call \`create-extension\` with a self-contained Alpine.js HTML body. To load a saved extension inline, call \`show-extension-inline\`. These are NOT code changes — extensions are sandboxed mini-apps. Do not preface with "let me build…" — just call the right extension action.
 
 Keep the first \`create-extension\` call compact and working. If the request is complex, create the v1 first and then refine with focused \`update-extension\` edits.
 
+Generated UI can read chat inputs from slotContext/window.onSlotContext, see/update app state through appFetch/appAction, use extensionData, record passive current values through agentNative.ui.output(value, opts?), and send visible results through agentNative.chat.send(...) or sendToAgentChat(...). ui.output writes \`inline-ui:<extensionId>:output\` in application state; when the user asks to use the current slider/selection/value, read \`readAppState("inline-ui:<id>:output")\`. Transient extensionData is browser-local only, so do not rely on it for values the agent or app must observe. Use semantic Tailwind theme classes.
+
 If the user asks to change, edit, fix, style, rename, or add behavior to an existing extension/widget/dashboard/calculator/mini-app, use the current extension id from \`<current-screen>\` or \`<current-url>\` when present. Call \`get-extension\` only if you need to inspect its content, then \`update-extension\` with that id. Use \`list-extensions\` only when no current id/name is available. Existing extension edits are SQL data updates, not source-code changes. Do NOT call \`connect-builder\` for them.
 
 For existing extensions, use \`get-extension\` or \`update-extension\` directly when \`<current-screen>\` or \`<current-url>\` provides an \`extensionId\`. Use \`list-extensions\` only to browse or resolve an unknown name. Use \`hide-extension\` when the user wants a shared extension removed only from their own view. Do not query the legacy \`tools\` table directly.
 
 ### Extensions vs. Code Changes — Pick the Right Path
 
-If the user wants a **new self-contained surface** (custom widget, dashboard, list, viewer, calculator), use \`create-extension\` — extensions ship instantly without a PR. Use \`connect-builder\` only when the request **modifies the host app's existing chrome** (nav bar, sidebar, current components, layout, styles, routes). Extensions cannot change the host nav or restyle existing components.`
+If the user wants a **one-off interactive answer in chat**, use \`render-inline-extension\`. If they want a **new reusable self-contained surface** (custom widget, dashboard, list, viewer, calculator), use \`create-extension\` — extensions ship instantly without a PR. Use \`connect-builder\` only when the request **modifies the host app's existing chrome** (nav bar, sidebar, current components, layout, styles, routes). Extensions cannot change the host nav or restyle existing components.`
     : `### Extensions Disabled
 
 Extension creation and management tools are disabled for this app. Do not claim you can create, edit, hide, or delete Agent-Native extensions unless the template exposes its own typed action for that workflow.`;

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

@@ -73,6 +73,19 @@ Extensions have full access to app data via helpers injected into the iframe
   per-extension (supports `{ scope: 'user' | 'org' | 'all' }` option). Legacy
   alias: `toolData` — kept for back-compat; both names refer to the same
   store.
+- `agentNative.ui.output(value, opts?)` — when an extension is rendered inline
+  in chat, record passive control/selection output at
+  `inline-ui:<extensionId>:output` in application state so the agent can read it
+  later with `readAppState`.
+- `agentNative.chat.send(message, opts?)` — send a visible prompt or selected
+  value back into the current agent chat.
+
+For transient inline generative UI, `extensionData` is host-browser
+`localStorage`: the agent cannot read it, it does not sync across devices, it
+does not migrate when the UI is saved later, and the server does not garbage
+collect it. Use it only for throwaway local UI state. Use application state,
+`agentNative.ui.output`, `appAction`, or `agentNative.chat.send` for anything
+the agent or app must observe.
 
 ## Data Persistence is Built In
 

package/corpus/core/src/templates/workspace-core/.agents/skills/extensions/references/api.md

@@ -105,6 +105,8 @@ await dbExec("UPDATE notes SET title = 'Updated Title' WHERE id = 'abc'");
 | `extensionData.list(collection, opts?)`          | List items in a collection                               | `extensionData.list('todos', { scope: 'all' })`                                                                  |
 | `extensionData.get(collection, id, opts?)`       | Get a single item by id                                  | `extensionData.get('todos', 'todo-1')`                                                                           |
 | `extensionData.remove(collection, id, opts?)`    | Delete an item                                           | `extensionData.remove('todos', 'todo-1')`                                                                        |
+| `agentNative.ui.output(value, opts?)`            | Record passive inline UI output in application state     | `agentNative.ui.output({ threshold })`                                                                           |
+| `agentNative.chat.send(message, opts?)`          | Send a visible prompt or selected value back to chat     | `agentNative.chat.send('Use Q2', { context: { q: 2 } })`                                                         |
 
 ## Persisting Custom Data
 

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

@@ -0,0 +1,115 @@
+---
+name: generative-ui
+description: >-
+  Generate transient or saved inline chat UI with Alpine/Tailwind controls,
+  outputs, app state, and extensions. Use for knobs, pickers, calculators,
+  dashboards, widgets, or reusable mini-apps.
+---
+
+# Generative UI
+
+Generative UI is sandboxed Alpine.js HTML rendered inline in chat. It is not a
+source-code change and does not go through Builder.
+
+## Pick the Lifetime
+
+- Use `render-inline-extension` for one-off UI that belongs only in the current
+  chat: knobs, controls, pickers, calculators, temporary charts, and previews.
+- Use `create-extension` when the UI should be saved, reusable, or visible in
+  the Extensions view. It also renders inline after creation.
+- Use `show-extension-inline` to reopen a saved extension inside chat.
+- Use `update-extension` to edit an existing saved extension.
+
+## Inputs From Chat
+
+Pass initial values through the action `context` argument. The iframe reads them
+from `window.slotContext` and can subscribe to changes with
+`window.onSlotContext(fn)`.
+
+```html
+<script>
+  Alpine.data("controls", () => ({
+    threshold: 50,
+    init() {
+      this.threshold = Number(window.slotContext?.threshold ?? 50);
+      window.onSlotContext?.((ctx) => {
+        if (ctx.threshold !== undefined) {
+          this.threshold = Number(ctx.threshold);
+        }
+      });
+    },
+  }));
+</script>
+```
+
+## Outputs To The Agent
+
+Use passive output when a control's current value should be visible to the agent
+on the next turn without requiring a submit click:
+
+```html
+<input
+  type="range"
+  min="0"
+  max="100"
+  x-model.number="threshold"
+  @input="agentNative.ui.output({ threshold }, { label: 'Threshold' })"
+/>
+```
+
+`agentNative.ui.output(value, opts?)` writes application state at:
+
+```txt
+inline-ui:<extensionId>:output
+```
+
+The id is scoped automatically; the HTML author must not pass it. When the user
+says "use that value", "apply the current setting", or "run it with the current
+selection", read the value with:
+
+```ts
+const output = await readAppState("inline-ui:<id>:output");
+```
+
+The stored payload includes `value`, `updatedAt`, `extensionId`, and
+`source: "inline-ui"`, plus optional `label`, `context`, or `meta`.
+
+Use `agentNative.chat.send(message, opts?)` or `sendToAgentChat(message, opts?)`
+for a visible Apply/Submit button that should send a prompt or selected value
+into the chat.
+
+## App Data And State
+
+- Prefer `appAction(name, params)` for template data and operations.
+- Use `appFetch(path, options)` only for allowed framework endpoints under
+  `/_agent-native/*`, including application-state reads and writes.
+- Do not call template `/api/*` routes from generated UI.
+- Use `dbQuery`/`dbExec` only for known existing SQL tables when no action fits.
+- Use `extensionFetch` for external APIs through the sandbox proxy and secrets.
+
+## Transient extensionData Boundary
+
+For saved extensions, `extensionData` uses the authenticated database-backed
+extension data API.
+
+For transient inline UIs, `extensionData` is host `localStorage`. The agent
+cannot read it, it does not sync across devices, it does not migrate when a UI
+is promoted to a saved Extension, and the server does not garbage-collect it.
+Use it only for throwaway local UI state.
+
+For anything the agent or app must observe, use `agentNative.ui.output`,
+application state through `appFetch`, an `appAction`, or
+`agentNative.chat.send`.
+
+## Styling
+
+Use semantic Tailwind classes so the iframe inherits the parent app theme:
+
+- `bg-background`, `text-foreground`, `border-border`
+- `bg-card`, `text-card-foreground`
+- `bg-primary`, `text-primary-foreground`
+- `text-muted-foreground`, `bg-accent`
+
+Do not hardcode provider tokens, private data, or internal secrets in generated
+HTML. Do not call an LLM directly from the iframe; route AI work through the
+agent chat.

package/corpus/templates/analytics/.agents/skills/dashboard-management/SKILL.md

@@ -23,13 +23,17 @@ Current storage:
 
 Legacy settings keys such as `u:<email>:dashboard-*`, `u:<email>:sql-dashboard-*`, `o:<orgId>:sql-dashboard-*`, and `adhoc-analysis-*` are still read as a fallback and copied into SQL on access. Do not create new dashboard settings rows.
 
-Use `update-dashboard` for dashboard edits. It resolves the current user/org context, validates the config, applies JSON-pointer operations when provided, writes the SQL-backed record, and preserves sharing semantics.
+Use `mutate-dashboard` for existing dashboard edits. It resolves the current
+user/org context, validates the resulting config, writes the SQL-backed record,
+syncs collab, and returns compact proof. Use `update-dashboard` for new
+full-config saves, UI full-config saves, or explicitly requested low-level
+JSON-pointer edits.
 
 Never use `db-patch`, raw SQL, or settings-key edits to create or modify a
 dashboard config. Those bypass the dashboard action's access checks, SQL
-validation, collab sync, and proof-of-done return. If an `update-dashboard`
-call fails because the argument shape was wrong, fix the `update-dashboard`
-arguments and retry once — do not switch tools.
+validation, collab sync, and proof-of-done return. If a dashboard action fails
+because the argument shape was wrong, fix that action's arguments and retry
+once — do not switch to db-patch or raw SQL.
 
 ## Valid Panel Sources
 
@@ -68,7 +72,7 @@ The save path dry-runs BigQuery panels before persisting. If validation returns
 ## When To Use An Extension Instead
 
 Native Analytics dashboards are JSON configs rendered by the built-in dashboard
-components. Use `update-dashboard` only when the request fits that model:
+components. Use native dashboard actions only when the request fits that model:
 standard panels, supported chart types, filters, variables, sections, and grid
 layout.
 
@@ -167,71 +171,196 @@ Filters auto-apply on change — there is no Apply button. Each filter change wr
 
 ## Modifying A Dashboard
 
-Preferred patterns:
+For existing dashboard edits, default to `mutate-dashboard`. It gives the
+agent a small typed script API without exposing arbitrary JavaScript execution.
+The main action payload is a string, so it avoids native-array serialization
+traps in tool calls while still giving the agent a code-like editing surface.
+The server parses only documented `dashboard.*` method calls, applies the
+resulting operations in memory, validates the final dashboard config, writes
+SQL once, syncs collab, and returns compact proof.
+
+Arguments must be JSON-compatible literals, so quote object keys. Variables,
+imports, loops, functions, templates, network, filesystem, DB access, and
+calling other actions from the script are not available.
+
+```ts
+type DashboardMutationApi = {
+  dashboard: {
+    set(patch: DashboardPatch): void;
+    panel(id: string): PanelSelection;
+    section(id: string): SectionSelection;
+    panels(ids: string[]): PanelSelection;
+    panelsMatching(filter: PanelFilter): PanelSelection;
+    insertPanel(panel: PanelInput): InsertedPanel;
+  };
+};
+
+type DashboardPatch = {
+  name?: string;
+  description?: string;
+  columns?: number;
+  filters?: unknown[];
+  variables?: Record<string, string>;
+};
+
+type PanelPatch = {
+  title?: string;
+  sql?: string;
+  source?: "bigquery" | "ga4" | "amplitude" | "first-party" | "demo" | "prometheus";
+  chartType?: "line" | "area" | "bar" | "metric" | "table" | "pie" | "section" | "heatmap" | "callout";
+  width?: number;
+  columns?: number;
+  tab?: string;
+  config?: Record<string, unknown>;
+  description?: string;
+};
+
+type PanelInput = PanelPatch & {
+  id: string;
+  title: string;
+  chartType: NonNullable<PanelPatch["chartType"]>;
+  source?: PanelPatch["source"]; // required for non-section panels
+  sql?: string; // required for non-section panels
+};
+
+type PanelFilter = {
+  id?: string;
+  ids?: string[];
+  idIncludes?: string;
+  title?: string;
+  titleIncludes?: string;
+  chartType?: PanelPatch["chartType"];
+  source?: PanelPatch["source"];
+  tab?: string;
+  isSection?: boolean;
+};
+
+type PanelSelection = {
+  moveToTop(): void;
+  moveToBottom(): void;
+  moveBefore(panelId: string): void;
+  moveAfter(panelId: string): void;
+  moveToIndex(index: number): void;
+  remove(): void;
+  set(patch: PanelPatch): void;
+  setTitle(title: string): void;
+  setSql(sql: string): void;
+  setWidth(width: number): void;
+  setConfig(patch: Record<string, unknown>): void;
+  setConfigPath(path: string, value: unknown): void;
+  duplicate(newPanelId: string, patch?: PanelPatch): void;
+};
+
+type SectionSelection = PanelSelection & {
+  append(panelIds: string[]): void;
+};
+
+type InsertedPanel = {
+  atTop(): void;
+  atBottom(): void;
+  before(panelId: string): void;
+  after(panelId: string): void;
+  atIndex(index: number): void;
+};
+```
 
-```bash
-# JSON-pointer style patch
-pnpm action update-dashboard --dashboardId weekly-metrics \
-  --ops '[{"op":"replace","path":"/panels/0/title","value":"Events by Day"}]'
+Examples:
+
+```ts
+dashboard.panels(["dau-over-time", "wau-over-time"]).moveToTop();
+dashboard.panel("top-referrers").setTitle("Top Referrers by Domain");
+dashboard.panel("retention").set({
+  "width": 2,
+  "config": { "description": "Updated definition." }
+});
+dashboard.panelsMatching({ "source": "first-party" }).setWidth(2);
+dashboard.panelsMatching({ "titleIncludes": "Revenue" }).setConfigPath(
+  "yAxis.format",
+  "currency"
+);
+dashboard.panelsMatching({ "titleIncludes": "Signed-In" }).moveToTop();
+dashboard.section("retention-activity-section").append([
+  "repeat-users",
+  "retention-over-time"
+]);
+dashboard.insertPanel({
+  "id": "new-kpi",
+  "title": "New KPI",
+  "source": "first-party",
+  "chartType": "metric",
+  "width": 1,
+  "sql": "SELECT COUNT(*) AS value FROM analytics_events"
+}).atTop();
+```
 
-# Full config replacement
-pnpm action update-dashboard --dashboardId weekly-metrics --config '<full json>'
+Native tool call:
+
+```json
+{
+  "dashboardId": "weekly-metrics",
+  "code": "dashboard.panels([\"dau-over-time\",\"wau-over-time\"]).moveToTop();"
+}
 ```
 
-After a mutation, navigate to the dashboard if the user is elsewhere. The app syncs through the framework's polling/query invalidation path.
+Use `update-dashboard` only for new full-config saves, UI full-config saves, or
+when the user specifically requests low-level JSON-pointer edits.
 
-### Existing Dashboard Edits
+`get-sql-dashboard` is compact by default. It returns panel summaries, ids,
+titles, chart types, sources, layout groups, `layout.panelOrder`, and
+`layout.firstPanelIds` without embedding every panel's full SQL. Use that
+compact result to find panel ids and verify order. Pass `includeConfig: true`
+only when you need full panel SQL/config for a detailed edit.
 
-When the user asks to change existing panels:
+After a mutation, navigate to the dashboard if the user is elsewhere. The app syncs through the framework's polling/query invalidation path.
 
-1. Read the current dashboard config through the dashboard/action surface.
-2. Find panel indexes by `panel.id` from the current config you just read. Do
-   not rely on seed-file order, stale memory, or screenshots.
-3. Build one `ops` array that includes every change.
-4. Call `update-dashboard` once.
-5. Verify the returned `panelCount`, `appliedOps`, and `summary`. If possible,
-   read the affected panels back and confirm the exact fields changed.
+### Reordering Panels
 
-For native production tools, pass `ops` as a native array:
+For simple "move this chart/section" requests, prefer `mutate-dashboard` with a
+string script:
 
 ```json
 {
   "dashboardId": "weekly-metrics",
-  "ops": [
-    {
-      "op": "replace",
-      "path": "/panels/3/sql",
-      "value": "SELECT COUNT(*) AS value FROM analytics_events"
-    },
-    {
-      "op": "replace",
-      "path": "/panels/3/config/description",
-      "value": "Updated definition."
-    }
-  ]
+  "code": "dashboard.panels([\"dau-over-time\",\"wau-over-time\"]).moveToTop();"
 }
 ```
 
-The quoted JSON examples in this skill are for shell commands only. In native
-tool calls, do not pass `ops` as a string. If the tool complains about the
-shape, retry `update-dashboard` with a native array and continue from the same
-dashboard config.
+Do not do index arithmetic with `/panels/<index>` unless the user specifically
+asks for a low-level JSON-pointer edit. Use `moveBefore`, `moveAfter`,
+`moveToTop`, `moveToBottom`, or `moveToIndex` against panel ids instead.
+
+`get-sql-dashboard` returns `layout.panelOrder`, `layout.firstPanelIds`, and
+row/group summaries. Use those fields for orientation and verification instead
+of re-reading stale screenshots or counting positions from memory.
+
+### Existing Dashboard Edits
+
+When the user asks to change existing panels:
 
-For SQL-only panel edits, replacing `/panels/<index>/sql` is enough. If the
-metric semantics changed, also replace `/panels/<index>/config/description` so
-the visible dashboard explains the new definition. If the title, source, chart
-type, width, or config shape changes together, replace the whole panel object at
-`/panels/<index>` in the same `ops` array.
+1. Read the current dashboard with `get-sql-dashboard` compact mode unless full
+   SQL/config is required.
+2. Call `mutate-dashboard` once with every change in one script. Use
+   `panel(...)`, `panels([...])`, or `panelsMatching({...})` selectors by id or
+   metadata; do not compute shifted array indexes.
+3. Verify the returned `panelCount`, `appliedOps`, `firstPanelIds`, and
+   `summary`. If possible, read the affected panels back and confirm the exact
+   fields changed.
+
+For SQL-only panel edits, use `dashboard.panel("id").setSql("...")`. If the
+metric semantics changed, also update the visible definition with
+`setConfigPath("description", "...")` or `set({ "description": "..." })`. If
+the title, source, chart type, width, or config shape changes together, put them
+in the same `set({...})` call.
 
 ### First-Party User Metrics
 
 For first-party `/track` events, be precise about identity:
 
-| Metric intent                                | Identity expression                                      |
-| -------------------------------------------- | -------------------------------------------------------- |
-| Account users, DAU, WAU, retention, cohorts  | `NULLIF(user_id, '')` plus `NULLIF(user_id, '') IS NOT NULL`, but only on events that actually represent the activity being measured |
+| Metric intent                                | Identity expression                                                                                                                                                                |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Account users, DAU, WAU, retention, cohorts  | `NULLIF(user_id, '')` plus `NULLIF(user_id, '') IS NOT NULL`, but only on events that actually represent the activity being measured                                               |
 | Signed-in visitor activity                   | `event_name = 'session status' AND signed_in = 'true'` keyed by `COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, ''))`, labeled as signed-in visitors rather than account users |
-| Public traffic, visitors, clip/share viewers | `COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, ''))` |
+| Public traffic, visitors, clip/share viewers | `COALESCE(NULLIF(user_id, ''), NULLIF(anonymous_id, ''))`                                                                                                                          |
 
 Do not call anonymous visitors "users" in dashboard labels or descriptions.
 When a user asks for DAU, WAU, retention, repeat users, or account cohorts,
@@ -272,18 +401,26 @@ This is the dashboard-specific application of the framework-wide `reliable-mutat
 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:
 
 - **For a large first-party dashboard, use `compose-dashboard`** (see the section above): name the metrics, the server generates the panels in one call. Do not hand-author the big config.
-- **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`).
-  - In native tool calls, `ops` is an array, not a JSON string. Shell commands quote JSON only because shells need strings.
+- **Batch ALL edits into ONE `mutate-dashboard` call.** One script can move,
+  insert, remove, duplicate, and update many panels. Never loop dashboard edit
+  actions panel-by-panel.
+  - To bulk edit existing panels, use selectors:
+    `dashboard.panelsMatching({"source":"first-party"}).setWidth(2);`
+  - To make nested config edits, use
+    `setConfigPath("yAxis.format", "percent")` instead of resending/clobbering
+    the whole nested object.
 - **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.
+- **Always verify the returned proof-of-done and report it.**
+  `mutate-dashboard` returns `panelCount`, `appliedOps`, `panelOrder`,
+  `firstPanelIds`, `changedPanelIds`, `commandLog`, 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"}}]'
+# Add or edit several panels in ONE atomic call (never one call per panel)
+pnpm action mutate-dashboard --dashboardId weekly-metrics \
+  --code 'dashboard.panelsMatching({"source":"first-party"}).setWidth(2);'
 
 # 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
@@ -318,7 +455,9 @@ Writes require editor access; deletes require admin access. Owners always satisf
 - Never fabricate data or create a dashboard from guessed schema. A panel's SQL must hit a real source; do not present figures you did not actually query.
 - Never write dashboard configs into the settings table.
 - Never use `db-patch` as a fallback for dashboard config edits. Use
-  `update-dashboard` and fix the action arguments.
+  `mutate-dashboard` for existing edits, or `update-dashboard` for new/full
+  config saves, and fix the action arguments.
 - Never set `panel.source` to a table name or unsupported backend.
 - Use `first-party` for `/track` data and `query-agent-native-analytics` for ad-hoc first-party event questions.
-- Use `update-dashboard` for creates and edits.
+- Use `update-dashboard` for new dashboard config saves and full config
+  replacements. Use `mutate-dashboard` for existing dashboard edits.

package/corpus/templates/analytics/AGENTS.md

@@ -65,6 +65,18 @@ details live in `.agents/skills/`.
 - For shipped dashboard templates, call `list-dashboard-templates` first, then
   `install-dashboard-template` with the selected `templateId`. Do not recreate a
   catalog template by hand unless the user asks for a custom variant.
+- For dashboard edits, default to `mutate-dashboard` with its typed
+  `dashboard.*` script API. It supports id-based panel moves, title/SQL/config
+  edits, inserts, duplication, removal, and dashboard field patches in one
+  atomic save. The main payload is a string, so it avoids native-array
+  serialization traps. The script is constrained: only documented dashboard
+  method calls with JSON-compatible arguments are parsed; variables, imports,
+  loops, functions, network, filesystem, and DB access are not available.
+- Do not count shifting `/panels/<index>` values for ordinary dashboard edit
+  requests. Use low-level JSON-pointer edits only when explicitly requested.
+- `get-sql-dashboard` is compact by default for agents. Use its `panels`
+  summaries and `layout.panelOrder` / `layout.firstPanelIds` for orientation and
+  proof. Pass `includeConfig: true` only when full panel SQL/config is needed.
 - Native dashboards and saved analyses are constrained artifacts. If a requested
   dashboard, analysis surface, visualization, interaction model, custom layout,
   or bespoke workflow cannot be done faithfully with the built-in dashboard JSON