diff --git a/.gitleaksignore b/.gitleaksignore
index d9b9fcb25..f8bc1e186 100644
--- a/.gitleaksignore
+++ b/.gitleaksignore
@@ -1,3 +1,5 @@
 8f797d824d664ccecaf1ce356509db5a3e3b739d:e2e/tests/enterprise/oidc.spec.js:generic-api-key:174
 8f797d824d664ccecaf1ce356509db5a3e3b739d:e2e/tests/enterprise/oidc.spec.js:generic-api-key:175
 8f797d824d664ccecaf1ce356509db5a3e3b739d:e2e/tests/enterprise/oidc.spec.js:generic-api-key:176
+b45446d25724585fee8379601c351e0bb1960373:e2e/tests/console/mcpBridgePermissions.spec.js:generic-api-key:9
+b45446d25724585fee8379601c351e0bb1960373:src/utils/mcp/consumePendingPair.test.ts:generic-api-key:27
diff --git a/e2e/commands.js b/e2e/commands.js
index 785af348d..d939c9bc9 100644
--- a/e2e/commands.js
+++ b/e2e/commands.js
@@ -722,8 +722,13 @@ Cypress.Commands.add("getSearchResultGroups", () => {
   return cy.getByDataHook("search-result-buffer-group")
 })
 
-Cypress.Commands.add("createTabWithContent", (content, title) => {
+Cypress.Commands.add("addEditorTab", () => {
   cy.getByDataHook("new-tab-button").click()
+  cy.getByDataHook("new-tab-editor").click()
+})
+
+Cypress.Commands.add("createTabWithContent", (content, title) => {
+  cy.addEditorTab()
   cy.get(".chrome-tab-was-just-added").should("be.visible")
   cy.get(".chrome-tab-was-just-added").should("not.exist")
   cy.typeQueryDirectly(content)
diff --git a/e2e/questdb b/e2e/questdb
index 3b6d3ed93..88f051fee 160000
--- a/e2e/questdb
+++ b/e2e/questdb
@@ -1 +1 @@
-Subproject commit 3b6d3ed9325c78c6e3ccc6942608afab772c03a0
+Subproject commit 88f051feefbb5cdfe986851a14f33277a0f838f4
diff --git a/e2e/tests/console/aiAssistant.spec.js b/e2e/tests/console/aiAssistant.spec.js
index 248aa5119..5bc3533f1 100644
--- a/e2e/tests/console/aiAssistant.spec.js
+++ b/e2e/tests/console/aiAssistant.spec.js
@@ -396,8 +396,9 @@ describe("ai assistant", () => {
       // Then
       cy.getByDataHook("ai-settings-modal-step-two").should("be.visible")
 
-      // When
-      cy.getByDataHook("ai-settings-schema-access").click()
+      // When - drop permissions to None so schema tools are excluded.
+      cy.getByDataHook("permissions-trigger").click()
+      cy.getByDataHook("permission-level-none").click()
       cy.getByDataHook("multi-step-modal-next-button").click()
 
       // Then - AI chat should be available
@@ -420,9 +421,10 @@ describe("ai assistant", () => {
         })
       })
 
-      // When - Open settings modal and enable schema access
+      // When - Open settings modal and re-enable schema access
       cy.getByDataHook("ai-assistant-settings-button").click()
-      cy.getByDataHook("ai-settings-schema-access").click()
+      cy.getByDataHook("permissions-trigger").click()
+      cy.getByDataHook("permission-level-schema").click()
       cy.getByDataHook("ai-settings-save").click()
       cy.get(".toast-success-container").should("be.visible").click()
 
@@ -1234,7 +1236,7 @@ describe("ai assistant", () => {
 
       // When - Close chat and create a new tab
       cy.getByDataHook("chat-window-close").click()
-      cy.get(".new-tab-button").click()
+      cy.addEditorTab()
 
       // Then - New tab should be created (2 tabs total now)
       cy.getEditorTabs().should("have.length", 2)
@@ -3026,7 +3028,7 @@ Syntax: \`avg(column)\`
 
       // Close the tab that the suggestion was applied to (archive the buffer)
       // First, create another tab so we can close the current one
-      cy.get(".new-tab-button").click()
+      cy.addEditorTab()
       cy.getEditorTabs().should("have.length", 2)
 
       // Close the first tab (the one with the accepted query)
@@ -3336,7 +3338,8 @@ describe("custom providers", () => {
     cy.getByDataHook("custom-provider-remove-model").click()
     cy.getByDataHook("custom-provider-model-chip").should("not.exist")
 
-    cy.getByDataHook("custom-provider-schema-access").check()
+    cy.getByDataHook("permissions-trigger").click()
+    cy.getByDataHook("permission-level-schema").click()
     cy.getByDataHook("multi-step-modal-next-button").click()
 
     cy.contains("AI Assistant activated successfully").should("be.visible")
@@ -3911,7 +3914,7 @@ describe("custom providers", () => {
       "have.value",
       "200000",
     )
-    cy.getByDataHook("custom-provider-schema-access").should("be.checked")
+    cy.getByDataHook("permissions-trigger").should("contain", "Schema access")
     cy.getByDataHook("custom-provider-add-model-button").should("be.disabled")
 
     cy.getByDataHook("custom-provider-manual-model-input").type(
@@ -4266,8 +4269,8 @@ describe("custom providers", () => {
     cy.get("[data-model='llama3']").should("exist")
     cy.get("[data-model='mistral']").should("exist")
 
-    // Schema access toggle is not disabled
-    cy.getByDataHook("ai-settings-schema-access").should("not.be.disabled")
+    // Permissions select is not disabled
+    cy.getByDataHook("permissions-trigger").should("not.be.disabled")
 
     // Manage models button visible
     cy.getByDataHook("ai-settings-manage-models").should("be.visible")
diff --git a/e2e/tests/console/aiAssistantPermissions.spec.js b/e2e/tests/console/aiAssistantPermissions.spec.js
new file mode 100644
index 000000000..f8f7651d4
--- /dev/null
+++ b/e2e/tests/console/aiAssistantPermissions.spec.js
@@ -0,0 +1,243 @@
+/// <reference types="cypress" />
+
+const {
+  PROVIDERS,
+  getOpenAIConfiguredSettings,
+  getOpenAIPermissionedSettings,
+  createToolCallFlow,
+} = require("../../utils/aiAssistant")
+
+const installValidateIntercept = () => {
+  cy.intercept("GET", "**/api/v1/sql/validate*", (req) => {
+    const url = new URL(req.url)
+    const sql = (url.searchParams.get("query") || "").trim().toUpperCase()
+    if (sql.startsWith("SELECT") || sql.startsWith("SHOW")) {
+      req.reply({
+        statusCode: 200,
+        body: {
+          query: sql,
+          columns: [{ name: "c1", type: "LONG" }],
+          timestamp: -1,
+        },
+      })
+      return
+    }
+    if (
+      sql.startsWith("INSERT") ||
+      sql.startsWith("UPDATE") ||
+      sql.startsWith("DELETE")
+    ) {
+      req.reply({ statusCode: 200, body: { queryType: "INSERT" } })
+      return
+    }
+    req.reply({ statusCode: 200, body: { queryType: "CREATE TABLE" } })
+  }).as("validate")
+}
+
+const installExecDqlIntercept = () => {
+  cy.intercept("GET", "**/exec*", (req) => {
+    req.reply({
+      statusCode: 200,
+      body: {
+        query: "SELECT 1",
+        columns: [{ name: "c1", type: "LONG" }],
+        dataset: [[1]],
+        count: 1,
+        timestamp: -1,
+      },
+    })
+  }).as("exec")
+}
+
+// get_questdb_toc fetches the docs TOC over the network; stub it so the free
+// tool resolves deterministically instead of reaching questdb.com.
+const installDocsTocIntercept = () => {
+  cy.intercept("GET", "**/web-console/toc-list.json", {
+    statusCode: 200,
+    body: { functions: ["count()"], operators: ["="], sql: ["SELECT"] },
+  }).as("docsToc")
+}
+
+// Every backend a granted tool can touch, stubbed in one call so a single
+// conversation can drive the full surface matrix without hitting the live DB.
+const installToolStubs = () => {
+  installValidateIntercept()
+  installExecDqlIntercept()
+  installDocsTocIntercept()
+}
+
+describe("ai assistant permissions", () => {
+  beforeEach(() => {
+    // Fail loudly on any unmocked provider request — each test scripts its own intercept.
+    cy.intercept("POST", PROVIDERS.openai.endpoint, (req) => {
+      throw new Error(
+        `Unhandled OpenAI request detected! Request body: ${JSON.stringify(
+          req.body,
+        ).slice(0, 200)}...`,
+      )
+    }).as("unhandledOpenAI")
+  })
+
+  describe("PermissionsSection in settings modals", () => {
+    beforeEach(() => {
+      cy.loadConsoleWithAuth(false, getOpenAIConfiguredSettings())
+    })
+
+    it("renders permission level select with cascading levels in SettingsModal", () => {
+      cy.getByDataHook("ai-assistant-settings-button")
+        .should("be.visible")
+        .click()
+
+      cy.getByDataHook("permissions").should("be.visible")
+      cy.getByDataHook("permissions-trigger").should("contain", "Schema access")
+
+      // Raise to Write: trigger label updates and all levels listed in menu.
+      cy.getByDataHook("permissions-trigger").click()
+      cy.getByDataHook("permission-level-write").click()
+      cy.getByDataHook("permissions-trigger").should("contain", "Write")
+
+      // Drop to None: trigger label updates back.
+      cy.getByDataHook("permissions-trigger").click()
+      cy.getByDataHook("permission-level-none").click()
+      cy.getByDataHook("permissions-trigger").should("contain", "None")
+    })
+  })
+
+  describe("tool permission gate — one pass per level", () => {
+    const GRANTED = { excludes: ["PERMISSION_DENIED"] }
+    const GRANTED_DQL = {
+      includes: ['"type":"dql"'],
+      excludes: ["PERMISSION_DENIED"],
+    }
+    const DENIED_SCHEMA = {
+      includes: ["PERMISSION_DENIED", "grantSchemaAccess"],
+    }
+    const DENIED_READ = { includes: ["PERMISSION_DENIED", "'read' permission"] }
+    const DENIED_WRITE = {
+      includes: ["PERMISSION_DENIED", "'write' permission"],
+    }
+
+    const hasRead = (level) => level === "read" || level === "write"
+
+    // Each surface is one tool call; `expect(level)` is the assertion for that
+    // surface's tool result at the configured level. free tools never gate;
+    // schema tools need grantSchemaAccess; run_query DQL needs read, DDL/DML
+    // needs write.
+    const SURFACES = [
+      {
+        toolCall: { name: "validate_query", args: { query: "SELECT 1" } },
+        expect: () => GRANTED,
+      },
+      {
+        toolCall: { name: "suggest_query", args: { query: "SELECT 1" } },
+        expect: () => GRANTED,
+      },
+      {
+        toolCall: { name: "get_questdb_toc", args: {} },
+        expect: () => GRANTED,
+      },
+      {
+        toolCall: { name: "get_tables", args: {} },
+        expect: (level) => (level === "none" ? DENIED_SCHEMA : GRANTED),
+      },
+      {
+        toolCall: {
+          name: "get_table_schema",
+          args: { table_name: "btc_trades" },
+        },
+        expect: (level) => (level === "none" ? DENIED_SCHEMA : GRANTED),
+      },
+      {
+        toolCall: {
+          name: "get_table_details",
+          args: { table_name: "btc_trades" },
+        },
+        expect: (level) => (level === "none" ? DENIED_SCHEMA : GRANTED),
+      },
+      {
+        toolCall: {
+          name: "run_query",
+          args: { sql: "SELECT count(*) FROM btc_trades" },
+        },
+        expect: (level) => (hasRead(level) ? GRANTED_DQL : DENIED_READ),
+      },
+      {
+        toolCall: { name: "run_query", args: { sql: "DROP TABLE btc_trades" } },
+        expect: (level) => (level === "write" ? GRANTED : DENIED_WRITE),
+      },
+    ]
+
+    const buildSteps = (level) => {
+      const steps = SURFACES.map((surface, index) => ({
+        toolCall: surface.toolCall,
+        ...(index > 0
+          ? { expectToolResult: SURFACES[index - 1].expect(level) }
+          : {}),
+      }))
+      steps.push({
+        finalResponse: {
+          explanation: "Permission matrix probe complete.",
+          sql: null,
+        },
+        expectToolResult: SURFACES[SURFACES.length - 1].expect(level),
+      })
+      return steps
+    }
+
+    const runMatrix = (level) => {
+      const flow = createToolCallFlow({
+        provider: "openai",
+        streaming: true,
+        question: `Probe tool permissions for the ${level} level.`,
+        steps: buildSteps(level),
+      })
+
+      flow.intercept()
+      cy.getByDataHook("ai-chat-button").click()
+      cy.getByDataHook("chat-input-textarea")
+        .should("be.visible")
+        .type(flow.question)
+      cy.getByDataHook("chat-send-button").click()
+      flow.waitForCompletion()
+
+      cy.getByDataHook("chat-message-assistant")
+        .should("be.visible")
+        .should("contain", "matrix probe complete")
+    }
+
+    const LEVELS = {
+      none: { read: false, write: false, grantSchemaAccess: false },
+      schema: { read: false, write: false, grantSchemaAccess: true },
+      read: { read: true, write: false, grantSchemaAccess: true },
+      write: { read: true, write: true, grantSchemaAccess: true },
+    }
+
+    const loadAtLevel = (level) => {
+      cy.loadConsoleWithAuth(
+        false,
+        getOpenAIPermissionedSettings(LEVELS[level]),
+      )
+      installToolStubs()
+    }
+
+    it("none: free tools pass, schema and SQL tools are denied", () => {
+      loadAtLevel("none")
+      runMatrix("none")
+    })
+
+    it("schema access: schema tools pass, SQL tools still denied", () => {
+      loadAtLevel("schema")
+      runMatrix("schema")
+    })
+
+    it("read access: DQL runs, write SQL still denied", () => {
+      loadAtLevel("read")
+      runMatrix("read")
+    })
+
+    it("write access: every tool surface is granted", () => {
+      loadAtLevel("write")
+      runMatrix("write")
+    })
+  })
+})
diff --git a/e2e/tests/console/editor.spec.js b/e2e/tests/console/editor.spec.js
index ebacbd173..b49ef326a 100644
--- a/e2e/tests/console/editor.spec.js
+++ b/e2e/tests/console/editor.spec.js
@@ -1360,7 +1360,7 @@ describe("editor tabs", () => {
   })
 
   it("should open the second empty tab on plus icon click", () => {
-    cy.get(".new-tab-button").click()
+    cy.addEditorTab()
     cy.get(".chrome-tab-was-just-added").should("not.exist")
     cy.getEditorTabs().should("have.length", 2)
     ;["SQL", "SQL 1"].forEach((title) => {
@@ -1411,7 +1411,7 @@ describe("editor tabs", () => {
   })
 
   it("should drag tabs", () => {
-    cy.get(".new-tab-button").click()
+    cy.addEditorTab()
     cy.get(".chrome-tab-was-just-added").should("not.exist")
     cy.getEditorTabByTitle("SQL").should("be.visible")
     cy.getEditorTabByTitle("SQL 1").should("be.visible")
@@ -1451,7 +1451,7 @@ describe.skip("editor tabs history", () => {
   it("should close and archive tabs", () => {
     cy.typeQuery("--1")
     ;["SQL 1", "SQL 2"].forEach((title) => {
-      cy.get(".new-tab-button").click()
+      cy.addEditorTab()
       const dragHandle = getTabDragHandleByTitle(title)
       cy.get(dragHandle).should("be.visible")
     })
@@ -1487,9 +1487,7 @@ describe.skip("editor tabs history", () => {
 
 describe("handling comments", () => {
   beforeEach(() => {
-    cy.loadConsoleWithAuth(false, {
-      "splitter.results.basis": Number.MAX_SAFE_INTEGER.toString(),
-    })
+    cy.loadConsoleWithAuth(false)
   })
 
   beforeEach(() => {
@@ -1763,7 +1761,7 @@ describe("multiple run buttons with dynamic query log", () => {
     cy.getCursorQueryGlyph().should("have.length", 3)
 
     // When
-    cy.get(".new-tab-button").click()
+    cy.addEditorTab()
     // Then
     cy.getEditorTabByTitle("SQL 1")
       .should("be.visible")
@@ -1904,7 +1902,7 @@ describe("import/export tabs", () => {
     cy.getEditorTabs().should("be.visible")
   })
 
-  it("should show error toast when importing invalid file", () => {
+  it("should show validation reason in import summary when importing invalid file", () => {
     cy.getByDataHook("editor-tabs-menu-button").click()
     cy.getByDataHook("editor-tabs-menu").should("be.visible")
 
@@ -1914,11 +1912,19 @@ describe("import/export tabs", () => {
       { force: true },
     )
 
-    cy.get(".toast-error-container")
-      .should("be.visible")
-      .should("contain", "Failed to import tabs")
-      .should("contain", "(id: 1)")
-      .should("contain", "label must be a string")
+    // An invalid tab is skipped rather than aborting the whole import; its
+    // validation reason is surfaced in the summary dialog.
+    cy.getByDataHook("import-summary-dialog").should("be.visible")
+    cy.getByDataHook("import-summary-dialog").should("contain", "0 tab")
+    cy.getByDataHook("import-summary-dialog").should("contain", "1 tab skipped")
+    cy.getByDataHook("import-summary-skipped-item").should("have.length", 1)
+    cy.getByDataHook("import-summary-skipped-item").should(
+      "contain",
+      "label must be a string",
+    )
+
+    cy.getByDataHook("import-summary-close").click()
+    cy.getByDataHook("import-summary-dialog").should("not.exist")
   })
 
   it("should import tabs successfully with active and archived tabs", () => {
diff --git a/e2e/tests/console/mcpBridgePermissions.spec.js b/e2e/tests/console/mcpBridgePermissions.spec.js
new file mode 100644
index 000000000..bfeaa1bcb
--- /dev/null
+++ b/e2e/tests/console/mcpBridgePermissions.spec.js
@@ -0,0 +1,433 @@
+/// <reference types="cypress" />
+
+// E2E coverage for the MCP bridge permission system.
+
+const contextPath = process.env.QDB_HTTP_CONTEXT_WEB_CONSOLE || ""
+const baseUrl = `http://localhost:9999${contextPath}`
+
+const TEST_BRIDGE_URL = "ws://127.0.0.1:57123"
+const TEST_BRIDGE_TOKEN = "abcdef0123456789abcdef0123456789"
+// Must match src/utils/mcp/protocolVersion.ts; mismatches are silently dropped.
+const PROTOCOL_VERSION = "1"
+
+// Fake WebSocket installed before the app boots; exposed on `win.__mcpFakeWS`.
+const installFakeWebSocket = (win) => {
+  class FakeWS {
+    constructor(url) {
+      this.url = url
+      this.readyState = 0
+      this.sent = []
+      this.listeners = {}
+      win.__mcpFakeWS = this
+      // Async "open" mirrors real WebSocket — lets listener registration finish.
+      win.setTimeout(() => {
+        this.readyState = 1
+        this._dispatch("open", {})
+      }, 0)
+    }
+    addEventListener(type, fn) {
+      if (!this.listeners[type]) this.listeners[type] = new Set()
+      this.listeners[type].add(fn)
+    }
+    removeEventListener(type, fn) {
+      this.listeners[type]?.delete(fn)
+    }
+    send(data) {
+      if (this.readyState !== 1) {
+        throw new Error("FakeWS.send while not open")
+      }
+      this.sent.push(data)
+      const parsed = JSON.parse(data)
+      if (parsed.type === "ping") {
+        this.receive({
+          v: PROTOCOL_VERSION,
+          type: "pong",
+          nonce: parsed.nonce,
+        })
+      }
+    }
+    close() {
+      this.readyState = 3
+      this._dispatch("close", { code: 1000, reason: "test-close" })
+    }
+    receive(payload) {
+      this._dispatch("message", { data: JSON.stringify(payload) })
+    }
+    helloAck() {
+      this.receive({
+        v: PROTOCOL_VERSION,
+        type: "hello_ack",
+        sessionId: "test-session",
+        heartbeatIntervalMs: 60000,
+        seenToolCount: 1,
+      })
+    }
+    toolCall(name, args, requestId) {
+      const id = requestId || "req-" + Math.random().toString(36).slice(2)
+      this.receive({
+        v: PROTOCOL_VERSION,
+        type: "tool_call",
+        requestId: id,
+        name,
+        arguments: args,
+        deadlineMs: 15000,
+      })
+      return id
+    }
+    _dispatch(type, ev) {
+      this.listeners[type]?.forEach((fn) => fn(ev))
+    }
+    framesOfType(type) {
+      return this.sent.map((s) => JSON.parse(s)).filter((m) => m.type === type)
+    }
+  }
+  // Real-WebSocket statics — MCPBridgeClient reads WebSocket.OPEN.
+  FakeWS.CONNECTING = 0
+  FakeWS.OPEN = 1
+  FakeWS.CLOSING = 2
+  FakeWS.CLOSED = 3
+  win.WebSocket = FakeWS
+}
+
+// Permission classifier calls /api/v1/sql/validate to distinguish DQL vs DDL/DML.
+const installValidateIntercept = () => {
+  cy.intercept("GET", "**/api/v1/sql/validate*", (req) => {
+    const url = new URL(req.url)
+    const sql = (url.searchParams.get("query") || "").trim().toUpperCase()
+    if (sql.startsWith("SELECT") || sql.startsWith("SHOW")) {
+      req.reply({
+        statusCode: 200,
+        body: {
+          query: sql,
+          columns: [{ name: "c1", type: "LONG" }],
+          timestamp: -1,
+        },
+      })
+      return
+    }
+    if (
+      sql.startsWith("INSERT") ||
+      sql.startsWith("UPDATE") ||
+      sql.startsWith("DELETE")
+    ) {
+      req.reply({ statusCode: 200, body: { queryType: "INSERT" } })
+      return
+    }
+    req.reply({ statusCode: 200, body: { queryType: "CREATE TABLE" } })
+  }).as("validate")
+}
+
+const deepLinkSuffix = () =>
+  `?mcp-pair=1&mcp-ws=${encodeURIComponent(TEST_BRIDGE_URL)}` +
+  `&mcp-token=${encodeURIComponent(TEST_BRIDGE_TOKEN)}`
+
+// Visit with deep-link params before login so they survive into the SPA boot.
+const loginAndVisitDeepLink = (seedLocalStorage = {}) => {
+  cy.visit(`${baseUrl}/${deepLinkSuffix()}`, {
+    onBeforeLoad: (win) => {
+      win.localStorage.clear()
+      win.sessionStorage.clear()
+      win.indexedDB.deleteDatabase("web-console")
+      for (const [k, v] of Object.entries(seedLocalStorage)) {
+        win.localStorage.setItem(k, v)
+      }
+      installFakeWebSocket(win)
+    },
+  })
+  cy.loginWithUserAndPassword()
+}
+
+const waitForPaired = () => {
+  cy.window({ timeout: 10000 }).its("__mcpFakeWS").should("exist")
+  cy.window({ timeout: 10000 }).should((win) => {
+    expect(win.__mcpFakeWS.framesOfType("hello").length).to.be.greaterThan(0)
+  })
+  cy.window().then((win) => win.__mcpFakeWS.helloAck())
+  cy.getByDataHook("mcp-bridge-status-pill", { timeout: 10000 }).should(
+    "contain",
+    "MCP connected",
+  )
+}
+
+const lastToolResult = (win, requestId) => {
+  const results = win.__mcpFakeWS.framesOfType("tool_result")
+  return results.find((r) => r.requestId === requestId)
+}
+
+describe("MCP bridge permissions (e2e)", () => {
+  beforeEach(() => {
+    installValidateIntercept()
+  })
+
+  describe("consent modal", () => {
+    it("default is Read; user raises to Write before Connect; hello carries { grantSchemaAccess:T, read:T, write:T }", () => {
+      loginAndVisitDeepLink()
+
+      cy.getByDataHook("permissions").should("be.visible")
+      cy.getByDataHook("permissions-trigger").should("contain", "Read")
+
+      cy.getByDataHook("permissions-trigger").click()
+      cy.getByDataHook("permission-level-write").click()
+      cy.getByDataHook("permissions-trigger").should("contain", "Write")
+
+      cy.getByDataHook("mcp-pair-consent-connect").click()
+
+      cy.window().should((win) => {
+        const hellos = win.__mcpFakeWS.framesOfType("hello")
+        expect(hellos.length).to.be.greaterThan(0)
+        expect(hellos[0].permissions).to.deep.equal({
+          grantSchemaAccess: true,
+          read: true,
+          write: true,
+        })
+        expect(hellos[0].token).to.equal(TEST_BRIDGE_TOKEN)
+      })
+
+      cy.window().then((win) => win.__mcpFakeWS.helloAck())
+      cy.getByDataHook("mcp-bridge-status-pill").should(
+        "contain",
+        "MCP connected",
+      )
+      cy.window().then((win) => {
+        expect(
+          JSON.parse(win.localStorage.getItem("mcp:permissions")),
+        ).to.deep.equal({
+          grantSchemaAccess: true,
+          read: true,
+          write: true,
+        })
+      })
+    })
+
+    it("user drops to None; hello carries all-false", () => {
+      loginAndVisitDeepLink()
+
+      cy.getByDataHook("permissions-trigger").click()
+      cy.getByDataHook("permission-level-none").click()
+      cy.getByDataHook("permissions-trigger").should("contain", "None")
+
+      cy.getByDataHook("mcp-pair-consent-connect").click()
+      cy.window().should((win) => {
+        const hellos = win.__mcpFakeWS.framesOfType("hello")
+        expect(hellos.length).to.be.greaterThan(0)
+        expect(hellos[0].permissions).to.deep.equal({
+          grantSchemaAccess: false,
+          read: false,
+          write: false,
+        })
+      })
+    })
+  })
+
+  describe("permission gate over the wire", () => {
+    const expectedLabel = (p) => {
+      if (p.write) return "Write"
+      if (p.read) return "Read"
+      if (p.grantSchemaAccess) return "Schema access"
+      return "None"
+    }
+    const setupPaired = (permissions) => {
+      loginAndVisitDeepLink({
+        "mcp:permissions": JSON.stringify(permissions),
+      })
+      cy.getByDataHook("permissions-trigger").should(
+        "contain",
+        expectedLabel(permissions),
+      )
+      cy.getByDataHook("mcp-pair-consent-connect").click()
+      waitForPaired()
+    }
+
+    it("read+write granted: DQL, DML, schema all run", () => {
+      setupPaired({ grantSchemaAccess: true, read: true, write: true })
+
+      const ids = {}
+      cy.window().then((win) => {
+        ids.dql = win.__mcpFakeWS.toolCall("run_query", {
+          sql: "SELECT 1",
+          limit: 10,
+        })
+        ids.dml = win.__mcpFakeWS.toolCall("run_query", {
+          sql: "INSERT INTO t VALUES (1)",
+          limit: 10,
+        })
+        ids.schema = win.__mcpFakeWS.toolCall("get_tables", {})
+      })
+
+      cy.window({ timeout: 10000 }).should((w) => {
+        expect(w.__mcpFakeWS.framesOfType("tool_result").length).to.be.gte(3)
+      })
+
+      cy.window().then((w) => {
+        // Only PERMISSION_DENIED matters here; other errors are ignored.
+        for (const id of Object.values(ids)) {
+          const r = lastToolResult(w, id)
+          expect(r, `result for ${id}`).to.exist
+          if (r.isError) {
+            expect(r.content[0].text).to.not.match(/PERMISSION_DENIED/)
+          }
+        }
+      })
+    })
+
+    it("read-only: DQL granted, DDL/DML denied via /validate classification", () => {
+      setupPaired({ grantSchemaAccess: true, read: true, write: false })
+
+      const ids = {}
+      cy.window().then((win) => {
+        ids.dql = win.__mcpFakeWS.toolCall("run_query", {
+          sql: "SELECT * FROM t",
+          limit: 10,
+        })
+        ids.dml = win.__mcpFakeWS.toolCall("run_query", {
+          sql: "INSERT INTO t VALUES (1)",
+          limit: 10,
+        })
+        ids.ddl = win.__mcpFakeWS.toolCall("run_query", {
+          sql: "CREATE TABLE t (a INT)",
+          limit: 10,
+        })
+        ids.schema = win.__mcpFakeWS.toolCall("get_tables", {})
+      })
+
+      cy.window({ timeout: 10000 }).should((w) => {
+        expect(w.__mcpFakeWS.framesOfType("tool_result").length).to.be.gte(4)
+      })
+
+      cy.window().then((w) => {
+        const dml = lastToolResult(w, ids.dml)
+        expect(dml.isError).to.equal(true)
+        expect(dml.content[0].text).to.match(/PERMISSION_DENIED/)
+        expect(dml.content[0].text).to.match(/'write' permission/)
+
+        const ddl = lastToolResult(w, ids.ddl)
+        expect(ddl.isError).to.equal(true)
+        expect(ddl.content[0].text).to.match(/PERMISSION_DENIED/)
+
+        const schema = lastToolResult(w, ids.schema)
+        if (schema.isError) {
+          expect(schema.content[0].text).to.not.match(/PERMISSION_DENIED/)
+        }
+        const dql = lastToolResult(w, ids.dql)
+        if (dql.isError) {
+          expect(dql.content[0].text).to.not.match(/PERMISSION_DENIED/)
+        }
+      })
+    })
+
+    it("no permissions: even DQL + schema reads are denied", () => {
+      setupPaired({ grantSchemaAccess: false, read: false, write: false })
+
+      const ids = {}
+      cy.window().then((win) => {
+        ids.dql = win.__mcpFakeWS.toolCall("run_query", {
+          sql: "SELECT 1",
+          limit: 10,
+        })
+        ids.schema = win.__mcpFakeWS.toolCall("get_tables", {})
+      })
+
+      cy.window({ timeout: 10000 }).should((w) => {
+        expect(w.__mcpFakeWS.framesOfType("tool_result").length).to.be.gte(2)
+      })
+
+      cy.window().then((w) => {
+        const dql = lastToolResult(w, ids.dql)
+        expect(dql.isError).to.equal(true)
+        expect(dql.content[0].text).to.match(/PERMISSION_DENIED/)
+
+        const schema = lastToolResult(w, ids.schema)
+        expect(schema.isError).to.equal(true)
+        expect(schema.content[0].text).to.match(/PERMISSION_DENIED/)
+        expect(schema.content[0].text).to.match(/'grantSchemaAccess'/)
+      })
+    })
+  })
+
+  describe("popover: submit-only persistence", () => {
+    it("raising to Write without clicking Apply does NOT change localStorage", () => {
+      loginAndVisitDeepLink()
+      cy.getByDataHook("mcp-pair-consent-connect").click()
+      waitForPaired()
+
+      cy.getByDataHook("mcp-bridge-status-pill").click()
+      cy.getByDataHook("mcp-pair-popover").should("be.visible")
+
+      cy.window().then((win) => {
+        expect(
+          JSON.parse(win.localStorage.getItem("mcp:permissions")),
+        ).to.deep.equal({ grantSchemaAccess: true, read: true, write: false })
+      })
+
+      cy.getByDataHook("permissions-trigger").click()
+      cy.getByDataHook("permission-level-write").click()
+      cy.getByDataHook("mcp-pair-cancel").click()
+
+      cy.window().then((win) => {
+        expect(
+          JSON.parse(win.localStorage.getItem("mcp:permissions")),
+        ).to.deep.equal({ grantSchemaAccess: true, read: true, write: false })
+      })
+
+      cy.getByDataHook("mcp-bridge-status-pill").click()
+      cy.getByDataHook("permissions-trigger").should("contain", "Read")
+    })
+
+    it("raise to Write + Apply: localStorage updates, no reconnect", () => {
+      loginAndVisitDeepLink()
+      cy.getByDataHook("mcp-pair-consent-connect").click()
+      waitForPaired()
+
+      cy.getByDataHook("mcp-bridge-status-pill").click()
+      cy.getByDataHook("permissions-trigger").click()
+      cy.getByDataHook("permission-level-write").click()
+      cy.getByDataHook("mcp-pair-submit").should("contain", "Connect").click()
+
+      cy.window().then((win) => {
+        expect(
+          JSON.parse(win.localStorage.getItem("mcp:permissions")),
+        ).to.deep.equal({ grantSchemaAccess: true, read: true, write: true })
+        expect(win.__mcpFakeWS.framesOfType("hello")).to.have.length(1)
+      })
+      cy.getByDataHook("mcp-bridge-status-pill").should(
+        "contain",
+        "MCP connected",
+      )
+    })
+  })
+
+  describe("persistence across refresh", () => {
+    it("consented pair auto-restores; new hello carries the previously-committed permissions", () => {
+      loginAndVisitDeepLink()
+      cy.getByDataHook("permissions-trigger").click()
+      cy.getByDataHook("permission-level-write").click()
+      cy.getByDataHook("mcp-pair-consent-connect").click()
+      waitForPaired()
+
+      // cy.reload doesn't accept onBeforeLoad — re-visit so the fake WS reinstalls.
+      cy.visit(baseUrl, {
+        onBeforeLoad: (win) => installFakeWebSocket(win),
+      })
+
+      cy.window({ timeout: 10000 }).its("__mcpFakeWS").should("exist")
+      cy.window({ timeout: 10000 }).should((win) => {
+        expect(win.__mcpFakeWS.framesOfType("hello").length).to.be.greaterThan(
+          0,
+        )
+      })
+      cy.window().then((win) => {
+        const hello = win.__mcpFakeWS.framesOfType("hello")[0]
+        expect(hello.permissions).to.deep.equal({
+          grantSchemaAccess: true,
+          read: true,
+          write: true,
+        })
+        win.__mcpFakeWS.helloAck()
+      })
+      cy.getByDataHook("mcp-bridge-status-pill").should(
+        "contain",
+        "MCP connected",
+      )
+    })
+  })
+})
diff --git a/e2e/utils/aiAssistant.js b/e2e/utils/aiAssistant.js
index 8a6f208e7..c3bbecbe1 100644
--- a/e2e/utils/aiAssistant.js
+++ b/e2e/utils/aiAssistant.js
@@ -34,6 +34,34 @@ function getOpenAIConfiguredSettings(schemaAccess = true) {
   }
 }
 
+/**
+ * OpenAI settings with the AI permission scopes (grantSchemaAccess/read/write)
+ * set explicitly. These are the per-provider scopes `getAiPermissions` reads —
+ * NOT the MCP `mcp:permissions` key — so the permission gate decides off them
+ * directly. `grantSchemaAccess` defaults to true; pass false for the "none"
+ * level where even schema tools are denied.
+ */
+function getOpenAIPermissionedSettings({
+  read,
+  write,
+  grantSchemaAccess = true,
+}) {
+  return {
+    "ai.assistant.settings": JSON.stringify({
+      selectedModel: "gpt-5-mini",
+      providers: {
+        openai: {
+          apiKey: "test-openai-key",
+          enabledModels: ["gpt-5-mini", "gpt-5"],
+          grantSchemaAccess,
+          read,
+          write,
+        },
+      },
+    }),
+  }
+}
+
 function getAnthropicConfiguredSettings(schemaAccess = true) {
   return {
     "ai.assistant.settings": JSON.stringify({
@@ -945,6 +973,9 @@ function createToolCallFlow(config) {
           for (const expected of step.expectToolResult.includes || []) {
             expect(toolOutputContent).to.include(expected)
           }
+          for (const forbidden of step.expectToolResult.excludes || []) {
+            expect(toolOutputContent).to.not.include(forbidden)
+          }
         }
 
         // Send response
@@ -1136,6 +1167,7 @@ module.exports = {
   PROVIDERS,
   CUSTOM_PROVIDER_DEFAULTS,
   getOpenAIConfiguredSettings,
+  getOpenAIPermissionedSettings,
   getAnthropicConfiguredSettings,
   getCustomProviderConfiguredSettings,
   getCustomProviderEndpoint,
diff --git a/package.json b/package.json
index 15d6a5664..845ec20a1 100644
--- a/package.json
+++ b/package.json
@@ -72,7 +72,8 @@
     "dexie-react-hooks": "^4.2.0",
     "dotenv": "^10.0.0",
     "draggabilly": "^3.0.0",
-    "echarts": "^5.2.2",
+    "echarts": "^5.6.0",
+    "echarts-for-react": "^3.0.6",
     "eventemitter3": "^5.0.1",
     "fflate": "^0.8.2",
     "intersection-observer": "^0.12.2",
@@ -91,6 +92,7 @@
     "react": "17.0.2",
     "react-calendar": "^4.0.0",
     "react-dom": "17.0.2",
+    "react-grid-layout": "^2.2.3",
     "react-highlight-words": "^0.20.0",
     "react-hook-form": "^7.56.0",
     "react-is": "^18.1.0",
@@ -124,13 +126,13 @@
     "@styled-icons/styled-icon": "^10.7.0",
     "@types/babel__core": "^7",
     "@types/draggabilly": "^2.1.6",
-    "@types/echarts": "^4.9.22",
     "@types/jquery": "3.5.1",
     "@types/lodash.merge": "^4.6.9",
     "@types/node": "^18.0.0",
     "@types/ramda": "0.27.40",
     "@types/react": "17.0.2",
     "@types/react-dom": "17.0.2",
+    "@types/react-grid-layout": "^2.1.0",
     "@types/react-highlight-words": "^0.16.7",
     "@types/react-redux": "7.1.9",
     "@types/react-transition-group": "4.4.0",
@@ -186,7 +188,7 @@
       },
       {
         "path": "dist/assets/index-*.js",
-        "maxSize": "3MB",
+        "maxSize": "3.5MB",
         "compression": "none"
       },
       {
diff --git a/public/assets/icon-notebook.svg b/public/assets/icon-notebook.svg
new file mode 100644
index 000000000..61f8e88bc
--- /dev/null
+++ b/public/assets/icon-notebook.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" fill="#8be9fd" viewBox="0 0 256 256"><path d="M184,112a8,8,0,0,1-8,8H112a8,8,0,0,1,0-16h64A8,8,0,0,1,184,112Zm-8,24H112a8,8,0,0,0,0,16h64a8,8,0,0,0,0-16Zm48-88V208a16,16,0,0,1-16,16H48a16,16,0,0,1-16-16V48A16,16,0,0,1,48,32H208A16,16,0,0,1,224,48ZM48,208H72V48H48Zm160,0V48H88V208H208Z"></path></svg>
\ No newline at end of file
diff --git a/src/components/AIStatusIndicator/AssistantModes.tsx b/src/components/AIStatusIndicator/AssistantModes.tsx
index f2b2bf51c..35a592041 100644
--- a/src/components/AIStatusIndicator/AssistantModes.tsx
+++ b/src/components/AIStatusIndicator/AssistantModes.tsx
@@ -82,6 +82,7 @@ export const getIsExpandableSection = (section: OperationSection) => {
     AIOperationStatus.InvestigatingTable,
     AIOperationStatus.InvestigatingDocs,
     AIOperationStatus.Thinking,
+    AIOperationStatus.RunningQuery,
   ].includes(section.type)
 }
 
diff --git a/src/components/AIStatusIndicator/AssistantModesCompact.tsx b/src/components/AIStatusIndicator/AssistantModesCompact.tsx
index 9344e885b..345e8480a 100644
--- a/src/components/AIStatusIndicator/AssistantModesCompact.tsx
+++ b/src/components/AIStatusIndicator/AssistantModesCompact.tsx
@@ -361,10 +361,12 @@ export const AssistantModesCompact: React.FC<AssistantModesCompactProps> = ({
       nextSection,
       !nextSection ? endTimestamp : undefined,
     )
-    const thinkingSegmentText =
-      section.type === AIOperationStatus.Thinking
-        ? (section.operations[0]?.content ?? "")
-        : ""
+    const isContentSection =
+      section.type === AIOperationStatus.Thinking ||
+      section.type === AIOperationStatus.RunningQuery
+    const sectionContentText = isContentSection
+      ? (section.operations[0]?.content ?? "")
+      : ""
 
     return (
       <ModeHeader
@@ -414,16 +416,16 @@ export const AssistantModesCompact: React.FC<AssistantModesCompactProps> = ({
             )}
           </Box>
         </ModeHeaderTop>
-        {isExpandable && section.type === AIOperationStatus.Thinking && (
+        {isExpandable && isContentSection && (
           <ExpandableWrapper $expanded={isExpanded}>
             <ExpandableContent>
-              {thinkingSegmentText ? (
-                <ThinkingContent>{thinkingSegmentText}</ThinkingContent>
+              {sectionContentText ? (
+                <ThinkingContent>{sectionContentText}</ThinkingContent>
               ) : null}
             </ExpandableContent>
           </ExpandableWrapper>
         )}
-        {isExpandable && section.type !== AIOperationStatus.Thinking && (
+        {isExpandable && !isContentSection && (
           <ExpandableWrapper $expanded={isExpanded}>
             <ExpandableContent>
               <ReasoningThread>
diff --git a/src/components/Button/skin.ts b/src/components/Button/skin.ts
index 600e6ecda..1b4580f54 100644
--- a/src/components/Button/skin.ts
+++ b/src/components/Button/skin.ts
@@ -13,6 +13,7 @@ export const skins = [
   "secondary",
   "success",
   "error",
+  "danger",
   "warning",
   "transparent",
   "gradient",
@@ -114,6 +115,23 @@ const themes: {
       color: "gray1",
     },
   },
+  danger: {
+    normal: {
+      background: "dangerBackground",
+      border: "transparent",
+      color: "dangerForeground",
+    },
+    hover: {
+      background: "dangerBackgroundHover",
+      border: "transparent",
+      color: "dangerForeground",
+    },
+    disabled: {
+      background: "selection",
+      border: "gray1",
+      color: "gray1",
+    },
+  },
   warning: {
     normal: {
       background: "selection",
diff --git a/src/components/ContextMenu/index.tsx b/src/components/ContextMenu/index.tsx
index 8253d8f29..cf1c204b8 100644
--- a/src/components/ContextMenu/index.tsx
+++ b/src/components/ContextMenu/index.tsx
@@ -3,29 +3,28 @@ import styled from "styled-components"
 import * as ContextMenuPrimitive from "@radix-ui/react-context-menu"
 
 const StyledContent = styled(ContextMenuPrimitive.Content)`
-  background-color: #343846; /* vscode-menu-background */
+  background-color: ${({ theme }) => theme.color.backgroundDarker};
   border-radius: 0.5rem;
   padding: 0.4rem;
-  box-shadow: 0 0.2rem 0.8rem rgba(0, 0, 0, 0.36); /* vscode-widget-shadow */
+  box-shadow: 0 0.2rem 0.8rem rgba(0, 0, 0, 0.36);
   z-index: 9999;
-  min-width: 160px;
+  min-width: 16rem;
 `
 
 const StyledItem = styled(ContextMenuPrimitive.Item)`
-  font-size: 1.3rem;
-  height: 3rem;
+  font-size: 1.4rem;
   font-family: "system-ui", sans-serif;
   cursor: pointer;
-  color: rgb(248, 248, 242); /* vscode-menu-foreground */
+  color: ${({ theme }) => theme.color.foreground};
   display: flex;
+  gap: 1rem;
+  min-height: 3rem;
   align-items: center;
-  padding: 1rem 1.2rem;
+  padding: 0.5rem 1rem;
   border-radius: 0.4rem;
-  border: 1px solid transparent;
 
   &[data-highlighted] {
-    background: #043c5c;
-    border: 1px solid #8be9fd;
+    background: ${({ theme }) => theme.color.tableSelection};
   }
 
   &[data-disabled] {
@@ -35,7 +34,6 @@ const StyledItem = styled(ContextMenuPrimitive.Item)`
 `
 
 const IconWrapper = styled.span`
-  margin-right: 1.2rem;
   display: flex;
   align-items: center;
   justify-content: center;
diff --git a/src/components/CopyButton/index.tsx b/src/components/CopyButton/index.tsx
index 1ad8ff249..9b6381fc5 100644
--- a/src/components/CopyButton/index.tsx
+++ b/src/components/CopyButton/index.tsx
@@ -12,7 +12,9 @@ const StyledButton = styled(Button)`
 
 const StyledCheckboxCircle = styled(CheckboxCircle)`
   position: absolute;
-  transform: translate(75%, -75%);
+  top: 0;
+  right: 0;
+  transform: translate(50%, -50%);
   color: ${({ theme }) => theme.color.green};
 `
 
@@ -44,6 +46,7 @@ export const CopyButton = ({
       skin="secondary"
       size={size}
       data-hook="copy-value"
+      data-copied={copied || undefined}
       title="Copy to clipboard"
       onClick={(e: React.MouseEvent<HTMLButtonElement>) => {
         void copyToClipboard(text)
@@ -57,9 +60,7 @@ export const CopyButton = ({
       })}
       {...props}
     >
-      {copied && (
-        <StyledCheckboxCircle size={size === "sm" ? "10px" : "14px"} />
-      )}
+      {copied && <StyledCheckboxCircle size={size === "sm" ? "8px" : "14px"} />}
       {iconOnly ? <FileCopy size={size === "sm" ? "12px" : "16px"} /> : "Copy"}
     </StyledButton>
   )
diff --git a/src/components/DropdownMenu/index.tsx b/src/components/DropdownMenu/index.tsx
index 63022fa63..9f7e887c5 100644
--- a/src/components/DropdownMenu/index.tsx
+++ b/src/components/DropdownMenu/index.tsx
@@ -11,13 +11,13 @@ export const DropdownMenu = {
   Portal: styled(RadixDropdownMenu.Portal)``,
 
   Content: styled(RadixDropdownMenu.Content)`
-    display: grid;
-    gap: 0.2rem;
-    min-width: 22rem;
-    background: ${({ theme }) => theme.color.backgroundLighter};
-    border-radius: ${({ theme }) => theme.borderRadius};
-    box-shadow: 0 5px 5px 0 ${({ theme }) => theme.color.black40};
-    padding: 0.5rem 0;
+    background-color: ${({ theme }) => theme.color.backgroundDarker};
+    border-radius: 0.5rem;
+    border: 1px solid ${({ theme }) => theme.color.baseGrey};
+    padding: 0.4rem;
+    box-shadow: 0 0.2rem 0.8rem rgba(0, 0, 0, 0.36);
+    z-index: 9999;
+    min-width: 16rem;
   `,
 
   Arrow: styled(RadixDropdownMenu.Arrow)`
@@ -25,29 +25,31 @@ export const DropdownMenu = {
   `,
 
   Item: styled(RadixDropdownMenu.Item)`
-    border-radius: 3px;
+    font-size: 1.4rem;
+    cursor: pointer;
+    color: ${({ theme }) => theme.color.foreground};
     display: flex;
-    gap: 1.5rem;
+    gap: 1rem;
+    min-height: 3rem;
     align-items: center;
     padding: 0.5rem 1rem;
-    margin: 0 0.5rem;
+    border-radius: 0.4rem;
     user-select: none;
     outline: none;
 
-    &[data-disabled] {
-      pointer-events: none;
-      opacity: 0.8;
+    &[data-highlighted] {
+      background: ${({ theme }) => theme.color.tableSelection};
     }
 
-    &:focus {
-      background: ${({ theme }) => theme.color.comment};
-      cursor: pointer;
+    &[data-disabled] {
+      opacity: 0.5;
+      pointer-events: none;
     }
   `,
 
   Divider: styled.div`
     height: 1px;
     background: ${({ theme }) => theme.color.selection};
-    margin: 0.5rem 0;
+    margin: 0.3rem 0;
   `,
 }
diff --git a/src/components/ExplainQueryButton/index.tsx b/src/components/ExplainQueryButton/index.tsx
index 8c07d9a10..580829c7c 100644
--- a/src/components/ExplainQueryButton/index.tsx
+++ b/src/components/ExplainQueryButton/index.tsx
@@ -7,7 +7,7 @@ import { AISparkle } from "../AISparkle"
 import { QuestContext } from "../../providers"
 import { selectors } from "../../store"
 import { useAIStatus } from "../../providers/AIStatusProvider"
-import { useAIConversation } from "../../providers/AIConversationProvider"
+import { useAIConversationActions } from "../../providers/AIConversationProvider"
 import type { ConversationId } from "../../providers/AIConversationProvider/types"
 import {
   executeAIFlow,
@@ -54,7 +54,7 @@ export const ExplainQueryButton = ({
     updateConversationName,
     persistMessages,
     setIsStreaming,
-  } = useAIConversation()
+  } = useAIConversationActions()
 
   const handleExplainQuery = () => {
     void trackEvent(ConsoleEvent.AI_EXPLAIN_QUERY)
diff --git a/src/components/HighlightedSql/index.tsx b/src/components/HighlightedSql/index.tsx
new file mode 100644
index 000000000..5b08a925b
--- /dev/null
+++ b/src/components/HighlightedSql/index.tsx
@@ -0,0 +1,42 @@
+import React, { useEffect, useState } from "react"
+import styled from "styled-components"
+import { monacoPromise } from "../../utils/monacoInit"
+import { QuestDBLanguageName } from "../../scenes/Editor/Monaco/utils"
+
+type Props = {
+  code: string
+  language?: string
+  className?: string
+}
+
+const Pre = styled.pre`
+  white-space: pre-wrap;
+  overflow-wrap: normal;
+  word-break: normal;
+`
+
+export const HighlightedSql: React.FC<Props> = ({
+  code,
+  language = QuestDBLanguageName,
+  className,
+}) => {
+  const [html, setHtml] = useState<string | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    void monacoPromise
+      .then((monaco) => monaco.editor.colorize(code, language, {}))
+      .then((colorized) => {
+        if (!cancelled) setHtml(colorized)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [code, language])
+
+  return html === null ? (
+    <Pre className={className}>{code}</Pre>
+  ) : (
+    <Pre className={className} dangerouslySetInnerHTML={{ __html: html }} />
+  )
+}
diff --git a/src/components/Input/index.tsx b/src/components/Input/index.tsx
index 9f17b5e32..c1d14b0b9 100644
--- a/src/components/Input/index.tsx
+++ b/src/components/Input/index.tsx
@@ -10,6 +10,10 @@ type InputProps = React.InputHTMLAttributes<HTMLInputElement> & {
 const errorStyle = css`
   border-color: ${({ theme }) => theme.color.red};
   background-color: #ff555515;
+  &:focus {
+    border-color: ${({ theme }) => theme.color.red};
+    background: #ff555515;
+  }
 `
 
 export const Input = styled.input.attrs((props) => ({
diff --git a/src/components/Markdown/SafeMarkdown.test.tsx b/src/components/Markdown/SafeMarkdown.test.tsx
new file mode 100644
index 000000000..d06353458
--- /dev/null
+++ b/src/components/Markdown/SafeMarkdown.test.tsx
@@ -0,0 +1,59 @@
+import React from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { SafeMarkdown } from "./SafeMarkdown"
+
+const render = (markdown: string, allowImages = false) =>
+  renderToStaticMarkup(
+    <SafeMarkdown allowImages={allowImages}>{markdown}</SafeMarkdown>,
+  )
+
+describe("SafeMarkdown", () => {
+  it("never renders images by default", () => {
+    const html = render("![pixel](http://evil.example/track.png)")
+    expect(html).not.toContain("<img")
+    expect(html).not.toContain("track.png")
+  })
+
+  it("renders images when allowImages and src is http(s)/data:image", () => {
+    expect(render("![ok](https://example.com/a.png)", true)).toContain("<img")
+    expect(render("![ok](data:image/png;base64,iVBORw0KGgo=)", true)).toContain(
+      "<img",
+    )
+  })
+
+  it("drops images with unsafe src even when images are allowed", () => {
+    expect(render("![x](javascript:alert(1))", true)).not.toContain("<img")
+    expect(render("![x](vbscript:msgbox(1))", true)).not.toContain("<img")
+  })
+
+  it("escapes raw HTML — no live script or event-handler element", () => {
+    const html = render("<script>alert(1)</script>")
+    // Raw HTML is escaped to inert text, never a live element.
+    expect(html).not.toContain("<script")
+    const imgHtml = render('<img src=x onerror="alert(1)">', true)
+    // The raw <img> is escaped (rendered as text), not emitted as an element.
+    expect(imgHtml).toContain("&lt;img")
+    expect(imgHtml).not.toMatch(/<img[^>]*onerror/i)
+  })
+
+  it("opens http(s) links in a new tab with noopener noreferrer", () => {
+    const html = render("[site](https://example.com)")
+    expect(html).toContain('target="_blank"')
+    expect(html).toContain('rel="noopener noreferrer"')
+  })
+
+  it("does not add target/rel to relative or anchor links", () => {
+    const html = render("[here](#section)")
+    expect(html).not.toContain('target="_blank"')
+  })
+
+  it("neutralizes javascript: link hrefs (react-markdown default)", () => {
+    const html = render("[x](javascript:alert(1))")
+    expect(html).not.toContain("javascript:alert")
+  })
+
+  it("renders GFM tables by default", () => {
+    const html = render("| a | b |\n| - | - |\n| 1 | 2 |")
+    expect(html).toContain("<table")
+  })
+})
diff --git a/src/components/Markdown/SafeMarkdown.tsx b/src/components/Markdown/SafeMarkdown.tsx
new file mode 100644
index 000000000..4df3c5c17
--- /dev/null
+++ b/src/components/Markdown/SafeMarkdown.tsx
@@ -0,0 +1,71 @@
+import React from "react"
+import ReactMarkdown, { type Components, type Options } from "react-markdown"
+import remarkGfm from "remark-gfm"
+
+// The security boundary for every markdown surface in the app (notebook
+// markdown cells, AI chat, News). It renders only the configured
+// <ReactMarkdown> — no wrapper element — so each call site keeps its own
+// styled container.
+//
+// Guarantees:
+//   - No raw HTML: react-markdown@8 escapes raw HTML by default and we never
+//     add rehype-raw, so embedded <script>/<img onerror> stay inert text.
+//   - Safe links: http(s) links open in a new tab with rel="noopener
+//     noreferrer"; other protocols are passed through react-markdown's default
+//     uriTransformer (which neutralizes javascript: etc.).
+//   - Images off by default: dropped entirely unless allowImages is set, in
+//     which case only http(s)/data:image sources render.
+
+const isHttpUrl = (value?: string): value is string =>
+  typeof value === "string" && /^https?:\/\//i.test(value)
+
+const isSafeImageSrc = (value?: string): value is string =>
+  typeof value === "string" &&
+  (/^https?:\/\//i.test(value) || /^data:image\//i.test(value))
+
+const SafeLink = ({ children, href, ...props }: React.ComponentProps<"a">) => (
+  <a
+    href={href}
+    {...(isHttpUrl(href)
+      ? { target: "_blank", rel: "noopener noreferrer" }
+      : {})}
+    {...props}
+  >
+    {children}
+  </a>
+)
+
+const SafeImage = ({ src, alt, ...props }: React.ComponentProps<"img">) =>
+  isSafeImageSrc(src) ? <img src={src} alt={alt ?? ""} {...props} /> : null
+
+const DropImage = () => null
+
+type SafeMarkdownProps = {
+  children: string
+  allowImages?: boolean
+  remarkPlugins?: Options["remarkPlugins"]
+  components?: Components
+}
+
+export const SafeMarkdown = ({
+  children,
+  allowImages = false,
+  remarkPlugins = [remarkGfm],
+  components,
+}: SafeMarkdownProps) => {
+  const merged: Components = {
+    a: SafeLink,
+    ...(allowImages ? { img: SafeImage } : {}),
+    // Caller overrides (e.g. chat's LiteEditor code block) layer on top...
+    ...components,
+    // ...but image policy is enforced LAST so a caller can never re-enable
+    // images when allowImages is false.
+    ...(allowImages ? {} : { img: DropImage }),
+  }
+
+  return (
+    <ReactMarkdown remarkPlugins={remarkPlugins} components={merged}>
+      {children}
+    </ReactMarkdown>
+  )
+}
diff --git a/src/components/Markdown/index.ts b/src/components/Markdown/index.ts
new file mode 100644
index 000000000..17fd7112b
--- /dev/null
+++ b/src/components/Markdown/index.ts
@@ -0,0 +1 @@
+export * from "./SafeMarkdown"
diff --git a/src/components/MultiSelect/index.tsx b/src/components/MultiSelect/index.tsx
new file mode 100644
index 000000000..d363b21be
--- /dev/null
+++ b/src/components/MultiSelect/index.tsx
@@ -0,0 +1,204 @@
+import React from "react"
+import styled from "styled-components"
+import * as RadixDropdownMenu from "@radix-ui/react-dropdown-menu"
+import { ArrowDropDown } from "@styled-icons/remix-line"
+import { Check } from "@phosphor-icons/react"
+
+export type MultiSelectOption = {
+  label: string
+  value: string
+}
+
+type Props = {
+  options: MultiSelectOption[]
+  value: string[]
+  onChange: (next: string[]) => void
+  name?: string
+  placeholder?: string
+  disabled?: boolean
+  className?: string
+  // Above this count, trigger shows "X of Y" instead of comma-joined labels.
+  inlineThreshold?: number
+}
+
+const Trigger = styled(RadixDropdownMenu.Trigger)`
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.4rem;
+  background: ${({ theme }) => theme.color.selection};
+  border: 1px transparent solid;
+  padding: 0 0 0 0.75rem;
+  height: 3rem;
+  border-radius: 0.4rem;
+  color: ${({ theme }) => theme.color.foreground};
+  cursor: pointer;
+  width: 100%;
+  font-family: inherit;
+  font-size: ${({ theme }) => theme.fontSize.md};
+
+  &:focus,
+  &[data-state="open"] {
+    border-color: ${({ theme }) => theme.color.pink};
+    outline: none;
+  }
+
+  &:disabled {
+    cursor: default;
+    color: ${({ theme }) => theme.color.gray1};
+    border-color: ${({ theme }) => theme.color.gray1};
+  }
+`
+
+const TriggerLabel = styled.span`
+  flex: 1;
+  text-align: left;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+`
+
+const Caret = styled(ArrowDropDown)`
+  flex-shrink: 0;
+  fill: ${({ theme }) => theme.color.white};
+`
+
+const Content = styled(RadixDropdownMenu.Content)`
+  background: ${({ theme }) => theme.color.backgroundDarker};
+  border: 1px solid ${({ theme }) => theme.color.selection};
+  border-radius: 0.4rem;
+  padding: 0.4rem;
+  z-index: 9999;
+  min-width: var(--radix-dropdown-menu-trigger-width);
+  max-height: 30rem;
+  overflow-y: auto;
+  box-shadow: 0 0.2rem 0.8rem rgba(0, 0, 0, 0.36);
+`
+
+const Item = styled(RadixDropdownMenu.CheckboxItem)`
+  font-size: ${({ theme }) => theme.fontSize.md};
+  color: ${({ theme }) => theme.color.foreground};
+  display: flex;
+  align-items: center;
+  gap: 0.8rem;
+  min-height: 2.8rem;
+  padding: 0.4rem 0.8rem;
+  border-radius: 0.3rem;
+  user-select: none;
+  outline: none;
+  cursor: pointer;
+
+  &[data-highlighted] {
+    background: ${({ theme }) => theme.color.tableSelection};
+  }
+
+  &[data-disabled] {
+    opacity: 0.5;
+    pointer-events: none;
+  }
+`
+
+const CheckBox = styled.span<{ $checked: boolean }>`
+  width: 1.4rem;
+  height: 1.4rem;
+  border-radius: 0.2rem;
+  border: 1px solid
+    ${({ theme, $checked }) =>
+      $checked ? theme.color.pinkPrimary : theme.color.gray1};
+  background: ${({ theme, $checked }) =>
+    $checked ? theme.color.pinkPrimary : "transparent"};
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  color: ${({ theme }) => theme.color.foreground};
+`
+
+const Empty = styled.div`
+  font-size: ${({ theme }) => theme.fontSize.sm};
+  color: ${({ theme }) => theme.color.gray2};
+  padding: 0.6rem 0.8rem;
+`
+
+const summarize = (
+  value: string[],
+  options: MultiSelectOption[],
+  placeholder: string,
+  inlineThreshold: number,
+): string => {
+  if (value.length === 0) return placeholder
+  if (value.length === options.length && options.length > 0)
+    return `All (${options.length})`
+  if (value.length <= inlineThreshold) {
+    return value
+      .map((v) => options.find((o) => o.value === v)?.label ?? v)
+      .join(", ")
+  }
+  return `${value.length} of ${options.length}`
+}
+
+export const MultiSelect: React.FC<Props> = ({
+  options,
+  value,
+  onChange,
+  name,
+  placeholder = "None selected",
+  disabled,
+  className,
+  inlineThreshold = 2,
+}) => {
+  const summary = summarize(value, options, placeholder, inlineThreshold)
+  const selected = new Set(value)
+
+  const toggle = (v: string) => {
+    // Preserve option order so persisted selections stay stable across toggles.
+    if (selected.has(v)) {
+      onChange(value.filter((x) => x !== v))
+    } else {
+      onChange(
+        options
+          .filter((o) => selected.has(o.value) || o.value === v)
+          .map((o) => o.value),
+      )
+    }
+  }
+
+  return (
+    <RadixDropdownMenu.Root>
+      <Trigger
+        className={className}
+        data-name={name}
+        disabled={disabled}
+        title={summary}
+        aria-label={[name, summary].filter(Boolean).join(": ")}
+      >
+        <TriggerLabel>{summary}</TriggerLabel>
+        <Caret size="24" />
+      </Trigger>
+      <RadixDropdownMenu.Portal>
+        <Content sideOffset={4} align="start">
+          {options.length === 0 ? (
+            <Empty>No options</Empty>
+          ) : (
+            options.map((opt) => {
+              const checked = selected.has(opt.value)
+              return (
+                <Item
+                  key={opt.value}
+                  checked={checked}
+                  onCheckedChange={() => toggle(opt.value)}
+                  onSelect={(e) => e.preventDefault()}
+                >
+                  <CheckBox $checked={checked}>
+                    {checked && <Check size={10} weight="bold" />}
+                  </CheckBox>
+                  {opt.label}
+                </Item>
+              )
+            })
+          )}
+        </Content>
+      </RadixDropdownMenu.Portal>
+    </RadixDropdownMenu.Root>
+  )
+}
diff --git a/src/components/PopperToggle/index.tsx b/src/components/PopperToggle/index.tsx
index 1b3e88281..5dcb7cf57 100644
--- a/src/components/PopperToggle/index.tsx
+++ b/src/components/PopperToggle/index.tsx
@@ -86,6 +86,10 @@ export const PopperToggle = ({
         return
       }
 
+      if (target?.closest?.("[data-radix-popper-content-wrapper]")) {
+        return
+      }
+
       if (_active) {
         setActive(false)
         if (onToggle) {
diff --git a/src/components/ResultGrid/index.ts b/src/components/ResultGrid/index.ts
index 9474862df..6bcd4e4c0 100644
--- a/src/components/ResultGrid/index.ts
+++ b/src/components/ResultGrid/index.ts
@@ -2,6 +2,7 @@ export { ResultGrid } from "./ResultGrid"
 export type { ResultGridHandle } from "./ResultGrid"
 
 export type {
+  ColumnLayout,
   DqlQueryResult,
   ResultGridDataSource,
   ResultGridRow,
diff --git a/src/components/ResultGrid/styles.ts b/src/components/ResultGrid/styles.ts
index f19a3852e..5bb5dd79d 100644
--- a/src/components/ResultGrid/styles.ts
+++ b/src/components/ResultGrid/styles.ts
@@ -14,6 +14,7 @@ export const GridContainer = styled.div`
   outline: none;
   font-size: ${({ theme }) => theme.fontSize.xs};
   position: relative;
+  isolation: isolate;
 `
 
 export const ScrollContainer = styled.div<{ $scrollable: boolean }>`
diff --git a/src/components/ResultGrid/types.ts b/src/components/ResultGrid/types.ts
index 0d3a5aa6f..c691ad34c 100644
--- a/src/components/ResultGrid/types.ts
+++ b/src/components/ResultGrid/types.ts
@@ -8,6 +8,12 @@ export type CellValue = boolean | string | number | null
 
 export type ResultGridRow = CellValue[]
 
+export type ColumnLayout = {
+  columnSizing?: Record<string, number>
+  columnOrder?: string[]
+  pinnedColumns?: string[]
+}
+
 // Neutral DQL-result shape the grid reads from, free of feature-specific
 // coupling so it stays reusable.
 export type DqlQueryResult = {
diff --git a/src/components/SetupAIAssistant/ConfigurationModal.tsx b/src/components/SetupAIAssistant/ConfigurationModal.tsx
index 31c743fc3..d533f39a9 100644
--- a/src/components/SetupAIAssistant/ConfigurationModal.tsx
+++ b/src/components/SetupAIAssistant/ConfigurationModal.tsx
@@ -5,7 +5,6 @@ import { MultiStepModal, Step } from "../MultiStepModal"
 import { Box } from "../Box"
 import { Input } from "../Input"
 import { Switch } from "../Switch"
-import { Checkbox } from "../Checkbox"
 import { Text } from "../Text"
 import { useLocalStorage } from "../../providers/LocalStorageProvider"
 import { testApiKey } from "../../utils/aiAssistant"
@@ -20,6 +19,8 @@ import {
   type ProviderId,
   getProviderName,
 } from "../../utils/ai"
+import { PermissionsSection } from "../../scenes/Footer/MCPBridgeStatus/PermissionsSection"
+import type { Permissions } from "../../utils/tools/permissions"
 import { useModalNavigation } from "../MultiStepModal"
 import { OpenAIIcon } from "./OpenAIIcon"
 import { AnthropicIcon } from "./AnthropicIcon"
@@ -217,11 +218,6 @@ const ModelList = styled(Box).attrs({ flexDirection: "column", gap: "1.2rem" })`
   width: 100%;
 `
 
-const StyledCheckbox = styled(Checkbox)`
-  font-size: 1.4rem;
-  display: inline;
-`
-
 const FormGroup = styled(Box).attrs({
   flexDirection: "column",
   gap: "1.6rem",
@@ -303,77 +299,6 @@ const ModelNameText = styled(Text)`
   color: ${({ theme }) => theme.color.foreground};
 `
 
-const SchemaAccessSection = styled(Box).attrs({
-  flexDirection: "column",
-  gap: "1.6rem",
-})`
-  width: 100%;
-`
-
-const SchemaAccessHeader = styled(Box).attrs({
-  justifyContent: "space-between",
-  align: "center",
-  gap: "1rem",
-})`
-  width: 100%;
-`
-
-const SchemaAccessTitle = styled(Text)`
-  font-size: 1.6rem;
-  font-weight: 600;
-  color: ${({ theme }) => theme.color.gray2};
-  flex: 1;
-`
-
-const SchemaCheckboxContainer = styled(Box).attrs({
-  gap: "1.5rem",
-  align: "flex-start",
-})`
-  background: rgba(68, 71, 90, 0.56);
-  padding: 0.75rem;
-  border-radius: 0.4rem;
-  width: 100%;
-`
-
-const SchemaCheckboxInner = styled(Box).attrs({
-  gap: "1.5rem",
-  align: "center",
-})`
-  flex: 1;
-  padding: 0.75rem;
-  border-radius: 0.5rem;
-`
-
-const SchemaCheckboxWrapper = styled.div`
-  flex-shrink: 0;
-  display: flex;
-  align-items: center;
-`
-
-const SchemaCheckboxContent = styled(Box).attrs({
-  flexDirection: "column",
-  gap: "0.6rem",
-})`
-  flex: 1;
-`
-
-const SchemaCheckboxLabel = styled(Text)`
-  font-size: 1.4rem;
-  font-weight: 500;
-  color: ${({ theme }) => theme.color.foreground};
-`
-
-const SchemaCheckboxDescription = styled(Text)`
-  font-size: 1.3rem;
-  font-weight: 400;
-  color: ${({ theme }) => theme.color.gray2};
-`
-
-const SchemaCheckboxDescriptionBold = styled.span`
-  font-weight: 500;
-  color: ${({ theme }) => theme.color.foreground};
-`
-
 const WarningText = styled(Text)`
   font-size: 1.3rem;
   font-weight: 400;
@@ -427,10 +352,17 @@ type StepOneContentProps = {
 type StepTwoContentProps = {
   selectedProvider: ProviderId | null
   enabledModels: string[]
-  grantSchemaAccess: boolean
+  permissions: Permissions
   modelsByProvider: Record<string, ModelOption[]>
   onModelToggle: (modelValue: string) => void
-  onSchemaAccessChange: (checked: boolean) => void
+  onPermissionsChange: (next: Permissions) => void
+}
+
+// New scopes default to denied; schema access stays on for back-compat.
+const DEFAULT_PERMISSIONS: Permissions = {
+  grantSchemaAccess: true,
+  read: false,
+  write: false,
 }
 
 const CloseButton = ({ onClick }: { onClick: () => void }) => {
@@ -565,10 +497,10 @@ const StepOneContent = ({
 const StepTwoContent = ({
   selectedProvider,
   enabledModels,
-  grantSchemaAccess,
+  permissions,
   modelsByProvider,
   onModelToggle,
-  onSchemaAccessChange,
+  onPermissionsChange,
 }: StepTwoContentProps) => {
   const navigation = useModalNavigation()
   const handleClose: () => void = navigation.handleClose
@@ -656,37 +588,11 @@ const StepTwoContent = ({
       <Separator />
       <ContentSection>
         {currentProvider && (
-          <SchemaAccessSection>
-            <SchemaAccessHeader>
-              <SchemaAccessTitle>Schema Access</SchemaAccessTitle>
-            </SchemaAccessHeader>
-            <SchemaCheckboxContainer>
-              <SchemaCheckboxInner>
-                <SchemaCheckboxWrapper>
-                  <StyledCheckbox
-                    id={`schema-access-${currentProvider}`}
-                    checked={grantSchemaAccess}
-                    onChange={(e) => onSchemaAccessChange(e.target.checked)}
-                    data-hook="ai-settings-schema-access"
-                  />
-                </SchemaCheckboxWrapper>
-                <SchemaCheckboxContent align="flex-start">
-                  <SchemaCheckboxLabel>
-                    Grant schema access to {getProviderName(currentProvider)}
-                  </SchemaCheckboxLabel>
-                  <SchemaCheckboxDescription>
-                    When enabled, the AI assistant can access your database
-                    schema information to provide more accurate suggestions and
-                    explanations. Schema information helps the AI understand
-                    your table structures, column names, and relationships.{" "}
-                    <SchemaCheckboxDescriptionBold>
-                      The AI model will not have access to your database store.
-                    </SchemaCheckboxDescriptionBold>
-                  </SchemaCheckboxDescription>
-                </SchemaCheckboxContent>
-              </SchemaCheckboxInner>
-            </SchemaCheckboxContainer>
-          </SchemaAccessSection>
+          <PermissionsSection
+            value={permissions}
+            onChange={onPermissionsChange}
+            variant="rich"
+          />
         )}
       </ContentSection>
       <WarningText>
@@ -721,7 +627,8 @@ export const ConfigurationModal = ({
   }, [open])
 
   const [enabledModels, setEnabledModels] = useState<string[]>([])
-  const [grantSchemaAccess, setGrantSchemaAccess] = useState<boolean>(true)
+  const [permissions, setPermissions] =
+    useState<Permissions>(DEFAULT_PERMISSIONS)
 
   const modelsByProvider = useMemo(() => {
     const result: Record<string, ModelOption[]> = {}
@@ -754,8 +661,8 @@ export const ConfigurationModal = ({
     })
   }, [])
 
-  const handleSchemaAccessChange = useCallback((checked: boolean) => {
-    setGrantSchemaAccess(checked)
+  const handlePermissionsChange = useCallback((next: Permissions) => {
+    setPermissions(next)
   }, [])
 
   const handleComplete = () => {
@@ -763,7 +670,9 @@ export const ConfigurationModal = ({
 
     void trackEvent(ConsoleEvent.AI_PROVIDER_CONFIGURE, {
       name: selectedProvider,
-      grantSchemaAccess,
+      grantSchemaAccess: permissions.grantSchemaAccess,
+      read: permissions.read,
+      write: permissions.write,
     })
 
     const selectedModel =
@@ -781,7 +690,9 @@ export const ConfigurationModal = ({
         [selectedProvider]: {
           apiKey,
           enabledModels,
-          grantSchemaAccess,
+          grantSchemaAccess: permissions.grantSchemaAccess,
+          read: permissions.read,
+          write: permissions.write,
         },
       },
     }
@@ -855,7 +766,7 @@ export const ConfigurationModal = ({
       // When going back from step 2 to step 1, reset step 2 state but keep API key
       if (newStepIndex === 0 && direction === "previous") {
         setEnabledModels([])
-        setGrantSchemaAccess(true)
+        setPermissions(DEFAULT_PERMISSIONS)
       }
     },
     [],
@@ -866,7 +777,7 @@ export const ConfigurationModal = ({
     setApiKey("")
     setError(null)
     setEnabledModels([])
-    setGrantSchemaAccess(true)
+    setPermissions(DEFAULT_PERMISSIONS)
   }, [])
 
   const handleCustomProviderSave = useCallback(
@@ -888,6 +799,8 @@ export const ConfigurationModal = ({
             apiKey: definition.apiKey ?? "",
             enabledModels: newEnabledModels,
             grantSchemaAccess: definition.grantSchemaAccess ?? false,
+            read: definition.read ?? false,
+            write: definition.write ?? false,
           },
         },
       }
@@ -895,6 +808,8 @@ export const ConfigurationModal = ({
       void trackEvent(ConsoleEvent.AI_PROVIDER_CONFIGURE, {
         name: "custom",
         grantSchemaAccess: definition.grantSchemaAccess ?? false,
+        read: definition.read ?? false,
+        write: definition.write ?? false,
         type: definition.type,
         contextWindow: definition.contextWindow,
       })
@@ -934,10 +849,10 @@ export const ConfigurationModal = ({
           <StepTwoContent
             selectedProvider={selectedProvider}
             enabledModels={enabledModels}
-            grantSchemaAccess={grantSchemaAccess}
+            permissions={permissions}
             modelsByProvider={modelsByProvider}
             onModelToggle={handleModelToggle}
-            onSchemaAccessChange={handleSchemaAccessChange}
+            onPermissionsChange={handlePermissionsChange}
           />
         ),
         validate: validateStepTwo,
@@ -951,10 +866,10 @@ export const ConfigurationModal = ({
       handleProviderSelect,
       handleApiKeyChange,
       enabledModels,
-      grantSchemaAccess,
+      permissions,
       modelsByProvider,
       handleModelToggle,
-      handleSchemaAccessChange,
+      handlePermissionsChange,
       validateStepOne,
       validateStepTwo,
     ],
diff --git a/src/components/SetupAIAssistant/CustomProviderModal.tsx b/src/components/SetupAIAssistant/CustomProviderModal.tsx
index 6d4b686f3..ae655ca38 100644
--- a/src/components/SetupAIAssistant/CustomProviderModal.tsx
+++ b/src/components/SetupAIAssistant/CustomProviderModal.tsx
@@ -326,7 +326,9 @@ export const CustomProviderModal = ({
       apiKey: apiKey || undefined,
       contextWindow: values.contextWindow,
       models: values.models,
-      grantSchemaAccess: values.grantSchemaAccess,
+      grantSchemaAccess: values.permissions.grantSchemaAccess,
+      read: values.permissions.read,
+      write: values.permissions.write,
     }
 
     onSave(providerId, definition)
@@ -373,7 +375,6 @@ export const CustomProviderModal = ({
                 baseURL,
               }}
               renderSchemaAccess
-              providerName={name || "this provider"}
             />
           </ModalContent>
         ),
diff --git a/src/components/SetupAIAssistant/ManageModelsModal.tsx b/src/components/SetupAIAssistant/ManageModelsModal.tsx
index ba418c213..bae1cb7f8 100644
--- a/src/components/SetupAIAssistant/ManageModelsModal.tsx
+++ b/src/components/SetupAIAssistant/ManageModelsModal.tsx
@@ -138,9 +138,12 @@ export const ManageModelsModal = ({
                   initialValues={{
                     models: definition.models,
                     contextWindow: definition.contextWindow,
-                    grantSchemaAccess: definition.grantSchemaAccess,
+                    permissions: {
+                      grantSchemaAccess: definition.grantSchemaAccess,
+                      read: definition.read,
+                      write: definition.write,
+                    },
                   }}
-                  providerName={definition.name}
                   onLoadingChange={setModelsLoading}
                 />
               )}
diff --git a/src/components/SetupAIAssistant/ModelSettings.tsx b/src/components/SetupAIAssistant/ModelSettings.tsx
index 2b05b9ae7..74493ab75 100644
--- a/src/components/SetupAIAssistant/ModelSettings.tsx
+++ b/src/components/SetupAIAssistant/ModelSettings.tsx
@@ -15,6 +15,8 @@ import { LoadingSpinner } from "../LoadingSpinner"
 import { WarningIcon, XIcon } from "@phosphor-icons/react"
 import { createProviderByType } from "../../utils/ai/registry"
 import type { ProviderType } from "../../utils/ai/settings"
+import { PermissionsSection } from "../../scenes/Footer/MCPBridgeStatus/PermissionsSection"
+import type { Permissions } from "../../utils/tools/permissions"
 
 export const InputSection = styled(Box).attrs({
   flexDirection: "column",
@@ -175,70 +177,6 @@ const SelectAllLink = styled.button`
   }
 `
 
-const SchemaAccessSection = styled(Box).attrs({
-  flexDirection: "column",
-  gap: "1.6rem",
-  align: "flex-start",
-})`
-  width: 100%;
-`
-
-const SchemaAccessTitle = styled(Text)`
-  font-size: 1.6rem;
-  font-weight: 600;
-  color: ${({ theme }) => theme.color.gray2};
-  flex: 1;
-`
-
-const SchemaCheckboxContainer = styled(Box).attrs({
-  gap: "1.5rem",
-  align: "flex-start",
-})`
-  background: rgba(68, 71, 90, 0.56);
-  padding: 0.75rem;
-  border-radius: 0.4rem;
-  width: 100%;
-`
-
-const SchemaCheckboxInner = styled(Box).attrs({
-  gap: "1.5rem",
-  align: "center",
-})`
-  flex: 1;
-  padding: 0.75rem;
-  border-radius: 0.5rem;
-`
-
-const SchemaCheckboxWrapper = styled.div`
-  flex-shrink: 0;
-  display: flex;
-  align-items: center;
-`
-
-const SchemaCheckboxContent = styled(Box).attrs({
-  flexDirection: "column",
-  gap: "0.6rem",
-})`
-  flex: 1;
-`
-
-const SchemaCheckboxLabel = styled(Text)`
-  font-size: 1.4rem;
-  font-weight: 500;
-  color: ${({ theme }) => theme.color.foreground};
-`
-
-const SchemaCheckboxDescription = styled(Text)`
-  font-size: 1.3rem;
-  font-weight: 400;
-  color: ${({ theme }) => theme.color.gray2};
-`
-
-const SchemaCheckboxDescriptionBold = styled.span`
-  font-weight: 500;
-  color: ${({ theme }) => theme.color.foreground};
-`
-
 const ContentSection = styled(Box).attrs({
   flexDirection: "column",
   gap: "2rem",
@@ -271,13 +209,14 @@ export type FetchConfig = {
 export type ModelSettingsInitialValues = {
   models?: string[]
   contextWindow?: number
-  grantSchemaAccess?: boolean
+  // Missing keys fall back to: schema=true, read=false, write=false.
+  permissions?: Partial<Permissions>
 }
 
 export type ModelSettingsData = {
   models: string[]
   contextWindow: number
-  grantSchemaAccess: boolean
+  permissions: Permissions
 }
 
 export type ModelSettingsRef = {
@@ -289,7 +228,6 @@ export type ModelSettingsProps = {
   initialValues?: ModelSettingsInitialValues
   fetchConfig: FetchConfig
   renderSchemaAccess?: boolean
-  providerName?: string
   onLoadingChange?: (loading: boolean) => void
 }
 
@@ -313,13 +251,7 @@ async function fetchProviderModels(
 
 export const ModelSettings = forwardRef<ModelSettingsRef, ModelSettingsProps>(
   (
-    {
-      initialValues,
-      fetchConfig,
-      renderSchemaAccess,
-      providerName,
-      onLoadingChange,
-    },
+    { initialValues, fetchConfig, renderSchemaAccess, onLoadingChange },
     ref,
   ) => {
     const theme = useTheme()
@@ -333,9 +265,11 @@ export const ModelSettings = forwardRef<ModelSettingsRef, ModelSettingsProps>(
     const [contextWindowInput, setContextWindowInput] = useState(() =>
       String(initialValues?.contextWindow ?? 200_000),
     )
-    const [grantSchemaAccess, setGrantSchemaAccess] = useState(
-      () => initialValues?.grantSchemaAccess ?? true,
-    )
+    const [permissions, setPermissions] = useState<Permissions>(() => ({
+      grantSchemaAccess: initialValues?.permissions?.grantSchemaAccess ?? true,
+      read: initialValues?.permissions?.read ?? false,
+      write: initialValues?.permissions?.write ?? false,
+    }))
     const [isLoading, setIsLoading] = useState(true)
 
     const fetchConfigRef = useRef(fetchConfig)
@@ -450,7 +384,7 @@ export const ModelSettings = forwardRef<ModelSettingsRef, ModelSettingsProps>(
           }
 
           const contextWindow = Number(contextWindowInput) || 0
-          return { models, contextWindow, grantSchemaAccess }
+          return { models, contextWindow, permissions }
         },
         validate: () => {
           const pending = manualModelInput.trim()
@@ -473,7 +407,7 @@ export const ModelSettings = forwardRef<ModelSettingsRef, ModelSettingsProps>(
         selectedModels,
         manualModels,
         contextWindowInput,
-        grantSchemaAccess,
+        permissions,
       ],
     )
 
@@ -638,35 +572,11 @@ export const ModelSettings = forwardRef<ModelSettingsRef, ModelSettingsProps>(
           <>
             <Separator />
             <ContentSection align="flex-start">
-              <SchemaAccessSection>
-                <SchemaAccessTitle>Schema Access</SchemaAccessTitle>
-                <SchemaCheckboxContainer>
-                  <SchemaCheckboxInner>
-                    <SchemaCheckboxWrapper>
-                      <Checkbox
-                        data-hook="custom-provider-schema-access"
-                        checked={grantSchemaAccess}
-                        onChange={(e) => setGrantSchemaAccess(e.target.checked)}
-                      />
-                    </SchemaCheckboxWrapper>
-                    <SchemaCheckboxContent align="flex-start">
-                      <SchemaCheckboxLabel>
-                        Grant schema access to {providerName || "this provider"}
-                      </SchemaCheckboxLabel>
-                      <SchemaCheckboxDescription>
-                        When enabled, the AI assistant can access your database
-                        schema information to provide more accurate suggestions
-                        and explanations. Schema information helps the AI
-                        understand your table structures, column names, and
-                        relationships.{" "}
-                        <SchemaCheckboxDescriptionBold>
-                          The AI model will not have access to your data.
-                        </SchemaCheckboxDescriptionBold>
-                      </SchemaCheckboxDescription>
-                    </SchemaCheckboxContent>
-                  </SchemaCheckboxInner>
-                </SchemaCheckboxContainer>
-              </SchemaAccessSection>
+              <PermissionsSection
+                value={permissions}
+                onChange={setPermissions}
+                variant="rich"
+              />
             </ContentSection>
           </>
         )}
diff --git a/src/components/SetupAIAssistant/SettingsModal.tsx b/src/components/SetupAIAssistant/SettingsModal.tsx
index db6df70d3..bd0b59a2b 100644
--- a/src/components/SetupAIAssistant/SettingsModal.tsx
+++ b/src/components/SetupAIAssistant/SettingsModal.tsx
@@ -5,7 +5,6 @@ import { Dialog } from "../Dialog"
 import { Box } from "../Box"
 import { Input } from "../Input"
 import { Switch } from "../Switch"
-import { Checkbox } from "../Checkbox"
 import { Text } from "../Text"
 import { Button } from "../Button"
 import { useLocalStorage } from "../../providers/LocalStorageProvider"
@@ -34,6 +33,8 @@ import type {
   AiAssistantSettings,
   CustomProviderDefinition,
 } from "../../providers/LocalStorageProvider/types"
+import { PermissionsSection } from "../../scenes/Footer/MCPBridgeStatus/PermissionsSection"
+import type { Permissions } from "../../utils/tools/permissions"
 import { ForwardRef } from "../ForwardRef"
 import { Badge, BadgeType } from "../../components/Badge"
 import { CheckboxCircle } from "@styled-icons/remix-fill"
@@ -417,77 +418,6 @@ const ManageModelsButton = styled.button`
   }
 `
 
-const SchemaAccessSection = styled(Box).attrs({
-  flexDirection: "column",
-  gap: "1.6rem",
-})`
-  width: 100%;
-`
-
-const SchemaAccessHeader = styled(Box).attrs({
-  justifyContent: "space-between",
-  align: "center",
-  gap: "1rem",
-})`
-  width: 100%;
-`
-
-const SchemaAccessTitle = styled(Text)`
-  font-size: 1.6rem;
-  font-weight: 600;
-  color: ${({ theme }) => theme.color.foreground};
-  flex: 1;
-`
-
-const SchemaCheckboxContainer = styled(Box).attrs({
-  gap: "1.5rem",
-  align: "flex-start",
-})`
-  background: rgba(68, 71, 90, 0.56);
-  padding: 0.75rem;
-  border-radius: 0.4rem;
-  width: 100%;
-`
-
-const SchemaCheckboxInner = styled(Box).attrs({
-  gap: "1.5rem",
-  align: "center",
-})`
-  flex: 1;
-  padding: 0.75rem;
-  border-radius: 0.5rem;
-`
-
-const SchemaCheckboxWrapper = styled.div`
-  flex-shrink: 0;
-  display: flex;
-  align-items: center;
-`
-
-const SchemaCheckboxContent = styled(Box).attrs({
-  flexDirection: "column",
-  gap: "0.6rem",
-})`
-  flex: 1;
-`
-
-const SchemaCheckboxLabel = styled(Text)`
-  font-size: 1.4rem;
-  font-weight: 500;
-  color: ${({ theme }) => theme.color.foreground};
-`
-
-const SchemaCheckboxDescription = styled(Text)`
-  font-size: 1.3rem;
-  font-weight: 400;
-  color: ${({ theme }) => theme.color.gray2};
-`
-
-const SchemaCheckboxDescriptionBold = styled.span`
-  font-weight: 500;
-  color: ${({ theme }) => theme.color.foreground};
-`
-
 const RemoveProviderButton = styled(Button)`
   border: 0.1rem solid ${({ theme }) => theme.color.red};
   background: ${({ theme }) => theme.color.backgroundDarker};
@@ -621,16 +551,25 @@ export const SettingsModal = ({ open, onOpenChange }: SettingsModalProps) => {
       [],
     ),
   )
-  const [grantSchemaAccess, setGrantSchemaAccess] = useState<
-    Record<ProviderId, boolean>
+  const [permissions, setPermissions] = useState<
+    Record<ProviderId, Permissions>
   >(() =>
-    initializeProviderState((provider) => {
-      const providerSettings = aiAssistantSettings.providers?.[provider]
-      if (providerSettings) return providerSettings.grantSchemaAccess !== false
-      const custom = aiAssistantSettings.customProviders?.[provider]
-      if (custom) return custom.grantSchemaAccess !== false
-      return true
-    }, true),
+    initializeProviderState<Permissions>(
+      (provider) => {
+        const providerSettings = aiAssistantSettings.providers?.[provider]
+        const custom = aiAssistantSettings.customProviders?.[provider]
+        const source = providerSettings ?? custom
+        if (!source) {
+          return { grantSchemaAccess: true, read: false, write: false }
+        }
+        return {
+          grantSchemaAccess: source.grantSchemaAccess !== false,
+          read: source.read === true,
+          write: source.write === true,
+        }
+      },
+      { grantSchemaAccess: true, read: false, write: false },
+    ),
   )
   const [validatedApiKeys, setValidatedApiKeys] = useState<
     Record<ProviderId, boolean>
@@ -766,12 +705,17 @@ export const SettingsModal = ({ open, onOpenChange }: SettingsModalProps) => {
     [],
   )
 
-  const handleSchemaAccessChange = useCallback(
-    (provider: ProviderId, checked: boolean) => {
-      if (!checked) {
-        void trackEvent(ConsoleEvent.AI_SETTINGS_SCHEMA_ACCESS_REMOVE)
-      }
-      setGrantSchemaAccess((prev) => ({ ...prev, [provider]: checked }))
+  // Emit the legacy schema-access-removed event on grantSchemaAccess → false
+  // so existing dashboards keep working.
+  const handlePermissionsChange = useCallback(
+    (provider: ProviderId, next: Permissions) => {
+      setPermissions((prev) => {
+        const prior = prev[provider]
+        if (prior?.grantSchemaAccess && !next.grantSchemaAccess) {
+          void trackEvent(ConsoleEvent.AI_SETTINGS_SCHEMA_ACCESS_REMOVE)
+        }
+        return { ...prev, [provider]: next }
+      })
     },
     [],
   )
@@ -783,10 +727,13 @@ export const SettingsModal = ({ open, onOpenChange }: SettingsModalProps) => {
     for (const provider of allProviderIds) {
       const isCustom = !BUILTIN_PROVIDERS[provider]
       if (validatedApiKeys[provider] || isCustom) {
+        const perms = permissions[provider]
         updatedProviders[provider] = {
           apiKey: apiKeys[provider] ?? "",
           enabledModels: enabledModels[provider],
-          grantSchemaAccess: grantSchemaAccess[provider],
+          grantSchemaAccess: perms.grantSchemaAccess,
+          read: perms.read,
+          write: perms.write,
         }
       } else {
         delete updatedProviders[provider]
@@ -800,17 +747,19 @@ export const SettingsModal = ({ open, onOpenChange }: SettingsModalProps) => {
       }
     }
 
-    // Sync API keys and schema access into custom provider definitions
     const updatedCustomProviders =
       Object.keys(localCustomProviders).length > 0
         ? { ...localCustomProviders }
         : undefined
     if (updatedCustomProviders) {
       for (const provider of Object.keys(updatedCustomProviders)) {
+        const perms = permissions[provider]
         updatedCustomProviders[provider] = {
           ...updatedCustomProviders[provider],
           apiKey: apiKeys[provider] || undefined,
-          grantSchemaAccess: grantSchemaAccess[provider],
+          grantSchemaAccess: perms.grantSchemaAccess,
+          read: perms.read,
+          write: perms.write,
         }
       }
     }
@@ -837,7 +786,7 @@ export const SettingsModal = ({ open, onOpenChange }: SettingsModalProps) => {
     localCustomProviders,
     apiKeys,
     enabledModels,
-    grantSchemaAccess,
+    permissions,
     validatedApiKeys,
     updateSettings,
     onOpenChange,
@@ -862,7 +811,10 @@ export const SettingsModal = ({ open, onOpenChange }: SettingsModalProps) => {
       }
 
       setApiKeys((prev) => ({ ...prev, [providerId]: "" }))
-      setGrantSchemaAccess((prev) => ({ ...prev, [providerId]: false }))
+      setPermissions((prev) => ({
+        ...prev,
+        [providerId]: { grantSchemaAccess: false, read: false, write: false },
+      }))
       setValidatedApiKeys((prev) => ({ ...prev, [providerId]: false }))
       setValidationState((prev) => ({ ...prev, [providerId]: "idle" }))
       setValidationErrors((prev) => ({ ...prev, [providerId]: null }))
@@ -899,9 +851,13 @@ export const SettingsModal = ({ open, onOpenChange }: SettingsModalProps) => {
         ...prev,
         [providerId]: definition.apiKey ?? "",
       }))
-      setGrantSchemaAccess((prev) => ({
+      setPermissions((prev) => ({
         ...prev,
-        [providerId]: definition.grantSchemaAccess ?? false,
+        [providerId]: {
+          grantSchemaAccess: definition.grantSchemaAccess ?? false,
+          read: definition.read ?? false,
+          write: definition.write ?? false,
+        },
       }))
       setValidatedApiKeys((prev) => ({
         ...prev,
@@ -922,6 +878,8 @@ export const SettingsModal = ({ open, onOpenChange }: SettingsModalProps) => {
           apiKey: definition.apiKey ?? "",
           enabledModels: newEnabledModels,
           grantSchemaAccess: definition.grantSchemaAccess ?? false,
+          read: definition.read ?? false,
+          write: definition.write ?? false,
         },
       }
       updateSettings(StoreKey.AI_ASSISTANT_SETTINGS, {
@@ -1341,53 +1299,23 @@ export const SettingsModal = ({ open, onOpenChange }: SettingsModalProps) => {
                     </Box>
                   </ContentSection>
                   <ContentSection>
-                    <SchemaAccessSection>
-                      <SchemaAccessHeader>
-                        <SchemaAccessTitle>Schema Access</SchemaAccessTitle>
-                      </SchemaAccessHeader>
-                      <SchemaCheckboxContainer>
-                        <SchemaCheckboxInner>
-                          <SchemaCheckboxWrapper>
-                            <Checkbox
-                              id={`schema-access-${selectedProvider}`}
-                              checked={
-                                grantSchemaAccess[selectedProvider] ?? false
-                              }
-                              onChange={(e) =>
-                                handleSchemaAccessChange(
-                                  selectedProvider,
-                                  e.target.checked,
-                                )
-                              }
-                              disabled={
-                                !currentProviderValidated &&
-                                !(
-                                  isCustomProvider &&
-                                  modelsForProvider.length > 0
-                                )
-                              }
-                              data-hook="ai-settings-schema-access"
-                            />
-                          </SchemaCheckboxWrapper>
-                          <SchemaCheckboxContent align="flex-start">
-                            <SchemaCheckboxLabel>
-                              Grant schema access to{" "}
-                              {getProviderName(selectedProvider, localSettings)}
-                            </SchemaCheckboxLabel>
-                            <SchemaCheckboxDescription>
-                              When enabled, the AI assistant can access your
-                              database schema information to provide more
-                              accurate suggestions and explanations. Schema
-                              information helps the AI understand your table
-                              structures, column names, and relationships.{" "}
-                              <SchemaCheckboxDescriptionBold>
-                                The AI model will not have access to your data.
-                              </SchemaCheckboxDescriptionBold>
-                            </SchemaCheckboxDescription>
-                          </SchemaCheckboxContent>
-                        </SchemaCheckboxInner>
-                      </SchemaCheckboxContainer>
-                    </SchemaAccessSection>
+                    <PermissionsSection
+                      value={
+                        permissions[selectedProvider] ?? {
+                          grantSchemaAccess: false,
+                          read: false,
+                          write: false,
+                        }
+                      }
+                      onChange={(next) =>
+                        handlePermissionsChange(selectedProvider, next)
+                      }
+                      disabled={
+                        !currentProviderValidated &&
+                        !(isCustomProvider && modelsForProvider.length > 0)
+                      }
+                      variant="rich"
+                    />
                   </ContentSection>
                   <ContentSection style={{ alignItems: "flex-start" }}>
                     <RemoveProviderButton
diff --git a/src/components/index.ts b/src/components/index.ts
index 8eea33352..19c64df84 100644
--- a/src/components/index.ts
+++ b/src/components/index.ts
@@ -47,7 +47,9 @@ export * from "./Input"
 export * from "./Key"
 export * from "./Link"
 export * from "./Loader"
+export * from "./Markdown"
 export * from "./LoadingSpinner"
+export * from "./MultiSelect"
 export * from "./MultiStepModal"
 export * from "./Overlay"
 export * from "./PaneContent"
diff --git a/src/consts/shared-definitions.json b/src/consts/shared-definitions.json
new file mode 100644
index 000000000..2dba3209c
--- /dev/null
+++ b/src/consts/shared-definitions.json
@@ -0,0 +1,891 @@
+[
+  {
+    "name": "get_tables",
+    "category": "schema",
+    "description": "Get a list of all tables and materialized views in the QuestDB database",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {}
+    }
+  },
+  {
+    "name": "get_table_schema",
+    "category": "schema",
+    "description": "Get the full schema definition (DDL) for a specific table or materialized view",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "table_name": {
+          "type": "string",
+          "description": "The name of the table or materialized view to get schema for"
+        }
+      },
+      "required": ["table_name"]
+    }
+  },
+  {
+    "name": "get_table_details",
+    "category": "schema",
+    "description": "Get the runtime details/statistics of a specific table or materialized view",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "table_name": {
+          "type": "string",
+          "description": "The name of the table or materialized view to get details for"
+        }
+      },
+      "required": ["table_name"]
+    }
+  },
+  {
+    "name": "suggest_query",
+    "category": "free",
+    "surfaces": ["ai"],
+    "description": "Suggest a SQL query to the user. The query will be displayed as a suggestion that the user can accept or reject. Always validate the query using validate_query before suggesting it.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "The SQL query to suggest to the user"
+        }
+      },
+      "required": ["query"]
+    }
+  },
+  {
+    "name": "validate_query",
+    "category": "free",
+    "description": "Validate the syntax correctness of a SQL query using QuestDB's SQL syntax validator. All generated SQL queries should be validated using this tool before responding to the user.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "The SQL query to validate"
+        }
+      },
+      "required": ["query"]
+    }
+  },
+  {
+    "name": "get_questdb_toc",
+    "category": "free",
+    "description": "Get a table of contents listing all available QuestDB functions, operators, and SQL keywords. Use this first to see what documentation is available before requesting specific items.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {}
+    }
+  },
+  {
+    "name": "get_questdb_documentation",
+    "category": "free",
+    "description": "Get documentation for specific QuestDB functions, operators, or SQL keywords. This is much more efficient than loading all documentation.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "category": {
+          "type": "string",
+          "enum": [
+            "functions",
+            "operators",
+            "sql",
+            "concepts",
+            "schema",
+            "cookbook"
+          ],
+          "description": "The category of documentation to retrieve"
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of specific docs items in the category. IMPORTANT: Category of these items must match the category parameter. Name of these items should exactly match the entry in the table of contents you get with get_questdb_toc."
+        }
+      },
+      "required": ["category", "items"]
+    }
+  },
+  {
+    "name": "create_notebook",
+    "category": "free",
+    "mutatesNotebook": true,
+    "description": "Create a new QuestDB notebook tab in the editor. You never see query data; this only scaffolds the tab and binds the current chat if it isn't already bound to a notebook.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "label": {
+          "type": ["string", "null"],
+          "description": "Label shown on the new notebook tab. Pass null to use the default."
+        }
+      },
+      "required": ["label"]
+    }
+  },
+  {
+    "name": "duplicate_notebook",
+    "category": "free",
+    "mutatesNotebook": true,
+    "description": "Duplicate a notebook tab. Copies every cell (SQL, mode, chart config) and the layout into a NEW notebook labelled \"<label> (copy)\" placed right after the original; cell ids are regenerated and last-run results are cleared. Returns the new { bufferId, label }.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number",
+          "description": "Source notebook buffer id (from <notebook_context> prefix)."
+        }
+      },
+      "required": ["buffer_id"]
+    }
+  },
+  {
+    "name": "delete_notebook",
+    "category": "free",
+    "mutatesNotebook": true,
+    "description": "Archive (soft-delete) a notebook tab — the same as the user closing it with the X. It moves to history and the user can restore it; it is not permanently destroyed and query data is untouched. If this notebook is bound to the current chat, the binding goes stale (start a new one with create_notebook).",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number",
+          "description": "Notebook buffer id (from <notebook_context> prefix)."
+        }
+      },
+      "required": ["buffer_id"]
+    }
+  },
+  {
+    "name": "list_cells",
+    "category": "free",
+    "description": "List the cells in a notebook. Returns id, type, short preview (≤120 chars), position, mode, and last-run status. No cell data values.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number",
+          "description": "Notebook buffer id (from <notebook_context> prefix)."
+        }
+      },
+      "required": ["buffer_id"]
+    }
+  },
+  {
+    "name": "get_cell",
+    "category": "free",
+    "description": "Get full details of a cell (value, kind via `type`, UI flags, chart config, last-run status + trimmed error). `type:\"markdown\"` marks a prose cell whose `value` is markdown source; SQL cells omit `type`. Never includes query result data. By default the value is capped at 4 KB; a capped response carries `truncated: true` and `full_length`. A truncated value is NOT the cell's real content — NEVER write it back (update_cell / apply_notebook_state value); re-read with get_full_content: true first, or keep the cell with preserve_value: true.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": "string"
+        },
+        "get_full_content": {
+          "type": ["boolean", "null"],
+          "description": "True returns the verbatim full value with no cap (errors above 1 MB). Required before rewriting any cell whose read came back truncated. Null/omitted applies the 4 KB cap."
+        }
+      },
+      "required": ["buffer_id", "cell_id", "get_full_content"]
+    }
+  },
+  {
+    "name": "get_notebook_state",
+    "category": "free",
+    "description": "Full structural snapshot of a notebook (layout, cells with previews, kind via `type`, last-run statuses). `type:\"markdown\"` marks a prose cell; SQL cells omit `type`. No cell data values; no columns/rows/count. Previews are capped at 120 chars — cells cut carry `preview_truncated: true` + `full_length`; a preview is never a cell's real content to write back.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        }
+      },
+      "required": ["buffer_id"]
+    }
+  },
+  {
+    "name": "add_cell",
+    "category": "free",
+    "mutatesNotebook": true,
+    "description": "Append a cell to the notebook. Returns the new cell id and, if run=true, a per-query status array. You never see query rows or column data. Set type:\"markdown\" to add a prose cell instead of a SQL cell — its `sql` field then carries the markdown source, it is rendered (never executed), and `run` is ignored.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "sql": {
+          "type": "string",
+          "description": "SQL for the cell. May contain multiple statements separated by `;`. In draw mode, multi-statement cells overlay series on a single chart: the first query's timestamp column is the x-axis anchor, subsequent queries contribute additional numeric series merged on the time axis. For a markdown cell (type:\"markdown\"), this is the markdown source text instead of SQL."
+        },
+        "type": {
+          "type": ["string", "null"],
+          "enum": ["sql", "markdown", null],
+          "description": "Cell kind. \"markdown\" creates a rendered prose cell that is never executed (`run` is ignored). null/omitted = \"sql\"."
+        },
+        "after_cell_id": {
+          "type": ["string", "null"],
+          "description": "Insert after this cell id; pass null to append to the end."
+        },
+        "run": {
+          "type": ["boolean", "null"],
+          "description": "If true, run the cell immediately after inserting. Response then includes `ran` (true iff every statement succeeded), `queryCount`, and `results: string[]` — one entry per `;`-separated statement, each `\"success\"`, `\"cancelled\"`, or `\"ERROR: <message>\"`. The order matches the cell's SQL. Still no row data. Pass null to skip. Running is DQL-only: a cell containing DDL/DML (INSERT/UPDATE/CREATE/DROP/...) is added but NEVER executed — the response gets `{ ran: false, skipped: true, note: <reason> }`. Markdown cells (type:\"markdown\") are likewise never executed. Take consent from the user, then call run_cell explicitly."
+        }
+      },
+      "required": ["buffer_id", "sql", "after_cell_id", "run", "type"]
+    }
+  },
+  {
+    "name": "update_cell",
+    "category": "free",
+    "mutatesNotebook": true,
+    "editsCells": true,
+    "description": "Replace a cell's value. Overwrites preemptively — cells are auto-saved. Use to fix a broken SQL cell. When editing part of a long cell, base the new value on a non-truncated read (get_cell with get_full_content: true) — never on a preview or a `truncated: true` read.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": "string"
+        },
+        "value": {
+          "type": "string"
+        }
+      },
+      "required": ["buffer_id", "cell_id", "value"]
+    }
+  },
+  {
+    "name": "delete_cell",
+    "category": "free",
+    "mutatesNotebook": true,
+    "editsCells": true,
+    "description": "Delete a cell from the notebook.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": "string"
+        }
+      },
+      "required": ["buffer_id", "cell_id"]
+    }
+  },
+  {
+    "name": "move_cell_up",
+    "category": "free",
+    "mutatesNotebook": true,
+    "editsCells": true,
+    "description": "Swap a cell with the one above it.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": "string"
+        }
+      },
+      "required": ["buffer_id", "cell_id"]
+    }
+  },
+  {
+    "name": "move_cell_down",
+    "category": "free",
+    "mutatesNotebook": true,
+    "editsCells": true,
+    "description": "Swap a cell with the one below it.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": "string"
+        }
+      },
+      "required": ["buffer_id", "cell_id"]
+    }
+  },
+  {
+    "name": "duplicate_cell",
+    "category": "free",
+    "mutatesNotebook": true,
+    "description": "Duplicate a cell immediately after the original.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": "string"
+        }
+      },
+      "required": ["buffer_id", "cell_id"]
+    }
+  },
+  {
+    "name": "run_cell",
+    "category": "sql",
+    "mutatesNotebook": true,
+    "description": "Execute a SQL cell. Each `;`-separated statement runs sequentially; if one fails, the remaining statements are NOT attempted. Returns `{ success, queryCount, results: string[] }`, where each `results` entry is `\"success\"`, `\"cancelled\"`, or `\"ERROR: <message>\"`, in source order. You do NOT see columns, rows, or values — call run_query if you need data. `success` is true only when every statement reached `\"success\"`. This is the ONLY path that executes agent-initiated DDL/DML in a cell (apply_notebook_state and add_cell never auto-run writes) — it requires the 'write' permission and the user's consent. A markdown cell is never executed: the response is `{ ran: false, skipped: true, note: <reason> }`.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": "string"
+        }
+      },
+      "required": ["buffer_id", "cell_id"]
+    }
+  },
+  {
+    "name": "set_layout_mode",
+    "category": "free",
+    "mutatesNotebook": true,
+    "editsCells": true,
+    "description": "Switch a notebook between list and grid layouts.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "mode": {
+          "type": "string",
+          "enum": ["list", "grid"]
+        }
+      },
+      "required": ["buffer_id", "mode"]
+    }
+  },
+  {
+    "name": "set_cell_layout",
+    "category": "free",
+    "mutatesNotebook": true,
+    "editsCells": true,
+    "description": "Position a single cell in grid mode. x/y/w/h are integers in the 12-column react-grid-layout grid (w ≤ 12).",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": "string"
+        },
+        "x": {
+          "type": "number"
+        },
+        "y": {
+          "type": "number"
+        },
+        "w": {
+          "type": "number"
+        },
+        "h": {
+          "type": "number"
+        }
+      },
+      "required": ["buffer_id", "cell_id", "x", "y", "w", "h"]
+    }
+  },
+  {
+    "name": "set_cell_mode",
+    "category": "free",
+    "mutatesNotebook": true,
+    "editsCells": true,
+    "description": "Switch a SQL cell between run (table output) and draw (chart output). Draw cells auto-execute — do not call run_cell afterwards. MULTI-SERIES TIP: a draw-mode cell can hold multiple SELECT statements separated by `;`. The first query's timestamp column is the chart's x-axis (the 'anchor'); every additional query contributes its numeric columns as extra series merged on the time axis. Use this to overlay metrics that come from different tables or different aggregations on a single chart.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": "string"
+        },
+        "mode": {
+          "type": "string",
+          "enum": ["run", "draw"]
+        }
+      },
+      "required": ["buffer_id", "cell_id", "mode"]
+    }
+  },
+  {
+    "name": "set_cell_chart_config",
+    "category": "free",
+    "mutatesNotebook": true,
+    "editsCells": true,
+    "description": "Configure the chart for a draw-mode cell. The cell's `;`-separated SELECTs AUTO-COMBINE into one chart sharing the first query's x-axis; `queries` holds one config per statement (index-aligned). Queries combine when their x-axis kind matches: all-temporal merge by time, all-categorical merge by category name. Each query keeps its own `type` (line/area/stepLine/stepArea/bar/stackedBar/scatter/pie/candlestick); set `axis:\"right\"` (+ optional `right_axis`) for a series on a different unit/scale; `enabled:false` opts a query out (the first query is always included — it defines the x-axis). For a candlestick query, supply `ohlc:{open,high,low,close}` (required — a candlestick needs an explicit ohlc mapping). When x_column is a NUMERIC column (not a timestamp/category) it renders as a continuous value axis. Numeric-x charts are single-query (they don't combine). Patch semantics: top-level `x_column`/`name`/`right_axis` null = preserve; `queries` null = preserve; `queries: []` clears overrides (back to inference); a non-null `queries` array REPLACES all per-query configs (send one entry per `;`-split statement — a non-empty array whose length differs from the statement count is rejected). pie/scatter/stackedBar only render as a chart of their own (single-query).",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": "string"
+        },
+        "x_column": {
+          "type": ["string", "null"],
+          "description": "Shared x-axis column (the first query's). Null preserves."
+        },
+        "name": {
+          "type": ["string", "null"],
+          "description": "Chart title. Null preserves."
+        },
+        "queries": {
+          "type": ["array", "null"],
+          "description": "One config per `;`-split query, index-aligned. Send the FULL array — one entry per statement, never a partial subset: a non-null array REPLACES all per-query configs, so any omitted statement loses its config. A non-empty array whose length ≠ the cell's `;`-split statement count is REJECTED. Null (the whole array) preserves the current config; `[]` resets every statement to inference; a `null` entry infers just that statement.",
+          "items": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "line",
+                  "area",
+                  "stepLine",
+                  "stepArea",
+                  "bar",
+                  "stackedBar",
+                  "scatter",
+                  "pie",
+                  "candlestick"
+                ]
+              },
+              "y_columns": {
+                "type": ["array", "null"],
+                "items": { "type": "string" },
+                "description": "Columns to plot from THIS query; null = all numeric. Not used for candlestick — set `ohlc` instead."
+              },
+              "ohlc": {
+                "type": ["object", "null"],
+                "additionalProperties": false,
+                "description": "Candlestick OHLC mapping. All four required when used; null otherwise.",
+                "properties": {
+                  "open": { "type": "string" },
+                  "high": { "type": "string" },
+                  "low": { "type": "string" },
+                  "close": { "type": "string" }
+                },
+                "required": ["open", "high", "low", "close"]
+              },
+              "partition_by_column": {
+                "type": ["string", "null"],
+                "description": "Categorical column to partition this query's series by; null = none."
+              },
+              "axis": {
+                "type": ["string", "null"],
+                "enum": ["left", "right", null],
+                "description": "'right' = shared secondary axis for a different unit/scale. null = left."
+              },
+              "enabled": {
+                "type": ["boolean", "null"],
+                "description": "false opts this query out of the chart. null = included. The first query is always included."
+              },
+              "name": {
+                "type": ["string", "null"],
+                "description": "Legend label for this query."
+              }
+            },
+            "required": [
+              "type",
+              "y_columns",
+              "ohlc",
+              "partition_by_column",
+              "axis",
+              "enabled",
+              "name"
+            ]
+          }
+        },
+        "right_axis": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "description": "Shared right y-axis; meaningful when some query has axis='right'. Null preserves.",
+          "properties": {
+            "name": { "type": ["string", "null"] },
+            "min": {
+              "type": ["number", "null"],
+              "description": "Pin axis min (e.g. 0). Null = autoscale."
+            },
+            "max": {
+              "type": ["number", "null"],
+              "description": "Pin axis max (e.g. 100). Null = autoscale."
+            }
+          },
+          "required": ["name", "min", "max"]
+        }
+      },
+      "required": [
+        "buffer_id",
+        "cell_id",
+        "x_column",
+        "name",
+        "queries",
+        "right_axis"
+      ]
+    }
+  },
+  {
+    "name": "set_cell_autorefresh",
+    "category": "free",
+    "mutatesNotebook": true,
+    "editsCells": true,
+    "description": "Enable or disable auto-refresh polling for a draw-mode cell's chart.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": "string"
+        },
+        "value": {
+          "type": "boolean"
+        }
+      },
+      "required": ["buffer_id", "cell_id", "value"]
+    }
+  },
+  {
+    "name": "set_cell_chart_maximized",
+    "category": "free",
+    "mutatesNotebook": true,
+    "editsCells": true,
+    "description": "Toggle chart-fills-cell (maximized chart) for a draw cell.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": "string"
+        },
+        "value": {
+          "type": "boolean"
+        }
+      },
+      "required": ["buffer_id", "cell_id", "value"]
+    }
+  },
+  {
+    "name": "apply_notebook_state",
+    "category": "free",
+    "mutatesNotebook": true,
+    "description": "Bulk-apply the entire desired state of a notebook in one atomic call. Use INSTEAD OF chained add_cell + update_cell + set_cell_mode + set_cell_chart_config when composing a multi-cell layout from scratch or restructuring an existing notebook — far faster than per-cell calls. The cells array is the COMPLETE desired list: cells in the current notebook whose id is missing from your request are DELETED. For new cells, omit `id` and one will be generated. Each cell carries exactly one of `value` (full verbatim SQL) or `preserve_value: true` (keep the existing cell's SQL, results, and run history unchanged) — prefer preserve_value for every cell whose SQL you are not changing, and NEVER send a value reconstructed from a preview or a truncated get_cell read. Charts in mode='draw' with auto_refresh=true render automatically — do not call run_cell afterwards. Cells with resolved mode='run' (explicit, or omitted: new defaults to 'run', existing preserves) auto-execute after the apply — EXCEPT cells whose statements include DDL/DML (INSERT/UPDATE/CREATE/DROP/...): those are NEVER auto-executed (their `runs` entry gets `skipped: true`), so applying state can never trigger a write's side effects. Take consent from the user, then call run_cell explicitly to execute them. Markdown cells (type:\"markdown\") are rendered prose and are likewise never auto-run. The response includes a `runs: [{cellId, success, queryCount?, results?, error?, skipped?}]` array — `results` is the per-statement status list (`\"success\"` / `\"cancelled\"` / `\"ERROR: <message>\"`); a top-level `error` is set only when the run was refused before any statement executed. Always call get_workspace_state first; the state-freshness gate applies.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "layout_mode": {
+          "type": ["string", "null"],
+          "enum": ["list", "grid", null],
+          "description": "Notebook layout mode after this apply. Null preserves current."
+        },
+        "maximized_cell_id": {
+          "type": ["string", "null"],
+          "description": "Spotlight one cell id, or null to clear. Pass null to clear."
+        },
+        "variables": {
+          "type": ["array", "null"],
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": ["name", "value"]
+          },
+          "description": "Ordered notebook-scoped global variables to be referenced as @var in the query (the DECLARE block surfaced in the Variables popover). Each item is {\"name\": \"from\", \"value\": \"dateadd('d', -7, now())\"}; names have no leading '@'. Order matters: if one variable references another, place the dependency first and the dependent variable later. Values are sent as a notebook-scoped `DECLARE` block prepended to each cell statement (or merged into the cell's own `DECLARE` block when present). Globals are server-resolved at parse time, so operator precedence and lexical shadowing follow QuestDB's `DECLARE` semantics. For non-`SELECT` statement forms (`INSERT`/`CREATE`/`UPDATE`/`ALTER`/…) globals are not injected; declare locally inside the inner `SELECT` if needed. Pass null to preserve current; pass [] to clear all."
+        },
+        "cells": {
+          "type": "array",
+          "description": "Complete desired cell list, in order. Cell at index N gets position N. Missing existing-cell ids are deleted.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": ["string", "null"],
+                "description": "Existing cell id to update, or null/omitted for a new cell."
+              },
+              "value": {
+                "type": ["string", "null"],
+                "description": "SQL text of the cell, VERBATIM and COMPLETE (from a non-truncated get_cell read; never from a preview or a `truncated: true` read). May contain multiple statements separated by `;`. In draw mode, this overlays series on one chart: the first query's timestamp is the x-axis anchor; subsequent queries contribute extra numeric series merged on time. Use this to combine metrics from different tables or different aggregations into a single chart. Null/omitted REQUIRES preserve_value: true."
+              },
+              "preserve_value": {
+                "type": ["boolean", "null"],
+                "description": "True keeps the existing cell's current SQL unchanged (and with it the cell's results and run history) instead of echoing it — exactly one of value / preserve_value:true per cell. PREFER this for every cell whose SQL you are not changing; it is the only safe option when your copy may be stale (STATE_STALE retry) or came from a truncated read. Existing-id cells only."
+              },
+              "type": {
+                "type": ["string", "null"],
+                "enum": ["sql", "markdown", null],
+                "description": "Cell kind. \"markdown\" makes this a rendered prose cell — `value` is markdown source, and `mode`/`chart_config` MUST be null (rejected otherwise). It is never executed or auto-run. Cell kind is STICKY: null/omitted preserves an existing cell's kind (it does NOT reset markdown cells to SQL); new cells default to \"sql\"."
+              },
+              "mode": {
+                "type": ["string", "null"],
+                "enum": ["run", "draw", null],
+                "description": "Cell mode. Null defaults to 'run' for new cells, preserves current for existing."
+              },
+              "auto_refresh": {
+                "type": ["boolean", "null"],
+                "description": "Auto-refresh polling for draw cells. Null defaults to true when mode='draw'."
+              },
+              "is_chart_maximized": {
+                "type": ["boolean", "null"],
+                "description": "Chart-fills-cell flag. Null defaults to true when mode='draw'."
+              },
+              "chart_config": {
+                "type": ["object", "null"],
+                "additionalProperties": false,
+                "description": "Chart configuration; required when mode='draw'. apply_notebook_state is a full PUT — this REPLACES the cell's chart entirely; null/omitted means NO chart (it is NOT preserved). To keep an existing chart unchanged, re-send its full config (shown as `chart_config` on the cell in <notebook_context> / get_notebook_state). The cell's `;`-separated SELECTs auto-combine into one chart sharing the first query's x-axis; `queries` holds one config per statement (each keeps its own type; axis:'right' for a second scale).",
+                "properties": {
+                  "x_column": {
+                    "type": ["string", "null"]
+                  },
+                  "name": {
+                    "type": ["string", "null"]
+                  },
+                  "queries": {
+                    "type": ["array", "null"],
+                    "description": "One config per `;`-split query, index-aligned — send the FULL array, exactly one entry per statement (its length must equal the cell's `;`-split statement count, else REJECTED). These entries are the chart's per-query configs in full (apply is a PUT); a `null` entry infers that statement. To keep a chart unchanged, re-send its full config from <notebook_context>.",
+                    "items": {
+                      "type": ["object", "null"],
+                      "additionalProperties": false,
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "enum": [
+                            "line",
+                            "area",
+                            "stepLine",
+                            "stepArea",
+                            "bar",
+                            "stackedBar",
+                            "scatter",
+                            "pie",
+                            "candlestick"
+                          ]
+                        },
+                        "y_columns": {
+                          "type": ["array", "null"],
+                          "items": { "type": "string" }
+                        },
+                        "ohlc": {
+                          "type": ["object", "null"],
+                          "additionalProperties": false,
+                          "properties": {
+                            "open": { "type": "string" },
+                            "high": { "type": "string" },
+                            "low": { "type": "string" },
+                            "close": { "type": "string" }
+                          },
+                          "required": ["open", "high", "low", "close"]
+                        },
+                        "partition_by_column": {
+                          "type": ["string", "null"]
+                        },
+                        "axis": {
+                          "type": ["string", "null"],
+                          "enum": ["left", "right", null]
+                        },
+                        "enabled": {
+                          "type": ["boolean", "null"]
+                        },
+                        "name": {
+                          "type": ["string", "null"]
+                        }
+                      },
+                      "required": [
+                        "type",
+                        "y_columns",
+                        "ohlc",
+                        "partition_by_column",
+                        "axis",
+                        "enabled",
+                        "name"
+                      ]
+                    }
+                  },
+                  "right_axis": {
+                    "type": ["object", "null"],
+                    "additionalProperties": false,
+                    "properties": {
+                      "name": { "type": ["string", "null"] },
+                      "min": { "type": ["number", "null"] },
+                      "max": { "type": ["number", "null"] }
+                    },
+                    "required": ["name", "min", "max"]
+                  }
+                },
+                "required": ["x_column", "name", "queries", "right_axis"]
+              },
+              "grid": {
+                "type": ["object", "null"],
+                "additionalProperties": false,
+                "description": "Grid position when layout_mode='grid'. x/y/w/h in 12-column units (w ≤ 12).",
+                "properties": {
+                  "x": {
+                    "type": "integer"
+                  },
+                  "y": {
+                    "type": "integer"
+                  },
+                  "w": {
+                    "type": "integer"
+                  },
+                  "h": {
+                    "type": "integer"
+                  }
+                },
+                "required": ["x", "y", "w", "h"]
+              }
+            },
+            "required": [
+              "id",
+              "value",
+              "preserve_value",
+              "type",
+              "mode",
+              "auto_refresh",
+              "is_chart_maximized",
+              "chart_config",
+              "grid"
+            ]
+          }
+        }
+      },
+      "required": [
+        "buffer_id",
+        "layout_mode",
+        "maximized_cell_id",
+        "variables",
+        "cells"
+      ]
+    }
+  },
+  {
+    "name": "set_cell_maximized",
+    "category": "free",
+    "mutatesNotebook": true,
+    "editsCells": true,
+    "description": "Spotlight one cell (or null to restore normal layout). Hides other cells in the notebook view.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "buffer_id": {
+          "type": "number"
+        },
+        "cell_id": {
+          "type": ["string", "null"],
+          "description": "Cell id to spotlight, or null to clear."
+        }
+      },
+      "required": ["buffer_id", "cell_id"]
+    }
+  },
+  {
+    "name": "run_query",
+    "category": "sql",
+    "description": "Execute an arbitrary SQL statement against the user's QuestDB instance and return the result rows so you can inspect data, validate work, or compose follow-up queries. UNLIKE `run_cell`, this tool DOES return data values. Default limit is 100 rows; pass `limit` (max 10000) to request more. The response payload is capped at ~1 MB — rows beyond that are dropped from the tail. The response includes `truncated`, `total_count`, and `returned_count` so you know exactly what was clipped. DDL/DML (CREATE / INSERT / UPDATE / DROP / etc.) is allowed and executes against the live database — be deliberate. Auth + connection are handled by the user's already-authenticated browser session.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sql": {
+          "type": "string",
+          "description": "The SQL statement to execute."
+        },
+        "limit": {
+          "type": ["integer", "null"],
+          "minimum": 1,
+          "maximum": 10000,
+          "description": "Maximum rows to return (default 100, max 10000). Pass null for default."
+        }
+      },
+      "required": ["sql", "limit"]
+    }
+  },
+  {
+    "name": "get_workspace_state",
+    "category": "free",
+    "surfaces": ["mcp"],
+    "description": "If notebook tools fail with BRIDGE_NOT_PAIRED, call get_pairing_credentials to begin pairing (the response includes a one-click URL to show the user; authentication runs in the browser, the bridge never sees credentials). Once paired, call get_workspace_state at the start of each notebook turn; the digest of edits since your last fetch is in get_recent_user_actions.\n\nReturn the current workspace + notebook context as text. Use this at the start of every notebook turn so you know which notebook is active, what cells exist, layout mode, chart configs, and last-run statuses. Pass include_user_events=true to also receive the digest of edits the user made since your last fetch.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "include_user_events": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "get_recent_user_actions",
+    "category": "free",
+    "surfaces": ["mcp"],
+    "description": "If notebook tools fail with BRIDGE_NOT_PAIRED, call get_pairing_credentials to begin pairing (the response includes a one-click URL to show the user; authentication runs in the browser, the bridge never sees credentials). Once paired, call get_workspace_state at the start of each notebook turn; the digest of edits since your last fetch is in get_recent_user_actions.\n\nReturn the digest of user edits to the notebook since your last fetch (or session start). Use this to detect that the user changed something the agent might want to react to. Coalesced — multiple typing events on the same cell collapse to a single 'edited' entry.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  }
+]
diff --git a/src/consts/shared-definitions.sync.test.ts b/src/consts/shared-definitions.sync.test.ts
new file mode 100644
index 000000000..f8fb3c548
--- /dev/null
+++ b/src/consts/shared-definitions.sync.test.ts
@@ -0,0 +1,25 @@
+import { existsSync, readFileSync } from "fs"
+import { dirname, resolve } from "path"
+import { fileURLToPath } from "url"
+
+// The MCP tool schema is duplicated: the UI loads its own copy, and the
+// mcp-bridge package loads its own. They MUST stay byte-identical — drift
+// silently breaks the bridge's view of the tools. `yarn sync-tools` would
+// overwrite the UI copy from `main`, so when editing on a feature branch,
+// edit BOTH src copies by hand and rely on this test to catch a missed one.
+const here = dirname(fileURLToPath(import.meta.url))
+const uiCopy = resolve(here, "shared-definitions.json")
+const bridgeCopy = resolve(
+  here,
+  "../../../mcp-bridge/src/consts/shared-definitions.json",
+)
+
+describe("shared-definitions.json", () => {
+  it("UI and mcp-bridge copies are byte-identical", () => {
+    const ui = readFileSync(uiCopy, "utf8")
+    // The mcp-bridge package is not always checked out alongside the UI
+    // (e.g. UI-only CI). Skip rather than fail when the sibling is absent.
+    if (!existsSync(bridgeCopy)) return
+    expect(readFileSync(bridgeCopy, "utf8")).toBe(ui)
+  })
+})
diff --git a/src/hooks/useAIQuickActions.ts b/src/hooks/useAIQuickActions.ts
index 53692e198..ef1f3aaaa 100644
--- a/src/hooks/useAIQuickActions.ts
+++ b/src/hooks/useAIQuickActions.ts
@@ -2,7 +2,7 @@ import { useContext } from "react"
 import { useSelector } from "react-redux"
 import { toast } from "../components"
 import { QuestContext } from "../providers"
-import { useAIConversation } from "../providers/AIConversationProvider"
+import { useAIConversationActions } from "../providers/AIConversationProvider"
 import { isBlockingAIStatus, useAIStatus } from "../providers/AIStatusProvider"
 import {
   executeAIFlow,
@@ -66,7 +66,7 @@ export const useAIQuickActions = () => {
     setIsStreaming,
     getLastRoundMessages,
     setScrollToMessageId,
-  } = useAIConversation()
+  } = useAIConversationActions()
 
   const getTableSchema = async (
     tableName: string,
diff --git a/src/hooks/useQueryExecution.ts b/src/hooks/useQueryExecution.ts
new file mode 100644
index 000000000..12c030ba9
--- /dev/null
+++ b/src/hooks/useQueryExecution.ts
@@ -0,0 +1,102 @@
+import { useCallback, useContext } from "react"
+import { QuestContext } from "../providers/QuestProvider"
+import * as QuestDB from "../utils/questdb"
+import type { ColumnDefinition, Timings } from "../utils/questdb/types"
+import { expandGlobals } from "../scenes/Editor/Notebook/declareUtils"
+import type { NotebookVariable } from "../store/notebook"
+
+export const RESULT_DISPLAY_LIMIT = 50_000
+
+export type QueryExecResult = {
+  type: "dql" | "ddl" | "dml" | "error"
+  query: string
+  columns: ColumnDefinition[]
+  dataset: (boolean | string | number | null)[][]
+  count: number
+  timestamp?: number
+  timings?: Timings
+  error?: string
+}
+
+export const useQueryExecution = (globals?: NotebookVariable[]) => {
+  const { quest } = useContext(QuestContext)
+
+  const executeSingle = useCallback(
+    async (
+      sql: string,
+      signal?: AbortSignal,
+      limit: number = RESULT_DISPLAY_LIMIT,
+    ): Promise<QueryExecResult> => {
+      try {
+        if (signal?.aborted) {
+          return {
+            type: "error",
+            query: sql,
+            columns: [],
+            dataset: [],
+            count: 0,
+            error: "Query aborted before execution.",
+          }
+        }
+        const expanded = expandGlobals(sql, globals)
+        const { promise, queryId } = quest.queryRaw(expanded, {
+          limit: `0,${limit}`,
+          cancellable: true,
+        })
+        if (signal) {
+          signal.addEventListener("abort", () => quest.abort(queryId), {
+            once: true,
+          })
+        }
+        const result = await promise
+
+        if (result.type === QuestDB.Type.DQL) {
+          return {
+            type: "dql",
+            query: sql,
+            columns: result.columns,
+            dataset: result.dataset,
+            count: result.count,
+            timestamp: result.timestamp,
+            timings: result.timings,
+          }
+        }
+
+        if (result.type === QuestDB.Type.ERROR) {
+          return {
+            type: "error",
+            query: sql,
+            columns: [],
+            dataset: [],
+            count: 0,
+            error: result.error,
+          }
+        }
+
+        return {
+          type: result.type === QuestDB.Type.DDL ? "ddl" : "dml",
+          query: sql,
+          columns: [],
+          dataset: [],
+          count: 0,
+        }
+      } catch (e: unknown) {
+        const err = e as Record<string, unknown> | null
+        return {
+          type: "error",
+          query: sql,
+          columns: [],
+          dataset: [],
+          count: 0,
+          error:
+            (err?.error as string) ??
+            (err?.message as string) ??
+            "Unknown error",
+        }
+      }
+    },
+    [quest, globals],
+  )
+
+  return { executeSingle }
+}
diff --git a/src/index.tsx b/src/index.tsx
index 1b23eb251..11907f38e 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -27,6 +27,12 @@ import "./js/console"
 import "./utils/monacoInit"
 import "./js/console/cryptoPolyfill"
 
+import { consumePendingPairFromUrl } from "./utils/mcp/consumePendingPair"
+
+// Stash MCP-pair URL params to sessionStorage before any provider mounts;
+// AuthProvider can trigger an OIDC redirect that drops them otherwise.
+consumePendingPairFromUrl()
+
 import React from "react"
 import ReactDOM from "react-dom"
 import { Provider } from "react-redux"
diff --git a/src/js/console/quick-vis.ts b/src/js/console/quick-vis.ts
index cac1aedb2..d7050c023 100644
--- a/src/js/console/quick-vis.ts
+++ b/src/js/console/quick-vis.ts
@@ -90,6 +90,7 @@ export function quickVis(
   let cachedQuery: AnyIfEmpty
   let requestActive: boolean = false
   let executionToken = 0
+  let activeQueryId: QuestDB.QueryId | null = null
 
   const chartTypePicker = new SlimSelect({
     select: "#_qvis_frm_chart_type",
@@ -283,13 +284,14 @@ export function quickVis(
 
       // time the query because control that displays query success expected time delta
       queryExecutionTimestamp = new Date().getTime()
-      const { promise: queryPromise } = quest.queryRaw(query, {
+      const { promise: queryPromise, queryId } = quest.queryRaw(query, {
         count: false,
         timings: false,
         cols: urlColumns,
         src: "vis",
         cancellable: true,
       })
+      activeQueryId = queryId
       try {
         const response = await queryPromise
         if (response.type === QuestDB.Type.DQL) {
@@ -299,6 +301,7 @@ export function quickVis(
         }
         eventBus.publish(EventType.MSG_QUERY_RUNNING)
       } finally {
+        activeQueryId = null
         releaseIfOwner()
         setDrawBtnToDraw()
       }
@@ -307,13 +310,20 @@ export function quickVis(
 
   function requestExecuteQueryAndDraw() {
     if (!query) return
-    questExecution.requestExecution(
-      QUICK_VIS_BUFFER_ID,
-      createDetachedQueryKey(query),
-      () => {
+    const queryKey = createDetachedQueryKey(query)
+    questExecution.requestExecution({
+      abort: () => {
+        if (activeQueryId !== null) {
+          quest.abort(activeQueryId)
+          activeQueryId = null
+        }
+      },
+      bufferId: QUICK_VIS_BUFFER_ID,
+      execute: () => {
         void executeQueryAndDraw()
       },
-    )
+      queryKey,
+    })
   }
 
   function clearChart() {
diff --git a/src/modules/EventBus/types.ts b/src/modules/EventBus/types.ts
index 6d98a5fbb..5c7156860 100644
--- a/src/modules/EventBus/types.ts
+++ b/src/modules/EventBus/types.ts
@@ -22,4 +22,7 @@ export enum EventType {
   BUFFERS_UPDATED = "buffers.updated",
   EXPLAIN_QUERY_EXEC = "ai.explain.query.exec",
   AI_QUERY_HIGHLIGHT = "ai.query.highlight",
+  NOTEBOOK_CELL_RESET_SIZE = "notebook.cell.reset.size",
+  NOTEBOOK_CELL_EXPAND_WIDTH = "notebook.cell.expand.width",
+  NOTEBOOK_REVEAL_CELL = "notebook.cell.reveal",
 }
diff --git a/src/modules/ZeroState/start.tsx b/src/modules/ZeroState/start.tsx
deleted file mode 100644
index 39d5bbae6..000000000
--- a/src/modules/ZeroState/start.tsx
+++ /dev/null
@@ -1,80 +0,0 @@
-import React from "react"
-import styled from "styled-components"
-import { bezierTransition, Text, Heading } from "../../components"
-import { actions } from "../../store"
-import { useDispatch } from "react-redux"
-import { useSettings } from "../../providers"
-
-const Items = styled.div`
-  display: grid;
-  grid-auto-flow: row;
-  grid-auto-columns: max-content;
-  gap: 4rem;
-  text-align: center;
-  justify-items: center;
-`
-
-const StyledHeading = styled(Heading)`
-  color: ${({ theme }) => theme.color.foreground};
-`
-
-const Action = styled.button`
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  border: none;
-  outline: none;
-  gap: 2rem;
-  padding: 2rem;
-  border-radius: ${({ theme }) => theme.borderRadius};
-  background: #2c2e3d;
-  cursor: pointer;
-  color: ${({ theme }) => theme.color.foreground};
-
-  &,
-  &:hover:not([disabled]) {
-    ${bezierTransition};
-  }
-
-  > * {
-    opacity: 0.8;
-  }
-
-  &:hover:not([disabled]) {
-    background: #3f4252;
-
-    > * {
-      opacity: 1;
-    }
-  }
-
-  &:disabled {
-    cursor: not-allowed;
-    opacity: 0.5;
-  }
-`
-
-export const Start = () => {
-  const dispatch = useDispatch()
-  const { consoleConfig } = useSettings()
-  return (
-    <Items>
-      <StyledHeading level={3}>
-        Enter a query and press <Text color="green">Run</Text> to view results.
-      </StyledHeading>
-      <Action
-        disabled={consoleConfig.readOnly}
-        onClick={() => dispatch(actions.console.setActiveBottomPanel("import"))}
-      >
-        <img
-          alt="File upload icon"
-          width="60"
-          height="80"
-          src="assets/upload.svg"
-        />
-        <Heading level={5}>Import CSV</Heading>
-      </Action>
-    </Items>
-  )
-}
diff --git a/src/providers/AIConversationProvider/index.tsx b/src/providers/AIConversationProvider/index.tsx
index 13660dc9a..af6d78951 100644
--- a/src/providers/AIConversationProvider/index.tsx
+++ b/src/providers/AIConversationProvider/index.tsx
@@ -16,7 +16,13 @@ import type {
   ChatWindowState,
   ConversationId,
   AIConversation,
+  UserActionDigest,
 } from "./types"
+import { applyUserActionToDigest, createEmptyDigest } from "./userActionDigest"
+import {
+  on as onUserAction,
+  type UserActionEvent,
+} from "../../utils/notebookAIBridge"
 import type { QueryKey } from "../../scenes/Editor/Monaco/utils"
 import {
   normalizeQueryText,
@@ -26,7 +32,7 @@ import {
   shiftQueryKey,
 } from "../../scenes/Editor/Monaco/utils"
 import { useEditor } from "../EditorProvider"
-import { normalizeSql } from "../../utils/aiAssistant"
+import { normalizeSql } from "../../utils/formatSql"
 import { useDispatch, useSelector } from "react-redux"
 import { trackEvent } from "../../modules/ConsoleEventTracker"
 import { ConsoleEvent } from "../../modules/ConsoleEventTracker/events"
@@ -41,7 +47,6 @@ export type AcceptSuggestionParams = {
 
 type AIConversationContextType = {
   conversationMetas: Map<ConversationId, ConversationMeta>
-  activeConversationMessages: ConversationMessage[]
   chatWindowState: ChatWindowState
   isLoadingMessages: boolean
   isStreaming: boolean
@@ -64,7 +69,23 @@ type AIConversationContextType = {
     bufferId?: number
     queryKey?: QueryKey
     tableId?: number
+    notebookBufferId?: number
   }) => Promise<AIConversation>
+  findNotebookChat: (notebookBufferId: number) => ConversationMeta | undefined
+  findOrCreateNotebookChat: (
+    notebookBufferId: number,
+  ) => Promise<AIConversation>
+  openNotebookChat: (notebookBufferId: number) => Promise<void>
+  bindConversationToNotebook: (
+    conversationId: ConversationId,
+    notebookBufferId: number,
+  ) => Promise<void>
+  readUserActionDigest: (
+    conversationId: ConversationId,
+  ) => UserActionDigest | undefined
+  rotateUserActionDigest: (
+    conversationId: ConversationId,
+  ) => UserActionDigest | undefined
   handleGlyphClick: (options: {
     bufferId: number
     queryKey: QueryKey
@@ -131,6 +152,43 @@ export const useAIConversation = () => {
   return context
 }
 
+const ActiveConversationMessagesContext = createContext<
+  ConversationMessage[] | undefined
+>(undefined)
+
+export const useActiveConversationMessages = () => {
+  const context = useContext(ActiveConversationMessagesContext)
+  if (context === undefined) {
+    throw new Error(
+      "useActiveConversationMessages must be used within AIConversationProvider",
+    )
+  }
+  return context
+}
+
+type AIConversationActionsContextType = Omit<
+  AIConversationContextType,
+  | "conversationMetas"
+  | "chatWindowState"
+  | "isLoadingMessages"
+  | "isStreaming"
+  | "scrollToMessageId"
+>
+
+const AIConversationActionsContext = createContext<
+  AIConversationActionsContextType | undefined
+>(undefined)
+
+export const useAIConversationActions = () => {
+  const context = useContext(AIConversationActionsContext)
+  if (!context) {
+    throw new Error(
+      "useAIConversationActions must be used within AIConversationProvider",
+    )
+  }
+  return context
+}
+
 export const AIConversationProvider: React.FC<{
   children: React.ReactNode
 }> = ({ children }) => {
@@ -147,6 +205,32 @@ export const AIConversationProvider: React.FC<{
     [conversationMetasArray],
   )
 
+  const userActionDigestsRef = useRef<Map<ConversationId, UserActionDigest>>(
+    new Map(),
+  )
+  const conversationMetasRef = useRef(conversationMetas)
+  useEffect(() => {
+    conversationMetasRef.current = conversationMetas
+  }, [conversationMetas])
+
+  useEffect(() => {
+    const cleanupUserActionListener = onUserAction(
+      "user-action",
+      (evt: UserActionEvent) => {
+        for (const meta of conversationMetasRef.current.values()) {
+          if (meta.notebookBufferId !== evt.bufferId) continue
+          let digest = userActionDigestsRef.current.get(meta.id)
+          if (!digest) {
+            digest = createEmptyDigest()
+            userActionDigestsRef.current.set(meta.id, digest)
+          }
+          applyUserActionToDigest(digest, evt)
+        }
+      },
+    )
+    return cleanupUserActionListener
+  }, [])
+
   const [activeConversationMessages, setActiveConversationMessages] = useState<
     ConversationMessage[]
   >([])
@@ -294,6 +378,7 @@ export const AIConversationProvider: React.FC<{
       bufferId?: number
       queryKey?: QueryKey
       tableId?: number
+      notebookBufferId?: number
     }): Promise<AIConversation> => {
       const id = crypto.randomUUID()
       const { queryText } = getQueryInfoFromKey(options.queryKey)
@@ -302,6 +387,7 @@ export const AIConversationProvider: React.FC<{
         queryKey: options.queryKey,
         bufferId: options.bufferId,
         tableId: options.tableId,
+        notebookBufferId: options.notebookBufferId,
         currentSQL: queryText,
         conversationName: "AI Assistant",
         updatedAt: Date.now(),
@@ -315,6 +401,64 @@ export const AIConversationProvider: React.FC<{
     [],
   )
 
+  const findNotebookChat = useCallback(
+    (notebookBufferId: number): ConversationMeta | undefined => {
+      let best: ConversationMeta | undefined
+      for (const meta of conversationMetas.values()) {
+        if (meta.notebookBufferId !== notebookBufferId) continue
+        if (!best || meta.updatedAt > best.updatedAt) best = meta
+      }
+      return best
+    },
+    [conversationMetas],
+  )
+
+  const findOrCreateNotebookChat = useCallback(
+    async (notebookBufferId: number): Promise<AIConversation> => {
+      const existing = findNotebookChat(notebookBufferId)
+      if (existing) {
+        const messages = await aiConversationStore.getMessages(existing.id)
+        return { ...existing, messages }
+      }
+      return createConversation({ notebookBufferId })
+    },
+    [findNotebookChat, createConversation],
+  )
+
+  const bindConversationToNotebook = useCallback(
+    async (
+      conversationId: ConversationId,
+      notebookBufferId: number,
+    ): Promise<void> => {
+      // Fall back to Dexie when ref hasn't picked up a freshly-created meta yet — otherwise bind silently no-ops.
+      const meta =
+        conversationMetasRef.current.get(conversationId) ??
+        (await aiConversationStore.getMeta(conversationId))
+      if (!meta) return
+      if (meta.notebookBufferId !== undefined) return
+      await aiConversationStore.updateMeta(conversationId, {
+        notebookBufferId,
+      })
+    },
+    [],
+  )
+
+  const readUserActionDigest = useCallback(
+    (conversationId: ConversationId): UserActionDigest | undefined =>
+      userActionDigestsRef.current.get(conversationId),
+    [],
+  )
+
+  const rotateUserActionDigest = useCallback(
+    (conversationId: ConversationId): UserActionDigest | undefined => {
+      const current = userActionDigestsRef.current.get(conversationId)
+      if (!current) return undefined
+      userActionDigestsRef.current.set(conversationId, createEmptyDigest())
+      return current
+    },
+    [],
+  )
+
   const acceptSuggestionChanges = useCallback(
     async (
       conversationId: ConversationId,
@@ -686,6 +830,15 @@ export const AIConversationProvider: React.FC<{
     await openChatWindow(blankConversation.id, { loadMessages: false })
   }, [createConversation, openChatWindow])
 
+  const openNotebookChat = useCallback(
+    async (notebookBufferId: number): Promise<void> => {
+      const conv = await findOrCreateNotebookChat(notebookBufferId)
+      const isExisting = conversationMetasRef.current.has(conv.id)
+      await openChatWindow(conv.id, { loadMessages: isExisting })
+    },
+    [findOrCreateNotebookChat, openChatWindow],
+  )
+
   const openHistoryView = useCallback(() => {
     void trackEvent(ConsoleEvent.AI_HISTORY_OPEN)
     setChatWindowState((prev) => ({
@@ -996,44 +1149,167 @@ export const AIConversationProvider: React.FC<{
     ],
   )
 
+  const actionsValue = useMemo<AIConversationActionsContextType>(
+    () => ({
+      setIsStreaming,
+      setScrollToMessageId,
+      getConversationMeta,
+      findConversationByQuery,
+      findConversationByTableId,
+      findQueryByConversationId,
+      hasConversationForQuery,
+      createConversation,
+      findNotebookChat,
+      findOrCreateNotebookChat,
+      openNotebookChat,
+      bindConversationToNotebook,
+      readUserActionDigest,
+      rotateUserActionDigest,
+      handleGlyphClick,
+      shiftQueryKeysForBuffer,
+      openChatWindow,
+      openOrCreateBlankChatWindow,
+      openBlankChatWindow,
+      closeChatWindow,
+      openHistoryView,
+      closeHistoryView,
+      deleteConversation,
+      addMessage,
+      removeMessages,
+      updateMessage,
+      updateMessagesWithCompaction,
+      updateConversationName,
+      acceptSuggestion,
+      rejectSuggestion,
+      persistMessages,
+      getLastRoundMessages,
+    }),
+    [
+      setIsStreaming,
+      setScrollToMessageId,
+      getConversationMeta,
+      findConversationByQuery,
+      findConversationByTableId,
+      findQueryByConversationId,
+      hasConversationForQuery,
+      createConversation,
+      findNotebookChat,
+      findOrCreateNotebookChat,
+      openNotebookChat,
+      bindConversationToNotebook,
+      readUserActionDigest,
+      rotateUserActionDigest,
+      handleGlyphClick,
+      shiftQueryKeysForBuffer,
+      openChatWindow,
+      openOrCreateBlankChatWindow,
+      openBlankChatWindow,
+      closeChatWindow,
+      openHistoryView,
+      closeHistoryView,
+      deleteConversation,
+      addMessage,
+      removeMessages,
+      updateMessage,
+      updateMessagesWithCompaction,
+      updateConversationName,
+      acceptSuggestion,
+      rejectSuggestion,
+      persistMessages,
+      getLastRoundMessages,
+    ],
+  )
+
+  const value = useMemo<AIConversationContextType>(
+    () => ({
+      conversationMetas,
+      chatWindowState,
+      isLoadingMessages,
+      isStreaming,
+      setIsStreaming,
+      scrollToMessageId,
+      setScrollToMessageId,
+      getConversationMeta,
+      findConversationByQuery,
+      findConversationByTableId,
+      hasConversationForQuery,
+      findQueryByConversationId,
+      createConversation,
+      handleGlyphClick,
+      shiftQueryKeysForBuffer,
+      openChatWindow,
+      openOrCreateBlankChatWindow,
+      openBlankChatWindow,
+      openNotebookChat,
+      findNotebookChat,
+      findOrCreateNotebookChat,
+      bindConversationToNotebook,
+      readUserActionDigest,
+      rotateUserActionDigest,
+      closeChatWindow,
+      openHistoryView,
+      closeHistoryView,
+      deleteConversation,
+      addMessage,
+      removeMessages,
+      updateMessage,
+      updateMessagesWithCompaction,
+      updateConversationName,
+      acceptSuggestion,
+      rejectSuggestion,
+      persistMessages,
+      getLastRoundMessages,
+    }),
+    [
+      conversationMetas,
+      chatWindowState,
+      isLoadingMessages,
+      isStreaming,
+      setIsStreaming,
+      scrollToMessageId,
+      setScrollToMessageId,
+      getConversationMeta,
+      findConversationByQuery,
+      findConversationByTableId,
+      hasConversationForQuery,
+      findQueryByConversationId,
+      createConversation,
+      handleGlyphClick,
+      shiftQueryKeysForBuffer,
+      openChatWindow,
+      openOrCreateBlankChatWindow,
+      openBlankChatWindow,
+      openNotebookChat,
+      findNotebookChat,
+      findOrCreateNotebookChat,
+      bindConversationToNotebook,
+      readUserActionDigest,
+      rotateUserActionDigest,
+      closeChatWindow,
+      openHistoryView,
+      closeHistoryView,
+      deleteConversation,
+      addMessage,
+      removeMessages,
+      updateMessage,
+      updateMessagesWithCompaction,
+      updateConversationName,
+      acceptSuggestion,
+      rejectSuggestion,
+      persistMessages,
+      getLastRoundMessages,
+    ],
+  )
+
   return (
-    <AIConversationContext.Provider
-      value={{
-        conversationMetas,
-        activeConversationMessages,
-        chatWindowState,
-        isLoadingMessages,
-        isStreaming,
-        setIsStreaming,
-        scrollToMessageId,
-        setScrollToMessageId,
-        getConversationMeta,
-        findConversationByQuery,
-        findConversationByTableId,
-        hasConversationForQuery,
-        findQueryByConversationId,
-        createConversation,
-        handleGlyphClick,
-        shiftQueryKeysForBuffer,
-        openChatWindow,
-        openOrCreateBlankChatWindow,
-        openBlankChatWindow,
-        closeChatWindow,
-        openHistoryView,
-        closeHistoryView,
-        deleteConversation,
-        addMessage,
-        removeMessages,
-        updateMessage,
-        updateMessagesWithCompaction,
-        updateConversationName,
-        acceptSuggestion,
-        rejectSuggestion,
-        persistMessages,
-        getLastRoundMessages,
-      }}
-    >
-      {children}
-    </AIConversationContext.Provider>
+    <AIConversationActionsContext.Provider value={actionsValue}>
+      <AIConversationContext.Provider value={value}>
+        <ActiveConversationMessagesContext.Provider
+          value={activeConversationMessages}
+        >
+          {children}
+        </ActiveConversationMessagesContext.Provider>
+      </AIConversationContext.Provider>
+    </AIConversationActionsContext.Provider>
   )
 }
diff --git a/src/providers/AIConversationProvider/types.ts b/src/providers/AIConversationProvider/types.ts
index ace6dfb8b..2d7987587 100644
--- a/src/providers/AIConversationProvider/types.ts
+++ b/src/providers/AIConversationProvider/types.ts
@@ -1,6 +1,7 @@
 import type { PartitionBy } from "../../utils/questdb"
 import type { QueryKey } from "../../scenes/Editor/Monaco/utils"
 import type { Message } from "../../utils/ai/types"
+import type { RanStatus } from "../../utils/ai/runStatus"
 import type { TokenUsage } from "../../utils/aiAssistant"
 import type { OperationHistory } from "../AIStatusProvider"
 
@@ -58,6 +59,18 @@ export type AIConversation = {
   bufferId?: number
   queryKey?: QueryKey
   currentSQL?: string
+  // 1:1 notebook binding — persists via Dexie, never auto-cleared.
+  notebookBufferId?: number
+}
+
+// Coalesced user-action summary since the last assistant turn — see applyUserActionToDigest for fold rules.
+export type UserActionDigest = {
+  added: Set<string>
+  deleted: Set<string>
+  edited: Set<string>
+  ran: Map<string, RanStatus>
+  layoutModeTo?: "list" | "grid"
+  notebookStatusChange?: "archived" | "deleted"
 }
 
 export type ChatWindowState = {
diff --git a/src/providers/AIConversationProvider/userActionDigest.test.ts b/src/providers/AIConversationProvider/userActionDigest.test.ts
new file mode 100644
index 000000000..1a2b7490d
--- /dev/null
+++ b/src/providers/AIConversationProvider/userActionDigest.test.ts
@@ -0,0 +1,162 @@
+import { describe, it, expect } from "vitest"
+import {
+  applyUserActionToDigest,
+  createEmptyDigest,
+  isEmptyDigest,
+} from "./userActionDigest"
+import type { UserActionEvent } from "../../utils/notebookAIBridge"
+
+const apply = (events: UserActionEvent[]) => {
+  const d = createEmptyDigest()
+  for (const e of events) applyUserActionToDigest(d, e)
+  return d
+}
+
+describe("createEmptyDigest / isEmptyDigest", () => {
+  it("starts empty", () => {
+    expect(isEmptyDigest(createEmptyDigest())).toBe(true)
+  })
+
+  it("is not empty after a single added cell", () => {
+    const d = apply([{ kind: "user_added_cell", bufferId: 1, cellId: "a" }])
+    expect(isEmptyDigest(d)).toBe(false)
+  })
+
+  it("stays empty for events that only affect the snapshot", () => {
+    const d = apply([
+      { kind: "user_moved_cell", bufferId: 1, cellId: "a" },
+      {
+        kind: "user_duplicated_cell",
+        bufferId: 1,
+        cellId: "a",
+        newCellId: "b",
+      },
+      {
+        kind: "user_changed_cell_mode",
+        bufferId: 1,
+        cellId: "a",
+        mode: "draw",
+      },
+      { kind: "user_changed_grid_layout", bufferId: 1 },
+    ])
+    expect(isEmptyDigest(d)).toBe(true)
+  })
+})
+
+describe("user_added_cell", () => {
+  it("adds the cell id to `added`", () => {
+    const d = apply([{ kind: "user_added_cell", bufferId: 1, cellId: "a" }])
+    expect([...d.added]).toEqual(["a"])
+  })
+
+  it("dedupes repeated adds of the same id", () => {
+    const d = apply([
+      { kind: "user_added_cell", bufferId: 1, cellId: "a" },
+      { kind: "user_added_cell", bufferId: 1, cellId: "a" },
+    ])
+    expect(d.added.size).toBe(1)
+  })
+})
+
+describe("user_deleted_cell", () => {
+  it("add-then-delete cancels both", () => {
+    const d = apply([
+      { kind: "user_added_cell", bufferId: 1, cellId: "a" },
+      { kind: "user_deleted_cell", bufferId: 1, cellId: "a" },
+    ])
+    expect(d.added.size).toBe(0)
+    expect(d.deleted.size).toBe(0)
+  })
+
+  it("delete-on-existing moves to `deleted`", () => {
+    const d = apply([{ kind: "user_deleted_cell", bufferId: 1, cellId: "a" }])
+    expect([...d.deleted]).toEqual(["a"])
+  })
+
+  it("delete removes the cell from edited and ran", () => {
+    const d = apply([
+      { kind: "user_updated_cell", bufferId: 1, cellId: "a" },
+      {
+        kind: "user_ran_cell",
+        bufferId: 1,
+        cellId: "a",
+        status: "success",
+      },
+      { kind: "user_deleted_cell", bufferId: 1, cellId: "a" },
+    ])
+    expect(d.edited.has("a")).toBe(false)
+    expect(d.ran.has("a")).toBe(false)
+    expect(d.deleted.has("a")).toBe(true)
+  })
+})
+
+describe("user_updated_cell", () => {
+  it("adds to `edited` for an existing cell", () => {
+    const d = apply([{ kind: "user_updated_cell", bufferId: 1, cellId: "a" }])
+    expect([...d.edited]).toEqual(["a"])
+  })
+
+  it("is a no-op when the cell is in `added` (edits fold into the add)", () => {
+    const d = apply([
+      { kind: "user_added_cell", bufferId: 1, cellId: "a" },
+      { kind: "user_updated_cell", bufferId: 1, cellId: "a" },
+      { kind: "user_updated_cell", bufferId: 1, cellId: "a" },
+    ])
+    expect(d.added.has("a")).toBe(true)
+    expect(d.edited.has("a")).toBe(false)
+  })
+
+  it("dedupes repeated edits on the same id", () => {
+    const d = apply([
+      { kind: "user_updated_cell", bufferId: 1, cellId: "a" },
+      { kind: "user_updated_cell", bufferId: 1, cellId: "a" },
+      { kind: "user_updated_cell", bufferId: 1, cellId: "a" },
+    ])
+    expect(d.edited.size).toBe(1)
+  })
+})
+
+describe("user_ran_cell", () => {
+  it("latest status wins", () => {
+    const d = apply([
+      { kind: "user_ran_cell", bufferId: 1, cellId: "a", status: "error" },
+      {
+        kind: "user_ran_cell",
+        bufferId: 1,
+        cellId: "a",
+        status: "success",
+      },
+    ])
+    expect(d.ran.get("a")).toBe("success")
+  })
+})
+
+describe("user_changed_layout_mode", () => {
+  it("stores the final mode", () => {
+    const d = apply([
+      { kind: "user_changed_layout_mode", bufferId: 1, mode: "list" },
+      { kind: "user_changed_layout_mode", bufferId: 1, mode: "grid" },
+    ])
+    expect(d.layoutModeTo).toBe("grid")
+  })
+})
+
+describe("notebook lifecycle events", () => {
+  it("user_archived_notebook flips the flag to archived", () => {
+    const d = apply([{ kind: "user_archived_notebook", bufferId: 1 }])
+    expect(d.notebookStatusChange).toBe("archived")
+  })
+
+  it("user_deleted_notebook flips the flag to deleted", () => {
+    const d = apply([{ kind: "user_deleted_notebook", bufferId: 1 }])
+    expect(d.notebookStatusChange).toBe("deleted")
+  })
+
+  it("delete wins over archive if both fire", () => {
+    const d = apply([
+      { kind: "user_archived_notebook", bufferId: 1 },
+      { kind: "user_deleted_notebook", bufferId: 1 },
+    ])
+    expect(d.notebookStatusChange).toBe("deleted")
+  })
+})
diff --git a/src/providers/AIConversationProvider/userActionDigest.ts b/src/providers/AIConversationProvider/userActionDigest.ts
new file mode 100644
index 000000000..8f2cda97d
--- /dev/null
+++ b/src/providers/AIConversationProvider/userActionDigest.ts
@@ -0,0 +1,60 @@
+import type { UserActionEvent } from "../../utils/notebookAIBridge"
+import type { UserActionDigest } from "./types"
+
+export const createEmptyDigest = (): UserActionDigest => ({
+  added: new Set(),
+  deleted: new Set(),
+  edited: new Set(),
+  ran: new Map(),
+})
+
+// Coalesces user-action events into the digest. Notes:
+// - delete after add in same digest cancels both (add wins → erased).
+// - edit on an added cell folds into the creation (no-op).
+// - move/duplicate/cell-mode/grid-layout aren't tracked here; they ride on the snapshot.
+export const applyUserActionToDigest = (
+  digest: UserActionDigest,
+  evt: UserActionEvent,
+): UserActionDigest => {
+  switch (evt.kind) {
+    case "user_added_cell":
+      digest.added.add(evt.cellId)
+      return digest
+    case "user_deleted_cell":
+      if (digest.added.has(evt.cellId)) {
+        digest.added.delete(evt.cellId)
+      } else {
+        digest.deleted.add(evt.cellId)
+      }
+      digest.edited.delete(evt.cellId)
+      digest.ran.delete(evt.cellId)
+      return digest
+    case "user_updated_cell":
+      if (!digest.added.has(evt.cellId)) {
+        digest.edited.add(evt.cellId)
+      }
+      return digest
+    case "user_ran_cell":
+      digest.ran.set(evt.cellId, evt.status)
+      return digest
+    case "user_changed_layout_mode":
+      digest.layoutModeTo = evt.mode
+      return digest
+    case "user_archived_notebook":
+      digest.notebookStatusChange = "archived"
+      return digest
+    case "user_deleted_notebook":
+      digest.notebookStatusChange = "deleted"
+      return digest
+    default:
+      return digest
+  }
+}
+
+export const isEmptyDigest = (d: UserActionDigest): boolean =>
+  d.added.size === 0 &&
+  d.deleted.size === 0 &&
+  d.edited.size === 0 &&
+  d.ran.size === 0 &&
+  d.layoutModeTo === undefined &&
+  d.notebookStatusChange === undefined
diff --git a/src/providers/AIStatusProvider/index.tsx b/src/providers/AIStatusProvider/index.tsx
index 28ef5189a..6ca42ad66 100644
--- a/src/providers/AIStatusProvider/index.tsx
+++ b/src/providers/AIStatusProvider/index.tsx
@@ -47,10 +47,22 @@ export enum AIOperationStatus {
   RetrievingDocumentation = "Reviewing docs",
   InvestigatingDocs = "Investigating docs",
   ValidatingQuery = "Validating query",
+  RunningQuery = "Running query",
   GeneratingResponse = "Generating response",
   Aborted = "Operation has been cancelled",
   Compacting = "Compacting conversation",
   Thinking = "Thinking",
+  BuildingNotebook = "Building notebook",
+  DuplicatingNotebook = "Duplicating notebook",
+  DeletingNotebook = "Deleting notebook",
+  AddingCell = "Adding cell",
+  UpdatingCell = "Updating cell",
+  DeletingCell = "Deleting cell",
+  RunningCell = "Running cell",
+  // Layout = positional/structural; Chart = visualization settings.
+  ConfiguringLayout = "Configuring layout",
+  ConfiguringChart = "Configuring chart",
+  InspectingNotebook = "Inspecting notebook",
 }
 
 export type StatusArgs = {
@@ -58,6 +70,9 @@ export type StatusArgs = {
   section?: string
   tableOpType?: "schema" | "details"
   items?: Array<{ name: string; section?: string }>
+  label?: string
+  cellId?: string
+  content?: string
 }
 
 export type StatusEntry = {
@@ -174,6 +189,9 @@ export const AIStatusProvider: React.FC<AIStatusProviderProps> = ({
           type: newStatus,
           args: normalizedArgs ?? undefined,
           timestamp: Date.now(),
+          ...(normalizedArgs?.content !== undefined && {
+            content: normalizedArgs.content,
+          }),
         }
         if (
           statusRef.current === null ||
diff --git a/src/providers/EditorProvider/index.tsx b/src/providers/EditorProvider/index.tsx
index 69b7400e0..26d2d9f21 100644
--- a/src/providers/EditorProvider/index.tsx
+++ b/src/providers/EditorProvider/index.tsx
@@ -1,4 +1,4 @@
-import type { Monaco } from "@monaco-editor/react"
+import { loader, type Monaco } from "@monaco-editor/react"
 import type { editor, IRange } from "monaco-editor"
 import React, {
   createContext,
@@ -20,8 +20,13 @@ import {
   parseQueryKey,
   createQueryKey,
 } from "../../scenes/Editor/Monaco/utils"
+import { useSchemaCompletionProvider } from "../../scenes/Editor/Monaco/questdb-sql/useSchemaCompletionProvider"
+import {
+  cloneNotebookViewState,
+  nextCopyLabel,
+} from "../../scenes/Editor/Notebook/notebookUtils"
 import type { ConversationId } from "../AIConversationProvider/types"
-import { normalizeSql } from "../../utils/aiAssistant"
+import { normalizeSql } from "../../utils/formatSql"
 import type { Buffer, PreviewContent } from "../../store/buffers"
 import type { ExecutionRefs } from "../../scenes/Editor/index"
 import {
@@ -33,8 +38,11 @@ import {
 } from "../../store/buffers"
 import { toast } from "../../components/Toast"
 import { db } from "../../store/db"
+import { deleteNotebookSnapshots } from "../../store/notebookResults"
+import { removeNotebookBufferLayouts } from "../../scenes/Editor/Notebook/notebookColumnLayoutStore"
 import { eventBus } from "../../modules/EventBus"
 import { EventType } from "../../modules/EventBus/types"
+import { emitUserAction } from "../../utils/notebookAIBridge"
 
 import { useLiveQuery } from "dexie-react-hooks"
 import { trackEvent } from "../../modules/ConsoleEventTracker"
@@ -86,10 +94,11 @@ export type EditorContext = {
   ) => Promise<void>
   addBuffer: (
     buffer?: Partial<Buffer>,
-    options?: { shouldSelectAll?: boolean },
+    options?: { shouldSelectAll?: boolean; afterBufferId?: number },
   ) => Promise<Buffer | undefined>
   deleteBuffer: (id: number, setActiveBuffer?: boolean) => Promise<void>
   archiveBuffer: (id: number) => Promise<void>
+  duplicateNotebook: (id: number) => Promise<Buffer | undefined>
   updateBuffer: (
     id: number,
     buffer?: Partial<Buffer>,
@@ -105,7 +114,6 @@ export type EditorContext = {
   isNavigatingFromSearchRef: MutableRefObject<boolean>
   showPreviewBuffer: (content: PreviewBufferContent) => Promise<void>
   closePreviewBuffer: () => Promise<void>
-  // Apply AI SQL change to editor
   applyAISQLChange: (options: ApplyAISQLChangeOptions) => ApplyAISQLChangeResult
   executionRefs: MutableRefObject<ExecutionRefs>
   cleanupExecutionRefs: (bufferId: number) => void
@@ -125,6 +133,7 @@ const defaultValues = {
   addBuffer: () => Promise.resolve(fallbackBuffer),
   deleteBuffer: () => Promise.resolve(),
   archiveBuffer: () => Promise.resolve(),
+  duplicateNotebook: () => Promise.resolve(undefined),
   updateBuffer: () => Promise.resolve(),
   updateBuffersPositions: () => Promise.resolve(),
   editorReadyTrigger: () => undefined,
@@ -146,6 +155,7 @@ export const EditorProvider: React.FC = ({ children }) => {
   const editorRef = useRef<IStandaloneCodeEditor>(null)
   const monacoRef = useRef<Monaco>(null)
   const executionRefs = useRef<ExecutionRefs>({})
+  const [loadedMonaco, setLoadedMonaco] = useState<Monaco | null>(null)
   const [temporaryBufferId, setTemporaryBufferId] = useState<number | null>(
     null,
   )
@@ -171,6 +181,8 @@ export const EditorProvider: React.FC = ({ children }) => {
 
   const ranOnce = useRef(false)
 
+  useSchemaCompletionProvider(loadedMonaco)
+
   const getNextPosition = useCallback(() => {
     if (!buffers) return 0
     const activeBuffers = buffers.filter((b) => !b.archived || b.isTemporary)
@@ -203,7 +215,11 @@ export const EditorProvider: React.FC = ({ children }) => {
           isNavigatingFromSearchRef.current = true
         }
 
-        if (editorRef.current && monacoRef.current) {
+        if (
+          editorRef.current &&
+          monacoRef.current &&
+          !buffer.notebookViewState
+        ) {
           const currentModel = editorRef.current.getModel()
           if (currentModel) {
             currentModel.dispose()
@@ -296,7 +312,7 @@ export const EditorProvider: React.FC = ({ children }) => {
   )
 
   const addBuffer: EditorContext["addBuffer"] = useCallback(
-    async (newBuffer, { shouldSelectAll = false } = {}) => {
+    async (newBuffer, { shouldSelectAll = false, afterBufferId } = {}) => {
       if (buffers && buffers.length >= MAX_TABS) {
         toast.error(
           `Tab limit reached (${MAX_TABS}). Please clear history to free up space.`,
@@ -304,28 +320,32 @@ export const EditorProvider: React.FC = ({ children }) => {
         return undefined
       }
 
+      const bufferType = newBuffer?.notebookViewState
+        ? BufferType.NOTEBOOK
+        : newBuffer?.metricsViewState
+          ? BufferType.METRICS
+          : BufferType.SQL
+
       void trackEvent(ConsoleEvent.TAB_ADD, {
-        type: newBuffer?.metricsViewState ? BufferType.METRICS : BufferType.SQL,
+        type: bufferType,
         count: (buffers?.length ?? 0) + 1,
       })
 
-      const fallback = makeFallbackBuffer(
-        newBuffer?.metricsViewState ? BufferType.METRICS : BufferType.SQL,
-      )
+      const fallback = makeFallbackBuffer(bufferType)
 
       const currentDefaultTabNumbers = (
         await db.buffers
-          .filter((buffer) =>
-            buffer.label.startsWith(fallback.label) &&
-            newBuffer?.metricsViewState
-              ? buffer.metricsViewState !== undefined
-              : true,
-          )
+          .filter((buffer) => {
+            if (!buffer.label.startsWith(fallback.label)) return false
+            if (newBuffer?.notebookViewState)
+              return buffer.notebookViewState !== undefined
+            if (newBuffer?.metricsViewState)
+              return buffer.metricsViewState !== undefined
+            return true
+          })
           .toArray()
       )
-        .map((buffer) =>
-          buffer.label.slice(fallback.label.length + /* whitespace */ 1),
-        )
+        .map((buffer) => buffer.label.slice(fallback.label.length + 1))
         .filter(Boolean)
         .map((n) => parseInt(n, 10))
         .sort()
@@ -339,21 +359,47 @@ export const EditorProvider: React.FC = ({ children }) => {
         }
       }
 
-      const position = buffers
-        ? buffers.filter((b) => !b.archived && !b.isTemporary).length
-        : 0
+      const activeBuffers = buffers
+        ? buffers.filter((b) => !b.archived && !b.isTemporary)
+        : []
+      const insertAfter =
+        afterBufferId !== undefined
+          ? activeBuffers.find((b) => b.id === afterBufferId)
+          : undefined
+      const position = insertAfter
+        ? insertAfter.position + 1
+        : activeBuffers.length
 
       const buffer = makeBuffer({
         ...newBuffer,
         label: newBuffer?.label ?? `${fallback.label} ${nextNumber()}`,
         position,
       })
-      const id = await db.buffers.add(buffer)
+
+      let id: number
+      if (insertAfter) {
+        const toShift = activeBuffers.filter(
+          (b) => typeof b.id === "number" && b.position >= position,
+        )
+        id = await db.transaction("rw", db.buffers, async () => {
+          for (const b of toShift) {
+            await db.buffers.update(b.id as number, {
+              position: b.position + 1,
+            })
+          }
+          return db.buffers.add(buffer)
+        })
+      } else {
+        id = await db.buffers.add(buffer)
+      }
 
       await setActiveBuffer(buffer, { focus: true })
 
-      // Select all text if requested (model is already created by setActiveBuffer)
-      if (shouldSelectAll && editorRef.current) {
+      if (
+        shouldSelectAll &&
+        editorRef.current &&
+        !newBuffer?.notebookViewState
+      ) {
         const model = editorRef.current.getModel()
         if (model) {
           editorRef.current.setSelection(model.getFullModelRange())
@@ -387,12 +433,10 @@ export const EditorProvider: React.FC = ({ children }) => {
       const label = content.type === "diff" ? "AI Suggestion" : "Preview"
 
       if (existingPreviewBuffer && existingPreviewBuffer.id) {
-        // Update existing preview buffer
         await bufferStore.update(existingPreviewBuffer.id, {
           previewContent,
           label,
         })
-        // Switch to it
         const updatedBuffer = {
           ...existingPreviewBuffer,
           previewContent,
@@ -400,7 +444,6 @@ export const EditorProvider: React.FC = ({ children }) => {
         }
         await setActiveBuffer(updatedBuffer)
       } else {
-        // Create new preview buffer
         const position = buffers
           ? buffers.filter((b) => !b.archived && !b.isTemporary).length
           : 0
@@ -411,13 +454,21 @@ export const EditorProvider: React.FC = ({ children }) => {
           position,
           previewContent,
         })
-        // addBuffer already switches to it
       }
     },
     [buffers, setActiveBuffer, addBuffer],
   )
 
-  // this effect should run only once, after mount and after `buffers` and `activeBufferId` are ready from the db
+  useEffect(() => {
+    let cancelled = false
+    void loader.init().then((m) => {
+      if (!cancelled) setLoadedMonaco(m)
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
   useEffect(() => {
     if (!ranOnce.current && buffers && activeBufferId) {
       const buffer =
@@ -445,14 +496,11 @@ export const EditorProvider: React.FC = ({ children }) => {
 
     if (payload && "isTemporary" in payload) {
       if (payload.isTemporary) {
-        // archived -> temporary
         setTemporaryBufferId(id)
       } else if (id === temporaryBufferId) {
         if (payload?.archived === false) {
-          // temporary -> permanent
           newPosition = getNextPosition()
         } else {
-          // temporary -> archived
           newPosition = -1
         }
         setTemporaryBufferId(null)
@@ -480,12 +528,15 @@ export const EditorProvider: React.FC = ({ children }) => {
       window.clearTimeout(searchUpdateTimeoutRef.current)
     }
 
-    const searchUpdateKeys = ["value", "label", "archived"]
+    const searchUpdateKeys = ["value", "label", "archived", "notebookViewState"]
     const keys = Object.keys(payload || {})
     if (searchUpdateKeys.some((key) => keys.includes(key))) {
       searchUpdateTimeoutRef.current = window.setTimeout(() => {
-        const metaUpdate = !(keys.length === 1 && keys[0] === "value")
-        const contentUpdate = keys.includes("value")
+        const contentOnlyKeys = ["value", "notebookViewState"]
+        const metaUpdate = !(
+          keys.length === 1 && contentOnlyKeys.includes(keys[0])
+        )
+        const contentUpdate = keys.some((key) => contentOnlyKeys.includes(key))
         eventBus.publish(EventType.BUFFERS_UPDATED, {
           type: "update",
           metaUpdate,
@@ -498,7 +549,6 @@ export const EditorProvider: React.FC = ({ children }) => {
   }
 
   const setActiveBufferOnRemoved = async (id: number) => {
-    // set new active buffer only when removing currently active buffer
     const activeBufferId = (await bufferStore.getActiveId())?.value
     if (typeof activeBufferId !== "undefined" && activeBufferId === id) {
       const nextActive = await db.buffers
@@ -517,6 +567,8 @@ export const EditorProvider: React.FC = ({ children }) => {
   }
 
   const archiveBuffer: EditorContext["archiveBuffer"] = async (id) => {
+    // Snapshot before write — live query refresh makes post-update read unreliable.
+    const wasNotebook = !!buffers.find((b) => b.id === id)?.notebookViewState
     await updateBuffer(id, {
       archived: true,
       archivedAt: new Date().getTime(),
@@ -527,12 +579,31 @@ export const EditorProvider: React.FC = ({ children }) => {
       type: "archive",
       bufferId: id,
     })
+    if (wasNotebook) {
+      emitUserAction({ kind: "user_archived_notebook", bufferId: id })
+    }
+  }
+
+  const duplicateNotebook: EditorContext["duplicateNotebook"] = async (id) => {
+    const source = buffers.find((b) => b.id === id)
+    if (!source?.notebookViewState) return undefined
+
+    const persisted = await bufferStore.getById(id)
+    const view = persisted?.notebookViewState ?? source.notebookViewState
+    return addBuffer(
+      {
+        label: nextCopyLabel(source.label),
+        notebookViewState: cloneNotebookViewState(view),
+      },
+      { afterBufferId: id },
+    )
   }
 
   const deleteBuffer: EditorContext["deleteBuffer"] = async (
     id,
     setActiveBuffer = true,
   ) => {
+    const wasNotebook = !!buffers.find((b) => b.id === id)?.notebookViewState
     await bufferStore.delete(id)
     cleanupExecutionRefs(id)
     if (setActiveBuffer) {
@@ -542,6 +613,11 @@ export const EditorProvider: React.FC = ({ children }) => {
       type: "delete",
       bufferId: id,
     })
+    if (wasNotebook) {
+      void deleteNotebookSnapshots(id)
+      removeNotebookBufferLayouts(id)
+      emitUserAction({ kind: "user_deleted_notebook", bufferId: id })
+    }
   }
 
   const setTemporaryBuffer: EditorContext["setTemporaryBuffer"] = async (
@@ -624,12 +700,11 @@ export const EditorProvider: React.FC = ({ children }) => {
           shouldReplace = true
         }
       } catch {
-        // Invalid queryKey or query not found, fall back to appending
+        // Invalid queryKey or query not found — fall back to appending.
       }
     }
 
     if (!shouldReplace || !replaceRange) {
-      // Append to end of editor
       const lineNumber = model.getLineCount()
       const column = model.getLineMaxColumn(lineNumber)
       finalQueryStartOffset = model.getOffsetAt({ lineNumber, column })
@@ -738,6 +813,7 @@ export const EditorProvider: React.FC = ({ children }) => {
         addBuffer,
         deleteBuffer,
         archiveBuffer,
+        duplicateNotebook,
         updateBuffer,
         updateBuffersPositions,
         setTemporaryBuffer,
diff --git a/src/providers/LocalStorageProvider/types.ts b/src/providers/LocalStorageProvider/types.ts
index 144476236..3c7ca8b1e 100644
--- a/src/providers/LocalStorageProvider/types.ts
+++ b/src/providers/LocalStorageProvider/types.ts
@@ -2,6 +2,9 @@ export type ProviderSettings = {
   apiKey: string
   enabledModels: string[]
   grantSchemaAccess: boolean
+  // Optional for back-compat; missing fields default to denied.
+  read?: boolean
+  write?: boolean
 }
 
 export type CustomProviderDefinition = {
@@ -12,6 +15,8 @@ export type CustomProviderDefinition = {
   contextWindow: number
   models: string[]
   grantSchemaAccess?: boolean
+  read?: boolean
+  write?: boolean
 }
 
 export type AiAssistantSettings = {
diff --git a/src/providers/MCPBridgeProvider/PairingConsentModal.tsx b/src/providers/MCPBridgeProvider/PairingConsentModal.tsx
new file mode 100644
index 000000000..6f83b53df
--- /dev/null
+++ b/src/providers/MCPBridgeProvider/PairingConsentModal.tsx
@@ -0,0 +1,350 @@
+import React, { useEffect, useState } from "react"
+import styled from "styled-components"
+import {
+  PlugsConnectedIcon,
+  PlugsIcon,
+  ShieldCheckIcon,
+  WarningIcon,
+} from "@phosphor-icons/react"
+import { AlertDialog } from "../../components/AlertDialog"
+import { Overlay } from "../../components/Overlay"
+import { Button, LoadingSpinner } from "../../components"
+import { MAX_RECONNECT_ATTEMPTS } from "../../utils/mcp/MCPBridgeClient"
+import type { Permissions } from "../../utils/tools/permissions"
+import { PermissionsSection } from "../../scenes/Footer/MCPBridgeStatus/PermissionsSection"
+
+const CONNECT_HOOK = "mcp-pair-consent-connect"
+
+const StyledContent = styled(AlertDialog.Content)`
+  background-color: ${({ theme }) => theme.color.backgroundDarker};
+  border: 1px solid ${({ theme }) => theme.color.selection};
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+`
+
+const Hero = styled.div`
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+  padding: 2.4rem 2.4rem 1.6rem;
+  gap: 1.2rem;
+`
+
+const IconBadge = styled.div<{ $tone?: "neutral" | "success" }>`
+  width: 4.8rem;
+  height: 4.8rem;
+  border-radius: 0.8rem;
+  border: 1px solid
+    ${({ theme, $tone }) =>
+      $tone === "success" ? theme.color.green : theme.color.pinkPrimary};
+  color: ${({ theme, $tone }) =>
+    $tone === "success" ? theme.color.green : theme.color.pinkPrimary};
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+`
+
+const Title = styled(AlertDialog.Title)`
+  margin: 0;
+  font-size: 1.8rem;
+  font-weight: 600;
+  color: ${({ theme }) => theme.color.foreground};
+`
+
+const Lede = styled(AlertDialog.Description)`
+  margin: 0;
+  color: ${({ theme }) => theme.color.gray2};
+  line-height: 1.5;
+  font-size: 1.4rem;
+`
+
+const Body = styled.div`
+  padding: 0 2.4rem 1.6rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1.6rem;
+`
+
+const Fields = styled.dl`
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 1.2rem;
+  margin: 0;
+  padding: 1.6rem;
+  background: ${({ theme }) => theme.color.backgroundDarker};
+  border: 1px solid ${({ theme }) => theme.color.selection};
+  border-radius: 0.6rem;
+
+  @media (min-width: 32em) {
+    grid-template-columns: max-content 1fr;
+    column-gap: 2rem;
+    row-gap: 1rem;
+    align-items: baseline;
+  }
+
+  dt {
+    font-size: 1.1rem;
+    color: ${({ theme }) => theme.color.gray2};
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    font-weight: 600;
+    margin: 0;
+  }
+
+  dd {
+    margin: 0;
+    font-family: ${({ theme }) => theme.fontMonospace};
+    font-size: 1.3rem;
+    color: ${({ theme }) => theme.color.foreground};
+    word-break: break-all;
+    line-height: 1.5;
+  }
+`
+
+const TrustNote = styled.div`
+  display: flex;
+  align-items: flex-start;
+  gap: 0.5rem;
+  color: ${({ theme }) => theme.color.gray2};
+
+  svg {
+    flex-shrink: 0;
+    color: ${({ theme }) => theme.color.green};
+  }
+
+  strong {
+    color: ${({ theme }) => theme.color.foreground};
+    font-weight: 600;
+  }
+`
+
+const StatusRow = styled.div<{ $tone: "info" | "danger" }>`
+  display: flex;
+  align-items: flex-start;
+  margin-right: auto;
+  gap: 0.8rem;
+  width: 100%;
+  background: ${({ theme, $tone }) =>
+    $tone === "danger" ? `${theme.color.red}1f` : theme.color.backgroundDarker};
+  color: ${({ theme, $tone }) =>
+    $tone === "danger" ? theme.color.foreground : theme.color.gray2};
+
+  padding: 0.8rem 2.4rem;
+
+  svg {
+    flex-shrink: 0;
+    color: ${({ theme, $tone }) =>
+      $tone === "danger" ? theme.color.red : theme.color.pinkPrimary};
+    margin-top: 0.2rem;
+  }
+
+  strong {
+    color: ${({ theme }) => theme.color.foreground};
+    font-weight: 600;
+  }
+`
+
+const StatusText = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+  min-width: 0;
+  line-height: 1.4;
+`
+
+const StatusDetail = styled.span`
+  font-size: 1.2rem;
+  color: ${({ theme }) => theme.color.gray2};
+  word-break: break-word;
+`
+
+const Actions = styled.div`
+  display: flex;
+  gap: 0.8rem;
+  justify-content: flex-end;
+  padding: 2rem 2.4rem 2.4rem;
+
+  @media (max-width: 28em) {
+    flex-direction: column-reverse;
+
+    > * {
+      width: 100%;
+    }
+  }
+`
+
+type Props = {
+  pending: { url: string; token: string } | null
+  isConnecting: boolean
+  succeeded: boolean
+  retryAttempt: number
+  error: string | null
+  permissions: Permissions
+  onConnect: (committedPermissions: Permissions) => void
+  onCancel: () => void
+}
+
+export const PairingConsentModal: React.FC<Props> = ({
+  pending,
+  isConnecting,
+  succeeded,
+  retryAttempt,
+  error,
+  permissions,
+  onConnect,
+  onCancel,
+}) => {
+  const [pendingPermissions, setPendingPermissions] = useState<Permissions>(
+    () => permissions,
+  )
+  useEffect(() => {
+    if (pending) setPendingPermissions(permissions)
+  }, [pending])
+  const handleOpenAutoFocus = (e: Event) => {
+    e.preventDefault()
+    const root = e.currentTarget as HTMLElement | null
+    const target = root?.querySelector<HTMLButtonElement>(
+      `[data-hook="${CONNECT_HOOK}"]`,
+    )
+    target?.focus()
+  }
+
+  const handleConnectClick = () => {
+    if (isConnecting) return
+    onConnect(pendingPermissions)
+  }
+
+  return (
+    <AlertDialog.Root open={pending !== null}>
+      <AlertDialog.Portal>
+        <Overlay primitive={AlertDialog.Overlay} />
+        <StyledContent
+          onOpenAutoFocus={handleOpenAutoFocus}
+          onEscapeKeyDown={(e) => {
+            if (isConnecting) e.preventDefault()
+          }}
+        >
+          <Hero>
+            <IconBadge
+              $tone={succeeded ? "success" : "neutral"}
+              data-hook={
+                succeeded ? "mcp-pair-consent-success-badge" : undefined
+              }
+            >
+              {succeeded ? (
+                <PlugsConnectedIcon size={28} weight="duotone" />
+              ) : (
+                <PlugsIcon size={28} weight="duotone" />
+              )}
+            </IconBadge>
+            <Title>
+              {succeeded ? "MCP Bridge connected" : "Connect to MCP Bridge?"}
+            </Title>
+            <Lede>
+              {succeeded
+                ? "You can track the connection status from the bottom bar."
+                : "An external coding agent is asking to pair with this Web Console. Once connected, it can read and edit notebooks, run SQL, and inspect schemas on your behalf."}
+            </Lede>
+          </Hero>
+
+          {!succeeded && (
+            <Body>
+              <Fields>
+                <dt>WebSocket URL:</dt>
+                <dd data-hook="mcp-pair-consent-ws">{pending?.url ?? ""}</dd>
+                <dt>Token:</dt>
+                <dd data-hook="mcp-pair-consent-token">
+                  {pending?.token ?? ""}
+                </dd>
+              </Fields>
+
+              <PermissionsSection
+                value={pendingPermissions}
+                onChange={setPendingPermissions}
+                disabled={isConnecting}
+              />
+
+              <TrustNote>
+                <ShieldCheckIcon size={16} weight="duotone" />
+                <span>
+                  <strong>Loopback only:</strong> The bridge runs on your
+                  machine and never leaves it. Every action runs through your
+                  already-authenticated console session.
+                </span>
+              </TrustNote>
+            </Body>
+          )}
+
+          {!succeeded && isConnecting && (
+            <StatusRow
+              $tone="info"
+              data-hook="mcp-pair-consent-connecting"
+              role="status"
+              aria-live="polite"
+            >
+              <LoadingSpinner size="16px" />
+              <StatusText>
+                <span>Establishing WebSocket connection...</span>
+                {/* -1 on both sides so the counter shows retries-allowed,
+                    not total attempts (the first attempt isn't a retry). */}
+                {retryAttempt > 1 && (
+                  <StatusDetail data-hook="mcp-pair-consent-retries">
+                    (Retry {retryAttempt - 1} of {MAX_RECONNECT_ATTEMPTS - 1})
+                  </StatusDetail>
+                )}
+              </StatusText>
+            </StatusRow>
+          )}
+
+          {!succeeded && !isConnecting && (error || retryAttempt > 0) && (
+            <StatusRow
+              $tone="danger"
+              data-hook="mcp-pair-consent-error"
+              role="alert"
+            >
+              <WarningIcon size={16} weight="duotone" />
+              <StatusText>
+                <strong>Could not connect to MCP bridge</strong>
+                <StatusDetail>
+                  {error ??
+                    `Bridge stopped responding after ${MAX_RECONNECT_ATTEMPTS} attempts. Click Try again, or ask your coding agent for a fresh deep link.`}
+                </StatusDetail>
+              </StatusText>
+            </StatusRow>
+          )}
+
+          <Actions>
+            <AlertDialog.Cancel asChild>
+              <Button
+                skin="secondary"
+                onClick={onCancel}
+                data-hook="mcp-pair-consent-cancel"
+              >
+                {succeeded ? "Dismiss" : "Cancel"}
+              </Button>
+            </AlertDialog.Cancel>
+            {!succeeded && (
+              <AlertDialog.Action asChild>
+                <Button
+                  skin="primary"
+                  onClick={handleConnectClick}
+                  disabled={isConnecting}
+                  data-hook={CONNECT_HOOK}
+                >
+                  {isConnecting
+                    ? "Connecting…"
+                    : error || retryAttempt > 0
+                      ? "Try again"
+                      : "Connect"}
+                </Button>
+              </AlertDialog.Action>
+            )}
+          </Actions>
+        </StyledContent>
+      </AlertDialog.Portal>
+    </AlertDialog.Root>
+  )
+}
diff --git a/src/providers/MCPBridgeProvider/index.tsx b/src/providers/MCPBridgeProvider/index.tsx
new file mode 100644
index 000000000..540378a5a
--- /dev/null
+++ b/src/providers/MCPBridgeProvider/index.tsx
@@ -0,0 +1,495 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react"
+import { MCPBridgeClient } from "../../utils/mcp/MCPBridgeClient"
+import type { MCPBridgeClientStatus } from "../../utils/mcp/MCPBridgeClient"
+import { dispatchMCPTool } from "../../utils/mcp/dispatchMCPTool"
+import type {
+  FreshnessGate,
+  StateFreshness,
+} from "../../utils/mcp/dispatchMCPTool"
+import { mcpTools } from "../../utils/tools/tools"
+import { EXPECTED_BRIDGE_VERSION } from "../../utils/mcp/protocolVersion"
+import type { ToolCallMessage } from "../../utils/mcp/types"
+import {
+  clearLegacyLocalStorage,
+  clearPendingPair,
+  markPendingPairConsented,
+  readPendingPair,
+  readPermissions,
+  writePendingPair,
+  writePermissions,
+} from "../../utils/mcp/mcpBridgeStorage"
+import {
+  DEFAULT_GRANTED,
+  normalizePermissions,
+  type Permissions,
+} from "../../utils/tools/permissions"
+import { consumePendingPairFromUrl } from "../../utils/mcp/consumePendingPair"
+import { QuestContext } from "../QuestProvider"
+import { on as onUserAction, onUserEdit } from "../../utils/notebookAIBridge"
+import type { ToolDefinition } from "../../utils/ai/types"
+import {
+  applyUserActionToDigest,
+  createEmptyDigest,
+} from "../AIConversationProvider/userActionDigest"
+import type { UserActionDigest } from "../AIConversationProvider/types"
+import { useBridgeToolRunner } from "./useBridgeToolRunner"
+import { PairingConsentModal } from "./PairingConsentModal"
+
+export type MCPBridgeContextValue = {
+  status: MCPBridgeClientStatus
+  latencyMs: number | null
+  lastError: string | null
+  retryAttempt: number
+  url: string | null
+  token: string | null
+  connect: (url: string, token: string) => void
+  disconnect: () => void
+  permissions: Permissions
+  setPermissions: (next: Permissions) => void
+}
+
+const defaultContext: MCPBridgeContextValue = {
+  status: "disconnected",
+  latencyMs: null,
+  lastError: null,
+  retryAttempt: 0,
+  url: null,
+  token: null,
+  connect: () => undefined,
+  disconnect: () => undefined,
+  permissions: DEFAULT_GRANTED,
+  setPermissions: () => undefined,
+}
+
+const MCPBridgeContext = createContext<MCPBridgeContextValue>(defaultContext)
+
+export const useMCPBridge = () => useContext(MCPBridgeContext)
+
+// Sent in `hello` so the bridge can detect drift against its bundled
+// tool list (Codex caches the initial tools/list and never refetches).
+const toWireSchema = (t: ToolDefinition) => ({
+  name: t.name,
+  description: t.description ?? "",
+  inputSchema: t.inputSchema as Record<string, unknown>,
+})
+const buildToolListForHello = () => mcpTools.map(toWireSchema)
+
+const consoleOrigin =
+  typeof window !== "undefined" ? window.location.origin : "unknown"
+
+const CONSENT_SUCCESS_AUTOCLOSE_MS = 3_000
+
+export const MCPBridgeProvider: React.FC<{ children: React.ReactNode }> = ({
+  children,
+}) => {
+  const { quest } = useContext(QuestContext)
+  const [url, setUrl] = useState<string | null>(null)
+  const [token, setToken] = useState<string | null>(null)
+  const [status, setStatus] = useState<MCPBridgeClientStatus>("disconnected")
+  const [latencyMs, setLatencyMs] = useState<number | null>(null)
+  const [lastError, setLastError] = useState<string | null>(null)
+  const [permissions, setPermissionsState] = useState<Permissions>(() =>
+    readPermissions(),
+  )
+  const permissionsRef = useRef<Permissions>(permissions)
+  permissionsRef.current = permissions
+  const permissionsDirtyRef = useRef<boolean>(false)
+  const [retryAttempt, setRetryAttempt] = useState(0)
+  const [pendingConsent, setPendingConsent] = useState<{
+    url: string
+    token: string
+  } | null>(null)
+  const [consentInFlight, setConsentInFlight] = useState(false)
+  const [consentSucceeded, setConsentSucceeded] = useState(false)
+  // Bumped on every Connect click so "Try again" re-runs the construction
+  // effect even when {url,token} are unchanged; otherwise a wedged client
+  // (consecutiveFailedAttempts pinned at the cap) is never rebuilt.
+  const [connectAttempt, setConnectAttempt] = useState(0)
+
+  const freshnessRef = useRef<StateFreshness>("unfetched")
+  const freshBufferRef = useRef<number | null>(null)
+  const freshnessGate: FreshnessGate = useMemo(
+    () => ({
+      get: () => freshnessRef.current,
+      set: (next) => {
+        freshnessRef.current = next
+      },
+      getReadBuffer: () => freshBufferRef.current,
+      setReadBuffer: (bufferId) => {
+        freshBufferRef.current = bufferId
+      },
+    }),
+    [],
+  )
+
+  const digestRef = useRef<UserActionDigest>(createEmptyDigest())
+  const getDigest = useCallback(() => digestRef.current, [])
+  // Snapshot-and-reset so the same user actions aren't re-emitted across
+  // successive tool results.
+  const consumeDigest = useCallback(() => {
+    const snapshot = digestRef.current
+    digestRef.current = createEmptyDigest()
+    return snapshot
+  }, [])
+
+  const { modelToolsClient, metaToolContext } = useBridgeToolRunner(
+    getDigest,
+    consumeDigest,
+  )
+
+  const validateSql = useCallback(
+    (sql: string) => quest.validateQuery(sql),
+    [quest],
+  )
+
+  // Refs let the dispatcher read live values outside React's render flow.
+  const permissionsRefs = useMemo(
+    () => ({
+      get: () => permissionsRef.current,
+      consumeDirty: (): boolean => {
+        const wasDirty = permissionsDirtyRef.current
+        permissionsDirtyRef.current = false
+        return wasDirty
+      },
+    }),
+    [],
+  )
+
+  const dispatchCtxRef = useRef({
+    modelToolsClient,
+    freshness: freshnessGate,
+    metaToolContext,
+    permissions: permissionsRefs,
+    validateSql,
+  })
+  dispatchCtxRef.current = {
+    modelToolsClient,
+    freshness: freshnessGate,
+    metaToolContext,
+    permissions: permissionsRefs,
+    validateSql,
+  }
+
+  const inflightAbortersRef = useRef(new Map<string, AbortController>())
+
+  // Distinguishes a revocation-driven abort from other reasons so the
+  // toolCall handler sends an explicit error back to the bridge instead
+  // of silently letting the agent time out.
+  const PERMISSIONS_REVOKED_REASON = "permissions_revoked"
+
+  const clientRef = useRef<MCPBridgeClient | null>(null)
+
+  useEffect(() => {
+    const cleanupUserActionListener = onUserAction("user-action", (evt) => {
+      digestRef.current = applyUserActionToDigest(digestRef.current, evt)
+      freshnessRef.current = "stale"
+    })
+    const cleanupUserEditListener = onUserEdit(() => {
+      freshnessRef.current = "stale"
+    })
+    return () => {
+      cleanupUserActionListener()
+      cleanupUserEditListener()
+    }
+  }, [])
+
+  useEffect(() => {
+    if (!url || !token) return
+    const client = new MCPBridgeClient({
+      url,
+      token,
+      tools: buildToolListForHello(),
+      consoleOrigin,
+      permissions: permissionsRef.current,
+    })
+    clientRef.current = client
+
+    const offStatus = client.on("status", (s) => setStatus(s))
+    const offLatency = client.on("latency", (ms) => setLatencyMs(ms))
+    const offError = client.on("error", (err) => setLastError(err.message))
+    const offRetry = client.on("retryAttempt", (n) => setRetryAttempt(n))
+    const offHelloAck = client.on("helloAck", () => {
+      // Promote pending → consented so a same-tab refresh silently restores.
+      markPendingPairConsented()
+      setLastError(null)
+    })
+
+    const offToolCall = client.on("toolCall", (call: ToolCallMessage) => {
+      const aborter = new AbortController()
+      inflightAbortersRef.current.set(call.requestId, aborter)
+      const deadlineTimer =
+        typeof call.deadlineMs === "number" && call.deadlineMs > 0
+          ? window.setTimeout(
+              () => aborter.abort("deadline_exceeded"),
+              call.deadlineMs,
+            )
+          : null
+      const sendRevokedErrorIfNeeded = (): boolean => {
+        if (!aborter.signal.aborted) return false
+        if (aborter.signal.reason === PERMISSIONS_REVOKED_REASON) {
+          client.sendToolResult({
+            v: EXPECTED_BRIDGE_VERSION,
+            type: "tool_result",
+            requestId: call.requestId,
+            content: [
+              {
+                type: "text",
+                text: "PERMISSION_REVOKED: the user revoked permissions mid-call. Re-check current permissions before retrying.",
+              },
+            ],
+            isError: true,
+          })
+        }
+        return true
+      }
+      void (async () => {
+        try {
+          const result = await dispatchMCPTool(call, {
+            ...dispatchCtxRef.current,
+            signal: aborter.signal,
+          })
+          if (sendRevokedErrorIfNeeded()) return
+          client.sendToolResult({
+            v: EXPECTED_BRIDGE_VERSION,
+            type: "tool_result",
+            requestId: call.requestId,
+            content: result.content,
+            isError: result.isError ?? false,
+          })
+        } catch (err) {
+          if (sendRevokedErrorIfNeeded()) return
+          const message =
+            err instanceof Error ? err.message : "tool dispatch failed"
+          client.sendToolResult({
+            v: EXPECTED_BRIDGE_VERSION,
+            type: "tool_result",
+            requestId: call.requestId,
+            content: [{ type: "text", text: `dispatch_error: ${message}` }],
+            isError: true,
+          })
+        } finally {
+          if (deadlineTimer !== null) window.clearTimeout(deadlineTimer)
+          inflightAbortersRef.current.delete(call.requestId)
+        }
+      })()
+    })
+
+    const offCancel = client.on("cancel", (msg) => {
+      const aborter = inflightAbortersRef.current.get(msg.requestId)
+      if (aborter) aborter.abort()
+    })
+
+    client.connect()
+
+    return () => {
+      offStatus()
+      offLatency()
+      offError()
+      offRetry()
+      offHelloAck()
+      offToolCall()
+      offCancel()
+      for (const a of Array.from(inflightAbortersRef.current.values())) {
+        a.abort()
+      }
+      inflightAbortersRef.current.clear()
+      client.disconnect()
+      if (clientRef.current === client) clientRef.current = null
+    }
+  }, [url, token, connectAttempt])
+
+  const connect = useCallback((nextUrl: string, nextToken: string) => {
+    setRetryAttempt(0)
+    setLastError(null)
+    setConnectAttempt((n) => n + 1)
+    setUrl(nextUrl)
+    setToken(nextToken)
+    writePendingPair({
+      url: nextUrl,
+      token: nextToken,
+      receivedAt: Date.now(),
+    })
+  }, [])
+
+  const setPermissions = useCallback((nextRaw: Permissions) => {
+    const next = normalizePermissions(nextRaw)
+    const prev = permissionsRef.current
+    const isDowngrade =
+      (prev.grantSchemaAccess && !next.grantSchemaAccess) ||
+      (prev.read && !next.read) ||
+      (prev.write && !next.write)
+    writePermissions(next)
+    permissionsDirtyRef.current = true
+    setPermissionsState(next)
+    clientRef.current?.setPermissions(next)
+    // Calls already past the dispatcher gate keep running; abort them so a
+    // revoked write doesn't complete and feed a stale success to the agent.
+    if (isDowngrade) {
+      for (const aborter of Array.from(inflightAbortersRef.current.values())) {
+        aborter.abort(PERMISSIONS_REVOKED_REASON)
+      }
+    }
+  }, [])
+
+  const disconnect = useCallback(() => {
+    if (clientRef.current) {
+      clientRef.current.disconnect("user_disconnect")
+    }
+    clearPendingPair()
+    setUrl(null)
+    setToken(null)
+    setStatus("disconnected")
+    setLatencyMs(null)
+    setLastError(null)
+    setRetryAttempt(0)
+    digestRef.current = createEmptyDigest()
+    freshnessRef.current = "unfetched"
+  }, [])
+
+  useEffect(() => {
+    clearLegacyLocalStorage()
+
+    if (typeof window !== "undefined") {
+      consumePendingPairFromUrl()
+    }
+    const pair = readPendingPair()
+    if (!pair) return
+    if (pair.consented) {
+      setConnectAttempt((n) => n + 1)
+      setUrl(pair.url)
+      setToken(pair.token)
+    } else {
+      setPendingConsent({ url: pair.url, token: pair.token })
+    }
+  }, [])
+
+  // Distinguishes the initial "disconnected" (before Connect commits)
+  // from the terminal "gave up" disconnected.
+  const attemptSawActiveRef = useRef(false)
+
+  useEffect(() => {
+    if (!pendingConsent || !consentInFlight) return
+    if (status === "connected") {
+      attemptSawActiveRef.current = false
+      setConsentInFlight(false)
+      setConsentSucceeded(true)
+      markPendingPairConsented()
+    } else if (status === "connecting" || status === "reconnecting") {
+      attemptSawActiveRef.current = true
+    } else if (status === "disconnected" && attemptSawActiveRef.current) {
+      attemptSawActiveRef.current = false
+      setConsentInFlight(false)
+    }
+  }, [status, pendingConsent, consentInFlight])
+
+  // After give-up against a dead bridge, drop a consented pair so a refresh
+  // doesn't restart an infinite-retry loop. Pre-consent pairs stay — the
+  // modal's "Try again" needs them.
+  useEffect(() => {
+    if (status !== "disconnected") return
+    if (!url || !token) return
+    if (!lastError) return
+    const stored = readPendingPair()
+    if (stored?.consented) clearPendingPair()
+  }, [status, url, token, lastError])
+
+  // Don't flip consentSucceeded inside the timer: React 17 doesn't batch
+  // setStates in setTimeout, and Radix keeps the modal mounted during its
+  // 0.25s exit animation, so a flip would briefly swap success → default.
+  useEffect(() => {
+    if (!consentSucceeded) return
+    const t = setTimeout(() => {
+      setPendingConsent(null)
+    }, CONSENT_SUCCESS_AUTOCLOSE_MS)
+    return () => clearTimeout(t)
+  }, [consentSucceeded])
+
+  const acceptPendingConsent = useCallback(
+    (committedPermissions: Permissions) => {
+      if (!pendingConsent || consentInFlight) return
+      // Order matters: the about-to-be-constructed client reads
+      // permissionsRef.current in its initial hello.
+      setPermissions(committedPermissions)
+      attemptSawActiveRef.current = false
+      setConsentInFlight(true)
+      setConsentSucceeded(false)
+      setLastError(null)
+      setRetryAttempt(0)
+      setConnectAttempt((n) => n + 1)
+      setUrl(pendingConsent.url)
+      setToken(pendingConsent.token)
+    },
+    [pendingConsent, consentInFlight, setPermissions],
+  )
+
+  const declinePendingConsent = useCallback(() => {
+    // In the success state, Dismiss should NOT disconnect — the user
+    // just confirmed connection.
+    if (consentSucceeded) {
+      setPendingConsent(null)
+      setConsentSucceeded(false)
+      return
+    }
+    setPendingConsent(null)
+    setConsentInFlight(false)
+    if (clientRef.current) {
+      clientRef.current.disconnect("user_disconnect")
+      clientRef.current = null
+    }
+    setUrl(null)
+    setToken(null)
+    setRetryAttempt(0)
+    clearPendingPair()
+  }, [consentSucceeded])
+
+  const value = useMemo<MCPBridgeContextValue>(
+    () => ({
+      status,
+      latencyMs,
+      lastError,
+      retryAttempt,
+      url,
+      token,
+      connect,
+      disconnect,
+      permissions,
+      setPermissions,
+    }),
+    [
+      status,
+      latencyMs,
+      lastError,
+      retryAttempt,
+      url,
+      token,
+      connect,
+      disconnect,
+      permissions,
+      setPermissions,
+    ],
+  )
+
+  return (
+    <MCPBridgeContext.Provider value={value}>
+      {children}
+      <PairingConsentModal
+        pending={pendingConsent}
+        isConnecting={consentInFlight}
+        succeeded={consentSucceeded}
+        retryAttempt={retryAttempt}
+        error={consentInFlight ? null : lastError}
+        permissions={permissions}
+        onConnect={acceptPendingConsent}
+        onCancel={declinePendingConsent}
+      />
+    </MCPBridgeContext.Provider>
+  )
+}
diff --git a/src/providers/MCPBridgeProvider/useBridgeToolRunner.ts b/src/providers/MCPBridgeProvider/useBridgeToolRunner.ts
new file mode 100644
index 000000000..5cdaf40f1
--- /dev/null
+++ b/src/providers/MCPBridgeProvider/useBridgeToolRunner.ts
@@ -0,0 +1,74 @@
+import { useContext, useMemo } from "react"
+import { useSelector } from "react-redux"
+import { selectors } from "../../store"
+import { QuestContext } from "../QuestProvider"
+import { createModelToolsClient } from "../../utils/aiAssistant"
+import { useEditor } from "../EditorProvider"
+import type { MetaToolContext } from "../../utils/mcp/metaResolvers"
+import type { WorkspaceInfo } from "../../utils/executeAIFlow"
+import type { UserActionDigest } from "../AIConversationProvider/types"
+
+export const useBridgeToolRunner = (
+  getDigest: () => UserActionDigest | null,
+  consumeDigest: () => UserActionDigest | null,
+) => {
+  const { quest } = useContext(QuestContext)
+  const tables = useSelector(selectors.query.getTables)
+  const { activeBuffer, buffers } = useEditor()
+
+  const modelToolsClient = useMemo(
+    () => createModelToolsClient(quest, tables),
+    [quest, tables],
+  )
+
+  const workspace: WorkspaceInfo | null = useMemo(() => {
+    const notebooks = buffers
+      .filter((b) => !!b.notebookViewState && typeof b.id === "number")
+      .map((b) => ({
+        buffer_id: b.id as number,
+        label: b.label,
+        archived: !!b.archived,
+      }))
+    if (notebooks.length === 0 && typeof activeBuffer.id !== "number") {
+      return null
+    }
+    return {
+      notebooks,
+      ...(typeof activeBuffer.id === "number"
+        ? {
+            active: {
+              buffer_id: activeBuffer.id,
+              label: activeBuffer.label,
+              kind: activeBuffer.notebookViewState
+                ? ("notebook" as const)
+                : activeBuffer.metricsViewState
+                  ? ("metrics" as const)
+                  : activeBuffer.editorViewState
+                    ? ("sql" as const)
+                    : ("other" as const),
+            },
+          }
+        : {}),
+    }
+  }, [buffers, activeBuffer])
+
+  const activeNotebookBufferId = useMemo<number | null>(
+    () =>
+      activeBuffer.notebookViewState && typeof activeBuffer.id === "number"
+        ? activeBuffer.id
+        : null,
+    [activeBuffer],
+  )
+
+  const metaToolContext: MetaToolContext = useMemo(
+    () => ({
+      getActiveBufferId: () => activeNotebookBufferId,
+      getWorkspace: () => workspace,
+      getDigest,
+      consumeDigest,
+    }),
+    [activeNotebookBufferId, workspace, getDigest, consumeDigest],
+  )
+
+  return { modelToolsClient, metaToolContext }
+}
diff --git a/src/providers/QuestProvider/index.tsx b/src/providers/QuestProvider/index.tsx
index ab8aca240..115667b47 100644
--- a/src/providers/QuestProvider/index.tsx
+++ b/src/providers/QuestProvider/index.tsx
@@ -41,7 +41,7 @@ import {
 import { QueryExecutionConfirmDialog } from "../../components/QueryExecutionConfirmDialog"
 
 const questClient = new QuestDB.Client()
-const questExecution = new QuestDB.QueryExecutionManager(questClient)
+const questExecution = new QuestDB.QueryExecutionManager()
 
 type ContextProps = {
   quest: QuestDB.Client
diff --git a/src/scenes/Console/index.tsx b/src/scenes/Console/index.tsx
index 851d001f6..a108e666a 100644
--- a/src/scenes/Console/index.tsx
+++ b/src/scenes/Console/index.tsx
@@ -8,7 +8,6 @@ import Editor from "../Editor"
 import Result from "../Result"
 import Schema from "../Schema"
 import { useScreenSize } from "../../hooks"
-import { ZeroState } from "./zero-state"
 import { useLocalStorage } from "../../providers/LocalStorageProvider"
 import { StoreKey } from "../../utils/localStorage/types"
 import { useSelector } from "react-redux"
@@ -52,6 +51,13 @@ const Top = styled.div`
   overflow: hidden;
 `
 
+const ContentArea = styled.div`
+  display: flex;
+  flex: 1;
+  height: 100%;
+  min-width: 0;
+`
+
 const Bottom = styled.div`
   display: flex;
   height: 100%;
@@ -61,11 +67,15 @@ const Bottom = styled.div`
 
 const Tab = styled.div`
   display: flex;
-  width: calc(100% - 4.5rem);
+  width: 100%;
   height: 100%;
   overflow: auto;
 `
 
+const SidebarSpacer = styled.div`
+  flex: 1;
+`
+
 const SidePanelRight = styled.div`
   background: ${color("chatBackground")};
   height: 100%;
@@ -110,7 +120,6 @@ const Console = () => {
 
   const [resultViewMode, setResultViewMode] = useState<ResultViewMode>("grid")
   const resultRef = React.useRef<HTMLDivElement>(null)
-  const zeroStateRef = React.useRef<HTMLDivElement>(null)
   const importRef = React.useRef<HTMLDivElement>(null)
   const horizontalSplitterRef = React.useRef<AllotmentHandle>(null)
 
@@ -118,21 +127,17 @@ const Console = () => {
     if (resultRef.current) {
       resultRef.current.style.display = panel === "result" ? "flex" : "none"
     }
-    if (zeroStateRef.current) {
-      zeroStateRef.current.style.display =
-        panel === "zeroState" ? "flex" : "none"
-    }
     if (importRef.current) {
       importRef.current.style.display = panel === "import" ? "flex" : "none"
     }
   }
 
   useEffect(() => {
-    if (resultRef.current && result) {
-      dispatch(actions.console.setActiveBottomPanel("result"))
-    } else if (zeroStateRef.current) {
-      dispatch(actions.console.setActiveBottomPanel("zeroState"))
-    }
+    dispatch(
+      actions.console.setActiveBottomPanel(
+        resultRef.current && result ? "result" : "zeroState",
+      ),
+    )
   }, [result])
 
   useEffect(() => {
@@ -151,176 +156,176 @@ const Console = () => {
       >
         <Allotment.Pane>
           <MainContent>
-            <Allotment
-              vertical
-              onDragEnd={(sizes) => {
-                updateSettings(StoreKey.RESULTS_SPLITTER_BASIS, sizes[0])
-              }}
-            >
-              <Allotment.Pane
-                minSize={100}
-                preferredSize={resultsSplitterBasis}
-              >
-                <Top>
-                  <Sidebar align="top">
-                    {!sm && (
-                      <Tooltip
-                        placement="right"
-                        content={`${isDataSourcesPanelOpen ? "Hide" : "Show"} data sources`}
-                      >
-                        <Navigation
-                          data-hook="tables-panel-button"
-                          direction="left"
-                          onClick={() => {
-                            if (isDataSourcesPanelOpen) {
-                              void trackEvent(ConsoleEvent.SCHEMA_OPEN)
-                              updateLeftPanelState({
-                                type: null,
-                                width: leftPanelState.width,
-                              })
-                            } else {
-                              void trackEvent(ConsoleEvent.SCHEMA_CLOSE)
-                              updateLeftPanelState({
-                                type: LeftPanelType.DATASOURCES,
-                                width: leftPanelState.width,
-                              })
-                            }
-                          }}
-                          selected={isDataSourcesPanelOpen}
-                        >
-                          <Database2 size={BUTTON_ICON_SIZE} />
-                        </Navigation>
-                      </Tooltip>
-                    )}
-                    <Tooltip
-                      placement="right"
-                      content={
-                        isSearchPanelOpen
-                          ? "Hide search in tabs"
-                          : "Search in tabs"
-                      }
+            <ContentArea>
+              <Sidebar align="top">
+                {!sm && (
+                  <Tooltip
+                    placement="right"
+                    content={`${isDataSourcesPanelOpen ? "Hide" : "Show"} data sources`}
+                  >
+                    <Navigation
+                      data-hook="tables-panel-button"
+                      direction="left"
+                      onClick={() => {
+                        if (isDataSourcesPanelOpen) {
+                          void trackEvent(ConsoleEvent.SCHEMA_OPEN)
+                          updateLeftPanelState({
+                            type: null,
+                            width: leftPanelState.width,
+                          })
+                        } else {
+                          void trackEvent(ConsoleEvent.SCHEMA_CLOSE)
+                          updateLeftPanelState({
+                            type: LeftPanelType.DATASOURCES,
+                            width: leftPanelState.width,
+                          })
+                        }
+                      }}
+                      selected={isDataSourcesPanelOpen}
                     >
+                      <Database2 size={BUTTON_ICON_SIZE} />
+                    </Navigation>
+                  </Tooltip>
+                )}
+                <Tooltip
+                  placement="right"
+                  content={
+                    isSearchPanelOpen ? "Hide search in tabs" : "Search in tabs"
+                  }
+                >
+                  <Navigation
+                    data-hook="search-panel-button"
+                    direction="left"
+                    onClick={() => {
+                      if (!isSearchPanelOpen) {
+                        void trackEvent(ConsoleEvent.SEARCH_OPEN)
+                      }
+                      setSearchPanelOpen(!isSearchPanelOpen)
+                    }}
+                    selected={isSearchPanelOpen}
+                  >
+                    <FileSearch size={BUTTON_ICON_SIZE} />
+                  </Navigation>
+                </Tooltip>
+                <SidebarSpacer />
+                {result &&
+                  viewModes.map(({ icon, mode, tooltipText }) => (
+                    <Tooltip key={mode} placement="right" content={tooltipText}>
                       <Navigation
-                        data-hook="search-panel-button"
+                        data-hook={`${mode}-panel-button`}
                         direction="left"
                         onClick={() => {
-                          if (!isSearchPanelOpen) {
-                            void trackEvent(ConsoleEvent.SEARCH_OPEN)
-                          }
-                          setSearchPanelOpen(!isSearchPanelOpen)
+                          const isActive =
+                            activeBottomPanel === "result" &&
+                            resultViewMode === mode
+                          void trackEvent(ConsoleEvent.PANEL_BOTTOM_SWITCH, {
+                            panel: isActive ? "zeroState" : mode,
+                          })
+                          dispatch(
+                            actions.console.setActiveBottomPanel(
+                              isActive ? "zeroState" : "result",
+                            ),
+                          )
+                          setResultViewMode(mode)
                         }}
-                        selected={isSearchPanelOpen}
+                        selected={
+                          activeBottomPanel === "result" &&
+                          resultViewMode === mode
+                        }
                       >
-                        <FileSearch size={BUTTON_ICON_SIZE} />
+                        {icon}
                       </Navigation>
                     </Tooltip>
-                  </Sidebar>
-                  <Allotment
-                    proportionalLayout={false}
-                    ref={horizontalSplitterRef}
-                    onDragEnd={(sizes) => {
-                      if (sizes[0] !== 0) {
-                        updateLeftPanelState({
-                          type: leftPanelState.type,
-                          width: sizes[0],
+                  ))}
+                <Tooltip
+                  placement="right"
+                  content={
+                    consoleConfig.readOnly
+                      ? "To use this feature, turn off read-only mode in the configuration file"
+                      : "Import files from CSV"
+                  }
+                >
+                  <PrimaryToggleButton
+                    readOnly={consoleConfig.readOnly}
+                    {...(!consoleConfig.readOnly && {
+                      onClick: () => {
+                        const isActive = activeBottomPanel === "import"
+                        void trackEvent(ConsoleEvent.PANEL_BOTTOM_SWITCH, {
+                          panel: isActive ? "zeroState" : "import",
                         })
-                      }
-                    }}
-                    snap
+                        dispatch(
+                          actions.console.setActiveBottomPanel(
+                            isActive ? "zeroState" : "import",
+                          ),
+                        )
+                      },
+                    })}
+                    selected={activeBottomPanel === "import"}
+                    data-hook="import-panel-button"
                   >
-                    <Allotment.Pane
-                      preferredSize={leftPanelState.width}
-                      visible={
-                        (isDataSourcesPanelOpen || isSearchPanelOpen) && !sm
-                      }
-                      minSize={320}
-                    >
-                      <Schema open={isDataSourcesPanelOpen} />
-                      <SearchPanel
-                        ref={searchPanelRef}
-                        open={isSearchPanelOpen}
-                      />
-                    </Allotment.Pane>
-                    <Allotment.Pane>
-                      <Editor />
-                    </Allotment.Pane>
-                  </Allotment>
-                </Top>
-              </Allotment.Pane>
-
-              <Allotment.Pane minSize={100}>
-                <Bottom>
-                  <Sidebar align="bottom">
-                    {result &&
-                      viewModes.map(({ icon, mode, tooltipText }) => (
-                        <Tooltip
-                          key={mode}
-                          placement="right"
-                          content={tooltipText}
-                        >
-                          <Navigation
-                            data-hook={`${mode}-panel-button`}
-                            direction="left"
-                            onClick={() => {
-                              void trackEvent(
-                                ConsoleEvent.PANEL_BOTTOM_SWITCH,
-                                {
-                                  panel: mode,
-                                },
-                              )
-                              dispatch(
-                                actions.console.setActiveBottomPanel("result"),
-                              )
-                              setResultViewMode(mode)
-                            }}
-                            selected={
-                              activeBottomPanel === "result" &&
-                              resultViewMode === mode
-                            }
-                          >
-                            {icon}
-                          </Navigation>
-                        </Tooltip>
-                      ))}
-                    <Tooltip
-                      placement="right"
-                      content={
-                        consoleConfig.readOnly
-                          ? "To use this feature, turn off read-only mode in the configuration file"
-                          : "Import files from CSV"
-                      }
+                    <ImportIcon size={BUTTON_ICON_SIZE} />
+                  </PrimaryToggleButton>
+                </Tooltip>
+              </Sidebar>
+              <Allotment
+                vertical
+                onDragEnd={(sizes) => {
+                  updateSettings(StoreKey.RESULTS_SPLITTER_BASIS, sizes[0])
+                }}
+              >
+                <Allotment.Pane
+                  minSize={100}
+                  preferredSize={resultsSplitterBasis}
+                >
+                  <Top>
+                    <Allotment
+                      proportionalLayout={false}
+                      ref={horizontalSplitterRef}
+                      onDragEnd={(sizes) => {
+                        if (sizes[0] !== 0) {
+                          updateLeftPanelState({
+                            type: leftPanelState.type,
+                            width: sizes[0],
+                          })
+                        }
+                      }}
+                      snap
                     >
-                      <PrimaryToggleButton
-                        readOnly={consoleConfig.readOnly}
-                        {...(!consoleConfig.readOnly && {
-                          onClick: () => {
-                            void trackEvent(ConsoleEvent.PANEL_BOTTOM_SWITCH, {
-                              panel: "import",
-                            })
-                            dispatch(
-                              actions.console.setActiveBottomPanel("import"),
-                            )
-                          },
-                        })}
-                        selected={activeBottomPanel === "import"}
-                        data-hook="import-panel-button"
+                      <Allotment.Pane
+                        preferredSize={leftPanelState.width}
+                        visible={
+                          (isDataSourcesPanelOpen || isSearchPanelOpen) && !sm
+                        }
+                        minSize={320}
                       >
-                        <ImportIcon size={BUTTON_ICON_SIZE} />
-                      </PrimaryToggleButton>
-                    </Tooltip>
-                  </Sidebar>
-                  <Tab ref={resultRef}>
-                    {result && <Result viewMode={resultViewMode} />}
-                  </Tab>
-                  <Tab ref={zeroStateRef}>
-                    <ZeroState />
-                  </Tab>
-                  <Tab ref={importRef}>
-                    <Import />
-                  </Tab>
-                </Bottom>
-              </Allotment.Pane>
-            </Allotment>
+                        <Schema open={isDataSourcesPanelOpen} />
+                        <SearchPanel
+                          ref={searchPanelRef}
+                          open={isSearchPanelOpen}
+                        />
+                      </Allotment.Pane>
+                      <Allotment.Pane>
+                        <Editor />
+                      </Allotment.Pane>
+                    </Allotment>
+                  </Top>
+                </Allotment.Pane>
+
+                <Allotment.Pane
+                  minSize={0}
+                  visible={activeBottomPanel !== "zeroState"}
+                >
+                  <Bottom>
+                    <Tab ref={resultRef}>
+                      {result && <Result viewMode={resultViewMode} />}
+                    </Tab>
+                    <Tab ref={importRef}>
+                      <Import />
+                    </Tab>
+                  </Bottom>
+                </Allotment.Pane>
+              </Allotment>
+            </ContentArea>
           </MainContent>
           <AIStatusIndicator />
         </Allotment.Pane>
diff --git a/src/scenes/Console/zero-state.tsx b/src/scenes/Console/zero-state.tsx
deleted file mode 100644
index 778c3b639..000000000
--- a/src/scenes/Console/zero-state.tsx
+++ /dev/null
@@ -1,42 +0,0 @@
-import React, { useContext, useEffect, useState } from "react"
-import styled from "styled-components"
-import { Start } from "../../modules/ZeroState/start"
-import { PaneContent, PaneWrapper } from "../../components"
-import * as QuestDB from "../../utils/questdb"
-import { QuestContext } from "../../providers"
-
-const StyledPaneContent = styled(PaneContent)`
-  align-items: center;
-  justify-content: center;
-`
-
-export const ZeroState = () => {
-  const { quest } = useContext(QuestContext)
-  const [loading, setLoading] = useState(true)
-  const [tables, setTables] = useState<QuestDB.Table[]>([])
-
-  const fetchTables = async () => {
-    try {
-      const response = await quest.showTables()
-      if (response && response.type === QuestDB.Type.DQL) {
-        setTables(response.data)
-      }
-    } catch (error) {
-      return
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  useEffect(() => {
-    void fetchTables()
-  }, [])
-
-  return (
-    <PaneWrapper>
-      <StyledPaneContent>
-        {!loading && tables.length <= 2 && <Start />}
-      </StyledPaneContent>
-    </PaneWrapper>
-  )
-}
diff --git a/src/scenes/Editor/AIChatWindow/AssistantMarkdown.tsx b/src/scenes/Editor/AIChatWindow/AssistantMarkdown.tsx
index 04c28c625..da474d33d 100644
--- a/src/scenes/Editor/AIChatWindow/AssistantMarkdown.tsx
+++ b/src/scenes/Editor/AIChatWindow/AssistantMarkdown.tsx
@@ -1,7 +1,6 @@
 import React, { memo, useEffect, useMemo, useRef } from "react"
 import styled from "styled-components"
-import ReactMarkdown from "react-markdown"
-import remarkGfm from "remark-gfm"
+import { SafeMarkdown } from "../../../components"
 import { LiteEditor } from "../../../components/LiteEditor"
 import type { OpenInEditorContent } from "./ChatMessages"
 import { color } from "../../../utils"
@@ -123,23 +122,11 @@ const MarkdownContent = styled.div`
   }
 `
 
+// Links are handled by SafeMarkdown's SafeLink. Chat keeps its own table/pre
+// wrappers and renders fenced code blocks through LiteEditor.
 const createComponents = (
   onOpenInEditor: React.RefObject<(content: OpenInEditorContent) => void>,
 ) => ({
-  a: ({ children, href, ...props }: React.ComponentProps<"a">) => (
-    <a
-      {...(typeof href === "string" && href.startsWith("http")
-        ? {
-            target: "_blank",
-            rel: "noopener noreferrer",
-          }
-        : {})}
-      href={href}
-      {...props}
-    >
-      {children}
-    </a>
-  ),
   table: ({ children, ...props }: React.ComponentProps<"table">) => (
     <div className="table-wrapper">
       <table {...props}>{children}</table>
@@ -197,9 +184,9 @@ export const AssistantMarkdown = memo(
 
     return (
       <MarkdownContent key={messageId}>
-        <ReactMarkdown remarkPlugins={[remarkGfm]} components={components}>
+        <SafeMarkdown allowImages components={components}>
           {content}
-        </ReactMarkdown>
+        </SafeMarkdown>
       </MarkdownContent>
     )
   },
diff --git a/src/scenes/Editor/AIChatWindow/ChatInput.tsx b/src/scenes/Editor/AIChatWindow/ChatInput.tsx
index ffc3fc83c..16519dddc 100644
--- a/src/scenes/Editor/AIChatWindow/ChatInput.tsx
+++ b/src/scenes/Editor/AIChatWindow/ChatInput.tsx
@@ -11,7 +11,7 @@ import styled from "styled-components"
 import { Box } from "../../../components"
 import { Text } from "../../../components/Text"
 import { color } from "../../../utils"
-import { ArrowUpIcon, CodeBlockIcon } from "@phosphor-icons/react"
+import { ArrowUpIcon, CodeBlockIcon, NotebookIcon } from "@phosphor-icons/react"
 import {
   useAIStatus,
   isBlockingAIStatus,
@@ -98,35 +98,37 @@ const ContextBadgeContainer = styled.div`
   background: ${color("backgroundDarker")};
 `
 
-const ContextBadge = styled.button`
+const ContextBadge = styled.button<{ $warn?: boolean }>`
   display: flex;
   padding: 0.3rem 0.6rem;
   align-items: center;
   gap: 0.4rem;
   line-height: 1.4;
   border-radius: 0.6rem;
-  border: 1px solid ${color("selection")};
+  border: 1px solid
+    ${({ $warn, theme }) => ($warn ? theme.color.red : theme.color.selection)};
   background: ${color("chatBackground")};
-  color: ${color("gray2")};
+  color: ${({ theme }) => theme.color.gray2};
   font-size: 1.3rem;
   user-select: none;
-  cursor: pointer;
+  cursor: ${({ $warn }) => ($warn ? "default" : "pointer")};
   font-family: inherit;
 
   &:hover {
-    border: 1px solid ${color("offWhite")};
-    color: ${color("offWhite")};
+    border: 1px solid
+      ${({ $warn, theme }) => ($warn ? theme.color.red : theme.color.offWhite)};
+    color: ${({ theme }) => theme.color.offWhite};
   }
 `
 
-const ContextBadgeIcon = styled.div`
+const ContextBadgeIcon = styled.div<{ $warn?: boolean }>`
   display: flex;
   align-items: center;
   color: ${color("gray2")};
   flex-shrink: 0;
 
   svg {
-    color: ${color("gray2")};
+    color: ${({ $warn, theme }) => ($warn ? theme.color.red : color("gray2"))};
   }
 `
 
@@ -184,12 +186,19 @@ const StopButtonWrapper = styled.div`
   transform: translateY(-50%);
 `
 
+export type NotebookContext = {
+  label: string
+  warn?: "archived" | "deleted" | null
+  onClick: () => void | Promise<void>
+}
+
 type ChatInputProps = {
   onSend: (message: string) => void
   disabled?: boolean
   placeholder?: string
   contextSQL?: string
   contextTableId?: number
+  contextNotebook?: NotebookContext
   onContextClick: () => void
 }
 
@@ -212,6 +221,7 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
       placeholder = "Ask a question or request a refinement...",
       contextSQL,
       contextTableId,
+      contextNotebook,
       onContextClick,
     },
     ref,
@@ -225,13 +235,23 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
       return tables.find((t) => t.id === contextTableId) ?? null
     }, [contextTableId, tables])
 
-    // Determine what to show in context badge
-    const contextText = tableData?.table_name
-      ? truncateText(tableData.table_name)
-      : contextSQL
-        ? truncateText(contextSQL)
-        : null
+    // Notebook context wins over table/SQL when the chat is bound; bound chats never carry SQL context.
+    const contextText = contextNotebook
+      ? truncateText(contextNotebook.label)
+      : tableData?.table_name
+        ? truncateText(tableData.table_name)
+        : contextSQL
+          ? truncateText(contextSQL)
+          : null
     const hasContext = Boolean(contextText)
+    const notebookWarn = contextNotebook?.warn
+    const notebookBadgeTitle = contextNotebook
+      ? notebookWarn === "archived"
+        ? `Notebook archived`
+        : notebookWarn === "deleted"
+          ? `Notebook deleted`
+          : `Attached: ${contextNotebook.label} — click to switch`
+      : undefined
 
     useImperativeHandle(ref, () => ({
       focus: () => {
@@ -304,12 +324,20 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
               <ContextBadgeContainer>
                 <ContextBadge
                   type="button"
-                  onClick={onContextClick}
-                  aria-label={`Change context: ${contextText}`}
+                  $warn={Boolean(notebookWarn)}
+                  onClick={
+                    contextNotebook
+                      ? () => void contextNotebook.onClick()
+                      : onContextClick
+                  }
+                  title={notebookBadgeTitle}
+                  aria-label={`Chat context: ${contextText}`}
                   data-hook="chat-context-badge"
                 >
-                  <ContextBadgeIcon>
-                    {tableData ? (
+                  <ContextBadgeIcon $warn={Boolean(notebookWarn)}>
+                    {contextNotebook ? (
+                      <NotebookIcon size={14} weight="regular" />
+                    ) : tableData ? (
                       <TableIcon
                         kind={getTableKind(tableData)}
                         partitionBy={tableData.partitionBy}
@@ -320,7 +348,11 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
                       <CodeBlockIcon size={14} weight="regular" />
                     )}
                   </ContextBadgeIcon>
-                  {contextText}
+                  {notebookWarn === "archived"
+                    ? `Archived: ${contextText}`
+                    : notebookWarn === "deleted"
+                      ? `Deleted: ${contextText}`
+                      : contextText}
                 </ContextBadge>
               </ContextBadgeContainer>
             )}
diff --git a/src/scenes/Editor/AIChatWindow/ChatMessages.tsx b/src/scenes/Editor/AIChatWindow/ChatMessages.tsx
index ddd4b691c..847ae9af8 100644
--- a/src/scenes/Editor/AIChatWindow/ChatMessages.tsx
+++ b/src/scenes/Editor/AIChatWindow/ChatMessages.tsx
@@ -823,7 +823,7 @@ export const ChatMessages: React.FC<ChatMessagesProps> = ({
             )
           }
 
-          // Default: plain text message
+          // Prefer `displayUserMessage` so wire-protocol prefixes don't show in the chat bubble.
           return (
             <MessageBubble
               key={key}
@@ -832,7 +832,9 @@ export const ChatMessages: React.FC<ChatMessagesProps> = ({
                 if (el) messageRefs.current.set(message.id, el)
               }}
             >
-              <MessageContent>{message.content}</MessageContent>
+              <MessageContent>
+                {message.displayUserMessage || message.content}
+              </MessageContent>
             </MessageBubble>
           )
         }
diff --git a/src/scenes/Editor/AIChatWindow/index.tsx b/src/scenes/Editor/AIChatWindow/index.tsx
index 78da2fda5..c843ea669 100644
--- a/src/scenes/Editor/AIChatWindow/index.tsx
+++ b/src/scenes/Editor/AIChatWindow/index.tsx
@@ -17,7 +17,10 @@ import {
   ClockCounterClockwiseIcon,
 } from "@phosphor-icons/react"
 import { useEditor } from "../../../providers"
-import { useAIConversation } from "../../../providers/AIConversationProvider"
+import {
+  useAIConversation,
+  useActiveConversationMessages,
+} from "../../../providers/AIConversationProvider"
 import { extractErrorByQueryKey } from "../utils"
 import {
   createDetachedQueryKey,
@@ -36,7 +39,7 @@ import { LiteEditor } from "../../../components/LiteEditor"
 import { ChatMessages } from "./ChatMessages"
 import { ChatInput, type ChatInputHandle } from "./ChatInput"
 import { ChatHistoryView } from "./ChatHistoryView"
-import { normalizeSql } from "../../../utils/aiAssistant"
+import { normalizeSql } from "../../../utils/formatSql"
 import {
   executeAIFlow,
   createChatFlowConfig,
@@ -57,6 +60,12 @@ import { eventBus } from "../../../modules/EventBus"
 import { EventType } from "../../../modules/EventBus/types"
 import { Stop } from "@styled-icons/remix-line"
 import { CircleNotchSpinner } from "../Monaco/icons"
+import { getUserActionSeq, getWorkspace } from "../../../utils/notebookAIBridge"
+import { buildSnapshot } from "../../../utils/ai/notebookSnapshot"
+import type {
+  NotebookFlowContext,
+  WorkspaceInfo,
+} from "../../../utils/executeAIFlow"
 import { QueryInNotification } from "../Monaco/query-in-notification"
 import { useQueryExecutionState } from "../../../hooks/useQueryExecutionState"
 import { getLastTurnWithUnactionedDiff } from "../../../utils/ai/turnView"
@@ -197,10 +206,13 @@ const AIChatWindow: React.FC = () => {
     addBuffer,
     executionRefs,
     highlightQuery,
+    buffers,
+    activeBuffer,
+    setActiveBuffer,
   } = useEditor()
+  const activeConversationMessages = useActiveConversationMessages()
   const {
     conversationMetas,
-    activeConversationMessages,
     chatWindowState,
     isLoadingMessages,
     isStreaming,
@@ -220,6 +232,9 @@ const AIChatWindow: React.FC = () => {
     acceptSuggestion,
     rejectSuggestion,
     persistMessages,
+    bindConversationToNotebook,
+    readUserActionDigest,
+    rotateUserActionDigest,
   } = useAIConversation()
   const {
     status: aiStatus,
@@ -378,6 +393,48 @@ const AIChatWindow: React.FC = () => {
     return "Ask AI about your tables, or generate a query..."
   }
 
+  // <workspace> always emits when tabs exist so unbound chats can resolve user-said labels to buffer_ids.
+  const buildNotebookFlowContext = useCallback(
+    (conversationId: string): NotebookFlowContext | undefined => {
+      const meta = getConversationMeta(conversationId)
+      const bufferId = meta?.notebookBufferId
+      const readSeq = getUserActionSeq()
+      const snapshot = bufferId ? buildSnapshot(getWorkspace(), bufferId) : null
+      const digest = readUserActionDigest(conversationId)
+      const notebookBuffers = buffers.filter(
+        (b) => !!b.notebookViewState && typeof b.id === "number",
+      )
+      const workspace: WorkspaceInfo | undefined =
+        notebookBuffers.length > 0 || typeof activeBuffer.id === "number"
+          ? {
+              notebooks: notebookBuffers.map((b) => ({
+                buffer_id: b.id as number,
+                label: b.label,
+                archived: !!b.archived,
+                ...(b.id === bufferId ? { bound_to_this_chat: true } : {}),
+              })),
+              active:
+                typeof activeBuffer.id === "number"
+                  ? {
+                      buffer_id: activeBuffer.id,
+                      label: activeBuffer.label,
+                      kind: activeBuffer.notebookViewState
+                        ? "notebook"
+                        : activeBuffer.metricsViewState
+                          ? "metrics"
+                          : activeBuffer.editorViewState
+                            ? "sql"
+                            : "other",
+                    }
+                  : undefined,
+            }
+          : undefined
+      if (!snapshot && !digest && !workspace) return undefined
+      return { snapshot, digest, workspace, readSeq }
+    },
+    [getConversationMeta, readUserActionDigest, buffers, activeBuffer],
+  )
+
   const handleSendMessage = (
     userMessage: string,
     hasUnactionedDiffParam: boolean = false,
@@ -411,6 +468,7 @@ const AIChatWindow: React.FC = () => {
         tables,
         hasSchemaAccess,
         abortSignal: abortController?.signal,
+        notebookContext: buildNotebookFlowContext(conversationId),
       }),
       {
         addMessage,
@@ -420,6 +478,8 @@ const AIChatWindow: React.FC = () => {
         setIsStreaming,
         persistMessages,
         updateConversationName,
+        bindConversationToNotebook,
+        rotateUserActionDigest,
         updateMessagesWithCompaction,
       },
     )
@@ -458,11 +518,17 @@ const AIChatWindow: React.FC = () => {
 
       const normalizedSQL = normalizeQueryText(sql)
       const queryKey = createDetachedQueryKey(normalizedSQL)
+      let queryId: QuestDB.QueryId | null = null
 
-      questExecution.requestExecution(
-        notificationNamespaceKey,
+      questExecution.requestExecution({
+        abort: () => {
+          if (queryId !== null) {
+            quest.abort(queryId)
+          }
+        },
+        bufferId: notificationNamespaceKey,
         queryKey,
-        () => {
+        execute: () => {
           const timeoutId = window.setTimeout(() => {
             dispatch(
               actions.query.addNotification(
@@ -499,6 +565,9 @@ const AIChatWindow: React.FC = () => {
             dispatch,
             executionRefs,
             releaseExecution: questExecution.releaseExecution,
+            onQueryStarted: (nextQueryId) => {
+              queryId = nextQueryId
+            },
             onSettled: () => {
               if (notificationTimeoutRef.current === timeoutId) {
                 window.clearTimeout(timeoutId)
@@ -507,7 +576,7 @@ const AIChatWindow: React.FC = () => {
             },
           })
         },
-      )
+      })
     },
     [
       conversation,
@@ -664,6 +733,7 @@ const AIChatWindow: React.FC = () => {
         tables,
         hasSchemaAccess,
         abortSignal: abortController?.signal,
+        notebookContext: buildNotebookFlowContext(conversationId),
       }
 
       const callbacks = {
@@ -675,6 +745,8 @@ const AIChatWindow: React.FC = () => {
         persistMessages,
         updateConversationName,
         updateMessagesWithCompaction,
+        bindConversationToNotebook,
+        rotateUserActionDigest,
       }
 
       switch (userMessage.displayType) {
@@ -798,6 +870,8 @@ const AIChatWindow: React.FC = () => {
       persistMessages,
       updateConversationName,
       updateMessagesWithCompaction,
+      bindConversationToNotebook,
+      buildNotebookFlowContext,
       currentSQL,
     ],
   )
@@ -862,6 +936,25 @@ const AIChatWindow: React.FC = () => {
     return null
   }
 
+  const notebookContext = (() => {
+    const boundId = conversation?.notebookBufferId
+    if (typeof boundId !== "number") return undefined
+    const buf = buffers.find((b) => b.id === boundId)
+    const isMissing = !buf
+    const isArchived = !!buf?.archived
+    const label = buf?.label ?? `#${boundId}`
+    const warn: "archived" | "deleted" | null = isMissing
+      ? "deleted"
+      : isArchived
+        ? "archived"
+        : null
+    const onClick = async () => {
+      if (warn) return
+      if (buf) await setActiveBuffer(buf)
+    }
+    return { label, warn, onClick }
+  })()
+
   return (
     <>
       <Drawer
@@ -996,6 +1089,7 @@ const AIChatWindow: React.FC = () => {
                 placeholder={getPlaceholder()}
                 contextSQL={queryInfo.queryText}
                 contextTableId={conversation?.tableId}
+                contextNotebook={notebookContext}
                 onContextClick={handleContextClick}
               />
             </ChatPanel>
diff --git a/src/scenes/Editor/Monaco/QueryDropdown.tsx b/src/scenes/Editor/Monaco/QueryDropdown.tsx
index b293a225d..e7366a491 100644
--- a/src/scenes/Editor/Monaco/QueryDropdown.tsx
+++ b/src/scenes/Editor/Monaco/QueryDropdown.tsx
@@ -7,45 +7,10 @@ import { PlayFilled } from "../../../components/icons/play-filled"
 import { AISparkle } from "../../../components/AISparkle"
 import type { Request } from "./utils"
 
-const StyledDropdownContent = styled(DropdownMenu.Content)`
-  background-color: #343846;
-  border-radius: 0.5rem;
-  padding: 0.4rem;
-  box-shadow: 0 0.2rem 0.8rem rgba(0, 0, 0, 0.36);
-  z-index: 9999;
-  min-width: 160px;
-  gap: 0;
-`
-
-const StyledDropdownItem = styled(DropdownMenu.Item)`
-  font-size: 1.3rem;
-  height: 3rem;
-  font-family: "system-ui", sans-serif;
-  cursor: pointer;
-  color: rgb(248, 248, 242);
-  display: flex;
-  align-items: center;
-  padding: 1rem 1.2rem;
-  border-radius: 0.4rem;
-  margin: 0;
-  gap: 0;
-  border: 1px solid transparent;
-
-  &[data-highlighted] {
-    background: #043c5c;
-    border: 1px solid #8be9fd;
-  }
-
-  &[data-disabled] {
-    opacity: 0.5;
-  }
-`
-
 const IconWrapper = styled.span`
   display: flex;
   align-items: center;
   justify-content: center;
-  margin-right: 1.2rem;
 `
 
 const StyledPlayFilled = styled(PlayFilled)`
@@ -117,11 +82,11 @@ export const QueryDropdown: React.FC<QueryDropdownProps> = ({
         />
       </DropdownMenu.Trigger>
       <DropdownMenu.Portal>
-        <StyledDropdownContent>
+        <DropdownMenu.Content>
           {isAIDropdownRef.current
             ? // AI dropdown - show "Ask AI about query X" options
               queriesRef.current.map((query, index) => (
-                <StyledDropdownItem
+                <DropdownMenu.Item
                   // eslint-disable-next-line react/no-array-index-key
                   key={`ask-ai-${query.query}-${index}`}
                   onClick={() => onAskAIRef.current(query)}
@@ -131,14 +96,14 @@ export const QueryDropdown: React.FC<QueryDropdownProps> = ({
                     <AISparkle size={18} variant="filled" />
                   </IconWrapper>
                   Ask AI about {extractQueryTextToRun(query)}
-                </StyledDropdownItem>
+                </DropdownMenu.Item>
               ))
             : queriesRef.current.length > 1
               ? // Multiple queries - show options for each
                 queriesRef.current
                   .map((query, index) => {
                     const items = [
-                      <StyledDropdownItem
+                      <DropdownMenu.Item
                         // eslint-disable-next-line react/no-array-index-key
                         key={`run-${query.query}-${index}`}
                         onClick={() => onRunQuery(query)}
@@ -148,12 +113,12 @@ export const QueryDropdown: React.FC<QueryDropdownProps> = ({
                           <StyledPlayFilled size={18} color="#fff" />
                         </IconWrapper>
                         Run {extractQueryTextToRun(query)}
-                      </StyledDropdownItem>,
+                      </DropdownMenu.Item>,
                     ]
 
                     if (isContextMenuRef.current) {
                       items.push(
-                        <StyledDropdownItem
+                        <DropdownMenu.Item
                           // eslint-disable-next-line react/no-array-index-key
                           key={`explain-${query.query}-${index}`}
                           disabled={isExplainDisabled(query)}
@@ -164,8 +129,8 @@ export const QueryDropdown: React.FC<QueryDropdownProps> = ({
                             <Information size={18} />
                           </IconWrapper>
                           Get query plan for {extractQueryTextToRun(query)}
-                        </StyledDropdownItem>,
-                        <StyledDropdownItem
+                        </DropdownMenu.Item>,
+                        <DropdownMenu.Item
                           // eslint-disable-next-line react/no-array-index-key
                           key={`copy-link-${query.query}-${index}`}
                           onClick={() => onCopyQueryLink(query)}
@@ -175,7 +140,7 @@ export const QueryDropdown: React.FC<QueryDropdownProps> = ({
                             <LinkSimpleIcon size={18} />
                           </IconWrapper>
                           Copy link to {extractQueryTextToRun(query)}
-                        </StyledDropdownItem>,
+                        </DropdownMenu.Item>,
                       )
                     }
 
@@ -183,7 +148,7 @@ export const QueryDropdown: React.FC<QueryDropdownProps> = ({
                   })
                   .flat()
               : [
-                  <StyledDropdownItem
+                  <DropdownMenu.Item
                     key="run"
                     onClick={() => onRunQuery(queriesRef.current[0])}
                     data-hook="dropdown-item-run-query"
@@ -192,8 +157,8 @@ export const QueryDropdown: React.FC<QueryDropdownProps> = ({
                       <StyledPlayFilled size={18} color="#fff" />
                     </IconWrapper>
                     Run {extractQueryTextToRun(queriesRef.current[0])}
-                  </StyledDropdownItem>,
-                  <StyledDropdownItem
+                  </DropdownMenu.Item>,
+                  <DropdownMenu.Item
                     key="explain"
                     disabled={isExplainDisabled(queriesRef.current[0])}
                     onClick={() => onExplainQuery(queriesRef.current[0])}
@@ -204,8 +169,8 @@ export const QueryDropdown: React.FC<QueryDropdownProps> = ({
                     </IconWrapper>
                     Get query plan for{" "}
                     {extractQueryTextToRun(queriesRef.current[0])}
-                  </StyledDropdownItem>,
-                  <StyledDropdownItem
+                  </DropdownMenu.Item>,
+                  <DropdownMenu.Item
                     key="copy-link"
                     onClick={() => onCopyQueryLink(queriesRef.current[0])}
                     data-hook="dropdown-item-copy-query-link"
@@ -214,9 +179,9 @@ export const QueryDropdown: React.FC<QueryDropdownProps> = ({
                       <LinkSimpleIcon size={18} />
                     </IconWrapper>
                     Copy link to {extractQueryTextToRun(queriesRef.current[0])}
-                  </StyledDropdownItem>,
+                  </DropdownMenu.Item>,
                 ]}
-        </StyledDropdownContent>
+        </DropdownMenu.Content>
       </DropdownMenu.Portal>
     </DropdownMenu.Root>
   )
diff --git a/src/scenes/Editor/Monaco/exportTabs.test.ts b/src/scenes/Editor/Monaco/exportTabs.test.ts
new file mode 100644
index 000000000..6f266d64d
--- /dev/null
+++ b/src/scenes/Editor/Monaco/exportTabs.test.ts
@@ -0,0 +1,187 @@
+import { describe, it, expect, vi, beforeEach } from "vitest"
+
+// Mock the Dexie db and export-import lib so importing the module under test
+// does not touch IndexedDB. db exposes a few tables so we can assert skipTables.
+vi.mock("../../../store/db", () => ({
+  db: {
+    tables: [
+      { name: "buffers" },
+      { name: "editor_settings" },
+      { name: "notebook_results" },
+    ],
+  },
+}))
+type ExportOpts = {
+  skipTables: string[]
+  filter: (table: string, value: unknown) => boolean
+}
+const { exportDB } = vi.hoisted(() => ({
+  exportDB: vi.fn((_db: unknown, _options: ExportOpts) =>
+    Promise.resolve(new Blob(["{}"])),
+  ),
+}))
+vi.mock("dexie-export-import", () => ({ exportDB }))
+
+import {
+  shouldExportBuffer,
+  buildExportFileName,
+  reconcileRowCounts,
+  exportBuffers,
+} from "./exportTabs"
+
+describe("shouldExportBuffer", () => {
+  it("includes a normal buffer when no bufferId is given", () => {
+    expect(shouldExportBuffer({ id: 1 })).toBe(true)
+  })
+
+  it("excludes temporary and preview buffers", () => {
+    expect(shouldExportBuffer({ id: 1, isTemporary: true })).toBe(false)
+    expect(shouldExportBuffer({ id: 1, isPreviewBuffer: true })).toBe(false)
+  })
+
+  it("keeps only the matching buffer when a bufferId is given", () => {
+    expect(shouldExportBuffer({ id: 7 }, { bufferId: 7 })).toBe(true)
+    expect(shouldExportBuffer({ id: 8 }, { bufferId: 7 })).toBe(false)
+  })
+
+  it("excludes temporary/preview even when their id matches the bufferId", () => {
+    expect(
+      shouldExportBuffer({ id: 7, isTemporary: true }, { bufferId: 7 }),
+    ).toBe(false)
+    expect(
+      shouldExportBuffer({ id: 7, isPreviewBuffer: true }, { bufferId: 7 }),
+    ).toBe(false)
+  })
+
+  it("treats bufferId 0 as a real target (not 'no filter')", () => {
+    expect(shouldExportBuffer({ id: 0 }, { bufferId: 0 })).toBe(true)
+    expect(shouldExportBuffer({ id: 1 }, { bufferId: 0 })).toBe(false)
+  })
+})
+
+describe("buildExportFileName", () => {
+  const timestamp = "2026-06-16T10:30:45.123Z"
+
+  it("uses the 'tabs' segment for a full export", () => {
+    expect(buildExportFileName(undefined, timestamp)).toBe(
+      "questdb-tabs-2026-06-16T10-30-45-123Z.json",
+    )
+  })
+
+  it("uses the 'notebook' segment for a single-notebook export", () => {
+    expect(buildExportFileName({ bufferId: 3 }, timestamp)).toBe(
+      "questdb-notebook-2026-06-16T10-30-45-123Z.json",
+    )
+  })
+
+  it("sanitizes colons and dots out of the timestamp", () => {
+    const name = buildExportFileName({ bufferId: 0 }, timestamp)
+    expect(name).not.toContain(":")
+    // The only remaining dot should be the `.json` extension.
+    expect(name.replace(/\.json$/, "")).not.toContain(".")
+  })
+})
+
+describe("reconcileRowCounts", () => {
+  it("rewrites an overstated rowCount to the rows actually exported", () => {
+    const json = {
+      data: {
+        tables: [{ name: "buffers", rowCount: 42 }],
+        data: [{ tableName: "buffers", rows: [{ id: 1 }] }],
+      },
+    }
+    reconcileRowCounts(json)
+    expect(json.data.tables[0].rowCount).toBe(1)
+  })
+
+  it("reconciles each table independently", () => {
+    const json = {
+      data: {
+        tables: [
+          { name: "buffers", rowCount: 99 },
+          { name: "settings", rowCount: 99 },
+        ],
+        data: [
+          { tableName: "buffers", rows: [{}, {}] },
+          { tableName: "settings", rows: [] },
+        ],
+      },
+    }
+    reconcileRowCounts(json)
+    expect(json.data.tables.map((t) => t.rowCount)).toEqual([2, 0])
+  })
+
+  it("leaves a table untouched when it has no data entry", () => {
+    const json = {
+      data: {
+        tables: [{ name: "buffers", rowCount: 5 }],
+        data: [{ tableName: "other", rows: [{}] }],
+      },
+    }
+    reconcileRowCounts(json)
+    expect(json.data.tables[0].rowCount).toBe(5)
+  })
+
+  it("returns the input unchanged when the structure is missing", () => {
+    expect(reconcileRowCounts({})).toEqual({})
+    expect(reconcileRowCounts({ data: {} })).toEqual({ data: {} })
+  })
+})
+
+describe("exportBuffers wiring", () => {
+  beforeEach(() => {
+    exportDB.mockClear()
+    // Stub the DOM download plumbing (test env is node, not jsdom).
+    vi.stubGlobal("URL", {
+      createObjectURL: vi.fn(() => "blob:stub"),
+      revokeObjectURL: vi.fn(),
+    })
+    vi.stubGlobal("document", {
+      createElement: vi.fn(() => ({ click: vi.fn() })),
+    })
+  })
+
+  it("skips every table except 'buffers'", async () => {
+    await exportBuffers()
+    const [, options] = exportDB.mock.calls[0]
+    expect(options.skipTables).toEqual(["editor_settings", "notebook_results"])
+  })
+
+  it("forwards the bufferId into the filter handed to exportDB", async () => {
+    await exportBuffers({ bufferId: 7 })
+    const [, options] = exportDB.mock.calls[0]
+    // The filter exportDB receives must reflect the single-notebook scope.
+    expect(options.filter("buffers", { id: 7 })).toBe(true)
+    expect(options.filter("buffers", { id: 8 })).toBe(false)
+  })
+
+  it("writes a corrected rowCount into the downloaded file", async () => {
+    let captured: Blob | undefined
+    vi.stubGlobal("URL", {
+      createObjectURL: vi.fn((b: Blob) => {
+        captured = b
+        return "blob:stub"
+      }),
+      revokeObjectURL: vi.fn(),
+    })
+    // exportDB stamps rowCount 50 but only one row is actually emitted.
+    exportDB.mockResolvedValueOnce(
+      new Blob([
+        JSON.stringify({
+          data: {
+            tables: [{ name: "buffers", rowCount: 50 }],
+            data: [{ tableName: "buffers", rows: [{ id: 1 }] }],
+          },
+        }),
+      ]),
+    )
+
+    await exportBuffers({ bufferId: 1 })
+
+    const text = await (captured as Blob).text()
+    const parsed = JSON.parse(text) as {
+      data: { tables: Array<{ rowCount: number }> }
+    }
+    expect(parsed.data.tables[0].rowCount).toBe(1)
+  })
+})
diff --git a/src/scenes/Editor/Monaco/exportTabs.ts b/src/scenes/Editor/Monaco/exportTabs.ts
new file mode 100644
index 000000000..40bcf532c
--- /dev/null
+++ b/src/scenes/Editor/Monaco/exportTabs.ts
@@ -0,0 +1,88 @@
+import { exportDB } from "dexie-export-import"
+import { db } from "../../../store/db"
+import type { Buffer } from "../../../store/buffers"
+
+type ExportOptions = { bufferId?: number }
+
+// Pure predicate deciding whether a buffer belongs in an export.
+// Temporary and preview buffers are always excluded; when a bufferId is
+// given, only that single buffer is kept (single-notebook export).
+export const shouldExportBuffer = (
+  buffer: Pick<Buffer, "id" | "isTemporary" | "isPreviewBuffer">,
+  options?: ExportOptions,
+): boolean => {
+  if (buffer.isTemporary || buffer.isPreviewBuffer) return false
+  if (options?.bufferId !== undefined && buffer.id !== options.bufferId) {
+    return false
+  }
+  return true
+}
+
+export const buildExportFileName = (
+  options?: ExportOptions,
+  timestamp = new Date().toISOString(),
+): string => {
+  const namePart = options?.bufferId !== undefined ? "notebook" : "tabs"
+  return `questdb-${namePart}-${timestamp.replace(/[:.]/g, "-")}.json`
+}
+
+type DexieExport = {
+  data?: {
+    tables?: Array<{ name?: string; rowCount?: number }>
+    data?: Array<{ tableName?: string; rows?: unknown[] }>
+  }
+}
+
+// dexie-export-import stamps each table's `rowCount` from the full table count,
+// ignoring the row `filter` — so a filtered export overstates the count and the
+// importer's tab-limit check reads it as far more tabs than were emitted. Rewrite
+// each rowCount to the rows actually present in the export.
+export const reconcileRowCounts = (json: DexieExport): DexieExport => {
+  const tables = json.data?.tables
+  const tableData = json.data?.data
+  if (!Array.isArray(tables) || !Array.isArray(tableData)) return json
+
+  const rowsByTable = new Map<string, number>()
+  for (const entry of tableData) {
+    if (entry && typeof entry.tableName === "string") {
+      rowsByTable.set(
+        entry.tableName,
+        Array.isArray(entry.rows) ? entry.rows.length : 0,
+      )
+    }
+  }
+  for (const table of tables) {
+    if (
+      table &&
+      typeof table.name === "string" &&
+      rowsByTable.has(table.name)
+    ) {
+      table.rowCount = rowsByTable.get(table.name)
+    }
+  }
+  return json
+}
+
+export const exportBuffers = async (options?: ExportOptions) => {
+  const skipTables = db.tables
+    .map((t) => t.name)
+    .filter((name) => name !== "buffers")
+  const blob = await exportDB(db, {
+    skipTables,
+    filter: (_table, value) => shouldExportBuffer(value as Buffer, options),
+  })
+
+  const reconciled = reconcileRowCounts(
+    JSON.parse(await blob.text()) as unknown as DexieExport,
+  )
+  const finalBlob = new Blob([JSON.stringify(reconciled)], {
+    type: "application/json",
+  })
+
+  const url = URL.createObjectURL(finalBlob)
+  const a = document.createElement("a")
+  a.href = url
+  a.download = buildExportFileName(options)
+  a.click()
+  URL.revokeObjectURL(url)
+}
diff --git a/src/scenes/Editor/Monaco/importTabs.test.ts b/src/scenes/Editor/Monaco/importTabs.test.ts
index 4903a4652..c2539fb2a 100644
--- a/src/scenes/Editor/Monaco/importTabs.test.ts
+++ b/src/scenes/Editor/Monaco/importTabs.test.ts
@@ -105,12 +105,14 @@ describe("validateBufferSchema", () => {
       ).toBe("Item [0]: position must be a number")
     })
 
-    it("should reject tabs without editorViewState or metricsViewState", () => {
+    it("should reject tabs without editorViewState, metricsViewState, or notebookViewState", () => {
       expect(
         validateBufferSchema([
           { label: "Tab 1", value: "SELECT 1", position: 0 },
         ]),
-      ).toBe("Item [0]: must have editorViewState or metricsViewState")
+      ).toBe(
+        "Item [0]: must have editorViewState, metricsViewState, or notebookViewState",
+      )
     })
 
     it("should accept tab with editorViewState", () => {
@@ -138,6 +140,113 @@ describe("validateBufferSchema", () => {
         ]),
       ).toBe(true)
     })
+
+    it("should accept tab with a well-formed notebookViewState", () => {
+      expect(
+        validateBufferSchema([
+          {
+            label: "Notebook",
+            value: "",
+            position: 0,
+            notebookViewState: {
+              cells: [
+                { id: "c1", position: 0, value: "SELECT 1" },
+                { id: "c2", position: 1, value: "SELECT 2", mode: "draw" },
+              ],
+            },
+          },
+        ]),
+      ).toBe(true)
+    })
+  })
+
+  describe("notebookViewState validation", () => {
+    const notebookTab = (notebookViewState: unknown) => [
+      { label: "Notebook", value: "", position: 0, notebookViewState },
+    ]
+
+    it("rejects a non-object notebookViewState", () => {
+      expect(validateBufferSchema(notebookTab("nope"))).toContain(
+        "notebookViewState: must be an object",
+      )
+    })
+
+    it("rejects a missing/non-array cells field", () => {
+      expect(validateBufferSchema(notebookTab({}))).toContain(
+        "notebookViewState.cells: must be an array",
+      )
+      expect(validateBufferSchema(notebookTab({ cells: {} }))).toContain(
+        "notebookViewState.cells: must be an array",
+      )
+    })
+
+    it("rejects non-object and malformed cells", () => {
+      expect(validateBufferSchema(notebookTab({ cells: [null] }))).toContain(
+        "cells[0]: must be an object",
+      )
+      expect(
+        validateBufferSchema(notebookTab({ cells: [{ id: 1, value: "x" }] })),
+      ).toContain("cells[0].id: must be a non-empty string")
+      expect(
+        validateBufferSchema(notebookTab({ cells: [{ id: "a", value: 5 }] })),
+      ).toContain("cells[0].value: must be a string")
+      expect(
+        validateBufferSchema(
+          notebookTab({ cells: [{ id: "a", value: "x", mode: "chart" }] }),
+        ),
+      ).toContain("cells[0].mode: invalid value")
+    })
+
+    it("rejects duplicate cell ids", () => {
+      expect(
+        validateBufferSchema(
+          notebookTab({
+            cells: [
+              { id: "a", value: "x" },
+              { id: "a", value: "y" },
+            ],
+          }),
+        ),
+      ).toContain('cells[1].id: duplicate "a"')
+    })
+
+    it("rejects a notebook with more than 50 cells", () => {
+      const cells = Array.from({ length: 51 }, (_, i) => ({
+        id: `c${i}`,
+        value: "SELECT 1",
+      }))
+      expect(validateBufferSchema(notebookTab({ cells }))).toContain(
+        "notebookViewState.cells: exceeds cell limit (51 > 50)",
+      )
+    })
+
+    it("accepts a notebook with exactly 50 cells", () => {
+      const cells = Array.from({ length: 50 }, (_, i) => ({
+        id: `c${i}`,
+        value: "SELECT 1",
+      }))
+      expect(validateBufferSchema(notebookTab({ cells }))).toBe(true)
+    })
+
+    it("rejects a cell value exceeding the line limit", () => {
+      const hugeValue = Array(100001).fill("line").join("\n")
+      expect(
+        validateBufferSchema(
+          notebookTab({ cells: [{ id: "a", value: hugeValue }] }),
+        ),
+      ).toContain("cells[0].value: exceeds line limit")
+    })
+
+    it("exempts markdown cells from the line limit", () => {
+      const hugeValue = Array(100001).fill("line").join("\n")
+      expect(
+        validateBufferSchema(
+          notebookTab({
+            cells: [{ id: "a", value: hugeValue, type: "markdown" }],
+          }),
+        ),
+      ).toBe(true)
+    })
   })
 
   describe("line count limit", () => {
@@ -664,6 +773,96 @@ describe("sanitizeBuffer", () => {
     })
   })
 
+  describe("notebookViewState sanitization", () => {
+    it("whitelists cell fields, reindexes positions, drops session state", () => {
+      const input = {
+        label: "Notebook",
+        value: "",
+        position: 0,
+        notebookViewState: {
+          cells: [
+            {
+              id: "c1",
+              position: 7,
+              value: "SELECT 1",
+              mode: "draw",
+              autoRefresh: true,
+              result: { results: "garbage" },
+              editorViewState: { broken: true },
+              extraField: "should not be copied",
+            },
+            { id: "c2", position: 2, value: "SELECT 2" },
+          ],
+          focusedCellId: "c1",
+          maximizedCellId: "missing-cell",
+          settings: {
+            layoutMode: "grid",
+            layout: [
+              { i: "c1", x: 0, y: 0, w: 6, h: 4 },
+              { i: "bad", x: "0", y: 0, w: 6, h: 4 },
+              null,
+            ],
+            variables: [
+              { name: "v", value: "1" },
+              { name: 5, value: "x" },
+            ],
+          },
+        },
+      }
+      const result = sanitizeBuffer(input)
+      const state = result.notebookViewState
+      expect(state).toBeDefined()
+      expect(state?.cells.map((c) => [c.id, c.position, c.value])).toEqual([
+        ["c1", 0, "SELECT 1"],
+        ["c2", 1, "SELECT 2"],
+      ])
+      expect(state?.cells[0].mode).toBe("draw")
+      expect(state?.cells[0].autoRefresh).toBe(true)
+      const cell = state?.cells[0] as unknown as Record<string, unknown>
+      expect(cell.result).toBeUndefined()
+      expect(cell.editorViewState).toBeUndefined()
+      expect(cell.extraField).toBeUndefined()
+      // maximizedCellId referencing a non-existent cell is dropped
+      expect(state?.maximizedCellId).toBeUndefined()
+      expect(state?.settings?.layoutMode).toBe("grid")
+      expect(state?.settings?.layout).toEqual([
+        { i: "c1", x: 0, y: 0, w: 6, h: 4 },
+      ])
+      expect(state?.settings?.variables).toEqual([{ name: "v", value: "1" }])
+    })
+
+    it("drops legacy chartConfig (non-array queries) and keeps valid ones", () => {
+      const input = {
+        label: "Notebook",
+        value: "",
+        position: 0,
+        notebookViewState: {
+          cells: [
+            {
+              id: "c1",
+              value: "SELECT 1",
+              chartConfig: { type: "line", series: "legacy-shape" },
+            },
+            {
+              id: "c2",
+              value: "SELECT 2",
+              chartConfig: {
+                xColumn: "ts",
+                queries: [{ type: "line", yColumns: ["price"] }, "junk"],
+              },
+            },
+          ],
+        },
+      }
+      const result = sanitizeBuffer(input)
+      expect(result.notebookViewState?.cells[0].chartConfig).toBeUndefined()
+      expect(result.notebookViewState?.cells[1].chartConfig).toEqual({
+        xColumn: "ts",
+        queries: [{ type: "line", yColumns: ["price"] }, null],
+      })
+    })
+  })
+
   describe("metricsViewState sanitization", () => {
     it("should sanitize metricsViewState fields", () => {
       const input = {
@@ -943,5 +1142,40 @@ describe("deduplication", () => {
       }
       expect(createBufferContentKey(buffer)).toBe("Tab|SELECT * FROM t")
     })
+
+    it("creates key from cell values for notebook tabs", () => {
+      const buffer = {
+        label: "Notebook",
+        value: "",
+        notebookViewState: {
+          cells: [
+            { id: "a", type: "sql", position: 0, value: "SELECT 1" },
+            { id: "b", type: "markdown", position: 1, value: "# title" },
+          ],
+        },
+      } as unknown as Parameters<typeof createBufferContentKey>[0]
+      expect(createBufferContentKey(buffer)).toBe(
+        `Notebook|${JSON.stringify(["SELECT 1", "# title"])}`,
+      )
+    })
+
+    it("notebook branch is guarded against missing cells array", () => {
+      const buffer = {
+        label: "Notebook",
+        value: "",
+        notebookViewState: {},
+      } as unknown as Parameters<typeof createBufferContentKey>[0]
+      expect(createBufferContentKey(buffer)).toBe("Notebook|[]")
+    })
+
+    it("notebook branch takes precedence over metricsViewState", () => {
+      const buffer = {
+        label: "Hybrid",
+        value: "",
+        metricsViewState: { viewMode: MetricViewMode.LIST },
+        notebookViewState: { cells: [] },
+      } as unknown as Parameters<typeof createBufferContentKey>[0]
+      expect(createBufferContentKey(buffer)).toBe("Hybrid|[]")
+    })
   })
 })
diff --git a/src/scenes/Editor/Monaco/importTabs.ts b/src/scenes/Editor/Monaco/importTabs.ts
index 78f5bbf16..905c4bda8 100644
--- a/src/scenes/Editor/Monaco/importTabs.ts
+++ b/src/scenes/Editor/Monaco/importTabs.ts
@@ -10,7 +10,20 @@ import {
   SampleBy,
   RefreshRate,
 } from "../Metrics/utils"
+import type {
+  CellLayoutItem,
+  NotebookCell,
+  NotebookSettings,
+  NotebookVariable,
+  NotebookViewState,
+} from "../../../store/notebook"
+import type { ChartConfig, QueryChart } from "../Notebook/CellChart/chartTypes"
 import { LINE_NUMBER_HARD_LIMIT } from "./index"
+import {
+  MAX_NOTEBOOK_CELLS,
+  MAX_CELL_LINES,
+  exceedsCellLineLimit,
+} from "../../../store/notebook"
 
 type ValidationResult = true | string
 
@@ -79,6 +92,50 @@ const validateMetricsViewState = (item: unknown): ValidationResult => {
   return true
 }
 
+const validateNotebookCell = (
+  item: unknown,
+  index: number,
+): ValidationResult => {
+  if (typeof item !== "object" || item === null)
+    return `cells[${index}]: must be an object`
+  const obj = item as Record<string, unknown>
+
+  if (typeof obj.id !== "string" || obj.id.length === 0)
+    return `cells[${index}].id: must be a non-empty string`
+  if (typeof obj.value !== "string")
+    return `cells[${index}].value: must be a string`
+  if (obj.type !== "markdown" && exceedsCellLineLimit(obj.value))
+    return `cells[${index}].value: exceeds line limit (line count > ${MAX_CELL_LINES})`
+  if (obj.type !== undefined && obj.type !== "sql" && obj.type !== "markdown")
+    return `cells[${index}].type: invalid value ${JSON.stringify(obj.type)}`
+  if (obj.mode !== undefined && obj.mode !== "run" && obj.mode !== "draw")
+    return `cells[${index}].mode: invalid value ${JSON.stringify(obj.mode)}`
+
+  return true
+}
+
+const validateNotebookViewState = (item: unknown): ValidationResult => {
+  if (typeof item !== "object" || item === null)
+    return "notebookViewState: must be an object"
+  const obj = item as Record<string, unknown>
+
+  if (!Array.isArray(obj.cells))
+    return "notebookViewState.cells: must be an array"
+  if (obj.cells.length > MAX_NOTEBOOK_CELLS)
+    return `notebookViewState.cells: exceeds cell limit (${obj.cells.length} > ${MAX_NOTEBOOK_CELLS})`
+  const ids = new Set<string>()
+  for (let i = 0; i < obj.cells.length; i++) {
+    const result = validateNotebookCell(obj.cells[i], i)
+    if (result !== true) return `notebookViewState.${result}`
+    const id = (obj.cells[i] as Record<string, unknown>).id as string
+    if (ids.has(id))
+      return `notebookViewState.cells[${i}].id: duplicate "${id}"`
+    ids.add(id)
+  }
+
+  return true
+}
+
 export const validateBufferItem = (item: unknown): ValidationResult => {
   if (typeof item !== "object" || item === null) return "must be an object"
   const obj = item as Record<string, unknown>
@@ -98,14 +155,20 @@ export const validateBufferItem = (item: unknown): ValidationResult => {
 
   const hasEditorViewState = obj.editorViewState !== undefined
   const hasMetricsViewState = obj.metricsViewState !== undefined
-  if (!hasEditorViewState && !hasMetricsViewState)
-    return "must have editorViewState or metricsViewState"
+  const hasNotebookViewState = obj.notebookViewState !== undefined
+  if (!hasEditorViewState && !hasMetricsViewState && !hasNotebookViewState)
+    return "must have editorViewState, metricsViewState, or notebookViewState"
 
   if (hasMetricsViewState) {
     const result = validateMetricsViewState(obj.metricsViewState)
     if (result !== true) return result
   }
 
+  if (hasNotebookViewState) {
+    const result = validateNotebookViewState(obj.notebookViewState)
+    if (result !== true) return result
+  }
+
   return true
 }
 
@@ -156,10 +219,108 @@ const sanitizeMetricsViewState = (
   return state
 }
 
+const sanitizeChartConfig = (item: unknown): ChartConfig | undefined => {
+  if (typeof item !== "object" || item === null) return undefined
+  const obj = item as Record<string, unknown>
+  // Legacy (pre-`queries`) configs are dropped on load anyway.
+  if (!Array.isArray(obj.queries)) return undefined
+
+  const config: ChartConfig = {
+    xColumn: typeof obj.xColumn === "string" ? obj.xColumn : null,
+    queries: obj.queries.map((q) =>
+      typeof q === "object" && q !== null ? (q as QueryChart) : null,
+    ),
+  }
+  if (typeof obj.name === "string") config.name = obj.name
+  if (typeof obj.autoRefresh === "boolean") config.autoRefresh = obj.autoRefresh
+  if (typeof obj.rightAxis === "object" && obj.rightAxis !== null)
+    config.rightAxis = obj.rightAxis as ChartConfig["rightAxis"]
+  return config
+}
+
+// Whitelists notebook content fields; session/display state (results,
+// editorViewState) is intentionally dropped so an imported notebook starts
+// fresh and malformed payloads can't crash the renderers.
+const sanitizeNotebookCell = (
+  item: Record<string, unknown>,
+  index: number,
+): NotebookCell => {
+  const cell: NotebookCell = {
+    id: item.id as string,
+    position: index,
+    value: item.value as string,
+  }
+  // Whitelist the kind so a hand-crafted import can't smuggle a bogus type
+  // (anything other than "markdown" collapses to the SQL default).
+  if (item.type === "markdown") cell.type = "markdown"
+  if (item.mode === "run" || item.mode === "draw") cell.mode = item.mode
+  const chartConfig = sanitizeChartConfig(item.chartConfig)
+  if (chartConfig) cell.chartConfig = chartConfig
+  if (typeof item.autoRefresh === "boolean") cell.autoRefresh = item.autoRefresh
+  if (typeof item.isChartMaximized === "boolean")
+    cell.isChartMaximized = item.isChartMaximized
+  if (typeof item.topHeight === "number") cell.topHeight = item.topHeight
+  if (typeof item.bottomHeight === "number")
+    cell.bottomHeight = item.bottomHeight
+  if (typeof item.topResized === "boolean") cell.topResized = item.topResized
+  if (typeof item.spotlightEditorRatio === "number")
+    cell.spotlightEditorRatio = item.spotlightEditorRatio
+  return cell
+}
+
+const sanitizeNotebookSettings = (
+  item: Record<string, unknown>,
+): NotebookSettings => {
+  const settings: NotebookSettings = {}
+  if (item.layoutMode === "list" || item.layoutMode === "grid")
+    settings.layoutMode = item.layoutMode
+  if (Array.isArray(item.layout)) {
+    settings.layout = item.layout.filter((l): l is CellLayoutItem => {
+      if (typeof l !== "object" || l === null) return false
+      const o = l as Record<string, unknown>
+      return (
+        typeof o.i === "string" &&
+        typeof o.x === "number" &&
+        typeof o.y === "number" &&
+        typeof o.w === "number" &&
+        typeof o.h === "number"
+      )
+    })
+  }
+  if (Array.isArray(item.variables)) {
+    settings.variables = item.variables.filter((v): v is NotebookVariable => {
+      if (typeof v !== "object" || v === null) return false
+      const o = v as Record<string, unknown>
+      return typeof o.name === "string" && typeof o.value === "string"
+    })
+  }
+  return settings
+}
+
+const sanitizeNotebookViewState = (
+  item: Record<string, unknown>,
+): NotebookViewState => {
+  const cells = (item.cells as unknown[]).map((c, i) =>
+    sanitizeNotebookCell(c as Record<string, unknown>, i),
+  )
+  const state: NotebookViewState = { cells }
+  if (
+    typeof item.maximizedCellId === "string" &&
+    cells.some((c) => c.id === item.maximizedCellId)
+  )
+    state.maximizedCellId = item.maximizedCellId
+  if (typeof item.settings === "object" && item.settings !== null)
+    state.settings = sanitizeNotebookSettings(
+      item.settings as Record<string, unknown>,
+    )
+  return state
+}
+
 export const sanitizeBuffer = (
   item: Record<string, unknown>,
 ): Omit<Buffer, "id"> => {
   const hasMetricsViewState = item.metricsViewState !== undefined
+  const hasNotebookViewState = item.notebookViewState !== undefined
 
   const sanitized: Omit<Buffer, "id"> = {
     label: item.label as string,
@@ -167,7 +328,11 @@ export const sanitizeBuffer = (
     position: item.position as number,
   }
 
-  if (hasMetricsViewState) {
+  if (hasNotebookViewState) {
+    sanitized.notebookViewState = sanitizeNotebookViewState(
+      item.notebookViewState as Record<string, unknown>,
+    )
+  } else if (hasMetricsViewState) {
     sanitized.metricsViewState = sanitizeMetricsViewState(
       item.metricsViewState as Record<string, unknown>,
     )
@@ -198,10 +363,17 @@ export const validateBufferSchema = (data: unknown): ValidationResult => {
 }
 
 export const createBufferContentKey = (
-  buffer: Pick<Buffer, "label" | "value" | "metricsViewState">,
+  buffer: Pick<
+    Buffer,
+    "label" | "value" | "metricsViewState" | "notebookViewState"
+  >,
 ): string => {
-  const content = buffer.metricsViewState
-    ? JSON.stringify(buffer.metricsViewState)
-    : buffer.value
-  return `${buffer.label}|${content}`
+  if (buffer.notebookViewState) {
+    const cellValues = buffer.notebookViewState.cells?.map((c) => c.value) ?? []
+    return `${buffer.label}|${JSON.stringify(cellValues)}`
+  }
+  if (buffer.metricsViewState) {
+    return `${buffer.label}|${JSON.stringify(buffer.metricsViewState)}`
+  }
+  return `${buffer.label}|${buffer.value}`
 }
diff --git a/src/scenes/Editor/Monaco/index.tsx b/src/scenes/Editor/Monaco/index.tsx
index 753e05212..da12740ea 100644
--- a/src/scenes/Editor/Monaco/index.tsx
+++ b/src/scenes/Editor/Monaco/index.tsx
@@ -2,14 +2,8 @@ import Editor from "@monaco-editor/react"
 import type { Monaco } from "@monaco-editor/react"
 import { Stop } from "@styled-icons/remix-line"
 import { Error as ErrorIcon } from "@styled-icons/boxicons-regular"
-import type { editor, IDisposable } from "monaco-editor"
-import React, {
-  useCallback,
-  useContext,
-  useEffect,
-  useRef,
-  useState,
-} from "react"
+import type { editor } from "monaco-editor"
+import React, { useContext, useEffect, useRef, useState } from "react"
 import type { ReactNode } from "react"
 import { useDispatch, useSelector } from "react-redux"
 import styled from "styled-components"
@@ -34,9 +28,10 @@ import {
   useAIStatus,
   isBlockingAIStatus,
 } from "../../../providers/AIStatusProvider"
-import { useAIConversation } from "../../../providers/AIConversationProvider"
+import { useAIConversationActions } from "../../../providers/AIConversationProvider"
 import { actions, selectors } from "../../../store"
 import { RunningType } from "../../../store/Query/types"
+import { MAX_CELL_LINES } from "../../../store/notebook"
 import type { NotificationShape } from "../../../store/Query/types"
 import { theme } from "../../../theme"
 import { NotificationType } from "../../../types"
@@ -48,7 +43,6 @@ import QueryResult from "../QueryResult"
 import { registerEditorActions } from "./editor-addons"
 import { registerLegacyEventBusEvents } from "./legacy-event-bus"
 import { QueryInNotification } from "./query-in-notification"
-import { createSchemaCompletionProvider } from "./questdb-sql"
 import { Request } from "./utils"
 import {
   applyValidationMarkers,
@@ -76,6 +70,7 @@ import {
   readShareLinkParams,
   clearShareLinkParams,
   buildShareLinkUrl,
+  pinMonacoContextMenu,
 } from "./utils"
 import { toast } from "../../../components/Toast"
 import { LiteEditor } from "../../../components/LiteEditor"
@@ -100,7 +95,7 @@ type IndividualQueryResult = {
     | null
 }
 
-export const LINE_NUMBER_HARD_LIMIT = 99999
+export const LINE_NUMBER_HARD_LIMIT = MAX_CELL_LINES
 
 const Content = styled(PaneContent)<{ $hidden?: boolean }>`
   position: relative;
@@ -287,11 +282,9 @@ const MonacoEditor = ({ hidden = false }: { hidden?: boolean }) => {
     hasConversationForQuery,
     shiftQueryKeysForBuffer,
     findQueryByConversationId,
-  } = useAIConversation()
+  } = useAIConversationActions()
   const [request, setRequest] = useState<Request | undefined>()
-  const [editorReady, setEditorReady] = useState<boolean>(false)
   const [lastExecutedQuery, setLastExecutedQuery] = useState("")
-  const [refreshingTables, setRefreshingTables] = useState(false)
   const [dropdownOpen, setDropdownOpen] = useState(false)
   const [scriptConfirmationOpen, setScriptConfirmationOpen] = useState(false)
   const scriptConfirmationOpenRef = useRef(false)
@@ -308,13 +301,10 @@ const MonacoEditor = ({ hidden = false }: { hidden?: boolean }) => {
   const dispatch = useDispatch()
   const running = useSelector(selectors.query.getRunning)
   const tables = useSelector(selectors.query.getTables)
-  const columns = useSelector(selectors.query.getColumns)
   const activeNotification = useSelector(selectors.query.getActiveNotification)
   const queryNotifications = useSelector(
     selectors.query.getQueryNotificationsForBuffer(activeBuffer.id as number),
   )
-  const [schemaCompletionHandle, setSchemaCompletionHandle] =
-    useState<IDisposable>()
   const isRunningScriptRef = useRef(false)
   const queryOffsetsRef = useRef<
     { startOffset: number; endOffset: number }[] | null
@@ -589,9 +579,19 @@ const MonacoEditor = ({ hidden = false }: { hidden?: boolean }) => {
     const targetBufferId = activeBufferRef.current.id as number
     const queryKey = createQueryKeyFromRequest(editor, query)
 
-    questExecution.requestExecution(targetBufferId, queryKey, () => {
-      setCursorBeforeRunning(query)
-      toggleRunning(type)
+    questExecution.requestExecution({
+      abort: () => {
+        if (editorQueryIdRef.current !== null) {
+          quest.abort(editorQueryIdRef.current)
+          editorQueryIdRef.current = null
+        }
+      },
+      bufferId: targetBufferId,
+      execute: () => {
+        setCursorBeforeRunning(query)
+        toggleRunning(type)
+      },
+      queryKey,
     })
   }
 
@@ -901,7 +901,6 @@ const MonacoEditor = ({ hidden = false }: { hidden?: boolean }) => {
     editor.setModel(
       monaco.editor.createModel(activeBuffer.value, QuestDBLanguageName),
     )
-    setEditorReady(true)
     editorReadyTrigger(editor)
     isNavigatingFromSearchRef.current = false
 
@@ -941,41 +940,7 @@ const MonacoEditor = ({ hidden = false }: { hidden?: boolean }) => {
       }),
     )
 
-    // Prevent context menu from being clipped
-    const containerDomNode = editor.getContainerDomNode()
-    const contextMenuObserver = new MutationObserver((mutations) => {
-      for (const mutation of mutations) {
-        for (const node of Array.from(mutation.addedNodes)) {
-          if (
-            node instanceof HTMLElement &&
-            node.classList.contains("context-view") &&
-            node.classList.contains("monaco-menu-container")
-          ) {
-            const rect = node.getBoundingClientRect()
-            node.style.position = "fixed"
-            node.style.left = `${rect.left}px`
-            node.style.top = `${rect.top}px`
-
-            // Monaco reuses the node on subsequent opens, resetting styles.
-            const styleObserver = new MutationObserver(() => {
-              if (node.style.position !== "fixed") {
-                const rect = node.getBoundingClientRect()
-                node.style.position = "fixed"
-                node.style.left = `${rect.left}px`
-                node.style.top = `${rect.top}px`
-              }
-            })
-            styleObserver.observe(node, {
-              attributes: true,
-              attributeFilter: ["style"],
-            })
-            cleanupActionsRef.current.push(() => styleObserver.disconnect())
-          }
-        }
-      }
-    })
-    contextMenuObserver.observe(containerDomNode, { childList: true })
-    cleanupActionsRef.current.push(() => contextMenuObserver.disconnect())
+    cleanupActionsRef.current.push(pinMonacoContextMenu(editor))
 
     editor.onDidChangeCursorPosition((e) => {
       // To ensure the fixed position of the "run query" glyph we adjust the width of the line count element.
@@ -1826,7 +1791,12 @@ const MonacoEditor = ({ hidden = false }: { hidden?: boolean }) => {
         editor.updateOptions({ readOnly: true })
         const parentQuery = request.query
         const parentQueryKey = createQueryKeyFromRequest(editor, request)
-        questExecution.markActive(targetBufferId, parentQueryKey)
+        questExecution.markActive(targetBufferId, parentQueryKey, () => {
+          if (editorQueryIdRef.current !== null) {
+            quest.abort(editorQueryIdRef.current)
+            editorQueryIdRef.current = null
+          }
+        })
         const originalQueryText = request.selection
           ? request.selection.queryText
           : request.query
@@ -2115,26 +2085,6 @@ const MonacoEditor = ({ hidden = false }: { hidden?: boolean }) => {
     editorRef.current?.updateOptions({ readOnly: !!request })
   }, [request])
 
-  const setCompletionProvider = useCallback(() => {
-    if (editorReady && monacoRef?.current && editorRef?.current) {
-      schemaCompletionHandle?.dispose()
-      setRefreshingTables(true)
-      setSchemaCompletionHandle(
-        monacoRef.current.languages.registerCompletionItemProvider(
-          QuestDBLanguageName,
-          createSchemaCompletionProvider(tables, columns),
-        ),
-      )
-      setRefreshingTables(false)
-    }
-  }, [editorReady, schemaCompletionHandle, tables, columns])
-
-  useEffect(() => {
-    if (!refreshingTables) {
-      setCompletionProvider()
-    }
-  }, [tables, columns, monacoRef, editorReady])
-
   useEffect(() => {
     activeBufferRef.current = activeBuffer
     currentBufferValueRef.current = activeBuffer.value
@@ -2177,13 +2127,6 @@ const MonacoEditor = ({ hidden = false }: { hidden?: boolean }) => {
     }
   }, [aiStatus])
 
-  useEffect(() => {
-    window.addEventListener("focus", setCompletionProvider)
-    return () => {
-      window.removeEventListener("focus", setCompletionProvider)
-    }
-  }, [setCompletionProvider])
-
   useEffect(() => {
     const handler = (conversationId: unknown) => {
       if (!editorRef.current) return
diff --git a/src/scenes/Editor/Monaco/questdb-sql/useSchemaCompletionProvider.ts b/src/scenes/Editor/Monaco/questdb-sql/useSchemaCompletionProvider.ts
new file mode 100644
index 000000000..8d3ccaa6e
--- /dev/null
+++ b/src/scenes/Editor/Monaco/questdb-sql/useSchemaCompletionProvider.ts
@@ -0,0 +1,20 @@
+import { useEffect } from "react"
+import { useSelector } from "react-redux"
+import type { Monaco } from "@monaco-editor/react"
+import { createSchemaCompletionProvider } from "./createSchemaCompletionProvider"
+import { QuestDBLanguageName } from "../utils"
+import { selectors } from "../../../../store"
+
+export const useSchemaCompletionProvider = (monaco: Monaco | null) => {
+  const tables = useSelector(selectors.query.getTables)
+  const columns = useSelector(selectors.query.getColumns)
+
+  useEffect(() => {
+    if (!monaco) return
+    const handle = monaco.languages.registerCompletionItemProvider(
+      QuestDBLanguageName,
+      createSchemaCompletionProvider(tables, columns),
+    )
+    return () => handle.dispose()
+  }, [monaco, tables, columns])
+}
diff --git a/src/scenes/Editor/Monaco/tabs.tsx b/src/scenes/Editor/Monaco/tabs.tsx
index 1d042e2fa..901498a7f 100644
--- a/src/scenes/Editor/Monaco/tabs.tsx
+++ b/src/scenes/Editor/Monaco/tabs.tsx
@@ -2,12 +2,15 @@ import React, { useLayoutEffect, useState, useMemo } from "react"
 import styled, { css } from "styled-components"
 import { Tabs as ReactChromeTabs } from "../../../components/ReactChromeTabs"
 import { useEditor, MAX_TABS } from "../../../providers"
-import { File, History, LineChart, Trash } from "@styled-icons/boxicons-regular"
+import { History, LineChart, Trash } from "@styled-icons/boxicons-regular"
 import {
   DotsThreeVerticalIcon,
   DownloadSimpleIcon,
   UploadSimpleIcon,
+  NotebookIcon,
+  FileTextIcon,
 } from "@phosphor-icons/react"
+import { createDefaultNotebookViewState } from "../../../store/notebook"
 import { toast } from "../../../components/Toast"
 import { db } from "../../../store/db"
 import {
@@ -16,7 +19,8 @@ import {
   createBufferContentKey,
 } from "./importTabs"
 import { migrateBuffer, getCurrentDbVersion } from "../../../store/migrations"
-import { exportDB, importInto, peakImportFile } from "dexie-export-import"
+import { importInto, peakImportFile } from "dexie-export-import"
+import { exportBuffers } from "./exportTabs"
 import { ImportSummaryDialog, SkippedTab } from "./ImportSummaryDialog"
 import {
   Box,
@@ -63,8 +67,6 @@ const HistoryButton = styled(Button)`
 
 const DropdownMenuContent = styled(DropdownMenu.Content)`
   margin-top: 0.5rem;
-  z-index: 100;
-  background: ${({ theme }) => theme.color.backgroundDarker};
 `
 
 const ArchivedBuffersList = styled.div`
@@ -72,7 +74,21 @@ const ArchivedBuffersList = styled.div`
   overflow-y: auto;
 `
 
+// Invisible trigger we reposition to anchor Radix's menu at the chrome-tabs "+".
+const NewTabAnchor = styled(DropdownMenu.Trigger)`
+  position: fixed;
+  width: 0;
+  height: 0;
+  padding: 0;
+  border: 0;
+  opacity: 0;
+  pointer-events: none;
+`
+
 const mapTabIconToType = (buffer: Buffer) => {
+  if (buffer.notebookViewState) {
+    return "assets/icon-notebook.svg"
+  }
   if (buffer.metricsViewState) {
     return "assets/icon-chart.svg"
   }
@@ -98,6 +114,11 @@ export const Tabs = () => {
   const userLocale = useMemo(fetchUserLocale, [])
   const [historyOpen, setHistoryOpen] = useState(false)
   const [menuOpen, setMenuOpen] = useState(false)
+  const [newTabMenuOpen, setNewTabMenuOpen] = useState(false)
+  const [newTabMenuPos, setNewTabMenuPos] = useState<{
+    x: number
+    y: number
+  } | null>(null)
   const [importSummaryOpen, setImportSummaryOpen] = useState(false)
   const [importedCount, setImportedCount] = useState(0)
   const [skippedTabs, setSkippedTabs] = useState<SkippedTab[]>([])
@@ -105,23 +126,7 @@ export const Tabs = () => {
   const handleExportTabs = async () => {
     void trackEvent(ConsoleEvent.TAB_EXPORT)
     try {
-      const skipTables = db.tables
-        .map((t) => t.name)
-        .filter((name) => name !== "buffers")
-      const blob = await exportDB(db, {
-        skipTables,
-        filter: (table, value) => {
-          const buffer = value as Buffer
-          return !buffer.isTemporary && !buffer.isPreviewBuffer
-        },
-      })
-
-      const url = URL.createObjectURL(blob)
-      const a = document.createElement("a")
-      a.href = url
-      a.download = `questdb-tabs-${new Date().toISOString().replace(/[:.]/g, "-")}.json`
-      a.click()
-      URL.revokeObjectURL(url)
+      await exportBuffers()
     } catch (err) {
       console.error("Export error:", err)
       toast.error(
@@ -232,10 +237,25 @@ export const Tabs = () => {
               migratedValue as Record<string, unknown>,
             )
             if (validationResult !== true) {
-              const tabId = buffer.id !== undefined ? ` (id: ${buffer.id})` : ""
-              throw new Error(
-                `Validation failed for tab "${migratedValue.label}"${tabId}: ${validationResult}`,
-              )
+              skipped.push({
+                label:
+                  typeof migratedValue.label === "string"
+                    ? migratedValue.label
+                    : "Untitled",
+                reason: validationResult,
+                isMetricsTab: !!migratedValue.metricsViewState,
+              })
+              return {
+                value: {
+                  ...migratedValue,
+                  // Drop the source id; keeping it risks a primary-key
+                  // collision that aborts the whole import transaction. This
+                  // row is deleted post-import anyway.
+                  id: undefined,
+                  position: -1,
+                  _markedForDeletion: true,
+                },
+              }
             }
 
             const sanitized = sanitizeBuffer(
@@ -376,7 +396,8 @@ export const Tabs = () => {
     if (
       buffer?.value !== "" ||
       (buffer.metricsViewState?.metrics &&
-        buffer.metricsViewState.metrics.length > 0)
+        buffer.metricsViewState.metrics.length > 0) ||
+      buffer.notebookViewState != null
     ) {
       await archiveBuffer(parseInt(id))
     } else {
@@ -430,7 +451,12 @@ export const Tabs = () => {
 
   const handleNewTab = () => {
     if (tabsDisabled) return
-    void addBuffer()
+    const btn = document.querySelector(".chrome-tabs .new-tab-button-wrapper")
+    if (btn) {
+      const rect = btn.getBoundingClientRect()
+      setNewTabMenuPos({ x: rect.left, y: rect.top + 40 })
+    }
+    setNewTabMenuOpen(true)
   }
 
   useLayoutEffect(() => {
@@ -473,6 +499,9 @@ export const Tabs = () => {
           })
           .map((buffer) => {
             const classNames = []
+            if (buffer.notebookViewState) {
+              classNames.push("notebook-tab")
+            }
             if (buffer.metricsViewState) {
               classNames.push("metrics-tab")
             }
@@ -518,7 +547,7 @@ export const Tabs = () => {
         <DropdownMenu.Portal>
           <DropdownMenuContent data-hook="editor-tabs-history">
             {archivedBuffers.length === 0 ? (
-              <div style={{ padding: "0 1rem" }}>
+              <div style={{ padding: "0.5rem 1.4rem" }}>
                 <Text color="gray2">History is empty</Text>
               </div>
             ) : (
@@ -547,8 +576,10 @@ export const Tabs = () => {
                     >
                       {buffer.metricsViewState ? (
                         <LineChart size="18px" />
+                      ) : buffer.notebookViewState ? (
+                        <NotebookIcon size="18px" />
                       ) : (
-                        <File size="18px" />
+                        <FileTextIcon size="18px" />
                       )}
                       <Box
                         flexDirection="column"
@@ -643,6 +674,44 @@ export const Tabs = () => {
         importedCount={importedCount}
         skippedTabs={skippedTabs}
       />
+      <DropdownMenu.Root open={newTabMenuOpen} onOpenChange={setNewTabMenuOpen}>
+        <NewTabAnchor
+          aria-label="Open new tab menu"
+          style={{
+            left: newTabMenuPos?.x ?? 0,
+            top: newTabMenuPos?.y ?? 0,
+          }}
+        />
+        <DropdownMenu.Portal>
+          <DropdownMenu.Content
+            side="bottom"
+            align="start"
+            sideOffset={4}
+            onCloseAutoFocus={(e) => e.preventDefault()}
+          >
+            <DropdownMenu.Item
+              onSelect={() => {
+                void addBuffer()
+              }}
+              data-hook="new-tab-editor"
+            >
+              <FileTextIcon size={16} />
+              New editor
+            </DropdownMenu.Item>
+            <DropdownMenu.Item
+              onSelect={() => {
+                void addBuffer({
+                  notebookViewState: createDefaultNotebookViewState(),
+                })
+              }}
+              data-hook="new-tab-notebook"
+            >
+              <NotebookIcon size={16} />
+              New notebook
+            </DropdownMenu.Item>
+          </DropdownMenu.Content>
+        </DropdownMenu.Portal>
+      </DropdownMenu.Root>
     </Root>
   )
 }
diff --git a/src/scenes/Editor/Monaco/utils.test.ts b/src/scenes/Editor/Monaco/utils.test.ts
index 02883a90f..16dd80f29 100644
--- a/src/scenes/Editor/Monaco/utils.test.ts
+++ b/src/scenes/Editor/Monaco/utils.test.ts
@@ -1,5 +1,93 @@
 import { describe, it, expect } from "vitest"
-import { isCursorInComment, isCursorInQuotedIdentifier } from "./utils"
+import {
+  getQueriesFromText,
+  isCursorInComment,
+  isCursorInQuotedIdentifier,
+} from "./utils"
+
+describe("getQueriesFromText", () => {
+  it("splits two simple statements", () => {
+    expect(getQueriesFromText("SELECT 1; SELECT 2;")).toEqual([
+      "SELECT 1",
+      "SELECT 2",
+    ])
+  })
+
+  it("returns empty for empty input", () => {
+    expect(getQueriesFromText("")).toEqual([])
+    expect(getQueriesFromText("   \n  ")).toEqual([])
+  })
+
+  it("ignores semicolons inside strings", () => {
+    expect(getQueriesFromText("SELECT ';'; SELECT 'a;b'")).toEqual([
+      "SELECT ';'",
+      "SELECT 'a;b'",
+    ])
+  })
+
+  it("ignores semicolons in line comments", () => {
+    expect(
+      getQueriesFromText("SELECT 1 -- comment with ;\n; SELECT 2"),
+    ).toEqual(["SELECT 1 -- comment with ;", "SELECT 2"])
+  })
+
+  it("ignores semicolons in block comments", () => {
+    expect(getQueriesFromText("SELECT 1 /* a; b; */; SELECT 2")).toEqual([
+      "SELECT 1 /* a; b; */",
+      "SELECT 2",
+    ])
+  })
+
+  it("handles trailing statement with no semicolon", () => {
+    expect(getQueriesFromText("SELECT 1;\nSELECT 2")).toEqual([
+      "SELECT 1",
+      "SELECT 2",
+    ])
+  })
+
+  it("drops a trailing line-comment-only segment", () => {
+    expect(getQueriesFromText("select 1; -- note")).toEqual(["select 1"])
+  })
+
+  it("drops a trailing block-comment-only segment", () => {
+    expect(getQueriesFromText("select 1; /* note */")).toEqual(["select 1"])
+  })
+
+  it("drops standalone comment-only segments after the last statement", () => {
+    expect(
+      getQueriesFromText(
+        "--comment;\nselect 1;\n-- select /* comment */ 2;\n-- -- comment;",
+      ),
+    ).toEqual(["select 1"])
+  })
+
+  it("strips a leading comment but keeps a following statement", () => {
+    expect(
+      getQueriesFromText("--some comment;\nselect 1;\nselect /*comment*/ 2;\n"),
+    ).toEqual(["select 1", "select /*comment*/ 2"])
+  })
+
+  it("returns empty for comment-only input", () => {
+    expect(getQueriesFromText("-- just a comment")).toEqual([])
+    expect(getQueriesFromText("/* block only */")).toEqual([])
+  })
+
+  it("preserves WITH..SELECT and DECLARE prefixes (VWAP example)", () => {
+    const sql = `declare
+  @symbol := 'BTC-USDT'
+WITH sampled AS (SELECT 1 FROM trades)
+SELECT * FROM sampled;
+declare
+  @symbol := 'ETH-USDT'
+WITH sampled AS (SELECT 2 FROM trades)
+SELECT * FROM sampled;`
+    const out = getQueriesFromText(sql)
+    expect(out).toHaveLength(2)
+    expect(out[0]).toContain("BTC-USDT")
+    expect(out[0]).toContain("WITH sampled")
+    expect(out[1]).toContain("ETH-USDT")
+  })
+})
 
 describe("isCursorInComment", () => {
   it("returns false when cursor is in normal SQL", () => {
diff --git a/src/scenes/Editor/Monaco/utils.ts b/src/scenes/Editor/Monaco/utils.ts
index a5e1364dd..671f9e5ef 100644
--- a/src/scenes/Editor/Monaco/utils.ts
+++ b/src/scenes/Editor/Monaco/utils.ts
@@ -108,6 +108,25 @@ export const stripSQLComments = (text: string): string =>
     return match
   })
 
+export const getQueriesFromText = (text: string): string[] => {
+  if (!text || !stripSQLComments(text)) return []
+
+  const lines = text.split("\n")
+  const lastPosition: IPosition = {
+    lineNumber: lines.length,
+    column: (lines[lines.length - 1]?.length ?? 0) + 1,
+  }
+
+  const { sqlTextStack, nextSql } = getQueriesFromPositionInText(
+    text,
+    lastPosition,
+  )
+  const items = nextSql ? [...sqlTextStack, nextSql] : sqlTextStack
+  return items
+    .map((item) => text.substring(item.position, item.limit).trim())
+    .filter((query) => query.length > 0)
+}
+
 export const getSelectedText = (
   editor: IStandaloneCodeEditor,
 ): string | undefined => {
@@ -194,23 +213,16 @@ export const getQueriesToRun = (
   return requests.filter(Boolean) as Request[]
 }
 
-export const getQueriesFromPosition = (
-  editor: IStandaloneCodeEditor,
+export const getQueriesFromPositionInText = (
+  text: string,
   editorPosition: IPosition,
   startPosition?: IPosition,
 ): { sqlTextStack: SqlTextItem[]; nextSql: SqlTextItem | null } => {
-  const text = editor.getValue({ preserveBOM: false, lineEnding: "\n" })
-
-  if (!text || !stripSQLComments(text)) {
-    return { sqlTextStack: [], nextSql: null }
-  }
-
   const position = {
     row: editorPosition.lineNumber - 1,
     column: editorPosition.column,
   }
 
-  // Calculate starting position - default to beginning if not provided
   const start = startPosition
     ? {
         row: startPosition.lineNumber - 1,
@@ -218,14 +230,13 @@ export const getQueriesFromPosition = (
       }
     : { row: 0, column: 1 }
 
-  // Convert start position to character index
   let startCharIndex = 0
   if (startPosition) {
     const lines = text.split("\n")
     const maxRow = Math.min(start.row, lines.length - 1)
     for (let i = 0; i < maxRow; i++) {
       if (lines[i] !== undefined) {
-        startCharIndex += lines[i].length + 1 // +1 for newline character
+        startCharIndex += lines[i].length + 1
       }
     }
     if (lines[maxRow] !== undefined) {
@@ -453,8 +464,6 @@ export const getQueriesFromPosition = (
     }
   }
 
-  // lastStackItem is the last query that is completed before the current cursor position.
-  // nextSql is the next query that is not completed before the current cursor position, or started after the current cursor position.
   if (!nextSql) {
     const sqlText =
       startPos === -1
@@ -485,6 +494,20 @@ export const getQueriesFromPosition = (
   return { sqlTextStack: filteredSqlTextStack, nextSql: filteredNextSql }
 }
 
+export const getQueriesFromPosition = (
+  editor: IStandaloneCodeEditor,
+  editorPosition: IPosition,
+  startPosition?: IPosition,
+): { sqlTextStack: SqlTextItem[]; nextSql: SqlTextItem | null } => {
+  const text = editor.getValue({ preserveBOM: false, lineEnding: "\n" })
+
+  if (!text || !stripSQLComments(text)) {
+    return { sqlTextStack: [], nextSql: null }
+  }
+
+  return getQueriesFromPositionInText(text, editorPosition, startPosition)
+}
+
 export const getQueryFromCursor = (
   editor: IStandaloneCodeEditor,
 ): Request | undefined => {
@@ -749,6 +772,28 @@ export const getQueryRequestFromLastExecutedQuery = (
   }
 }
 
+export const getQueryRequestFromAISuggestion = (
+  editor: IStandaloneCodeEditor,
+  aiSuggestion: { query: string; startOffset: number },
+): Request | undefined => {
+  const model = editor.getModel()
+  if (!model) return undefined
+
+  const position = model.getPositionAt(aiSuggestion.startOffset)
+
+  const lines = aiSuggestion.query.split("\n")
+  const endRow = lines.length
+  const endColumn = lines[lines.length - 1].length + 1
+
+  return {
+    query: aiSuggestion.query,
+    row: position.lineNumber - 1,
+    column: position.column,
+    endRow: position.lineNumber - 1 + endRow - 1,
+    endColumn: endRow === 1 ? position.column + endColumn - 1 : endColumn,
+  }
+}
+
 export const getErrorRange = (
   editor: IStandaloneCodeEditor,
   request: Request,
@@ -929,14 +974,7 @@ export const normalizeQueryText = (query: string) => {
 }
 
 export const findMatches = (model: editor.ITextModel, needle: string) =>
-  model.findMatches(
-    needle /* searchString */,
-    true /* searchOnlyEditableRange */,
-    false /* isRegex */,
-    true /* matchCase */,
-    null /* wordSeparators */,
-    true /* captureMatches */,
-  ) ?? null
+  model.findMatches(needle, true, false, true, null, true) ?? null
 
 export const getLastPosition = (
   editor: IStandaloneCodeEditor,
@@ -1114,7 +1152,7 @@ export const cancelAllValidationRequests = () => {
 export const clearValidationMarkers = (
   monaco: Monaco | null,
   editor: IStandaloneCodeEditor | null,
-  bufferId?: number,
+  bufferId?: string | number,
 ) => {
   const model = editor?.getModel()
   if (model && monaco) {
@@ -1131,7 +1169,7 @@ export const clearValidationMarkers = (
 export const applyValidationMarkers = (
   monaco: Monaco,
   editor: IStandaloneCodeEditor,
-  bufferId: number,
+  bufferId: string | number,
 ) => {
   const model = editor.getModel()
   if (!model) return
@@ -1150,7 +1188,7 @@ export const applyValidationMarkers = (
 export const validateQueryJIT = (
   monaco: Monaco,
   editor: IStandaloneCodeEditor,
-  bufferId: number,
+  bufferId: string | number,
   getBufferExecutions: () => Record<QueryKey, unknown>,
   validateQuery: (
     query: string,
@@ -1175,7 +1213,6 @@ export const validateQueryJIT = (
   const queryText = normalizeQueryText(queryAtCursor.query)
   const version = model.getVersionId()
 
-  // Skip if already validated this exact query+version
   const cached = validationRefs[bufferKey]
   if (cached && cached.queryText === queryText && cached.version === version) {
     return
@@ -1189,7 +1226,6 @@ export const validateQueryJIT = (
     return
   }
 
-  // Skip if execution result already exists for this query
   const queryKey = createQueryKeyFromRequest(editor, queryAtCursor)
   const bufferExecutions = getBufferExecutions()
   if (bufferExecutions[queryKey]) {
@@ -1200,7 +1236,6 @@ export const validateQueryJIT = (
     return
   }
 
-  // Abort any previous in-flight validation for this buffer
   validationControllers[bufferKey]?.abort()
   const controller = new AbortController()
   validationControllers[bufferKey] = controller
@@ -1221,7 +1256,6 @@ export const validateQueryJIT = (
         return
       }
 
-      // Query was executed while validation was in flight — skip
       if (getBufferExecutions()[queryKey]) return
 
       if ("error" in result) {
@@ -1257,15 +1291,12 @@ export const validateQueryJIT = (
       }
     })
     .catch(() => {
-      // Abort or network error — silently ignore
       if (validationControllers[bufferKey] === controller) {
         delete validationControllers[bufferKey]
       }
     })
 }
 
-// Creates a QueryKey for schema explanation conversations
-// Uses DDL hash so same schema = same queryKey = cached conversation
 export const createSchemaQueryKey = (
   tableName: string,
   ddl: string,
@@ -1274,37 +1305,29 @@ export const createSchemaQueryKey = (
   return `schema:${tableName}:${ddlHash}@0-0` as QueryKey
 }
 
-/**
- * Check if cursor is inside a line comment (--) or block comment.
- * Skips over string literals and quoted identifiers so quotes
- * inside comments don't cause false positives.
- */
 export function isCursorInComment(text: string, cursorOffset: number): boolean {
   let i = 0
   const end = Math.min(cursorOffset, text.length)
   while (i < end) {
     const ch = text[i]
     const next = text[i + 1]
-    // Line comment: -- until end of line
     if (ch === "-" && next === "-") {
       i += 2
       while (i < end && text[i] !== "\n") i++
       if (i >= cursorOffset) return true
       continue
     }
-    // Block comment: /* until */
     if (ch === "/" && next === "*") {
       i += 2
       while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++
       if (i >= cursorOffset) return true
-      i += 2 // skip */
+      i += 2
       continue
     }
-    // Skip over string literals and quoted identifiers so quotes inside comments don't confuse us
     if (ch === "'" || ch === '"') {
       i++
       while (i < text.length && text[i] !== ch) i++
-      i++ // skip closing quote
+      i++
       continue
     }
     i++
@@ -1312,12 +1335,7 @@ export function isCursorInComment(text: string, cursorOffset: number): boolean {
   return false
 }
 
-/**
- * Check if cursor is inside a double-quoted identifier (e.g. "my-table").
- * Tracks quote state from `startOffset` to `cursorOffset`, handling
- * escaped quotes (""), single-quoted strings, and comments.
- * Returns the offset of the opening " if inside, or -1 if not.
- */
+// Returns the offset of the opening `"` if cursor is inside a double-quoted identifier, else -1.
 export function isCursorInQuotedIdentifier(
   text: string,
   startOffset: number,
@@ -1338,14 +1356,12 @@ export function isCursorInQuotedIdentifier(
       if (ch === '"' && next === '"') i++
       else if (ch === '"') inDouble = false
     } else if (ch === "-" && next === "-") {
-      // Skip line comment
       i += 2
       while (i < cursorOffset && text[i] !== "\n") i++
     } else if (ch === "/" && next === "*") {
-      // Skip block comment
       i += 2
       while (i < cursorOffset && !(text[i] === "*" && text[i + 1] === "/")) i++
-      i++ // skip past */
+      i++
     } else if (ch === '"') {
       inDouble = true
       openQuoteOffset = i
@@ -1355,3 +1371,46 @@ export function isCursorInQuotedIdentifier(
   }
   return inDouble ? openQuoteOffset : -1
 }
+
+export const pinMonacoContextMenu = (
+  editor: IStandaloneCodeEditor,
+): (() => void) => {
+  const cleanups: Array<() => void> = []
+  const containerDomNode = editor.getContainerDomNode()
+  const contextMenuObserver = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      for (const node of Array.from(mutation.addedNodes)) {
+        if (
+          node instanceof HTMLElement &&
+          node.classList.contains("context-view") &&
+          node.classList.contains("monaco-menu-container")
+        ) {
+          const rect = node.getBoundingClientRect()
+          node.style.position = "fixed"
+          node.style.left = `${rect.left}px`
+          node.style.top = `${rect.top}px`
+
+          // Monaco reuses the node on subsequent opens, resetting styles.
+          const styleObserver = new MutationObserver(() => {
+            if (node.style.position !== "fixed") {
+              const rect = node.getBoundingClientRect()
+              node.style.position = "fixed"
+              node.style.left = `${rect.left}px`
+              node.style.top = `${rect.top}px`
+            }
+          })
+          styleObserver.observe(node, {
+            attributes: true,
+            attributeFilter: ["style"],
+          })
+          cleanups.push(() => styleObserver.disconnect())
+        }
+      }
+    }
+  })
+  contextMenuObserver.observe(containerDomNode, { childList: true })
+  cleanups.push(() => contextMenuObserver.disconnect())
+  return () => {
+    for (const c of cleanups) c()
+  }
+}
diff --git a/src/scenes/Editor/Notebook/CellChart/ChartActions.tsx b/src/scenes/Editor/Notebook/CellChart/ChartActions.tsx
new file mode 100644
index 000000000..b043aaf16
--- /dev/null
+++ b/src/scenes/Editor/Notebook/CellChart/ChartActions.tsx
@@ -0,0 +1,163 @@
+import React from "react"
+import styled from "styled-components"
+import {
+  ArrowClockwiseIcon,
+  ArrowsInLineVerticalIcon,
+  ArrowsOutLineVerticalIcon,
+  GearIcon,
+} from "@phosphor-icons/react"
+import { Reset } from "@styled-icons/boxicons-regular"
+import { Button, Tooltip } from "../../../../components"
+import { Switch } from "../../../../components/Switch"
+import { CellToolbar } from "../cells/CellToolbar"
+
+// Chart maximize uses ArrowsOutLineVertical/ArrowsInLineVertical (maximize INTO the cell)
+// to stay visually distinct from the cell's CornersOut/CornersIn (maximize INTO the buffer).
+const Bar = styled.div<{ $maximized: boolean }>`
+  flex-shrink: 0;
+  z-index: 2;
+  height: 4rem;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.8rem;
+  padding: 0 1rem;
+  background: ${({ theme }) => theme.color.backgroundDarker};
+  border-bottom: 1px solid ${({ theme }) => theme.color.selection};
+
+  ${({ $maximized }) =>
+    $maximized &&
+    `
+      cursor: grab;
+
+      &:active {
+        cursor: grabbing;
+      }
+    `}
+`
+
+const Name = styled.span`
+  min-width: 0;
+  font-size: 1.6rem;
+  font-weight: 600;
+  color: ${({ theme }) => theme.color.foreground};
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+`
+
+const ToggleGroup = styled.div`
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  flex-shrink: 0;
+`
+
+const Cluster = styled.div`
+  display: flex;
+  align-items: center;
+  gap: 0.8rem;
+  flex-shrink: 0;
+`
+
+const ToggleLabel = styled.span`
+  font-size: 1.1rem;
+  color: ${({ theme }) => theme.color.gray2};
+  user-select: none;
+`
+
+const ResetIcon = styled(Reset)`
+  width: 1.8rem;
+  height: 1.8rem;
+`
+
+type Props = {
+  name?: string
+  autoRefresh: boolean
+  onAutoRefreshChange: (value: boolean) => void
+  onManualRefresh: () => void
+  isMaximized: boolean
+  onMaximizedChange: (maximized: boolean) => void
+  onOpenSettings: () => void
+  canResetZoom?: boolean
+  onResetZoom?: () => void
+  cellId?: string
+}
+
+export const ChartActions: React.FC<Props> = ({
+  name,
+  autoRefresh,
+  onAutoRefreshChange,
+  onManualRefresh,
+  isMaximized,
+  onMaximizedChange,
+  onOpenSettings,
+  canResetZoom,
+  onResetZoom,
+  cellId,
+}) => (
+  <Bar
+    data-hook="chart-actions"
+    $maximized={isMaximized}
+    className={isMaximized ? "cell-drag-handle" : undefined}
+  >
+    <Name title={name}>{name}</Name>
+    <Cluster>
+      <ToggleGroup>
+        <ToggleLabel>Auto-refresh</ToggleLabel>
+        <Switch checked={autoRefresh} onChange={onAutoRefreshChange} />
+      </ToggleGroup>
+      {canResetZoom && onResetZoom && (
+        <Tooltip content="Reset zoom">
+          <Button
+            skin="transparent"
+            type="button"
+            onClick={onResetZoom}
+            aria-label="Reset zoom"
+          >
+            <ResetIcon />
+          </Button>
+        </Tooltip>
+      )}
+      {!autoRefresh && (
+        <Tooltip content="Refresh chart">
+          <Button
+            skin="transparent"
+            type="button"
+            onClick={onManualRefresh}
+            aria-label="Refresh chart"
+          >
+            <ArrowClockwiseIcon size={18} />
+          </Button>
+        </Tooltip>
+      )}
+      <Tooltip content={isMaximized ? "Restore chart" : "Maximize chart"}>
+        <Button
+          skin="transparent"
+          type="button"
+          onClick={() => onMaximizedChange(!isMaximized)}
+          aria-label={isMaximized ? "Restore chart" : "Maximize chart"}
+        >
+          {isMaximized ? (
+            <ArrowsInLineVerticalIcon size={18} />
+          ) : (
+            <ArrowsOutLineVerticalIcon size={18} />
+          )}
+        </Button>
+      </Tooltip>
+      <Tooltip content="Chart settings">
+        <Button
+          skin="transparent"
+          type="button"
+          onClick={onOpenSettings}
+          aria-label="Chart settings"
+        >
+          <GearIcon size={18} />
+        </Button>
+      </Tooltip>
+      {isMaximized && cellId !== undefined && (
+        <CellToolbar inline cellId={cellId} />
+      )}
+    </Cluster>
+  </Bar>
+)
diff --git a/src/scenes/Editor/Notebook/CellChart/ChartRenderer.tsx b/src/scenes/Editor/Notebook/CellChart/ChartRenderer.tsx
new file mode 100644
index 000000000..478b99cbc
--- /dev/null
+++ b/src/scenes/Editor/Notebook/CellChart/ChartRenderer.tsx
@@ -0,0 +1,168 @@
+import React, { useEffect, useImperativeHandle, useMemo, useRef } from "react"
+import ReactECharts from "echarts-for-react/lib/core"
+import type { EChartsOption } from "echarts"
+import { echarts, QUESTDB_THEME } from "./echartsSetup"
+
+export type ChartRendererHandle = {
+  resetZoom: () => void
+}
+
+type Props = {
+  option: EChartsOption
+  height?: number | string
+  onZoomChange?: (start: number, end: number) => void
+  isFocused?: boolean
+}
+
+// Structural fingerprint — we remount on changes here so stale series from
+// the prior option don't linger; routine data refreshes keep the key stable
+// so dataZoom state survives the merge.
+const structuralKey = (option: EChartsOption): string => {
+  const rawSeries = option.series
+  const series = Array.isArray(rawSeries)
+    ? rawSeries
+    : rawSeries
+      ? [rawSeries]
+      : []
+  const seriesTypes = series.map((s) => {
+    const spec = s as {
+      type?: string
+      areaStyle?: unknown
+      step?: unknown
+      stack?: unknown
+    }
+    return [
+      spec.type ?? "",
+      spec.areaStyle ? "a" : "",
+      spec.step ? "s" : "",
+      spec.stack ? "k" : "",
+    ].join("")
+  })
+  const xAxis = Array.isArray(option.xAxis) ? option.xAxis[0] : option.xAxis
+  const yAxis = Array.isArray(option.yAxis) ? option.yAxis[0] : option.yAxis
+  const hasZoom = Array.isArray(option.dataZoom) && option.dataZoom.length > 0
+  const axisCount = Array.isArray(option.yAxis) ? "2y" : "1y"
+  return [
+    seriesTypes.join("|"),
+    (xAxis as { type?: string } | undefined)?.type ?? "",
+    (yAxis as { type?: string } | undefined)?.type ?? "",
+    axisCount,
+    hasZoom ? "z" : "nz",
+  ].join("::")
+}
+
+type DataZoomEvent = {
+  start?: number
+  end?: number
+  batch?: Array<{ start?: number; end?: number }>
+}
+
+export const ChartRenderer = React.forwardRef<ChartRendererHandle, Props>(
+  function ChartRenderer(
+    { option, height = "100%", onZoomChange, isFocused = true },
+    ref,
+  ) {
+    const reactEchartsRef = useRef<ReactECharts | null>(null)
+    const wrapperRef = useRef<HTMLDivElement | null>(null)
+
+    // Capture-phase wheel listener must intercept BEFORE ECharts' inner
+    // listeners so the page scrolls instead of ECharts preventDefaulting.
+    useEffect(() => {
+      if (isFocused) return
+      const node = wrapperRef.current
+      if (!node) return
+      const stop = (e: WheelEvent) => {
+        e.stopPropagation()
+      }
+      node.addEventListener("wheel", stop, { capture: true })
+      return () => node.removeEventListener("wheel", stop, { capture: true })
+    }, [isFocused])
+
+    useEffect(() => {
+      const wrapper = wrapperRef.current
+      if (!wrapper) return
+
+      const resizeTo = (width: number, height: number) => {
+        if (width === 0 || height === 0) return
+        reactEchartsRef.current?.getEchartsInstance()?.resize({ width, height })
+      }
+
+      const observer = new ResizeObserver((entries) => {
+        const box = entries[0]?.contentRect
+        if (box) resizeTo(box.width, box.height)
+      })
+      observer.observe(wrapper)
+
+      const handleVisibility = () => {
+        if (document.visibilityState !== "visible") return
+        requestAnimationFrame(() => {
+          const rect = wrapper.getBoundingClientRect()
+          resizeTo(rect.width, rect.height)
+        })
+      }
+      document.addEventListener("visibilitychange", handleVisibility)
+
+      return () => {
+        observer.disconnect()
+        document.removeEventListener("visibilitychange", handleVisibility)
+      }
+    }, [])
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        resetZoom: () => {
+          const instance = reactEchartsRef.current?.getEchartsInstance()
+          instance?.dispatchAction({
+            type: "dataZoom",
+            start: 0,
+            end: 100,
+          })
+        },
+      }),
+      [],
+    )
+
+    const key = useMemo(() => structuralKey(option), [option])
+
+    const events = useMemo(() => {
+      if (!onZoomChange) return undefined
+      return {
+        datazoom: (evt: unknown) => {
+          const e = evt as DataZoomEvent
+          const first = e.batch?.[0] ?? e
+          if (
+            typeof first.start === "number" &&
+            typeof first.end === "number"
+          ) {
+            onZoomChange(first.start, first.end)
+          }
+        },
+      }
+    }, [onZoomChange])
+
+    return (
+      <div
+        ref={wrapperRef}
+        style={{
+          width: "100%",
+          height: typeof height === "number" ? `${height}px` : height,
+        }}
+      >
+        <ReactECharts
+          key={key}
+          ref={reactEchartsRef}
+          echarts={echarts}
+          option={option}
+          theme={QUESTDB_THEME}
+          notMerge={false}
+          lazyUpdate
+          autoResize={false}
+          onEvents={events}
+          style={{ height: "100%", width: "100%" }}
+          opts={{ renderer: "canvas" }}
+        />
+      </div>
+    )
+  },
+)
diff --git a/src/scenes/Editor/Notebook/CellChart/ChartSettingsDrawer.tsx b/src/scenes/Editor/Notebook/CellChart/ChartSettingsDrawer.tsx
new file mode 100644
index 000000000..ca3572455
--- /dev/null
+++ b/src/scenes/Editor/Notebook/CellChart/ChartSettingsDrawer.tsx
@@ -0,0 +1,390 @@
+import React, { useEffect, useState } from "react"
+import styled, { keyframes } from "styled-components"
+import { XIcon } from "@phosphor-icons/react"
+import { Button, Input } from "../../../../components"
+import { Select } from "../../../../components/Select"
+import type { ChartConfig, QueryChart } from "./chartTypes"
+import { groupColumns } from "./inferChartConfig"
+import type { QueryTab } from "../DrawCanvas/drawCanvasUtils"
+import {
+  Field,
+  FieldGroup,
+  FieldLabel,
+  IncompatibleIcon,
+} from "./chartSettingsStyles"
+import { QueryControls } from "./QueryControls"
+
+const fadeIn = keyframes`
+  from { opacity: 0; }
+  to { opacity: 1; }
+`
+
+const slideIn = keyframes`
+  from { transform: translateX(100%); }
+  to { transform: translateX(0); }
+`
+
+const Backdrop = styled.div`
+  position: absolute;
+  inset: 0;
+  z-index: 3;
+  background: rgba(0, 0, 0, 0.35);
+  animation: ${fadeIn} 0.2s ease both;
+`
+
+const Panel = styled.div`
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: min(36rem, 90%);
+  z-index: 4;
+  background: ${({ theme }) => theme.color.backgroundDarker};
+  border-left: 1px solid ${({ theme }) => theme.color.selection};
+  display: flex;
+  flex-direction: column;
+  animation: ${slideIn} 0.25s cubic-bezier(0.16, 1, 0.3, 1) both;
+`
+
+const Header = styled.div`
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 1rem 1.2rem;
+  border-bottom: 1px solid ${({ theme }) => theme.color.selection};
+`
+
+const Title = styled.h3`
+  margin: 0;
+  font-size: 1.4rem;
+  font-weight: 600;
+  color: ${({ theme }) => theme.color.foreground};
+`
+
+const Body = styled.form`
+  flex: 1;
+  overflow-y: auto;
+  padding: 1.2rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1.4rem;
+
+  /* [aria-haspopup="menu"] covers the MultiSelect trigger (a styled menu
+     button) so it matches the native inputs/selects in this form. */
+  input,
+  select,
+  textarea,
+  [aria-haspopup="menu"] {
+    font-size: 1.4rem;
+    font-weight: 400;
+    background: ${({ theme }) => theme.color.inputBackground};
+    border-color: ${({ theme }) => theme.color.selection};
+
+    &:focus {
+      background: ${({ theme }) => theme.color.inputBackground};
+    }
+  }
+`
+
+const Row = styled.div`
+  display: flex;
+  gap: 0.8rem;
+  & > * {
+    flex: 1 1 0;
+    min-width: 0;
+  }
+`
+
+const Footer = styled.div`
+  padding: 1rem 1.2rem;
+  border-top: 1px solid ${({ theme }) => theme.color.selection};
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.8rem;
+`
+
+const Divider = styled.div`
+  border-top: 1px solid ${({ theme }) => theme.color.selection};
+`
+
+const TabStrip = styled.div`
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.2rem;
+  border-bottom: 1px solid ${({ theme }) => theme.color.selection};
+`
+
+const Tab = styled.button<{ active: boolean }>`
+  flex: 0 0 auto;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  white-space: nowrap;
+  padding: 0.8rem 1.4rem;
+  border: none;
+  border-bottom: 2px solid
+    ${({ active, theme }) => (active ? theme.color.pink : "transparent")};
+  margin-bottom: -1px;
+  background: ${({ active, theme }) =>
+    active ? theme.color.backgroundLighter : "transparent"};
+  color: ${({ active, theme }) =>
+    active ? theme.color.foreground : theme.color.gray2};
+  cursor: pointer;
+  font-size: 1.3rem;
+
+  &:hover {
+    color: ${({ theme }) => theme.color.foreground};
+  }
+`
+
+const parseBound = (v: string): number | undefined => {
+  const n = Number(v)
+  return v === "" || !Number.isFinite(n) ? undefined : n
+}
+
+const candlestickMissingOhlc = (q: QueryChart | null): boolean => {
+  if (!q || q.type !== "candlestick" || q.enabled === false) return false
+  const o = q.ohlc
+  if (!o || !o.open || !o.high || !o.low || !o.close) return true
+  return new Set([o.open, o.high, o.low, o.close]).size !== 4
+}
+
+type Props = {
+  open: boolean
+  onClose: () => void
+  tabs: QueryTab[]
+  config: ChartConfig
+  onSave: (next: ChartConfig) => void
+}
+
+export const ChartSettingsDrawer: React.FC<Props> = ({
+  open,
+  onClose,
+  tabs,
+  config,
+  onSave,
+}) => {
+  const [draft, setDraft] = useState<ChartConfig>(config)
+  const [activeIndex, setActiveIndex] = useState<number>(tabs[0]?.index ?? 0)
+  const [saveAttempted, setSaveAttempted] = useState(false)
+
+  useEffect(() => {
+    if (open) {
+      setDraft(config)
+      setActiveIndex(tabs[0]?.index ?? 0)
+      setSaveAttempted(false)
+    }
+  }, [open])
+
+  useEffect(() => {
+    if (!open) return
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape") return
+      if (
+        document.querySelector("[data-radix-popper-content-wrapper]") !== null
+      ) {
+        return
+      }
+      onClose()
+      e.stopImmediatePropagation()
+    }
+    window.addEventListener("keydown", onKey, { capture: true })
+    return () => window.removeEventListener("keydown", onKey, { capture: true })
+  }, [open, onClose])
+
+  if (!open) return null
+
+  const anchorTab = tabs[0]
+  const anchorGroups = anchorTab
+    ? groupColumns(anchorTab.columns)
+    : { temporal: [], numeric: [], categorical: [], other: [] }
+  const xCandidates = [
+    ...anchorGroups.temporal,
+    ...anchorGroups.categorical,
+    ...anchorGroups.numeric,
+  ]
+
+  const activeTab = tabs.find((t) => t.index === activeIndex) ?? anchorTab
+  const isAnchorTab = activeTab != null && activeTab.index === anchorTab?.index
+  const query: QueryChart | undefined =
+    activeTab != null
+      ? (draft.queries[activeTab.index] ?? undefined)
+      : undefined
+
+  const hasRight = draft.queries.some((q) => q?.axis === "right")
+
+  const updateQuery = (index: number, patch: Partial<QueryChart>) =>
+    setDraft((d) => ({
+      ...d,
+      queries: d.queries.map((q, i) =>
+        i === index && q ? { ...q, ...patch } : q,
+      ),
+    }))
+
+  const setQuery = (index: number, next: QueryChart) =>
+    setDraft((d) => ({
+      ...d,
+      queries: d.queries.map((q, i) => (i === index ? next : q)),
+    }))
+
+  const commit = () => {
+    const badIdx = draft.queries.findIndex(candlestickMissingOhlc)
+    if (badIdx >= 0) {
+      setSaveAttempted(true)
+      setActiveIndex(badIdx)
+      return
+    }
+    onSave(draft)
+    onClose()
+  }
+
+  return (
+    <>
+      <Backdrop onClick={onClose} aria-hidden />
+      <Panel role="dialog" aria-label="Chart settings">
+        <Header>
+          <Title>Chart settings</Title>
+          <Button
+            skin="transparent"
+            type="button"
+            onClick={onClose}
+            aria-label="Close chart settings"
+          >
+            <XIcon size={18} />
+          </Button>
+        </Header>
+
+        <Body
+          onSubmit={(e) => {
+            e.preventDefault()
+            commit()
+          }}
+        >
+          <Field>
+            <FieldLabel>Name</FieldLabel>
+            <Input
+              name="chart-name"
+              placeholder="e.g. Daily trades"
+              value={draft.name ?? ""}
+              onChange={(e) =>
+                setDraft((d) => ({ ...d, name: e.target.value }))
+              }
+            />
+          </Field>
+
+          <Field>
+            <FieldLabel>X-axis</FieldLabel>
+            <Select
+              name="x-axis"
+              value={draft.xColumn ?? ""}
+              onChange={(e) =>
+                setDraft((d) => ({ ...d, xColumn: e.target.value || null }))
+              }
+              options={xCandidates.map((c) => ({
+                label: c.name,
+                value: c.name,
+              }))}
+            />
+          </Field>
+
+          {hasRight && (
+            <FieldGroup>
+              <FieldLabel>Right axis</FieldLabel>
+              <Input
+                name="right-axis-name"
+                placeholder="Name (e.g. RSI)"
+                value={draft.rightAxis?.name ?? ""}
+                onChange={(e) =>
+                  setDraft((d) => ({
+                    ...d,
+                    rightAxis: { ...d.rightAxis, name: e.target.value },
+                  }))
+                }
+              />
+              <Row>
+                <Input
+                  name="right-axis-min"
+                  type="number"
+                  placeholder="min"
+                  value={draft.rightAxis?.min ?? ""}
+                  onChange={(e) =>
+                    setDraft((d) => ({
+                      ...d,
+                      rightAxis: {
+                        ...d.rightAxis,
+                        min: parseBound(e.target.value),
+                      },
+                    }))
+                  }
+                />
+                <Input
+                  name="right-axis-max"
+                  type="number"
+                  placeholder="max"
+                  value={draft.rightAxis?.max ?? ""}
+                  onChange={(e) =>
+                    setDraft((d) => ({
+                      ...d,
+                      rightAxis: {
+                        ...d.rightAxis,
+                        max: parseBound(e.target.value),
+                      },
+                    }))
+                  }
+                />
+              </Row>
+            </FieldGroup>
+          )}
+
+          {tabs.length > 1 && (
+            <>
+              <Divider />
+              <FieldLabel>Queries</FieldLabel>
+              <TabStrip>
+                {tabs.map((t) => (
+                  <Tab
+                    key={t.index}
+                    type="button"
+                    active={t.index === activeIndex}
+                    onClick={() => setActiveIndex(t.index)}
+                    title={
+                      t.compatible
+                        ? t.query
+                        : `${t.query}\n\n(x-axis incompatible — excluded)`
+                    }
+                  >
+                    {t.label}
+                    {!t.compatible && (
+                      <IncompatibleIcon size={14} weight="fill" />
+                    )}
+                  </Tab>
+                ))}
+              </TabStrip>
+            </>
+          )}
+
+          {activeTab && query && (
+            <QueryControls
+              activeTab={activeTab}
+              query={query}
+              anchorLabel={anchorTab?.label ?? "Q1"}
+              isAnchorTab={isAnchorTab}
+              ohlcError={saveAttempted && candlestickMissingOhlc(query)}
+              onUpdateQuery={(patch) => updateQuery(activeTab.index, patch)}
+              onSetQuery={(next) => setQuery(activeTab.index, next)}
+            />
+          )}
+        </Body>
+
+        <Footer>
+          <Button type="button" skin="secondary" onClick={onClose}>
+            Cancel
+          </Button>
+          <Button type="button" skin="primary" onClick={commit}>
+            Save
+          </Button>
+        </Footer>
+      </Panel>
+    </>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/CellChart/QueryControls.tsx b/src/scenes/Editor/Notebook/CellChart/QueryControls.tsx
new file mode 100644
index 000000000..fed608a75
--- /dev/null
+++ b/src/scenes/Editor/Notebook/CellChart/QueryControls.tsx
@@ -0,0 +1,308 @@
+import React from "react"
+import styled from "styled-components"
+import { Button, CopyButton, MultiSelect, Text } from "../../../../components"
+import { Select } from "../../../../components/Select"
+import { HighlightedSql } from "../../../../components/HighlightedSql"
+import type { ChartType, QueryChart, SeriesAxis } from "./chartTypes"
+import { availableChartTypes, findOhlc, groupColumns } from "./inferChartConfig"
+import type { QueryTab } from "../DrawCanvas/drawCanvasUtils"
+import {
+  Field,
+  FieldGroup,
+  FieldLabel,
+  IncompatibleIcon,
+} from "./chartSettingsStyles"
+
+const TYPE_LABELS: Record<ChartType, string> = {
+  line: "Line",
+  area: "Area",
+  stepLine: "Step line",
+  stepArea: "Step area",
+  bar: "Bar",
+  stackedBar: "Stacked bar",
+  scatter: "Scatter",
+  pie: "Pie",
+  candlestick: "Candlestick",
+}
+
+const PARTITION_TYPES: ChartType[] = [
+  "line",
+  "area",
+  "stepLine",
+  "stepArea",
+  "bar",
+  "stackedBar",
+  "scatter",
+]
+
+const QueryCard = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+`
+
+const QueryLabelRow = styled.div`
+  display: flex;
+  align-items: center;
+  gap: 0.8rem;
+`
+
+const SqlPre = styled(HighlightedSql)`
+  margin: 0;
+  padding: 0.7rem;
+  max-height: 9rem;
+  overflow: auto;
+  background: ${({ theme }) => theme.color.backgroundDarker};
+  border: 1px solid ${({ theme }) => theme.color.selection};
+  border-radius: 0.4rem;
+  color: ${({ theme }) => theme.color.foreground};
+  font-family: ${({ theme }) => theme.fontMonospace};
+  font-size: 1.1rem;
+`
+
+const CheckboxRow = styled.label`
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 1.2rem;
+  color: ${({ theme }) => theme.color.foreground};
+  cursor: pointer;
+`
+
+const OhlcGrid = styled.div`
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 0.8rem;
+`
+
+const MiniField = styled.label`
+  display: flex;
+  flex-direction: column;
+  gap: 0.3rem;
+  min-width: 0;
+`
+
+const IncompatibleNote = styled.div`
+  display: flex;
+  align-items: flex-start;
+  gap: 0.5rem;
+  padding: 0.5rem;
+`
+
+export type QueryControlsProps = {
+  activeTab: QueryTab
+  query: QueryChart
+  anchorLabel: string
+  isAnchorTab: boolean
+  ohlcError: boolean
+  onUpdateQuery: (patch: Partial<QueryChart>) => void
+  onSetQuery: (next: QueryChart) => void
+}
+
+export const QueryControls: React.FC<QueryControlsProps> = ({
+  activeTab,
+  query,
+  anchorLabel,
+  isAnchorTab,
+  ohlcError,
+  onUpdateQuery,
+  onSetQuery,
+}) => {
+  const groups = groupColumns(activeTab.columns)
+  const hasOhlc = !!findOhlc(groups.numeric)
+  const baseTypes = availableChartTypes(groups, hasOhlc)
+  const types = baseTypes.includes(query.type)
+    ? baseTypes
+    : [query.type, ...baseTypes]
+  const numericOptions = groups.numeric.map((c) => ({
+    label: c.name,
+    value: c.name,
+  }))
+  const idx = activeTab.index
+
+  return (
+    <QueryCard>
+      <FieldGroup>
+        <QueryLabelRow>
+          <FieldLabel>Query</FieldLabel>
+          <CopyButton type="button" text={activeTab.query} size="sm" iconOnly />
+        </QueryLabelRow>
+        <SqlPre code={activeTab.query} />
+      </FieldGroup>
+
+      {!activeTab.compatible && (
+        <IncompatibleNote>
+          <IncompatibleIcon size={14} weight="fill" />
+          <Text color="orange" size="xs" lineHeight="1.2">
+            {`This query has a different x-axis kind from ${anchorLabel}. It cannot combine and is hidden from the chart.`}
+          </Text>
+        </IncompatibleNote>
+      )}
+
+      {!isAnchorTab && (
+        <CheckboxRow>
+          <input
+            type="checkbox"
+            checked={query.enabled !== false}
+            onChange={(e) =>
+              onUpdateQuery({
+                enabled: e.target.checked ? undefined : false,
+              })
+            }
+          />
+          Include in chart
+        </CheckboxRow>
+      )}
+
+      <Field>
+        <FieldLabel>Type</FieldLabel>
+        <Select
+          name={`type-${idx}`}
+          value={query.type}
+          onChange={(e) => {
+            const type = e.target.value as ChartType
+            const patch: Partial<QueryChart> = { type }
+            if (type === "candlestick" && !query.ohlc) {
+              const oh = findOhlc(groups.numeric)
+              if (oh) patch.ohlc = oh
+            }
+            onUpdateQuery(patch)
+          }}
+          options={types.map((t) => ({ label: TYPE_LABELS[t], value: t }))}
+        />
+      </Field>
+
+      {query.type === "candlestick" && (
+        <FieldGroup>
+          <OhlcGrid>
+            {(
+              [
+                ["open", "Open"],
+                ["high", "High"],
+                ["low", "Low"],
+                ["close", "Close"],
+              ] as const
+            ).map(([k, label]) => (
+              <MiniField key={k}>
+                <Text color="gray2" size="xs">
+                  {label}
+                </Text>
+                <Select
+                  name={`ohlc-${k}-${idx}`}
+                  value={query.ohlc?.[k] ?? ""}
+                  onChange={(e) =>
+                    onUpdateQuery({
+                      ohlc: {
+                        open: "",
+                        high: "",
+                        low: "",
+                        close: "",
+                        ...query.ohlc,
+                        [k]: e.target.value,
+                      },
+                    })
+                  }
+                  options={[
+                    { label: "Select column", value: "" },
+                    ...numericOptions,
+                  ]}
+                />
+              </MiniField>
+            ))}
+          </OhlcGrid>
+          {ohlcError && (
+            <IncompatibleNote>
+              <IncompatibleIcon size={14} weight="fill" />
+              <Text color="orange" size="xs" lineHeight="1.2">
+                Map all four OHLC fields to distinct numeric columns
+              </Text>
+            </IncompatibleNote>
+          )}
+        </FieldGroup>
+      )}
+
+      {query.type === "pie" && (
+        <Field>
+          <FieldLabel>Value</FieldLabel>
+          <Select
+            name={`value-${idx}`}
+            value={query.yColumns[0] ?? ""}
+            onChange={(e) =>
+              onUpdateQuery({
+                yColumns: e.target.value ? [e.target.value] : [],
+              })
+            }
+            options={[{ label: "Select column", value: "" }, ...numericOptions]}
+          />
+        </Field>
+      )}
+
+      {(query.type === "line" ||
+        query.type === "area" ||
+        query.type === "stepLine" ||
+        query.type === "stepArea" ||
+        query.type === "bar" ||
+        query.type === "stackedBar" ||
+        query.type === "scatter") && (
+        <Field>
+          <FieldLabel>Series</FieldLabel>
+          <MultiSelect
+            name={`y-${idx}`}
+            value={query.yColumns}
+            onChange={(next) => onUpdateQuery({ yColumns: next })}
+            options={numericOptions}
+            placeholder="None selected"
+          />
+        </Field>
+      )}
+
+      {PARTITION_TYPES.includes(query.type) &&
+        groups.categorical.length > 0 && (
+          <Field>
+            <FieldLabel>Partition by</FieldLabel>
+            <Select
+              name={`partition-${idx}`}
+              value={query.partitionByColumn ?? ""}
+              onChange={(e) =>
+                onUpdateQuery({
+                  partitionByColumn: e.target.value || undefined,
+                })
+              }
+              options={[
+                { label: "None", value: "" },
+                ...groups.categorical.map((c) => ({
+                  label: c.name,
+                  value: c.name,
+                })),
+              ]}
+            />
+          </Field>
+        )}
+
+      {!isAnchorTab && (
+        <Field>
+          <FieldLabel>Y-axis</FieldLabel>
+          <Select
+            name={`axis-${idx}`}
+            value={query.axis ?? "left"}
+            onChange={(e) =>
+              onUpdateQuery({ axis: e.target.value as SeriesAxis })
+            }
+            options={[
+              { label: "Left", value: "left" },
+              { label: "Right", value: "right" },
+            ]}
+          />
+        </Field>
+      )}
+
+      <Button
+        type="button"
+        skin="secondary"
+        onClick={() => onSetQuery(activeTab.inferredChart)}
+      >
+        Reset to auto
+      </Button>
+    </QueryCard>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/CellChart/buildEchartsOption.test.ts b/src/scenes/Editor/Notebook/CellChart/buildEchartsOption.test.ts
new file mode 100644
index 000000000..8d8d443ff
--- /dev/null
+++ b/src/scenes/Editor/Notebook/CellChart/buildEchartsOption.test.ts
@@ -0,0 +1,352 @@
+import { describe, it, expect } from "vitest"
+import type { ColumnDefinition } from "../../../../utils/questdb/types"
+import {
+  buildEchartsOption,
+  type ChartGlobals,
+  type ResolvedQuery,
+} from "./buildEchartsOption"
+
+const col = (name: string, type: string): ColumnDefinition => ({ name, type })
+
+const resolved = (over: Partial<ResolvedQuery>): ResolvedQuery => ({
+  index: 0,
+  columns: [],
+  dataset: [],
+  xColumn: null,
+  type: "line",
+  yColumns: [],
+  axis: "left",
+  ...over,
+})
+
+// Narrow the loose echarts option types for assertions.
+const firstAxis = (axis: unknown): Record<string, unknown> =>
+  (Array.isArray(axis) ? axis[0] : axis) as Record<string, unknown>
+const seriesList = (s: unknown): Record<string, unknown>[] =>
+  (Array.isArray(s) ? s : [s]) as Record<string, unknown>[]
+
+describe("buildEchartsOption — order-book depth (numeric value x-axis + step)", () => {
+  const depthColumns = [
+    col("price", "DOUBLE"),
+    col("cum_bid", "DOUBLE"),
+    col("cum_ask", "DOUBLE"),
+  ]
+  const depthDataset: (number | null)[][] = [
+    [100, 5, null],
+    [101, 3, null],
+    [102, null, 4],
+    [103, null, 7],
+  ]
+  const chart: ChartGlobals = { xColumn: "price" }
+
+  it("renders a continuous value x-axis (not a category axis) for numeric x", () => {
+    const opt = buildEchartsOption(chart, [
+      resolved({
+        columns: depthColumns,
+        dataset: depthDataset,
+        xColumn: "price",
+        type: "stepArea",
+        yColumns: ["cum_bid", "cum_ask"],
+      }),
+    ])
+    const x = firstAxis(opt.xAxis)
+    expect(x.type).toBe("value")
+    expect(x.name).toBe("price")
+    // A category axis would carry a `data` array of price labels; a value axis must not.
+    expect(x.data).toBeUndefined()
+  })
+
+  it("stepArea emits stepped, area-filled line series with [x,y] numeric pairs", () => {
+    const opt = buildEchartsOption(chart, [
+      resolved({
+        columns: depthColumns,
+        dataset: depthDataset,
+        xColumn: "price",
+        type: "stepArea",
+        yColumns: ["cum_bid", "cum_ask"],
+      }),
+    ])
+    const series = seriesList(opt.series)
+    expect(series).toHaveLength(2)
+    for (const s of series) {
+      expect(s.type).toBe("line")
+      expect(s.step).toBe("end")
+      expect(s.areaStyle).toBeDefined()
+      expect(s.smooth).toBeUndefined() // stepped curves must not smooth
+    }
+    // x is carried positionally as [price, value] pairs along the value axis.
+    expect(series[0].data).toEqual([
+      [100, 5],
+      [101, 3],
+      [102, null],
+      [103, null],
+    ])
+  })
+
+  it("stepLine is stepped but NOT area-filled", () => {
+    const opt = buildEchartsOption(chart, [
+      resolved({
+        columns: depthColumns,
+        dataset: depthDataset,
+        xColumn: "price",
+        type: "stepLine",
+        yColumns: ["cum_bid"],
+      }),
+    ])
+    const s = seriesList(opt.series)[0]
+    expect(s.type).toBe("line")
+    expect(s.step).toBe("end")
+    expect(s.areaStyle).toBeUndefined()
+  })
+
+  it("plain line over a numeric x also gets a value axis (was a category axis)", () => {
+    const opt = buildEchartsOption(chart, [
+      resolved({
+        columns: depthColumns,
+        dataset: depthDataset,
+        xColumn: "price",
+        type: "line",
+        yColumns: ["cum_bid"],
+      }),
+    ])
+    expect(firstAxis(opt.xAxis).type).toBe("value")
+    expect(seriesList(opt.series)[0].step).toBeUndefined()
+  })
+})
+
+describe("buildEchartsOption — volume bars overlaid on candlesticks", () => {
+  const columns = [
+    col("ts", "TIMESTAMP"),
+    col("open", "DOUBLE"),
+    col("high", "DOUBLE"),
+    col("low", "DOUBLE"),
+    col("close", "DOUBLE"),
+    col("volume", "DOUBLE"),
+  ]
+  const dataset: number[][] = [
+    [1000, 10, 12, 9, 11, 500],
+    [2000, 11, 13, 10, 12, 700],
+  ]
+
+  it("makes the volume bars translucent and lifts candlesticks above them", () => {
+    const opt = buildEchartsOption({ xColumn: "ts" }, [
+      resolved({
+        columns,
+        dataset,
+        xColumn: "ts",
+        type: "candlestick",
+        ohlc: { open: "open", high: "high", low: "low", close: "close" },
+      }),
+      resolved({
+        index: 1,
+        columns,
+        dataset,
+        xColumn: "ts",
+        type: "bar",
+        yColumns: ["volume"],
+        axis: "right",
+      }),
+    ])
+    const series = seriesList(opt.series)
+    const bar = series.find((s) => s.type === "bar")
+    const candle = series.find((s) => s.type === "candlestick")
+    expect((bar?.itemStyle as { opacity?: number })?.opacity).toBeLessThan(1)
+    expect(candle?.z).toBe(3) // candles render above the translucent bars
+  })
+
+  it("leaves a pure bar chart fully opaque (no overlay)", () => {
+    const opt = buildEchartsOption({ xColumn: "ts" }, [
+      resolved({
+        columns,
+        dataset,
+        xColumn: "ts",
+        type: "bar",
+        yColumns: ["volume"],
+      }),
+    ])
+    const bar = seriesList(opt.series).find((s) => s.type === "bar")
+    expect(bar?.itemStyle).toBeUndefined()
+  })
+
+  it("emits an empty candle ('-') when any OHLC component is null", () => {
+    const ohlcColumns = [
+      col("ts", "TIMESTAMP"),
+      col("open", "DOUBLE"),
+      col("high", "DOUBLE"),
+      col("low", "DOUBLE"),
+      col("close", "DOUBLE"),
+    ]
+    const opt = buildEchartsOption({ xColumn: "ts" }, [
+      resolved({
+        columns: ohlcColumns,
+        dataset: [
+          [1000, 10, 12, 9, 11],
+          [2000, null, null, null, null],
+        ],
+        xColumn: "ts",
+        type: "candlestick",
+        ohlc: { open: "open", high: "high", low: "low", close: "close" },
+      }),
+    ])
+    const candle = seriesList(opt.series).find((s) => s.type === "candlestick")
+    // [ts, open, close, low, high]; the empty bucket must stay a gap, not [0,0,0,0].
+    expect(candle?.data).toEqual([
+      [1000, 10, 11, 9, 12],
+      [2000, "-", "-", "-", "-"],
+    ])
+  })
+})
+
+describe("buildEchartsOption — scatter keeps nulls as gaps (no fabricated zeros)", () => {
+  it("emits null for a missing x or y instead of plotting a point at 0", () => {
+    const opt = buildEchartsOption({ xColumn: "a" }, [
+      resolved({
+        columns: [col("a", "DOUBLE"), col("b", "DOUBLE")],
+        dataset: [
+          [1, 100],
+          [2, null],
+          [null, 300],
+        ],
+        xColumn: "a",
+        type: "scatter",
+        yColumns: ["b"],
+      }),
+    ])
+    const s = seriesList(opt.series)[0]
+    expect(s.type).toBe("scatter")
+    // A null measurement must be a gap, not a real point pinned to 0.
+    expect(s.data).toEqual([
+      [1, 100],
+      [2, null],
+      [null, 300],
+    ])
+  })
+})
+
+describe("buildEchartsOption — categorical x preserves duplicate rows", () => {
+  const columns = [col("side", "SYMBOL"), col("qty", "LONG")]
+  // Non-aggregated rows: "buy" and "sell" each appear twice.
+  const dataset: (string | number)[][] = [
+    ["buy", 10],
+    ["sell", 5],
+    ["buy", 20],
+    ["sell", 7],
+  ]
+
+  it("renders one axis slot and one value per row (no last-write-wins collapse)", () => {
+    const opt = buildEchartsOption({ xColumn: "side" }, [
+      resolved({
+        columns,
+        dataset,
+        xColumn: "side",
+        type: "bar",
+        yColumns: ["qty"],
+      }),
+    ])
+    const x = firstAxis(opt.xAxis)
+    expect(x.type).toBe("category")
+    // All four rows survive — duplicates are kept, not deduped into a Set.
+    expect(x.data).toEqual(["buy", "sell", "buy", "sell"])
+    expect(seriesList(opt.series)[0].data).toEqual([10, 5, 20, 7])
+  })
+
+  it("still dedupes onto a shared category union when overlaying multiple queries", () => {
+    const opt = buildEchartsOption({ xColumn: "side" }, [
+      resolved({
+        columns,
+        dataset: [
+          ["buy", 10],
+          ["sell", 5],
+        ],
+        xColumn: "side",
+        type: "bar",
+        yColumns: ["qty"],
+      }),
+      resolved({
+        index: 1,
+        columns: [col("side", "SYMBOL"), col("price", "DOUBLE")],
+        dataset: [
+          ["sell", 200],
+          ["buy", 100],
+        ],
+        xColumn: "side",
+        type: "line",
+        yColumns: ["price"],
+      }),
+    ])
+    const x = firstAxis(opt.xAxis)
+    // Two queries share one axis: union is deduped and each series aligns to it.
+    expect(x.data).toEqual(["buy", "sell"])
+    const series = seriesList(opt.series)
+    expect(series[0].data).toEqual([10, 5])
+    expect(series[1].data).toEqual([100, 200])
+  })
+})
+
+describe("buildEchartsOption — partitioned categorical x aligns to the shared union", () => {
+  const columns = [
+    col("region", "SYMBOL"),
+    col("grp", "SYMBOL"),
+    col("qty", "LONG"),
+  ]
+  // Partition "A" has both regions (north twice → last-write-wins);
+  // partition "B" only has north → south must align to null, not shift.
+  const dataset: (string | number)[][] = [
+    ["north", "A", 10],
+    ["south", "A", 20],
+    ["north", "B", 30],
+    ["north", "A", 99],
+  ]
+
+  it("pivots partitions to series and aligns each to the category union (last row wins, missing → null)", () => {
+    const opt = buildEchartsOption({ xColumn: "region" }, [
+      resolved({
+        columns,
+        dataset,
+        xColumn: "region",
+        partitionByColumn: "grp",
+        type: "bar",
+        yColumns: ["qty"],
+      }),
+    ])
+    const x = firstAxis(opt.xAxis)
+    expect(x.type).toBe("category")
+    expect(x.data).toEqual(["north", "south"])
+    const series = seriesList(opt.series)
+    const a = series.find((s) => s.name === "A")
+    const b = series.find((s) => s.name === "B")
+    // A: north keeps the last row (99, not 10); south present (20).
+    expect(a?.data).toEqual([99, 20])
+    // B: north present (30); south absent → aligned to null, not collapsed.
+    expect(b?.data).toEqual([30, null])
+  })
+})
+
+describe("buildEchartsOption — step over a temporal x", () => {
+  it("keeps a time axis and applies the step to the line series", () => {
+    const columns = [col("ts", "TIMESTAMP"), col("state", "DOUBLE")]
+    const dataset: (number | null)[][] = [
+      [1000, 0],
+      [2000, 1],
+      [3000, 0],
+    ]
+    const opt = buildEchartsOption({ xColumn: "ts" }, [
+      resolved({
+        columns,
+        dataset,
+        xColumn: "ts",
+        type: "stepLine",
+        yColumns: ["state"],
+      }),
+    ])
+    expect(firstAxis(opt.xAxis).type).toBe("time")
+    const s = seriesList(opt.series)[0]
+    expect(s.type).toBe("line")
+    expect(s.step).toBe("end")
+    expect(s.data).toEqual([
+      [1000, 0],
+      [2000, 1],
+      [3000, 0],
+    ])
+  })
+})
diff --git a/src/scenes/Editor/Notebook/CellChart/buildEchartsOption.ts b/src/scenes/Editor/Notebook/CellChart/buildEchartsOption.ts
new file mode 100644
index 000000000..363e3ee98
--- /dev/null
+++ b/src/scenes/Editor/Notebook/CellChart/buildEchartsOption.ts
@@ -0,0 +1,552 @@
+import type { EChartsOption } from "echarts"
+import type { ColumnDefinition } from "../../../../utils/questdb/types"
+import type { ChartConfig, ChartType, SeriesAxis } from "./chartTypes"
+import { MAX_PARTITION_SERIES, classifyColumn } from "./inferChartConfig"
+
+type Dataset = (boolean | string | number | null)[][]
+
+export type ResolvedQuery = {
+  index: number
+  columns: ColumnDefinition[]
+  dataset: Dataset
+  xColumn: string | null // for value extraction
+  type: ChartType
+  yColumns: string[]
+  ohlc?: { open: string; high: string; low: string; close: string }
+  partitionByColumn?: string
+  axis: SeriesAxis
+  name?: string
+}
+
+export type ChartGlobals = {
+  xColumn: string | null
+  name?: string
+  rightAxis?: ChartConfig["rightAxis"]
+}
+
+type Series = Record<string, unknown>
+
+type XMode = "time" | "value" | "category"
+
+type SeriesContext = {
+  xMode: XMode
+  categoryUnion: string[] | null // set only when overlaying series onto a shared category axis; null for a single positional query
+}
+
+const DATAZOOM_THRESHOLD = 200
+
+const LEGEND_BOTTOM = 3
+const SLIDER_HEIGHT = 18
+const SLIDER_BOTTOM = 40
+const GRID_BOTTOM_NO_ZOOM = 56
+const GRID_BOTTOM_WITH_ZOOM = 86
+const CHART_FONT_SIZE = 12
+const BAR_OVERLAY_OPACITY = 0.45
+const X_AXIS_NAME_GAP = 26
+
+const buildColumnIndexMap = (
+  columns: ColumnDefinition[],
+): Map<string, number> => {
+  const m = new Map<string, number>()
+  columns.forEach((c, i) => m.set(c.name, i))
+  return m
+}
+
+const toNumberOrNull = (v: unknown): number | null => {
+  if (v === null || v === undefined) return null
+  if (typeof v === "number") return v
+  if (typeof v === "boolean") return v ? 1 : 0
+  const n = Number(v)
+  return Number.isFinite(n) ? n : null
+}
+
+const toCategoryLabel = (v: unknown): string => {
+  if (v === null || v === undefined) return ""
+  if (typeof v === "string") return v
+  if (typeof v === "number" || typeof v === "boolean") return String(v)
+  return JSON.stringify(v)
+}
+
+const extractColumnValues = (dataset: Dataset, idx: number): unknown[] =>
+  dataset.map((row) => row[idx])
+
+const resolveSeriesRenderSpec = (type: ChartType) => {
+  const isStep = type === "stepLine" || type === "stepArea"
+  const isArea = type === "area" || type === "stepArea"
+  const isLineFamily =
+    type === "line" ||
+    type === "area" ||
+    type === "stepLine" ||
+    type === "stepArea"
+  const isStacked = type === "stackedBar"
+  const isScatter = type === "scatter"
+  const seriesType: "line" | "bar" | "scatter" = isScatter
+    ? "scatter"
+    : isLineFamily
+      ? "line"
+      : "bar"
+  const lineExtras: Record<string, unknown> = {}
+  if (isArea) {
+    lineExtras.areaStyle = {}
+    lineExtras.symbol = "none"
+  }
+  if (isStep) lineExtras.step = "end"
+  // Scatter/bar use `large` for big point/bar sets; lines downsample with LTTB.
+  const perfExtras: { sampling?: "lttb"; large?: boolean } = isLineFamily
+    ? { sampling: "lttb" }
+    : { large: true }
+  return { seriesType, lineExtras, perfExtras, isStacked }
+}
+
+const alignValuesToCategoryUnion = (
+  q: ResolvedQuery,
+  xIdx: number,
+  yIdx: number,
+  union: string[],
+): (number | null)[] => {
+  const m = new Map<string, number | null>()
+  for (const row of q.dataset)
+    m.set(toCategoryLabel(row[xIdx]), toNumberOrNull(row[yIdx]))
+  return union.map((lbl) => (m.has(lbl) ? (m.get(lbl) ?? null) : null))
+}
+
+const alignRowsToCategoryUnion = (
+  rows: Dataset,
+  xIdx: number,
+  yIdx: number,
+  union: string[],
+): (number | null)[] => {
+  const m = new Map<string, number | null>()
+  for (const row of rows)
+    m.set(toCategoryLabel(row[xIdx]), toNumberOrNull(row[yIdx]))
+  return union.map((lbl) => (m.has(lbl) ? (m.get(lbl) ?? null) : null))
+}
+
+const buildCartesianSeries = (
+  q: ResolvedQuery,
+  ctx: SeriesContext,
+): Series[] => {
+  const { seriesType, lineExtras, perfExtras, isStacked } =
+    resolveSeriesRenderSpec(q.type)
+  const yAxisIndex = q.axis === "right" ? 1 : 0
+  const idx = buildColumnIndexMap(q.columns)
+  const xIdx = q.xColumn != null ? idx.get(q.xColumn) : undefined
+  if (xIdx === undefined) return []
+  const stack = isStacked ? `stack-${q.index}` : undefined
+  const out: Series[] = []
+
+  const partIdx =
+    q.partitionByColumn != null ? idx.get(q.partitionByColumn) : undefined
+
+  if (partIdx !== undefined) {
+    // Long → wide pivot: each distinct partition value → its own series.
+    const groups = new Map<string, Map<string, Dataset>>()
+    for (const row of q.dataset) {
+      const partVal = toCategoryLabel(row[partIdx])
+      let metricMap = groups.get(partVal)
+      if (!metricMap) {
+        metricMap = new Map()
+        groups.set(partVal, metricMap)
+      }
+      for (const yName of q.yColumns) {
+        const yIdx = idx.get(yName)
+        if (yIdx === undefined) continue
+        let rows = metricMap.get(yName)
+        if (!rows) {
+          rows = []
+          metricMap.set(yName, rows)
+        }
+        rows.push(row)
+      }
+    }
+    const sortedKeys = [...groups.keys()].sort().slice(0, MAX_PARTITION_SERIES)
+    for (const partVal of sortedKeys) {
+      const metricMap = groups.get(partVal)
+      if (!metricMap) continue
+      for (const [yName, rows] of metricMap) {
+        const yIdx = idx.get(yName)
+        if (yIdx === undefined) continue
+        const data =
+          ctx.xMode === "time"
+            ? rows.map((row) => [row[xIdx], toNumberOrNull(row[yIdx])])
+            : ctx.xMode === "value"
+              ? rows.map((row) => [
+                  toNumberOrNull(row[xIdx]),
+                  toNumberOrNull(row[yIdx]),
+                ])
+              : ctx.categoryUnion
+                ? alignRowsToCategoryUnion(rows, xIdx, yIdx, ctx.categoryUnion)
+                : rows.map((row) => toNumberOrNull(row[yIdx]))
+        out.push({
+          name: q.yColumns.length > 1 ? `${partVal} · ${yName}` : partVal,
+          type: seriesType,
+          yAxisIndex,
+          data,
+          ...lineExtras,
+          ...perfExtras,
+          ...(stack ? { stack } : {}),
+        })
+      }
+    }
+    return out
+  }
+
+  for (const name of q.yColumns) {
+    const yIdx = idx.get(name)
+    if (yIdx === undefined) continue
+    const data =
+      ctx.xMode === "time"
+        ? q.dataset.map((row) => [row[xIdx], toNumberOrNull(row[yIdx])])
+        : ctx.xMode === "value"
+          ? q.dataset.map((row) => [
+              toNumberOrNull(row[xIdx]),
+              toNumberOrNull(row[yIdx]),
+            ])
+          : ctx.categoryUnion
+            ? alignValuesToCategoryUnion(q, xIdx, yIdx, ctx.categoryUnion)
+            : q.dataset.map((row) => toNumberOrNull(row[yIdx]))
+    out.push({
+      name,
+      type: seriesType,
+      yAxisIndex,
+      data,
+      ...lineExtras,
+      ...perfExtras,
+      ...(stack ? { stack } : {}),
+    })
+  }
+  return out
+}
+
+const EMPTY_CANDLE: (number | string)[] = ["-", "-", "-", "-"]
+
+const buildCandlestickSeries = (
+  q: ResolvedQuery,
+  ctx: SeriesContext,
+): Series[] => {
+  if (!q.ohlc) return []
+  const idx = buildColumnIndexMap(q.columns)
+  const xIdx = q.xColumn != null ? idx.get(q.xColumn) : undefined
+  const oIdx = idx.get(q.ohlc.open)
+  const cIdx = idx.get(q.ohlc.close)
+  const lIdx = idx.get(q.ohlc.low)
+  const hIdx = idx.get(q.ohlc.high)
+  if (
+    xIdx === undefined ||
+    oIdx === undefined ||
+    cIdx === undefined ||
+    lIdx === undefined ||
+    hIdx === undefined
+  ) {
+    return []
+  }
+  const candle = (row: Dataset[number]): (number | string)[] => {
+    const o = toNumberOrNull(row[oIdx])
+    const c = toNumberOrNull(row[cIdx])
+    const l = toNumberOrNull(row[lIdx])
+    const h = toNumberOrNull(row[hIdx])
+    if (o === null || c === null || l === null || h === null)
+      return EMPTY_CANDLE
+    return [o, c, l, h]
+  }
+  let data: unknown[]
+  if (ctx.xMode === "time") {
+    data = q.dataset.map((row) => [row[xIdx], ...candle(row)])
+  } else if (ctx.xMode === "value") {
+    data = q.dataset.map((row) => [toNumberOrNull(row[xIdx]), ...candle(row)])
+  } else if (ctx.categoryUnion) {
+    const m = new Map<string, (number | string)[]>()
+    for (const row of q.dataset) m.set(toCategoryLabel(row[xIdx]), candle(row))
+    data = ctx.categoryUnion.map((lbl) => m.get(lbl) ?? EMPTY_CANDLE)
+  } else {
+    data = q.dataset.map((row) => candle(row))
+  }
+  return [
+    {
+      name: q.name ?? "OHLC",
+      type: "candlestick",
+      yAxisIndex: q.axis === "right" ? 1 : 0,
+      data,
+    },
+  ]
+}
+
+const buildPieChartOption = (
+  q: ResolvedQuery,
+  chartText: { fontSize: number },
+  legend: object,
+): EChartsOption => {
+  const idx = buildColumnIndexMap(q.columns)
+  const xIdx = q.xColumn != null ? idx.get(q.xColumn) : undefined
+  const yIdx = q.yColumns[0] != null ? idx.get(q.yColumns[0]) : undefined
+  if (xIdx === undefined || yIdx === undefined)
+    return { tooltip: { trigger: "item", textStyle: chartText } }
+  const data = q.dataset.map((row) => ({
+    name: toCategoryLabel(row[xIdx]),
+    value: toNumberOrNull(row[yIdx]) ?? 0,
+  }))
+  return {
+    tooltip: { trigger: "item", textStyle: chartText },
+    legend,
+    series: [
+      {
+        name: q.yColumns[0],
+        type: "pie",
+        radius: ["35%", "70%"],
+        avoidLabelOverlap: true,
+        label: {
+          show: true,
+          formatter: "{b}: {d}%",
+          fontSize: CHART_FONT_SIZE,
+        },
+        data,
+      },
+    ],
+  }
+}
+
+const buildScatterChartOption = (
+  q: ResolvedQuery,
+  chartText: { fontSize: number },
+  legend: object,
+  axisLabel: { fontSize: number },
+  axisName: { fontSize: number },
+): EChartsOption => {
+  const idx = buildColumnIndexMap(q.columns)
+  const xIdx = q.xColumn != null ? idx.get(q.xColumn) : undefined
+  if (xIdx === undefined)
+    return { tooltip: { trigger: "item", textStyle: chartText } }
+  const series = q.yColumns
+    .map((name) => {
+      const yIdx = idx.get(name)
+      if (yIdx === undefined) return null
+      return {
+        name,
+        type: "scatter" as const,
+        large: true,
+        data: q.dataset.map((row) => [
+          toNumberOrNull(row[xIdx]),
+          toNumberOrNull(row[yIdx]),
+        ]),
+      }
+    })
+    .filter((s): s is NonNullable<typeof s> => s !== null)
+  return {
+    tooltip: { trigger: "item", textStyle: chartText },
+    legend,
+    grid: {
+      left: 24,
+      right: 24,
+      top: 40,
+      bottom: 48,
+      containLabel: true,
+    },
+    xAxis: {
+      type: "value",
+      scale: true,
+      name: q.xColumn ?? "",
+      axisLabel,
+      nameTextStyle: axisName,
+    },
+    yAxis: { type: "value", scale: true, axisLabel, nameTextStyle: axisName },
+    series,
+  }
+}
+
+export const buildEchartsOption = (
+  chart: ChartGlobals,
+  queries: ResolvedQuery[],
+): EChartsOption => {
+  const chartText = { fontSize: CHART_FONT_SIZE }
+  const axisLabel = { fontSize: CHART_FONT_SIZE }
+  const axisName = { fontSize: CHART_FONT_SIZE }
+  const baseLegend = {
+    type: "scroll" as const,
+    bottom: LEGEND_BOTTOM,
+    textStyle: chartText,
+  }
+
+  const anchor = queries[0]
+  if (!anchor) return { tooltip: { textStyle: chartText } }
+
+  const single = queries.length === 1
+  const anchorCol = anchor.columns.find((c) => c.name === anchor.xColumn)
+  const anchorRole = anchorCol ? classifyColumn(anchorCol) : "other"
+
+  if (single && anchor.type === "pie")
+    return buildPieChartOption(anchor, chartText, baseLegend)
+  if (single && anchor.type === "scatter" && anchorRole === "numeric")
+    return buildScatterChartOption(
+      anchor,
+      chartText,
+      baseLegend,
+      axisLabel,
+      axisName,
+    )
+
+  const xMode: XMode =
+    anchorRole === "temporal"
+      ? "time"
+      : anchorRole === "numeric"
+        ? "value"
+        : "category"
+
+  // A single, non-partitioned query renders positionally: one axis slot and one
+  // value per row, so duplicate categorical x values are preserved. The deduped
+  // category union + per-label alignment is only needed to overlay several
+  // series (multiple queries, or a partition pivot) onto one shared axis — there
+  // the Map keying necessarily picks one row per label.
+  const positionalCategory =
+    xMode === "category" && single && anchor.partitionByColumn == null
+
+  let categoryUnion: string[] | null = null
+  let categoryAxisData: string[] = []
+  if (positionalCategory) {
+    const xIdx = anchor.columns.findIndex((c) => c.name === anchor.xColumn)
+    categoryAxisData =
+      xIdx < 0 ? [] : anchor.dataset.map((row) => toCategoryLabel(row[xIdx]))
+  } else if (xMode === "category") {
+    const seen = new Set<string>()
+    const union: string[] = []
+    for (const q of queries) {
+      const xIdx = q.columns.findIndex((c) => c.name === q.xColumn)
+      if (xIdx < 0) continue
+      for (const v of extractColumnValues(q.dataset, xIdx)) {
+        const lbl = toCategoryLabel(v)
+        if (seen.has(lbl)) continue
+        seen.add(lbl)
+        union.push(lbl)
+      }
+    }
+    categoryUnion = union
+    categoryAxisData = union
+  }
+
+  const ctx: SeriesContext = { xMode, categoryUnion }
+  const hasCandle = queries.some((q) => q.type === "candlestick")
+  const hasBar = queries.some(
+    (q) => q.type === "bar" || q.type === "stackedBar",
+  )
+
+  const series: Series[] = []
+  for (const q of queries) {
+    if (q.type === "candlestick") series.push(...buildCandlestickSeries(q, ctx))
+    else if (q.type === "pie")
+      continue // pie can't share an axis
+    else series.push(...buildCartesianSeries(q, ctx)) // line/area/bar/stackedBar/scatter
+  }
+
+  const overlaidByBars =
+    series.some((s) => s.type === "bar") && series.some((s) => s.type !== "bar")
+  if (overlaidByBars) {
+    for (const s of series) {
+      if (s.type === "bar") {
+        s.itemStyle = {
+          ...(s.itemStyle as object),
+          opacity: BAR_OVERLAY_OPACITY,
+        }
+      } else {
+        // Default series z is 2; bump non-bar series above the bars.
+        s.z = 3
+      }
+    }
+  }
+
+  const hasRight = queries.some((q) => q.axis === "right")
+  const rightQueries = queries.filter((q) => q.axis === "right")
+  const rightTitle =
+    chart.rightAxis?.name ??
+    (rightQueries.length === 1
+      ? (rightQueries[0].name ?? rightQueries[0].yColumns[0] ?? "")
+      : "")
+
+  const maxRows = queries.reduce((m, q) => Math.max(m, q.dataset.length), 0)
+  const hasZoom = maxRows > DATAZOOM_THRESHOLD
+  const sliderZoom = {
+    type: "slider" as const,
+    height: SLIDER_HEIGHT,
+    bottom: SLIDER_BOTTOM,
+    textStyle: chartText,
+  }
+
+  const rightPadding = 36
+
+  const grid: EChartsOption["grid"] = {
+    left: 24,
+    right: rightPadding,
+    top: 40,
+    bottom: hasZoom ? GRID_BOTTOM_WITH_ZOOM : GRID_BOTTOM_NO_ZOOM,
+    containLabel: true,
+  }
+
+  const leftAxis = {
+    type: "value" as const,
+    scale: true,
+    axisLabel,
+    nameTextStyle: axisName,
+  }
+  const yAxis: EChartsOption["yAxis"] = hasRight
+    ? [
+        leftAxis,
+        {
+          type: "value",
+          scale: true,
+          position: "right",
+          name: rightTitle,
+          nameTextStyle: axisName,
+          axisLabel,
+          splitLine: { show: false },
+          ...(chart.rightAxis?.min != null ? { min: chart.rightAxis.min } : {}),
+          ...(chart.rightAxis?.max != null ? { max: chart.rightAxis.max } : {}),
+        },
+      ]
+    : leftAxis
+
+  const xAxisName = {
+    name: chart.xColumn ?? "",
+    nameLocation: "middle" as const,
+    nameGap: X_AXIS_NAME_GAP,
+    axisLabel,
+    nameTextStyle: axisName,
+  }
+  const xAxis: EChartsOption["xAxis"] =
+    xMode === "time"
+      ? {
+          type: "time",
+          ...xAxisName,
+          // Extend the time axis 5% on each side so candle bodies sit inside the
+          // plot (time axis is boundaryGap:false by default).
+          ...(hasCandle
+            ? {
+                min: (v: { min: number; max: number }) =>
+                  v.min - (v.max - v.min) * 0.05,
+                max: (v: { min: number; max: number }) =>
+                  v.max + (v.max - v.min) * 0.05,
+              }
+            : {}),
+        }
+      : xMode === "value"
+        ? { type: "value", scale: true, ...xAxisName }
+        : {
+            type: "category",
+            data: categoryAxisData,
+            ...xAxisName,
+            boundaryGap: hasBar || hasCandle,
+          }
+
+  const tooltip: EChartsOption["tooltip"] = {
+    trigger: "axis",
+    textStyle: chartText,
+    ...(hasCandle ? { axisPointer: { type: "cross" } } : {}),
+  }
+
+  return {
+    tooltip,
+    legend: baseLegend,
+    grid,
+    xAxis,
+    yAxis,
+    dataZoom: hasZoom ? [{ type: "inside" }, sliderZoom] : undefined,
+    series: series as EChartsOption["series"],
+  }
+}
diff --git a/src/scenes/Editor/Notebook/CellChart/chartSettingsStyles.ts b/src/scenes/Editor/Notebook/CellChart/chartSettingsStyles.ts
new file mode 100644
index 000000000..b8d5977a0
--- /dev/null
+++ b/src/scenes/Editor/Notebook/CellChart/chartSettingsStyles.ts
@@ -0,0 +1,24 @@
+import styled from "styled-components"
+import { WarningIcon } from "@phosphor-icons/react"
+
+export const IncompatibleIcon = styled(WarningIcon)`
+  color: ${({ theme }) => theme.color.orange};
+  flex-shrink: 0;
+`
+
+export const Field = styled.label`
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+`
+
+export const FieldGroup = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+`
+
+export const FieldLabel = styled.span`
+  font-size: 1.1rem;
+  color: ${({ theme }) => theme.color.gray2};
+`
diff --git a/src/scenes/Editor/Notebook/CellChart/chartTypes.ts b/src/scenes/Editor/Notebook/CellChart/chartTypes.ts
new file mode 100644
index 000000000..04ce2c227
--- /dev/null
+++ b/src/scenes/Editor/Notebook/CellChart/chartTypes.ts
@@ -0,0 +1,40 @@
+export const CHART_TYPES = [
+  "line",
+  "area",
+  "stepLine",
+  "stepArea",
+  "bar",
+  "stackedBar",
+  "scatter",
+  "pie",
+  "candlestick",
+] as const
+
+export type ChartType = (typeof CHART_TYPES)[number]
+
+export type ColumnRole = "temporal" | "numeric" | "categorical" | "other"
+
+export type SeriesAxis = "left" | "right"
+
+export type QueryChart = {
+  type: ChartType
+  yColumns: string[]
+  ohlc?: {
+    open: string
+    high: string
+    low: string
+    close: string
+  }
+  partitionByColumn?: string
+  axis?: SeriesAxis
+  enabled?: boolean
+  name?: string
+}
+
+export type ChartConfig = {
+  xColumn: string | null
+  name?: string
+  queries: (QueryChart | null)[]
+  rightAxis?: { name?: string; min?: number; max?: number }
+  autoRefresh?: boolean
+}
diff --git a/src/scenes/Editor/Notebook/CellChart/echartsSetup.ts b/src/scenes/Editor/Notebook/CellChart/echartsSetup.ts
new file mode 100644
index 000000000..a862663af
--- /dev/null
+++ b/src/scenes/Editor/Notebook/CellChart/echartsSetup.ts
@@ -0,0 +1,40 @@
+import * as echarts from "echarts/core"
+import {
+  BarChart,
+  LineChart,
+  PieChart,
+  ScatterChart,
+  CandlestickChart,
+} from "echarts/charts"
+import {
+  GridComponent,
+  TooltipComponent,
+  LegendComponent,
+  DataZoomComponent,
+  ToolboxComponent,
+  TitleComponent,
+} from "echarts/components"
+import { CanvasRenderer } from "echarts/renderers"
+import { questdbTheme } from "./questdbTheme"
+
+echarts.use([
+  BarChart,
+  LineChart,
+  PieChart,
+  ScatterChart,
+  CandlestickChart,
+  GridComponent,
+  TooltipComponent,
+  LegendComponent,
+  DataZoomComponent,
+  ToolboxComponent,
+  TitleComponent,
+  CanvasRenderer,
+])
+
+export const QUESTDB_THEME = "questdb"
+echarts.registerTheme(QUESTDB_THEME, questdbTheme)
+
+// Pair with `echarts-for-react/lib/core` — importing the default wrapper
+// instead would pull the full echarts catalog and undo the tree-shaking.
+export { echarts }
diff --git a/src/scenes/Editor/Notebook/CellChart/inferChartConfig.test.ts b/src/scenes/Editor/Notebook/CellChart/inferChartConfig.test.ts
new file mode 100644
index 000000000..7bce177df
--- /dev/null
+++ b/src/scenes/Editor/Notebook/CellChart/inferChartConfig.test.ts
@@ -0,0 +1,278 @@
+import { describe, it, expect } from "vitest"
+import type { ColumnDefinition } from "../../../../utils/questdb/types"
+import {
+  inferChartConfig,
+  isResultChartable,
+  classifyColumn,
+  availableChartTypes,
+  groupColumns,
+  MAX_DEFAULT_SERIES,
+} from "./inferChartConfig"
+
+const col = (name: string, type: string): ColumnDefinition => ({ name, type })
+
+describe("availableChartTypes", () => {
+  it("offers step types alongside line/area for temporal + numeric", () => {
+    const groups = groupColumns([col("ts", "TIMESTAMP"), col("v", "DOUBLE")])
+    const types = availableChartTypes(groups, false)
+    expect(types).toContain("stepLine")
+    expect(types).toContain("stepArea")
+    expect(types).toContain("line")
+  })
+
+  it("offers line family + steps (no bars) for numeric-only x (depth charts)", () => {
+    const groups = groupColumns([
+      col("price", "DOUBLE"),
+      col("cum_bid", "DOUBLE"),
+      col("cum_ask", "DOUBLE"),
+    ])
+    const types = availableChartTypes(groups, false)
+    expect(types).toEqual(
+      expect.arrayContaining([
+        "line",
+        "area",
+        "stepLine",
+        "stepArea",
+        "scatter",
+      ]),
+    )
+    expect(types).not.toContain("bar")
+    expect(types).not.toContain("stackedBar")
+  })
+
+  it("offers candlestick for temporal + 4 numeric even when columns aren't named open/high/low/close", () => {
+    const groups = groupColumns([
+      col("time", "TIMESTAMP"),
+      col("open", "DOUBLE"),
+      col("close", "DOUBLE"),
+      col("lo", "DOUBLE"),
+      col("hi", "DOUBLE"),
+    ])
+    expect(availableChartTypes(groups, false)).toContain("candlestick")
+  })
+
+  it("does not offer candlestick without a temporal axis, nor with fewer than 4 numeric", () => {
+    const fourNumericNoTime = groupColumns([
+      col("a", "DOUBLE"),
+      col("b", "DOUBLE"),
+      col("c", "DOUBLE"),
+      col("d", "DOUBLE"),
+    ])
+    expect(availableChartTypes(fourNumericNoTime, false)).not.toContain(
+      "candlestick",
+    )
+    const temporalThreeNumeric = groupColumns([
+      col("ts", "TIMESTAMP"),
+      col("a", "DOUBLE"),
+      col("b", "DOUBLE"),
+      col("c", "DOUBLE"),
+    ])
+    expect(availableChartTypes(temporalThreeNumeric, false)).not.toContain(
+      "candlestick",
+    )
+  })
+})
+
+describe("classifyColumn", () => {
+  it("identifies temporal", () => {
+    expect(classifyColumn(col("ts", "TIMESTAMP"))).toBe("temporal")
+    expect(classifyColumn(col("ts", "TIMESTAMP_NS"))).toBe("temporal")
+    expect(classifyColumn(col("d", "DATE"))).toBe("temporal")
+  })
+  it("identifies numeric", () => {
+    expect(classifyColumn(col("p", "DOUBLE"))).toBe("numeric")
+    expect(classifyColumn(col("p", "LONG"))).toBe("numeric")
+  })
+  it("identifies categorical", () => {
+    expect(classifyColumn(col("s", "SYMBOL"))).toBe("categorical")
+    expect(classifyColumn(col("s", "VARCHAR"))).toBe("categorical")
+  })
+  it("flags arrays/uuid as other", () => {
+    expect(classifyColumn(col("u", "UUID"))).toBe("other")
+    expect(classifyColumn(col("a", "ARRAY"))).toBe("other")
+  })
+})
+
+describe("isResultChartable", () => {
+  it("true with at least one numeric/temporal/categorical", () => {
+    expect(isResultChartable([col("p", "DOUBLE")])).toBe(true)
+  })
+  it("false when all columns are non-chartable", () => {
+    expect(isResultChartable([col("u", "UUID"), col("b", "BINARY")])).toBe(
+      false,
+    )
+  })
+})
+
+describe("inferChartConfig", () => {
+  it("picks candlestick for OHLC + temporal", () => {
+    const columns = [
+      col("ts", "TIMESTAMP"),
+      col("open", "DOUBLE"),
+      col("high", "DOUBLE"),
+      col("low", "DOUBLE"),
+      col("close", "DOUBLE"),
+    ]
+    const config = inferChartConfig(
+      columns,
+      [],
+      "SELECT ts, open, high, low, close FROM t SAMPLE BY 1h",
+    )
+    expect(config.chart.type).toBe("candlestick")
+    expect(config.xColumn).toBe("ts")
+    expect(config.chart.ohlc).toEqual({
+      open: "open",
+      high: "high",
+      low: "low",
+      close: "close",
+    })
+  })
+
+  it("OHLC detection is case-insensitive", () => {
+    const columns = [
+      col("ts", "TIMESTAMP"),
+      col("Open", "DOUBLE"),
+      col("HIGH", "DOUBLE"),
+      col("Low", "DOUBLE"),
+      col("CLOSE", "DOUBLE"),
+    ]
+    const config = inferChartConfig(columns, [], "SELECT * FROM t")
+    expect(config.chart.type).toBe("candlestick")
+  })
+
+  it("picks line for temporal + numeric without OHLC", () => {
+    const columns = [col("ts", "TIMESTAMP"), col("price", "DOUBLE")]
+    const config = inferChartConfig(
+      columns,
+      [],
+      "SELECT ts, price FROM trades SAMPLE BY 1m",
+    )
+    expect(config.chart.type).toBe("line")
+    expect(config.xColumn).toBe("ts")
+    expect(config.chart.yColumns).toEqual(["price"])
+    expect(config.chart.partitionByColumn).toBeUndefined()
+  })
+
+  it("auto-partitions long-format temporal + categorical + numeric", () => {
+    const columns = [
+      col("time", "TIMESTAMP"),
+      col("symbol", "SYMBOL"),
+      col("rsi_14", "DOUBLE"),
+    ]
+    const dataset: (string | number)[][] = [
+      ["2024-01-01", "BTC-USDT", 60],
+      ["2024-01-01", "ETH-USDT", 55],
+      ["2024-01-02", "BTC-USDT", 62],
+      ["2024-01-02", "ETH-USDT", 50],
+    ]
+    const config = inferChartConfig(
+      columns,
+      dataset,
+      "SELECT time, symbol, rsi_14 FROM ...",
+    )
+    expect(config.chart.type).toBe("line")
+    expect(config.xColumn).toBe("time")
+    expect(config.chart.partitionByColumn).toBe("symbol")
+    expect(config.chart.yColumns).toEqual(["rsi_14"])
+  })
+
+  it("does not auto-partition when categorical cardinality is too high", () => {
+    const columns = [
+      col("time", "TIMESTAMP"),
+      col("trade_id", "SYMBOL"),
+      col("price", "DOUBLE"),
+    ]
+    const dataset: (string | number)[][] = Array.from(
+      { length: 50 },
+      (_, i) => ["2024-01-01", `id-${i}`, i],
+    )
+    const config = inferChartConfig(
+      columns,
+      dataset,
+      "SELECT time, trade_id, price FROM ...",
+    )
+    expect(config.chart.type).toBe("line")
+    expect(config.chart.partitionByColumn).toBeUndefined()
+    expect(config.chart.yColumns).toEqual(["price"])
+  })
+
+  it("picks pie for low-cardinality categorical + numeric", () => {
+    const columns = [col("symbol", "SYMBOL"), col("c", "LONG")]
+    const dataset: (string | number)[][] = [
+      ["BTC", 10],
+      ["ETH", 8],
+      ["SOL", 5],
+    ]
+    const config = inferChartConfig(
+      columns,
+      dataset,
+      "SELECT symbol, count() FROM trades",
+    )
+    expect(config.chart.type).toBe("pie")
+    expect(config.xColumn).toBe("symbol")
+    expect(config.chart.yColumns).toEqual(["c"])
+  })
+
+  it("picks bar for high-cardinality categorical + numeric", () => {
+    const columns = [col("symbol", "SYMBOL"), col("c", "LONG")]
+    const dataset: (string | number)[][] = Array.from(
+      { length: 30 },
+      (_, i) => [`S${i}`, i],
+    )
+    const config = inferChartConfig(
+      columns,
+      dataset,
+      "SELECT symbol, count() FROM trades",
+    )
+    expect(config.chart.type).toBe("bar")
+  })
+
+  it("picks bar for LATEST ON snapshot", () => {
+    const columns = [col("symbol", "SYMBOL"), col("price", "DOUBLE")]
+    const config = inferChartConfig(
+      columns,
+      [
+        ["BTC", 1],
+        ["ETH", 2],
+      ],
+      "SELECT symbol, price FROM trades LATEST ON ts PARTITION BY symbol",
+    )
+    expect(config.chart.type).toBe("bar")
+    expect(config.xColumn).toBe("symbol")
+  })
+
+  it("picks scatter when only numerics, no temporal", () => {
+    const columns = [col("x", "DOUBLE"), col("y", "DOUBLE")]
+    const config = inferChartConfig(columns, [], "SELECT x, y FROM t")
+    expect(config.chart.type).toBe("scatter")
+    expect(config.xColumn).toBe("x")
+    expect(config.chart.yColumns).toEqual(["y"])
+  })
+
+  it("falls back to bar for unclassifiable shapes", () => {
+    const columns = [col("u", "UUID"), col("b", "BINARY")]
+    const config = inferChartConfig(columns, [], "SELECT u, b FROM t")
+    expect(config.chart.type).toBe("bar")
+    expect(config.xColumn).toBe("u")
+    expect(config.chart.yColumns).toEqual(["b"])
+  })
+
+  it("caps default series at MAX_DEFAULT_SERIES", () => {
+    const columns = [
+      col("ts", "TIMESTAMP"),
+      ...Array.from({ length: MAX_DEFAULT_SERIES + 4 }, (_, i) =>
+        col(`m${i}`, "DOUBLE"),
+      ),
+    ]
+    const config = inferChartConfig(columns, [], "SELECT * FROM t")
+    expect(config.chart.type).toBe("line")
+    expect(config.chart.yColumns).toHaveLength(MAX_DEFAULT_SERIES)
+  })
+
+  it("does not throw on empty columns", () => {
+    const config = inferChartConfig([], [], "")
+    expect(config.chart.type).toBe("bar")
+    expect(config.xColumn).toBeNull()
+    expect(config.chart.yColumns).toEqual([])
+  })
+})
diff --git a/src/scenes/Editor/Notebook/CellChart/inferChartConfig.ts b/src/scenes/Editor/Notebook/CellChart/inferChartConfig.ts
new file mode 100644
index 000000000..40197f8f9
--- /dev/null
+++ b/src/scenes/Editor/Notebook/CellChart/inferChartConfig.ts
@@ -0,0 +1,224 @@
+import { parseToAst } from "@questdb/sql-parser"
+import type { ColumnDefinition } from "../../../../utils/questdb/types"
+import type { ChartType, ColumnRole, QueryChart } from "./chartTypes"
+
+export type InferredChart = { xColumn: string | null; chart: QueryChart }
+
+const TEMPORAL = new Set(["TIMESTAMP", "TIMESTAMP_NS", "DATE"])
+const NUMERIC = new Set([
+  "DOUBLE",
+  "FLOAT",
+  "INT",
+  "LONG",
+  "SHORT",
+  "BYTE",
+  "DECIMAL",
+])
+const CATEGORICAL = new Set(["SYMBOL", "STRING", "VARCHAR", "CHAR", "BOOLEAN"])
+
+export const MAX_DEFAULT_SERIES = 10
+const PIE_THRESHOLD = 12
+export const MAX_AUTO_PARTITION_CARDINALITY = 20
+export const MAX_PARTITION_SERIES = 30
+
+export const classifyColumn = (col: ColumnDefinition): ColumnRole => {
+  const t = col.type?.toUpperCase()
+  if (!t) return "other"
+  if (TEMPORAL.has(t)) return "temporal"
+  if (NUMERIC.has(t)) return "numeric"
+  if (CATEGORICAL.has(t)) return "categorical"
+  return "other"
+}
+
+export type ColumnGroups = {
+  temporal: ColumnDefinition[]
+  numeric: ColumnDefinition[]
+  categorical: ColumnDefinition[]
+  other: ColumnDefinition[]
+}
+
+export const groupColumns = (columns: ColumnDefinition[]): ColumnGroups => {
+  const groups: ColumnGroups = {
+    temporal: [],
+    numeric: [],
+    categorical: [],
+    other: [],
+  }
+  for (const col of columns) {
+    groups[classifyColumn(col)].push(col)
+  }
+  return groups
+}
+
+export const isResultChartable = (columns: ColumnDefinition[]): boolean => {
+  const g = groupColumns(columns)
+  return (
+    g.numeric.length > 0 || g.categorical.length > 0 || g.temporal.length > 0
+  )
+}
+
+export const findOhlc = (
+  numeric: ColumnDefinition[],
+): QueryChart["ohlc"] | undefined => {
+  const byName = new Map<string, string>()
+  for (const c of numeric) byName.set(c.name.toLowerCase(), c.name)
+  const open = byName.get("open")
+  const high = byName.get("high")
+  const low = byName.get("low")
+  const close = byName.get("close")
+  if (open && high && low && close) return { open, high, low, close }
+  return undefined
+}
+
+type QueryHints = {
+  hasSampleBy?: boolean
+  hasLatest?: boolean
+}
+
+// AST-based so SAMPLE BY / LATEST ON in literals/comments/subqueries
+// don't false-positive. `LATEST BY <col>` (legacy) also maps to latestOn.
+const parseQueryHints = (query: string): QueryHints => {
+  try {
+    const { ast } = parseToAst(query)
+    const topSelect = ast.find((s) => s?.type === "select")
+    if (topSelect?.type !== "select") return {}
+    return {
+      hasSampleBy: !!topSelect.sampleBy,
+      hasLatest: !!topSelect.latestOn,
+    }
+  } catch {
+    return {}
+  }
+}
+
+const distinctCount = (
+  dataset: (boolean | string | number | null)[][],
+  colIndex: number,
+  cap = PIE_THRESHOLD,
+): number => {
+  const seen = new Set<unknown>()
+  for (const row of dataset) {
+    seen.add(row[colIndex])
+    if (seen.size > cap) return seen.size
+  }
+  return seen.size
+}
+
+export const inferChartConfig = (
+  columns: ColumnDefinition[],
+  dataset: (boolean | string | number | null)[][],
+  query: string,
+): InferredChart => {
+  const groups = groupColumns(columns)
+  const hints = parseQueryHints(query)
+
+  const capSeries = (cols: ColumnDefinition[]): string[] =>
+    cols.slice(0, MAX_DEFAULT_SERIES).map((c) => c.name)
+
+  if (groups.temporal.length > 0 && groups.numeric.length >= 4) {
+    const ohlc = findOhlc(groups.numeric)
+    if (ohlc) {
+      return {
+        xColumn: groups.temporal[0].name,
+        chart: {
+          type: "candlestick",
+          yColumns: [ohlc.open, ohlc.high, ohlc.low, ohlc.close],
+          ohlc,
+        },
+      }
+    }
+  }
+
+  if (
+    groups.temporal.length > 0 &&
+    groups.categorical.length > 0 &&
+    groups.numeric.length > 0
+  ) {
+    const catCol = groups.categorical[0]
+    const catIdx = columns.findIndex((c) => c.name === catCol.name)
+    if (
+      catIdx >= 0 &&
+      distinctCount(dataset, catIdx, MAX_AUTO_PARTITION_CARDINALITY) <=
+        MAX_AUTO_PARTITION_CARDINALITY
+    ) {
+      return {
+        xColumn: groups.temporal[0].name,
+        chart: {
+          type: "line",
+          yColumns: capSeries(groups.numeric),
+          partitionByColumn: catCol.name,
+        },
+      }
+    }
+  }
+
+  if (groups.temporal.length > 0 && groups.numeric.length > 0) {
+    return {
+      xColumn: groups.temporal[0].name,
+      chart: { type: "line", yColumns: capSeries(groups.numeric) },
+    }
+  }
+
+  if (
+    hints.hasLatest &&
+    groups.categorical.length > 0 &&
+    groups.numeric.length > 0
+  ) {
+    return {
+      xColumn: groups.categorical[0].name,
+      chart: { type: "bar", yColumns: capSeries(groups.numeric) },
+    }
+  }
+
+  if (groups.categorical.length > 0 && groups.numeric.length === 1) {
+    const xIdx = columns.findIndex((c) => c.name === groups.categorical[0].name)
+    if (xIdx >= 0 && distinctCount(dataset, xIdx) < PIE_THRESHOLD) {
+      return {
+        xColumn: groups.categorical[0].name,
+        chart: { type: "pie", yColumns: [groups.numeric[0].name] },
+      }
+    }
+  }
+
+  if (groups.categorical.length > 0 && groups.numeric.length > 0) {
+    return {
+      xColumn: groups.categorical[0].name,
+      chart: { type: "bar", yColumns: capSeries(groups.numeric) },
+    }
+  }
+
+  if (groups.numeric.length >= 2 && groups.temporal.length === 0) {
+    return {
+      xColumn: groups.numeric[0].name,
+      chart: { type: "scatter", yColumns: capSeries(groups.numeric.slice(1)) },
+    }
+  }
+
+  const x = columns[0]?.name ?? null
+  const ys = columns.slice(1, 1 + MAX_DEFAULT_SERIES).map((c) => c.name)
+  return { xColumn: x, chart: { type: "bar", yColumns: ys } }
+}
+
+export const availableChartTypes = (
+  groups: ColumnGroups,
+  hasOhlc: boolean,
+): ChartType[] => {
+  const types: ChartType[] = []
+  const hasNumeric = groups.numeric.length > 0
+  const hasTemporal = groups.temporal.length > 0
+  const hasCategorical = groups.categorical.length > 0
+  if (hasNumeric && (hasTemporal || hasCategorical)) {
+    types.push("line", "area", "stepLine", "stepArea", "bar", "stackedBar")
+  } else if (groups.numeric.length >= 2) {
+    types.push("line", "area", "stepLine", "stepArea")
+  }
+  if (
+    hasNumeric &&
+    (groups.numeric.length >= 2 || hasTemporal || hasCategorical)
+  )
+    types.push("scatter")
+  if (hasNumeric && hasCategorical) types.push("pie")
+  if (hasTemporal && (hasOhlc || groups.numeric.length >= 4))
+    types.push("candlestick")
+  return types.length ? types : ["bar"]
+}
diff --git a/src/scenes/Editor/Notebook/CellChart/questdbTheme.ts b/src/scenes/Editor/Notebook/CellChart/questdbTheme.ts
new file mode 100644
index 000000000..f5f38defd
--- /dev/null
+++ b/src/scenes/Editor/Notebook/CellChart/questdbTheme.ts
@@ -0,0 +1,112 @@
+const FOREGROUND = "#f8f8f2"
+const GRAY2 = "#bbbbbb"
+const COMMENT = "#6272a4"
+const SELECTION = "#44475a"
+const SPLIT_LINE = "rgba(68, 71, 90, 0.4)"
+const BACKGROUND_DARKER = "#22222c"
+
+const SERIES_PALETTE = [
+  "#8be9fd",
+  "#d14671",
+  "#ffb86c",
+  "#bd93f9",
+  "#f1fa8c",
+  "#ff79c6",
+  "#50fa7b",
+  "#ff5555",
+]
+
+const UP_FILL = "#50fa7b"
+const UP_BORDER = "#00aa3b"
+const DOWN_FILL = "#ff5555"
+const DOWN_BORDER = "#be2f5b"
+
+const axis = {
+  axisLine: { lineStyle: { color: SELECTION } },
+  axisTick: { lineStyle: { color: SELECTION } },
+  axisLabel: { color: GRAY2, fontSize: 12 },
+  splitLine: { lineStyle: { color: SPLIT_LINE } },
+  splitArea: {
+    areaStyle: { color: ["transparent", "rgba(255,255,255,0.02)"] },
+  },
+  nameTextStyle: { color: GRAY2, fontSize: 12 },
+  fontSize: undefined,
+}
+
+export const questdbTheme = {
+  color: SERIES_PALETTE,
+  backgroundColor: "#282a36",
+  // Canvas 2D font shorthand silently rejects the whole string if any token is malformed
+  // (CSS keywords, leading-hyphen families, unquoted hyphenated names) and falls back to
+  // "10px sans-serif", which then eats every fontSize. Keep to standard family names only.
+  textStyle: {
+    color: FOREGROUND,
+    fontFamily: "Helvetica, Arial, sans-serif",
+    fontSize: 12,
+  },
+  legend: {
+    textStyle: { color: GRAY2, fontSize: 12 },
+    inactiveColor: COMMENT,
+    pageTextStyle: { color: GRAY2, fontSize: 12 },
+    pageIconColor: GRAY2,
+    pageIconInactiveColor: COMMENT,
+  },
+  tooltip: {
+    appendToBody: true,
+    backgroundColor: BACKGROUND_DARKER,
+    borderColor: SELECTION,
+    borderWidth: 1,
+    textStyle: { color: FOREGROUND, fontSize: 12 },
+    axisPointer: {
+      lineStyle: { color: COMMENT },
+      crossStyle: { color: COMMENT },
+      label: { backgroundColor: SELECTION, color: FOREGROUND },
+    },
+  },
+  categoryAxis: axis,
+  valueAxis: axis,
+  timeAxis: axis,
+  logAxis: axis,
+  line: {
+    itemStyle: { borderWidth: 0 },
+    lineStyle: { width: 1.5 },
+    showSymbol: false,
+    symbol: "circle",
+    symbolSize: 6,
+    smooth: false,
+    textStyle: { fontSize: 12 },
+  },
+  bar: {
+    itemStyle: { barBorderWidth: 0, barBorderColor: SELECTION },
+  },
+  pie: {
+    itemStyle: { borderColor: BACKGROUND_DARKER, borderWidth: 1 },
+    label: { color: FOREGROUND },
+    labelLine: { lineStyle: { color: COMMENT } },
+  },
+  scatter: {
+    itemStyle: { borderWidth: 0 },
+  },
+  candlestick: {
+    itemStyle: {
+      color: UP_FILL,
+      color0: DOWN_FILL,
+      borderColor: UP_BORDER,
+      borderColor0: DOWN_BORDER,
+      borderWidth: 1,
+    },
+  },
+  dataZoom: {
+    backgroundColor: "transparent",
+    dataBackgroundColor: SELECTION,
+    fillerColor: "rgba(98, 114, 164, 0.2)",
+    handleColor: COMMENT,
+    handleSize: "100%",
+    textStyle: { color: GRAY2, fontSize: 12 },
+    borderColor: SELECTION,
+  },
+  toolbox: {
+    iconStyle: { borderColor: GRAY2 },
+    emphasis: { iconStyle: { borderColor: FOREGROUND } },
+  },
+}
diff --git a/src/scenes/Editor/Notebook/DrawCanvas/drawCanvasUtils.test.ts b/src/scenes/Editor/Notebook/DrawCanvas/drawCanvasUtils.test.ts
new file mode 100644
index 000000000..9e3dd94e4
--- /dev/null
+++ b/src/scenes/Editor/Notebook/DrawCanvas/drawCanvasUtils.test.ts
@@ -0,0 +1,203 @@
+import { describe, it, expect } from "vitest"
+import {
+  resolveDraw,
+  resultsEquivalent,
+  successResults,
+  toExecResult,
+} from "./drawCanvasUtils"
+import type { QueryExecResult } from "../../../../hooks/useQueryExecution"
+import type { SingleQueryResult } from "../../../../store/notebook"
+import type { ChartConfig } from "../CellChart/chartTypes"
+
+const dql = (
+  columns: { name: string; type: string }[],
+  dataset: (number | string | boolean | null)[][],
+  query = "q",
+): QueryExecResult => ({
+  type: "dql",
+  query,
+  columns,
+  dataset,
+  count: dataset.length,
+})
+
+describe("successResults", () => {
+  it("keeps only DQL with non-empty datasets", () => {
+    const rows: (QueryExecResult | null)[] = [
+      dql([{ name: "x", type: "INT" }], [[1]]),
+      null,
+      { type: "error", query: "bad", columns: [], dataset: [], count: 0 },
+      dql([{ name: "y", type: "INT" }], []),
+      {
+        type: "ddl",
+        query: "CREATE TABLE x (y INT)",
+        columns: [],
+        dataset: [],
+        count: 0,
+      },
+    ]
+    expect(successResults(rows)).toHaveLength(1)
+    expect(successResults(rows)[0].columns[0].name).toBe("x")
+  })
+
+  it("returns empty when nothing qualifies", () => {
+    expect(successResults([null, null])).toEqual([])
+    expect(successResults([])).toEqual([])
+  })
+})
+
+describe("resultsEquivalent", () => {
+  it("returns false on length mismatch", () => {
+    const a = [dql([{ name: "x", type: "INT" }], [[1]])]
+    const b: QueryExecResult[] = []
+    expect(resultsEquivalent(a, b)).toBe(false)
+  })
+
+  it("returns true for identical shape + values", () => {
+    const a = [dql([{ name: "x", type: "INT" }], [[1], [2], [3]])]
+    const b = [dql([{ name: "x", type: "INT" }], [[1], [2], [3]])]
+    expect(resultsEquivalent(a, b)).toBe(true)
+  })
+
+  it("returns false when column names differ", () => {
+    const a = [dql([{ name: "x", type: "INT" }], [[1]])]
+    const b = [dql([{ name: "y", type: "INT" }], [[1]])]
+    expect(resultsEquivalent(a, b)).toBe(false)
+  })
+
+  it("returns false when column count differs", () => {
+    const a = [
+      dql(
+        [
+          { name: "x", type: "INT" },
+          { name: "y", type: "INT" },
+        ],
+        [[1, 2]],
+      ),
+    ]
+    const b = [dql([{ name: "x", type: "INT" }], [[1]])]
+    expect(resultsEquivalent(a, b)).toBe(false)
+  })
+
+  it("returns false when dataset length differs", () => {
+    const a = [dql([{ name: "x", type: "INT" }], [[1], [2]])]
+    const b = [dql([{ name: "x", type: "INT" }], [[1]])]
+    expect(resultsEquivalent(a, b)).toBe(false)
+  })
+
+  it("returns true when both datasets are empty (no rows to compare)", () => {
+    const a = [dql([{ name: "x", type: "INT" }], [])]
+    const b = [dql([{ name: "x", type: "INT" }], [])]
+    expect(resultsEquivalent(a, b)).toBe(true)
+  })
+
+  it("returns false when first row differs but length matches", () => {
+    const a = [dql([{ name: "x", type: "INT" }], [[1], [9]])]
+    const b = [dql([{ name: "x", type: "INT" }], [[2], [9]])]
+    expect(resultsEquivalent(a, b)).toBe(false)
+  })
+
+  it("returns false when last row differs", () => {
+    const a = [dql([{ name: "x", type: "INT" }], [[1], [2], [9]])]
+    const b = [dql([{ name: "x", type: "INT" }], [[1], [2], [10]])]
+    expect(resultsEquivalent(a, b)).toBe(false)
+  })
+
+  it("returns false when a middle row differs (full deep compare)", () => {
+    const a = [dql([{ name: "x", type: "INT" }], [[1], [2], [3]])]
+    const b = [dql([{ name: "x", type: "INT" }], [[1], [99], [3]])]
+    expect(resultsEquivalent(a, b)).toBe(false)
+  })
+
+  it("compares multiple results side-by-side", () => {
+    const a = [
+      dql([{ name: "x", type: "INT" }], [[1]]),
+      dql([{ name: "y", type: "INT" }], [[2]]),
+    ]
+    const b = [
+      dql([{ name: "x", type: "INT" }], [[1]]),
+      dql([{ name: "y", type: "INT" }], [[2]]),
+    ]
+    expect(resultsEquivalent(a, b)).toBe(true)
+  })
+
+  it("handles null cell values", () => {
+    const a = [dql([{ name: "x", type: "INT" }], [[null], [null]])]
+    const b = [dql([{ name: "x", type: "INT" }], [[null], [null]])]
+    expect(resultsEquivalent(a, b)).toBe(true)
+
+    const c = [dql([{ name: "x", type: "INT" }], [[null], [null]])]
+    const d = [dql([{ name: "x", type: "INT" }], [[null], [1]])]
+    expect(resultsEquivalent(c, d)).toBe(false)
+  })
+})
+
+describe("resolveDraw — unresolved statements use a null slot, not an inert config", () => {
+  const tsPrice = (query: string) =>
+    dql(
+      [
+        { name: "ts", type: "TIMESTAMP" },
+        { name: "price", type: "DOUBLE" },
+      ],
+      [[1000, 5]],
+      query,
+    )
+
+  it("writes null (not {type:'line',yColumns:[]}) for a statement that hasn't resolved", () => {
+    const statements = ["SELECT ts, price FROM a", "SELECT ts, price FROM b"]
+    // Only the 2nd statement resolved; the 1st is still awaiting a result.
+    const results = [tsPrice("SELECT ts, price FROM b")]
+    const { effectiveConfig } = resolveDraw(statements, results, undefined)
+    // Slot 0 has no result and nothing saved → null, so a Save can't bake in a
+    // blank placeholder that would later suppress inference.
+    expect(effectiveConfig.queries[0]).toBeNull()
+    expect(effectiveConfig.queries[1]).not.toBeNull()
+  })
+
+  it("a saved null does not suppress inference once the statement resolves", () => {
+    const statements = ["SELECT ts, price FROM a", "SELECT ts, price FROM b"]
+    // Config saved earlier while statement 0 was unresolved → its slot is null.
+    const saved: ChartConfig = {
+      xColumn: "ts",
+      queries: [null, { type: "line", yColumns: ["price"] }],
+    }
+    // Both statements now return rows.
+    const results = [
+      tsPrice("SELECT ts, price FROM a"),
+      tsPrice("SELECT ts, price FROM b"),
+    ]
+    const { renderQueries } = resolveDraw(statements, results, saved)
+    const q0 = renderQueries.find((q) => q.index === 0)
+    // Inference ran for slot 0 (yColumns populated) — not a blank render.
+    expect(q0?.yColumns).toEqual(["price"])
+  })
+})
+
+describe("toExecResult", () => {
+  it("maps a DQL snapshot entry to a chartable QueryExecResult", () => {
+    const snap: SingleQueryResult = {
+      type: "dql",
+      query: "select x",
+      columns: [{ name: "x", type: "INT" }],
+      dataset: [[1], [2]],
+      count: 2,
+    }
+    const exec = toExecResult(snap)
+    expect(exec.type).toBe("dql")
+    expect(exec.dataset).toEqual([[1], [2]])
+    expect(exec.columns).toEqual([{ name: "x", type: "INT" }])
+    // round-trips through successResults (DQL with rows survives)
+    expect(successResults([exec])).toHaveLength(1)
+  })
+
+  it("maps non-DQL/transient entries to empty results that successResults drops", () => {
+    const entries: SingleQueryResult[] = [
+      { type: "ddl", query: "create table t (x int)" },
+      { type: "error", query: "bad", error: "boom" },
+      { type: "cancelled", query: "c" },
+    ]
+    const execs = entries.map(toExecResult)
+    expect(execs.every((e) => e.dataset.length === 0)).toBe(true)
+    expect(successResults(execs)).toHaveLength(0)
+  })
+})
diff --git a/src/scenes/Editor/Notebook/DrawCanvas/drawCanvasUtils.ts b/src/scenes/Editor/Notebook/DrawCanvas/drawCanvasUtils.ts
new file mode 100644
index 000000000..ab6833850
--- /dev/null
+++ b/src/scenes/Editor/Notebook/DrawCanvas/drawCanvasUtils.ts
@@ -0,0 +1,237 @@
+import type { QueryExecResult } from "../../../../hooks/useQueryExecution"
+import type { SingleQueryResult } from "../../../../store/notebook"
+import type { ColumnDefinition } from "../../../../utils/questdb/types"
+import type { ChartConfig, QueryChart } from "../CellChart/chartTypes"
+import type {
+  ChartGlobals,
+  ResolvedQuery,
+} from "../CellChart/buildEchartsOption"
+import {
+  classifyColumn,
+  findOhlc,
+  groupColumns,
+  inferChartConfig,
+} from "../CellChart/inferChartConfig"
+
+// Keep only DQL results that actually returned rows. The chart can't render
+// empty datasets, and non-DQL results (error/ddl/dml) have no columns.
+export const successResults = (
+  results: (QueryExecResult | null)[],
+): QueryExecResult[] =>
+  results.filter(
+    (r): r is QueryExecResult =>
+      r !== null && r.type === "dql" && r.dataset.length > 0,
+  )
+
+// Rehydrate a persisted snapshot entry into the QueryExecResult shape DrawCanvas
+// works with. Only DQL carries chartable data; other types map to empty results
+// (which successResults() then filters out).
+export const toExecResult = (r: SingleQueryResult): QueryExecResult => {
+  if (r.type === "dql") {
+    return {
+      type: "dql",
+      query: r.query,
+      columns: r.columns,
+      dataset: r.dataset,
+      count: r.count,
+      timings: r.timings,
+    }
+  }
+  if (r.type === "error") {
+    return {
+      type: "error",
+      query: r.query,
+      columns: [],
+      dataset: [],
+      count: 0,
+      error: r.error,
+    }
+  }
+  if (r.type === "ddl" || r.type === "dml") {
+    return { type: r.type, query: r.query, columns: [], dataset: [], count: 0 }
+  }
+  // transient (running/queued/cancelled) — not chartable
+  return { type: "error", query: r.query, columns: [], dataset: [], count: 0 }
+}
+
+export const resultsEquivalent = (
+  a: QueryExecResult[],
+  b: QueryExecResult[],
+): boolean => {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i]
+    const y = b[i]
+    if (x.columns.length !== y.columns.length) return false
+    for (let c = 0; c < x.columns.length; c++) {
+      if (x.columns[c].name !== y.columns[c].name) return false
+    }
+    if (x.dataset.length !== y.dataset.length) return false
+    for (let r = 0; r < x.dataset.length; r++) {
+      const rowA = x.dataset[r]
+      const rowB = y.dataset[r]
+      if (rowA.length !== rowB.length) return false
+      for (let c = 0; c < rowA.length; c++) {
+        if (rowA[c] !== rowB[c]) return false
+      }
+    }
+  }
+  return true
+}
+
+export type QueryTab = {
+  index: number
+  label: string
+  query: string
+  columns: ColumnDefinition[]
+  compatible: boolean
+  inferredChart: QueryChart
+}
+
+export type DrawResolution = {
+  chart: ChartGlobals
+  renderQueries: ResolvedQuery[] // enabled & x-compatible, anchor first — for echarts
+  effectiveConfig: ChartConfig // dense, statement-aligned — for the settings drawer
+  tabs: QueryTab[] // one per successful query — for the drawer tab strip
+}
+
+const xRoleOf = (columns: ColumnDefinition[], name: string | null) => {
+  const col = name != null ? columns.find((c) => c.name === name) : undefined
+  return col ? classifyColumn(col) : "other"
+}
+
+const resolveOhlc = (
+  qc: QueryChart,
+  columns: ColumnDefinition[],
+): QueryChart["ohlc"] | undefined => {
+  if (qc.type !== "candlestick") return undefined
+  const names = new Set(columns.map((c) => c.name))
+  const allPresent = (o: NonNullable<QueryChart["ohlc"]>) =>
+    names.has(o.open) &&
+    names.has(o.high) &&
+    names.has(o.low) &&
+    names.has(o.close)
+
+  if (qc.ohlc && allPresent(qc.ohlc)) return qc.ohlc
+
+  return findOhlc(groupColumns(columns).numeric)
+}
+
+// Drop references to columns the query no longer returns (e.g. a column removed
+// from the SELECT), so series/partition don't carry stale entries.
+const pruneQuery = (
+  qc: QueryChart,
+  columns: ColumnDefinition[],
+): QueryChart => {
+  const names = new Set(columns.map((c) => c.name))
+  const next: QueryChart = {
+    ...qc,
+    yColumns: (Array.isArray(qc.yColumns) ? qc.yColumns : []).filter((n) =>
+      names.has(n),
+    ),
+  }
+  if (next.partitionByColumn && !names.has(next.partitionByColumn))
+    delete next.partitionByColumn
+  return next
+}
+
+// Resolves the cell's queries into everything the chart + drawer need: matches
+// each successful result to its statement (stable index, tolerant of failures),
+// merges saved config with per-query inference, picks the anchor x-axis, and
+// flags x-incompatible queries. Pure so it can be memoized and tested.
+export const resolveDraw = (
+  statements: string[],
+  results: QueryExecResult[],
+  config: ChartConfig | undefined,
+): DrawResolution => {
+  const used = new Set<number>()
+  const items = results.map((r) => {
+    let idx = statements.indexOf(r.query)
+    if (idx >= 0 && used.has(idx)) {
+      idx = statements.findIndex((s, i) => s === r.query && !used.has(i))
+    }
+    if (idx >= 0) used.add(idx)
+    const inferred = inferChartConfig(r.columns, r.dataset, r.query)
+    const saved = idx >= 0 ? config?.queries[idx] : undefined
+    return {
+      idx,
+      r,
+      inferred,
+      qc: pruneQuery(saved ?? inferred.chart, r.columns),
+    }
+  })
+
+  const anchor = items[0]
+  // Drop a stale x-axis (a removed column) by falling back to inference.
+  const savedX = config?.xColumn
+  const anchorX: string | null =
+    savedX != null &&
+    anchor != null &&
+    anchor.r.columns.some((c) => c.name === savedX)
+      ? savedX
+      : (anchor?.inferred.xColumn ?? null)
+  const anchorRole = anchor ? xRoleOf(anchor.r.columns, anchorX) : "other"
+  const canCombine = anchorRole === "temporal" || anchorRole === "categorical"
+
+  const tabs: QueryTab[] = []
+  const renderQueries: ResolvedQuery[] = []
+  items.forEach((it, i) => {
+    const isAnchor = i === 0
+    const ownX = isAnchor ? anchorX : it.inferred.xColumn
+    const role = xRoleOf(it.r.columns, ownX)
+    const compatible = isAnchor || (canCombine && role === anchorRole)
+    const enabled = isAnchor ? true : (it.qc.enabled ?? true)
+    if (it.idx >= 0) {
+      tabs.push({
+        index: it.idx,
+        label: `Q${it.idx + 1}`,
+        query: it.r.query,
+        columns: it.r.columns,
+        compatible,
+        inferredChart: it.inferred.chart,
+      })
+    }
+    if (!compatible || !enabled) return
+    renderQueries.push({
+      index: it.idx,
+      columns: it.r.columns,
+      dataset: it.r.dataset,
+      xColumn: ownX,
+      type: it.qc.type,
+      yColumns: it.qc.yColumns ?? [],
+      ohlc: resolveOhlc(it.qc, it.r.columns),
+      partitionByColumn: it.qc.partitionByColumn,
+      axis: it.qc.axis ?? "left",
+      name: it.qc.name,
+    })
+  })
+
+  // Dense, statement-aligned config for the drawer: a concrete QueryChart per
+  // statement that ran, else the saved override, else `null` for unresolved statements.
+  const denseQueries: (QueryChart | null)[] = statements.map((_stmt, i) => {
+    const it = items.find((x) => x.idx === i)
+    if (it) {
+      const qc: QueryChart = { ...it.qc }
+      const oh = resolveOhlc(qc, it.r.columns)
+      if (oh) qc.ohlc = oh
+      return qc
+    }
+    return config?.queries[i] ?? null
+  })
+
+  return {
+    chart: {
+      xColumn: anchorX,
+      name: config?.name,
+      rightAxis: config?.rightAxis,
+    },
+    renderQueries,
+    effectiveConfig: {
+      xColumn: anchorX,
+      name: config?.name,
+      rightAxis: config?.rightAxis,
+      queries: denseQueries,
+    },
+    tabs,
+  }
+}
diff --git a/src/scenes/Editor/Notebook/DrawCanvas/index.tsx b/src/scenes/Editor/Notebook/DrawCanvas/index.tsx
new file mode 100644
index 000000000..34c5c0603
--- /dev/null
+++ b/src/scenes/Editor/Notebook/DrawCanvas/index.tsx
@@ -0,0 +1,401 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import styled from "styled-components"
+import type { NotebookCell } from "../../../../store/notebook"
+import type { ChartConfig } from "../CellChart/chartTypes"
+import { buildEchartsOption } from "../CellChart/buildEchartsOption"
+import {
+  ChartRenderer,
+  type ChartRendererHandle,
+} from "../CellChart/ChartRenderer"
+import { ChartActions } from "../CellChart/ChartActions"
+import { ChartSettingsDrawer } from "../CellChart/ChartSettingsDrawer"
+import { useAdaptivePoll } from "../../../../hooks/useAdaptivePoll"
+import { useQueryExecution } from "../../../../hooks/useQueryExecution"
+import type { QueryExecResult } from "../../../../hooks/useQueryExecution"
+import { getQueriesFromText } from "../../Monaco/utils"
+import {
+  resolveDraw,
+  resultsEquivalent,
+  successResults,
+  toExecResult,
+} from "./drawCanvasUtils"
+import { useNotebookActions } from "../NotebookProvider"
+import { useValidateWithGlobals } from "../globals/useValidateWithGlobals"
+import { toast } from "../../../../components/Toast"
+import { CircleNotchSpinner } from "../../Monaco/icons"
+import {
+  capResultBytes,
+  NOTEBOOK_BYTE_CAP,
+  NOTEBOOK_ROW_CAP,
+  singleResultFromExec,
+  sqlHash,
+} from "../notebookUtils"
+import {
+  deleteCellSnapshot,
+  loadCellSnapshot,
+} from "../../../../store/notebookResults"
+import { persistCellSnapshot } from "../persistCellSnapshot"
+
+const REFRESH_MIN_MS = 2000
+const REFRESH_MAX_MS = 60000
+const FETCH_DEBOUNCE_MS = 300
+// Draw auto-refresh can poll every few seconds; throttle snapshot writes so a
+// live chart doesn't churn IndexedDB. A reload restores the last saved frame.
+const SNAPSHOT_THROTTLE_MS = 10000
+
+const Wrapper = styled.div`
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  position: relative;
+  background: ${({ theme }) => theme.color.backgroundLighter};
+`
+
+const Canvas = styled.div`
+  flex: 1;
+  min-height: 0;
+  position: relative;
+`
+
+const EmptyState = styled.div`
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: ${({ theme }) => theme.color.gray2};
+  font-size: ${({ theme }) => theme.fontSize.sm};
+`
+
+type Props = {
+  cell: NotebookCell
+  bufferId?: number
+  isFocused: boolean
+  onConfigChange: (config: ChartConfig) => void
+  onAutoRefreshChange: (value: boolean) => void
+  onMaximizedChange: (value: boolean) => void
+}
+
+export const DrawCanvas: React.FC<Props> = ({
+  cell,
+  bufferId,
+  isFocused,
+  onConfigChange,
+  onAutoRefreshChange,
+  onMaximizedChange,
+}) => {
+  const { getVariables } = useNotebookActions()
+  const { executeSingle } = useQueryExecution(getVariables())
+  const validateWithGlobals = useValidateWithGlobals()
+  const [results, setResults] = useState<QueryExecResult[]>([])
+  const [settingsOpen, setSettingsOpen] = useState(false)
+  const [settledKey, setSettledKey] = useState<string | null>(null)
+  const [lastFetchHadError, setLastFetchHadError] = useState(false)
+  const [classifyBlock, setClassifyBlock] = useState<
+    | { kind: "write"; queryType: string }
+    | { kind: "failed"; message: string }
+    | null
+  >(null)
+  const [zoomStart, setZoomStart] = useState(0)
+  const [zoomEnd, setZoomEnd] = useState(100)
+  const [debouncedSql, setDebouncedSql] = useState(cell.value)
+  useEffect(() => {
+    const timer = setTimeout(
+      () => setDebouncedSql(cell.value),
+      FETCH_DEBOUNCE_MS,
+    )
+    return () => clearTimeout(timer)
+  }, [cell.value])
+
+  const classifyCache = useMemo(
+    () => new Map<string, "DQL" | "DDL_DML" | "ERROR">(),
+    [debouncedSql],
+  )
+
+  const configAtSettingsOpenRef = useRef<ChartConfig | undefined>(undefined)
+  const chartRendererRef = useRef<ChartRendererHandle | null>(null)
+  const isZoomed = zoomStart > 0 || zoomEnd < 100
+
+  const handleZoomChange = useCallback((start: number, end: number) => {
+    setZoomStart(start)
+    setZoomEnd(end)
+  }, [])
+
+  const handleResetZoom = useCallback(() => {
+    chartRendererRef.current?.resetZoom()
+    setZoomStart(0)
+    setZoomEnd(100)
+  }, [])
+
+  const queries = useMemo(
+    () => getQueriesFromText(debouncedSql),
+    [debouncedSql],
+  )
+  const queriesKey = queries.join("\u0001")
+
+  const inFlightRef = useRef<AbortController | null>(null)
+  const lastSnapshotAtRef = useRef(0)
+  const lastSavedRef = useRef<{
+    sqlHash: string
+    results: QueryExecResult[]
+  } | null>(null)
+
+  // Persist a bounded, throttled copy of the chart's rows — shared with run
+  // mode (one snapshot per cell) so the chart survives reload without re-fetch.
+  // Frames identical to the last saved one are skipped; a changed frame blocked
+  // by the throttle retries on the next poll tick, so the final frame persists.
+  const saveDrawSnapshot = useCallback(
+    (execResults: QueryExecResult[]) => {
+      if (bufferId === undefined) return
+      const currentSqlHash = sqlHash(debouncedSql)
+      const last = lastSavedRef.current
+      if (
+        last &&
+        last.sqlHash === currentSqlHash &&
+        resultsEquivalent(last.results, execResults)
+      )
+        return
+      const now = Date.now()
+      if (now - lastSnapshotAtRef.current < SNAPSHOT_THROTTLE_MS) return
+      lastSnapshotAtRef.current = now
+      lastSavedRef.current = { sqlHash: currentSqlHash, results: execResults }
+      const results = execResults.map((r) =>
+        capResultBytes(singleResultFromExec(r, r.query), NOTEBOOK_BYTE_CAP),
+      )
+      persistCellSnapshot({
+        bufferId,
+        cellId: cell.id,
+        sqlHash: currentSqlHash,
+        results,
+        savedAt: now,
+      })
+    },
+    [bufferId, cell.id, debouncedSql],
+  )
+
+  const clearDrawSnapshot = useCallback(() => {
+    if (bufferId === undefined) return
+    const currentSqlHash = sqlHash(debouncedSql)
+    const last = lastSavedRef.current
+    if (last && last.sqlHash === currentSqlHash && last.results.length === 0)
+      return
+    lastSavedRef.current = { sqlHash: currentSqlHash, results: [] }
+    void deleteCellSnapshot(bufferId, cell.id)
+  }, [bufferId, cell.id, debouncedSql])
+
+  const fetchAll = useCallback(async () => {
+    if (queries.length === 0) {
+      setResults((prev) => (prev.length === 0 ? prev : []))
+      setSettledKey(queriesKey)
+      setLastFetchHadError(false)
+      setClassifyBlock(null)
+      return
+    }
+    inFlightRef.current?.abort()
+    const ac = new AbortController()
+    inFlightRef.current = ac
+    try {
+      // Runtime backstop: a user typing DDL into an already-draw cell would
+      // otherwise reach executeSingle on the next poll tick.
+      try {
+        await Promise.all(
+          queries.map(async (q) => {
+            if (classifyCache.has(q)) return
+            const res = await validateWithGlobals(q, ac.signal)
+            if ("error" in res) classifyCache.set(q, "ERROR")
+            else if ("columns" in res) classifyCache.set(q, "DQL")
+            else classifyCache.set(q, "DDL_DML")
+          }),
+        )
+      } catch (e) {
+        if (ac.signal.aborted) return
+        const message = e instanceof Error ? e.message : "validate failed"
+        setClassifyBlock({ kind: "failed", message })
+        setSettledKey(queriesKey)
+        return
+      }
+      if (ac.signal.aborted) return
+      const offender = queries
+        .map((q) => ({ q, klass: classifyCache.get(q) }))
+        .find((x) => x.klass === "DDL_DML")
+      if (offender) {
+        const validateResult = await validateWithGlobals(
+          offender.q,
+          ac.signal,
+        ).catch(() => null)
+        if (ac.signal.aborted) return
+        const queryType =
+          validateResult && "queryType" in validateResult
+            ? validateResult.queryType
+            : "write"
+        setClassifyBlock({ kind: "write", queryType })
+        setResults((prev) => (prev.length === 0 ? prev : []))
+        setLastFetchHadError(false)
+        setSettledKey(queriesKey)
+        return
+      }
+      setClassifyBlock(null)
+      const out = await Promise.all(
+        queries.map((q) =>
+          executeSingle(q, ac.signal, NOTEBOOK_ROW_CAP).catch(() => null),
+        ),
+      )
+      if (ac.signal.aborted) return
+      const next = successResults(out)
+      setResults((prev) => (resultsEquivalent(prev, next) ? prev : next))
+      setLastFetchHadError(out.some((r) => r === null))
+      setSettledKey(queriesKey)
+      if (next.length > 0) saveDrawSnapshot(next)
+      else clearDrawSnapshot()
+    } finally {
+      if (inFlightRef.current === ac) inFlightRef.current = null
+    }
+  }, [
+    classifyCache,
+    executeSingle,
+    validateWithGlobals,
+    queries,
+    queriesKey,
+    saveDrawSnapshot,
+    clearDrawSnapshot,
+  ])
+
+  // On mount, render instantly from the persisted snapshot (shared with run
+  // mode) when it still matches this cell's SQL. autoRefresh-off cells then stay
+  // on the cached frame (no DB hit on load); autoRefresh-on cells let the poll
+  // refresh in the background. Falls back to a live fetch when there's no
+  // matching snapshot.
+  useEffect(() => {
+    let cancelled = false
+    void (async () => {
+      if (bufferId !== undefined) {
+        // Best-effort: a failed read falls through to a live fetch instead of
+        // leaving the chart on its loading spinner forever.
+        const snap = await loadCellSnapshot(bufferId, cell.id).catch(
+          () => undefined,
+        )
+        if (cancelled) return
+        if (snap && snap.sqlHash === sqlHash(debouncedSql)) {
+          const hydrated = successResults(snap.results.map(toExecResult))
+          if (hydrated.length > 0) {
+            // Don't clobber live data that may already have landed.
+            setResults((prev) => (prev.length > 0 ? prev : hydrated))
+            setSettledKey(queriesKey)
+            return
+          }
+        }
+      }
+      if (!cancelled) void fetchAll()
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [fetchAll, bufferId, cell.id, debouncedSql, queriesKey])
+
+  useEffect(
+    () => () => {
+      inFlightRef.current?.abort()
+    },
+    [],
+  )
+
+  const autoRefresh = cell.autoRefresh ?? true
+
+  useAdaptivePoll({
+    fetchFn: fetchAll,
+    enabled: autoRefresh && queries.length > 0,
+    key: `${cell.id}:${queriesKey}`,
+    minIntervalMs: REFRESH_MIN_MS,
+    maxIntervalMs: REFRESH_MAX_MS,
+  })
+
+  const resolution = useMemo(
+    () => resolveDraw(queries, results, cell.chartConfig),
+    [queries, results, cell.chartConfig],
+  )
+
+  const openSettings = useCallback(() => {
+    configAtSettingsOpenRef.current = cell.chartConfig
+    setSettingsOpen(true)
+  }, [cell.chartConfig])
+
+  const option = useMemo(
+    () => buildEchartsOption(resolution.chart, resolution.renderQueries),
+    [resolution],
+  )
+
+  const empty =
+    classifyBlock !== null || queries.length === 0 || results.length === 0
+  const settledForCurrentQueries = settledKey === queriesKey
+  // Initial load (snapshot hydration or first fetch) with nothing to show yet:
+  // a spinner replaces the chart area until data lands.
+  const loading =
+    queries.length > 0 &&
+    classifyBlock === null &&
+    !settledForCurrentQueries &&
+    results.length === 0
+  let emptyMessage: string
+  if (classifyBlock?.kind === "write") {
+    emptyMessage = `Cannot draw a write query ('${classifyBlock.queryType}'). Switch to Run mode to execute this SQL.`
+  } else if (classifyBlock?.kind === "failed") {
+    emptyMessage = `Cannot classify cell SQL (${classifyBlock.message}). Refusing to draw until the query can be classified safely.`
+  } else if (queries.length === 0) {
+    emptyMessage = "Type a query to draw."
+  } else if (!settledForCurrentQueries) {
+    emptyMessage = "Drawing\u2026"
+  } else if (lastFetchHadError) {
+    emptyMessage = "Query failed — check the SQL editor for the error."
+  } else {
+    emptyMessage = "No data to plot."
+  }
+
+  useEffect(() => {
+    if (!settingsOpen) return
+    if (cell.chartConfig !== configAtSettingsOpenRef.current) {
+      setSettingsOpen(false)
+      toast.info(
+        "Chart settings were updated by the assistant. Reopen chart configuration to edit.",
+      )
+    }
+  }, [cell.chartConfig, settingsOpen])
+
+  return (
+    <Wrapper>
+      <ChartActions
+        name={resolution.chart.name}
+        autoRefresh={autoRefresh}
+        onAutoRefreshChange={onAutoRefreshChange}
+        onManualRefresh={() => void fetchAll()}
+        isMaximized={!!cell.isChartMaximized}
+        onMaximizedChange={onMaximizedChange}
+        onOpenSettings={openSettings}
+        canResetZoom={isZoomed}
+        onResetZoom={handleResetZoom}
+        cellId={cell.id}
+      />
+      {loading ? (
+        <EmptyState>
+          <CircleNotchSpinner size={24} />
+        </EmptyState>
+      ) : empty ? (
+        <EmptyState>{emptyMessage}</EmptyState>
+      ) : (
+        <Canvas>
+          <ChartRenderer
+            ref={chartRendererRef}
+            option={option}
+            onZoomChange={handleZoomChange}
+            isFocused={isFocused}
+          />
+        </Canvas>
+      )}
+      <ChartSettingsDrawer
+        open={settingsOpen}
+        onClose={() => setSettingsOpen(false)}
+        tabs={resolution.tabs}
+        config={resolution.effectiveConfig}
+        onSave={onConfigChange}
+      />
+    </Wrapper>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/NotebookProvider.tsx b/src/scenes/Editor/Notebook/NotebookProvider.tsx
new file mode 100644
index 000000000..4163ad6bd
--- /dev/null
+++ b/src/scenes/Editor/Notebook/NotebookProvider.tsx
@@ -0,0 +1,570 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react"
+import type { MutableRefObject } from "react"
+import { unstable_batchedUpdates } from "react-dom"
+import { useEditor } from "../../../providers/EditorProvider"
+import { QuestContext } from "../../../providers/QuestProvider"
+import { MAX_NOTEBOOK_CELLS } from "../../../store/notebook"
+import type {
+  CellLayoutItem,
+  NotebookCell,
+  NotebookVariable,
+  NotebookViewState,
+  NotebookSettings,
+  CellMode,
+  CellType,
+} from "../../../store/notebook"
+import type { ChartConfig } from "./CellChart/chartTypes"
+import { useQueryExecution } from "../../../hooks/useQueryExecution"
+import { useCellsStore } from "./useCellsStore"
+import { useCellExecution } from "./useCellExecution"
+import { useNotebookPersistence } from "./useNotebookPersistence"
+import {
+  createNotebookController,
+  registerController,
+  unregisterController,
+  type NotebookControllerActions,
+} from "../../../utils/notebookAIBridge"
+import {
+  computeResultBottomHeight,
+  DEFAULT_CHART_BOTTOM_HEIGHT,
+  sqlHash,
+} from "./notebookUtils"
+import {
+  deleteCellSnapshot,
+  loadNotebookSnapshots,
+} from "../../../store/notebookResults"
+import { removeNotebookCellLayouts } from "./notebookColumnLayoutStore"
+import type { QueryKey } from "../../../store/Query/types"
+
+// State and actions live in SEPARATE contexts: action-only consumers never
+// re-render when state changes (the actions value is ref-stable for life).
+
+export type NotebookState = {
+  cells: NotebookCell[]
+  settings: NotebookSettings
+  focusedCellId: string | null
+  maximizedCellId: string | null
+  runningCellIds: Set<string>
+  // True until persisted result snapshots have been loaded on mount. Cells that
+  // had a result (lastRunStatus set) reserve their result area + show a spinner
+  // while this is true, so the hydrated grid lands without elongating the cell.
+  isHydrating: boolean
+}
+
+export type NotebookActions = {
+  getVariables: () => NotebookVariable[] | undefined
+  updateSettings: (updates: Partial<NotebookSettings>) => void
+  addCell: (afterCellId?: string, value?: string, type?: CellType) => string
+  deleteCell: (cellId: string) => void
+  updateCell: (cellId: string, updates: Partial<NotebookCell>) => void
+  moveCellUp: (cellId: string) => void
+  moveCellDown: (cellId: string) => void
+  duplicateCell: (cellId: string) => string
+  runCell: (
+    cellId: string,
+    sql?: string,
+    signal?: AbortSignal,
+  ) => Promise<boolean>
+  reRunResultAt: (cellId: string, index: number) => Promise<boolean>
+  cancelCell: (cellId: string) => void
+  cancelQuery: (cellId: string, index: number) => void
+  setActiveResultIndex: (cellId: string, index: number) => void
+  setCellMode: (cellId: string, mode: CellMode) => void
+  setCellChartConfig: (cellId: string, config: ChartConfig) => void
+  setCellAutoRefresh: (cellId: string, value: boolean) => void
+  setCellChartMaximized: (cellId: string, value: boolean) => void
+  setCellLayout: (
+    cellId: string,
+    pos: { x: number; y: number; w: number; h: number },
+  ) => void
+  setFocusedCell: (cellId: string | null) => void
+  setMaximizedCellId: (cellId: string | null) => void
+  getCellsSnapshot: () => NotebookCell[]
+}
+
+export type NotebookContextType = NotebookState & NotebookActions
+
+type LiveNotebookActions = NotebookActions & NotebookControllerActions
+
+type ActionMap = Record<string, (...args: never[]) => unknown>
+
+const NOOP_ACTIONS: NotebookActions = {
+  getVariables: () => undefined,
+  updateSettings: () => undefined,
+  addCell: () => "",
+  deleteCell: () => undefined,
+  updateCell: () => undefined,
+  moveCellUp: () => undefined,
+  moveCellDown: () => undefined,
+  duplicateCell: () => "",
+  runCell: () => Promise.resolve(false),
+  reRunResultAt: () => Promise.resolve(false),
+  cancelCell: () => undefined,
+  cancelQuery: () => undefined,
+  setActiveResultIndex: () => undefined,
+  setCellMode: () => undefined,
+  setCellChartConfig: () => undefined,
+  setCellAutoRefresh: () => undefined,
+  setCellChartMaximized: () => undefined,
+  setCellLayout: () => undefined,
+  setFocusedCell: () => undefined,
+  setMaximizedCellId: () => undefined,
+  getCellsSnapshot: () => [],
+}
+
+const NOOP_LIVE_ACTIONS: LiveNotebookActions = {
+  ...NOOP_ACTIONS,
+  getSettings: () => ({}),
+  getMaximizedCellId: () => null,
+  updateCells: () => undefined,
+}
+
+const NOTEBOOK_ACTION_KEYS = Object.keys(NOOP_ACTIONS) as Array<
+  keyof NotebookActions
+>
+
+const createStableActionProxy = <T extends ActionMap, K extends keyof T>(
+  ref: MutableRefObject<T>,
+  keys: K[],
+): Pick<T, K> =>
+  Object.fromEntries(
+    keys.map((key) => [
+      key,
+      (...args: Parameters<T[K]>) => ref.current[key](...args),
+    ]),
+  ) as Pick<T, K>
+
+const EMPTY_STATE: NotebookState = {
+  cells: [],
+  settings: {},
+  focusedCellId: null,
+  maximizedCellId: null,
+  runningCellIds: new Set(),
+  isHydrating: false,
+}
+
+const createNotebookQueryKey = (
+  bufferId: number,
+  cellId: string,
+  runId: number,
+): QueryKey => `notebook:${bufferId}:${cellId}:run-${runId}@0-0` as QueryKey
+
+const createNotebookScopeKey = (bufferId: number, cellId: string): string =>
+  `notebook:${bufferId}:${cellId}`
+
+const NotebookStateContext = createContext<NotebookState>(EMPTY_STATE)
+const NotebookActionsContext = createContext<NotebookActions>(NOOP_ACTIONS)
+
+export const useNotebookState = () => useContext(NotebookStateContext)
+export const useNotebookActions = () => useContext(NotebookActionsContext)
+
+export const useNotebook = (): NotebookContextType => {
+  const state = useNotebookState()
+  const actions = useNotebookActions()
+  return useMemo(() => ({ ...state, ...actions }), [state, actions])
+}
+
+export const NotebookProvider: React.FC<{
+  initialState: NotebookViewState
+  bufferId: number
+}> = ({ initialState, bufferId, children }) => {
+  const { updateBuffer } = useEditor()
+  const { questExecution } = useContext(QuestContext)
+
+  const [focusedCellId, setFocusedCellState] = useState<string | null>(
+    initialState.focusedCellId ?? null,
+  )
+  const [maximizedCellId, setMaximizedCellIdState] = useState<string | null>(
+    () =>
+      initialState.maximizedCellId &&
+      initialState.cells.some((c) => c.id === initialState.maximizedCellId)
+        ? initialState.maximizedCellId
+        : null,
+  )
+  const [settings, setSettingsState] = useState<NotebookSettings>(
+    initialState.settings ?? {},
+  )
+
+  const focusedCellIdRef = useRef(focusedCellId)
+  const maximizedCellIdRef = useRef(maximizedCellId)
+  const settingsRef = useRef(settings)
+  const activeCellQueryKeysRef = useRef<Map<string, QueryKey>>(new Map())
+  const notebookRunIdRef = useRef(0)
+  const liveActionsRef = useRef<LiveNotebookActions>(NOOP_LIVE_ACTIONS)
+
+  const { executeSingle } = useQueryExecution(settings.variables)
+
+  const { persistCells, persistImmediately, persistDebounced } =
+    useNotebookPersistence({
+      bufferId,
+      updateBuffer,
+      focusedCellIdRef,
+      maximizedCellIdRef,
+      settingsRef,
+    })
+
+  const store = useCellsStore({
+    initialCells: initialState.cells,
+    persistCells,
+  })
+
+  // Restore persisted result snapshots on mount. Results are stripped before
+  // persist, so cells load empty; rehydrate each from its bounded snapshot when
+  // the cell's SQL still matches and no live result has landed yet. Cells that
+  // had a result (`lastRunStatus` set — known synchronously) reserve their
+  // result area + show a spinner while `isHydrating`, so the grid lands in
+  // place rather than elongating the cell once this async load resolves.
+  const { hydrateCells, cellsRef } = store
+  const [hydrationSettled, setHydrationSettled] = useState(false)
+  useEffect(() => {
+    let cancelled = false
+    loadNotebookSnapshots(bufferId)
+      .then((snapshots) => {
+        if (cancelled) return
+        const byCell = new Map(snapshots.map((s) => [s.cellId, s]))
+        hydrateCells((prev) =>
+          prev.map((cell) => {
+            if (cell.result) return cell
+            const snap = byCell.get(cell.id)
+            if (!snap || snap.sqlHash !== sqlHash(cell.value)) return cell
+            return {
+              ...cell,
+              result: {
+                results: snap.results,
+                activeResultIndex: 0,
+                timestamp: snap.savedAt,
+              },
+            }
+          }),
+        )
+        const liveCellIds = new Set(cellsRef.current.map((c) => c.id))
+        snapshots
+          .filter((s) => !liveCellIds.has(s.cellId))
+          .forEach((s) => void deleteCellSnapshot(bufferId, s.cellId))
+      })
+      .catch(() => undefined)
+      .finally(() => {
+        if (!cancelled) setHydrationSettled(true)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [bufferId, hydrateCells])
+
+  const execution = useCellExecution({
+    bufferId,
+    cellsRef,
+    executeSingle,
+    updateCellResult: store.updateCellResult,
+    updateCell: store.updateCell,
+    updateCells: store.updateCells,
+    markCancelledAll: store.markCancelledAll,
+    markCancelledOne: store.markCancelledOne,
+    setScriptSummary: store.setScriptSummary,
+  })
+
+  const setFocusedCell = useCallback(
+    (cellId: string | null) => {
+      if (focusedCellIdRef.current === cellId) return
+      focusedCellIdRef.current = cellId
+      setFocusedCellState(cellId)
+      persistDebounced(store.cellsRef.current)
+    },
+    [persistDebounced, store.cellsRef],
+  )
+
+  const updateSettings = useCallback(
+    (updates: Partial<NotebookSettings>) => {
+      const next = { ...settingsRef.current, ...updates }
+      settingsRef.current = next
+      setSettingsState(next)
+      persistImmediately(store.cellsRef.current)
+    },
+    [persistImmediately, store.cellsRef],
+  )
+
+  const setMaximizedCellId = useCallback(
+    (cellId: string | null) => {
+      maximizedCellIdRef.current = cellId
+      setMaximizedCellIdState(cellId)
+      persistImmediately(store.cellsRef.current)
+    },
+    [persistImmediately, store.cellsRef],
+  )
+
+  const setCellLayout = useCallback(
+    (cellId: string, pos: { x: number; y: number; w: number; h: number }) => {
+      const prev = settingsRef.current
+      const layout = prev.layout ?? []
+      const idx = layout.findIndex((l) => l.i === cellId)
+      const nextLayout: CellLayoutItem[] =
+        idx >= 0
+          ? layout.map((l) => (l.i === cellId ? { ...l, ...pos } : l))
+          : [...layout, { i: cellId, ...pos }]
+      const next = { ...prev, layout: nextLayout }
+      settingsRef.current = next
+      setSettingsState(next)
+      persistImmediately(store.cellsRef.current)
+    },
+    [persistImmediately, store.cellsRef],
+  )
+
+  // In grid mode, freshly added cells must land in `settings.layout` so
+  // mergeCellLayout has a real position entry to read. The `h` value
+  // written here is a placeholder — the actual rendered grid h is derived
+  // at render time from cell.topHeight + cell.bottomHeight (see
+  // computeCellGridH).
+  const addCell = useCallback(
+    (afterCellId?: string, value?: string, type?: CellType): string => {
+      if (store.cellsRef.current.length >= MAX_NOTEBOOK_CELLS) return ""
+      let newId = ""
+      unstable_batchedUpdates(() => {
+        newId = store.addCell(afterCellId, value, type)
+        if (settingsRef.current.layoutMode !== "grid") return
+        const layout = settingsRef.current.layout ?? []
+        const maxY =
+          layout.length > 0 ? Math.max(...layout.map((l) => l.y + l.h)) : 0
+        // h = 1 sentinel; computeCellGridH overrides at render.
+        setCellLayout(newId, { x: 0, y: maxY, w: 12, h: 1 })
+      })
+      return newId
+    },
+    [store, setCellLayout],
+  )
+
+  // Mode toggle: when a cell flips between run and draw, seed bottomHeight
+  // with the mode-appropriate default. This puts the cell into double-view
+  // immediately for draw, and back to single-view (or result-double-view)
+  // for run.
+  const setCellMode = useCallback(
+    (cellId: string, mode: CellMode) => {
+      store.setCellMode(cellId, mode)
+      if (mode === "draw") {
+        store.updateCell(cellId, { bottomHeight: DEFAULT_CHART_BOTTOM_HEIGHT })
+      } else {
+        // back to run mode: size the bottom slot based on what the
+        // existing result actually contains (DQL-with-rows → 10-row
+        // height; DDL/DML/error/empty → notification-only). No result
+        // yet → drop to single-view by clearing bottomHeight.
+        const cell = store.cellsRef.current.find((c) => c.id === cellId)
+        store.updateCell(cellId, {
+          bottomHeight: cell?.result
+            ? computeResultBottomHeight(cell.result)
+            : undefined,
+        })
+      }
+    },
+    [store],
+  )
+
+  const cancelCell = useCallback(
+    (cellId: string) => {
+      execution.cancelCell(cellId)
+
+      const queryKey = activeCellQueryKeysRef.current.get(cellId)
+      if (queryKey) {
+        activeCellQueryKeysRef.current.delete(cellId)
+        questExecution.releaseExecution(
+          queryKey,
+          createNotebookScopeKey(bufferId, cellId),
+        )
+      }
+    },
+    [bufferId, execution, questExecution],
+  )
+
+  const runCellNow = useCallback(
+    async (
+      cellId: string,
+      queryKey: QueryKey,
+      scopeKey: string,
+      sql?: string,
+      signal?: AbortSignal,
+    ) => {
+      activeCellQueryKeysRef.current.set(cellId, queryKey)
+
+      try {
+        const ok = await execution.runCell(cellId, sql, signal)
+        // Every run (success OR error) puts the cell into result-double-view.
+        // Height is conditioned on the actual result shape so DDL/DML/empty-
+        // DQL/error results don't reserve 10 blank rows of space. Any prior user
+        // drag of the bottom handle is discarded on re-run.
+        const cell = store.cellsRef.current.find((c) => c.id === cellId)
+        if (cell && cell.mode !== "draw" && cell.type !== "markdown") {
+          store.updateCell(cellId, {
+            bottomHeight: computeResultBottomHeight(cell.result),
+          })
+        }
+
+        return ok
+      } finally {
+        if (activeCellQueryKeysRef.current.get(cellId) === queryKey) {
+          activeCellQueryKeysRef.current.delete(cellId)
+          questExecution.releaseExecution(queryKey, scopeKey)
+        }
+      }
+    },
+    [execution, questExecution, store],
+  )
+
+  const runCell = useCallback(
+    async (cellId: string, sql?: string, signal?: AbortSignal) => {
+      const runId = ++notebookRunIdRef.current
+      const queryKey = createNotebookQueryKey(bufferId, cellId, runId)
+      const scopeKey = createNotebookScopeKey(bufferId, cellId)
+
+      return new Promise<boolean>((resolve) => {
+        const execute = () => {
+          void runCellNow(cellId, queryKey, scopeKey, sql, signal).then(resolve)
+        }
+        const request = () =>
+          questExecution.requestExecution({
+            abort: () => cancelCell(cellId),
+            bufferId,
+            execute,
+            onDismiss: () => resolve(false),
+            queryKey,
+            scopeKey,
+          })
+
+        if (signal) {
+          questExecution.dismissPending(scopeKey)
+          questExecution.abortActiveByScope(scopeKey)
+          request()
+          return
+        }
+
+        request()
+      })
+    },
+    [bufferId, cancelCell, questExecution, runCellNow],
+  )
+
+  const deleteCell = useCallback(
+    (cellId: string) => {
+      cancelCell(cellId)
+      store.removeCellById(cellId)
+      void deleteCellSnapshot(bufferId, cellId)
+      removeNotebookCellLayouts(bufferId, cellId)
+      if (focusedCellIdRef.current === cellId) {
+        setFocusedCell(null)
+      }
+      if (maximizedCellIdRef.current === cellId) {
+        setMaximizedCellId(null)
+      }
+    },
+    [store, setMaximizedCellId, cancelCell, bufferId],
+  )
+
+  const duplicateCell = useCallback(
+    (cellId: string): string => {
+      if (store.cellsRef.current.length >= MAX_NOTEBOOK_CELLS) return ""
+      // batchedUpdates ensures the cells append and the layout entry land
+      // in a single render. React 17 doesn't auto-batch outside event
+      // handlers (Radix DropdownMenu defers onSelect via setTimeout), so
+      // without this the duplicate flashes at the bottom before snapping
+      // into place.
+      let newId = ""
+      unstable_batchedUpdates(() => {
+        newId = store.duplicateCell(cellId)
+        if (settingsRef.current.layoutMode !== "grid") return
+        const layout = settingsRef.current.layout ?? []
+        const original = layout.find((l) => l.i === cellId)
+        if (!original) return
+        setCellLayout(newId, {
+          x: original.x,
+          y: original.y,
+          w: original.w,
+          h: original.h,
+        })
+      })
+      return newId
+    },
+    [store, setCellLayout],
+  )
+
+  liveActionsRef.current = {
+    getVariables: () => settingsRef.current.variables,
+    updateSettings,
+    addCell,
+    deleteCell,
+    updateCell: store.updateCell,
+    moveCellUp: store.moveCellUp,
+    moveCellDown: store.moveCellDown,
+    duplicateCell,
+    runCell,
+    reRunResultAt: execution.reRunResultAt,
+    cancelCell,
+    cancelQuery: execution.cancelQuery,
+    setActiveResultIndex: execution.setActiveResultIndex,
+    setCellMode,
+    setCellChartConfig: store.setCellChartConfig,
+    setCellAutoRefresh: store.setCellAutoRefresh,
+    setCellChartMaximized: store.setCellChartMaximized,
+    setCellLayout,
+    setFocusedCell,
+    setMaximizedCellId,
+    getCellsSnapshot: () => store.cellsRef.current.slice(),
+    getSettings: () => ({ ...settingsRef.current }),
+    getMaximizedCellId: () => maximizedCellIdRef.current,
+    updateCells: store.updateCells,
+  }
+
+  const stateValue = useMemo<NotebookState>(
+    () => ({
+      cells: store.cells,
+      settings,
+      focusedCellId,
+      maximizedCellId,
+      runningCellIds: execution.runningCellIds,
+      isHydrating: !hydrationSettled,
+    }),
+    [
+      store.cells,
+      settings,
+      focusedCellId,
+      maximizedCellId,
+      execution.runningCellIds,
+      hydrationSettled,
+    ],
+  )
+
+  const actionsValue = useMemo<NotebookActions>(
+    () => createStableActionProxy(liveActionsRef, NOTEBOOK_ACTION_KEYS),
+    [],
+  )
+
+  useEffect(() => {
+    const activeCellQueryKeys = activeCellQueryKeysRef.current
+    return () => {
+      activeCellQueryKeys.forEach((queryKey, cellId) => {
+        const scopeKey = createNotebookScopeKey(bufferId, cellId)
+        questExecution.dismissPending(scopeKey)
+        questExecution.releaseExecution(queryKey, scopeKey)
+      })
+      activeCellQueryKeys.clear()
+    }
+  }, [bufferId, questExecution])
+
+  useEffect(() => {
+    const controller = createNotebookController(bufferId, liveActionsRef)
+    registerController(controller)
+    return () => unregisterController(bufferId)
+  }, [bufferId])
+
+  return (
+    <NotebookActionsContext.Provider value={actionsValue}>
+      <NotebookStateContext.Provider value={stateValue}>
+        {children}
+      </NotebookStateContext.Provider>
+    </NotebookActionsContext.Provider>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/NotebookToolbar.tsx b/src/scenes/Editor/Notebook/NotebookToolbar.tsx
new file mode 100644
index 000000000..979410907
--- /dev/null
+++ b/src/scenes/Editor/Notebook/NotebookToolbar.tsx
@@ -0,0 +1,348 @@
+import React, { useEffect, useRef, useState } from "react"
+import styled, { css } from "styled-components"
+import { Box, Button, Tooltip } from "../../../components"
+import { AISparkle } from "../../../components/AISparkle"
+import {
+  DownloadSimpleIcon,
+  ListIcon,
+  NotebookIcon,
+  PencilSimpleLineIcon,
+  SquaresFourIcon,
+} from "@phosphor-icons/react"
+import { CopyAlt } from "@styled-icons/boxicons-regular"
+import { color } from "../../../utils"
+import { toast } from "../../../components/Toast"
+import { trackEvent } from "../../../modules/ConsoleEventTracker"
+import { ConsoleEvent } from "../../../modules/ConsoleEventTracker/events"
+import { exportBuffers } from "../Monaco/exportTabs"
+import { useNotebookActions, useNotebookState } from "./NotebookProvider"
+import type { NotebookLayoutMode } from "../../../store/notebook"
+import { useEditor } from "../../../providers/EditorProvider"
+import { useAIConversationActions } from "../../../providers/AIConversationProvider"
+import {
+  isBlockingAIStatus,
+  useAIStatus,
+} from "../../../providers/AIStatusProvider"
+import { emitUserAction } from "../../../utils/notebookAIBridge"
+import { VariablesPopover } from "./globals/VariablesPopover"
+
+const Toolbar = styled(Box).attrs({
+  align: "center",
+  justifyContent: "space-between",
+})`
+  width: 100%;
+  padding: 0.8rem 2.5rem;
+  background: ${color("midnight")};
+  border-bottom: 1px solid ${color("baseGrey")};
+  box-shadow: 0 2px 10px 0 rgba(23, 23, 23, 0.35);
+  flex-shrink: 0;
+  position: relative;
+  z-index: 1;
+`
+
+const NotebookGlyph = styled(NotebookIcon)`
+  flex-shrink: 0;
+  color: ${color("pinkPrimary")};
+`
+
+const TitleContainer = styled(Box).attrs({ align: "center", gap: "0.5rem" })`
+  min-width: 0;
+`
+
+const Name = styled.span`
+  min-width: 0;
+  font-size: 1.6rem;
+  font-weight: 600;
+  letter-spacing: -0.32px;
+  color: ${color("foreground")};
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+`
+
+const NameInput = styled.input`
+  min-width: 0;
+  font-family: inherit;
+  font-size: 1.6rem;
+  font-weight: 600;
+  color: ${color("foreground")};
+  background: transparent;
+  border: 1px solid ${color("pinkDarker")};
+  border-radius: 4px;
+  outline: none;
+  padding: 0.2rem 0.6rem;
+
+  &::selection {
+    background: ${color("pinkPrimary")};
+  }
+`
+
+const EditButton = styled.button`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  padding: 0.3rem;
+  background: transparent;
+  border: none;
+  border-radius: 4px;
+  color: ${color("gray2")};
+  cursor: pointer;
+
+  &:hover {
+    color: ${color("foreground")};
+    background: ${color("selection")};
+  }
+`
+
+// Mirrors SchemaAIButton's skin; kept inline because SchemaAIButton carries schema-access gating that doesn't apply here.
+const BuildWithAIButton = styled(Button).attrs({ skin: "gradient" })`
+  border: 1px solid ${({ theme }) => theme.color.pinkDarker};
+  &:hover:not([disabled]) {
+    border: 1px solid ${({ theme }) => theme.color.pinkDarker};
+  }
+  &:disabled {
+    svg {
+      filter: grayscale(100%);
+    }
+  }
+`
+
+const TooltipButton: React.FC<{
+  tooltip: string
+  children: React.ReactNode
+}> = ({ tooltip, children }) => (
+  // The span keeps the tooltip working while the button is disabled (a
+  // disabled button receives no pointer events of its own).
+  <Tooltip content={tooltip}>
+    <span style={{ display: "inline-flex" }}>{children}</span>
+  </Tooltip>
+)
+
+const ToggleGroup = styled.div`
+  display: flex;
+  gap: 2px;
+  padding: 3px;
+  background: ${color("backgroundLighter")};
+  border: 1px solid rgba(68, 71, 90, 0.5);
+  border-radius: 0.4rem;
+`
+
+const ToggleButton = styled.button<{ $active: boolean }>`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.6rem;
+  padding: 0 2rem;
+  height: 3rem;
+  font-size: 1.4rem;
+  border: none;
+  background: transparent;
+  color: ${color("gray2")};
+  cursor: pointer;
+  transition: all 0.1s;
+  border-radius: 0.4rem;
+
+  &:hover {
+    background: ${color("selectionDarker")};
+    color: ${color("foreground")};
+  }
+
+  ${({ $active }) =>
+    $active &&
+    css`
+      background: ${color("selection")};
+      color: ${color("foreground")};
+      &:hover {
+        background: ${color("selection")};
+      }
+    `}
+`
+
+export const NotebookToolbar: React.FC = () => {
+  const { settings } = useNotebookState()
+  const { updateSettings } = useNotebookActions()
+  const { activeBuffer, buffers, duplicateNotebook, updateBuffer } = useEditor()
+  const { openNotebookChat } = useAIConversationActions()
+  const { canUse, status: aiStatus } = useAIStatus()
+  const isOperationInProgress = isBlockingAIStatus(aiStatus)
+  const mode: NotebookLayoutMode = settings.layoutMode ?? "list"
+  const hasBuffer = typeof activeBuffer.id === "number"
+  // activeBuffer is a cached snapshot that updateBuffer doesn't refresh; read the
+  // label from the live buffers query so a rename shows immediately.
+  const label =
+    buffers.find((b) => b.id === activeBuffer.id)?.label ??
+    activeBuffer.label ??
+    ""
+  const aiTooltip = !canUse
+    ? "AI Assistant is not configured"
+    : isOperationInProgress
+      ? "An operation is in progress"
+      : "Build with AI"
+
+  const [isRenaming, setIsRenaming] = useState(false)
+  const [draftName, setDraftName] = useState("")
+  const nameInputRef = useRef<HTMLInputElement>(null)
+  // Set when the rename is cancelled (Escape) so the resulting blur discards.
+  const cancelRenameRef = useRef(false)
+  // The buffer being renamed, captured at start: the active buffer can change
+  // mid-rename (e.g. an agent activating another notebook), and commit must
+  // still target the notebook the user actually edited.
+  const renameTargetRef = useRef<{ id: number; label: string } | null>(null)
+
+  useEffect(() => {
+    if (isRenaming) {
+      nameInputRef.current?.focus()
+      nameInputRef.current?.select()
+    }
+  }, [isRenaming])
+
+  const startRename = () => {
+    if (typeof activeBuffer.id !== "number") return
+    renameTargetRef.current = { id: activeBuffer.id, label }
+    setDraftName(label)
+    setIsRenaming(true)
+  }
+
+  // Blur is the single commit path: Enter/Escape both blur the input.
+  const commitRename = () => {
+    setIsRenaming(false)
+    const target = renameTargetRef.current
+    renameTargetRef.current = null
+    if (cancelRenameRef.current) {
+      cancelRenameRef.current = false
+      return
+    }
+    if (!target) return
+    const trimmed = draftName.trim()
+    if (!trimmed || trimmed === target.label) return
+    void trackEvent(ConsoleEvent.TAB_RENAME)
+    void updateBuffer(target.id, { label: trimmed })
+  }
+
+  const handleNameKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "Enter") {
+      nameInputRef.current?.blur()
+    } else if (e.key === "Escape") {
+      cancelRenameRef.current = true
+      nameInputRef.current?.blur()
+    }
+  }
+
+  // User-origin only: tool-driven set_layout_mode bypasses this handler so it doesn't appear in the AI digest.
+  const handleModeChange = (next: NotebookLayoutMode) => {
+    if (next === mode) return
+    updateSettings({ layoutMode: next })
+    if (typeof activeBuffer.id === "number") {
+      emitUserAction({
+        kind: "user_changed_layout_mode",
+        bufferId: activeBuffer.id,
+        mode: next,
+      })
+    }
+  }
+
+  const handleBuildWithAI = () => {
+    if (typeof activeBuffer.id !== "number") return
+    void openNotebookChat(activeBuffer.id)
+  }
+
+  const handleDuplicate = () => {
+    if (typeof activeBuffer.id !== "number") return
+    void duplicateNotebook(activeBuffer.id)
+  }
+
+  const handleExport = () => {
+    if (typeof activeBuffer.id !== "number") return
+    void trackEvent(ConsoleEvent.TAB_EXPORT, { type: "notebook" })
+    exportBuffers({ bufferId: activeBuffer.id }).catch((err) => {
+      toast.error(
+        `Failed to export notebook: ${err instanceof Error ? err.message : "Unknown error"}`,
+      )
+    })
+  }
+
+  return (
+    <Toolbar>
+      <Box align="center" gap="1rem">
+        <NotebookGlyph size={20} weight="fill" />
+        {isRenaming ? (
+          <NameInput
+            ref={nameInputRef}
+            value={draftName}
+            onChange={(e) => setDraftName(e.target.value)}
+            onKeyDown={handleNameKeyDown}
+            onBlur={commitRename}
+            aria-label="Notebook name"
+            data-hook="notebook-rename-input"
+          />
+        ) : (
+          <TitleContainer>
+            <Name title={label}>{label}</Name>
+            {hasBuffer && (
+              <Tooltip content="Rename notebook">
+                <EditButton
+                  onClick={startRename}
+                  aria-label="Rename notebook"
+                  data-hook="notebook-rename"
+                >
+                  <PencilSimpleLineIcon size={16} />
+                </EditButton>
+              </Tooltip>
+            )}
+          </TitleContainer>
+        )}
+      </Box>
+      <Box align="center" gap="0.8rem">
+        <TooltipButton tooltip={aiTooltip}>
+          <BuildWithAIButton
+            disabled={!canUse || isOperationInProgress || !hasBuffer}
+            onClick={handleBuildWithAI}
+            aria-label="Build with AI"
+          >
+            <AISparkle size={18} variant="hollow" />
+          </BuildWithAIButton>
+        </TooltipButton>
+        <TooltipButton tooltip="Duplicate notebook">
+          <Button
+            skin="secondary"
+            disabled={!hasBuffer}
+            onClick={handleDuplicate}
+            aria-label="Duplicate notebook"
+          >
+            <CopyAlt size={18} />
+          </Button>
+        </TooltipButton>
+        <TooltipButton tooltip="Export notebook">
+          <Button
+            skin="secondary"
+            disabled={!hasBuffer}
+            onClick={handleExport}
+            aria-label="Export notebook"
+          >
+            <DownloadSimpleIcon size={18} />
+          </Button>
+        </TooltipButton>
+        <VariablesPopover />
+        <ToggleGroup>
+          <ToggleButton
+            $active={mode === "list"}
+            onClick={() => handleModeChange("list")}
+            title="List layout"
+          >
+            <ListIcon size={18} />
+            List
+          </ToggleButton>
+          <ToggleButton
+            $active={mode === "grid"}
+            onClick={() => handleModeChange("grid")}
+            title="Grid layout"
+          >
+            <SquaresFourIcon size={18} />
+            Grid
+          </ToggleButton>
+        </ToggleGroup>
+      </Box>
+    </Toolbar>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/NotebookWorkspaceBridge.tsx b/src/scenes/Editor/Notebook/NotebookWorkspaceBridge.tsx
new file mode 100644
index 000000000..d1c57e1a2
--- /dev/null
+++ b/src/scenes/Editor/Notebook/NotebookWorkspaceBridge.tsx
@@ -0,0 +1,146 @@
+import React, { useEffect, useRef } from "react"
+import { useEditor } from "../../../providers/EditorProvider"
+import {
+  NotebookToolError,
+  registerWorkspace,
+  unregisterWorkspace,
+  waitForController,
+  type NotebookWorkspaceBufferMeta,
+} from "../../../utils/notebookAIBridge"
+
+export const NotebookWorkspaceBridge: React.FC = () => {
+  const {
+    buffers,
+    activeBuffer,
+    addBuffer,
+    setActiveBuffer,
+    archiveBuffer,
+    duplicateNotebook: duplicateNotebookBuffer,
+    updateBuffersPositions,
+  } = useEditor()
+
+  const buffersRef = useRef(buffers)
+  buffersRef.current = buffers
+  const activeBufferRef = useRef(activeBuffer)
+  activeBufferRef.current = activeBuffer
+
+  useEffect(() => {
+    registerWorkspace({
+      async createNotebook(label, signal) {
+        // AI-created notebooks start with no cells; the agent populates via add_cell / apply_notebook_state.
+        const buffer = await addBuffer({
+          label: label ?? "Notebook",
+          notebookViewState: { cells: [] },
+        })
+        if (!buffer?.id) {
+          throw new Error("Failed to create notebook buffer")
+        }
+        await waitForController(buffer.id, 5000, signal)
+        return { bufferId: buffer.id, label: buffer.label }
+      },
+      async duplicateNotebook(bufferId, signal) {
+        const src = buffersRef.current.find((b) => b.id === bufferId)
+        if (!src) {
+          throw new NotebookToolError(
+            "deleted",
+            `Notebook ${bufferId} no longer exists.`,
+          )
+        }
+        if (src.archived) {
+          throw new NotebookToolError(
+            "archived",
+            `Notebook "${src.label}" is archived; ask the user to restore it before duplicating.`,
+          )
+        }
+        if (!src.notebookViewState) {
+          throw new NotebookToolError(
+            "not_a_notebook",
+            `Buffer ${bufferId} is not a notebook.`,
+          )
+        }
+        const created = await duplicateNotebookBuffer(bufferId)
+        if (!created?.id) {
+          throw new NotebookToolError(
+            "activation_failed",
+            "Could not create the duplicate (tab limit reached).",
+          )
+        }
+        await waitForController(created.id, 5000, signal)
+        return { bufferId: created.id, label: created.label }
+      },
+      async deleteNotebook(bufferId) {
+        const target = buffersRef.current.find((b) => b.id === bufferId)
+        if (!target) {
+          throw new NotebookToolError(
+            "deleted",
+            `Notebook ${bufferId} no longer exists.`,
+          )
+        }
+        if (!target.notebookViewState) {
+          throw new NotebookToolError(
+            "not_a_notebook",
+            `Buffer ${bufferId} is not a notebook.`,
+          )
+        }
+        if (target.archived) return
+        const remaining = buffersRef.current.filter(
+          (b) =>
+            (!b.archived || b.isTemporary) &&
+            typeof b.id === "number" &&
+            b.id !== bufferId,
+        )
+        if (remaining.length === 0) {
+          throw new NotebookToolError(
+            "last_tab",
+            "Cannot delete the only open tab. Create another notebook first, then delete this one.",
+          )
+        }
+        await archiveBuffer(bufferId)
+        await updateBuffersPositions(
+          remaining
+            .sort((a, b) => a.position - b.position)
+            .map((b, index) => ({ id: b.id as number, position: index })),
+        )
+      },
+      async activateNotebook(bufferId) {
+        const target = buffersRef.current.find(
+          (b) => b.id === bufferId && !b.archived,
+        )
+        if (!target) return false
+        await setActiveBuffer(target)
+        return true
+      },
+      getBufferMeta(bufferId): NotebookWorkspaceBufferMeta {
+        const b = buffersRef.current.find((x) => x.id === bufferId)
+        if (!b) return { kind: "deleted" }
+        if (b.archived) return { kind: "archived", label: b.label }
+        if (!b.notebookViewState) return null
+        const kind: "active" | "inactive" =
+          activeBufferRef.current?.id === b.id ? "active" : "inactive"
+        return {
+          kind,
+          label: b.label,
+          notebookViewState: b.notebookViewState,
+        }
+      },
+      listNotebookBuffers() {
+        return buffersRef.current
+          .filter((b) => !!b.notebookViewState && typeof b.id === "number")
+          .map((b) => ({
+            bufferId: b.id as number,
+            label: b.label,
+            archived: !!b.archived,
+          }))
+      },
+    })
+    return () => unregisterWorkspace()
+  }, [
+    addBuffer,
+    setActiveBuffer,
+    archiveBuffer,
+    duplicateNotebookBuffer,
+    updateBuffersPositions,
+  ])
+
+  return null
+}
diff --git a/src/scenes/Editor/Notebook/__fixtures__/declare-cases.json b/src/scenes/Editor/Notebook/__fixtures__/declare-cases.json
new file mode 100644
index 000000000..d13d6398c
--- /dev/null
+++ b/src/scenes/Editor/Notebook/__fixtures__/declare-cases.json
@@ -0,0 +1,91 @@
+[
+  "CREATE VIEW foo AS (DECLARE @x := 1, @y := 2 SELECT @x + @y)",
+  "DECLARE OVERRIDABLE @max_spread := 2.0 SELECT ts, symbol, bid, ask FROM quotes WHERE (ask - bid) <= @max_spread",
+  "DECLARE OVERRIDABLE @side := 'BUY' SELECT ts, symbol, price, side FROM trade_log WHERE side = @side",
+  "DECLARE @threshold := 6, @multiplier := 10\nWITH filtered AS (SELECT ts, v FROM view1)\nSELECT ts, v * @multiplier as scaled_v FROM filtered\n",
+  "DECLARE @x := 2\nSELECT * FROM (\n    DECLARE @x := 5, @y := 3\n    SELECT * FROM (\n        DECLARE @x := 8, @z := 1\n        SELECT @x + @y + @z as result FROM long_sequence(1)\n    )\n)\n",
+  "DECLARE @x := 2, @y := 100\nSELECT @x + @y as outer_result, inner_result FROM (\n    DECLARE @x := 5\n    SELECT @x + @y as inner_result FROM long_sequence(1)\n)\n",
+  "DECLARE OVERRIDABLE @min_qty := 50 SELECT ts, symbol, price, qty FROM trades WHERE qty >= @min_qty LATEST ON ts PARTITION BY symbol",
+  "DECLARE OVERRIDABLE @min_value := 15.0 SELECT ts, sensor, avg(value) as avg_val FROM samples WHERE value > @min_value SAMPLE BY 1m",
+  "DECLARE @x := 6, @y := 2\nSELECT * FROM (\n    DECLARE @z := 100\n    SELECT ts, v, @z as marker FROM view1\n) WHERE v > @y\n",
+  "DECLARE OVERRIDABLE @default_val := 0 SELECT ts, category, coalesce(value, @default_val) as value FROM nullable_data",
+  "CREATE TABLE foo AS (DECLARE @x := 1, @y := 2 SELECT @x + @y)",
+  "CREATE VIEW foo AS (DECLARE @x := 1, @y := 2 SELECT @x + @y)",
+  "INSERT INTO foo SELECT * FROM (DECLARE @x := 1, @y := 2 SELECT @x + @y as x)",
+  "DECLARE OVERRIDABLE @x := 5 SELECT @x",
+  "DECLARE overridable @x := 5 SELECT @x",
+  "DECLARE Overridable @x := 5 SELECT @x",
+  "DECLARE OVERRIDABLE @x := 5 SELECT @x",
+  "DECLARE OVERRIDABLE @x := 5, @y := 10 SELECT @x, @y",
+  "DECLARE OVERRIDABLE @x := 5, OVERRIDABLE @y := 10 SELECT @x, @y",
+  "declare @ts := '2025-07-02T13:00:00.000000Z', @int := interval(@ts, @ts)select @int",
+  "DECLARE @foo := foo, @bah := bah SELECT foo.ts, foo.x FROM @foo ASOF JOIN @bah",
+  "DECLARE @x := 2, @y := 5 WITH a AS (SELECT @x + @y) SELECT * FROM a",
+  "DECLARE @x := 1, @y := 5, @z := 2 SELECT CASE WHEN @x = @X THEN @y ELSE @z END",
+  "DECLARE @x := 2::timestamp SELECT @x",
+  "DECLARE @x := 5 SELECT CAST(@x AS timestamp)",
+  "DECLARE @x := symbol SELECT DISTINCT symbol FROM trades",
+  "DECLARE @x := 123.456 SELECT @x",
+  "DECLARE @a := 1, @b := 2 (SELECT @a + @b) EXCEPT (SELECT @a + @b)",
+  "DECLARE @a := 1, @b := 2 (SELECT @a + @b) EXCEPT ALL (SELECT @a + @b)",
+  "EXPLAIN DECLARE @x := 5 SELECT @x",
+  "DECLARE @lo := '2025-01-01', @hi := '2025-01-02', @unit := '1d' SELECT * FROM generate_series(@lo, @hi, @unit)",
+  "DECLARE @x := timestamp, @y := symbol SELECT timestamp, symbol, price FROM trades GROUP BY @x, @y, price",
+  "DECLARE @x := 1, @y := 2 SELECT timestamp, symbol, price FROM trades GROUP BY @x, @y, 3",
+  "DECLARE @x := 5 SELECT @x",
+  "DECLARE @a := 1, @b := 2 (SELECT @a + @b) INTERSECT (SELECT @a + @b)",
+  "DECLARE @a := 1, @b := 2 (SELECT @a + @b) INTERSECT ALL (SELECT @a + @b)",
+  "DECLARE @x := foo.x, @y := bah.y SELECT foo.ts, foo.x FROM foo JOIN bah on @x = @y",
+  "DECLARE @x := $1, @y := $2 SELECT @x, @y",
+  "DECLARE @ts := timestamp SELECT * FROM trades LATEST BY @ts;",
+  "DECLARE @ts := timestamp, @sym := symbol SELECT * FROM trades LATEST ON @ts PARTITION BY @sym;",
+  "DECLARE @lo := 2, @hi := 5 SELECT * FROM trades LIMIT @lo, @hi",
+  "DECLARE @x := 2, @y := 5 WITH a AS (SELECT @x + @y as col1), b AS (SELECT (@x - @y) + col1 as col2 FROM a) SELECT * FROM b",
+  "DECLARE @x := 1, @y := 2 SELECT @x, @y",
+  "DECLARE @x := 1, @y := 2 SELECT @x + @y",
+  "DECLARE @x := 1, @y := 2 SELECT @x * @y + @x / @y",
+  "DECLARE @lo := -5, @hi := -2 SELECT * FROM trades LIMIT @lo, @hi",
+  "DECLARE @lo := 2, @hi := 5 SELECT * FROM trades LIMIT -@lo, -@hi",
+  "DECLARE @x := timestamp, @y := symbol SELECT timestamp, symbol, price FROM trades ORDER BY @x, @y, price",
+  "DECLARE @x := 1, @y := 2 SELECT timestamp, symbol, price FROM trades ORDER BY @x, @y, 3",
+  "DECLARE @unit := 1h SELECT timestamp, symbol, avg(price) FROM trades SAMPLE BY @unit",
+  "DECLARE @unit := 1h SELECT timestamp, symbol, avg(price) FROM trades SAMPLE BY @unit ALIGN TO FIRST OBSERVATION",
+  "DECLARE @unit := 1h, @from := '2008-12-28', @to := '2009-01-05', @fill := null SELECT timestamp, symbol, avg(price) FROM trades SAMPLE BY @unit FROM @from TO @to FILL(@fill)",
+  "DECLARE @offset := '10:00' SELECT timestamp, symbol, avg(price) FROM trades SAMPLE BY 1h ALIGN TO CALENDAR WITH OFFSET @offset",
+  "DECLARE @tz := 'Antarctica/McMurdo' SELECT timestamp, symbol, avg(price) FROM trades SAMPLE BY 1h ALIGN TO CALENDAR TIME ZONE @tz",
+  "DECLARE @x := 2, @y := 5 SELECT * FROM (SELECT @x + @y)",
+  "DECLARE @x := 2, @y := 5 SELECT * FROM (DECLARE @x:= 7 SELECT @x + @y)",
+  "DECLARE @x := 2, @y := 5 SELECT @x - @y as foo, * FROM (DECLARE @x:= 7 SELECT @x + @y)",
+  "DECLARE @table_name := foo, @ts := ts, @x := x, SELECT @ts, @x FROM @table_name",
+  "DECLARE @a := 1, @b := 2 (SELECT @a + @b) UNION (SELECT @a + @b)",
+  "DECLARE @a := 1, @b := 2 (SELECT @a + @b) UNION ALL (SELECT @a + @b)",
+  "DECLARE @x := 2, @y := 5 SELECT @x + @y FROM long_sequence(1) WHERE @x < @y",
+  "DECLARE @x := 2::timestamp, @y := 5::timestamp SELECT @x + @y FROM long_sequence(1) WHERE @x < @y",
+  "DECLARE @max_price := max(price) SELECT timestamp, symbol, @max_price FROM trades",
+  "DECLARE\n    @today := today(),\n    @start := interval_start(@today),\n    @end := interval_end(@today)\n    SELECT @today = interval(@start, @end)",
+  "DECLARE\n    @ts := timestamp,\n    @bid_price := bid_px_00,\n    @bid_size := bid_sz_00,\n    @avg_time_range := '5',\n    @updates_period := '100',\n    @volume_2sec := '2'\nSELECT\n    @ts,\n    @bid_price,\n    AVG(@bid_price) OVER (\n        ORDER BY @ts\n        RANGE BETWEEN @avg_time_range MINUTE PRECEDING AND CURRENT ROW\n    ) AS avg_5min,\n    COUNT(*) OVER (\n        ORDER BY @ts\n        RANGE BETWEEN @updates_period MILLISECOND PRECEDING AND CURRENT ROW\n    ) AS updates_100ms,\n    SUM(@bid_size) OVER (\n        ORDER BY @ts\n        RANGE BETWEEN @volume_2sec SECOND PRECEDING AND CURRENT ROW\n    ) AS volume_2sec\nFROM AAPL_orderbook\nWHERE @bid_price > 0\nLIMIT 10;",
+  "DECLARE\n    @partition_col := bid_px_00,\n    @order_col := timestamp\nSELECT\n    @order_col,\n    @partition_col,\n    ROW_NUMBER() OVER (\n        PARTITION BY @partition_col\n        ORDER BY @order_col\n    ) AS row_num\nFROM AAPL_orderbook\nLIMIT 5;",
+  "DECLARE @x := (SELECT 1 as y) SELECT * FROM @x",
+  "DECLARE @x := (DECLARE @y := 4 SELECT @y as y) SELECT * FROM @x",
+  "DECLARE @x := 5, @y := (DECLARE @y := 4 SELECT @y + @x as z) SELECT * FROM @y",
+  "DECLARE @y := 2, @y2 := (@y * @y) SELECT @y, @y2",
+  "declare @ts := (timestamp > '2024-01-01') select timestamp, count() from trades where @ts;",
+  "declare @lo := '2024-01-01' select timestamp, count() from trades where timestamp > @lo;",
+  "declare @ts := (timestamp > '2024-01-01' and timestamp < '2024-08-23') select timestamp, count() from trades where @ts;",
+  "declare @lo := '2024-01-01', @hi := '2024-08-23' select timestamp, count() from trades where timestamp > @lo and timestamp < @hi;",
+  "declare @ts := (timestamp < '2024-08-23')  select timestamp, count() from trades where @ts;",
+  "declare @hi := '2024-08-23' select timestamp, count() from trades where timestamp < @hi;",
+  "declare @ts := (timestamp > '2024-01-01') select timestamp, count() from trades where @ts;",
+  "declare @lo := '2024-01-01' select timestamp, count() from trades where timestamp > @lo;",
+  "declare @ts := (timestamp >= '2024-01-01' and timestamp <= '2024-08-23') select timestamp, count() from trades where @ts;",
+  "declare @lo := '2024-01-01', @hi := '2024-08-23' select timestamp, count() from trades where timestamp >= @lo and timestamp <= @hi;",
+  "declare @ts := (timestamp <= '2024-08-23') select timestamp, count() from trades where @ts;",
+  "declare @hi := '2024-08-23' select timestamp, count() from trades where timestamp <= @hi;",
+  "declare @ts := (timestamp >= '2024-01-01') select timestamp, count() from trades where @ts;",
+  "declare @lo := '2024-01-01' select timestamp, count() from trades where timestamp >= @lo;",
+  "declare @ts := (timestamp between '2024-01-01' and '2024-08-23') select timestamp, count() from trades where @ts;",
+  "declare @lo := '2024-01-01', @hi := '2024-08-23' select timestamp, count() from trades where timestamp between @lo and @hi;",
+  "declare @id := id, @val := 4 select * from x where @id < @val",
+  "declare @expr := (id < 4) select * from x where @expr",
+  "declare @x := '2023-01-01T09:04:00.000000Z' select t.sym, t.price, t.ts, sum(p.price) as window_price from trades t window join prices p on (t.sym = p.sym)   range between 1 minute preceding and 1 minute following "
+]
diff --git a/src/scenes/Editor/Notebook/cellReveal.test.ts b/src/scenes/Editor/Notebook/cellReveal.test.ts
new file mode 100644
index 000000000..685549cd7
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cellReveal.test.ts
@@ -0,0 +1,67 @@
+import { describe, it, expect, beforeEach } from "vitest"
+import {
+  requestCellReveal,
+  getPendingReveal,
+  consumeReveal,
+  clearPendingReveal,
+} from "./cellReveal"
+
+const input = (overrides: Record<string, unknown> = {}) => ({
+  bufferId: 1,
+  cellId: "cell-1",
+  range: { startLineNumber: 1, startColumn: 1, endLineNumber: 1, endColumn: 5 },
+  notebookField: "cell" as const,
+  cellType: "sql" as const,
+  ...overrides,
+})
+
+describe("cellReveal store", () => {
+  beforeEach(() => clearPendingReveal())
+
+  it("returns null when nothing is pending", () => {
+    // Given no request
+    // Then there is nothing pending
+    expect(getPendingReveal()).toBeNull()
+  })
+
+  it("returns the parked request regardless of how long it waits", () => {
+    // Given a reveal request (no wall-clock expiry — a slow cold mount must still drain it)
+    requestCellReveal(input({ cellId: "c-live" }))
+
+    // Then it stays pending until consumed or superseded
+    expect(getPendingReveal()?.cellId).toBe("c-live")
+  })
+
+  it("supersedes an older request and issues a strictly greater token", () => {
+    // Given two successive requests
+    const first = requestCellReveal(input({ cellId: "old" }))
+    const second = requestCellReveal(input({ cellId: "new" }))
+
+    // Then the latest wins with a higher token
+    expect(second).toBeGreaterThan(first)
+    expect(getPendingReveal()?.cellId).toBe("new")
+  })
+
+  it("ignores consumeReveal for a superseded token", () => {
+    // Given a request that was superseded by a newer one
+    const stale = requestCellReveal(input({ cellId: "old" }))
+    requestCellReveal(input({ cellId: "new" }))
+
+    // When the stale token tries to consume
+    consumeReveal(stale)
+
+    // Then the newer request is left intact
+    expect(getPendingReveal()?.cellId).toBe("new")
+  })
+
+  it("clears the pending request when the matching token consumes it", () => {
+    // Given the current request
+    const token = requestCellReveal(input())
+
+    // When consumed with its own token
+    consumeReveal(token)
+
+    // Then nothing is pending
+    expect(getPendingReveal()).toBeNull()
+  })
+})
diff --git a/src/scenes/Editor/Notebook/cellReveal.ts b/src/scenes/Editor/Notebook/cellReveal.ts
new file mode 100644
index 000000000..f61e09947
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cellReveal.ts
@@ -0,0 +1,36 @@
+import type { IRange } from "monaco-editor"
+
+export type CellRevealRequest = {
+  bufferId: number
+  cellId: string
+  range: IRange
+  notebookField: "cell" | "chartName"
+  cellType: "sql" | "markdown"
+  token: number
+}
+
+type CellRevealInput = Omit<CellRevealRequest, "token">
+
+// Parks a search-result reveal until the (async-mounting) notebook and cell editor drain
+// it. Staleness is by token supersession — a newer request invalidates an older in-flight
+// one — not wall-clock, so a slow cold mount still reveals.
+let pending: CellRevealRequest | null = null
+let tokenSeq = 0
+
+export const requestCellReveal = (input: CellRevealInput): number => {
+  const token = ++tokenSeq
+  pending = { ...input, token }
+  return token
+}
+
+export const getPendingReveal = (): CellRevealRequest | null => pending
+
+export const consumeReveal = (token: number): void => {
+  if (pending && pending.token === token) {
+    pending = null
+  }
+}
+
+export const clearPendingReveal = (): void => {
+  pending = null
+}
diff --git a/src/scenes/Editor/Notebook/cells/AddCellButton.tsx b/src/scenes/Editor/Notebook/cells/AddCellButton.tsx
new file mode 100644
index 000000000..12bcbb7e9
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cells/AddCellButton.tsx
@@ -0,0 +1,197 @@
+import React from "react"
+import styled from "styled-components"
+import { Plus } from "@styled-icons/boxicons-regular"
+import { MarkdownLogoIcon } from "@phosphor-icons/react"
+import { color } from "../../../../utils"
+import { Tooltip } from "../../../../components"
+import type { CellType } from "../../../../store/notebook"
+import { MAX_NOTEBOOK_CELLS } from "../../../../store/notebook"
+import { useNotebookActions, useNotebookState } from "../NotebookProvider"
+import { useEditor } from "../../../../providers/EditorProvider"
+import { emitUserAction } from "../../../../utils/notebookAIBridge"
+
+const BottomButton = styled.div<{ $alignCenter?: boolean }>`
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  gap: 0.8rem;
+  height: ${({ $alignCenter }) => ($alignCenter ? "100%" : "auto")};
+  padding: 0.8rem 0;
+  margin-top: 1rem;
+`
+
+const AddButton = styled.button`
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.4rem 1rem;
+  border: none;
+  border-radius: 0.3rem;
+  background: transparent;
+  color: ${color("comment")};
+  cursor: pointer;
+  font-family: ${({ theme }) => theme.font};
+
+  &:hover {
+    color: ${color("foreground")};
+    background: ${color("selection")};
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.4;
+
+    &:hover {
+      color: ${color("comment")};
+      background: transparent;
+    }
+  }
+
+  svg {
+    width: 1.4rem;
+    height: 1.4rem;
+  }
+`
+
+const BetweenWrapper = styled.div`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 1.2rem;
+  position: relative;
+  opacity: 0;
+  transition: opacity 0.1s;
+
+  &:hover {
+    opacity: 1;
+  }
+`
+
+const BetweenLine = styled.div`
+  position: absolute;
+  top: 50%;
+  left: 0;
+  right: 0;
+  height: 1px;
+  background: ${color("selection")};
+`
+
+// Groups the two add buttons and masks the divider line behind them (matching
+// the notebook content background).
+const BetweenButtons = styled.div`
+  position: relative;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  padding: 0 0.8rem;
+  background: ${color("midnight")};
+`
+
+// User-origin only: tool-driven add_cell goes through NotebookController directly and doesn't emit here.
+const useUserAddCell = () => {
+  const { addCell } = useNotebookActions()
+  const { cells } = useNotebookState()
+  const { activeBuffer } = useEditor()
+  const atLimit = cells.length >= MAX_NOTEBOOK_CELLS
+  const add = (afterCellId?: string, type?: CellType) => {
+    const cellId = addCell(afterCellId, undefined, type)
+    if (typeof activeBuffer.id === "number" && cellId) {
+      emitUserAction({
+        kind: "user_added_cell",
+        bufferId: activeBuffer.id,
+        cellId,
+      })
+    }
+  }
+  return { add, atLimit }
+}
+
+const CELL_LIMIT_TITLE = `Notebook limit of ${MAX_NOTEBOOK_CELLS} cells reached`
+
+type AddActionProps = {
+  icon: React.ReactNode
+  label: string
+  atLimit: boolean
+  onClick: () => void
+}
+
+const AddAction: React.FC<AddActionProps> = ({
+  icon,
+  label,
+  atLimit,
+  onClick,
+}) => {
+  const button = (
+    <AddButton onClick={onClick} disabled={atLimit}>
+      {icon}
+      {label}
+    </AddButton>
+  )
+  if (!atLimit) return button
+  // The span lets the tooltip fire on a disabled button, which gets no pointer events.
+  return (
+    <Tooltip content={CELL_LIMIT_TITLE}>
+      <span style={{ display: "inline-flex" }}>{button}</span>
+    </Tooltip>
+  )
+}
+
+type AddCellBottomProps = {
+  alignCenter?: boolean
+  afterCellId?: string
+}
+
+export const AddCellBottom: React.FC<AddCellBottomProps> = ({
+  afterCellId,
+  alignCenter = false,
+}) => {
+  const { add, atLimit } = useUserAddCell()
+
+  return (
+    <BottomButton $alignCenter={alignCenter}>
+      <AddAction
+        icon={<Plus />}
+        label="Add Cell"
+        atLimit={atLimit}
+        onClick={() => add(afterCellId)}
+      />
+      <AddAction
+        icon={<MarkdownLogoIcon />}
+        label="Add Markdown"
+        atLimit={atLimit}
+        onClick={() => add(afterCellId, "markdown")}
+      />
+    </BottomButton>
+  )
+}
+
+type AddCellBetweenProps = {
+  afterCellId: string
+}
+
+export const AddCellBetween: React.FC<AddCellBetweenProps> = ({
+  afterCellId,
+}) => {
+  const { add, atLimit } = useUserAddCell()
+
+  return (
+    <BetweenWrapper>
+      <BetweenLine />
+      <BetweenButtons>
+        <AddAction
+          icon={<Plus />}
+          label="Add Cell"
+          atLimit={atLimit}
+          onClick={() => add(afterCellId)}
+        />
+        <AddAction
+          icon={<MarkdownLogoIcon />}
+          label="Add Markdown"
+          atLimit={atLimit}
+          onClick={() => add(afterCellId, "markdown")}
+        />
+      </BetweenButtons>
+    </BetweenWrapper>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/cells/Cell.tsx b/src/scenes/Editor/Notebook/cells/Cell.tsx
new file mode 100644
index 000000000..597949f70
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cells/Cell.tsx
@@ -0,0 +1,907 @@
+import React, { useCallback, useEffect, useRef, useState } from "react"
+import styled, { css, useTheme } from "styled-components"
+import { color } from "../../../../utils"
+import { Editor } from "@monaco-editor/react"
+import {
+  QuestDBLanguageName,
+  getQueryFromCursor,
+  normalizeQueryText,
+  stripSQLComments,
+} from "../../Monaco/utils"
+import { PlayIcon, CancelIcon, CircleNotchSpinner } from "../../Monaco/icons"
+import { ChartLineUpIcon } from "@phosphor-icons/react"
+import { QuestContext } from "../../../../providers/QuestProvider"
+import { useNotebookActions } from "../NotebookProvider"
+import { CellDragHeader } from "./CellDragHeader"
+import { useCellWrapperInteractions } from "./useCellWrapperInteractions"
+import { InlineResultTable } from "../result-table"
+import { ResizeHandle } from "../resize"
+import { CellWrapper } from "./CellWrapper"
+import { DrawCanvas } from "../DrawCanvas"
+import type { ChartConfig } from "../CellChart/chartTypes"
+import type { NotebookCell } from "../../../../store/notebook"
+import { exceedsCellLineLimit } from "../../../../store/notebook"
+import { useCellResize } from "./useCellResize"
+import { useCellSelectionDecoration } from "./useCellSelectionDecoration"
+import { useMonacoCellEditor } from "./useMonacoCellEditor"
+import { useCellReveal } from "./useCellReveal"
+import { useEditor } from "../../../../providers/EditorProvider"
+import {
+  emitUserAction,
+  signalUserEdit,
+} from "../../../../utils/notebookAIBridge"
+import { createRunStatus, type RanStatus } from "../../../../utils/ai/runStatus"
+import { requireAllDQL } from "../../../../utils/tools/permissions"
+import { toast } from "../../../../components/Toast"
+import { eventBus } from "../../../../modules/EventBus"
+import { EventType } from "../../../../modules/EventBus/types"
+import {
+  DEFAULT_TOP_HEIGHT,
+  defaultBottomHeightFor,
+  isDoubleView,
+  isExpectingResult,
+  MIN_BOTTOM_HEIGHT_PX,
+  partitionCellHeights,
+  RESERVED_RESULT_BOTTOM_HEIGHT,
+  scaleCellHeights,
+} from "../notebookUtils"
+import { useValidateWithGlobals } from "../globals/useValidateWithGlobals"
+
+// Minimum content area heights. `MIN_EDITOR_HEIGHT` matches Monaco's reported
+// content height for an empty editor (one line + padding); the previous
+// `MAX_EDITOR_HEIGHT` cap is gone — the editor now auto-grows freely with
+// pasted content (user-confirmed: unbounded).
+const MIN_EDITOR_HEIGHT = 72
+
+const RunButton = styled.button`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  border-radius: 0.3rem;
+  background: transparent;
+  cursor: pointer;
+  padding: 0;
+
+  &:hover {
+    filter: brightness(1.3);
+  }
+
+  &:disabled {
+    opacity: 0.3;
+    cursor: default;
+    filter: none;
+  }
+
+  svg {
+    width: 2.4rem;
+    height: 2.4rem;
+  }
+`
+
+const DrawButton = styled.button<{ $active: boolean }>`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  border-radius: 0.3rem;
+  background: transparent;
+  color: ${({ $active, theme }) =>
+    $active ? theme.color.cyan : theme.color.cyan};
+  cursor: pointer;
+  padding: 0;
+
+  &:hover {
+    filter: brightness(1.3);
+  }
+
+  &:disabled {
+    opacity: 0.3;
+    cursor: default;
+    filter: none;
+  }
+`
+
+const EditorContainer = styled.div<{ $spotlight: boolean }>`
+  overflow: hidden;
+  background: ${color("editorBackground")};
+
+  .cursorQueryDecoration {
+    width: 0.2rem !important;
+    background: ${color("green")};
+    margin-left: 0.5rem;
+  }
+
+  .notebookSearchHighlight {
+    background-color: rgba(255, 184, 108, 0.5);
+    border-radius: 2px;
+  }
+
+  ${({ $spotlight }) =>
+    $spotlight
+      ? css`
+          min-height: 0;
+        `
+      : css`
+          min-height: ${MIN_EDITOR_HEIGHT}px;
+          flex-shrink: 0;
+        `}
+`
+
+const BottomSlot = styled.div<{ $spotlight: boolean }>`
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  overflow: hidden;
+  ${({ $spotlight }) =>
+    $spotlight
+      ? null
+      : css`
+          flex-shrink: 0;
+        `}
+`
+
+// Wraps the (overflow-clipped) cell card in list mode so the bottom-edge resize
+// handle can straddle the cell border with its chip showing outside the card.
+const CellShell = styled.div`
+  position: relative;
+`
+
+const HydrationLoader = styled.div`
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 0;
+  color: ${({ theme }) => theme.color.gray2};
+`
+
+type Props = {
+  cell: NotebookCell
+  layoutMode?: "list" | "grid"
+  isFocused: boolean
+  isMaximized: boolean
+  isRunning: boolean
+  isHydrating: boolean
+}
+
+const CellInner: React.FC<Props> = ({
+  cell,
+  layoutMode = "list",
+  isFocused,
+  isMaximized,
+  isRunning,
+  isHydrating,
+}) => {
+  const {
+    runCell,
+    reRunResultAt,
+    cancelCell,
+    cancelQuery,
+    setActiveResultIndex,
+    setCellMode,
+    setCellChartConfig,
+    setCellAutoRefresh,
+    setCellChartMaximized,
+    updateCell,
+    setFocusedCell,
+    getCellsSnapshot,
+  } = useNotebookActions()
+  const theme = useTheme()
+  const { quest } = React.useContext(QuestContext)
+  const { activeBuffer } = useEditor()
+  const bufferIdForEvents =
+    typeof activeBuffer.id === "number" ? activeBuffer.id : undefined
+  const isDrawMode = cell.mode === "draw"
+  const isChartMaximized = isDrawMode && !!cell.isChartMaximized
+
+  const { wrapperRef, wrapperHandlers } = useCellWrapperInteractions({
+    cellId: cell.id,
+    layoutMode,
+    isMaximized,
+    isFocused,
+  })
+  const editorContainerRef = useRef<HTMLDivElement | null>(null)
+  const resultRef = useRef<HTMLDivElement | null>(null)
+
+  const contentHeightGetterRef = useRef<() => number | null>(() => null)
+
+  const validateWithGlobals = useValidateWithGlobals()
+
+  const topResize = useCellResize(
+    MIN_EDITOR_HEIGHT,
+    useCallback(
+      (height: number) =>
+        updateCell(cell.id, { topHeight: height, topResized: true }),
+      [cell.id, updateCell],
+    ),
+    // Write Monaco's CURRENT content height directly on reset, rather
+    // than setting `topHeight: undefined` and waiting for the next
+    // `onContentHeightChange` to fill it in. The wait creates a
+    // one-frame flicker where `topHeight` falls back to
+    // DEFAULT_TOP_HEIGHT (72 px) and the bottom slot jumps up.
+    useCallback(() => {
+      const contentH = contentHeightGetterRef.current()
+      const next =
+        contentH != null
+          ? Math.max(MIN_EDITOR_HEIGHT, contentH)
+          : MIN_EDITOR_HEIGHT
+      updateCell(cell.id, { topHeight: next, topResized: false })
+    }, [cell.id, updateCell]),
+  )
+  const bottomResize = useCellResize(
+    MIN_BOTTOM_HEIGHT_PX,
+    useCallback(
+      (height: number) => updateCell(cell.id, { bottomHeight: height }),
+      [cell.id, updateCell],
+    ),
+    useCallback(
+      () => updateCell(cell.id, { bottomHeight: undefined }),
+      [cell.id, updateCell],
+    ),
+  )
+
+  const handleChartConfigChange = useCallback(
+    (config: ChartConfig) => {
+      signalUserEdit()
+      setCellChartConfig(cell.id, config)
+    },
+    [cell.id, setCellChartConfig],
+  )
+  const handleAutoRefreshChange = useCallback(
+    (value: boolean) => {
+      signalUserEdit()
+      setCellAutoRefresh(cell.id, value)
+    },
+    [cell.id, setCellAutoRefresh],
+  )
+  const handleChartMaximizedChange = useCallback(
+    (value: boolean) => {
+      signalUserEdit()
+      setCellChartMaximized(cell.id, value)
+    },
+    [cell.id, setCellChartMaximized],
+  )
+
+  const validatingDrawRef = useRef(false)
+
+  const handleDrawClick = useCallback(async () => {
+    if (isDrawMode) {
+      setCellMode(cell.id, "run")
+      if (bufferIdForEvents !== undefined) {
+        emitUserAction({
+          kind: "user_changed_cell_mode",
+          bufferId: bufferIdForEvents,
+          cellId: cell.id,
+          mode: "run",
+        })
+      }
+      return
+    }
+    if (validatingDrawRef.current) return
+    validatingDrawRef.current = true
+    try {
+      const decision = await requireAllDQL(cell.value, (s) =>
+        validateWithGlobals(s),
+      )
+      if (!decision.granted) {
+        toast.error(decision.reason)
+        return
+      }
+      setCellMode(cell.id, "draw")
+      setCellChartMaximized(cell.id, false)
+      if (bufferIdForEvents !== undefined) {
+        emitUserAction({
+          kind: "user_changed_cell_mode",
+          bufferId: bufferIdForEvents,
+          cellId: cell.id,
+          mode: "draw",
+        })
+      }
+    } finally {
+      validatingDrawRef.current = false
+    }
+  }, [
+    cell.id,
+    cell.value,
+    isDrawMode,
+    setCellMode,
+    setCellChartMaximized,
+    bufferIdForEvents,
+    validateWithGlobals,
+  ])
+
+  const exitDrawIfNeeded = useCallback(() => {
+    if (isDrawMode) {
+      signalUserEdit()
+      setCellMode(cell.id, "run")
+    }
+  }, [cell.id, isDrawMode, setCellMode])
+
+  const liveTopHeight = topResize.liveHeight
+  const liveBottomHeight = bottomResize.liveHeight
+
+  const topHeight = liveTopHeight ?? cell.topHeight ?? DEFAULT_TOP_HEIGHT
+  // A run cell that had a persisted result (lastRunStatus is set, known
+  // synchronously from the view state) reserves its result area from the FIRST
+  // render while the snapshot hydrates
+  // computeCellGridH applies the same reservation to the grid item's height.
+  const expectingResult = isExpectingResult(cell, isHydrating)
+  const bottomHeight =
+    liveBottomHeight ??
+    cell.bottomHeight ??
+    (expectingResult
+      ? RESERVED_RESULT_BOTTOM_HEIGHT
+      : defaultBottomHeightFor(cell))
+  const doubleView = isDoubleView(cell) || expectingResult
+
+  const [spotlightLiveRatio, setSpotlightLiveRatio] = useState<number | null>(
+    null,
+  )
+  const spotlightEditorRatio =
+    spotlightLiveRatio ??
+    cell.spotlightEditorRatio ??
+    topHeight / (topHeight + bottomHeight)
+
+  // Editor height pipeline (hard-cap model):
+  //   - When NOT user-resized: cell.topHeight tracks Monaco's content height
+  //     exactly. Editor auto-grows / auto-shrinks with content.
+  //   - When user-resized (topResized === true): cell.topHeight is FIXED at
+  //     the user's drag value. Monaco's content-size events are ignored;
+  //     content overflow is handled by Monaco's internal scrollbar.
+  // Per user spec: configured top-height should not expand to fit content —
+  // the user's resize is a hard cap, scrolling stays inside Monaco.
+  const handleContentHeightChange = useCallback(
+    (px: number) => {
+      if (isMaximized) return
+      if (cell.topResized) return
+      const next = Math.max(MIN_EDITOR_HEIGHT, px)
+      if (next === cell.topHeight) return
+      updateCell(cell.id, { topHeight: next })
+    },
+    [isMaximized, cell.id, cell.topResized, cell.topHeight, updateCell],
+  )
+
+  const { editorRef, monacoRef, handleEditorMount } = useMonacoCellEditor({
+    cellId: cell.id,
+    editorViewState: cell.editorViewState,
+    quest,
+    onFocus: useCallback(
+      () => setFocusedCell(cell.id),
+      [cell.id, setFocusedCell],
+    ),
+    onSaveViewState: useCallback(
+      (state) => updateCell(cell.id, { editorViewState: state }),
+      [cell.id, updateCell],
+    ),
+    onRunAtCursor: () => void handleRunAtCursor(),
+    onRunAll: () => void handleRunAll(),
+    onContentHeightChange: handleContentHeightChange,
+    validate: validateWithGlobals,
+  })
+
+  const { applyHighlight, clearHighlight } = useCellSelectionDecoration(
+    editorRef,
+    monacoRef,
+  )
+
+  const { applyReveal } = useCellReveal(
+    editorRef,
+    monacoRef,
+    cell.id,
+    activeBuffer.id,
+  )
+
+  const handleRevealMount = useCallback<typeof handleEditorMount>(
+    (ed, monaco) => {
+      handleEditorMount(ed, monaco)
+      applyReveal()
+    },
+    [handleEditorMount, applyReveal],
+  )
+
+  // Install the content-height getter that `topResize.resetHeight`
+  // reads (declared above, before `editorRef` is in scope). The
+  // closure over the stable `editorRef` means we don't need to
+  // re-install when `editorRef.current` later transitions from null
+  // to the mounted instance.
+  useEffect(() => {
+    contentHeightGetterRef.current = () =>
+      editorRef.current?.getContentHeight() ?? null
+  }, [editorRef])
+
+  const tryRunSelection = useCallback(async (): Promise<boolean> => {
+    const ed = editorRef.current
+    if (!ed) return false
+    const selection = ed.getSelection()
+    const model = ed.getModel()
+    if (!selection || !model || selection.isEmpty()) return false
+
+    const selectedText = model.getValueInRange(selection)
+    const normalized = normalizeQueryText(selectedText)
+    if (!normalized) return false
+
+    clearHighlight()
+    const success = await runCell(cell.id, normalized)
+    applyHighlight(success)
+    return true
+  }, [cell.id, runCell, editorRef, applyHighlight, clearHighlight])
+
+  const emitRanEvent = useCallback(
+    (status: RanStatus) => {
+      if (bufferIdForEvents === undefined) return
+      emitUserAction({
+        kind: "user_ran_cell",
+        bufferId: bufferIdForEvents,
+        cellId: cell.id,
+        status,
+      })
+    },
+    [bufferIdForEvents, cell.id],
+  )
+
+  const handleRunAll = useCallback(async () => {
+    if (await tryRunSelection()) return
+    if (!editorRef.current) return
+
+    clearHighlight()
+
+    const priorResult =
+      getCellsSnapshot().find((c) => c.id === cell.id)?.result ?? null
+    const ok = await runCell(cell.id)
+    const freshResult =
+      getCellsSnapshot().find((c) => c.id === cell.id)?.result ?? null
+    emitRanEvent(createRunStatus(priorResult, freshResult, ok))
+  }, [
+    cell.id,
+    runCell,
+    tryRunSelection,
+    editorRef,
+    clearHighlight,
+    emitRanEvent,
+    getCellsSnapshot,
+  ])
+
+  const handleRunAtCursor = useCallback(async () => {
+    if (await tryRunSelection()) return
+    const ed = editorRef.current
+    if (!ed) return
+
+    const queryAtCursor = getQueryFromCursor(ed)
+    if (!queryAtCursor) return
+
+    clearHighlight()
+    void runCell(cell.id, normalizeQueryText(queryAtCursor.query))
+  }, [cell.id, runCell, tryRunSelection, editorRef, clearHighlight])
+
+  const isExternalSyncRef = useRef(false)
+
+  // 500 ms-debounced — one event per cell per typing burst keeps the digest tiny.
+  const updateEmitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const scheduleUpdateEvent = useCallback(() => {
+    if (bufferIdForEvents === undefined) return
+    if (updateEmitTimerRef.current !== null) {
+      clearTimeout(updateEmitTimerRef.current)
+    }
+    updateEmitTimerRef.current = setTimeout(() => {
+      updateEmitTimerRef.current = null
+      emitUserAction({
+        kind: "user_updated_cell",
+        bufferId: bufferIdForEvents,
+        cellId: cell.id,
+      })
+    }, 500)
+  }, [bufferIdForEvents, cell.id])
+  useEffect(() => {
+    return () => {
+      if (updateEmitTimerRef.current !== null) {
+        clearTimeout(updateEmitTimerRef.current)
+      }
+    }
+  }, [])
+
+  const handleEditorChange = useCallback(
+    (value: string | undefined) => {
+      if (isExternalSyncRef.current) return
+      if (value === undefined) return
+      if (exceedsCellLineLimit(value)) {
+        // Reject the edit (e.g. an oversized paste) by undoing it, mirroring
+        // the SQL editor's hard line cap.
+        editorRef.current?.trigger("line-limit", "undo", null)
+        toast.error("Maximum line limit reached")
+        return
+      }
+      const viewState = editorRef.current?.saveViewState() ?? undefined
+      updateCell(cell.id, { value, editorViewState: viewState })
+      signalUserEdit()
+      scheduleUpdateEvent()
+    },
+    [cell.id, updateCell, editorRef, scheduleUpdateEvent],
+  )
+
+  // <Editor defaultValue> only seeds on mount — push external edits (AI
+  // tools, duplicate clone, remote load) through executeEdits so undo
+  // history survives.
+  useEffect(() => {
+    const ed = editorRef.current
+    if (!ed) return
+    if (ed.getValue() === cell.value) return
+    const model = ed.getModel()
+    if (!model) return
+    isExternalSyncRef.current = true
+    try {
+      ed.executeEdits("external-sync", [
+        {
+          range: model.getFullModelRange(),
+          text: cell.value,
+          forceMoveMarkers: true,
+        },
+      ])
+    } finally {
+      isExternalSyncRef.current = false
+    }
+  }, [cell.value, editorRef])
+
+  useEffect(() => {
+    editorRef.current?.updateOptions({
+      scrollbar: { handleMouseWheel: isFocused },
+    })
+  }, [isFocused, editorRef])
+
+  const middleSum = useCallback(() => {
+    if (!isMaximized) return topHeight + bottomHeight
+    const editorH =
+      editorContainerRef.current?.getBoundingClientRect().height ?? 0
+    const bottomH = resultRef.current?.getBoundingClientRect().height ?? 0
+    return editorH + bottomH
+  }, [isMaximized, topHeight, bottomHeight])
+
+  const middleResizeLive = useCallback(
+    (height: number) => {
+      const sum = middleSum()
+      const { top, bottom } = partitionCellHeights(
+        sum,
+        height,
+        MIN_EDITOR_HEIGHT,
+        MIN_BOTTOM_HEIGHT_PX,
+      )
+      if (isMaximized) {
+        setSpotlightLiveRatio(top / (top + bottom))
+        return
+      }
+      topResize.resizeLive(top)
+      bottomResize.resizeLive(bottom)
+    },
+    [isMaximized, middleSum, topResize, bottomResize],
+  )
+
+  const middleResizeEnd = useCallback(
+    (height: number) => {
+      const sum = middleSum()
+      const { top, bottom } = partitionCellHeights(
+        sum,
+        height,
+        MIN_EDITOR_HEIGHT,
+        MIN_BOTTOM_HEIGHT_PX,
+      )
+      if (isMaximized) {
+        setSpotlightLiveRatio(null)
+        updateCell(cell.id, { spotlightEditorRatio: top / (top + bottom) })
+        return
+      }
+      topResize.resizeEnd(top)
+      bottomResize.resizeEnd(bottom)
+    },
+    [isMaximized, middleSum, topResize, bottomResize, cell.id, updateCell],
+  )
+
+  const resetToDefaults = useCallback(() => {
+    if (isMaximized) {
+      setSpotlightLiveRatio(null)
+      updateCell(cell.id, { spotlightEditorRatio: undefined })
+      return
+    }
+    bottomResize.resetHeight()
+    topResize.resetHeight()
+  }, [isMaximized, bottomResize, topResize, cell.id, updateCell])
+
+  const bottomEdgeResizeLive = useCallback(
+    (newResultHeight: number) => {
+      const { top, bottom } = scaleCellHeights(
+        topHeight,
+        bottomHeight,
+        topHeight + newResultHeight,
+        MIN_EDITOR_HEIGHT,
+        MIN_BOTTOM_HEIGHT_PX,
+      )
+      topResize.resizeLive(top)
+      bottomResize.resizeLive(bottom)
+    },
+    [topHeight, bottomHeight, topResize, bottomResize],
+  )
+
+  const bottomEdgeResizeEnd = useCallback(
+    (newResultHeight: number) => {
+      const { top, bottom } = scaleCellHeights(
+        topHeight,
+        bottomHeight,
+        topHeight + newResultHeight,
+        MIN_EDITOR_HEIGHT,
+        MIN_BOTTOM_HEIGHT_PX,
+      )
+      topResize.resizeEnd(top)
+      bottomResize.resizeEnd(bottom)
+    },
+    [topHeight, bottomHeight, topResize, bottomResize],
+  )
+
+  // When a chart is maximized the BottomSlot fills the whole cell, so its
+  // measured height IS the cell total — scale top/bottom to that new total
+  // (preserving the split so it's intact when the chart is restored).
+  const maximizedChartResizeLive = useCallback(
+    (newTotalHeight: number) => {
+      const { top, bottom } = scaleCellHeights(
+        topHeight,
+        bottomHeight,
+        newTotalHeight,
+        MIN_EDITOR_HEIGHT,
+        MIN_BOTTOM_HEIGHT_PX,
+      )
+      topResize.resizeLive(top)
+      bottomResize.resizeLive(bottom)
+    },
+    [topHeight, bottomHeight, topResize, bottomResize],
+  )
+
+  const maximizedChartResizeEnd = useCallback(
+    (newTotalHeight: number) => {
+      const { top, bottom } = scaleCellHeights(
+        topHeight,
+        bottomHeight,
+        newTotalHeight,
+        MIN_EDITOR_HEIGHT,
+        MIN_BOTTOM_HEIGHT_PX,
+      )
+      topResize.resizeEnd(top)
+      bottomResize.resizeEnd(bottom)
+    },
+    [topHeight, bottomHeight, topResize, bottomResize],
+  )
+
+  useEffect(() => {
+    const handler = (payload?: { cellId?: string }) => {
+      if (payload?.cellId !== cell.id) return
+      resetToDefaults()
+    }
+    eventBus.subscribe(EventType.NOTEBOOK_CELL_RESET_SIZE, handler)
+    return () =>
+      eventBus.unsubscribe(EventType.NOTEBOOK_CELL_RESET_SIZE, handler)
+  }, [cell.id, resetToDefaults])
+
+  const cellEl = (
+    <CellWrapper
+      ref={wrapperRef}
+      data-cell-id={cell.id}
+      tabIndex={-1}
+      $focused={isFocused}
+      $maximized={isMaximized}
+      $gridMode={layoutMode === "grid"}
+      {...wrapperHandlers}
+    >
+      {!isChartMaximized && (
+        <CellDragHeader
+          cellId={cell.id}
+          layoutMode={layoutMode}
+          left={
+            <>
+              {isRunning ? (
+                <RunButton
+                  onClick={(e) => {
+                    e.stopPropagation()
+                    cancelCell(cell.id)
+                  }}
+                  title="Cancel"
+                  aria-label="Cancel"
+                >
+                  <CancelIcon />
+                </RunButton>
+              ) : (
+                <RunButton
+                  disabled={!stripSQLComments(cell.value).trim()}
+                  onClick={(e) => {
+                    e.stopPropagation()
+                    exitDrawIfNeeded()
+                    void handleRunAll()
+                  }}
+                  title="Run (Ctrl+Shift+Enter)"
+                  aria-label="Run"
+                >
+                  <PlayIcon />
+                </RunButton>
+              )}
+              <DrawButton
+                type="button"
+                $active={isDrawMode}
+                disabled={!stripSQLComments(cell.value).trim()}
+                onClick={(e) => {
+                  e.stopPropagation()
+                  void handleDrawClick()
+                }}
+                title={
+                  isDrawMode
+                    ? (cell.autoRefresh ?? true)
+                      ? "Drawing — auto-refresh on"
+                      : "Refresh chart"
+                    : "Draw (auto-refresh chart)"
+                }
+                aria-label="Draw"
+              >
+                <ChartLineUpIcon
+                  size={isDrawMode ? 26 : 24}
+                  weight={isDrawMode ? "fill" : "regular"}
+                />
+              </DrawButton>
+            </>
+          }
+        />
+      )}
+      {!isChartMaximized && (
+        <EditorContainer
+          ref={editorContainerRef}
+          $spotlight={isMaximized}
+          style={
+            isMaximized ? { flex: spotlightEditorRatio } : { height: topHeight }
+          }
+        >
+          <Editor
+            defaultValue={cell.value}
+            language={QuestDBLanguageName}
+            theme="dracula"
+            // Default is the literal text "loading..."; the container already
+            // shows the editor background, so render nothing until Monaco mounts
+            // instead of a flashing placeholder.
+            loading={null}
+            onMount={handleRevealMount}
+            onChange={handleEditorChange}
+            options={{
+              useShadowDOM: false,
+              automaticLayout: true,
+              occurrencesHighlight: "off",
+              overviewRulerLanes: 0,
+              minimap: { enabled: false },
+              stickyScroll: {
+                enabled: false,
+              },
+              scrollbar: {
+                useShadows: false,
+                handleMouseWheel: isFocused,
+                alwaysConsumeMouseWheel: false,
+              },
+              folding: false,
+              renderLineHighlight: "gutter",
+              glyphMargin: true,
+              lineDecorationsWidth: 24,
+              lineNumbersMinChars: 3,
+              scrollBeyondLastLine: false,
+              wordWrap: "off",
+              padding: { top: 4, bottom: 4 },
+              fontSize: 14,
+              lineHeight: 24,
+              fixedOverflowWidgets: true,
+            }}
+          />
+        </EditorContainer>
+      )}
+      {/* Inner-top resize handle (between editor and bottom slot). Only
+          rendered in double-view, since there's nothing below in single-
+          view. Renders in every layout mode (list / grid / spotlight). */}
+      {!isChartMaximized && doubleView && (
+        <ResizeHandle
+          background={theme.color.editorBackground}
+          targetRef={editorContainerRef}
+          onResize={middleResizeLive}
+          onResizeEnd={middleResizeEnd}
+          onDoubleClick={resetToDefaults}
+          doubleView={doubleView}
+        />
+      )}
+      {/* Bottom slot: result grid OR chart, OR chart filling the whole cell
+          when expanded. */}
+      {(doubleView || isChartMaximized) && (
+        <BottomSlot
+          ref={resultRef}
+          $spotlight={isMaximized}
+          style={
+            isChartMaximized
+              ? isMaximized
+                ? { flex: 1 }
+                : { height: topHeight + bottomHeight }
+              : isMaximized
+                ? { flex: 1 - spotlightEditorRatio }
+                : { height: bottomHeight }
+          }
+        >
+          {isDrawMode ? (
+            <DrawCanvas
+              cell={cell}
+              bufferId={bufferIdForEvents}
+              isFocused={isFocused}
+              onConfigChange={handleChartConfigChange}
+              onAutoRefreshChange={handleAutoRefreshChange}
+              onMaximizedChange={handleChartMaximizedChange}
+            />
+          ) : cell.result ? (
+            <InlineResultTable
+              result={cell.result}
+              isFocused={isFocused}
+              onTabChange={(index) => setActiveResultIndex(cell.id, index)}
+              onCancelQuery={(index) => {
+                cancelQuery(cell.id, index)
+              }}
+              bufferId={bufferIdForEvents}
+              cellId={cell.id}
+              isRunning={isRunning}
+              onReRun={(index) => void reRunResultAt(cell.id, index)}
+              onYieldFocus={() => editorRef.current?.focus()}
+            />
+          ) : expectingResult ? (
+            <HydrationLoader>
+              <CircleNotchSpinner size={24} />
+            </HydrationLoader>
+          ) : null}
+        </BottomSlot>
+      )}
+    </CellWrapper>
+  )
+
+  // The bottom-edge handle lives outside CellWrapper (which clips its content)
+  // so its chip can straddle the cell border, mirroring grid's `s` handle.
+  const bottomHandle =
+    !isMaximized && layoutMode !== "grid" ? (
+      <ResizeHandle
+        overlay
+        targetRef={
+          isChartMaximized || doubleView ? resultRef : editorContainerRef
+        }
+        onResize={
+          isChartMaximized
+            ? maximizedChartResizeLive
+            : doubleView
+              ? bottomEdgeResizeLive
+              : topResize.resizeLive
+        }
+        onResizeEnd={
+          isChartMaximized
+            ? maximizedChartResizeEnd
+            : doubleView
+              ? bottomEdgeResizeEnd
+              : topResize.resizeEnd
+        }
+        onDoubleClick={
+          isChartMaximized || doubleView
+            ? resetToDefaults
+            : topResize.resetHeight
+        }
+        minHeight={
+          isChartMaximized
+            ? MIN_EDITOR_HEIGHT + MIN_BOTTOM_HEIGHT_PX
+            : doubleView
+              ? MIN_BOTTOM_HEIGHT_PX
+              : undefined
+        }
+      />
+    ) : null
+
+  if (bottomHandle) {
+    return (
+      <CellShell>
+        {cellEl}
+        {bottomHandle}
+      </CellShell>
+    )
+  }
+
+  return cellEl
+}
+
+export const Cell = React.memo(CellInner)
diff --git a/src/scenes/Editor/Notebook/cells/CellDragHeader.tsx b/src/scenes/Editor/Notebook/cells/CellDragHeader.tsx
new file mode 100644
index 000000000..5365b80d7
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cells/CellDragHeader.tsx
@@ -0,0 +1,72 @@
+import React from "react"
+import styled from "styled-components"
+import { CellToolbar } from "./CellToolbar"
+import { eventBus } from "../../../../modules/EventBus"
+import { EventType } from "../../../../modules/EventBus/types"
+
+// The cell's top bar: it is the grid drag handle (`cell-drag-handle`), the
+// double-click-to-expand-width target, and the mount point for CellToolbar.
+// Shared by SQL cells (RunBar) and markdown cells so the drag/expand/toolbar
+// contract the grid relies on lives in one place.
+const HeaderBar = styled.div`
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.5rem 1rem;
+  background: ${({ theme }) => theme.color.backgroundDarker};
+  cursor: grab;
+
+  &:active {
+    cursor: grabbing;
+  }
+`
+
+const Side = styled.div`
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+`
+
+// The right cluster holds the toolbar buttons (and a markdown cell's Apply/Edit
+// button), which already self-space via their own padding — no extra gap, so
+// every button in the cluster sits the same distance apart.
+const RightSide = styled(Side)`
+  gap: 0;
+`
+
+type Props = {
+  cellId: string
+  layoutMode: "list" | "grid"
+  left?: React.ReactNode
+  right?: React.ReactNode
+}
+
+export const CellDragHeader: React.FC<Props> = ({
+  cellId,
+  layoutMode,
+  left,
+  right,
+}) => (
+  <HeaderBar
+    className="cell-drag-handle"
+    onDoubleClick={(e) => {
+      if (layoutMode !== "grid") return
+      if (
+        (e.target as HTMLElement).closest(
+          "button, a, input, select, textarea, .cell-toolbar",
+        )
+      )
+        return
+      eventBus.publish(EventType.NOTEBOOK_CELL_EXPAND_WIDTH, {
+        cellId,
+        kind: "full",
+      })
+    }}
+  >
+    <Side>{left}</Side>
+    <RightSide>
+      {right}
+      <CellToolbar cellId={cellId} inline />
+    </RightSide>
+  </HeaderBar>
+)
diff --git a/src/scenes/Editor/Notebook/cells/CellToolbar.tsx b/src/scenes/Editor/Notebook/cells/CellToolbar.tsx
new file mode 100644
index 000000000..7ffd215da
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cells/CellToolbar.tsx
@@ -0,0 +1,194 @@
+import React, { useState } from "react"
+import styled, { css } from "styled-components"
+import {
+  ChevronUp,
+  ChevronDown,
+  CopyAlt,
+  Trash,
+} from "@styled-icons/boxicons-regular"
+import {
+  DotsThreeVerticalIcon,
+  CornersOutIcon,
+  CornersInIcon,
+} from "@phosphor-icons/react"
+import { DropdownMenu, Button, Tooltip } from "../../../../components"
+import { MAX_NOTEBOOK_CELLS } from "../../../../store/notebook"
+import { useNotebookActions, useNotebookState } from "../NotebookProvider"
+import { useEditor } from "../../../../providers/EditorProvider"
+import {
+  emitUserAction,
+  signalUserEdit,
+} from "../../../../utils/notebookAIBridge"
+
+const ToolbarWrapper = styled.div<{
+  $inline?: boolean
+  $forceVisible?: boolean
+}>`
+  display: flex;
+  align-items: center;
+
+  ${({ $inline, $forceVisible }) =>
+    $inline
+      ? ""
+      : css`
+          position: absolute;
+          top: 0.4rem;
+          right: 0.6rem;
+          z-index: 2;
+          opacity: ${$forceVisible ? 1 : 0};
+          transition: opacity 0.1s;
+        `}
+`
+
+const IconWrapper = styled.span`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+`
+
+type Props = {
+  cellId: string
+  inline?: boolean
+}
+
+export const CellToolbar: React.FC<Props> = ({ cellId, inline }) => {
+  const {
+    moveCellUp,
+    moveCellDown,
+    duplicateCell,
+    deleteCell,
+    setMaximizedCellId,
+  } = useNotebookActions()
+  const { cells, maximizedCellId, settings } = useNotebookState()
+  const cellIndex = cells.findIndex((c) => c.id === cellId)
+  const totalCells = cells.length
+  // Grid mode positions cells via settings.layout[i].{x,y,w,h}, so swapping array
+  // order doesn't move them visually — hide move up/down in grid mode.
+  const isGridMode = settings.layoutMode === "grid"
+  const { activeBuffer } = useEditor()
+
+  const isMaximized = maximizedCellId === cellId
+  const [menuOpen, setMenuOpen] = useState(false)
+
+  const handleMoveUp = () => {
+    moveCellUp(cellId)
+    if (typeof activeBuffer.id === "number") {
+      emitUserAction({
+        kind: "user_moved_cell",
+        bufferId: activeBuffer.id,
+        cellId,
+      })
+    }
+  }
+  const handleMoveDown = () => {
+    moveCellDown(cellId)
+    if (typeof activeBuffer.id === "number") {
+      emitUserAction({
+        kind: "user_moved_cell",
+        bufferId: activeBuffer.id,
+        cellId,
+      })
+    }
+  }
+  const handleDuplicate = () => {
+    const newCellId = duplicateCell(cellId)
+    if (typeof activeBuffer.id === "number" && newCellId) {
+      emitUserAction({
+        kind: "user_duplicated_cell",
+        bufferId: activeBuffer.id,
+        cellId,
+        newCellId,
+      })
+    }
+  }
+  const handleDelete = () => {
+    deleteCell(cellId)
+    if (typeof activeBuffer.id === "number") {
+      emitUserAction({
+        kind: "user_deleted_cell",
+        bufferId: activeBuffer.id,
+        cellId,
+      })
+    }
+  }
+
+  return (
+    <ToolbarWrapper
+      className="cell-toolbar"
+      $inline={inline}
+      $forceVisible={menuOpen}
+    >
+      <Tooltip content={isMaximized ? "Restore" : "Maximize"}>
+        <Button
+          skin="transparent"
+          onClick={() => {
+            signalUserEdit()
+            setMaximizedCellId(isMaximized ? null : cellId)
+          }}
+          aria-label={isMaximized ? "Restore" : "Maximize"}
+        >
+          {isMaximized ? (
+            <CornersInIcon size={20} />
+          ) : (
+            <CornersOutIcon size={20} />
+          )}
+        </Button>
+      </Tooltip>
+      {!isMaximized && (
+        <DropdownMenu.Root onOpenChange={setMenuOpen}>
+          <Tooltip content="More actions">
+            <DropdownMenu.Trigger asChild>
+              <Button skin="transparent" aria-label="More actions">
+                <DotsThreeVerticalIcon size={20} weight="bold" />
+              </Button>
+            </DropdownMenu.Trigger>
+          </Tooltip>
+          <DropdownMenu.Portal>
+            <DropdownMenu.Content align="end" sideOffset={4}>
+              {!isGridMode && (
+                <>
+                  <DropdownMenu.Item
+                    disabled={cellIndex === 0}
+                    onSelect={handleMoveUp}
+                  >
+                    <IconWrapper>
+                      <ChevronUp size={16} />
+                    </IconWrapper>
+                    Move up
+                  </DropdownMenu.Item>
+                  <DropdownMenu.Item
+                    disabled={cellIndex === totalCells - 1}
+                    onSelect={handleMoveDown}
+                  >
+                    <IconWrapper>
+                      <ChevronDown size={16} />
+                    </IconWrapper>
+                    Move down
+                  </DropdownMenu.Item>
+                </>
+              )}
+              <DropdownMenu.Item
+                disabled={totalCells >= MAX_NOTEBOOK_CELLS}
+                onSelect={handleDuplicate}
+              >
+                <IconWrapper>
+                  <CopyAlt size={16} />
+                </IconWrapper>
+                Duplicate
+              </DropdownMenu.Item>
+              <DropdownMenu.Item
+                disabled={totalCells <= 1}
+                onSelect={handleDelete}
+              >
+                <IconWrapper>
+                  <Trash size={16} />
+                </IconWrapper>
+                Delete
+              </DropdownMenu.Item>
+            </DropdownMenu.Content>
+          </DropdownMenu.Portal>
+        </DropdownMenu.Root>
+      )}
+    </ToolbarWrapper>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/cells/CellWrapper.tsx b/src/scenes/Editor/Notebook/cells/CellWrapper.tsx
new file mode 100644
index 000000000..79dd7b3e8
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cells/CellWrapper.tsx
@@ -0,0 +1,76 @@
+import styled, { css } from "styled-components"
+import { color } from "../../../../utils"
+
+// `data-notebook-cell` marker is read by the container's click-outside-to-blur logic to detect clicks landing inside a cell.
+export const CellWrapper = styled.div.attrs({
+  "data-notebook-cell": "true",
+})<{
+  $focused: boolean
+  $maximized: boolean
+  $gridMode?: boolean
+}>`
+  position: relative;
+  border: 1px solid ${color("baseGrey")};
+  background: ${color("backgroundLighter")};
+  border-radius: 0.6rem;
+  overflow: hidden;
+  min-width: 0;
+  transition: all 0.15s ease;
+
+  ${({ $focused }) =>
+    $focused &&
+    css`
+      border-color: ${color("pinkDarker")};
+      /* pinkPrimary @ 30% — selected-cell glow ring */
+      box-shadow: 0 0 0 3px rgba(201, 50, 97, 0.3);
+    `}
+
+  ${({ $focused }) =>
+    !$focused &&
+    css`
+      &:hover {
+        box-shadow: 0px 0px 10px 1px ${color("backgroundDarker")};
+      }
+    `}
+
+  ${({ $maximized }) =>
+    $maximized &&
+    css`
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      border: none;
+      border-radius: 0;
+    `}
+
+  ${({ $gridMode }) =>
+    $gridMode &&
+    css`
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      height: 100%;
+      min-height: 0;
+      > *:last-child {
+        flex-grow: 1;
+      }
+    `}
+
+  ${({ $gridMode }) =>
+    !$gridMode &&
+    css`
+      .cell-drag-handle,
+      .cell-drag-handle:active {
+        cursor: default;
+      }
+    `}
+
+  &:focus {
+    outline: none;
+  }
+
+  &:hover .cell-toolbar,
+  &:focus-within .cell-toolbar {
+    opacity: 1;
+  }
+`
diff --git a/src/scenes/Editor/Notebook/cells/MarkdownCell.tsx b/src/scenes/Editor/Notebook/cells/MarkdownCell.tsx
new file mode 100644
index 000000000..2e856fbc7
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cells/MarkdownCell.tsx
@@ -0,0 +1,352 @@
+import React, {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react"
+import styled from "styled-components"
+import { CheckIcon, PencilSimpleIcon } from "@phosphor-icons/react"
+import { color } from "../../../../utils"
+import { SafeMarkdown, Button, Tooltip } from "../../../../components"
+import type { NotebookCell } from "../../../../store/notebook"
+import { useNotebookActions } from "../NotebookProvider"
+import { useEditor } from "../../../../providers/EditorProvider"
+import {
+  emitUserAction,
+  signalUserEdit,
+} from "../../../../utils/notebookAIBridge"
+import { CellWrapper } from "./CellWrapper"
+import { CellDragHeader } from "./CellDragHeader"
+import { useCellWrapperInteractions } from "./useCellWrapperInteractions"
+
+// The whole cell body shares the editor canvas color so edit and rendered
+// modes are one uniform surface (no card-colored gap at the bottom).
+const Body = styled.div`
+  min-height: 0;
+  overflow: auto;
+  background: ${color("editorBackground")};
+`
+
+// Natural-height wrapper whose measured height feeds the grid row sizing
+// (ResizeObserver below). Kept height:auto so it reports CONTENT height even
+// when the grid cell stretches the Body around it.
+const Measure = styled.div`
+  height: auto;
+`
+
+const TextArea = styled.textarea`
+  display: block;
+  width: 100%;
+  border: none;
+  outline: none;
+  resize: none;
+  overflow: hidden;
+  box-sizing: border-box;
+  background: transparent;
+  color: ${color("foreground")};
+  font-family: ${({ theme }) => theme.fontMonospace};
+  font-size: 14px;
+  line-height: 24px;
+  padding: 0.6rem 1.2rem 0.4rem;
+  white-space: pre;
+  tab-size: 4;
+
+  &::placeholder {
+    color: ${color("gray2")};
+  }
+`
+
+// Rendered markdown: clean prose on the shared editor canvas.
+const Rendered = styled.div`
+  padding: 1rem 1.2rem 0.6rem;
+  color: ${color("foreground")};
+  font-family: ${({ theme }) => theme.font};
+  font-size: 1.4rem;
+  line-height: 2.1rem;
+  word-break: break-word;
+  cursor: default;
+
+  > :first-child {
+    margin-top: 0;
+  }
+  > :last-child {
+    margin-bottom: 0;
+  }
+
+  p {
+    margin: 0 0 1rem 0;
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    margin: 1.6rem 0 0.8rem 0;
+    font-weight: 600;
+    line-height: 1.3;
+  }
+  h1 {
+    font-size: 2.2rem;
+  }
+  h2 {
+    font-size: 1.9rem;
+  }
+  h3 {
+    font-size: 1.6rem;
+  }
+  h4,
+  h5,
+  h6 {
+    font-size: 1.4rem;
+  }
+
+  strong {
+    font-weight: 600;
+  }
+  em {
+    font-style: italic;
+  }
+
+  a {
+    color: ${({ theme }) => theme.color.cyan};
+    text-decoration: none;
+    &:hover {
+      text-decoration: underline;
+    }
+  }
+
+  ul,
+  ol {
+    margin: 0.5rem 0;
+    padding-left: 2rem;
+  }
+  li {
+    margin-bottom: 0.3rem;
+  }
+
+  code {
+    background: ${color("background")};
+    border: 1px solid ${color("selection")};
+    border-radius: 0.4rem;
+    padding: 0.1rem 0.4rem;
+    font-family: ${({ theme }) => theme.fontMonospace};
+    font-size: 1.3rem;
+    color: ${color("purple")};
+    white-space: pre-wrap;
+  }
+  pre {
+    margin: 1rem 0;
+    padding: 1rem 1.2rem;
+    background: ${color("background")};
+    border: 1px solid ${color("selection")};
+    border-radius: 0.6rem;
+    overflow-x: auto;
+    code {
+      background: transparent;
+      border: none;
+      padding: 0;
+      color: ${color("foreground")};
+    }
+  }
+
+  blockquote {
+    border-left: 3px solid ${color("selection")};
+    margin: 1rem 0;
+    padding-left: 1rem;
+    color: ${color("gray2")};
+  }
+
+  hr {
+    border: none;
+    border-top: 1px solid ${color("selection")};
+    margin: 1.6rem 0;
+  }
+
+  table {
+    border-collapse: collapse;
+    margin: 1rem 0;
+    display: block;
+    overflow-x: auto;
+  }
+  th,
+  td {
+    padding: 0.6rem 0.8rem;
+    border: 1px solid ${color("selection")};
+    text-align: left;
+  }
+  th {
+    background: ${color("backgroundDarker")};
+    font-weight: 600;
+  }
+`
+
+const EmptyHint = styled.div`
+  padding: 1rem 1.2rem 0.6rem;
+  color: ${color("gray2")};
+  font-style: italic;
+  cursor: default;
+`
+
+const PLACEHOLDER = "Write markdown… (⌘/Ctrl + Enter to apply)"
+
+type Props = {
+  cell: NotebookCell
+  layoutMode?: "list" | "grid"
+  isFocused: boolean
+  isMaximized: boolean
+  // Accepted for parity with <Cell/> so markdown can be a drop-in in the
+  // render loop; markdown never runs, so these are unused.
+  isRunning?: boolean
+  isHydrating?: boolean
+}
+
+const MarkdownCellInner: React.FC<Props> = ({
+  cell,
+  layoutMode = "list",
+  isFocused,
+  isMaximized,
+}) => {
+  const { updateCell } = useNotebookActions()
+  const { activeBuffer } = useEditor()
+  const bufferIdForEvents =
+    typeof activeBuffer.id === "number" ? activeBuffer.id : undefined
+
+  const { wrapperRef, wrapperHandlers } = useCellWrapperInteractions({
+    cellId: cell.id,
+    layoutMode,
+    isMaximized,
+    isFocused,
+  })
+
+  // Editing vs rendered is a LOCAL view toggle — never persisted. A freshly
+  // added (empty) cell opens in edit mode; a reloaded non-empty cell renders.
+  const [editing, setEditing] = useState(() => cell.value.trim() === "")
+
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null)
+  const measureRef = useRef<HTMLDivElement | null>(null)
+  const topHeightRef = useRef(cell.topHeight)
+  topHeightRef.current = cell.topHeight
+
+  // The cell value is persisted live as the user types (no separate draft), so
+  // nothing is lost if the user navigates away before applying. signalUserEdit
+  // bumps the action sequence so a concurrent agent apply detects the change.
+  const handleChange = useCallback(
+    (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+      updateCell(cell.id, { value: e.target.value })
+      signalUserEdit()
+    },
+    [cell.id, updateCell],
+  )
+
+  const apply = useCallback(() => {
+    setEditing(false)
+    if (bufferIdForEvents !== undefined) {
+      emitUserAction({
+        kind: "user_updated_cell",
+        bufferId: bufferIdForEvents,
+        cellId: cell.id,
+      })
+    }
+  }, [bufferIdForEvents, cell.id])
+
+  const edit = useCallback(() => setEditing(true), [])
+
+  // Auto-grow the textarea to its content so there's no inner scrollbar and the
+  // measured height reflects the full text.
+  useLayoutEffect(() => {
+    if (!editing) return
+    const el = textareaRef.current
+    if (!el) return
+    el.style.height = "auto"
+    el.style.height = `${el.scrollHeight}px`
+  }, [editing, cell.value])
+
+  useEffect(() => {
+    if (editing) textareaRef.current?.focus()
+  }, [editing])
+
+  // Grid rows are sized from cell.topHeight (computeCellGridH). Markdown has no
+  // Monaco content-height feedback, so measure the content and write topHeight.
+  // The equality guard (read from a ref to avoid re-subscribing) stops the
+  // observe → write → re-render → observe feedback loop.
+  useEffect(() => {
+    if (layoutMode !== "grid") return
+    const el = measureRef.current
+    if (!el) return
+    const observer = new ResizeObserver(() => {
+      if (isMaximized) return
+      const next = Math.round(el.getBoundingClientRect().height)
+      if (next <= 0 || next === topHeightRef.current) return
+      updateCell(cell.id, { topHeight: next })
+    })
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [cell.id, layoutMode, isMaximized, updateCell])
+
+  const isEmpty = cell.value.trim() === ""
+
+  return (
+    <CellWrapper
+      ref={wrapperRef}
+      data-cell-id={cell.id}
+      tabIndex={-1}
+      $focused={isFocused}
+      $maximized={isMaximized}
+      $gridMode={layoutMode === "grid"}
+      {...wrapperHandlers}
+    >
+      <CellDragHeader
+        cellId={cell.id}
+        layoutMode={layoutMode}
+        right={
+          editing ? (
+            <Tooltip content="Apply (⌘/Ctrl + Enter)">
+              <Button skin="transparent" onClick={apply} aria-label="Apply">
+                <CheckIcon size={20} />
+              </Button>
+            </Tooltip>
+          ) : (
+            <Tooltip content="Edit">
+              <Button skin="transparent" onClick={edit} aria-label="Edit">
+                <PencilSimpleIcon size={20} />
+              </Button>
+            </Tooltip>
+          )
+        }
+      />
+      <Body>
+        <Measure ref={measureRef}>
+          {editing ? (
+            <TextArea
+              ref={textareaRef}
+              value={cell.value}
+              placeholder={PLACEHOLDER}
+              spellCheck={false}
+              onChange={handleChange}
+              onKeyDown={(e) => {
+                if ((e.metaKey || e.ctrlKey) && e.key === "Enter") {
+                  e.preventDefault()
+                  e.stopPropagation()
+                  apply()
+                }
+              }}
+            />
+          ) : isEmpty ? (
+            <EmptyHint onDoubleClick={edit}>
+              Empty markdown cell — double-click to edit
+            </EmptyHint>
+          ) : (
+            <Rendered onDoubleClick={edit}>
+              <SafeMarkdown>{cell.value}</SafeMarkdown>
+            </Rendered>
+          )}
+        </Measure>
+      </Body>
+    </CellWrapper>
+  )
+}
+
+export const MarkdownCell = React.memo(MarkdownCellInner)
diff --git a/src/scenes/Editor/Notebook/cells/useCellResize.ts b/src/scenes/Editor/Notebook/cells/useCellResize.ts
new file mode 100644
index 000000000..548175c7a
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cells/useCellResize.ts
@@ -0,0 +1,40 @@
+import { useCallback, useState } from "react"
+
+export type ResizeController = {
+  /** Live drag value that should override any persisted height. Null when idle. */
+  liveHeight: number | null
+  /** Called per mousemove with the latest clamped height. */
+  resizeLive: (height: number) => void
+  /** Called on drop — clears liveHeight and writes the persisted height. */
+  resizeEnd: (height: number) => void
+  /** Called on double-click — clears liveHeight and removes the override. */
+  resetHeight: () => void
+}
+
+export const useCellResize = (
+  minHeight: number,
+  commit: (height: number) => void,
+  commitReset: () => void,
+): ResizeController => {
+  const [liveHeight, setLiveHeight] = useState<number | null>(null)
+
+  const resizeLive = useCallback(
+    (height: number) => setLiveHeight(Math.max(minHeight, height)),
+    [minHeight],
+  )
+
+  const resizeEnd = useCallback(
+    (height: number) => {
+      setLiveHeight(null)
+      commit(Math.max(minHeight, height))
+    },
+    [minHeight, commit],
+  )
+
+  const resetHeight = useCallback(() => {
+    setLiveHeight(null)
+    commitReset()
+  }, [commitReset])
+
+  return { liveHeight, resizeLive, resizeEnd, resetHeight }
+}
diff --git a/src/scenes/Editor/Notebook/cells/useCellReveal.ts b/src/scenes/Editor/Notebook/cells/useCellReveal.ts
new file mode 100644
index 000000000..46eede9e8
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cells/useCellReveal.ts
@@ -0,0 +1,83 @@
+import { useCallback, useEffect, useRef } from "react"
+import type { Monaco } from "@monaco-editor/react"
+import type { editor } from "monaco-editor"
+import { eventBus } from "../../../../modules/EventBus"
+import { EventType } from "../../../../modules/EventBus/types"
+import { consumeReveal, getPendingReveal } from "../cellReveal"
+
+const FLASH_DURATION_MS = 2000
+
+// Flashes the matched text in this SQL cell's editor, drained on editor mount and on the nudge.
+export const useCellReveal = (
+  editorRef: React.MutableRefObject<editor.IStandaloneCodeEditor | null>,
+  monacoRef: React.MutableRefObject<Monaco | null>,
+  cellId: string,
+  bufferId: number | undefined,
+) => {
+  const decorationIdsRef = useRef<string[]>([])
+  const clearTimerRef = useRef<number | null>(null)
+
+  const clearReveal = useCallback(() => {
+    if (clearTimerRef.current !== null) {
+      window.clearTimeout(clearTimerRef.current)
+      clearTimerRef.current = null
+    }
+    const model = editorRef.current?.getModel()
+    if (model && decorationIdsRef.current.length > 0) {
+      decorationIdsRef.current = model.deltaDecorations(
+        decorationIdsRef.current,
+        [],
+      )
+    }
+  }, [editorRef])
+
+  const applyReveal = useCallback(() => {
+    const request = getPendingReveal()
+    if (
+      !request ||
+      request.cellId !== cellId ||
+      request.notebookField !== "cell" ||
+      request.bufferId !== bufferId
+    ) {
+      return
+    }
+    const ed = editorRef.current
+    const monaco = monacoRef.current
+    if (!ed || !monaco || !ed.getModel()) return
+    const { token, range } = request
+    requestAnimationFrame(() => {
+      const current = getPendingReveal()
+      if (!current || current.token !== token) return
+      const model = ed.getModel()
+      if (!model) return
+      const lineCount = model.getLineCount()
+      const target = new monaco.Range(
+        Math.min(range.startLineNumber, lineCount),
+        range.startColumn,
+        Math.min(range.endLineNumber, lineCount),
+        range.endColumn,
+      )
+      ed.revealRangeInCenter(target)
+      decorationIdsRef.current = model.deltaDecorations(
+        decorationIdsRef.current,
+        [{ range: target, options: { className: "notebookSearchHighlight" } }],
+      )
+      consumeReveal(token)
+      if (clearTimerRef.current !== null) {
+        window.clearTimeout(clearTimerRef.current)
+      }
+      clearTimerRef.current = window.setTimeout(clearReveal, FLASH_DURATION_MS)
+    })
+  }, [cellId, bufferId, editorRef, monacoRef, clearReveal])
+
+  useEffect(() => {
+    applyReveal()
+    eventBus.subscribe(EventType.NOTEBOOK_REVEAL_CELL, applyReveal)
+    return () => {
+      eventBus.unsubscribe(EventType.NOTEBOOK_REVEAL_CELL, applyReveal)
+      clearReveal()
+    }
+  }, [applyReveal, clearReveal])
+
+  return { applyReveal }
+}
diff --git a/src/scenes/Editor/Notebook/cells/useCellSelectionDecoration.ts b/src/scenes/Editor/Notebook/cells/useCellSelectionDecoration.ts
new file mode 100644
index 000000000..7931cc94a
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cells/useCellSelectionDecoration.ts
@@ -0,0 +1,47 @@
+import { useCallback, useRef } from "react"
+import type { Monaco } from "@monaco-editor/react"
+import type { editor } from "monaco-editor"
+
+export const useCellSelectionDecoration = (
+  editorRef: React.MutableRefObject<editor.IStandaloneCodeEditor | null>,
+  monacoRef: React.MutableRefObject<Monaco | null>,
+) => {
+  const decorationIdsRef = useRef<string[]>([])
+
+  const applyHighlight = useCallback(
+    (success: boolean) => {
+      const ed = editorRef.current
+      const mon = monacoRef.current
+      if (!ed || !mon) return
+      const selection = ed.getSelection()
+      const model = ed.getModel()
+      if (!selection || !model || selection.isEmpty()) return
+
+      decorationIdsRef.current = ed.deltaDecorations(decorationIdsRef.current, [
+        {
+          range: new mon.Range(
+            selection.startLineNumber,
+            selection.startColumn,
+            selection.endLineNumber,
+            selection.endColumn,
+          ),
+          options: {
+            isWholeLine: false,
+            className: success
+              ? "selectionSuccessHighlight"
+              : "selectionErrorHighlight",
+          },
+        },
+      ])
+    },
+    [editorRef, monacoRef],
+  )
+
+  const clearHighlight = useCallback(() => {
+    const ed = editorRef.current
+    if (!ed) return
+    decorationIdsRef.current = ed.deltaDecorations(decorationIdsRef.current, [])
+  }, [editorRef])
+
+  return { applyHighlight, clearHighlight }
+}
diff --git a/src/scenes/Editor/Notebook/cells/useCellWrapperInteractions.ts b/src/scenes/Editor/Notebook/cells/useCellWrapperInteractions.ts
new file mode 100644
index 000000000..64a23d0ee
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cells/useCellWrapperInteractions.ts
@@ -0,0 +1,91 @@
+import React, { useCallback, useEffect, useRef } from "react"
+import { useNotebookActions } from "../NotebookProvider"
+import { useEditor } from "../../../../providers/EditorProvider"
+import { emitUserAction } from "../../../../utils/notebookAIBridge"
+
+// Wrapper-level interactions shared by every cell kind (SQL and markdown) so
+// they behave identically and can't drift: click-to-focus, arrow-key reorder
+// (list mode), and Esc-to-blur. The selector that decides "did the user click
+// an interactive element" is the single source of truth for both cells.
+const INTERACTIVE_SELECTOR =
+  "button, a, input, select, textarea, [contenteditable], .monaco-editor"
+
+type Options = {
+  cellId: string
+  layoutMode: "list" | "grid"
+  isMaximized: boolean
+  isFocused: boolean
+}
+
+export const useCellWrapperInteractions = ({
+  cellId,
+  layoutMode,
+  isMaximized,
+  isFocused,
+}: Options) => {
+  const { moveCellUp, moveCellDown, setFocusedCell } = useNotebookActions()
+  const { activeBuffer } = useEditor()
+  const bufferIdForEvents =
+    typeof activeBuffer.id === "number" ? activeBuffer.id : undefined
+
+  const wrapperRef = useRef<HTMLDivElement | null>(null)
+  const canArrowMove = layoutMode !== "grid" && !isMaximized
+
+  // Esc blurs the cell. Respect defaultPrevented so a Radix popper close
+  // doesn't double up with cell blur on the same keystroke.
+  useEffect(() => {
+    if (!isFocused) return
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape") return
+      if (e.defaultPrevented) return
+      setFocusedCell(null)
+      ;(document.activeElement as HTMLElement | null)?.blur?.()
+    }
+    window.addEventListener("keydown", onKey)
+    return () => window.removeEventListener("keydown", onKey)
+  }, [isFocused, setFocusedCell])
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      if (!canArrowMove || e.target !== e.currentTarget) return
+      if (e.key !== "ArrowUp" && e.key !== "ArrowDown") return
+      e.preventDefault()
+      if (e.key === "ArrowUp") moveCellUp(cellId)
+      else moveCellDown(cellId)
+      if (bufferIdForEvents !== undefined) {
+        emitUserAction({
+          kind: "user_moved_cell",
+          bufferId: bufferIdForEvents,
+          cellId,
+        })
+      }
+      requestAnimationFrame(() => {
+        const node = wrapperRef.current
+        if (!node) return
+        node.focus({ preventScroll: true })
+        node.scrollIntoView({ block: "nearest" })
+      })
+    },
+    [canArrowMove, cellId, moveCellUp, moveCellDown, bufferIdForEvents],
+  )
+
+  const onMouseDown = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      const target = e.target as HTMLElement
+      if (!target.closest?.(".cell-drag-handle")) {
+        e.stopPropagation()
+      }
+      setFocusedCell(cellId)
+      if (canArrowMove && !target.closest(INTERACTIVE_SELECTOR)) {
+        wrapperRef.current?.focus({ preventScroll: true })
+      }
+    },
+    [canArrowMove, cellId, setFocusedCell],
+  )
+
+  return {
+    wrapperRef,
+    canArrowMove,
+    wrapperHandlers: { onKeyDown, onMouseDown },
+  }
+}
diff --git a/src/scenes/Editor/Notebook/cells/useMonacoCellEditor.ts b/src/scenes/Editor/Notebook/cells/useMonacoCellEditor.ts
new file mode 100644
index 000000000..e0f814f62
--- /dev/null
+++ b/src/scenes/Editor/Notebook/cells/useMonacoCellEditor.ts
@@ -0,0 +1,195 @@
+import { useCallback, useEffect, useRef } from "react"
+import type { Monaco } from "@monaco-editor/react"
+import type { editor } from "monaco-editor"
+import type * as QuestDB from "../../../../utils/questdb"
+import {
+  clearModelMarkers,
+  clearValidationMarkers,
+  getQueryFromCursor,
+  pinMonacoContextMenu,
+  validateQueryJIT,
+} from "../../Monaco/utils"
+
+const VALIDATION_DEBOUNCE_MS = 300
+
+type ValidateFn = (
+  sql: string,
+  signal?: AbortSignal,
+) => ReturnType<QuestDB.Client["validateQuery"]>
+
+export type UseMonacoCellEditorOptions = {
+  cellId: string
+  editorViewState?: editor.ICodeEditorViewState
+  quest: QuestDB.Client
+  onFocus: () => void
+  onSaveViewState: (state: editor.ICodeEditorViewState) => void
+  onRunAtCursor: () => void
+  onRunAll: () => void
+  // Fires every time Monaco reports a content-size change. Cell.tsx uses
+  // this to drive cell.topHeight (the auto-grow path). Naturally rate-
+  // limited by Monaco to per-line-count changes; no debouncing needed
+  // here. Caller is responsible for guarding on cell.topResized.
+  onContentHeightChange?: (px: number) => void
+  // Optional override for the JIT validator. Notebook passes a wrapped
+  // function that prepends global variables as DECLARE so `@symbol`
+  // references resolve. Falls back to quest.validateQuery if absent.
+  validate?: ValidateFn
+}
+
+export const useMonacoCellEditor = ({
+  cellId,
+  editorViewState,
+  quest,
+  onFocus,
+  onSaveViewState,
+  onRunAtCursor,
+  onRunAll,
+  onContentHeightChange,
+  validate,
+}: UseMonacoCellEditorOptions) => {
+  const editorRef = useRef<editor.IStandaloneCodeEditor | null>(null)
+  const monacoRef = useRef<Monaco | null>(null)
+  const validationTimeoutRef = useRef<number | null>(null)
+  const contextMenuCleanupRef = useRef<(() => void) | null>(null)
+  const cursorQueryDecorationIdsRef = useRef<string[]>([])
+  const decoratingRef = useRef(false)
+
+  const decorateCursorQuery = useCallback(() => {
+    const ed = editorRef.current
+    const mon = monacoRef.current
+    if (!ed || !mon) return
+    if (decoratingRef.current) return
+    decoratingRef.current = true
+    try {
+      const query = getQueryFromCursor(ed)
+      cursorQueryDecorationIdsRef.current = ed.deltaDecorations(
+        cursorQueryDecorationIdsRef.current,
+        query
+          ? [
+              {
+                range: new mon.Range(
+                  query.row + 1,
+                  query.column,
+                  query.endRow + 1,
+                  query.endColumn,
+                ),
+                options: {
+                  isWholeLine: true,
+                  linesDecorationsClassName: "cursorQueryDecoration",
+                },
+              },
+            ]
+          : [],
+      )
+    } finally {
+      decoratingRef.current = false
+    }
+  }, [])
+
+  // Refs for handlers so the once-mounted Monaco listeners always read
+  // the latest callbacks instead of capturing stale closures.
+  const onRunAtCursorRef = useRef(onRunAtCursor)
+  onRunAtCursorRef.current = onRunAtCursor
+  const onRunAllRef = useRef(onRunAll)
+  onRunAllRef.current = onRunAll
+  const onContentHeightChangeRef = useRef(onContentHeightChange)
+  onContentHeightChangeRef.current = onContentHeightChange
+  const validateRef = useRef<ValidateFn | undefined>(validate)
+  validateRef.current = validate
+
+  const triggerValidation = useCallback(() => {
+    if (!monacoRef.current || !editorRef.current) return
+    validateQueryJIT(
+      monacoRef.current,
+      editorRef.current,
+      cellId,
+      () => ({}),
+      (q, signal) =>
+        validateRef.current
+          ? validateRef.current(q, signal)
+          : quest.validateQuery(q, signal),
+    )
+  }, [cellId, quest])
+
+  const scheduleValidation = useCallback(() => {
+    if (validationTimeoutRef.current) {
+      window.clearTimeout(validationTimeoutRef.current)
+    }
+    validationTimeoutRef.current = window.setTimeout(() => {
+      triggerValidation()
+      validationTimeoutRef.current = null
+    }, VALIDATION_DEBOUNCE_MS)
+  }, [triggerValidation])
+
+  const handleEditorMount = useCallback(
+    (ed: editor.IStandaloneCodeEditor, monaco: Monaco) => {
+      editorRef.current = ed
+      monacoRef.current = monaco
+
+      if (editorViewState) {
+        ed.restoreViewState(editorViewState)
+      }
+
+      const reportHeight = () => {
+        onContentHeightChangeRef.current?.(ed.getContentHeight())
+      }
+
+      ed.onDidContentSizeChange(reportHeight)
+      reportHeight()
+
+      contextMenuCleanupRef.current = pinMonacoContextMenu(ed)
+
+      ed.onDidFocusEditorWidget(onFocus)
+      ed.onDidChangeCursorPosition(() => {
+        scheduleValidation()
+        decorateCursorQuery()
+      })
+      ed.onDidChangeModelContent(() => {
+        scheduleValidation()
+        decorateCursorQuery()
+      })
+      decorateCursorQuery()
+
+      ed.addAction({
+        id: "notebook-run",
+        label: "Run Query",
+        keybindings: [monaco.KeyMod.CtrlCmd | monaco.KeyCode.Enter],
+        run: () => void onRunAtCursorRef.current(),
+      })
+
+      ed.addAction({
+        id: "notebook-run-all",
+        label: "Run All",
+        keybindings: [
+          monaco.KeyMod.CtrlCmd | monaco.KeyMod.Shift | monaco.KeyCode.Enter,
+        ],
+        run: () => void onRunAllRef.current(),
+      })
+    },
+    [editorViewState, onFocus, scheduleValidation, decorateCursorQuery],
+  )
+
+  useEffect(() => {
+    return () => {
+      if (validationTimeoutRef.current) {
+        window.clearTimeout(validationTimeoutRef.current)
+      }
+      contextMenuCleanupRef.current?.()
+      contextMenuCleanupRef.current = null
+      if (editorRef.current && monacoRef.current) {
+        clearModelMarkers(monacoRef.current, editorRef.current)
+        clearValidationMarkers(monacoRef.current, editorRef.current, cellId)
+        const state = editorRef.current.saveViewState()
+        if (state) {
+          onSaveViewState(state)
+        }
+      }
+    }
+  }, [])
+
+  return {
+    editorRef,
+    monacoRef,
+    handleEditorMount,
+  }
+}
diff --git a/src/scenes/Editor/Notebook/declareUtils.corpus.test.ts b/src/scenes/Editor/Notebook/declareUtils.corpus.test.ts
new file mode 100644
index 000000000..785996553
--- /dev/null
+++ b/src/scenes/Editor/Notebook/declareUtils.corpus.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest"
+import { prependGlobalsDeclare } from "./declareUtils"
+import queries from "./__fixtures__/declare-cases.json"
+
+const cases: string[] = queries
+
+const startsWithDeclare = (q: string) => /^\s*DECLARE\b/i.test(q)
+const startsWithExplain = (q: string) => /^\s*EXPLAIN\b/i.test(q)
+const hasInnerDeclare = (q: string) => /\bDECLARE\b/i.test(q)
+
+const GLOBAL = [{ name: "x", value: "999" }]
+
+describe("prependGlobalsDeclare — corpus regression (declare-cases.json)", () => {
+  it("EXPLAIN-led statements remain EXPLAIN-led", () => {
+    const explains = cases.filter(startsWithExplain)
+    expect(explains.length).toBeGreaterThan(0)
+    for (const c of explains) {
+      const { sql } = prependGlobalsDeclare(c, GLOBAL)
+      expect(/^\s*EXPLAIN\b/i.test(sql)).toBe(true)
+    }
+  })
+
+  it("wrapped shapes (CREATE VIEW/TABLE AS (, INSERT INTO ... SELECT * FROM () are left untouched", () => {
+    const wrapped = cases.filter(
+      (c) =>
+        !startsWithDeclare(c) && !startsWithExplain(c) && hasInnerDeclare(c),
+    )
+    expect(wrapped.length).toBeGreaterThan(0)
+    for (const c of wrapped) {
+      const r = prependGlobalsDeclare(c, GLOBAL)
+      expect(r.sql).toBe(c)
+      expect(r.insertedRange).toBeNull()
+    }
+  })
+
+  it("statements starting with DECLARE either merge `@x` once or no-op (shadowed/invalid)", () => {
+    const starts = cases.filter(startsWithDeclare)
+    expect(starts.length).toBeGreaterThan(40)
+    for (const c of starts) {
+      const { sql, insertedRange } = prependGlobalsDeclare(c, GLOBAL)
+      const userHasX = /@x\s*:=/.test(c)
+      if (userHasX) {
+        expect(sql).toBe(c)
+        expect(insertedRange).toBeNull()
+      } else if (insertedRange === null) {
+        expect(sql).toBe(c)
+      } else {
+        // Merged: the rendered block contains exactly one `@x := 999`.
+        const matches = sql.match(/@x\s*:=\s*999/g) ?? []
+        expect(matches.length).toBe(1)
+      }
+      // Result still starts with DECLARE.
+      expect(/^\s*DECLARE\b/i.test(sql)).toBe(true)
+    }
+  })
+
+  it("insertedRange.delta always matches the actual byte delta", () => {
+    for (const c of cases) {
+      const { sql, insertedRange } = prependGlobalsDeclare(c, GLOBAL)
+      expect(sql.length - c.length).toBe(insertedRange?.delta ?? 0)
+    }
+  })
+})
diff --git a/src/scenes/Editor/Notebook/declareUtils.test.ts b/src/scenes/Editor/Notebook/declareUtils.test.ts
new file mode 100644
index 000000000..4da8d7d2b
--- /dev/null
+++ b/src/scenes/Editor/Notebook/declareUtils.test.ts
@@ -0,0 +1,665 @@
+import { describe, expect, it } from "vitest"
+import {
+  isValidVariableName,
+  mapWireErrorPosition,
+  normalizeVariables,
+  parseDeclareBlock,
+  prependGlobalsDeclare,
+  renderDeclareBlock,
+  stripLeadingAt,
+  validateVariableShape,
+} from "./declareUtils"
+
+const vars = (values: Record<string, string>) =>
+  Object.entries(values).map(([name, value]) => ({ name, value }))
+
+describe("isValidVariableName", () => {
+  it.each(["x", "X", "_x", "symbol", "from_time", "v1", "_"])(
+    "accepts %s",
+    (n) => {
+      expect(isValidVariableName(n)).toBe(true)
+    },
+  )
+  it.each([
+    "café",
+    "日本語",
+    "Σx",
+    "naïve",
+    "한국",
+    "Москва",
+    "ø",
+    "θ_x",
+    "x_中文",
+  ])(
+    "accepts Unicode identifier %s (BMP above 0x80, like QuestDB lexer)",
+    (n) => {
+      expect(isValidVariableName(n)).toBe(true)
+    },
+  )
+  it.each([
+    "",
+    "1x", // leading digit
+    "-x", // leading hyphen (would be UnaryMinus)
+    "+x", // leading plus
+    ".x", // leading dot
+    "@x", // leading @
+    " x", // leading space
+    "x-y", // QuestDB Minus operator
+    "x+y", // QuestDB Plus operator
+    "x.y", // QuestDB Dot operator
+    "x:y", // QuestDB Colon / :=
+    "x y", // whitespace
+    "x'y", // single-quote starts string
+    'x"y', // double-quote starts identifier
+    "x`y", // backtick starts identifier
+    "x@y", // our reference-start marker
+    "x\\y", // escape safety
+  ])("rejects %s", (n) => {
+    expect(isValidVariableName(n)).toBe(false)
+  })
+})
+
+describe("stripLeadingAt", () => {
+  it("strips a leading @", () => {
+    expect(stripLeadingAt("@symbol")).toBe("symbol")
+  })
+  it("leaves names without @ untouched", () => {
+    expect(stripLeadingAt("symbol")).toBe("symbol")
+  })
+})
+
+describe("normalizeVariables", () => {
+  it("preserves ordered variable arrays", () => {
+    expect(
+      normalizeVariables([
+        { name: "base", value: "10" },
+        { name: "derived", value: "@base + 1" },
+      ]),
+    ).toEqual(vars({ base: "10", derived: "@base + 1" }))
+  })
+
+  it("upgrades old object-shaped variables without crashing", () => {
+    expect(normalizeVariables({ x: "1", y: "@x + 1" })).toEqual(
+      vars({ x: "1", y: "@x + 1" }),
+    )
+  })
+})
+
+describe("parseDeclareBlock", () => {
+  it("returns {} when no DECLARE is present", () => {
+    expect(parseDeclareBlock("SELECT 1 FROM t")).toEqual([])
+  })
+
+  it("returns {} for empty / whitespace input", () => {
+    expect(parseDeclareBlock("")).toEqual([])
+    expect(parseDeclareBlock("   \n  ")).toEqual([])
+  })
+
+  it("parses a single assignment", () => {
+    expect(parseDeclareBlock("DECLARE @x := 10")).toEqual(vars({ x: "10" }))
+  })
+
+  it("parses multiple assignments", () => {
+    expect(parseDeclareBlock("DECLARE @x := 10, @y := 'BTC'")).toEqual(
+      vars({ x: "10", y: "'BTC'" }),
+    )
+  })
+
+  it("preserves nested function values", () => {
+    expect(
+      parseDeclareBlock(
+        "DECLARE @from := dateadd('d', -7, now()), @to := now()",
+      ),
+    ).toEqual(vars({ from: "dateadd('d', -7, now())", to: "now()" }))
+  })
+
+  it("ignores trailing SELECT", () => {
+    expect(
+      parseDeclareBlock("DECLARE @x := 10, @y := 5 SELECT @x + @y FROM t"),
+    ).toEqual(vars({ x: "10", y: "5" }))
+  })
+
+  it("ignores trailing WITH", () => {
+    expect(
+      parseDeclareBlock("DECLARE @x := 10 WITH cte AS (SELECT 1) SELECT @x"),
+    ).toEqual(vars({ x: "10" }))
+  })
+
+  it("ignores trailing semicolon", () => {
+    expect(parseDeclareBlock("DECLARE @x := 10 ;")).toEqual(vars({ x: "10" }))
+  })
+
+  it("strips OVERRIDABLE modifier", () => {
+    expect(
+      parseDeclareBlock("DECLARE OVERRIDABLE @x := 1, OVERRIDABLE @y := 2"),
+    ).toEqual(vars({ x: "1", y: "2" }))
+  })
+
+  it("rejects assignments using `=` (server requires `:=`)", () => {
+    // QuestDB's parser refuses `DECLARE @x = …` with
+    //   `expected variable assignment operator ':='`.
+    // We mirror that: `=` assignments are dropped from the parsed map.
+    expect(parseDeclareBlock("DECLARE @x = 1, @y := 2")).toEqual(
+      vars({ y: "2" }),
+    )
+    expect(parseDeclareBlock("DECLARE @x = 1")).toEqual([])
+  })
+
+  it("handles multi-line input", () => {
+    const text = `
+DECLARE
+  @from := dateadd('d', -7, now()),
+  @to := now(),
+  @symbol := 'BTCUSD'
+SELECT * FROM trades`
+    expect(parseDeclareBlock(text)).toEqual(
+      vars({
+        from: "dateadd('d', -7, now())",
+        to: "now()",
+        symbol: "'BTCUSD'",
+      }),
+    )
+  })
+
+  it("ignores text before DECLARE", () => {
+    // (Pragmatic: clipboard might have whitespace or stray content.)
+    expect(parseDeclareBlock("   DECLARE @x := 1")).toEqual(vars({ x: "1" }))
+  })
+
+  it("preserves commas inside bracket subscripts (array indexing)", () => {
+    // QuestDB's array-indexing syntax `bids[1,1]` has a comma at paren
+    // depth 0 but bracket depth 1 — must NOT split the assignment.
+    expect(parseDeclareBlock("DECLARE @best_bid := bids[1,1]")).toEqual(
+      vars({ best_bid: "bids[1,1]" }),
+    )
+  })
+
+  it("handles multiple bracket-indexed values from QuestDB docs", () => {
+    expect(
+      parseDeclareBlock(
+        "DECLARE @best_bid := bids[1,1], @volume_l1 := bids[2,1]",
+      ),
+    ).toEqual(vars({ best_bid: "bids[1,1]", volume_l1: "bids[2,1]" }))
+  })
+
+  it("handles array slice syntax with colon", () => {
+    expect(parseDeclareBlock("DECLARE @first_four := bids[1:4]")).toEqual(
+      vars({ first_four: "bids[1:4]" }),
+    )
+  })
+
+  it("captures a subquery value without truncating it", () => {
+    expect(parseDeclareBlock("DECLARE @c := (SELECT count(*) FROM t)")).toEqual(
+      vars({ c: "(SELECT count(*) FROM t)" }),
+    )
+  })
+
+  it("does not swallow the next assignment when a comma is missing", () => {
+    // `DECLARE @x := 5 @y := 10` is malformed — the server would reject it.
+    // We should at minimum NOT capture `@y` into `@x`'s value. Whichever
+    // assignment we extract should hold its own value.
+    const out = parseDeclareBlock("DECLARE @x := 5 @y := 10")
+    expect(out.find((v) => v.name === "x")?.value).not.toBe("5 @y := 10")
+  })
+
+  it("rejects `@x = …` for both assignments (the server only accepts `:=`)", () => {
+    expect(parseDeclareBlock("DECLARE @x = 1, @y = 2")).toEqual([])
+  })
+})
+
+describe("renderDeclareBlock", () => {
+  it("returns empty string for empty input", () => {
+    expect(renderDeclareBlock([])).toBe("")
+  })
+  it("emits a multi-line DECLARE statement", () => {
+    expect(renderDeclareBlock(vars({ x: "10", y: "'BTC'" }))).toBe(
+      "DECLARE\n  @x := 10,\n  @y := 'BTC'",
+    )
+  })
+  it("indents a single assignment on its own line", () => {
+    expect(renderDeclareBlock(vars({ x: "10" }))).toBe("DECLARE\n  @x := 10")
+  })
+  it("drops invalid identifier names silently", () => {
+    expect(renderDeclareBlock(vars({ "bad-name": "1", good: "2" }))).toBe(
+      "DECLARE\n  @good := 2",
+    )
+  })
+  it("round-trips through parseDeclareBlock", () => {
+    const input = {
+      from: "dateadd('d', -7, now())",
+      to: "now()",
+      symbol: "'BTCUSD'",
+    }
+    expect(parseDeclareBlock(renderDeclareBlock(vars(input)))).toEqual(
+      vars(input),
+    )
+  })
+})
+
+describe("prependGlobalsDeclare", () => {
+  it("is a no-op when globals are empty", () => {
+    const sql = "SELECT @x FROM t"
+    expect(prependGlobalsDeclare(sql, [])).toEqual({
+      sql,
+      insertedRange: null,
+    })
+  })
+
+  it("is a no-op for empty / whitespace / comment-only input", () => {
+    const globals = vars({ x: "1" })
+    expect(prependGlobalsDeclare("", globals).insertedRange).toBeNull()
+    expect(prependGlobalsDeclare("   \n  ", globals).insertedRange).toBeNull()
+    expect(
+      prependGlobalsDeclare("-- only a comment", globals).insertedRange,
+    ).toBeNull()
+    expect(
+      prependGlobalsDeclare("/* block only */", globals).insertedRange,
+    ).toBeNull()
+  })
+
+  it("prepends DECLARE before a bare SELECT", () => {
+    const original = "SELECT @x FROM t"
+    const { sql, insertedRange } = prependGlobalsDeclare(
+      original,
+      vars({ x: "1" }),
+    )
+    expect(sql).toBe("DECLARE\n  @x := 1\nSELECT @x FROM t")
+    const blockLen = "DECLARE\n  @x := 1\n".length
+    expect(insertedRange).toEqual({
+      start: 0,
+      end: blockLen,
+      delta: blockLen,
+    })
+  })
+
+  it("prepends DECLARE before a bare WITH", () => {
+    const { sql } = prependGlobalsDeclare(
+      "WITH cte AS (SELECT 1) SELECT @x FROM cte",
+      vars({ x: "1" }),
+    )
+    expect(sql.startsWith("DECLARE\n  @x := 1\nWITH ")).toBe(true)
+  })
+
+  it("preserves a leading line comment, with insertion offset AFTER the comment", () => {
+    const { sql, insertedRange } = prependGlobalsDeclare(
+      "-- header\nSELECT @x",
+      vars({ x: "1" }),
+    )
+    expect(sql).toBe("-- header\nDECLARE\n  @x := 1\nSELECT @x")
+    // Start must point at the first non-trivia char (the 'S' of SELECT),
+    // not at 0. Otherwise marker classification of trivia-area errors breaks.
+    expect(insertedRange?.start).toBe("-- header\n".length)
+  })
+
+  it("preserves a leading block comment and inserts DECLARE after it", () => {
+    const { sql } = prependGlobalsDeclare(
+      "/* header */ SELECT @x",
+      vars({ x: "1" }),
+    )
+    expect(sql).toBe("/* header */ DECLARE\n  @x := 1\nSELECT @x")
+  })
+
+  it("no-ops when every global is shadowed by a user local", () => {
+    const sql = "DECLARE @x := 99 SELECT @x"
+    expect(prependGlobalsDeclare(sql, vars({ x: "1" }))).toEqual({
+      sql,
+      insertedRange: null,
+    })
+  })
+
+  it("merges non-shadowed globals into the user's DECLARE block (globals first)", () => {
+    const original = "DECLARE @y := 99 SELECT @x + @y"
+    const { sql, insertedRange } = prependGlobalsDeclare(
+      original,
+      vars({ x: "1", y: "10" }),
+    )
+    // Globals listed first; `y` is dropped because the user declared it.
+    expect(sql).toBe("DECLARE\n  @x := 1,\n  @y := 99 SELECT @x + @y")
+    expect(insertedRange?.start).toBe(0)
+    // The wire-block range covers the FULL merged DECLARE; `delta` is just
+    // the size change (used for the body shift after the block ends).
+    const wireBlock = "DECLARE\n  @x := 1,\n  @y := 99"
+    expect(insertedRange?.end).toBe(wireBlock.length)
+    expect(insertedRange?.delta).toBe(sql.length - original.length)
+  })
+
+  it("merge with multiple user assignments: wire block covers all locals, delta = total byte change", () => {
+    // The merge case where the simple `position - delta` math would mis-map
+    // positions inside the user's @a — the canonical `,\n  ` separator we
+    // emit doesn't match the user's `, ` separator, so shifts vary.
+    // `insertedRange.end` extending past the last user assignment ensures
+    // the validator wrapper treats any error inside the block as
+    // "in DECLARE block" rather than back-mapping incorrectly.
+    const original = "DECLARE @a := 1, @b := 2 SELECT @a + @b"
+    const { sql, insertedRange } = prependGlobalsDeclare(
+      original,
+      vars({ x: "99" }),
+    )
+    const wireBlock = "DECLARE\n  @x := 99,\n  @a := 1,\n  @b := 2"
+    expect(sql).toBe(`${wireBlock} SELECT @a + @b`)
+    expect(insertedRange).toEqual({
+      start: 0,
+      end: wireBlock.length,
+      delta: sql.length - original.length,
+    })
+    // A position INSIDE @a (in wire coords) must be inside [start, end) so
+    // the validator wrapper falls through to the "in DECLARE block" branch
+    // — back-mapping with `delta` would point at the wrong column.
+    const wireAtPosOfA = wireBlock.indexOf("@a")
+    expect(wireAtPosOfA).toBeGreaterThanOrEqual(insertedRange!.start)
+    expect(wireAtPosOfA).toBeLessThan(insertedRange!.end)
+  })
+
+  it("preserves OVERRIDABLE on a user assignment when merging in a new global", () => {
+    // P1 fix: the merge must not re-render the user's assignment from a plain
+    // name/value map — that would silently drop OVERRIDABLE and change view
+    // semantics (caller-can-override flag).
+    const { sql } = prependGlobalsDeclare(
+      "DECLARE OVERRIDABLE @y := 99 SELECT @x + @y",
+      vars({ x: "1" }),
+    )
+    expect(sql).toBe(
+      "DECLARE\n  @x := 1,\n  OVERRIDABLE @y := 99 SELECT @x + @y",
+    )
+  })
+
+  it("preserves OVERRIDABLE across multiple user assignments in a merge", () => {
+    const { sql } = prependGlobalsDeclare(
+      "DECLARE OVERRIDABLE @a := 1, @b := 2 SELECT @a + @b + @c",
+      vars({ c: "3" }),
+    )
+    expect(sql).toBe(
+      "DECLARE\n  @c := 3,\n  OVERRIDABLE @a := 1,\n  @b := 2 SELECT @a + @b + @c",
+    )
+  })
+
+  it("no-ops when the user's leading DECLARE contains an invalid `=` assignment", () => {
+    // P1 fix: don't silently rewrite the user's broken SQL into something
+    // executable just because we have a global. Let the server emit
+    // `expected variable assignment operator ':='`.
+    const sql = "DECLARE @x = 1 SELECT @x"
+    expect(prependGlobalsDeclare(sql, vars({ x: "10" }))).toEqual({
+      sql,
+      insertedRange: null,
+    })
+  })
+
+  it("no-ops when ANY user assignment is invalid, even if globals are non-shadowed", () => {
+    const sql = "DECLARE @x := 1, @y = 2 SELECT @x + @y + @z"
+    expect(prependGlobalsDeclare(sql, vars({ z: "3" }))).toEqual({
+      sql,
+      insertedRange: null,
+    })
+  })
+
+  it("EXPLAIN: recurses into the suffix and inserts before the inner SELECT", () => {
+    const original = "EXPLAIN SELECT @x"
+    const { sql, insertedRange } = prependGlobalsDeclare(
+      original,
+      vars({ x: "1" }),
+    )
+    expect(sql).toBe("EXPLAIN DECLARE\n  @x := 1\nSELECT @x")
+    const blockLen = "DECLARE\n  @x := 1\n".length
+    expect(insertedRange).toEqual({
+      start: "EXPLAIN ".length,
+      end: "EXPLAIN ".length + blockLen,
+      delta: blockLen,
+    })
+  })
+
+  it("EXPLAIN with user DECLARE: drops shadowed global, no-op when all shadowed", () => {
+    const sql = "EXPLAIN DECLARE @x := 99 SELECT @x"
+    expect(prependGlobalsDeclare(sql, vars({ x: "1" }))).toEqual({
+      sql,
+      insertedRange: null,
+    })
+  })
+
+  it("EXPLAIN with user DECLARE: merges non-shadowed globals", () => {
+    const { sql } = prependGlobalsDeclare(
+      "EXPLAIN DECLARE @y := 99 SELECT @x + @y",
+      vars({ x: "1" }),
+    )
+    expect(sql).toBe("EXPLAIN DECLARE\n  @x := 1,\n  @y := 99 SELECT @x + @y")
+  })
+
+  it("INSERT INTO is a no-op (phase-1 fallback)", () => {
+    const sql = "INSERT INTO t SELECT @x"
+    expect(prependGlobalsDeclare(sql, vars({ x: "1" }))).toEqual({
+      sql,
+      insertedRange: null,
+    })
+  })
+
+  it("WITH cte ... INSERT INTO is a no-op (WITH-led but not a SELECT body)", () => {
+    // `WITH ... INSERT INTO ... SELECT ...` is valid user SQL but is NOT a
+    // valid DECLARE target — the grammar is `DECLARE ... [WITH ...] SELECT`.
+    // Prepending would produce a server error.
+    const sql = "WITH cte AS (SELECT 1) INSERT INTO t SELECT * FROM cte"
+    expect(prependGlobalsDeclare(sql, vars({ x: "1" }))).toEqual({
+      sql,
+      insertedRange: null,
+    })
+  })
+
+  it("EXPLAIN WITH ... INSERT is a no-op (recursion delegates to analyzer)", () => {
+    const sql = "EXPLAIN WITH cte AS (SELECT 1) INSERT INTO t SELECT * FROM cte"
+    expect(prependGlobalsDeclare(sql, vars({ x: "1" }))).toEqual({
+      sql,
+      insertedRange: null,
+    })
+  })
+
+  it("WITH cte ... SELECT IS prepended (valid DECLARE target)", () => {
+    const original = "WITH cte AS (SELECT 1 AS v) SELECT @x + v FROM cte"
+    const { sql, insertedRange } = prependGlobalsDeclare(
+      original,
+      vars({ x: "1" }),
+    )
+    expect(sql).toBe(
+      `DECLARE\n  @x := 1\nWITH cte AS (SELECT 1 AS v) SELECT @x + v FROM cte`,
+    )
+    expect(insertedRange?.start).toBe(0)
+  })
+
+  it("DECLARE @x := 1 INSERT INTO ... is a no-op (parse-recovery sham)", () => {
+    // Parser recovery produces a declareClause + an orphan insertStatement.
+    // We must NOT silently rewrite the user's invalid SQL into something
+    // executable just because `x` doesn't shadow.
+    const sql = "DECLARE @x := 1 INSERT INTO t SELECT @x"
+    // Use a non-shadowing global so the merge would otherwise try to fire.
+    expect(prependGlobalsDeclare(sql, vars({ y: "2" }))).toEqual({
+      sql,
+      insertedRange: null,
+    })
+  })
+
+  it("DECLARE @x := 1 (no body) is a no-op (parser error, not a SELECT)", () => {
+    const sql = "DECLARE @x := 1"
+    expect(prependGlobalsDeclare(sql, vars({ y: "2" }))).toEqual({
+      sql,
+      insertedRange: null,
+    })
+  })
+
+  it("CREATE TABLE AS is a no-op (phase-1 fallback)", () => {
+    const sql = "CREATE TABLE foo AS (DECLARE @x := 99 SELECT @x)"
+    expect(prependGlobalsDeclare(sql, vars({ x: "1" }))).toEqual({
+      sql,
+      insertedRange: null,
+    })
+  })
+
+  it("UPDATE / DROP / ALTER / SHOW: all no-ops", () => {
+    for (const sql of [
+      "UPDATE t SET v = 1",
+      "DROP TABLE t",
+      "ALTER TABLE t ADD COLUMN c INT",
+      "SHOW TABLES",
+    ]) {
+      expect(prependGlobalsDeclare(sql, vars({ x: "1" }))).toEqual({
+        sql,
+        insertedRange: null,
+      })
+    }
+  })
+
+  it("drops globals with invalid identifier names without affecting valid ones", () => {
+    const { sql, insertedRange } = prependGlobalsDeclare(
+      "SELECT @x, @good FROM t",
+      vars({ x: "1", "bad-name": "2", good: "3" }),
+    )
+    expect(sql).toBe(
+      "DECLARE\n  @x := 1,\n  @good := 3\nSELECT @x, @good FROM t",
+    )
+    expect(insertedRange?.delta).toBeGreaterThan(0)
+  })
+
+  it("insertedRange.delta matches the actual byte difference", () => {
+    const original = "SELECT @x"
+    const { sql, insertedRange } = prependGlobalsDeclare(
+      original,
+      vars({ x: "1" }),
+    )
+    expect(sql.length - original.length).toBe(insertedRange?.delta)
+  })
+
+  it("does not substitute @x in string literals or comments (server resolves it)", () => {
+    // We don't do substitution anymore — the server handles @x reference resolution.
+    // Just confirm we don't accidentally rewrite comments / string literals.
+    const { sql } = prependGlobalsDeclare(
+      "SELECT @x, 'has @x in string', /* @x in comment */ @x",
+      vars({ x: "1" }),
+    )
+    expect(sql).toContain("'has @x in string'")
+    expect(sql).toContain("/* @x in comment */")
+  })
+})
+
+describe("validateVariableShape", () => {
+  it("accepts a plain integer literal", () => {
+    expect(validateVariableShape({ name: "x", value: "1" })).toBeNull()
+  })
+
+  it("accepts a function call value", () => {
+    expect(validateVariableShape({ name: "from", value: "now()" })).toBeNull()
+  })
+
+  it("accepts a string literal value", () => {
+    expect(validateVariableShape({ name: "symbol", value: "'BTC'" })).toBeNull()
+  })
+
+  it("accepts a value referencing another @variable", () => {
+    expect(
+      validateVariableShape({ name: "derived", value: "@base + 1" }),
+    ).toBeNull()
+  })
+
+  it("accepts parenthesised commas (row expression)", () => {
+    expect(validateVariableShape({ name: "x", value: "(1, 2)" })).toBeNull()
+  })
+
+  it("accepts a string literal containing := and ,", () => {
+    expect(
+      validateVariableShape({ name: "x", value: "'a := b, c'" }),
+    ).toBeNull()
+  })
+
+  it("rejects multi-assignment injection via top-level comma", () => {
+    const err = validateVariableShape({
+      name: "x",
+      value: "1, @evil := 999",
+    })
+    expect(err).toEqual({ kind: "count", actual: 2 })
+  })
+
+  it("rejects multi-assignment injection with newlines", () => {
+    const err = validateVariableShape({
+      name: "x",
+      value: "1,\n  @evil := 999",
+    })
+    expect(err).toEqual({ kind: "count", actual: 2 })
+  })
+
+  it("rejects multi-assignment injection with a subquery payload", () => {
+    const err = validateVariableShape({
+      name: "x",
+      value: "1, @api_key := (select 1)",
+    })
+    expect(err).toEqual({ kind: "count", actual: 2 })
+  })
+
+  it("rejects an empty value", () => {
+    const err = validateVariableShape({ name: "x", value: "" })
+    expect(err).not.toBeNull()
+  })
+
+  it("rejects an invalid variable name", () => {
+    const err = validateVariableShape({ name: "bad-name", value: "1" })
+    expect(err).toEqual({ kind: "parse" })
+  })
+})
+
+describe("mapWireErrorPosition", () => {
+  const range = { start: 10, end: 30, delta: 20 }
+
+  it("passes a position before the insertion point straight through", () => {
+    // Given a wire error positioned before the injected DECLARE block
+    // When mapped
+    // Then the original position is returned unchanged
+    expect(mapWireErrorPosition(range, 4)).toEqual({
+      kind: "passthrough",
+      position: 4,
+    })
+  })
+
+  it("clamps a position inside the DECLARE block to the block start", () => {
+    // Given a wire error landing within the injected block
+    // When mapped
+    // Then it is clamped to the block start and flagged as in-block
+    expect(mapWireErrorPosition(range, 20)).toEqual({
+      kind: "inDeclareBlock",
+      position: 10,
+    })
+  })
+
+  it("shifts a position after the DECLARE block back by delta", () => {
+    // Given a wire error positioned after the injected block
+    // When mapped
+    // Then it is shifted back into user-SQL coordinates by delta
+    expect(mapWireErrorPosition(range, 35)).toEqual({
+      kind: "shifted",
+      position: 15,
+    })
+  })
+
+  it("treats position === start as inside the block (lower boundary)", () => {
+    // Given a wire error exactly at the block start
+    // When mapped
+    // Then it is treated as inside the block, not as passthrough
+    expect(mapWireErrorPosition(range, 10)).toEqual({
+      kind: "inDeclareBlock",
+      position: 10,
+    })
+  })
+
+  it("treats position === end as after the block (upper boundary)", () => {
+    // Given a wire error exactly at the block end
+    // When mapped
+    // Then it is shifted, since end is exclusive for the in-block range
+    expect(mapWireErrorPosition(range, 30)).toEqual({
+      kind: "shifted",
+      position: 10,
+    })
+  })
+
+  it("treats position === end-1 as inside the block (last in-block offset)", () => {
+    // Given a wire error one position before the block end
+    // When mapped
+    // Then it is still inside the block
+    expect(mapWireErrorPosition(range, 29)).toEqual({
+      kind: "inDeclareBlock",
+      position: 10,
+    })
+  })
+})
diff --git a/src/scenes/Editor/Notebook/declareUtils.ts b/src/scenes/Editor/Notebook/declareUtils.ts
new file mode 100644
index 000000000..52a04b83d
--- /dev/null
+++ b/src/scenes/Editor/Notebook/declareUtils.ts
@@ -0,0 +1,347 @@
+import { parse, tokenize } from "@questdb/sql-parser"
+import type { CstNode, IToken } from "@chevrotain/types"
+import type { NotebookVariable } from "../../../store/notebook"
+
+const NAME_RE = /^[a-zA-Z\u0080-\uFFFF_][a-zA-Z0-9\u0080-\uFFFF_]*$/
+
+export const isValidVariableName = (name: string): boolean => NAME_RE.test(name)
+
+const isVariableLike = (value: unknown): value is NotebookVariable => {
+  if (!value || typeof value !== "object") return false
+  const candidate = value as { name?: unknown; value?: unknown }
+  return (
+    typeof candidate.name === "string" && typeof candidate.value === "string"
+  )
+}
+
+export const normalizeVariables = (raw: unknown): NotebookVariable[] => {
+  if (Array.isArray(raw)) {
+    return raw.flatMap((v) =>
+      isVariableLike(v) ? [{ name: v.name, value: v.value }] : [],
+    )
+  }
+  if (raw && typeof raw === "object") {
+    return Object.entries(raw).flatMap(([name, value]) =>
+      typeof value === "string" ? [{ name, value }] : [],
+    )
+  }
+  return []
+}
+
+export const expandGlobals = (sql: string, globals: unknown): string => {
+  const normalized = normalizeVariables(globals)
+  return normalized.length > 0
+    ? prependGlobalsDeclare(sql, normalized).sql
+    : sql
+}
+
+export const stripLeadingAt = (raw: string): string =>
+  raw.startsWith("@") ? raw.slice(1) : raw
+
+export const renderDeclareBlock = (variables: NotebookVariable[]): string => {
+  const valid = variables.filter(({ name }) => isValidVariableName(name))
+  if (valid.length === 0) return ""
+  const lines = valid.map(({ name, value }) => `  @${name} := ${value}`)
+  return `DECLARE\n${lines.join(",\n")}`
+}
+
+export const renderDeclareValidationQuery = (
+  variables: NotebookVariable[],
+): string => {
+  const block = renderDeclareBlock(variables)
+  return block ? `${block}\nSELECT 1` : "SELECT 1"
+}
+
+const isToken = (n: CstNode | IToken): n is IToken =>
+  (n as IToken).image !== undefined
+
+const findFirstNode = (root: CstNode, name: string): CstNode | null => {
+  if (root.name === name) return root
+  const children = root.children
+  for (const key of Object.keys(children)) {
+    for (const child of children[key]) {
+      if (isToken(child)) continue
+      const found = findFirstNode(child, name)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+const subtreeRange = (node: CstNode): { start: number; end: number } | null => {
+  let start = Infinity
+  let end = -1
+  const visit = (n: CstNode): void => {
+    for (const key of Object.keys(n.children)) {
+      for (const child of n.children[key]) {
+        if (isToken(child)) {
+          if (child.startOffset < start) start = child.startOffset
+          const ce = child.endOffset ?? child.startOffset
+          if (ce > end) end = ce
+        } else {
+          visit(child)
+        }
+      }
+    }
+  }
+  visit(node)
+  return end < 0 ? null : { start, end }
+}
+
+type UserDeclareAssignment = {
+  name: string
+  originalText: string
+}
+
+type LeadingDeclareInfo = {
+  assignments: UserDeclareAssignment[]
+  hasInvalidAssignment: boolean
+  blockStart: number
+  bodyStart: number
+}
+
+const extractLeadingDeclare = (text: string): LeadingDeclareInfo | null => {
+  const { cst } = parse(text)
+  if (!cst) return null
+
+  const decl = findFirstNode(cst, "declareClause")
+  if (!decl) return null
+
+  const range = subtreeRange(decl)
+  if (!range) return null
+
+  const assignments: UserDeclareAssignment[] = []
+  let hasInvalidAssignment = false
+  const rawAssignments = decl.children.declareAssignment ?? []
+  for (const a of rawAssignments) {
+    if (isToken(a)) continue
+    const aRange = subtreeRange(a)
+    if (!aRange) {
+      hasInvalidAssignment = true
+      continue
+    }
+    const nameTok = a.children.VariableReference?.[0] as IToken | undefined
+    const exprNode = a.children.expression?.[0] as CstNode | undefined
+    const hasColonEquals = Boolean(a.children.ColonEquals)
+    if (!nameTok || !exprNode || !hasColonEquals) {
+      hasInvalidAssignment = true
+      continue
+    }
+    const name = nameTok.image.slice(1)
+    if (!isValidVariableName(name)) {
+      hasInvalidAssignment = true
+      continue
+    }
+    assignments.push({
+      name,
+      originalText: text.slice(aRange.start, aRange.end + 1),
+    })
+  }
+  return {
+    assignments,
+    hasInvalidAssignment,
+    blockStart: range.start,
+    bodyStart: range.end + 1,
+  }
+}
+
+export const parseDeclareBlock = (text: string): NotebookVariable[] => {
+  const info = extractLeadingDeclare(text)
+  if (!info) return []
+  const out: NotebookVariable[] = []
+  for (const a of info.assignments) {
+    // Strip leading OVERRIDABLE for the map-style consumer (popover etc.).
+    const eqIdx = a.originalText.indexOf(":=")
+    if (eqIdx < 0) continue
+    out.push({ name: a.name, value: a.originalText.slice(eqIdx + 2).trim() })
+  }
+  return out
+}
+
+export type VariableShapeError =
+  | { kind: "parse" }
+  | { kind: "count"; actual: number }
+  | { kind: "name"; expected: string; actual: string }
+  | { kind: "value"; expected: string; actual: string }
+
+export const validateVariableShape = (
+  variable: NotebookVariable,
+): VariableShapeError | null => {
+  if (!isValidVariableName(variable.name)) return { kind: "parse" }
+  const block = renderDeclareBlock([variable])
+  const info = extractLeadingDeclare(block)
+  if (!info || info.hasInvalidAssignment) return { kind: "parse" }
+  if (info.assignments.length !== 1) {
+    return { kind: "count", actual: info.assignments.length }
+  }
+  const a = info.assignments[0]
+  if (a.name !== variable.name) {
+    return { kind: "name", expected: variable.name, actual: a.name }
+  }
+  const expectedText = `@${variable.name} := ${variable.value.trim()}`
+  if (a.originalText.trim() !== expectedText) {
+    return {
+      kind: "value",
+      expected: expectedText,
+      actual: a.originalText.trim(),
+    }
+  }
+  return null
+}
+
+export type InsertedRange = { start: number; end: number; delta: number }
+
+export type PreparedSql = {
+  sql: string
+  // Information about the rewrite, or null if no rewrite happened.
+  insertedRange: InsertedRange | null
+}
+
+export type WireErrorPosition =
+  | { kind: "passthrough"; position: number }
+  | { kind: "inDeclareBlock"; position: number }
+  | { kind: "shifted"; position: number }
+
+export const mapWireErrorPosition = (
+  range: InsertedRange,
+  wirePosition: number,
+): WireErrorPosition => {
+  if (wirePosition < range.start) {
+    return { kind: "passthrough", position: wirePosition }
+  }
+  if (wirePosition < range.end) {
+    return { kind: "inDeclareBlock", position: range.start }
+  }
+  return { kind: "shifted", position: wirePosition - range.delta }
+}
+
+const NO_OP = (sql: string): PreparedSql => ({ sql, insertedRange: null })
+
+const renderMergedDeclare = (
+  globals: NotebookVariable[],
+  userAssignments: UserDeclareAssignment[],
+): string => {
+  const validGlobalLines = globals
+    .filter(({ name }) => isValidVariableName(name))
+    .map(({ name, value }) => `  @${name} := ${value}`)
+  const userLines = userAssignments.map((a) => `  ${a.originalText}`)
+  const lines = [...validGlobalLines, ...userLines]
+  if (lines.length === 0) return ""
+  return `DECLARE\n${lines.join(",\n")}`
+}
+
+type StatementShape =
+  | { kind: "select" }
+  | { kind: "leadingDeclare"; info: LeadingDeclareInfo }
+  | { kind: "skip" }
+
+const analyzeStatement = (text: string): StatementShape => {
+  const r = parse(text)
+  // Any parse error or recovery-induced multi-statement shape: refuse to
+  // rewrite. The user's broken SQL surfaces server errors directly.
+  if (r.parseErrors.length > 0) return { kind: "skip" }
+  if (!r.cst) return { kind: "skip" }
+  const stmtChildren = (r.cst.children.statement ?? []).filter(
+    (s): s is CstNode => !isToken(s),
+  )
+  if (stmtChildren.length !== 1) return { kind: "skip" }
+  const stmt = stmtChildren[0]
+
+  if (stmt.children.selectStatement) {
+    const sel = stmt.children.selectStatement[0]
+    if (isToken(sel) || !sel.children.selectBody) return { kind: "skip" }
+    if (sel.children.declareClause) {
+      const info = extractLeadingDeclare(text)
+      if (!info || info.hasInvalidAssignment) return { kind: "skip" }
+      return { kind: "leadingDeclare", info }
+    }
+    return { kind: "select" }
+  }
+
+  if (stmt.children.withStatement) {
+    const w = stmt.children.withStatement[0]
+    if (isToken(w)) return { kind: "skip" }
+    // WITH … <body>. Only a SELECT body is safe to prepend DECLARE before
+    // (DECLARE grammar is `DECLARE … [WITH …] SELECT …`). WITH … INSERT,
+    // WITH … UPDATE, etc. are valid user SQL but not valid DECLARE targets.
+    if (w.children.selectBody) return { kind: "select" }
+    return { kind: "skip" }
+  }
+
+  // INSERT / CREATE / UPDATE / DELETE / ALTER / DROP / SHOW / TRUNCATE / etc.
+  return { kind: "skip" }
+}
+
+export const prependGlobalsDeclare = (
+  sql: string,
+  globals: NotebookVariable[],
+): PreparedSql => {
+  if (globals.length === 0) return NO_OP(sql)
+
+  const { tokens } = tokenize(sql)
+  if (tokens.length === 0) return NO_OP(sql)
+
+  const first = tokens[0]
+
+  // EXPLAIN is the one form we handle by stripping and recursing — the inner
+  // statement's grammar is what matters (`EXPLAIN DECLARE … SELECT …` is the
+  // only valid shape; `EXPLAIN WITH … INSERT …` is valid user SQL but not a
+  // DECLARE target). The recursive call's analyzer makes that call.
+  if (first.tokenType.name === "Explain") {
+    // QuestDBLexer is configured with `positionTracking: "full"`, so every
+    // token has both startOffset and endOffset as numbers. Asserting `!`
+    // here documents that invariant; the recursion is bounded by sql.length
+    // because suffixStart is always >= 1 (endOffset >= startOffset >= 0).
+    const suffixStart = first.endOffset! + 1
+    const recursed = prependGlobalsDeclare(sql.slice(suffixStart), globals)
+    if (!recursed.insertedRange) return NO_OP(sql)
+    return {
+      sql: sql.slice(0, suffixStart) + recursed.sql,
+      insertedRange: {
+        start: suffixStart + recursed.insertedRange.start,
+        end: suffixStart + recursed.insertedRange.end,
+        delta: recursed.insertedRange.delta,
+      },
+    }
+  }
+
+  const shape = analyzeStatement(sql)
+  if (shape.kind === "skip") return NO_OP(sql)
+
+  if (shape.kind === "select") {
+    const valid = globals.filter(({ name }) => isValidVariableName(name))
+    if (valid.length === 0) return NO_OP(sql)
+    const block = renderDeclareBlock(valid) + "\n"
+    return {
+      sql:
+        sql.slice(0, first.startOffset) + block + sql.slice(first.startOffset),
+      insertedRange: {
+        start: first.startOffset,
+        end: first.startOffset + block.length,
+        delta: block.length,
+      },
+    }
+  }
+
+  // shape.kind === "leadingDeclare"
+  const { info } = shape
+  const userNames = new Set(info.assignments.map((a) => a.name))
+  const filtered = globals.filter(
+    ({ name }) => isValidVariableName(name) && !userNames.has(name),
+  )
+  if (filtered.length === 0) return NO_OP(sql)
+  const newBlock = renderMergedDeclare(filtered, info.assignments)
+  const originalBlock = sql.slice(info.blockStart, info.bodyStart)
+  return {
+    sql: sql.slice(0, info.blockStart) + newBlock + sql.slice(info.bodyStart),
+    insertedRange: {
+      start: info.blockStart,
+      // `end` covers the full wire DECLARE block (globals + user locals).
+      // We can't back-map inside this range uniformly because we may have
+      // rewritten the inter-assignment separators; treat any error inside
+      // as "in DECLARE block" and only shift positions AFTER it.
+      end: info.blockStart + newBlock.length,
+      delta: newBlock.length - originalBlock.length,
+    },
+  }
+}
diff --git a/src/scenes/Editor/Notebook/globals/VariablesPopover.tsx b/src/scenes/Editor/Notebook/globals/VariablesPopover.tsx
new file mode 100644
index 000000000..94e8a9faa
--- /dev/null
+++ b/src/scenes/Editor/Notebook/globals/VariablesPopover.tsx
@@ -0,0 +1,676 @@
+import React, {
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react"
+import styled from "styled-components"
+import {
+  AtIcon,
+  ClipboardTextIcon,
+  DotsSixVerticalIcon,
+  PlusIcon,
+  XIcon,
+} from "@phosphor-icons/react"
+import { CheckboxCircle } from "@styled-icons/remix-fill"
+import { Button, Popover } from "../../../../components"
+import { CopyButton } from "../../../../components/CopyButton"
+import { Input } from "../../../../components/Input"
+import { toast } from "../../../../components/Toast"
+import { QuestContext } from "../../../../providers/QuestProvider"
+import { color } from "../../../../utils"
+import {
+  canReadFromClipboard,
+  readFromClipboard,
+} from "../../../../utils/copyToClipboard"
+import type { NotebookVariable } from "../../../../store/notebook"
+import { signalUserEdit } from "../../../../utils/notebookAIBridge"
+import { useNotebookActions, useNotebookState } from "../NotebookProvider"
+import {
+  isValidVariableName,
+  normalizeVariables,
+  parseDeclareBlock,
+  renderDeclareBlock,
+  renderDeclareValidationQuery,
+  stripLeadingAt,
+  validateVariableShape,
+} from "../declareUtils"
+
+const Trigger = styled(Button).attrs({ skin: "secondary" })`
+  svg {
+    transform: translateY(1px);
+  }
+`
+
+const Body = styled.div`
+  display: flex;
+  flex-direction: column;
+  width: min(56rem, calc(100vw - 4rem));
+  background: ${color("backgroundDarker")};
+`
+
+const Subtitle = styled.div`
+  font-size: 1.4rem;
+  padding: 1.2rem 1.6rem 0;
+  color: ${color("pinkLighter")};
+  font-family: ${({ theme }) => theme.fontMonospace};
+`
+
+const SubtitleStrong = styled.span`
+  font-family: ${({ theme }) => theme.fontMonospace};
+  color: ${color("foreground")};
+`
+
+const RowList = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 0.6rem;
+  padding: 1rem 1.6rem;
+  max-height: 40vh;
+  overflow-y: auto;
+`
+
+const Row = styled.div<{ $dragging?: boolean; $dragInProgress?: boolean }>`
+  display: grid;
+  grid-template-columns: auto auto 14rem auto 1fr auto;
+  gap: 0.6rem;
+  align-items: center;
+  padding: 0.2rem 0.4rem;
+  margin: 0 -0.4rem;
+  border-radius: 0.4rem;
+  border-left: 2px solid transparent;
+  transition:
+    background-color 0.12s ease,
+    opacity 0.12s ease,
+    border-color 0.12s ease,
+    box-shadow 0.12s ease;
+
+  ${({ $dragging, theme }) =>
+    $dragging &&
+    `
+    opacity: 0.55;
+    background-color: ${theme.color.backgroundDarker};
+    border-left-color: ${theme.color.pink};
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.35);
+  `}
+
+  /* Reveal the handle on hover */
+  &:hover [data-hook="drag-handle"] {
+    opacity: 1;
+  }
+
+  /* While any drag is in flight, keep all handles fully visible so the user
+     can see exactly where they're about to drop. */
+  ${({ $dragInProgress }) =>
+    $dragInProgress && `& [data-hook="drag-handle"] { opacity: 1; }`}
+`
+
+const DragHandle = styled.button.attrs({ "data-hook": "drag-handle" })`
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.8rem;
+  height: 2.4rem;
+  padding: 0;
+  border: 0;
+  border-radius: 0.4rem;
+  background: transparent;
+  color: ${color("gray2")};
+  cursor: grab;
+  opacity: 0.35;
+  transition:
+    opacity 0.15s ease,
+    color 0.15s ease,
+    background-color 0.15s ease,
+    transform 0.1s ease;
+
+  &:hover {
+    color: ${color("foreground")};
+    background: ${color("selection")};
+    transform: scale(1.08);
+  }
+
+  &:active {
+    cursor: grabbing;
+    transform: scale(0.96);
+    background: ${color("backgroundDarker")};
+  }
+
+  &:focus-visible {
+    outline: 2px solid ${color("pink")};
+    outline-offset: 1px;
+    opacity: 1;
+  }
+`
+
+const AtLabel = styled.span`
+  font-family: ${({ theme }) => theme.fontMonospace};
+  color: ${color("purple")};
+  font-size: 1.4rem;
+  user-select: none;
+`
+
+const AssignSymbol = styled.span`
+  font-family: ${({ theme }) => theme.fontMonospace};
+  color: ${color("pinkLighter")};
+  font-size: 1.4rem;
+  user-select: none;
+`
+
+const NameInput = styled(Input)`
+  font-family: ${({ theme }) => theme.fontMonospace};
+  font-size: 1.3rem;
+`
+
+const ValueInput = styled(Input)`
+  font-family: ${({ theme }) => theme.fontMonospace};
+  font-size: 1.3rem;
+`
+
+const DeleteButton = styled(Button).attrs({ skin: "transparent" })`
+  padding: 0.4rem;
+  color: ${color("gray2")};
+`
+
+const AddRow = styled.div`
+  padding: 0 1.6rem 1rem;
+`
+
+const Footer = styled.div`
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 1rem 1.6rem 1.2rem;
+  border-top: 1px solid ${color("background")};
+  gap: 0.8rem;
+`
+
+const FooterLeft = styled.div`
+  display: flex;
+  gap: 0.8rem;
+  align-items: center;
+`
+
+const FooterRight = styled.div`
+  display: flex;
+  gap: 0.8rem;
+  align-items: center;
+`
+
+const AddButton = styled(Button).attrs({
+  skin: "transparent",
+  prefixIcon: <PlusIcon size={14} />,
+})``
+
+const ImportButton = styled(Button)`
+  position: relative;
+`
+
+const ImportedTick = styled(CheckboxCircle)`
+  position: absolute;
+  top: 0;
+  right: 0;
+  transform: translate(50%, -50%);
+  color: ${({ theme }) => theme.color.green};
+`
+
+const InlineHint = styled.div`
+  font-size: 1.2rem;
+  color: ${color("red")};
+  padding-left: 2.4rem;
+  grid-column: 3 / span 4;
+`
+
+type Draft = {
+  key: string
+  name: string
+  value: string
+  // One-shot "@-was-stripped" hint per row.
+  showStripHint?: boolean
+}
+
+let DRAFT_KEY = 0
+const newKey = () => `v${++DRAFT_KEY}`
+
+const draftsFromVariables = (vars: unknown): Draft[] => {
+  const normalized = normalizeVariables(vars)
+  if (normalized.length === 0) return [{ key: newKey(), name: "", value: "" }]
+  return normalized.map(({ name, value }) => ({ key: newKey(), name, value }))
+}
+
+const isDuplicate = (drafts: Draft[], idx: number): boolean => {
+  const name = drafts[idx].name
+  if (!name) return false
+  // Flag only the LAST occurrence of a duplicated name. Earlier rows stay
+  // clean; user fixes/removes the most recent conflict.
+  const hasPrior = drafts.slice(0, idx).some((d) => d.name === name)
+  if (!hasPrior) return false
+  const hasLater = drafts.slice(idx + 1).some((d) => d.name === name)
+  return !hasLater
+}
+
+const hasInvalidShape = (draft: Draft): boolean => {
+  if (draft.value === "") return false
+  return (
+    validateVariableShape({ name: draft.name, value: draft.value }) !== null
+  )
+}
+
+const isRowInvalid = (drafts: Draft[], idx: number): boolean => {
+  const d = drafts[idx]
+  if (d.name === "") return false // empty rows are just pending, not invalid
+  if (!isValidVariableName(d.name)) return true
+  if (isDuplicate(drafts, idx)) return true
+  return hasInvalidShape(d)
+}
+
+const buildPersistList = (drafts: Draft[]): NotebookVariable[] => {
+  const seen = new Set<string>()
+  const out: NotebookVariable[] = []
+  for (const d of drafts) {
+    if (!d.name) continue
+    if (!isValidVariableName(d.name)) continue
+    if (seen.has(d.name)) continue
+    seen.add(d.name)
+    out.push({ name: d.name, value: d.value })
+  }
+  return out
+}
+
+const variablesEqual = (
+  a: NotebookVariable[] | undefined,
+  b: NotebookVariable[],
+): boolean => {
+  const aa = a ?? []
+  if (aa.length !== b.length) return false
+  for (let i = 0; i < b.length; i += 1) {
+    if (aa[i].name !== b[i].name || aa[i].value !== b[i].value) return false
+  }
+  return true
+}
+
+export const VariablesPopover: React.FC = () => {
+  const { quest } = useContext(QuestContext)
+  const { settings } = useNotebookState()
+  const { updateSettings } = useNotebookActions()
+  const [open, setOpen] = useState(false)
+  const [drafts, setDrafts] = useState<Draft[]>([])
+  const [serverErrors, setServerErrors] = useState<Record<string, string>>({})
+  const [validating, setValidating] = useState(false)
+  const [draggingKey, setDraggingKey] = useState<string | null>(null)
+  const [importedFlash, setImportedFlash] = useState(false)
+  const importedTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const draggingKeyRef = useRef<string | null>(null)
+  const cancelledRef = useRef(false)
+
+  useEffect(
+    () => () => {
+      if (importedTimeoutRef.current) clearTimeout(importedTimeoutRef.current)
+    },
+    [],
+  )
+
+  useEffect(() => {
+    if (open) setDrafts(draftsFromVariables(settings.variables))
+  }, [open])
+
+  const handleAdd = useCallback(() => {
+    const key = newKey()
+    setDrafts((prev) => [...prev, { key, name: "", value: "" }])
+  }, [])
+
+  const handleDelete = useCallback((idx: number) => {
+    setDrafts((prev) => prev.filter((_, i) => i !== idx))
+    setServerErrors({})
+  }, [])
+
+  const moveDraftToIndex = useCallback((key: string, toIndex: number) => {
+    setDrafts((prev) => {
+      const idx = prev.findIndex((d) => d.key === key)
+      if (idx < 0) return prev
+      const clamped = Math.max(0, Math.min(toIndex, prev.length))
+      const adjusted = idx < clamped ? clamped - 1 : clamped
+      if (idx === adjusted) return prev
+      const next = prev.slice()
+      const [moved] = next.splice(idx, 1)
+      next.splice(adjusted, 0, moved)
+      return next
+    })
+    setServerErrors({})
+  }, [])
+
+  const handleDragStart = useCallback(
+    (e: React.DragEvent<HTMLButtonElement>, key: string) => {
+      draggingKeyRef.current = key
+      setDraggingKey(key)
+      e.dataTransfer.effectAllowed = "move"
+      e.dataTransfer.setData("text/plain", key)
+    },
+    [],
+  )
+
+  const handleDragOver = useCallback(
+    (e: React.DragEvent<HTMLDivElement>, idx: number) => {
+      const key = draggingKeyRef.current
+      if (!key) return
+      e.preventDefault()
+      e.dataTransfer.dropEffect = "move"
+      const rect = e.currentTarget.getBoundingClientRect()
+      const toIndex = e.clientY > rect.top + rect.height / 2 ? idx + 1 : idx
+      moveDraftToIndex(key, toIndex)
+    },
+    [moveDraftToIndex],
+  )
+
+  const handleDragEnd = useCallback(() => {
+    draggingKeyRef.current = null
+    setDraggingKey(null)
+  }, [])
+
+  const handleNameChange = useCallback((idx: number, raw: string) => {
+    setDrafts((prev) => {
+      const next = prev.slice()
+      const stripped = stripLeadingAt(raw)
+      const showStripHint = raw !== stripped
+      next[idx] = {
+        ...next[idx],
+        name: stripped,
+        showStripHint: showStripHint || next[idx].showStripHint,
+      }
+      return next
+    })
+    setServerErrors({})
+  }, [])
+
+  const handleValueChange = useCallback((idx: number, raw: string) => {
+    setDrafts((prev) => {
+      const next = prev.slice()
+      next[idx] = { ...next[idx], value: raw }
+      return next
+    })
+    setServerErrors({})
+  }, [])
+
+  const handleEnterOnValue = (idx: number) => {
+    const isLast = idx === drafts.length - 1
+    if (isLast) {
+      handleAdd()
+    } else {
+      setDrafts((p) => p.slice())
+    }
+  }
+
+  const validateOnServer = async (
+    list: NotebookVariable[],
+  ): Promise<boolean> => {
+    const nextErrors: Record<string, string> = {}
+    for (let i = 0; i < list.length; i += 1) {
+      const shapeError = validateVariableShape(list[i])
+      if (shapeError) {
+        const draft = drafts.find((d) => d.name === list[i].name)
+        if (draft) {
+          nextErrors[draft.key] =
+            "Value must be a single expression — wrap in parentheses if you need commas."
+        }
+        setServerErrors(nextErrors)
+        return false
+      }
+      const prefix = list.slice(0, i + 1)
+      const result = await quest.validateQuery(
+        renderDeclareValidationQuery(prefix),
+      )
+      if ("error" in result) {
+        const draft = drafts.find((d) => d.name === list[i].name)
+        if (draft) nextErrors[draft.key] = result.error
+        setServerErrors(nextErrors)
+        return false
+      }
+    }
+    setServerErrors({})
+    return true
+  }
+
+  const handleApply = async () => {
+    const list = buildPersistList(drafts)
+    cancelledRef.current = false
+    setValidating(true)
+    try {
+      if (!(await validateOnServer(list))) return
+      if (cancelledRef.current) return
+      if (!variablesEqual(normalizeVariables(settings.variables), list)) {
+        signalUserEdit()
+        updateSettings({ variables: list })
+      }
+      setOpen(false)
+    } finally {
+      setValidating(false)
+    }
+  }
+
+  const handleCancel = () => {
+    cancelledRef.current = true
+    setOpen(false)
+  }
+
+  const handleOpenChange = (next: boolean) => {
+    if (!next) cancelledRef.current = true
+    setOpen(next)
+  }
+
+  const handleImport = async () => {
+    try {
+      const text = await readFromClipboard()
+      const parsed = parseDeclareBlock(text)
+      if (parsed.length === 0) {
+        toast.error("No DECLARE block found in clipboard")
+        return
+      }
+      setDrafts((prev) => {
+        const next = prev.filter((d) => d.name !== "" || d.value !== "")
+        for (const { name, value } of parsed) {
+          const idx = next.findIndex((d) => d.name === name)
+          if (idx >= 0) {
+            next[idx] = { ...next[idx], value }
+          } else {
+            next.push({ key: newKey(), name, value })
+          }
+        }
+        return next.length > 0 ? next : [{ key: newKey(), name: "", value: "" }]
+      })
+      setImportedFlash(true)
+      if (importedTimeoutRef.current) clearTimeout(importedTimeoutRef.current)
+      importedTimeoutRef.current = setTimeout(
+        () => setImportedFlash(false),
+        2000,
+      )
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "Could not read clipboard")
+    }
+  }
+
+  const declareBlock = useMemo(
+    () => renderDeclareBlock(buildPersistList(drafts)),
+    [drafts],
+  )
+
+  const clipboardReadable = useMemo(() => canReadFromClipboard(), [])
+
+  const count = useMemo(
+    () => normalizeVariables(settings.variables).length,
+    [settings.variables],
+  )
+
+  const { canApply, hasInvalid, hasValid } = useMemo(() => {
+    let invalid = false
+    let valid = false
+    for (let i = 0; i < drafts.length; i++) {
+      if (isRowInvalid(drafts, i) || Boolean(serverErrors[drafts[i].key])) {
+        invalid = true
+      } else if (drafts[i].name !== "") valid = true
+    }
+    const list = buildPersistList(drafts)
+    const dirty = !variablesEqual(normalizeVariables(settings.variables), list)
+    return {
+      hasInvalid: invalid,
+      hasValid: valid,
+      canApply: !invalid && dirty,
+    }
+  }, [drafts, serverErrors, settings.variables])
+
+  return (
+    <Popover
+      open={open}
+      onOpenChange={handleOpenChange}
+      align="end"
+      trigger={
+        <Trigger prefixIcon={<AtIcon size={14} />}>
+          Variables
+          {count > 0 ? ` (${count})` : ""}
+        </Trigger>
+      }
+    >
+      <Body>
+        <Subtitle>DECLARE</Subtitle>
+        <RowList>
+          {drafts.map((d, idx) => {
+            const clientInvalid = isRowInvalid(drafts, idx)
+            const serverError = serverErrors[d.key]
+            const invalid = clientInvalid || Boolean(serverError)
+            return (
+              <React.Fragment key={d.key}>
+                <Row
+                  $dragging={draggingKey === d.key}
+                  $dragInProgress={draggingKey !== null}
+                  onDragOver={(e) => handleDragOver(e, idx)}
+                  onDrop={handleDragEnd}
+                >
+                  <DragHandle
+                    type="button"
+                    draggable
+                    title="Drag to reorder"
+                    aria-label={`Drag ${d.name || "variable"} to reorder`}
+                    onDragStart={(e) => handleDragStart(e, d.key)}
+                    onDragEnd={handleDragEnd}
+                  >
+                    <DotsSixVerticalIcon size={15} />
+                  </DragHandle>
+                  <AtLabel>@</AtLabel>
+                  <NameInput
+                    value={d.name}
+                    placeholder="name"
+                    variant={invalid ? "error" : undefined}
+                    autoComplete="off"
+                    spellCheck={false}
+                    onChange={(e) => handleNameChange(idx, e.target.value)}
+                    onKeyDown={(e) => {
+                      if (e.key === "Enter") {
+                        e.preventDefault()
+                        ;(
+                          e.currentTarget.nextElementSibling
+                            ?.nextElementSibling as HTMLInputElement | null
+                        )?.focus()
+                      }
+                    }}
+                  />
+                  <AssignSymbol>:=</AssignSymbol>
+                  <ValueInput
+                    value={d.value}
+                    placeholder="value (e.g. 'string', 95, 1h, now())"
+                    variant={invalid ? "error" : undefined}
+                    autoComplete="off"
+                    spellCheck={false}
+                    onChange={(e) => handleValueChange(idx, e.target.value)}
+                    onKeyDown={(e) => {
+                      if (e.key === "Enter") {
+                        e.preventDefault()
+                        handleEnterOnValue(idx)
+                      }
+                    }}
+                  />
+                  {drafts.length > 1 ? (
+                    <DeleteButton
+                      title="Delete variable"
+                      aria-label="Delete variable"
+                      onClick={() => handleDelete(idx)}
+                    >
+                      <XIcon size={13} />
+                    </DeleteButton>
+                  ) : (
+                    <span />
+                  )}
+                </Row>
+                {d.showStripHint && (
+                  <InlineHint>
+                    <SubtitleStrong>@</SubtitleStrong> is added automatically —
+                    just type the name.
+                  </InlineHint>
+                )}
+                {(invalid || serverError) && d.name !== "" && (
+                  <InlineHint>
+                    {serverError
+                      ? serverError
+                      : isDuplicate(drafts, idx)
+                        ? "Name already used"
+                        : !isValidVariableName(d.name)
+                          ? "Names start with a letter, underscore, or Unicode character; then letters, digits, underscores, or Unicode characters."
+                          : hasInvalidShape(d)
+                            ? "Value must be a single expression — wrap in parentheses if you need commas."
+                            : "Value failed QuestDB validation."}
+                  </InlineHint>
+                )}
+              </React.Fragment>
+            )
+          })}
+        </RowList>
+        <AddRow>
+          <AddButton onClick={handleAdd}>Add variable</AddButton>
+        </AddRow>
+        <Footer>
+          <FooterLeft>
+            <ImportButton
+              skin="secondary"
+              prefixIcon={<ClipboardTextIcon size={16} />}
+              onClick={handleImport}
+              title="Import DECLARE block from clipboard"
+              disabled={!clipboardReadable}
+            >
+              Import from clipboard
+              {importedFlash && <ImportedTick size="14px" />}
+            </ImportButton>
+            <CopyButton
+              text={declareBlock}
+              disabled={!hasValid}
+              disabledTooltip={
+                !hasValid ? "Add at least one variable first" : undefined
+              }
+              title="Copy DECLARE block to clipboard"
+            />
+          </FooterLeft>
+          <FooterRight>
+            <Button skin="secondary" onClick={handleCancel}>
+              Cancel
+            </Button>
+            <Button
+              skin="primary"
+              onClick={handleApply}
+              disabled={!canApply || validating}
+              disabledTooltip={
+                hasInvalid
+                  ? "Fix invalid rows before applying"
+                  : validating
+                    ? "Validating variables"
+                    : !canApply
+                      ? "No changes to apply"
+                      : undefined
+              }
+            >
+              {validating ? "Validating..." : "Apply"}
+            </Button>
+          </FooterRight>
+        </Footer>
+      </Body>
+    </Popover>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/globals/useValidateWithGlobals.ts b/src/scenes/Editor/Notebook/globals/useValidateWithGlobals.ts
new file mode 100644
index 000000000..aa51979ed
--- /dev/null
+++ b/src/scenes/Editor/Notebook/globals/useValidateWithGlobals.ts
@@ -0,0 +1,44 @@
+import { useCallback, useContext } from "react"
+import { QuestContext } from "../../../../providers/QuestProvider"
+import { useNotebookActions } from "../NotebookProvider"
+import {
+  mapWireErrorPosition,
+  normalizeVariables,
+  prependGlobalsDeclare,
+} from "../declareUtils"
+
+// Wraps quest.validateQuery so callers can pass the user's original SQL while
+// the server sees the wire form (with notebook globals injected as a DECLARE
+// block). When the server reports an error position, we translate it back to
+// the original-SQL coordinate system so Monaco markers land on the user's
+// typo, not on our injected DECLARE prefix.
+export const useValidateWithGlobals = () => {
+  const { quest } = useContext(QuestContext)
+  const { getVariables } = useNotebookActions()
+
+  return useCallback(
+    async (sql: string, signal?: AbortSignal) => {
+      const variables = normalizeVariables(getVariables())
+      const prepared =
+        variables.length > 0
+          ? prependGlobalsDeclare(sql, variables)
+          : { sql, insertedRange: null }
+      const result = await quest.validateQuery(prepared.sql, signal)
+      if (!("error" in result) || !prepared.insertedRange) return result
+      const mapped = mapWireErrorPosition(
+        prepared.insertedRange,
+        result.position,
+      )
+      if (mapped.kind === "passthrough") return result
+      if (mapped.kind === "inDeclareBlock") {
+        return {
+          ...result,
+          position: mapped.position,
+          error: `${result.error} (in DECLARE block)`,
+        }
+      }
+      return { ...result, position: mapped.position }
+    },
+    [quest, getVariables],
+  )
+}
diff --git a/src/scenes/Editor/Notebook/index.tsx b/src/scenes/Editor/Notebook/index.tsx
new file mode 100644
index 000000000..eb676c744
--- /dev/null
+++ b/src/scenes/Editor/Notebook/index.tsx
@@ -0,0 +1,741 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import styled, { css } from "styled-components"
+import {
+  ResponsiveGridLayout,
+  useContainerWidth,
+  type EventCallback,
+  type Layout,
+  type LayoutItem,
+  verticalCompactor,
+} from "react-grid-layout"
+import { absoluteStrategy } from "react-grid-layout/core"
+import "react-grid-layout/css/styles.css"
+import "react-resizable/css/styles.css"
+import { useEditor } from "../../../providers/EditorProvider"
+import type { CellLayoutItem } from "../../../store/notebook"
+import { dropLegacyChartConfigs } from "../../../store/notebook"
+import { color } from "../../../utils"
+import {
+  NotebookProvider,
+  useNotebookActions,
+  useNotebookState,
+} from "./NotebookProvider"
+import { Cell } from "./cells/Cell"
+import { MarkdownCell } from "./cells/MarkdownCell"
+import type { NotebookCell } from "../../../store/notebook"
+import { AddCellBottom, AddCellBetween } from "./cells/AddCellButton"
+import { NotebookToolbar } from "./NotebookToolbar"
+import { renderEdgeHandle } from "./resize"
+import {
+  CELL_CHROME_PX,
+  computeCellGridH,
+  defaultBottomHeightFor,
+  DEFAULT_TOP_HEIGHT,
+  generateDefaultLayout as generateDefaultLayoutPure,
+  isDoubleView,
+  isExpectingResult,
+  mergeCellLayout,
+  MIN_BOTTOM_HEIGHT_PX,
+  scaleCellHeights,
+} from "./notebookUtils"
+import { emitUserAction } from "../../../utils/notebookAIBridge"
+import { eventBus } from "../../../modules/EventBus"
+import { EventType } from "../../../modules/EventBus/types"
+import { consumeReveal, getPendingReveal } from "./cellReveal"
+
+const GRID_COLS = 12
+// 10 px row increments — fine enough that `computeCellGridH`'s `Math.ceil`
+// adds at most 9 px of trailing whitespace per cell (vs. 49 px with the
+// previous 50 px rows). Makes drag-resize feel smoother too. All
+// row-unit constants below scale up 5× to keep the same pixel-equivalent
+// defaults and minimums.
+const ROW_HEIGHT = 10
+const DEFAULT_CELL_H = 30 // 30 × 10 = 300 px (was 6 × 50 = 300 px)
+
+const NotebookWrapper = styled.div.attrs({ "data-notebook-root": "true" })`
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  width: 100%;
+  overflow: hidden;
+`
+
+const CellListContainer = styled.div<{ $maximized?: boolean }>`
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  overflow-y: ${({ $maximized }) => ($maximized ? "hidden" : "auto")};
+  padding: ${({ $maximized }) => ($maximized ? "0" : "2rem")};
+  gap: 2rem;
+  background: ${color("midnight")};
+  /* Scroll anchoring fights arrow-key reordering: on a move-up React keeps the
+     focused cell's DOM node in place, the browser anchors to it and adjusts
+     scrollTop so the cell looks frozen while the cells above shuffle. Disabled
+     so the moved cell visibly travels and scrollIntoView can pin it. */
+  overflow-anchor: none;
+`
+
+const CellItem = styled.div<{ $maximized?: boolean }>`
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  ${({ $maximized }) => $maximized && `flex: 1; min-height: 0;`}
+`
+
+type GridCellWrapperProps = React.HTMLAttributes<HTMLDivElement> & {
+  cellId: string
+  focused?: boolean
+}
+const GridCellWrapper = React.forwardRef<HTMLDivElement, GridCellWrapperProps>(
+  ({ children, style, className, cellId, focused, ...rest }, ref) => (
+    <div
+      ref={ref}
+      data-cell-id={cellId}
+      data-cell-focused={focused ? "true" : undefined}
+      style={{
+        ...style,
+        display: "flex",
+        flexDirection: "column",
+        // visible (not hidden) so the resize handle chips, which render as
+        // children here and sit on/outside the cell edge, aren't clipped. The
+        // inner CellWrapper still clips the cell's own content.
+        overflow: "visible",
+      }}
+      className={className}
+      {...rest}
+    >
+      {children}
+    </div>
+  ),
+)
+
+const GridScrollContainer = styled.div<{ $suppressTransitions?: boolean }>`
+  flex: 1;
+  overflow-y: auto;
+  padding: 2rem;
+  background: ${color("midnight")};
+
+  .react-grid-item.react-grid-placeholder {
+    background: ${color("selection")};
+    opacity: 0.25;
+  }
+
+  .react-grid-item {
+    border-radius: 0.4rem;
+  }
+
+  /* A selected cell keeps its corner resize handles visible without hover. */
+  [data-cell-focused="true"] .edge-handle--corner {
+    opacity: 1;
+  }
+
+  /* On first mount, react-grid-layout's items would otherwise animate from
+     their initial state to their computed position/size (the "expanding"
+     glitch). Kill the transition until the layout has settled; it's re-enabled
+     for drag/resize. */
+  ${({ $suppressTransitions }) =>
+    $suppressTransitions &&
+    css`
+      .react-grid-item {
+        transition: none !important;
+      }
+    `}
+`
+
+const renderResizeHandle = renderEdgeHandle
+
+const MIN_CELL_W = 2
+// Minimum grid rows. Sized so the rendered floor is ~editor + chrome
+// (`MIN_EDITOR_HEIGHT 72 + CELL_CHROME_PX 40 ≈ 112 px`), letting the
+// user collapse a cell down to "just the editor". Rendered px for
+// h rows in rgl with our margins = h*rowHeight + (h-1)*marginY
+// = 5*10 + 4*20 = 130 px. Earlier value (20 rows) translated to 580 px
+// once the marginY-aware math landed, which the user reported as an
+// unwanted hard floor in grid mode.
+const MIN_CELL_H = 5
+
+const GRID_MARGIN_X = 20
+const GRID_MARGIN_Y = 20
+const GRID_MARGIN: [number, number] = [GRID_MARGIN_X, GRID_MARGIN_Y]
+const GRID_CONTAINER_PADDING: [number, number] = [0, 0]
+const GRID_BREAKPOINTS = { lg: 0 }
+const GRID_COLS_MAP = { lg: GRID_COLS }
+const DRAG_CONFIG = {
+  enabled: true,
+  handle: ".cell-drag-handle",
+  cancel: "button, a, input, select, textarea, .cell-toolbar",
+}
+const RESIZE_CONFIG = {
+  enabled: true,
+  handles: ["se", "sw", "s", "e", "w"] as const,
+  handleComponent: renderResizeHandle,
+}
+
+const LAYOUT_OPTS = {
+  gridCols: GRID_COLS,
+  defaultCellH: DEFAULT_CELL_H,
+  minW: MIN_CELL_W,
+  minH: MIN_CELL_H,
+}
+
+const generateDefaultLayout = (cells: { id: string }[]): CellLayoutItem[] =>
+  generateDefaultLayoutPure(cells, LAYOUT_OPTS)
+
+const useScrollAddedCellIntoView = (cells: { id: string }[]) => {
+  const prev = React.useRef<Set<string>>(new Set(cells.map((c) => c.id)))
+  useEffect(() => {
+    const added = cells.filter((c) => !prev.current.has(c.id))
+    prev.current = new Set(cells.map((c) => c.id))
+    if (added.length !== 1) return
+    const targetId = added[0].id
+    requestAnimationFrame(() => {
+      document
+        .querySelector<HTMLElement>(
+          `[data-notebook-cell][data-cell-id="${CSS.escape(targetId)}"]`,
+        )
+        ?.scrollIntoView({ block: "nearest", behavior: "smooth" })
+    })
+  }, [cells])
+}
+
+// Restoring a maximized cell re-renders the full list at scrollTop 0; scroll the
+// just-restored cell back into view so the user lands where they left off.
+const useScrollRestoredCellIntoView = (maximizedCellId: string | null) => {
+  const prev = React.useRef<string | null>(maximizedCellId)
+  useEffect(() => {
+    const restoredId = prev.current
+    prev.current = maximizedCellId
+    if (!restoredId || maximizedCellId) return
+    requestAnimationFrame(() => {
+      document
+        .querySelector<HTMLElement>(
+          `[data-notebook-cell][data-cell-id="${CSS.escape(restoredId)}"]`,
+        )
+        ?.scrollIntoView({ block: "nearest" })
+    })
+  }, [maximizedCellId])
+}
+
+const readClientY = (event: Event): number | null => {
+  if ("clientY" in event) return (event as MouseEvent).clientY
+  const touch =
+    (event as TouchEvent).touches?.[0] ??
+    (event as TouchEvent).changedTouches?.[0]
+  return touch ? touch.clientY : null
+}
+
+const EDGE_ZONE_PX = 64
+const MAX_SCROLL_SPEED_PX = 18
+
+const useGridDragAutoScroll = (containerRef: React.RefObject<HTMLElement>) => {
+  const pointerYRef = useRef<number | null>(null)
+  const rafRef = useRef<number | null>(null)
+
+  const stop = useCallback(() => {
+    pointerYRef.current = null
+    if (rafRef.current !== null) {
+      cancelAnimationFrame(rafRef.current)
+      rafRef.current = null
+    }
+  }, [])
+
+  const tick = useCallback(() => {
+    const el = containerRef.current
+    const y = pointerYRef.current
+    if (!el || y === null) {
+      rafRef.current = null
+      return
+    }
+    const rect = el.getBoundingClientRect()
+    const distTop = y - rect.top
+    const distBottom = rect.bottom - y
+    let dy = 0
+    if (distTop < EDGE_ZONE_PX) {
+      dy = -MAX_SCROLL_SPEED_PX * (1 - Math.max(distTop, 0) / EDGE_ZONE_PX)
+    } else if (distBottom < EDGE_ZONE_PX) {
+      dy = MAX_SCROLL_SPEED_PX * (1 - Math.max(distBottom, 0) / EDGE_ZONE_PX)
+    }
+    if (dy !== 0) el.scrollBy(0, dy)
+    rafRef.current = requestAnimationFrame(tick)
+  }, [containerRef])
+
+  const onDragStart = useCallback<EventCallback>(
+    (_l, _o, _n, _p, event) => {
+      pointerYRef.current = readClientY(event)
+      if (rafRef.current === null) rafRef.current = requestAnimationFrame(tick)
+    },
+    [tick],
+  )
+
+  const onDrag = useCallback<EventCallback>((_l, _o, _n, _p, event) => {
+    pointerYRef.current = readClientY(event)
+  }, [])
+
+  useEffect(() => stop, [stop])
+
+  return { onDragStart, onDrag, stop }
+}
+
+// Routes each cell to its kind. The single branch point keeps all three
+// render sites (list, grid, maximized) in sync.
+type CellViewProps = {
+  cell: NotebookCell
+  layoutMode: "list" | "grid"
+  isFocused: boolean
+  isMaximized: boolean
+  isRunning: boolean
+  isHydrating: boolean
+}
+
+const CellView: React.FC<CellViewProps> = (props) =>
+  props.cell.type === "markdown" ? (
+    <MarkdownCell {...props} />
+  ) : (
+    <Cell {...props} />
+  )
+
+const ListLayout: React.FC = () => {
+  const { cells, focusedCellId, maximizedCellId, runningCellIds, isHydrating } =
+    useNotebookState()
+  const { setFocusedCell } = useNotebookActions()
+  useScrollAddedCellIntoView(cells)
+
+  return (
+    <CellListContainer
+      onMouseDown={(e) => {
+        const target = e.target as HTMLElement
+        if (!target.closest("[data-notebook-cell]")) setFocusedCell(null)
+      }}
+    >
+      {cells.map((cell, index) => (
+        <React.Fragment key={cell.id}>
+          <CellItem>
+            <CellView
+              cell={cell}
+              layoutMode="list"
+              isFocused={focusedCellId === cell.id}
+              isMaximized={maximizedCellId === cell.id}
+              isRunning={runningCellIds.has(cell.id)}
+              isHydrating={isHydrating}
+            />
+          </CellItem>
+          {index < cells.length - 1 && <AddCellBetween afterCellId={cell.id} />}
+        </React.Fragment>
+      ))}
+      <AddCellBottom
+        afterCellId={cells.length > 0 ? cells[cells.length - 1].id : undefined}
+      />
+    </CellListContainer>
+  )
+}
+
+const GridLayout: React.FC = () => {
+  const {
+    cells,
+    settings,
+    focusedCellId,
+    maximizedCellId,
+    runningCellIds,
+    isHydrating,
+  } = useNotebookState()
+  const { setFocusedCell, updateSettings, updateCell } = useNotebookActions()
+  const { activeBuffer } = useEditor()
+  // measureBeforeMount: don't render the grid until the container width is
+  // measured, so cells first paint at their real width instead of animating
+  // from the guessed initialWidth (react-grid-layout transitions the change).
+  const {
+    width: containerWidth,
+    containerRef,
+    mounted: gridMeasured,
+  } = useContainerWidth({ measureBeforeMount: true })
+  const autoScroll = useGridDragAutoScroll(
+    containerRef as React.RefObject<HTMLElement>,
+  )
+  useScrollAddedCellIntoView(cells)
+
+  // Suppress react-grid-layout's item transition until the grid has rendered
+  // and the width has settled, so cells don't animate into place on mount.
+  // Two frames cover the initial render + the ResizeObserver's first callback.
+  const [gridReady, setGridReady] = useState(false)
+  useEffect(() => {
+    if (!gridMeasured) return
+    let raf2 = 0
+    const raf1 = requestAnimationFrame(() => {
+      raf2 = requestAnimationFrame(() => setGridReady(true))
+    })
+    return () => {
+      cancelAnimationFrame(raf1)
+      cancelAnimationFrame(raf2)
+    }
+  }, [gridMeasured])
+
+  // Derive each cell's grid h from topHeight + bottomHeight + chrome.
+  // The h value in settings.layout is ignored on read — it's a stale
+  // shadow that only matters when react-grid-layout consumes it. We
+  // recompute every render so a content-driven topHeight or run-driven
+  // bottomHeight change immediately resizes the grid cell.
+  const currentLayout = useMemo<LayoutItem[]>(() => {
+    const base = mergeCellLayout(
+      settings.layout && settings.layout.length > 0
+        ? settings.layout
+        : generateDefaultLayout(cells),
+      cells,
+      LAYOUT_OPTS,
+    ) as LayoutItem[]
+    const cellById = new Map(cells.map((c) => [c.id, c]))
+    return base.map((item) => {
+      const cell = cellById.get(item.i)
+      if (!cell) return item
+      const expectingResult = isExpectingResult(cell, isHydrating)
+      const minBottomPx =
+        isDoubleView(cell) || expectingResult ? MIN_BOTTOM_HEIGHT_PX : 0
+      const minTotalPx = DEFAULT_TOP_HEIGHT + minBottomPx + CELL_CHROME_PX
+      const minH = Math.max(
+        MIN_CELL_H,
+        Math.ceil((minTotalPx + GRID_MARGIN_Y) / (ROW_HEIGHT + GRID_MARGIN_Y)),
+      )
+      return {
+        ...item,
+        h: computeCellGridH(cell, ROW_HEIGHT, GRID_MARGIN_Y, expectingResult),
+        minH,
+      }
+    })
+  }, [settings.layout, cells, isHydrating])
+
+  const mapLayoutXYW = useCallback(
+    (rglLayout: Layout): CellLayoutItem[] =>
+      [...rglLayout]
+        .filter((item: LayoutItem) => cells.some((c) => c.id === item.i))
+        .map((item: LayoutItem) => ({
+          i: item.i,
+          x: item.x,
+          y: item.y,
+          w: item.w,
+          // Persist whatever h react-grid-layout reports; it's recomputed
+          // on next render by computeCellGridH anyway. Keeping it here
+          // means we don't have to special-case the persisted shape.
+          h: item.h,
+        })),
+    [cells],
+  )
+
+  // Drag-stop = move (x/y change). Just persist positions.
+  const handleDragStop = useCallback(
+    (newLayout: Layout, ..._args: unknown[]) => {
+      autoScroll.stop()
+      updateSettings({ layout: mapLayoutXYW(newLayout) })
+      if (typeof activeBuffer.id === "number") {
+        emitUserAction({
+          kind: "user_changed_grid_layout",
+          bufferId: activeBuffer.id,
+        })
+      }
+    },
+    [autoScroll, mapLayoutXYW, updateSettings, activeBuffer.id],
+  )
+
+  const handleResizeStop = useCallback(
+    (newLayout: Layout, ..._args: unknown[]) => {
+      updateSettings({ layout: mapLayoutXYW(newLayout) })
+      const cellById = new Map(cells.map((c) => [c.id, c]))
+      for (const item of newLayout) {
+        const cell = cellById.get(item.i)
+        if (!cell) continue
+        const derivedH = computeCellGridH(cell, ROW_HEIGHT, GRID_MARGIN_Y)
+        if (item.h === derivedH) continue
+        // Rendered px for an h-row cell is `h*rowHeight + (h-1)*marginY`,
+        // accounting for the inter-row gaps react-grid-layout inserts.
+        // Plain `h * rowHeight` is too small and made the resulting
+        // bottomHeight ~marginY-per-row shorter than the user dragged.
+        const rowsToPx = (h: number) => h * ROW_HEIGHT + (h - 1) * GRID_MARGIN_Y
+        const targetTotalPx = rowsToPx(item.h)
+        if (isDoubleView(cell)) {
+          const { top: nextTop, bottom: nextBottom } = scaleCellHeights(
+            cell.topHeight ?? DEFAULT_TOP_HEIGHT,
+            cell.bottomHeight ?? defaultBottomHeightFor(cell),
+            targetTotalPx - CELL_CHROME_PX,
+            DEFAULT_TOP_HEIGHT,
+            MIN_BOTTOM_HEIGHT_PX,
+          )
+          updateCell(cell.id, {
+            topHeight: nextTop,
+            bottomHeight: nextBottom,
+            topResized: true,
+          })
+        } else {
+          // Single-view: no bottom slot — south drag grows the editor.
+          // Mark topResized so Monaco's content-driven auto-grow stops
+          // snapping the cell back to MIN_EDITOR_HEIGHT after the user's
+          // drag. Without this, the dragged size only lingered in rgl's
+          // internal state and disappeared on the next layouts-prop
+          // reconciliation (e.g. when another cell was added).
+          const nextTopHeight = Math.max(
+            DEFAULT_TOP_HEIGHT,
+            targetTotalPx - CELL_CHROME_PX,
+          )
+          updateCell(cell.id, {
+            topHeight: nextTopHeight,
+            topResized: true,
+          })
+        }
+      }
+      if (typeof activeBuffer.id === "number") {
+        emitUserAction({
+          kind: "user_changed_grid_layout",
+          bufferId: activeBuffer.id,
+        })
+      }
+    },
+    [mapLayoutXYW, updateSettings, updateCell, cells, activeBuffer.id],
+  )
+
+  useEffect(() => {
+    const handler = (payload?: {
+      cellId?: string
+      kind?: "full" | "right" | "left"
+    }) => {
+      const cellId = payload?.cellId
+      const kind = payload?.kind
+      if (!cellId || !kind) return
+      const cur = currentLayout.find((l) => l.i === cellId)
+      if (!cur) return
+      let nextX = cur.x
+      let nextW = cur.w
+      if (kind === "full") {
+        nextX = 0
+        nextW = GRID_COLS
+      } else if (kind === "right") {
+        nextW = GRID_COLS - cur.x
+      } else if (kind === "left") {
+        nextX = 0
+        nextW = cur.x + cur.w
+      }
+      if (nextX === cur.x && nextW === cur.w) return
+      const nextLayout: CellLayoutItem[] = currentLayout.map((l) =>
+        l.i === cellId
+          ? { i: l.i, x: nextX, y: l.y, w: nextW, h: l.h }
+          : { i: l.i, x: l.x, y: l.y, w: l.w, h: l.h },
+      )
+      updateSettings({ layout: nextLayout })
+      if (typeof activeBuffer.id === "number") {
+        emitUserAction({
+          kind: "user_changed_grid_layout",
+          bufferId: activeBuffer.id,
+        })
+      }
+    }
+    eventBus.subscribe(EventType.NOTEBOOK_CELL_EXPAND_WIDTH, handler)
+    return () =>
+      eventBus.unsubscribe(EventType.NOTEBOOK_CELL_EXPAND_WIDTH, handler)
+  }, [currentLayout, updateSettings, activeBuffer.id])
+
+  return (
+    <GridScrollContainer
+      ref={containerRef as React.RefObject<HTMLDivElement>}
+      $suppressTransitions={!gridReady}
+      onMouseDown={(e) => {
+        const target = e.target as HTMLElement
+        const gridItem = target.closest<HTMLElement>("[data-cell-id]")
+        if (gridItem?.dataset.cellId) {
+          setFocusedCell(gridItem.dataset.cellId)
+        } else {
+          setFocusedCell(null)
+        }
+      }}
+    >
+      {/* No `key` on ResponsiveGridLayout: keying it on cellIds would
+       * unmount every Cell/DrawCanvas on add/remove and wipe chart state.
+       * rgl reconciles children by their own key matched against
+       * layouts.lg[].i. */}
+      {gridMeasured && (
+        <ResponsiveGridLayout
+          width={containerWidth}
+          layouts={{ lg: currentLayout as unknown as Layout }}
+          breakpoints={GRID_BREAKPOINTS}
+          cols={GRID_COLS_MAP}
+          rowHeight={ROW_HEIGHT}
+          margin={GRID_MARGIN}
+          containerPadding={GRID_CONTAINER_PADDING}
+          dragConfig={DRAG_CONFIG}
+          resizeConfig={RESIZE_CONFIG}
+          compactor={verticalCompactor}
+          onDragStart={autoScroll.onDragStart}
+          onDrag={autoScroll.onDrag}
+          onDragStop={handleDragStop}
+          onResizeStop={handleResizeStop}
+          positionStrategy={absoluteStrategy}
+        >
+          {cells.map((cell) => (
+            <GridCellWrapper
+              key={cell.id}
+              cellId={cell.id}
+              focused={focusedCellId === cell.id}
+            >
+              <CellView
+                cell={cell}
+                layoutMode="grid"
+                isFocused={focusedCellId === cell.id}
+                isMaximized={maximizedCellId === cell.id}
+                isRunning={runningCellIds.has(cell.id)}
+                isHydrating={isHydrating}
+              />
+            </GridCellWrapper>
+          ))}
+        </ResponsiveGridLayout>
+      )}
+      <AddCellBottom
+        afterCellId={cells.length > 0 ? cells[cells.length - 1].id : undefined}
+      />
+    </GridScrollContainer>
+  )
+}
+
+const REVEAL_SCROLL_RETRIES = 8
+
+// The cell may not be in the DOM yet on a cold (grid) mount; retry across frames
+// until it appears. A cell that no longer exists (deleted while away) never
+// resolves and is silently skipped once the retries are exhausted.
+const scrollNotebookCellIntoView = (cellId: string, attempt = 0): void => {
+  const node = document.querySelector<HTMLElement>(
+    `[data-notebook-cell][data-cell-id="${CSS.escape(cellId)}"]`,
+  )
+  if (node) {
+    node.scrollIntoView({ block: "center" })
+  } else if (attempt < REVEAL_SCROLL_RETRIES) {
+    requestAnimationFrame(() => scrollNotebookCellIntoView(cellId, attempt + 1))
+  }
+}
+
+const useScrollFocusedCellIntoViewOnOpen = (focusedCellId: string | null) => {
+  const focusedOnOpenRef = useRef(focusedCellId)
+  useEffect(() => {
+    const cellId = focusedOnOpenRef.current
+    if (!cellId || getPendingReveal()) return
+    scrollNotebookCellIntoView(cellId)
+  }, [])
+}
+
+// Scroll + glow the cell a search result points at, drained on mount and on the nudge.
+const useNotebookSearchReveal = () => {
+  const { activeBuffer, isNavigatingFromSearchRef } = useEditor()
+  const { setFocusedCell, setMaximizedCellId, getCellsSnapshot } =
+    useNotebookActions()
+  const { maximizedCellId } = useNotebookState()
+
+  const bufferId = activeBuffer.id
+  const maximizedCellIdRef = useRef(maximizedCellId)
+  useEffect(() => {
+    maximizedCellIdRef.current = maximizedCellId
+  }, [maximizedCellId])
+
+  useEffect(() => {
+    // Monaco/Metrics reset isNavigatingFromSearchRef on mount; notebooks must too.
+    isNavigatingFromSearchRef.current = false
+
+    const applyReveal = () => {
+      const request = getPendingReveal()
+      if (!request || request.bufferId !== bufferId) return
+      if (!getCellsSnapshot().some((cell) => cell.id === request.cellId)) return
+      if (
+        maximizedCellIdRef.current &&
+        maximizedCellIdRef.current !== request.cellId
+      ) {
+        setMaximizedCellId(null)
+      }
+      setFocusedCell(request.cellId)
+      scrollNotebookCellIntoView(request.cellId)
+      // SQL cell matches flash in their own editor (which consumes the request);
+      // markdown/chart matches have no in-editor consumer, so clear here.
+      if (
+        request.notebookField === "chartName" ||
+        request.cellType === "markdown"
+      ) {
+        consumeReveal(request.token)
+      }
+    }
+
+    applyReveal()
+    eventBus.subscribe(EventType.NOTEBOOK_REVEAL_CELL, applyReveal)
+    return () =>
+      eventBus.unsubscribe(EventType.NOTEBOOK_REVEAL_CELL, applyReveal)
+  }, [
+    bufferId,
+    getCellsSnapshot,
+    setFocusedCell,
+    setMaximizedCellId,
+    isNavigatingFromSearchRef,
+  ])
+}
+
+const NotebookContent: React.FC = () => {
+  const {
+    cells,
+    settings,
+    focusedCellId,
+    maximizedCellId,
+    runningCellIds,
+    isHydrating,
+  } = useNotebookState()
+  const layoutMode = settings.layoutMode ?? "list"
+  useScrollRestoredCellIntoView(maximizedCellId)
+  useScrollFocusedCellIntoViewOnOpen(focusedCellId)
+  useNotebookSearchReveal()
+
+  if (cells.length === 0) {
+    return (
+      <NotebookWrapper>
+        <NotebookToolbar />
+        <CellListContainer>
+          <AddCellBottom alignCenter />
+        </CellListContainer>
+      </NotebookWrapper>
+    )
+  }
+
+  const maximizedCell = maximizedCellId
+    ? cells.find((c) => c.id === maximizedCellId)
+    : undefined
+  if (maximizedCell) {
+    const cell = maximizedCell
+    return (
+      <NotebookWrapper>
+        <CellListContainer $maximized>
+          <CellItem $maximized>
+            <CellView
+              cell={cell}
+              layoutMode="list"
+              isFocused={focusedCellId === cell.id}
+              isMaximized
+              isRunning={runningCellIds.has(cell.id)}
+              isHydrating={isHydrating}
+            />
+          </CellItem>
+        </CellListContainer>
+      </NotebookWrapper>
+    )
+  }
+
+  return (
+    <NotebookWrapper>
+      <NotebookToolbar />
+      {layoutMode === "grid" ? <GridLayout /> : <ListLayout />}
+    </NotebookWrapper>
+  )
+}
+
+export const Notebook: React.FC = () => {
+  const { activeBuffer } = useEditor()
+
+  if (!activeBuffer.notebookViewState || !activeBuffer.id) {
+    return null
+  }
+
+  return (
+    <NotebookProvider
+      initialState={dropLegacyChartConfigs(activeBuffer.notebookViewState)}
+      bufferId={activeBuffer.id}
+    >
+      <NotebookContent />
+    </NotebookProvider>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/notebookColumnLayoutStore.test.ts b/src/scenes/Editor/Notebook/notebookColumnLayoutStore.test.ts
new file mode 100644
index 000000000..a6d688968
--- /dev/null
+++ b/src/scenes/Editor/Notebook/notebookColumnLayoutStore.test.ts
@@ -0,0 +1,218 @@
+import { describe, it, expect, beforeEach } from "vitest"
+import {
+  loadNotebookColumnLayout,
+  saveNotebookColumnLayout,
+  removeNotebookColumnLayout,
+  removeNotebookCellLayouts,
+  removeNotebookBufferLayouts,
+} from "./notebookColumnLayoutStore"
+
+// The store reads/writes this single localStorage entry.
+const STORAGE_KEY = "notebook.grid.layout"
+const LRU_MAX = 20
+
+const installMemoryLocalStorage = () => {
+  const store: Record<string, string> = {}
+  globalThis.localStorage = {
+    getItem: (key: string) => store[key] ?? null,
+    setItem: (key: string, value: string) => {
+      store[key] = value
+    },
+    removeItem: (key: string) => {
+      delete store[key]
+    },
+    clear: () => {
+      Object.keys(store).forEach((k) => delete store[k])
+    },
+    key: () => null,
+    length: 0,
+  } as Storage
+}
+
+// Query keys are opaque to the store, but the per-cell LRU relies on
+// insertion order, so callers prefix a non-digit (here "q") to keep keys from
+// sorting as integers.
+const q = (n: number): string => `q${n}`
+
+const CELL = "cell-a"
+const OTHER_CELL = "cell-b"
+
+beforeEach(() => {
+  installMemoryLocalStorage()
+})
+
+describe("notebookColumnLayoutStore", () => {
+  it("round-trips a saved layout for the same buffer, cell, and query", () => {
+    // Given a saved sizing
+    saveNotebookColumnLayout(1, CELL, q(0), { columnSizing: { col_0: 200 } })
+
+    // When loading it back
+    const loaded = loadNotebookColumnLayout(1, CELL, q(0))
+
+    // Then the same layout is returned
+    expect(loaded).toEqual({ columnSizing: { col_0: 200 } })
+  })
+
+  it("merges partial layouts for the same key", () => {
+    // Given a sizing already saved
+    saveNotebookColumnLayout(1, CELL, q(0), { columnSizing: { col_0: 200 } })
+
+    // When an order and pinned set are saved separately for the same key
+    saveNotebookColumnLayout(1, CELL, q(0), { columnOrder: ["col_1", "col_0"] })
+    saveNotebookColumnLayout(1, CELL, q(0), { pinnedColumns: ["col_0"] })
+
+    // Then all three are preserved
+    expect(loadNotebookColumnLayout(1, CELL, q(0))).toEqual({
+      columnSizing: { col_0: 200 },
+      columnOrder: ["col_1", "col_0"],
+      pinnedColumns: ["col_0"],
+    })
+  })
+
+  it("keeps layouts independent across query, cell, and buffer", () => {
+    // Given the same column position sized differently per query/cell/buffer
+    saveNotebookColumnLayout(1, CELL, q(0), { columnSizing: { col_0: 100 } })
+    saveNotebookColumnLayout(1, CELL, q(1), { columnSizing: { col_0: 200 } })
+    saveNotebookColumnLayout(1, OTHER_CELL, q(0), {
+      columnSizing: { col_0: 300 },
+    })
+    saveNotebookColumnLayout(2, CELL, q(0), { columnSizing: { col_0: 400 } })
+
+    // When each is loaded
+    // Then none bleed into another
+    expect(loadNotebookColumnLayout(1, CELL, q(0))).toEqual({
+      columnSizing: { col_0: 100 },
+    })
+    expect(loadNotebookColumnLayout(1, CELL, q(1))).toEqual({
+      columnSizing: { col_0: 200 },
+    })
+    expect(loadNotebookColumnLayout(1, OTHER_CELL, q(0))).toEqual({
+      columnSizing: { col_0: 300 },
+    })
+    expect(loadNotebookColumnLayout(2, CELL, q(0))).toEqual({
+      columnSizing: { col_0: 400 },
+    })
+  })
+
+  it("returns null and skips persistence for an undefined buffer", () => {
+    // Given no buffer id (session-only notebook)
+    // When saving and loading
+    saveNotebookColumnLayout(undefined, CELL, q(0), {
+      columnSizing: { col_0: 100 },
+    })
+
+    // Then nothing is stored or returned
+    expect(loadNotebookColumnLayout(undefined, CELL, q(0))).toBeNull()
+    expect(localStorage.getItem(STORAGE_KEY)).toBeNull()
+  })
+
+  it("removes a single query's layout, leaving its siblings", () => {
+    // Given two queries saved under one cell
+    saveNotebookColumnLayout(1, CELL, q(0), { columnSizing: { col_0: 100 } })
+    saveNotebookColumnLayout(1, CELL, q(1), { columnSizing: { col_0: 200 } })
+
+    // When one is removed
+    removeNotebookColumnLayout(1, CELL, q(0))
+
+    // Then only that one is gone
+    expect(loadNotebookColumnLayout(1, CELL, q(0))).toBeNull()
+    expect(loadNotebookColumnLayout(1, CELL, q(1))).toEqual({
+      columnSizing: { col_0: 200 },
+    })
+  })
+
+  it("drops a whole cell's subtree, leaving other cells", () => {
+    // Given two cells with layouts
+    saveNotebookColumnLayout(1, CELL, q(0), { columnSizing: { col_0: 100 } })
+    saveNotebookColumnLayout(1, CELL, q(1), { columnSizing: { col_0: 150 } })
+    saveNotebookColumnLayout(1, OTHER_CELL, q(0), {
+      columnSizing: { col_0: 200 },
+    })
+
+    // When one cell is deleted
+    removeNotebookCellLayouts(1, CELL)
+
+    // Then its queries are gone and the other cell survives
+    expect(loadNotebookColumnLayout(1, CELL, q(0))).toBeNull()
+    expect(loadNotebookColumnLayout(1, CELL, q(1))).toBeNull()
+    expect(loadNotebookColumnLayout(1, OTHER_CELL, q(0))).toEqual({
+      columnSizing: { col_0: 200 },
+    })
+  })
+
+  it("drops a whole buffer's subtree, leaving other buffers", () => {
+    // Given two buffers with layouts
+    saveNotebookColumnLayout(1, CELL, q(0), { columnSizing: { col_0: 100 } })
+    saveNotebookColumnLayout(2, CELL, q(0), { columnSizing: { col_0: 200 } })
+
+    // When one buffer is deleted
+    removeNotebookBufferLayouts(1)
+
+    // Then its cells are gone and the other buffer survives
+    expect(loadNotebookColumnLayout(1, CELL, q(0))).toBeNull()
+    expect(loadNotebookColumnLayout(2, CELL, q(0))).toEqual({
+      columnSizing: { col_0: 200 },
+    })
+  })
+
+  it("tolerates corrupted storage", () => {
+    // Given a malformed store entry
+    localStorage.setItem(STORAGE_KEY, "{not valid json")
+
+    // When loading
+    // Then it degrades to null instead of throwing
+    expect(() => loadNotebookColumnLayout(1, CELL, q(0))).not.toThrow()
+    expect(loadNotebookColumnLayout(1, CELL, q(0))).toBeNull()
+  })
+
+  it("evicts the least-recently-saved query past the cap, per cell", () => {
+    // Given one more than the cap of distinct queries saved in order
+    for (let i = 0; i <= LRU_MAX; i++) {
+      saveNotebookColumnLayout(1, CELL, q(i), { columnSizing: { col_0: i } })
+    }
+
+    // Then the first is evicted and the last survives
+    expect(loadNotebookColumnLayout(1, CELL, q(0))).toBeNull()
+    expect(loadNotebookColumnLayout(1, CELL, q(LRU_MAX))).toEqual({
+      columnSizing: { col_0: LRU_MAX },
+    })
+  })
+
+  it("bumps recency on re-save so an old query survives eviction", () => {
+    // Given the cap is filled
+    for (let i = 0; i < LRU_MAX; i++) {
+      saveNotebookColumnLayout(1, CELL, q(i), { columnSizing: { col_0: i } })
+    }
+
+    // And the oldest entry is re-saved (becoming most recent)
+    saveNotebookColumnLayout(1, CELL, q(0), { columnSizing: { col_0: 999 } })
+
+    // When one more new query pushes past the cap
+    saveNotebookColumnLayout(1, CELL, q(LRU_MAX), {
+      columnSizing: { col_0: LRU_MAX },
+    })
+
+    // Then the re-saved entry survives and the next-oldest is evicted instead
+    expect(loadNotebookColumnLayout(1, CELL, q(0))).toEqual({
+      columnSizing: { col_0: 999 },
+    })
+    expect(loadNotebookColumnLayout(1, CELL, q(1))).toBeNull()
+  })
+
+  it("scopes the cap per cell, not across the buffer", () => {
+    // Given one cell saves a single layout
+    saveNotebookColumnLayout(1, OTHER_CELL, q(0), {
+      columnSizing: { col_0: 7 },
+    })
+
+    // When a sibling cell is filled past the cap
+    for (let i = 0; i <= LRU_MAX; i++) {
+      saveNotebookColumnLayout(1, CELL, q(i), { columnSizing: { col_0: i } })
+    }
+
+    // Then the lightly-used cell's entry is untouched
+    expect(loadNotebookColumnLayout(1, OTHER_CELL, q(0))).toEqual({
+      columnSizing: { col_0: 7 },
+    })
+  })
+})
diff --git a/src/scenes/Editor/Notebook/notebookColumnLayoutStore.ts b/src/scenes/Editor/Notebook/notebookColumnLayoutStore.ts
new file mode 100644
index 000000000..1b33bf6ea
--- /dev/null
+++ b/src/scenes/Editor/Notebook/notebookColumnLayoutStore.ts
@@ -0,0 +1,87 @@
+import type { ColumnLayout } from "../../../components/ResultGrid/types"
+
+const STORAGE_KEY = "notebook.grid.layout"
+const LRU_MAX = 20
+
+type CellLayouts = Record<string, ColumnLayout>
+type BufferLayouts = Record<string, CellLayouts>
+type LayoutStore = Record<string, BufferLayouts>
+
+const readStore = (): LayoutStore => {
+  try {
+    return JSON.parse(localStorage.getItem(STORAGE_KEY) || "{}") as LayoutStore
+  } catch {
+    return {}
+  }
+}
+
+const writeStore = (store: LayoutStore): void => {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(store))
+  } catch {
+    // ignore quota / serialization errors — persistence is best-effort
+  }
+}
+
+export const loadNotebookColumnLayout = (
+  bufferId: number | undefined,
+  cellId: string,
+  queryKey: string,
+): ColumnLayout | null => {
+  if (bufferId === undefined) return null
+  return readStore()[bufferId]?.[cellId]?.[queryKey] ?? null
+}
+
+export const saveNotebookColumnLayout = (
+  bufferId: number | undefined,
+  cellId: string,
+  queryKey: string,
+  partial: ColumnLayout,
+): void => {
+  if (bufferId === undefined) return
+  const store = readStore()
+  if (!store[bufferId]) store[bufferId] = {}
+  if (!store[bufferId][cellId]) store[bufferId][cellId] = {}
+  const cell = store[bufferId][cellId]
+  const existing = cell[queryKey]
+  // Re-insert last so key order is recency; the caller's queryKey must be
+  // non-integer-like or it sorts first and breaks this LRU.
+  delete cell[queryKey]
+  cell[queryKey] = { ...existing, ...partial }
+  const keys = Object.keys(cell)
+  for (let i = 0; i < keys.length - LRU_MAX; i++) {
+    delete cell[keys[i]]
+  }
+  writeStore(store)
+}
+
+export const removeNotebookColumnLayout = (
+  bufferId: number | undefined,
+  cellId: string,
+  queryKey: string,
+): void => {
+  if (bufferId === undefined) return
+  const store = readStore()
+  const cell = store[bufferId]?.[cellId]
+  if (!cell?.[queryKey]) return
+  delete cell[queryKey]
+  writeStore(store)
+}
+
+export const removeNotebookCellLayouts = (
+  bufferId: number | undefined,
+  cellId: string,
+): void => {
+  if (bufferId === undefined) return
+  const store = readStore()
+  if (!store[bufferId]?.[cellId]) return
+  delete store[bufferId][cellId]
+  writeStore(store)
+}
+
+export const removeNotebookBufferLayouts = (bufferId: number): void => {
+  const store = readStore()
+  if (!store[bufferId]) return
+  delete store[bufferId]
+  writeStore(store)
+}
diff --git a/src/scenes/Editor/Notebook/notebookUtils.test.ts b/src/scenes/Editor/Notebook/notebookUtils.test.ts
new file mode 100644
index 000000000..03e02c976
--- /dev/null
+++ b/src/scenes/Editor/Notebook/notebookUtils.test.ts
@@ -0,0 +1,1633 @@
+import { describe, it, expect } from "vitest"
+import {
+  ApplyNotebookStateError,
+  attachScriptSummary,
+  buildAppliedCells,
+  buildAppliedLayout,
+  buildInitialScriptResults,
+  buildPersistPayload,
+  capResultBytes,
+  cancelAllInCell,
+  cancelOneInCell,
+  cloneNotebookViewState,
+  computeCellGridH,
+  computeResultBottomHeight,
+  duplicateCellAt,
+  generateDefaultLayout,
+  insertCell,
+  isDoubleView,
+  isExpectingResult,
+  isUnverifiableExecError,
+  mergeCellLayout,
+  nextCopyLabel,
+  removeCell,
+  setResultAt,
+  singleResultFromExec,
+  sqlHash,
+  stripCellResults,
+  swapCellDown,
+  swapCellUp,
+} from "./notebookUtils"
+import type {
+  NotebookCell,
+  NotebookViewState,
+  SingleQueryResult,
+} from "../../../store/notebook"
+import { createDefaultNotebookViewState } from "../../../store/notebook"
+import type { QueryExecResult } from "../../../hooks/useQueryExecution"
+
+const cell = (
+  id: string,
+  value = "",
+  result?: NotebookCell["result"],
+): NotebookCell => ({
+  id,
+  position: 0,
+  value,
+  result,
+})
+
+describe("singleResultFromExec", () => {
+  it("maps dql exec to DqlQueryResult preserving columns/dataset/count/timings", () => {
+    const exec: QueryExecResult = {
+      type: "dql",
+      query: "SELECT 1",
+      columns: [{ name: "x", type: "INT" }],
+      dataset: [[1]],
+      count: 1,
+      timings: {
+        compiler: 100,
+        execute: 200,
+        authentication: 10,
+        fetch: 5,
+        count: 1,
+      },
+    }
+    expect(singleResultFromExec(exec, "SELECT 1")).toEqual({
+      type: "dql",
+      query: "SELECT 1",
+      columns: exec.columns,
+      dataset: exec.dataset,
+      count: 1,
+      timings: exec.timings,
+    })
+  })
+
+  it("maps error exec to ErrorQueryResult with error message", () => {
+    const exec: QueryExecResult = {
+      type: "error",
+      query: "SELECT boom",
+      columns: [],
+      dataset: [],
+      count: 0,
+      error: "syntax error",
+    }
+    expect(singleResultFromExec(exec, "SELECT boom")).toEqual({
+      type: "error",
+      query: "SELECT boom",
+      error: "syntax error",
+    })
+  })
+
+  it("falls back to 'Unknown error' when error exec has no message", () => {
+    const exec: QueryExecResult = {
+      type: "error",
+      query: "SELECT ?",
+      columns: [],
+      dataset: [],
+      count: 0,
+    }
+    expect(singleResultFromExec(exec, "SELECT ?")).toEqual({
+      type: "error",
+      query: "SELECT ?",
+      error: "Unknown error",
+    })
+  })
+
+  it("maps ddl exec to DdlDmlQueryResult without data fields", () => {
+    const exec: QueryExecResult = {
+      type: "ddl",
+      query: "CREATE TABLE t (x INT)",
+      columns: [],
+      dataset: [],
+      count: 0,
+    }
+    expect(singleResultFromExec(exec, "CREATE TABLE t (x INT)")).toEqual({
+      type: "ddl",
+      query: "CREATE TABLE t (x INT)",
+    })
+  })
+
+  it("maps dml exec to DdlDmlQueryResult", () => {
+    const exec: QueryExecResult = {
+      type: "dml",
+      query: "INSERT INTO t VALUES (1)",
+      columns: [],
+      dataset: [],
+      count: 0,
+    }
+    expect(singleResultFromExec(exec, "INSERT INTO t VALUES (1)")).toEqual({
+      type: "dml",
+      query: "INSERT INTO t VALUES (1)",
+    })
+  })
+})
+
+describe("isUnverifiableExecError", () => {
+  // Abort / transport / parse failures carry no server verdict → the write may
+  // have committed → unverifiable (route through cancelled, not a retryable error).
+  it("flags abort and transport-level errors (no server verdict)", () => {
+    for (const error of [
+      "Cancelled by user",
+      "An error occurred, please try again",
+      "Failed to read response: TypeError",
+      "Invalid JSON response from the server: x",
+      "QuestDB is not reachable [504]",
+    ]) {
+      expect(isUnverifiableExecError({ type: "error", error })).toBe(true)
+    }
+  })
+
+  it("does NOT flag a real server error (definitively did not commit)", () => {
+    expect(
+      isUnverifiableExecError({
+        type: "error",
+        error: "table does not exist [table=trades]",
+      }),
+    ).toBe(false)
+  })
+
+  it("does NOT flag non-error results", () => {
+    expect(isUnverifiableExecError({ type: "dml" })).toBe(false)
+    expect(isUnverifiableExecError({ type: "dql" })).toBe(false)
+    expect(isUnverifiableExecError({ type: "error" })).toBe(false)
+  })
+})
+
+describe("stripCellResults", () => {
+  it("removes result from every cell", () => {
+    const cells: NotebookCell[] = [
+      cell("a", "SELECT 1", {
+        results: [
+          {
+            type: "dql",
+            query: "SELECT 1",
+            columns: [{ name: "x", type: "INT" }],
+            dataset: [[1]],
+            count: 1,
+          },
+        ],
+        activeResultIndex: 0,
+        timestamp: 0,
+      }),
+      cell("b", "SELECT 2"),
+    ]
+    const out = stripCellResults(cells)
+    expect(out[0].result).toBeUndefined()
+    expect(out[1].result).toBeUndefined()
+  })
+
+  // The stripped result is the only run signal an unmounted notebook can report
+  // to the agent — record it so a committed write isn't read back as "none".
+  it("records lastRunStatus from the result before stripping", () => {
+    const committed: NotebookCell[] = [
+      cell("a", "INSERT INTO t VALUES(1)", {
+        results: [{ type: "dml", query: "INSERT INTO t VALUES(1)" }],
+        activeResultIndex: 0,
+        timestamp: 0,
+      }),
+      cell("b", "SELECT 2"),
+    ]
+    const out = stripCellResults(committed)
+    expect(out[0].result).toBeUndefined()
+    expect(out[0].lastRunStatus).toBe("success")
+    // never-run cell gets no run status
+    expect(out[1].lastRunStatus).toBeUndefined()
+  })
+
+  // A run still in-flight at persist time was interrupted by the unmount; an
+  // aborted write may have committed, so persist "cancelled" (→ unverified on
+  // re-read), never a perpetual "running" the agent would re-run into a dup.
+  it("persists an in-flight (running) result as cancelled", () => {
+    const inFlight: NotebookCell[] = [
+      cell("a", "INSERT INTO t SELECT * FROM big", {
+        results: [
+          { type: "running", query: "INSERT INTO t SELECT * FROM big" },
+        ],
+        activeResultIndex: 0,
+        timestamp: 0,
+      }),
+    ]
+    expect(stripCellResults(inFlight)[0].lastRunStatus).toBe("cancelled")
+  })
+
+  it("returns an empty array for empty input", () => {
+    expect(stripCellResults([])).toEqual([])
+  })
+})
+
+describe("buildPersistPayload", () => {
+  it("packs cells, focusedCellId, maximizedCellId and settings; results are stripped", () => {
+    const cells: NotebookCell[] = [
+      cell("a", "SELECT 1", {
+        results: [{ type: "running", query: "SELECT 1" }],
+        activeResultIndex: 0,
+        timestamp: 0,
+      }),
+    ]
+    const payload = buildPersistPayload(cells, "a", null, {
+      layoutMode: "list",
+    })
+    expect(payload).toEqual({
+      cells: [{ ...cells[0], result: undefined, lastRunStatus: "cancelled" }],
+      focusedCellId: "a",
+      maximizedCellId: undefined,
+      settings: { layoutMode: "list" },
+    })
+  })
+
+  it("coerces null focusedCellId/maximizedCellId to undefined", () => {
+    const payload = buildPersistPayload([], null, null, {})
+    expect(payload.focusedCellId).toBeUndefined()
+    expect(payload.maximizedCellId).toBeUndefined()
+  })
+})
+
+describe("generateDefaultLayout", () => {
+  it("stacks each cell in its own row at x=0", () => {
+    const cells = [{ id: "a" }, { id: "b" }, { id: "c" }]
+    expect(
+      generateDefaultLayout(cells, { gridCols: 12, defaultCellH: 6 }),
+    ).toEqual([
+      { i: "a", x: 0, y: 0, w: 12, h: 6 },
+      { i: "b", x: 0, y: 6, w: 12, h: 6 },
+      { i: "c", x: 0, y: 12, w: 12, h: 6 },
+    ])
+  })
+
+  it("returns empty for no cells", () => {
+    expect(
+      generateDefaultLayout([], { gridCols: 12, defaultCellH: 6 }),
+    ).toEqual([])
+  })
+})
+
+describe("mergeCellLayout", () => {
+  const opts = { gridCols: 12, defaultCellH: 6, minW: 2, minH: 2 }
+
+  it("preserves saved entries for existing cells and adds minW/minH", () => {
+    const saved = [{ i: "a", x: 3, y: 4, w: 8, h: 10 }]
+    const cells = [{ id: "a" }]
+    expect(mergeCellLayout(saved, cells, opts)).toEqual([
+      { i: "a", x: 3, y: 4, w: 8, h: 10, minW: 2, minH: 2 },
+    ])
+  })
+
+  it("stacks new cells below the current max-y+h and defaults w/h", () => {
+    const saved = [{ i: "a", x: 0, y: 0, w: 12, h: 6 }]
+    const cells = [{ id: "a" }, { id: "b" }]
+    expect(mergeCellLayout(saved, cells, opts)).toEqual([
+      { i: "a", x: 0, y: 0, w: 12, h: 6, minW: 2, minH: 2 },
+      { i: "b", x: 0, y: 6, w: 12, h: 6, minW: 2, minH: 2 },
+    ])
+  })
+
+  it("preserves order from cells, not saved layout", () => {
+    const saved = [
+      { i: "a", x: 0, y: 0, w: 12, h: 6 },
+      { i: "b", x: 0, y: 6, w: 12, h: 6 },
+    ]
+    const cells = [{ id: "b" }, { id: "a" }]
+    const out = mergeCellLayout(saved, cells, opts)
+    expect(out.map((l) => l.i)).toEqual(["b", "a"])
+  })
+
+  it("starts at y=0 when saved layout is empty", () => {
+    expect(mergeCellLayout([], [{ id: "a" }, { id: "b" }], opts)).toEqual([
+      { i: "a", x: 0, y: 0, w: 12, h: 6, minW: 2, minH: 2 },
+      { i: "b", x: 0, y: 6, w: 12, h: 6, minW: 2, minH: 2 },
+    ])
+  })
+
+  it("drops entries for cells that no longer exist", () => {
+    const saved = [
+      { i: "a", x: 0, y: 0, w: 12, h: 6 },
+      { i: "b", x: 0, y: 6, w: 12, h: 6 },
+    ]
+    const cells = [{ id: "a" }]
+    expect(mergeCellLayout(saved, cells, opts).map((l) => l.i)).toEqual(["a"])
+  })
+})
+
+// Deterministic factory so tests can assert exact ids/positions.
+const fakeFactory = (position: number, value = ""): NotebookCell => ({
+  id: `cell-${position}`,
+  position,
+  value,
+})
+
+describe("insertCell", () => {
+  it("appends a new cell when afterCellId is undefined", () => {
+    const start: NotebookCell[] = [cell("a")]
+    const out = insertCell(start, undefined, fakeFactory)
+    expect(out).toHaveLength(2)
+    expect(out[0].id).toBe("a")
+    expect(out.map((c) => c.position)).toEqual([0, 1])
+  })
+
+  it("inserts right after the named cell", () => {
+    const start: NotebookCell[] = [cell("a"), cell("b"), cell("c")]
+    const out = insertCell(start, "a", fakeFactory)
+    expect(out).toHaveLength(4)
+    expect(out.map((c) => c.id)).toEqual(["a", "cell-1", "b", "c"])
+    expect(out.map((c) => c.position)).toEqual([0, 1, 2, 3])
+  })
+
+  it("inserts at the top when afterCellId is unknown (findIndex -1 + 1 = 0)", () => {
+    // Locks original provider behaviour: unknown afterCellId inserts at index 0, not the end.
+    const start: NotebookCell[] = [cell("a")]
+    const out = insertCell(start, "missing", fakeFactory)
+    expect(out).toHaveLength(2)
+    expect(out[1].id).toBe("a")
+    expect(out.map((c) => c.position)).toEqual([0, 1])
+  })
+
+  it("uses the override id when provided", () => {
+    const start: NotebookCell[] = [cell("a")]
+    const out = insertCell(start, undefined, fakeFactory, { id: "forced-id" })
+    expect(out[1].id).toBe("forced-id")
+  })
+
+  it("uses the override value when provided", () => {
+    const start: NotebookCell[] = [cell("a")]
+    const out = insertCell(start, undefined, fakeFactory, {
+      value: "SELECT 42",
+    })
+    expect(out[1].value).toBe("SELECT 42")
+  })
+
+  it("applies both id and value overrides together", () => {
+    const start: NotebookCell[] = [cell("a")]
+    const out = insertCell(start, undefined, fakeFactory, {
+      id: "forced",
+      value: "SELECT 1",
+    })
+    expect(out[1].id).toBe("forced")
+    expect(out[1].value).toBe("SELECT 1")
+  })
+})
+
+describe("removeCell", () => {
+  it("removes the target cell and re-numbers positions", () => {
+    const out = removeCell([cell("a"), cell("b"), cell("c")], "b")
+    expect(out.map((c) => c.id)).toEqual(["a", "c"])
+    expect(out.map((c) => c.position)).toEqual([0, 1])
+  })
+
+  it("refuses to delete the last remaining cell (returns original)", () => {
+    const start: NotebookCell[] = [cell("a")]
+    expect(removeCell(start, "a")).toBe(start)
+  })
+
+  it("returns the original when the id is unknown", () => {
+    const start: NotebookCell[] = [cell("a"), cell("b")]
+    expect(removeCell(start, "missing")).toBe(start)
+  })
+})
+
+describe("swapCellUp / swapCellDown", () => {
+  const start = [cell("a"), cell("b"), cell("c")] as NotebookCell[]
+
+  it("swapCellUp swaps with the previous cell and renumbers positions", () => {
+    const out = swapCellUp(start, "b")
+    expect(out.map((c) => c.id)).toEqual(["b", "a", "c"])
+    expect(out.map((c) => c.position)).toEqual([0, 1, 2])
+  })
+
+  it("swapCellUp is a no-op at the top", () => {
+    expect(swapCellUp(start, "a")).toBe(start)
+  })
+
+  it("swapCellDown swaps with the next cell", () => {
+    const out = swapCellDown(start, "b")
+    expect(out.map((c) => c.id)).toEqual(["a", "c", "b"])
+  })
+
+  it("swapCellDown is a no-op at the bottom", () => {
+    expect(swapCellDown(start, "c")).toBe(start)
+  })
+
+  it("unknown ids are no-ops for both directions", () => {
+    expect(swapCellUp(start, "missing")).toBe(start)
+    expect(swapCellDown(start, "missing")).toBe(start)
+  })
+})
+
+describe("duplicateCellAt", () => {
+  it("inserts a copy immediately after the original with the provided id", () => {
+    const start: NotebookCell[] = [cell("a", "SELECT 1"), cell("b")]
+    const out = duplicateCellAt(start, "a", "new-id")
+    expect(out.map((c) => c.id)).toEqual(["a", "new-id", "b"])
+    expect(out.map((c) => c.position)).toEqual([0, 1, 2])
+  })
+
+  it("drops the `result` blob but carries the persisted run status onto the copy", () => {
+    const original: NotebookCell = {
+      ...cell("a", "INSERT INTO t VALUES (1)"),
+      lastRunStatus: "success",
+    }
+    const out = duplicateCellAt([original], "a", "new-id")
+    const copy = out[1]
+    expect(copy.id).toBe("new-id")
+    expect(copy.result).toBe(null)
+    // the copy's write already ran via the original; agents read this from
+    // last_run_status before deciding on an explicit run_cell
+    expect(copy.lastRunStatus).toBe("success")
+  })
+
+  it("collapses a live result into the copy's run status", () => {
+    const original: NotebookCell = {
+      ...cell("a", "INSERT INTO t VALUES (1)"),
+      result: {
+        results: [{ type: "dml", query: "INSERT INTO t VALUES (1)" }],
+        activeResultIndex: 0,
+        timestamp: 0,
+      },
+    }
+    const out = duplicateCellAt([original], "a", "new-id")
+    expect(out[1].result).toBe(null)
+    expect(out[1].lastRunStatus).toBe("success")
+  })
+
+  it("keeps the copy of a never-run cell eligible for auto-run", () => {
+    const out = duplicateCellAt([cell("a", "SELECT 1")], "a", "new-id")
+    expect(out[1].lastRunStatus).toBeUndefined()
+  })
+
+  it("returns the original when the id is unknown", () => {
+    const start: NotebookCell[] = [cell("a")]
+    expect(duplicateCellAt(start, "missing", "x")).toBe(start)
+  })
+})
+
+describe("setResultAt", () => {
+  const withResult = (results: NotebookCell["result"]): NotebookCell =>
+    cell("a", "SELECT 1", results)
+
+  it("replaces the result at the given index", () => {
+    const cells: NotebookCell[] = [
+      withResult({
+        results: [
+          { type: "running", query: "q1" },
+          { type: "running", query: "q2" },
+        ],
+        activeResultIndex: 0,
+        timestamp: 0,
+      }),
+    ]
+    const next = {
+      type: "dql" as const,
+      query: "q2",
+      columns: [{ name: "x", type: "INT" }],
+      dataset: [[1]],
+      count: 1,
+    }
+    const out = setResultAt(cells, "a", 1, next)
+    expect(out[0].result?.results[1]).toEqual(next)
+    expect(out[0].result?.results[0].type).toBe("running")
+  })
+
+  it("updates activeResultIndex when provided", () => {
+    const cells: NotebookCell[] = [
+      withResult({
+        results: [
+          { type: "running", query: "q1" },
+          { type: "running", query: "q2" },
+        ],
+        activeResultIndex: 0,
+        timestamp: 0,
+      }),
+    ]
+    const out = setResultAt(cells, "a", 1, { type: "running", query: "q2" }, 1)
+    expect(out[0].result?.activeResultIndex).toBe(1)
+  })
+
+  it("does nothing when the cell has no result", () => {
+    const cells: NotebookCell[] = [cell("a")]
+    expect(setResultAt(cells, "a", 0, { type: "running", query: "q" })).toEqual(
+      cells,
+    )
+  })
+
+  it("does nothing when the cell id is unknown", () => {
+    const cells: NotebookCell[] = [cell("a")]
+    expect(
+      setResultAt(cells, "missing", 0, { type: "running", query: "q" }),
+    ).toEqual(cells)
+  })
+})
+
+describe("cancelAllInCell", () => {
+  it("flips running and queued results to cancelled, leaves terminal types alone", () => {
+    const c = cell("a", "", {
+      results: [
+        { type: "dql", query: "q1", columns: [], dataset: [[1]], count: 1 },
+        { type: "running", query: "q2" },
+        { type: "queued", query: "q3" },
+        { type: "error", query: "q4", error: "nope" },
+      ],
+      activeResultIndex: 0,
+      timestamp: 0,
+    })
+    const out = cancelAllInCell([c], "a")
+    const results = out[0].result!.results
+    expect(results.map((r) => r.type)).toEqual([
+      "dql",
+      "cancelled",
+      "cancelled",
+      "error",
+    ])
+    expect(results[1].query).toBe("q2")
+    expect(results[2].query).toBe("q3")
+  })
+
+  it("is a no-op for cells without a result", () => {
+    const cells: NotebookCell[] = [cell("a")]
+    expect(cancelAllInCell(cells, "a")).toEqual(cells)
+  })
+})
+
+describe("cancelOneInCell", () => {
+  it("marks only the running result at the given index as cancelled", () => {
+    const c = cell("a", "", {
+      results: [
+        { type: "running", query: "q1" },
+        { type: "running", query: "q2" },
+      ],
+      activeResultIndex: 0,
+      timestamp: 0,
+    })
+    const out = cancelOneInCell([c], "a", 0)
+    const results = out[0].result!.results
+    expect(results[0].type).toBe("cancelled")
+    expect(results[1].type).toBe("running")
+  })
+
+  it("is a no-op when the result isn't running (queued, dql, error)", () => {
+    const c = cell("a", "", {
+      results: [{ type: "queued", query: "q1" }],
+      activeResultIndex: 0,
+      timestamp: 0,
+    })
+    expect(cancelOneInCell([c], "a", 0)).toEqual([c])
+  })
+
+  it("is a no-op at an out-of-range index", () => {
+    const c = cell("a", "", {
+      results: [{ type: "running", query: "q" }],
+      activeResultIndex: 0,
+      timestamp: 0,
+    })
+    expect(cancelOneInCell([c], "a", 5)).toEqual([c])
+  })
+})
+
+describe("buildInitialScriptResults", () => {
+  it("marks the first as running and the rest queued", () => {
+    expect(buildInitialScriptResults(["q1", "q2", "q3"])).toEqual([
+      { type: "running", query: "q1" },
+      { type: "queued", query: "q2" },
+      { type: "queued", query: "q3" },
+    ])
+  })
+
+  it("returns an empty list for no queries", () => {
+    expect(buildInitialScriptResults([])).toEqual([])
+  })
+
+  it("returns a single running result for one query", () => {
+    expect(buildInitialScriptResults(["only"])).toEqual([
+      { type: "running", query: "only" },
+    ])
+  })
+})
+
+describe("attachScriptSummary", () => {
+  it("attaches the summary to the cell's existing result", () => {
+    const cells: NotebookCell[] = [
+      cell("a", "", {
+        results: [
+          { type: "dql", query: "q", columns: [], dataset: [], count: 0 },
+        ],
+        activeResultIndex: 0,
+        timestamp: 0,
+      }),
+    ]
+    const out = attachScriptSummary(cells, "a", {
+      successCount: 2,
+      failedCount: 0,
+      durationMs: 123,
+    })
+    expect(out[0].result?.script).toEqual({
+      successCount: 2,
+      failedCount: 0,
+      durationMs: 123,
+    })
+  })
+
+  it("is a no-op when the cell has no result", () => {
+    const cells: NotebookCell[] = [cell("a")]
+    expect(
+      attachScriptSummary(cells, "a", {
+        successCount: 0,
+        failedCount: 0,
+        durationMs: 0,
+      }),
+    ).toEqual(cells)
+  })
+
+  it("is a no-op when the cell id is unknown", () => {
+    const cells: NotebookCell[] = [cell("a")]
+    expect(
+      attachScriptSummary(cells, "missing", {
+        successCount: 0,
+        failedCount: 0,
+        durationMs: 0,
+      }),
+    ).toEqual(cells)
+  })
+})
+
+describe("buildAppliedCells", () => {
+  const dql = (query: string): NotebookCell["result"] => ({
+    results: [
+      {
+        type: "dql" as const,
+        query,
+        columns: [],
+        dataset: [],
+        count: 0,
+      },
+    ],
+    activeResultIndex: 0,
+    timestamp: 0,
+  })
+
+  it("inserts new cells with generated ids when id is omitted", () => {
+    const prev: NotebookCell[] = []
+    const { nextCells, diff } = buildAppliedCells(prev, {
+      cells: [{ value: "SELECT 1" }, { value: "SELECT 2" }],
+    })
+    expect(nextCells.map((c) => c.value)).toEqual(["SELECT 1", "SELECT 2"])
+    expect(nextCells.map((c) => c.position)).toEqual([0, 1])
+    expect(diff.added).toHaveLength(2)
+    expect(diff.updated).toEqual([])
+    expect(diff.deleted).toEqual([])
+  })
+
+  it("updates existing cells in place and preserves result when value unchanged", () => {
+    const prev: NotebookCell[] = [
+      { id: "a", position: 0, value: "x", result: dql("x") },
+      { id: "b", position: 1, value: "y", result: dql("y") },
+    ]
+    const { nextCells, diff } = buildAppliedCells(prev, {
+      cells: [
+        { id: "a", value: "x" }, // unchanged → result preserved
+        { id: "b", value: "y2" }, // changed → result dropped
+      ],
+    })
+    expect(nextCells[0].result).toEqual(dql("x"))
+    expect(nextCells[1].result).toBeNull()
+    expect(diff.updated).toEqual(["a", "b"])
+    expect(diff.added).toEqual([])
+    expect(diff.deleted).toEqual([])
+  })
+
+  it("preserves run history as lastRunStatus when a value change drops the result", () => {
+    // A run cell carries its outcome only in the live `result` during a
+    // session; dropping it on a value change must collapse to lastRunStatus so
+    // agents still see that the cell ran.
+    const prev: NotebookCell[] = [
+      {
+        id: "a",
+        position: 0,
+        value: "INSERT INTO t VALUES (1)",
+        result: {
+          results: [{ type: "dml", query: "INSERT INTO t VALUES (1)" }],
+          activeResultIndex: 0,
+          timestamp: 0,
+        },
+      },
+    ]
+    const { nextCells } = buildAppliedCells(prev, {
+      cells: [{ id: "a", value: "INSERT INTO t  VALUES (1)" }],
+    })
+    expect(nextCells[0].result).toBeNull()
+    expect(nextCells[0].lastRunStatus).toBe("success")
+  })
+
+  it("preserveValue keeps the existing cell's value, result, and run history", () => {
+    const prev: NotebookCell[] = [
+      {
+        id: "a",
+        position: 0,
+        value: "INSERT INTO t VALUES (1)",
+        result: {
+          results: [{ type: "dml", query: "INSERT INTO t VALUES (1)" }],
+          activeResultIndex: 0,
+          timestamp: 0,
+        },
+      },
+    ]
+    const { nextCells } = buildAppliedCells(prev, {
+      cells: [{ id: "a", preserveValue: true }],
+    })
+    expect(nextCells[0].value).toBe("INSERT INTO t VALUES (1)")
+    expect(nextCells[0].result).toBe(prev[0].result)
+  })
+
+  it("rejects a cell providing both value and preserveValue", () => {
+    const prev: NotebookCell[] = [{ id: "a", position: 0, value: "SELECT 1" }]
+    expect(() =>
+      buildAppliedCells(prev, {
+        cells: [{ id: "a", value: "SELECT 2", preserveValue: true }],
+      }),
+    ).toThrow(/exactly one/)
+  })
+
+  it("rejects a cell providing neither value nor preserveValue", () => {
+    const prev: NotebookCell[] = [{ id: "a", position: 0, value: "SELECT 1" }]
+    expect(() => buildAppliedCells(prev, { cells: [{ id: "a" }] })).toThrow(
+      /has no value/,
+    )
+  })
+
+  it("rejects preserveValue on a new cell", () => {
+    const prev: NotebookCell[] = [{ id: "a", position: 0, value: "SELECT 1" }]
+    expect(() =>
+      buildAppliedCells(prev, {
+        cells: [{ id: "a", value: "SELECT 1" }, { preserveValue: true }],
+      }),
+    ).toThrow(/without an existing cell id/)
+  })
+
+  it("rejects a request that would exceed the 50-cell limit", () => {
+    const prev: NotebookCell[] = []
+    expect(() =>
+      buildAppliedCells(prev, {
+        cells: Array.from({ length: 51 }, () => ({ value: "SELECT 1" })),
+      }),
+    ).toThrow(/at most 50/)
+  })
+
+  it("accepts a request of exactly 50 cells", () => {
+    const prev: NotebookCell[] = []
+    const { nextCells } = buildAppliedCells(prev, {
+      cells: Array.from({ length: 50 }, () => ({ value: "SELECT 1" })),
+    })
+    expect(nextCells).toHaveLength(50)
+  })
+
+  it("rejects a cell whose value exceeds the line limit", () => {
+    const prev: NotebookCell[] = []
+    const hugeValue = Array(100_000).fill("x").join("\n")
+    expect(() =>
+      buildAppliedCells(prev, { cells: [{ value: hugeValue }] }),
+    ).toThrow(/line limit/)
+  })
+
+  it("allows preserving an existing over-limit cell unchanged", () => {
+    const hugeValue = Array(100_000).fill("x").join("\n")
+    const prev: NotebookCell[] = [{ id: "a", position: 0, value: hugeValue }]
+    const { nextCells } = buildAppliedCells(prev, {
+      cells: [{ id: "a", preserveValue: true }],
+    })
+    expect(nextCells[0].value).toBe(hugeValue)
+  })
+
+  it("exempts markdown cells from the line limit", () => {
+    const prev: NotebookCell[] = []
+    const hugeValue = Array(100_000).fill("x").join("\n")
+    const { nextCells } = buildAppliedCells(prev, {
+      cells: [{ value: hugeValue, type: "markdown" }],
+    })
+    expect(nextCells[0].value).toBe(hugeValue)
+  })
+
+  it("rejects preserving an over-limit markdown cell flipped to sql", () => {
+    const hugeValue = Array(100_000).fill("x").join("\n")
+    const prev: NotebookCell[] = [
+      { id: "a", position: 0, value: hugeValue, type: "markdown" },
+    ]
+    expect(() =>
+      buildAppliedCells(prev, {
+        cells: [{ id: "a", preserveValue: true, type: "sql" }],
+      }),
+    ).toThrow(/line limit/)
+  })
+
+  it("deletes cells whose ids are missing from the request", () => {
+    const prev: NotebookCell[] = [
+      { id: "a", position: 0, value: "" },
+      { id: "b", position: 1, value: "" },
+      { id: "c", position: 2, value: "" },
+    ]
+    const { nextCells, diff } = buildAppliedCells(prev, {
+      cells: [
+        { id: "a", value: "" },
+        { id: "c", value: "" },
+      ],
+    })
+    expect(nextCells.map((c) => c.id)).toEqual(["a", "c"])
+    expect(diff.deleted.sort()).toEqual(["b"])
+  })
+
+  it("throws when ids are duplicated within a request", () => {
+    expect(() =>
+      buildAppliedCells([], {
+        cells: [
+          { id: "x", value: "a" },
+          { id: "x", value: "b" },
+        ],
+      }),
+    ).toThrow(ApplyNotebookStateError)
+  })
+
+  it("throws on a supplied unknown id instead of creating it (would silently delete omitted cells)", () => {
+    const prev: NotebookCell[] = [
+      { id: "real-a", position: 0, value: "a" },
+      {
+        id: "real-b",
+        position: 1,
+        value: "IMPORTANT",
+        result: dql("IMPORTANT"),
+      },
+    ]
+    expect(() =>
+      buildAppliedCells(prev, {
+        cells: [
+          { id: "real-a", value: "a" },
+          { id: "typo-b", value: "b" }, // mistyped id — must throw, not create + drop real-b
+        ],
+      }),
+    ).toThrow(ApplyNotebookStateError)
+  })
+
+  it("throws when a draw-mode cell has no chart_config", () => {
+    expect(() =>
+      buildAppliedCells([], {
+        cells: [{ value: "SELECT 1", mode: "draw" }],
+      }),
+    ).toThrow(/no chart_config/)
+  })
+
+  it("throws when candlestick has no ohlc", () => {
+    expect(() =>
+      buildAppliedCells([], {
+        cells: [
+          {
+            value: "SELECT 1",
+            mode: "draw",
+            chartConfig: {
+              xColumn: "ts",
+              queries: [{ type: "candlestick", yColumns: ["a", "b"] }],
+            },
+          },
+        ],
+      }),
+    ).toThrow(/ohlc/)
+  })
+
+  it("does not derive ohlc from 4 yColumns — candlestick still requires explicit ohlc", () => {
+    expect(() =>
+      buildAppliedCells([], {
+        cells: [
+          {
+            value: "SELECT 1",
+            mode: "draw",
+            chartConfig: {
+              xColumn: "ts",
+              queries: [
+                { type: "candlestick", yColumns: ["o", "h", "l", "c"] },
+              ],
+            },
+          },
+        ],
+      }),
+    ).toThrow(/ohlc/)
+  })
+
+  it("throws when a sent chart_config has no queries (null or empty)", () => {
+    expect(() =>
+      buildAppliedCells([], {
+        cells: [
+          {
+            value: "SELECT 1",
+            mode: "draw",
+            chartConfig: { xColumn: "ts", queries: [] },
+          },
+        ],
+      }),
+    ).toThrow(/no queries/)
+  })
+
+  it("throws when chart queries count != the cell's ;-split statement count", () => {
+    expect(() =>
+      buildAppliedCells([], {
+        cells: [
+          {
+            value: "SELECT 1; SELECT 2",
+            mode: "draw",
+            chartConfig: {
+              xColumn: "ts",
+              // One config for a two-statement cell — would silently drop Q2.
+              queries: [{ type: "line", yColumns: ["v"] }],
+            },
+          },
+        ],
+      }),
+    ).toThrow(/2 ;-split statements/)
+  })
+
+  it("accepts chart queries that match the ;-split statement count", () => {
+    const { nextCells } = buildAppliedCells([], {
+      cells: [
+        {
+          value: "SELECT 1; SELECT 2",
+          mode: "draw",
+          chartConfig: {
+            xColumn: "ts",
+            queries: [
+              { type: "line", yColumns: ["a"] },
+              { type: "bar", yColumns: ["b"] },
+            ],
+          },
+        },
+      ],
+    })
+    expect(nextCells[0].chartConfig?.queries).toHaveLength(2)
+  })
+
+  it("defaults isChartMaximized and autoRefresh to true on new draw cells", () => {
+    const { nextCells } = buildAppliedCells([], {
+      cells: [
+        {
+          value: "SELECT 1",
+          mode: "draw",
+          chartConfig: {
+            xColumn: "ts",
+            queries: [{ type: "line", yColumns: ["v"] }],
+          },
+        },
+      ],
+    })
+    expect(nextCells[0].autoRefresh).toBe(true)
+    expect(nextCells[0].isChartMaximized).toBe(true)
+  })
+
+  it("apply is a PUT: mode='draw' with no chart_config throws even when the existing cell had one (no merge)", () => {
+    const prev: NotebookCell[] = [
+      {
+        id: "a",
+        position: 0,
+        value: "SELECT 1",
+        mode: "draw",
+        chartConfig: {
+          xColumn: "ts",
+          queries: [{ type: "line", yColumns: ["v"] }],
+        },
+      },
+    ]
+    // Re-send as draw but omit chart_config. The old `?? existing` merge would
+    // have silently inherited the saved chart; under PUT this must fail.
+    expect(() =>
+      buildAppliedCells(prev, {
+        cells: [{ id: "a", value: "SELECT 1", mode: "draw" }],
+      }),
+    ).toThrow(/no chart_config/)
+  })
+
+  it("apply is a PUT: omitted fields on an existing cell are cleared, not inherited", () => {
+    const prev: NotebookCell[] = [
+      {
+        id: "a",
+        position: 0,
+        value: "SELECT 1",
+        mode: "draw",
+        autoRefresh: true,
+        isChartMaximized: true,
+        chartConfig: {
+          xColumn: "ts",
+          queries: [{ type: "line", yColumns: ["v"] }],
+        },
+      },
+    ]
+    const { nextCells } = buildAppliedCells(prev, {
+      cells: [{ id: "a", value: "SELECT 1" }], // bare cell — everything omitted
+    })
+    expect(nextCells[0].mode).toBeUndefined()
+    expect(nextCells[0].chartConfig).toBeUndefined()
+    expect(nextCells[0].autoRefresh).toBeUndefined()
+    expect(nextCells[0].isChartMaximized).toBeUndefined()
+  })
+
+  it("refuses an empty cells array", () => {
+    expect(() => buildAppliedCells([], { cells: [] })).toThrow(
+      /at least one cell/,
+    )
+  })
+})
+
+describe("isDoubleView", () => {
+  it("returns true for run cell with a result", () => {
+    expect(
+      isDoubleView({
+        id: "x",
+        position: 0,
+        value: "",
+        result: { results: [], activeResultIndex: 0, timestamp: 0 },
+      }),
+    ).toBe(true)
+  })
+  it("returns false for run cell with no result", () => {
+    expect(isDoubleView({ id: "x", position: 0, value: "" })).toBe(false)
+  })
+  it("returns true for draw cell, whether chart-expanded or not", () => {
+    expect(
+      isDoubleView({ id: "x", position: 0, value: "", mode: "draw" }),
+    ).toBe(true)
+    expect(
+      isDoubleView({
+        id: "x",
+        position: 0,
+        value: "",
+        mode: "draw",
+        isChartMaximized: true,
+      }),
+    ).toBe(true)
+  })
+})
+
+describe("computeResultBottomHeight", () => {
+  // Layout constants (kept in sync with notebookUtils.ts):
+  //   TAB_BAR_PX            = 40
+  //   NOTIFICATION_PX       = 44
+  //   RESULT_ACTIONS_BAR_PX = 36
+  //   HEADER_HEIGHT         = 44
+  //   ROW_HEIGHT            = 30
+  //   MAX_RESERVED_ROWS     = 10
+
+  it("null/undefined/empty result → notification-only", () => {
+    expect(computeResultBottomHeight(null)).toBe(44)
+    expect(computeResultBottomHeight(undefined)).toBe(44)
+    expect(
+      computeResultBottomHeight({
+        results: [],
+        activeResultIndex: 0,
+        timestamp: 0,
+      }),
+    ).toBe(44)
+  })
+
+  it("single error → notification-only", () => {
+    expect(
+      computeResultBottomHeight({
+        results: [{ type: "error", query: "X", error: "boom" }],
+        activeResultIndex: 0,
+        timestamp: 0,
+      }),
+    ).toBe(44)
+  })
+
+  it("single DDL/DML/notice → notification-only", () => {
+    for (const type of ["ddl", "dml"] as const) {
+      expect(
+        computeResultBottomHeight({
+          results: [{ type, query: "X" }],
+          activeResultIndex: 0,
+          timestamp: 0,
+        }),
+      ).toBe(44)
+    }
+  })
+
+  it("single DQL with 0 rows → notification-only (no grid header, no rows)", () => {
+    expect(
+      computeResultBottomHeight({
+        results: [
+          {
+            type: "dql",
+            query: "SELECT 1",
+            columns: [],
+            dataset: [],
+            count: 0,
+          },
+        ],
+        activeResultIndex: 0,
+        timestamp: 0,
+      }),
+    ).toBe(44)
+  })
+
+  it("single DQL with N rows → notification + header + N×row (N capped at 10)", () => {
+    const make = (rowCount: number) => ({
+      results: [
+        {
+          type: "dql" as const,
+          query: "SELECT 1",
+          columns: [],
+          dataset: Array.from({ length: rowCount }, () => [1]),
+          count: rowCount,
+        },
+      ],
+      activeResultIndex: 0,
+      timestamp: 0,
+    })
+    // 1 row: 44 + 36 + 44 + 1*30 = 154
+    expect(computeResultBottomHeight(make(1))).toBe(154)
+    // 5 rows: 44 + 36 + 44 + 5*30 = 274
+    expect(computeResultBottomHeight(make(5))).toBe(274)
+    // 10 rows: 44 + 36 + 44 + 10*30 = 424
+    expect(computeResultBottomHeight(make(10))).toBe(424)
+    // 50 rows: cap at 10 → still 424
+    expect(computeResultBottomHeight(make(50))).toBe(424)
+  })
+
+  it("multi-statement, first DQL with rows → tab + notification + header + 10 rows", () => {
+    // 40 + 44 + 36 + 44 + 10*30 = 464
+    expect(
+      computeResultBottomHeight({
+        results: [
+          {
+            type: "dql",
+            query: "Q1",
+            columns: [],
+            dataset: [[1]],
+            count: 1,
+          },
+          { type: "ddl", query: "Q2" },
+        ],
+        activeResultIndex: 0,
+        timestamp: 0,
+      }),
+    ).toBe(464)
+  })
+
+  it("multi-statement, first is error → tab + notification only (we never saw rows)", () => {
+    // 40 + 44 = 84
+    expect(
+      computeResultBottomHeight({
+        results: [
+          { type: "error", query: "Q1", error: "boom" },
+          { type: "dql", query: "Q2", columns: [], dataset: [[1]], count: 1 },
+        ],
+        activeResultIndex: 1,
+        timestamp: 0,
+      }),
+    ).toBe(84)
+  })
+
+  it("multi-statement, first DQL with 0 rows → tab + notification only", () => {
+    // Same shape as first-is-error: the first query produced no rows, so
+    // we never reserved 10-row space.
+    expect(
+      computeResultBottomHeight({
+        results: [
+          { type: "dql", query: "Q1", columns: [], dataset: [], count: 0 },
+          { type: "dql", query: "Q2", columns: [], dataset: [[1]], count: 1 },
+        ],
+        activeResultIndex: 0,
+        timestamp: 0,
+      }),
+    ).toBe(84)
+  })
+})
+
+describe("computeCellGridH", () => {
+  it("single-view (run, no result): topHeight + chrome rounded up", () => {
+    // 72 + 56 = 128 → ceil(128/50) = 3
+    expect(computeCellGridH({ id: "x", position: 0, value: "" }, 50)).toBe(3)
+  })
+  it("double-view (run with empty result): tight notification-only bottom", () => {
+    // result.results = [] (empty after run) → bottom = NOTIFICATION_PX (44).
+    // 72 + 56 + 44 = 172 → ceil(172/50) = 4
+    expect(
+      computeCellGridH(
+        {
+          id: "x",
+          position: 0,
+          value: "",
+          result: { results: [], activeResultIndex: 0, timestamp: 0 },
+        },
+        50,
+      ),
+    ).toBe(4)
+  })
+  it("respects explicit topHeight and bottomHeight overrides", () => {
+    // 200 + 56 + 300 = 556 → ceil(556/50) = 12
+    expect(
+      computeCellGridH(
+        {
+          id: "x",
+          position: 0,
+          value: "",
+          topHeight: 200,
+          bottomHeight: 300,
+          result: { results: [], activeResultIndex: 0, timestamp: 0 },
+        },
+        50,
+      ),
+    ).toBe(12)
+  })
+  it("draw cell uses chart default 350 when bottomHeight is unset", () => {
+    // 72 + 56 + 350 = 478 → ceil(478/50) = 10
+    expect(
+      computeCellGridH({ id: "x", position: 0, value: "", mode: "draw" }, 50),
+    ).toBe(10)
+  })
+  it("returns at least 1 row even for an empty cell", () => {
+    expect(
+      computeCellGridH({ id: "x", position: 0, value: "", topHeight: 0 }, 50),
+    ).toBeGreaterThanOrEqual(1)
+  })
+  it("accounts for marginY (inter-row gaps from react-grid-layout)", () => {
+    // Same cell as the "respects explicit … overrides" test above
+    // (topHeight=200, bottomHeight=300, chrome=56 → totalPx=556).
+    // With rowHeight=10 and NO margin: 556/10 = 56 rows. With marginY=20,
+    // each row occupies (10+20)=30 px effective, so h = ceil((556+20)/30)
+    // = ceil(576/30) = 20. Rendered px = 20*10 + 19*20 = 200 + 380 = 580,
+    // which fits the 556-px content. Without the marginY term, h would
+    // be 56 → rendered 56*10 + 55*20 = 1660 px (~3× too tall).
+    expect(
+      computeCellGridH(
+        {
+          id: "x",
+          position: 0,
+          value: "",
+          topHeight: 200,
+          bottomHeight: 300,
+          result: { results: [], activeResultIndex: 0, timestamp: 0 },
+        },
+        10,
+        20,
+      ),
+    ).toBe(20)
+  })
+  it("expectingResult reserves the result area when bottomHeight is unset", () => {
+    // RESERVED_RESULT_BOTTOM_HEIGHT = 44 + 36 + 44 + 10*30 = 424.
+    // 72 + 56 + 424 = 552 → ceil(552/50) = 12
+    expect(
+      computeCellGridH(
+        { id: "x", position: 0, value: "", lastRunStatus: "success" },
+        50,
+        0,
+        true,
+      ),
+    ).toBe(12)
+  })
+  it("expectingResult uses the cell's own bottomHeight when set", () => {
+    // 72 + 56 + 300 = 428 → ceil(428/50) = 9
+    expect(
+      computeCellGridH(
+        {
+          id: "x",
+          position: 0,
+          value: "",
+          bottomHeight: 300,
+          lastRunStatus: "success",
+        },
+        50,
+        0,
+        true,
+      ),
+    ).toBe(9)
+  })
+  it("expectingResult is ignored once a result is present (double-view wins)", () => {
+    // Same as the "double-view (run with empty result)" case: bottom = 44.
+    expect(
+      computeCellGridH(
+        {
+          id: "x",
+          position: 0,
+          value: "",
+          result: { results: [], activeResultIndex: 0, timestamp: 0 },
+        },
+        50,
+        0,
+        true,
+      ),
+    ).toBe(4)
+  })
+})
+
+describe("isExpectingResult", () => {
+  const ranCell = {
+    id: "x",
+    position: 0,
+    value: "select 1",
+    lastRunStatus: "success" as const,
+  }
+  it("true for a hydrating run cell that ran but has no result yet", () => {
+    expect(isExpectingResult(ranCell, true)).toBe(true)
+  })
+  it("false once hydration has settled", () => {
+    expect(isExpectingResult(ranCell, false)).toBe(false)
+  })
+  it("false when a result has already landed", () => {
+    expect(
+      isExpectingResult(
+        {
+          ...ranCell,
+          result: { results: [], activeResultIndex: 0, timestamp: 0 },
+        },
+        true,
+      ),
+    ).toBe(false)
+  })
+  it("false for a cell that never ran", () => {
+    expect(isExpectingResult({ id: "x", position: 0, value: "" }, true)).toBe(
+      false,
+    )
+    expect(isExpectingResult({ ...ranCell, lastRunStatus: "none" }, true)).toBe(
+      false,
+    )
+  })
+  it("false for draw cells (they size via the chart default)", () => {
+    expect(isExpectingResult({ ...ranCell, mode: "draw" }, true)).toBe(false)
+  })
+})
+
+describe("buildAppliedLayout", () => {
+  it("uses request.grid when provided, otherwise derives h from topHeight + bottomHeight", () => {
+    const cells: NotebookCell[] = [
+      { id: "a", position: 0, value: "" },
+      { id: "b", position: 1, value: "" },
+    ]
+    const layout = buildAppliedLayout(
+      {
+        cells: [
+          { id: "a", value: "", grid: { x: 0, y: 0, w: 6, h: 4 } },
+          { id: "b", value: "" },
+        ],
+      },
+      cells,
+      [],
+      { gridCols: 12, rowHeight: 50 },
+    )
+    expect(layout[0]).toEqual({ i: "a", x: 0, y: 0, w: 6, h: 4 })
+    // Run-mode cell, no result yet → single-view → only topHeight (72) + chrome (40)
+    // = 112 px → ceil(112 / 50) = 3 rows. Stacks below 'a' which had y+h = 4.
+    expect(layout[1]).toEqual({ i: "b", x: 0, y: 4, w: 12, h: 3 })
+  })
+
+  it("preserves prevLayout entry when request omits grid", () => {
+    const cells: NotebookCell[] = [{ id: "a", position: 0, value: "" }]
+    const layout = buildAppliedLayout(
+      { cells: [{ id: "a", value: "" }] },
+      cells,
+      [{ i: "a", x: 3, y: 4, w: 8, h: 5 }],
+      { gridCols: 12, rowHeight: 50 },
+    )
+    expect(layout).toEqual([{ i: "a", x: 3, y: 4, w: 8, h: 5 }])
+  })
+
+  it("gives draw-mode cells a taller default than run-mode cells (no result yet)", () => {
+    // buildAppliedCells seeds bottomHeight = DEFAULT_CHART_BOTTOM_HEIGHT for
+    // draw cells, so they're double-view from creation. Run cells stay
+    // single-view (no result) and only count topHeight + chrome.
+    const cells: NotebookCell[] = [
+      { id: "run-cell", position: 0, value: "", mode: "run" },
+      {
+        id: "draw-cell",
+        position: 1,
+        value: "",
+        mode: "draw",
+        bottomHeight: 350,
+      },
+    ]
+    const layout = buildAppliedLayout(
+      {
+        cells: [
+          { id: "run-cell", value: "" },
+          { id: "draw-cell", value: "" },
+        ],
+      },
+      cells,
+      [],
+      { gridCols: 12, rowHeight: 50 },
+    )
+    // run: 72 + 40 = 112 → 3 rows
+    expect(layout[0].h).toBe(3)
+    // draw: 72 + 350 + 40 = 462 → 10 rows
+    expect(layout[1].h).toBe(10)
+    expect(layout[1].y).toBe(3) // stacked below the run cell
+  })
+})
+
+describe("cloneNotebookViewState", () => {
+  const seqIds = () => {
+    let i = 0
+    return () => `new-${i++}`
+  }
+
+  const source = (): NotebookViewState => ({
+    cells: [
+      {
+        id: "a",
+        position: 0,
+        value: "SELECT 1",
+        topHeight: 120,
+        lastRunStatus: "success",
+      },
+      {
+        id: "b",
+        position: 1,
+        value: "SELECT 2",
+        mode: "draw",
+        autoRefresh: true,
+        isChartMaximized: true,
+        chartConfig: {
+          xColumn: "ts",
+          queries: [{ type: "line", yColumns: ["v"] }],
+        },
+        result: {
+          results: [
+            {
+              type: "dql",
+              query: "SELECT 2",
+              columns: [],
+              dataset: [],
+              count: 0,
+            },
+          ],
+          activeResultIndex: 0,
+          timestamp: 0,
+        },
+      },
+    ],
+    maximizedCellId: "b",
+    focusedCellId: "a",
+    settings: {
+      layoutMode: "grid",
+      layout: [
+        { i: "a", x: 0, y: 0, w: 6, h: 4 },
+        { i: "b", x: 6, y: 0, w: 6, h: 4 },
+      ],
+      variables: [{ name: "x", value: "1" }],
+    },
+  })
+
+  it("regenerates every cell id and preserves order/position/count", () => {
+    const src = source()
+    const out = cloneNotebookViewState(src, seqIds())
+    expect(out.cells.map((c) => c.id)).toEqual(["new-0", "new-1"])
+    expect(out.cells.map((c) => c.position)).toEqual([0, 1])
+    const srcIds = new Set(src.cells.map((c) => c.id))
+    expect(out.cells.every((c) => !srcIds.has(c.id))).toBe(true)
+  })
+
+  it("strips results but preserves structural fields and run history", () => {
+    const out = cloneNotebookViewState(source(), seqIds())
+    expect(out.cells[1].result).toBeUndefined()
+    // cloned cells keep run history so auto-run never re-fires their writes
+    expect(out.cells[0].lastRunStatus).toBe("success")
+    expect(out.cells[1].lastRunStatus).toBe("success")
+    expect(out.cells[0].topHeight).toBe(120)
+    expect(out.cells[1].mode).toBe("draw")
+    expect(out.cells[1].autoRefresh).toBe(true)
+    expect(out.cells[1].isChartMaximized).toBe(true)
+    expect(out.cells[1].chartConfig).toEqual({
+      xColumn: "ts",
+      queries: [{ type: "line", yColumns: ["v"] }],
+    })
+  })
+
+  it("remaps settings.layout[].i to the new ids and keeps geometry", () => {
+    const out = cloneNotebookViewState(source(), seqIds())
+    expect(out.settings?.layout).toEqual([
+      { i: "new-0", x: 0, y: 0, w: 6, h: 4 },
+      { i: "new-1", x: 6, y: 0, w: 6, h: 4 },
+    ])
+    expect(out.settings?.layoutMode).toBe("grid")
+  })
+
+  it("drops orphan layout items that reference no cell", () => {
+    const src = source()
+    src.settings!.layout!.push({ i: "ghost", x: 0, y: 9, w: 1, h: 1 })
+    const out = cloneNotebookViewState(src, seqIds())
+    expect(out.settings?.layout).toHaveLength(2)
+    expect(out.settings?.layout?.some((l) => l.i === "ghost")).toBe(false)
+  })
+
+  it("remaps maximizedCellId and focusedCellId", () => {
+    const out = cloneNotebookViewState(source(), seqIds())
+    expect(out.maximizedCellId).toBe("new-1")
+    expect(out.focusedCellId).toBe("new-0")
+  })
+
+  it("copies variables by value, not by reference", () => {
+    const src = source()
+    const out = cloneNotebookViewState(src, seqIds())
+    expect(out.settings?.variables).toEqual([{ name: "x", value: "1" }])
+    expect(out.settings?.variables).not.toBe(src.settings?.variables)
+  })
+
+  it("does not mutate the source when the clone is edited", () => {
+    const src = source()
+    const out = cloneNotebookViewState(src, seqIds())
+    out.cells[0].value = "EDITED"
+    expect(src.cells[0].value).toBe("SELECT 1")
+  })
+
+  it("clones a default (single empty cell, no settings) notebook", () => {
+    const out = cloneNotebookViewState(
+      createDefaultNotebookViewState(),
+      seqIds(),
+    )
+    expect(out.cells).toHaveLength(1)
+    expect(out.cells[0].id).toBe("new-0")
+    expect(out.settings).toBeUndefined()
+    expect(out.maximizedCellId).toBeUndefined()
+  })
+
+  it("handles settings without a layout", () => {
+    const src: NotebookViewState = {
+      cells: [{ id: "a", position: 0, value: "x" }],
+      settings: { variables: [{ name: "v", value: "1" }] },
+    }
+    const out = cloneNotebookViewState(src, seqIds())
+    expect(out.settings?.layout).toBeUndefined()
+    expect(out.settings?.variables).toEqual([{ name: "v", value: "1" }])
+  })
+})
+
+describe("nextCopyLabel", () => {
+  it("appends (copy) to a label with no copy suffix", () => {
+    expect(nextCopyLabel("notebook")).toBe("notebook (copy)")
+    expect(nextCopyLabel("My Notebook")).toBe("My Notebook (copy)")
+  })
+
+  it("bumps (copy) to (copy 2), not (copy) (copy)", () => {
+    expect(nextCopyLabel("notebook (copy)")).toBe("notebook (copy 2)")
+  })
+
+  it("increments an existing numbered copy suffix", () => {
+    expect(nextCopyLabel("notebook (copy 2)")).toBe("notebook (copy 3)")
+    expect(nextCopyLabel("report (copy 9)")).toBe("report (copy 10)")
+  })
+
+  it("does not treat unrelated parentheses as a copy suffix", () => {
+    expect(nextCopyLabel("my (draft) notebook")).toBe(
+      "my (draft) notebook (copy)",
+    )
+  })
+})
+
+describe("capResultBytes", () => {
+  const dql = (rows: number): Extract<SingleQueryResult, { type: "dql" }> => ({
+    type: "dql",
+    query: "q",
+    columns: [{ name: "x", type: "INT" }],
+    dataset: Array.from({ length: rows }, (_, i) => [i]),
+    count: rows,
+  })
+
+  it("returns the result unchanged when under the byte cap", () => {
+    const r = dql(5)
+    expect(capResultBytes(r, 1_000_000)).toBe(r)
+  })
+
+  it("slices the dataset to fit the byte cap, preserving count", () => {
+    const r = dql(100)
+    const capped = capResultBytes(r, 50) // tiny cap
+    expect(capped.type).toBe("dql")
+    if (capped.type !== "dql") throw new Error("expected dql")
+    expect(capped.dataset.length).toBeGreaterThanOrEqual(1)
+    expect(capped.dataset.length).toBeLessThan(100)
+    // kept rows are a prefix; count is left as the server-returned value so the
+    // existing "X of Y rows" indicator still reflects truncation
+    expect(capped.dataset).toEqual(r.dataset.slice(0, capped.dataset.length))
+    expect(capped.count).toBe(100)
+  })
+
+  it("passes non-DQL and empty results through untouched", () => {
+    const ddl: SingleQueryResult = { type: "ddl", query: "q" }
+    expect(capResultBytes(ddl, 1)).toBe(ddl)
+    const empty: SingleQueryResult = {
+      type: "dql",
+      query: "q",
+      columns: [],
+      dataset: [],
+      count: 0,
+    }
+    expect(capResultBytes(empty, 1)).toBe(empty)
+  })
+})
+
+describe("sqlHash", () => {
+  it("is stable for the same SQL and differs for different SQL", () => {
+    expect(sqlHash("select 1")).toBe(sqlHash("select 1"))
+    expect(sqlHash("select 1")).not.toBe(sqlHash("select 2"))
+    expect(typeof sqlHash("anything")).toBe("string")
+  })
+})
diff --git a/src/scenes/Editor/Notebook/notebookUtils.ts b/src/scenes/Editor/Notebook/notebookUtils.ts
new file mode 100644
index 000000000..a87b86166
--- /dev/null
+++ b/src/scenes/Editor/Notebook/notebookUtils.ts
@@ -0,0 +1,889 @@
+import type { QueryExecResult } from "../../../hooks/useQueryExecution"
+import type {
+  CellLayoutItem,
+  CellMode,
+  CellResult,
+  CellType,
+  NotebookCell,
+  NotebookSettings,
+  NotebookViewState,
+  SingleQueryResult,
+} from "../../../store/notebook"
+import {
+  createCell,
+  MAX_NOTEBOOK_CELLS,
+  MAX_CELL_LINES,
+  exceedsCellLineLimit,
+} from "../../../store/notebook"
+import { deriveRunStatusFromResults } from "../../../utils/ai/runStatus"
+import type { RunStatus } from "../../../utils/ai/runStatus"
+import type { ChartConfig, QueryChart } from "./CellChart/chartTypes"
+import { getQueriesFromText } from "../Monaco/utils"
+import {
+  HEADER_HEIGHT,
+  ROW_HEIGHT,
+} from "../../../components/ResultGrid/dimensions"
+
+export const singleResultFromExec = (
+  exec: QueryExecResult,
+  query: string,
+): SingleQueryResult => {
+  switch (exec.type) {
+    case "dql":
+      return {
+        type: "dql",
+        query,
+        columns: exec.columns,
+        dataset: exec.dataset,
+        count: exec.count,
+        timestamp: exec.timestamp,
+        timings: exec.timings,
+      }
+    case "error":
+      return { type: "error", query, error: exec.error ?? "Unknown error" }
+    default:
+      return { type: exec.type, query }
+  }
+}
+
+// Notebook-scoped result caps. Rows are bounded at the fetch; the byte cap
+// bounds wide results so a persisted snapshot stays small. Deliberately NOT the
+// shared RESULT_DISPLAY_LIMIT (which the main Result panel uses).
+export const NOTEBOOK_ROW_CAP = 10_000
+export const NOTEBOOK_BYTE_CAP = 2_000_000
+
+// Cap a DQL result's dataset to ~`maxBytes` of serialized rows. `count` is left
+// as the server-returned value so the existing "X of Y rows" indicator still
+// reflects that rows were dropped. Non-DQL / empty results pass through.
+export const capResultBytes = (
+  result: SingleQueryResult,
+  maxBytes: number,
+): SingleQueryResult => {
+  if (result.type !== "dql" || result.dataset.length === 0) return result
+  const serialized = JSON.stringify(result.dataset)
+  if (serialized.length <= maxBytes) return result
+  const avgRowBytes = serialized.length / result.dataset.length
+  const keepRows = Math.max(1, Math.floor(maxBytes / avgRowBytes))
+  if (keepRows >= result.dataset.length) return result
+  return { ...result, dataset: result.dataset.slice(0, keepRows) }
+}
+
+// Cheap stable hash of a cell's SQL — a restored snapshot is only reused while
+// the cell's current SQL still matches what was saved.
+export const sqlHash = (value: string): string => {
+  let h = 5381
+  for (let i = 0; i < value.length; i++) {
+    h = ((h << 5) + h) ^ value.charCodeAt(i)
+  }
+  return (h >>> 0).toString(36)
+}
+
+const UNVERIFIABLE_ERROR_MARKERS = [
+  "Cancelled by user",
+  "An error occurred, please try again",
+  "Failed to read response",
+  "Invalid JSON response from the server",
+  "QuestDB is not reachable",
+]
+
+export const isUnverifiableExecError = (exec: {
+  type: string
+  error?: string
+}): boolean =>
+  exec.type === "error" &&
+  exec.error !== undefined &&
+  UNVERIFIABLE_ERROR_MARKERS.some((m) => exec.error?.includes(m) ?? false)
+
+export const UNVERIFIED_RUN_NOTE =
+  "Run outcome unverified: the request did not return a confirmation, so the " +
+  "query may have committed server-side. Verify (e.g. with a SELECT, or " +
+  "get_notebook_state) before re-running to avoid duplicate writes."
+
+export const collapseResultToRunStatus = (result: CellResult): RunStatus => {
+  const status = deriveRunStatusFromResults(result.results).status
+  return status === "running" ? "cancelled" : status
+}
+
+// Run history must survive every path that drops the result blob (persist,
+// duplicate, clone) — agents read last_run_status to decide whether a cell
+// still needs an explicit run_cell.
+const carriedRunStatus = (cell: NotebookCell): RunStatus | undefined =>
+  cell.result ? collapseResultToRunStatus(cell.result) : cell.lastRunStatus
+
+export const stripCellResults = (cells: NotebookCell[]): NotebookCell[] =>
+  cells.map((cell) => ({
+    ...cell,
+    result: undefined,
+    lastRunStatus: carriedRunStatus(cell),
+  }))
+
+export const buildPersistPayload = (
+  cells: NotebookCell[],
+  focusedCellId: string | null,
+  maximizedCellId: string | null,
+  settings: NotebookViewState["settings"],
+): NotebookViewState => ({
+  cells: stripCellResults(cells),
+  focusedCellId: focusedCellId ?? undefined,
+  maximizedCellId: maximizedCellId ?? undefined,
+  settings,
+})
+
+type MergeLayoutOptions = {
+  gridCols: number
+  defaultCellH: number
+  minW: number
+  minH: number
+}
+
+export const mergeCellLayout = (
+  savedLayout: CellLayoutItem[],
+  cells: { id: string }[],
+  opts: MergeLayoutOptions,
+): (CellLayoutItem & { minW: number; minH: number })[] => {
+  const layoutMap = new Map(savedLayout.map((l) => [l.i, l]))
+  const maxY =
+    savedLayout.length > 0 ? Math.max(...savedLayout.map((l) => l.y + l.h)) : 0
+  let nextY = maxY
+  return cells.map((cell) => {
+    const existing = layoutMap.get(cell.id)
+    if (existing) {
+      return { ...existing, minW: opts.minW, minH: opts.minH }
+    }
+    const item = {
+      i: cell.id,
+      x: 0,
+      y: nextY,
+      w: opts.gridCols,
+      h: opts.defaultCellH,
+      minW: opts.minW,
+      minH: opts.minH,
+    }
+    nextY += opts.defaultCellH
+    return item
+  })
+}
+
+export const generateDefaultLayout = (
+  cells: { id: string }[],
+  opts: Pick<MergeLayoutOptions, "gridCols" | "defaultCellH">,
+): CellLayoutItem[] =>
+  cells.map((cell, i) => ({
+    i: cell.id,
+    x: 0,
+    y: i * opts.defaultCellH,
+    w: opts.gridCols,
+    h: opts.defaultCellH,
+  }))
+
+// Identity-preserving so React.memo'd siblings skip re-render when one
+// cell is added or removed.
+const reindex = (cells: NotebookCell[]): NotebookCell[] =>
+  cells.map((c, i) => (c.position === i ? c : { ...c, position: i }))
+
+export const insertCell = (
+  cells: NotebookCell[],
+  afterCellId: string | undefined,
+  factory: typeof createCell = createCell,
+  override?: { id?: string; value?: string; type?: CellType },
+): NotebookCell[] => {
+  const insertIndex =
+    afterCellId !== undefined
+      ? cells.findIndex((c) => c.id === afterCellId) + 1
+      : cells.length
+  const base = factory(insertIndex, override?.value ?? "")
+  const patch: Partial<NotebookCell> = {}
+  if (override?.id) patch.id = override.id
+  if (override?.value !== undefined) patch.value = override.value
+  if (override?.type) patch.type = override.type
+  const newCell: NotebookCell =
+    Object.keys(patch).length > 0 ? { ...base, ...patch } : base
+  const next = [...cells]
+  next.splice(insertIndex, 0, newCell)
+  return reindex(next)
+}
+
+export const removeCell = (
+  cells: NotebookCell[],
+  cellId: string,
+): NotebookCell[] => {
+  if (cells.length <= 1) return cells
+  const found = cells.some((c) => c.id === cellId)
+  if (!found) return cells
+  return reindex(cells.filter((c) => c.id !== cellId))
+}
+
+export const swapCellUp = (
+  cells: NotebookCell[],
+  cellId: string,
+): NotebookCell[] => {
+  const idx = cells.findIndex((c) => c.id === cellId)
+  if (idx <= 0) return cells
+  const next = [...cells]
+  ;[next[idx - 1], next[idx]] = [next[idx], next[idx - 1]]
+  return reindex(next)
+}
+
+export const swapCellDown = (
+  cells: NotebookCell[],
+  cellId: string,
+): NotebookCell[] => {
+  const idx = cells.findIndex((c) => c.id === cellId)
+  if (idx < 0 || idx >= cells.length - 1) return cells
+  const next = [...cells]
+  ;[next[idx], next[idx + 1]] = [next[idx + 1], next[idx]]
+  return reindex(next)
+}
+
+export const duplicateCellAt = (
+  cells: NotebookCell[],
+  cellId: string,
+  newId: string,
+): NotebookCell[] => {
+  const idx = cells.findIndex((c) => c.id === cellId)
+  if (idx < 0) return cells
+  const original = cells[idx]
+  const copy: NotebookCell = {
+    ...original,
+    id: newId,
+    position: idx + 1,
+    result: null,
+    lastRunStatus: carriedRunStatus(original),
+  }
+  const next = [...cells]
+  next.splice(idx + 1, 0, copy)
+  return reindex(next)
+}
+
+export const setResultAt = (
+  cells: NotebookCell[],
+  cellId: string,
+  index: number,
+  result: SingleQueryResult,
+  activeIndex?: number,
+): NotebookCell[] =>
+  cells.map((c) => {
+    if (c.id !== cellId || !c.result) return c
+    const results = [...c.result.results]
+    results[index] = result
+    const nextCellResult: CellResult = {
+      ...c.result,
+      results,
+      ...(activeIndex !== undefined && { activeResultIndex: activeIndex }),
+    }
+    return { ...c, result: nextCellResult }
+  })
+
+export const cancelAllInCell = (
+  cells: NotebookCell[],
+  cellId: string,
+): NotebookCell[] =>
+  cells.map((c) => {
+    if (c.id !== cellId || !c.result) return c
+    return {
+      ...c,
+      result: {
+        ...c.result,
+        results: c.result.results.map((r) =>
+          r.type === "running" || r.type === "queued"
+            ? { type: "cancelled", query: r.query }
+            : r,
+        ),
+      },
+    }
+  })
+
+export const cancelOneInCell = (
+  cells: NotebookCell[],
+  cellId: string,
+  index: number,
+): NotebookCell[] =>
+  cells.map((c) => {
+    if (c.id !== cellId || !c.result) return c
+    const results = [...c.result.results]
+    const target = results[index]
+    if (target?.type !== "running") return c
+    results[index] = { type: "cancelled", query: target.query }
+    return { ...c, result: { ...c.result, results } }
+  })
+
+export const buildInitialScriptResults = (
+  queries: string[],
+): SingleQueryResult[] =>
+  queries.map((q, i) => ({
+    type: i === 0 ? "running" : "queued",
+    query: q,
+  }))
+
+type ApplyCellRequest = {
+  id?: string | null
+  value?: string | null
+  preserveValue?: boolean | null
+  type?: CellType | null
+  mode?: CellMode | null
+  autoRefresh?: boolean | null
+  isChartMaximized?: boolean | null
+  chartConfig?: ChartConfig | null
+  grid?: { x: number; y: number; w: number; h: number } | null
+}
+
+type ApplyRequest = {
+  layoutMode?: "list" | "grid" | null
+  maximizedCellId?: string | null
+  cells: ApplyCellRequest[]
+}
+
+type AppliedDiff = {
+  added: string[]
+  updated: string[]
+  deleted: string[]
+}
+
+export class ApplyNotebookStateError extends Error {
+  readonly field?: string
+  constructor(message: string, field?: string) {
+    super(message)
+    this.name = "ApplyNotebookStateError"
+    this.field = field
+  }
+}
+
+const generateId = (): string =>
+  typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+    ? crypto.randomUUID()
+    : Math.random().toString(36).slice(2)
+
+export const nextCopyLabel = (label: string): string => {
+  const match = label.match(/^(.*) \(copy(?: (\d+))?\)$/)
+  if (!match) return `${label} (copy)`
+  const n = match[2] ? parseInt(match[2], 10) : 1
+  return `${match[1]} (copy ${n + 1})`
+}
+
+export const cloneNotebookViewState = (
+  source: NotebookViewState,
+  newId: () => string = generateId,
+): NotebookViewState => {
+  const idMap = new Map<string, string>()
+  const cells: NotebookCell[] = source.cells.map((cell) => {
+    const id = newId()
+    idMap.set(cell.id, id)
+    return {
+      ...cell,
+      id,
+      result: undefined,
+      lastRunStatus: carriedRunStatus(cell),
+    }
+  })
+
+  const next: NotebookViewState = { cells }
+
+  if (source.settings) {
+    const settings: NotebookSettings = { ...source.settings }
+    if (source.settings.layout) {
+      settings.layout = source.settings.layout
+        .filter((item) => idMap.has(item.i))
+        .map((item) => ({ ...item, i: idMap.get(item.i) as string }))
+    }
+    if (source.settings.variables) {
+      settings.variables = source.settings.variables.map((v) => ({ ...v }))
+    }
+    next.settings = settings
+  }
+
+  if (source.maximizedCellId && idMap.has(source.maximizedCellId)) {
+    next.maximizedCellId = idMap.get(source.maximizedCellId)
+  }
+  if (source.focusedCellId && idMap.has(source.focusedCellId)) {
+    next.focusedCellId = idMap.get(source.focusedCellId)
+  }
+
+  return next
+}
+
+const normalizeQueryChart = (q: QueryChart): QueryChart => {
+  const next: QueryChart = { type: q.type, yColumns: q.yColumns ?? [] }
+  if (q.ohlc) next.ohlc = q.ohlc
+  if (q.partitionByColumn) next.partitionByColumn = q.partitionByColumn
+  if (q.axis) next.axis = q.axis
+  if (q.enabled === false) next.enabled = false
+  if (q.name) next.name = q.name
+  return next
+}
+
+const normalizeChartConfig = (
+  cfg: ChartConfig | null | undefined,
+): ChartConfig | undefined => {
+  if (!cfg) return undefined
+  const next: ChartConfig = {
+    xColumn: cfg.xColumn ?? null,
+    queries: cfg.queries.map((q) => (q ? normalizeQueryChart(q) : null)),
+  }
+  if (cfg.name) next.name = cfg.name
+  if (cfg.rightAxis) next.rightAxis = cfg.rightAxis
+  if (cfg.autoRefresh !== undefined) next.autoRefresh = cfg.autoRefresh
+  return next
+}
+
+export const buildAppliedCells = (
+  prev: NotebookCell[],
+  request: ApplyRequest,
+): { nextCells: NotebookCell[]; diff: AppliedDiff } => {
+  const prevById = new Map(prev.map((c) => [c.id, c]))
+  const seenIds = new Set<string>()
+  const added: string[] = []
+  const updated: string[] = []
+
+  const nextCells: NotebookCell[] = request.cells.map((req, index) => {
+    const requestedId =
+      typeof req.id === "string" && req.id.length > 0 ? req.id : undefined
+    if (requestedId && seenIds.has(requestedId)) {
+      throw new ApplyNotebookStateError(
+        `Duplicate cell id "${requestedId}" in request.`,
+        "cells",
+      )
+    }
+
+    const existing = requestedId ? prevById.get(requestedId) : undefined
+    if (requestedId && !existing) {
+      throw new ApplyNotebookStateError(
+        `Unknown cell id "${requestedId}". Omit id to create a new cell; use an id from the current notebook to update one.`,
+        "cells",
+      )
+    }
+    const id = requestedId ?? generateId()
+    if (existing) seenIds.add(existing.id)
+    else seenIds.add(id)
+
+    // apply_notebook_state is a PUT: each requested cell fully describes
+    // itself — the value either verbatim or as an explicit preserve.
+    const preserve = req.preserveValue === true
+    if (preserve && typeof req.value === "string") {
+      throw new ApplyNotebookStateError(
+        `Cell at index ${index} provides both value and preserve_value:true. Send exactly one per cell.`,
+        "cells",
+      )
+    }
+    if (!preserve && typeof req.value !== "string") {
+      throw new ApplyNotebookStateError(
+        `Cell at index ${index} has no value. Send the full SQL text, or preserve_value:true to keep an existing cell's value unchanged.`,
+        "cells",
+      )
+    }
+    const value = preserve ? existing?.value : (req.value ?? undefined)
+    if (value === undefined) {
+      throw new ApplyNotebookStateError(
+        `Cell at index ${index} sets preserve_value:true without an existing cell id. New cells must send value.`,
+        "cells",
+      )
+    }
+    const resolvedMode: CellMode | undefined =
+      req.mode === undefined || req.mode === null ? undefined : req.mode
+
+    const chartConfig = normalizeChartConfig(req.chartConfig)
+
+    // Cell kind is STICKY: omitting type preserves an existing cell's kind
+    // (unlike mode, which is PUT-reset). Converting a markdown cell to SQL by
+    // omission would silently turn prose into a runnable query — too surprising.
+    const resolvedType: CellType | undefined =
+      req.type === undefined || req.type === null ? existing?.type : req.type
+
+    // Markdown cells hold prose, not editor SQL, so they're exempt from the cap.
+    const preservesStoredSql = preserve && existing?.type !== "markdown"
+    if (
+      !preservesStoredSql &&
+      resolvedType !== "markdown" &&
+      exceedsCellLineLimit(value)
+    ) {
+      throw new ApplyNotebookStateError(
+        `Cell at index ${index} has ${value.split("\n").length} lines, over the ${MAX_CELL_LINES}-line limit. Split it into multiple cells.`,
+        "cells",
+      )
+    }
+
+    if (resolvedType === "markdown") {
+      if (resolvedMode !== undefined) {
+        throw new ApplyNotebookStateError(
+          `Cell at index ${index} is a markdown cell and cannot have a mode. Omit mode and chart_config for markdown cells.`,
+          "cells",
+        )
+      }
+      if (req.chartConfig != null) {
+        throw new ApplyNotebookStateError(
+          `Cell at index ${index} is a markdown cell and cannot have a chart_config.`,
+          "cells",
+        )
+      }
+    }
+
+    if (resolvedMode === "draw" && !chartConfig) {
+      throw new ApplyNotebookStateError(
+        `Cell at index ${index} has mode='draw' but no chart_config. apply replaces the cell wholesale — send the full chart_config (read the current one from <notebook_context> / get_notebook_state).`,
+        "cells",
+      )
+    }
+    if (req.chartConfig && req.chartConfig.queries.length === 0) {
+      throw new ApplyNotebookStateError(
+        `Cell at index ${index} has a chart_config with no queries. Provide one entry per ;-split query (apply replaces the chart wholesale).`,
+        "cells",
+      )
+    }
+    if (req.chartConfig && req.chartConfig.queries.length > 0) {
+      const statementCount = getQueriesFromText(value).length
+      if (
+        statementCount > 0 &&
+        req.chartConfig.queries.length !== statementCount
+      ) {
+        throw new ApplyNotebookStateError(
+          `Cell at index ${index} has ${req.chartConfig.queries.length} chart queries but ${statementCount} ;-split statement${statementCount === 1 ? "" : "s"}. Send exactly one entry per statement (index-aligned); apply replaces all per-query configs.`,
+          "cells",
+        )
+      }
+    }
+    if (
+      chartConfig?.queries.some(
+        (q) => q != null && q.type === "candlestick" && !q.ohlc,
+      )
+    ) {
+      throw new ApplyNotebookStateError(
+        `Cell at index ${index} has a candlestick query with no ohlc mapping.`,
+        "cells",
+      )
+    }
+
+    const isDraw = resolvedMode === "draw"
+    const isChartMaximized =
+      req.isChartMaximized != null
+        ? req.isChartMaximized
+        : isDraw
+          ? true
+          : undefined
+    const autoRefresh =
+      req.autoRefresh != null ? req.autoRefresh : isDraw ? true : undefined
+
+    if (existing) {
+      updated.push(existing.id)
+      const valueChanged = existing.value !== value
+      const next: NotebookCell = {
+        ...existing,
+        id: existing.id,
+        position: index,
+        value,
+        result: valueChanged ? null : existing.result,
+      }
+      if (valueChanged && existing.result) {
+        next.lastRunStatus = collapseResultToRunStatus(existing.result)
+      }
+      if (resolvedMode !== undefined) next.mode = resolvedMode
+      else delete next.mode
+      if (chartConfig !== undefined) next.chartConfig = chartConfig
+      else delete next.chartConfig
+      if (autoRefresh !== undefined) next.autoRefresh = autoRefresh
+      else delete next.autoRefresh
+      if (isChartMaximized !== undefined)
+        next.isChartMaximized = isChartMaximized
+      else delete next.isChartMaximized
+      if (resolvedType === "markdown") {
+        // Markdown cells carry none of the SQL/chart sub-state.
+        next.type = "markdown"
+        next.result = null
+        delete next.mode
+        delete next.chartConfig
+        delete next.autoRefresh
+        delete next.isChartMaximized
+        delete next.bottomHeight
+        delete next.lastRunStatus
+      } else {
+        delete next.type
+      }
+      return next
+    }
+
+    added.push(id)
+    const created: NotebookCell = {
+      id,
+      position: index,
+      value,
+    }
+    if (resolvedType === "markdown") {
+      created.type = "markdown"
+      return created
+    }
+    if (resolvedMode !== undefined) created.mode = resolvedMode
+    if (chartConfig !== undefined) created.chartConfig = chartConfig
+    if (autoRefresh !== undefined) created.autoRefresh = autoRefresh
+    if (isChartMaximized !== undefined)
+      created.isChartMaximized = isChartMaximized
+    // Draw cells are double-view from creation (chart visible immediately),
+    // so seed bottomHeight with the chart default. Run cells stay single-
+    // view (no bottomHeight) until the user runs them.
+    if (resolvedMode === "draw") {
+      created.bottomHeight = DEFAULT_CHART_BOTTOM_HEIGHT
+    }
+    return created
+  })
+
+  if (nextCells.length === 0) {
+    throw new ApplyNotebookStateError(
+      "Request cells array is empty; a notebook must have at least one cell.",
+      "cells",
+    )
+  }
+
+  if (nextCells.length > MAX_NOTEBOOK_CELLS) {
+    throw new ApplyNotebookStateError(
+      `Request would result in ${nextCells.length} cells; a notebook can have at most ${MAX_NOTEBOOK_CELLS}.`,
+      "cells",
+    )
+  }
+
+  const deleted = prev.filter((c) => !seenIds.has(c.id)).map((c) => c.id)
+
+  return { nextCells, diff: { added, updated, deleted } }
+}
+
+// === Cell sizing model ======================================================
+// Cells are in one of two view states:
+//
+//   - Single-view: only the editor (or only the expanded chart) is visible.
+//     Total cell height = topHeight + chrome.
+//   - Double-view: editor on top + result/chart on bottom.
+//     Total cell height = topHeight + bottomHeight + chrome.
+//
+// `topHeight` and `bottomHeight` live on NotebookCell; they replace the four
+// `custom*Height` fields from the old model. In grid mode, the grid h (rows)
+// is *derived* from topHeight + bottomHeight on every render.
+// ============================================================================
+
+// Approximate fixed chrome around the editor in a cell, in pixels.
+// Breakdown:
+//   - RunBar: 40 px (1rem vertical padding + ~24 px button glyph)
+//   - CellWrapper top/bottom border: 2 px
+//   - Inner-top ResizeHandle (only when double-view): 10 px
+//   - Safety margin for sub-pixel rounding, grid row bottom-border,
+//     and any single-pixel adornments inside the result panel: 4 px
+// Stays a single conservative constant rather than state-aware: the
+// extra ~14 px in single-view is at most a half-row of trailing
+// whitespace at our 10 px grid granularity — invisible — but avoids
+// the "row cut by 2-3 px" symptom in double-view cells.
+export const CELL_CHROME_PX = 56
+
+// Default editor height for a newly-created cell, before any content arrives.
+// Matches MIN_EDITOR_HEIGHT used by Monaco; kept here so layout math doesn't
+// need to import Cell.tsx constants.
+export const DEFAULT_TOP_HEIGHT = 72
+
+// Default chart height for draw mode (experimental — per user spec).
+export const DEFAULT_CHART_BOTTOM_HEIGHT = 350
+
+export const MIN_BOTTOM_HEIGHT_PX = 88
+
+// Pixel sizes of the result panel's chrome. Kept in sync with the styled-
+// components in result-table/styles.ts; if those constants change, update
+// here.
+const TAB_BAR_PX = 40 // TabBarWrapper height = 4rem
+const NOTIFICATION_PX = 44 // StatusNotification (compact=true → 4rem + 1-2 px borders)
+const RESULT_ACTIONS_BAR_PX = 36 // ResultActionsBar height = 3.6rem (shown with the grid)
+const MAX_RESERVED_ROWS = 10 // cap for "tight-fit" single-query results
+
+// Height to reserve for a run cell's result area while its snapshot hydrates —
+// the same max single-statement grid height `computeResultBottomHeight` settles
+// to for a ≥10-row result, so the grid drops in without a height jump. Mirrors
+// how draw reserves a fixed DEFAULT_CHART_BOTTOM_HEIGHT before its data lands.
+export const RESERVED_RESULT_BOTTOM_HEIGHT =
+  NOTIFICATION_PX +
+  RESULT_ACTIONS_BAR_PX +
+  HEADER_HEIGHT +
+  MAX_RESERVED_ROWS * ROW_HEIGHT
+
+export const isExpectingResult = (
+  cell: NotebookCell,
+  isHydrating: boolean,
+): boolean =>
+  isHydrating &&
+  cell.mode !== "draw" &&
+  cell.lastRunStatus != null &&
+  cell.lastRunStatus !== "none" &&
+  cell.result == null
+
+const isDqlWithRows = (r: SingleQueryResult): boolean =>
+  r.type === "dql" && r.dataset.length > 0
+
+const dqlRowCount = (r: SingleQueryResult): number =>
+  r.type === "dql" ? r.dataset.length : 0
+
+// Computes the bottom slot height for a result based on its content.
+//
+// Rules:
+//   1. Single-statement, no data (error / DDL / DML / notice / 0-row DQL):
+//      just the notification bar — no wasted blank space.
+//   2. Single-statement DQL with N rows: notification + grid header + min(N, 10)
+//      rows. Shrinks for small results, caps at 10 for large ones.
+//   3. Multi-statement (script) run:
+//      - tab bar always visible.
+//      - If the first result is non-data (error / DDL / DML / notice), height
+//        is just tab bar + notification (the user never saw rows).
+//      - Otherwise reserve a full 10 rows worth of space regardless of how
+//        many rows the active tab actually has (avoids jitter when switching
+//        between tabs that have different row counts).
+export const computeResultBottomHeight = (
+  result: CellResult | null | undefined,
+): number => {
+  if (!result || result.results.length === 0) return NOTIFICATION_PX
+  const isMulti = result.results.length > 1
+  const tabBar = isMulti ? TAB_BAR_PX : 0
+
+  if (isMulti) {
+    const first = result.results[0]
+    if (!first || !isDqlWithRows(first)) {
+      // First query failed / wasn't DQL — we never saw any rows, no point
+      // reserving 10 rows of space. The tab bar still shows so the user can
+      // click through other tabs.
+      return tabBar + NOTIFICATION_PX
+    }
+    return (
+      tabBar +
+      NOTIFICATION_PX +
+      RESULT_ACTIONS_BAR_PX +
+      HEADER_HEIGHT +
+      MAX_RESERVED_ROWS * ROW_HEIGHT
+    )
+  }
+
+  // Single-statement: tight-fit up to 10 rows.
+  const only = result.results[0]
+  if (!only || !isDqlWithRows(only)) {
+    return NOTIFICATION_PX
+  }
+  const rows = Math.min(MAX_RESERVED_ROWS, dqlRowCount(only))
+  return (
+    NOTIFICATION_PX + RESULT_ACTIONS_BAR_PX + HEADER_HEIGHT + rows * ROW_HEIGHT
+  )
+}
+
+// Returns the appropriate default bottom-slot height for a cell, based on
+// what the bottom slot will contain. Used as the render-time fallback when
+// cell.bottomHeight is undefined (first paint of a freshly-loaded cell).
+// Always agrees with what runCell would have written into cell.bottomHeight.
+export const defaultBottomHeightFor = (cell: NotebookCell): number =>
+  cell.mode === "draw"
+    ? DEFAULT_CHART_BOTTOM_HEIGHT
+    : computeResultBottomHeight(cell.result)
+
+// True iff this cell occupies vertical space for a bottom slot — i.e. its
+// total height includes bottomHeight. This includes the chart-expanded case
+// (chart fills both slots; the cell footprint still spans topHeight +
+// bottomHeight).
+export const isDoubleView = (cell: NotebookCell): boolean => {
+  if (cell.mode === "draw") return true
+  return cell.result != null
+}
+
+// Derives the react-grid-layout `h` (row count) for a cell from its
+// topHeight + bottomHeight + chrome. Recomputed at render time on every
+// state change.
+//
+// react-grid-layout inserts `marginY` BETWEEN rows, so the actual
+// rendered px of an h-row cell is `h * rowHeight + (h - 1) * marginY`,
+// NOT `h * rowHeight`. To fit a content of `totalPx` we therefore need
+// `ceil((totalPx + marginY) / (rowHeight + marginY))` rows. Forgetting
+// the marginY term inflated cell heights by ~3× at rowHeight=10,
+// marginY=20 (a 500-px content asked for 50 rows that rendered as
+// ~1480 px). Default marginY=0 keeps backwards-compat for tests/callers
+// that ignore margins.
+export const computeCellGridH = (
+  cell: NotebookCell,
+  rowHeight: number,
+  marginY: number = 0,
+  expectingResult: boolean = false,
+): number => {
+  const top = cell.topHeight ?? DEFAULT_TOP_HEIGHT
+  const bottom = isDoubleView(cell)
+    ? (cell.bottomHeight ?? defaultBottomHeightFor(cell))
+    : expectingResult
+      ? (cell.bottomHeight ?? RESERVED_RESULT_BOTTOM_HEIGHT)
+      : 0
+  const totalPx = CELL_CHROME_PX + top + bottom
+  return Math.max(1, Math.ceil((totalPx + marginY) / (rowHeight + marginY)))
+}
+
+export const partitionCellHeights = (
+  sum: number,
+  requestedTop: number,
+  minTop: number,
+  minBottom: number,
+): { top: number; bottom: number } => {
+  let top = Math.max(minTop, requestedTop)
+  let bottom = sum - top
+  if (bottom < minBottom) {
+    bottom = minBottom
+    top = sum - bottom
+  }
+  return { top, bottom }
+}
+
+export const scaleCellHeights = (
+  oldTop: number,
+  oldBottom: number,
+  newContent: number,
+  minTop: number,
+  minBottom: number,
+): { top: number; bottom: number } => {
+  const oldContent = oldTop + oldBottom
+  const clampedContent = Math.max(minTop + minBottom, newContent)
+  const scale = oldContent > 0 ? clampedContent / oldContent : 1
+  let top = Math.round(oldTop * scale)
+  let bottom = clampedContent - top
+  if (top < minTop) {
+    top = minTop
+    bottom = clampedContent - top
+  }
+  if (bottom < minBottom) {
+    bottom = minBottom
+    top = clampedContent - bottom
+  }
+  return { top, bottom }
+}
+
+export const buildAppliedLayout = (
+  request: ApplyRequest,
+  nextCells: NotebookCell[],
+  prevLayout: CellLayoutItem[] | undefined,
+  defaults: { gridCols: number; rowHeight: number; marginY?: number },
+): CellLayoutItem[] => {
+  const prevById = new Map((prevLayout ?? []).map((l) => [l.i, l]))
+  let nextY = 0
+  return nextCells.map((cell, i) => {
+    const req = request.cells[i]
+    if (req?.grid) {
+      const item = { i: cell.id, ...req.grid }
+      nextY = Math.max(nextY, req.grid.y + req.grid.h)
+      return item
+    }
+    const existing = prevById.get(cell.id)
+    if (existing) {
+      nextY = Math.max(nextY, existing.y + existing.h)
+      return existing
+    }
+    const cellH = computeCellGridH(cell, defaults.rowHeight, defaults.marginY)
+    const item: CellLayoutItem = {
+      i: cell.id,
+      x: 0,
+      y: nextY,
+      w: defaults.gridCols,
+      h: cellH,
+    }
+    nextY += cellH
+    return item
+  })
+}
+
+export const attachScriptSummary = (
+  cells: NotebookCell[],
+  cellId: string,
+  summary: NonNullable<CellResult["script"]>,
+): NotebookCell[] =>
+  cells.map((c) => {
+    if (c.id !== cellId || !c.result) return c
+    return { ...c, result: { ...c.result, script: summary } }
+  })
diff --git a/src/scenes/Editor/Notebook/persistCellSnapshot.ts b/src/scenes/Editor/Notebook/persistCellSnapshot.ts
new file mode 100644
index 000000000..6ac5c79fe
--- /dev/null
+++ b/src/scenes/Editor/Notebook/persistCellSnapshot.ts
@@ -0,0 +1,22 @@
+import { toast } from "../../../components/Toast"
+import {
+  pruneToRecentNotebooks,
+  saveCellSnapshot,
+  type NotebookResultSnapshot,
+} from "../../../store/notebookResults"
+
+// Stable id so a storage failure that repeats across many cells (e.g. the disk
+// quota is exhausted) collapses into a single toast instead of flooding.
+const SNAPSHOT_SAVE_ERROR_TOAST_ID = "notebook-snapshot-save-error"
+
+export const persistCellSnapshot = (snapshot: NotebookResultSnapshot): void => {
+  saveCellSnapshot(snapshot)
+    .then(() => pruneToRecentNotebooks())
+    .catch((error) => {
+      console.error("Failed to persist notebook cell result", error)
+      toast.error(
+        "Couldn't save this cell's result for offline restore. It may be lost on reload or your browser storage might be full.",
+        { toastId: SNAPSHOT_SAVE_ERROR_TOAST_ID },
+      )
+    })
+}
diff --git a/src/scenes/Editor/Notebook/resize/EdgeHandle.tsx b/src/scenes/Editor/Notebook/resize/EdgeHandle.tsx
new file mode 100644
index 000000000..d4540be92
--- /dev/null
+++ b/src/scenes/Editor/Notebook/resize/EdgeHandle.tsx
@@ -0,0 +1,160 @@
+import React from "react"
+import styled from "styled-components"
+import { color } from "../../../../utils"
+import { eventBus } from "../../../../modules/EventBus"
+import { EventType } from "../../../../modules/EventBus/types"
+import { CornerChip, SideChip } from "./chips"
+
+const isCorner = (axis: string): boolean => axis === "se" || axis === "sw"
+
+const Handle = styled.div<{ $axis: string }>`
+  position: absolute;
+  z-index: 2;
+  outline: none;
+  color: ${color("pinkPrimary")};
+  --chip-bg: ${color("backgroundDarker")};
+
+  /* Visuals are hidden until the handle is hovered; corner handles are also
+     revealed when the cell is selected (rule lives on the grid container). */
+  opacity: 0;
+  transition: opacity 0.1s;
+
+  &:hover {
+    opacity: 1;
+  }
+
+  .edge-line {
+    position: absolute;
+    pointer-events: none;
+    background: ${color("pinkPrimary")};
+  }
+
+  .edge-chip {
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    line-height: 0;
+    pointer-events: none;
+  }
+
+  ${({ $axis }) =>
+    $axis === "e" &&
+    `
+    right: -10px;
+    top: 10px;
+    bottom: 10px;
+    width: 20px;
+    cursor: ew-resize;
+    .edge-line {
+      top: 0;
+      bottom: 0;
+      left: 50%;
+      transform: translateX(-50%);
+      width: 2px;
+    }
+    .edge-chip { transform: translate(-50%, -50%); }
+  `}
+
+  ${({ $axis }) =>
+    $axis === "w" &&
+    `
+    left: -10px;
+    top: 10px;
+    bottom: 10px;
+    width: 20px;
+    cursor: ew-resize;
+    .edge-line {
+      top: 0;
+      bottom: 0;
+      left: 50%;
+      transform: translateX(-50%);
+      width: 2px;
+    }
+    .edge-chip { transform: translate(-50%, -50%); }
+  `}
+
+  ${({ $axis }) =>
+    $axis === "s" &&
+    `
+    bottom: -10px;
+    left: 10px;
+    right: 10px;
+    height: 20px;
+    cursor: ns-resize;
+    .edge-line {
+      left: 0;
+      right: 0;
+      top: 50%;
+      transform: translateY(-50%);
+      height: 2px;
+    }
+    .edge-chip { transform: translate(-50%, -50%) rotate(90deg); }
+  `}
+
+  ${({ $axis }) =>
+    $axis === "se" &&
+    `
+    right: -10px;
+    bottom: -10px;
+    width: 20px;
+    height: 20px;
+    cursor: se-resize;
+    .edge-chip { transform: translate(-50%, -50%) scaleY(-1); }
+  `}
+
+  ${({ $axis }) =>
+    $axis === "sw" &&
+    `
+    left: -10px;
+    bottom: -10px;
+    width: 20px;
+    height: 20px;
+    cursor: sw-resize;
+    .edge-chip { transform: translate(-50%, -50%) scale(-1, -1); }
+  `}
+`
+
+const dispatchAxisDoubleClick = (axis: string, target: HTMLElement): void => {
+  const cellEl = target.closest<HTMLElement>("[data-cell-id]")
+  const cellId = cellEl?.dataset.cellId
+  if (!cellId) return
+  if (axis === "s") {
+    eventBus.publish(EventType.NOTEBOOK_CELL_RESET_SIZE, { cellId })
+    return
+  }
+  if (axis === "e" || axis === "w") {
+    eventBus.publish(EventType.NOTEBOOK_CELL_EXPAND_WIDTH, {
+      cellId,
+      kind: axis === "e" ? "right" : "left",
+    })
+  }
+}
+
+// Signature matches react-grid-layout's handleComponent prop.
+export const renderEdgeHandle = (axis: string, ref: React.Ref<HTMLElement>) => {
+  const corner = isCorner(axis)
+  return (
+    <Handle
+      ref={ref as React.Ref<HTMLDivElement>}
+      $axis={axis}
+      className={`edge-handle edge-handle--${corner ? "corner" : "side"}`}
+      data-axis={axis}
+      role="separator"
+      aria-orientation={axis === "s" || corner ? "horizontal" : "vertical"}
+      aria-label={`Resize cell (${axis}) — drag to resize`}
+      tabIndex={0}
+      onDoubleClick={
+        corner
+          ? undefined
+          : (e) => dispatchAxisDoubleClick(axis, e.currentTarget as HTMLElement)
+      }
+    >
+      {!corner && <span className="edge-line" />}
+      <span className="edge-chip">
+        {corner ? <CornerChip /> : <SideChip />}
+      </span>
+    </Handle>
+  )
+}
+
+export const EdgeHandle = Handle
diff --git a/src/scenes/Editor/Notebook/resize/ResizeHandle.tsx b/src/scenes/Editor/Notebook/resize/ResizeHandle.tsx
new file mode 100644
index 000000000..a8f185d88
--- /dev/null
+++ b/src/scenes/Editor/Notebook/resize/ResizeHandle.tsx
@@ -0,0 +1,181 @@
+import React, { useCallback, useEffect, useRef } from "react"
+import styled from "styled-components"
+import { color } from "../../../../utils"
+import { SideChip } from "./chips"
+
+// Matches the grid EdgeHandle `s` (south) affordance: a 2px pink line plus a
+// grip chip, revealed on hover, so list-mode resizing looks like grid.
+//
+// `$overlay` is the cell's bottom-edge handle: rather than an in-flow bar
+// (which would clip its chip against the cell border), it's an absolute strip
+// straddling the cell's bottom edge — like grid's `s` handle — so the line sits
+// on the border and the chip overflows outside the cell (the parent shell and
+// list container are overflow-visible).
+const Handle = styled.div<{
+  $background?: string
+  $doubleView?: boolean
+  $overlay?: boolean
+}>`
+  cursor: ns-resize;
+  z-index: 2;
+  flex-shrink: 0;
+  outline: none;
+  color: ${color("pinkPrimary")};
+  --chip-bg: ${color("backgroundDarker")};
+
+  ${({ $overlay, $doubleView, $background, theme }) =>
+    $overlay
+      ? `
+    position: absolute;
+    /* Inset from the corners (like grid's s handle) so the handle and its line
+       clear the cell's rounded bottom border instead of poking past it. */
+    left: 10px;
+    right: 10px;
+    bottom: -10px;
+    height: 20px;
+    background: transparent;
+  `
+      : `
+    position: relative;
+    height: ${$doubleView ? "6px" : "10px"};
+    background: ${$background ?? theme.color.backgroundLighter};
+  `}
+
+  .resize-line,
+  .resize-chip {
+    opacity: 0;
+    transition: opacity 0.1s;
+    pointer-events: none;
+  }
+
+  &:hover .resize-line,
+  &:focus-visible .resize-line,
+  &:hover .resize-chip,
+  &:focus-visible .resize-chip {
+    opacity: 1;
+  }
+
+  .resize-line {
+    position: absolute;
+    left: 0;
+    right: 0;
+    top: 50%;
+    transform: translateY(-50%);
+    height: 2px;
+    background: ${color("pinkPrimary")};
+  }
+
+  .resize-chip {
+    position: absolute;
+    left: 50%;
+    top: 50%;
+    transform: translate(-50%, -50%) rotate(90deg);
+    line-height: 0;
+  }
+`
+
+type Props = {
+  targetRef: React.RefObject<HTMLElement | null>
+  onResize: (height: number) => void
+  onResizeEnd: (height: number) => void
+  onDoubleClick: () => void
+  minHeight?: number
+  background?: string
+  doubleView?: boolean
+  // The cell's bottom-edge handle: an absolute strip straddling the cell edge
+  // (vs the in-flow editor/result divider), so its chip shows outside the cell.
+  overlay?: boolean
+}
+
+export const ResizeHandle: React.FC<Props> = ({
+  targetRef,
+  onResize,
+  onResizeEnd,
+  onDoubleClick,
+  minHeight = 48,
+  background,
+  doubleView,
+  overlay,
+}) => {
+  const startYRef = useRef(0)
+  const startHeightRef = useRef(0)
+  const lastHeightRef = useRef(0)
+  const endDragRef = useRef<(() => void) | null>(null)
+
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault()
+      startYRef.current = e.clientY
+
+      if (!targetRef.current) return
+      startHeightRef.current = targetRef.current.getBoundingClientRect().height
+      lastHeightRef.current = startHeightRef.current
+
+      const handleMouseMove = (moveEvent: MouseEvent) => {
+        const delta = moveEvent.clientY - startYRef.current
+        const newHeight = Math.max(minHeight, startHeightRef.current + delta)
+        lastHeightRef.current = newHeight
+        onResize(newHeight)
+      }
+
+      const endDrag = () => {
+        document.removeEventListener("mousemove", handleMouseMove)
+        document.removeEventListener("mouseup", handleMouseUp)
+        document.body.style.cursor = ""
+        document.body.style.userSelect = ""
+        endDragRef.current = null
+      }
+
+      const handleMouseUp = () => {
+        endDrag()
+        onResizeEnd(lastHeightRef.current)
+      }
+
+      document.body.style.cursor = "ns-resize"
+      document.body.style.userSelect = "none"
+      document.addEventListener("mousemove", handleMouseMove)
+      document.addEventListener("mouseup", handleMouseUp)
+      endDragRef.current = endDrag
+    },
+    [targetRef, onResize, onResizeEnd, minHeight],
+  )
+
+  // Enter/Space on a focused handle resets to default. This is the only
+  // keyboard-accessible interaction we offer — mouse-drag resizing has no
+  // ergonomic keyboard equivalent here, so don't pretend otherwise in
+  // the aria-label.
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault()
+        onDoubleClick()
+      }
+    },
+    [onDoubleClick],
+  )
+
+  useEffect(() => () => endDragRef.current?.(), [])
+
+  return (
+    <Handle
+      $background={background}
+      $doubleView={doubleView}
+      $overlay={overlay}
+      onMouseDown={handleMouseDown}
+      onDoubleClick={onDoubleClick}
+      onKeyDown={handleKeyDown}
+      role="separator"
+      aria-orientation="horizontal"
+      // Sighted mouse users hover for the tooltip; screen-reader users
+      // hear the aria-label. Two audiences, two affordances.
+      aria-label="Resize handle. Press Enter to reset to default size."
+      title="Drag to resize. Double-click to reset."
+      tabIndex={0}
+    >
+      <span className="resize-line" />
+      <span className="resize-chip">
+        <SideChip />
+      </span>
+    </Handle>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/resize/chips.tsx b/src/scenes/Editor/Notebook/resize/chips.tsx
new file mode 100644
index 000000000..b44d57df7
--- /dev/null
+++ b/src/scenes/Editor/Notebook/resize/chips.tsx
@@ -0,0 +1,48 @@
+import React from "react"
+
+// Resize-handle grip chips — the exact Figma assets. The pink stroke + grip
+// dots render with `currentColor` (set to pinkPrimary by the handle) and the
+// chip fill uses `--chip-bg` (backgroundDarker), so both follow the theme.
+export const CornerChip = () => (
+  <svg width="18" height="18" viewBox="0 0 18 18" fill="none">
+    <path
+      d="M14 0.5H4C2.067 0.5 0.5 2.067 0.5 4V14C0.5 15.933 2.067 17.5 4 17.5H14C15.933 17.5 17.5 15.933 17.5 14V4C17.5 2.067 15.933 0.5 14 0.5Z"
+      fill="var(--chip-bg)"
+    />
+    <g fill="currentColor">
+      <path d="M8 8.25V9.75C8 9.88807 8.11193 10 8.25 10H9.75C9.88807 10 10 9.88807 10 9.75V8.25C10 8.11193 9.88807 8 9.75 8H8.25C8.11193 8 8 8.11193 8 8.25Z" />
+      <path d="M12 8.25V9.75C12 9.88807 12.1119 10 12.25 10H13.75C13.8881 10 14 9.88807 14 9.75V8.25C14 8.11193 13.8881 8 13.75 8H12.25C12.1119 8 12 8.11193 12 8.25Z" />
+      <path d="M4 4.25V5.75C4 5.88807 4.11193 6 4.25 6H5.75C5.88807 6 6 5.88807 6 5.75V4.25C6 4.11193 5.88807 4 5.75 4H4.25C4.11193 4 4 4.11193 4 4.25Z" />
+      <path d="M12 12.25V13.75C12 13.8881 12.1119 14 12.25 14H13.75C13.8881 14 14 13.8881 14 13.75V12.25C14 12.1119 13.8881 12 13.75 12H12.25C12.1119 12 12 12.1119 12 12.25Z" />
+      <path d="M8 4.25V5.75C8 5.88807 8.11193 6 8.25 6H9.75C9.88807 6 10 5.88807 10 5.75V4.25C10 4.11193 9.88807 4 9.75 4H8.25C8.11193 4 8 4.11193 8 4.25Z" />
+      <path d="M12 4.25V5.75C12 5.88807 12.1119 6 12.25 6H13.75C13.8881 6 14 5.88807 14 5.75V4.25C14 4.11193 13.8881 4 13.75 4H12.25C12.1119 4 12 4.11193 12 4.25Z" />
+    </g>
+    <path
+      d="M14 0.5H4C2.067 0.5 0.5 2.067 0.5 4V14C0.5 15.933 2.067 17.5 4 17.5H14C15.933 17.5 17.5 15.933 17.5 14V4C17.5 2.067 15.933 0.5 14 0.5Z"
+      stroke="currentColor"
+    />
+  </svg>
+)
+
+export const SideChip = () => (
+  <svg width="16" height="24" viewBox="0 0 16 24" fill="none">
+    <path
+      d="M12 0.5H4C2.067 0.5 0.5 2.067 0.5 4V20C0.5 21.933 2.067 23.5 4 23.5H12C13.933 23.5 15.5 21.933 15.5 20V4C15.5 2.067 13.933 0.5 12 0.5Z"
+      fill="var(--chip-bg)"
+    />
+    <g fill="currentColor">
+      <path d="M6.75 5H5.25C5.11193 5 5 5.11193 5 5.25V6.75C5 6.88807 5.11193 7 5.25 7H6.75C6.88807 7 7 6.88807 7 6.75V5.25C7 5.11193 6.88807 5 6.75 5Z" />
+      <path d="M10.75 5H9.25C9.11193 5 9 5.11193 9 5.25V6.75C9 6.88807 9.11193 7 9.25 7H10.75C10.8881 7 11 6.88807 11 6.75V5.25C11 5.11193 10.8881 5 10.75 5Z" />
+      <path d="M6.75 9H5.25C5.11193 9 5 9.11193 5 9.25V10.75C5 10.8881 5.11193 11 5.25 11H6.75C6.88807 11 7 10.8881 7 10.75V9.25C7 9.11193 6.88807 9 6.75 9Z" />
+      <path d="M10.75 9H9.25C9.11193 9 9 9.11193 9 9.25V10.75C9 10.8881 9.11193 11 9.25 11H10.75C10.8881 11 11 10.8881 11 10.75V9.25C11 9.11193 10.8881 9 10.75 9Z" />
+      <path d="M10.75 13H9.25C9.11193 13 9 13.1119 9 13.25V14.75C9 14.8881 9.11193 15 9.25 15H10.75C10.8881 15 11 14.8881 11 14.75V13.25C11 13.1119 10.8881 13 10.75 13Z" />
+      <path d="M10.75 17H9.25C9.11193 17 9 17.1119 9 17.25V18.75C9 18.8881 9.11193 19 9.25 19H10.75C10.8881 19 11 18.8881 11 18.75V17.25C11 17.1119 10.8881 17 10.75 17Z" />
+      <path d="M6.75 13H5.25C5.11193 13 5 13.1119 5 13.25V14.75C5 14.8881 5.11193 15 5.25 15H6.75C6.88807 15 7 14.8881 7 14.75V13.25C7 13.1119 6.88807 13 6.75 13Z" />
+      <path d="M6.75 17H5.25C5.11193 17 5 17.1119 5 17.25V18.75C5 18.8881 5.11193 19 5.25 19H6.75C6.88807 19 7 18.8881 7 18.75V17.25C7 17.1119 6.88807 17 6.75 17Z" />
+    </g>
+    <path
+      d="M12 0.5H4C2.067 0.5 0.5 2.067 0.5 4V20C0.5 21.933 2.067 23.5 4 23.5H12C13.933 23.5 15.5 21.933 15.5 20V4C15.5 2.067 13.933 0.5 12 0.5Z"
+      stroke="currentColor"
+    />
+  </svg>
+)
diff --git a/src/scenes/Editor/Notebook/resize/index.ts b/src/scenes/Editor/Notebook/resize/index.ts
new file mode 100644
index 000000000..4b611aea7
--- /dev/null
+++ b/src/scenes/Editor/Notebook/resize/index.ts
@@ -0,0 +1,2 @@
+export { ResizeHandle } from "./ResizeHandle"
+export { EdgeHandle, renderEdgeHandle } from "./EdgeHandle"
diff --git a/src/scenes/Editor/Notebook/result-table/InlineResultTable.tsx b/src/scenes/Editor/Notebook/result-table/InlineResultTable.tsx
new file mode 100644
index 000000000..3360ebde0
--- /dev/null
+++ b/src/scenes/Editor/Notebook/result-table/InlineResultTable.tsx
@@ -0,0 +1,71 @@
+import React from "react"
+import type { CellResult } from "../../../../store/notebook"
+import { ResultGridPanel } from "./ResultGridPanel"
+import { StatusNotification } from "./StatusNotification"
+import { TabBar } from "./TabBar"
+import { ResultWrapper, SuccessMessage } from "./styles"
+
+type Props = {
+  result: CellResult
+  isFocused?: boolean
+  onTabChange?: (index: number) => void
+  onCancelQuery?: (index: number) => void
+  bufferId?: number
+  cellId: string
+  isRunning?: boolean
+  onReRun?: (index: number) => void
+  onYieldFocus?: () => void
+}
+
+export const InlineResultTable: React.FC<Props> = ({
+  result,
+  isFocused,
+  onTabChange,
+  onCancelQuery,
+  bufferId,
+  cellId,
+  isRunning,
+  onReRun,
+  onYieldFocus,
+}) => {
+  if (result.results.length === 0) {
+    return (
+      <ResultWrapper>
+        <SuccessMessage>OK</SuccessMessage>
+      </ResultWrapper>
+    )
+  }
+
+  const activeResult =
+    result.results[result.activeResultIndex] ?? result.results[0]
+  const isMultiQuery = result.results.length > 1
+
+  return (
+    <ResultWrapper>
+      {isMultiQuery && <TabBar result={result} onTabChange={onTabChange} />}
+
+      {activeResult && (
+        <StatusNotification
+          timestamp={result.timestamp}
+          activeResult={activeResult}
+          activeIndex={result.activeResultIndex}
+          onCancelQuery={onCancelQuery}
+        />
+      )}
+
+      {activeResult?.type === "dql" && activeResult.dataset.length > 0 && (
+        <ResultGridPanel
+          key={`${result.activeResultIndex}-${activeResult.query}`}
+          data={activeResult}
+          runToken={result.timestamp}
+          isFocused={isFocused}
+          bufferId={bufferId}
+          cellId={cellId}
+          isRunning={isRunning}
+          onReRun={() => onReRun?.(result.activeResultIndex)}
+          onYieldFocus={onYieldFocus}
+        />
+      )}
+    </ResultWrapper>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/result-table/ResultActionsBar.tsx b/src/scenes/Editor/Notebook/result-table/ResultActionsBar.tsx
new file mode 100644
index 000000000..147adb000
--- /dev/null
+++ b/src/scenes/Editor/Notebook/result-table/ResultActionsBar.tsx
@@ -0,0 +1,165 @@
+import React, { useState } from "react"
+import { Download2, Refresh, ArrowDownS } from "@styled-icons/remix-line"
+import { Reset } from "@styled-icons/boxicons-regular"
+import { HandPointLeft } from "@styled-icons/fa-regular"
+import { TableFreezeColumn } from "@styled-icons/fluentui-system-filled"
+import { Markdown } from "@styled-icons/bootstrap/Markdown"
+import { Check } from "@styled-icons/bootstrap/Check"
+import { DropdownMenu, Tooltip } from "../../../../components"
+import type { DqlQueryResult } from "../../../../store/notebook"
+import {
+  buildResultPageMarkdown,
+  type ResultGridHandle,
+} from "../../../../components/ResultGrid"
+import { copyToClipboard } from "../../../../utils/copyToClipboard"
+import { downloadQueryResult } from "../../../../utils/downloadQueryResult"
+import { trackEvent } from "../../../../modules/ConsoleEventTracker"
+import { ConsoleEvent } from "../../../../modules/ConsoleEventTracker/events"
+import { useNotebookActions } from "../NotebookProvider"
+import { expandGlobals } from "../declareUtils"
+import { ActionButton, ActionsBar, FreezeToggle } from "./styles"
+
+const preventFocusSteal = (e: React.MouseEvent) => e.preventDefault()
+
+type Props = {
+  data: DqlQueryResult
+  gridRef: React.RefObject<ResultGridHandle | null>
+  isFrozen: boolean
+  hasSelection: boolean
+  isRunning?: boolean
+  onReRun?: () => void
+}
+
+export const ResultActionsBar: React.FC<Props> = ({
+  data,
+  gridRef,
+  isFrozen,
+  hasSelection,
+  isRunning,
+  onReRun,
+}) => {
+  const { getVariables } = useNotebookActions()
+  const [isCopied, setIsCopied] = useState(false)
+
+  const copyMarkdown = () => {
+    void trackEvent(ConsoleEvent.GRID_MARKDOWN_COPY, { source: "notebook" })
+    void copyToClipboard(
+      buildResultPageMarkdown(data.columns, data.dataset),
+    ).then(() => {
+      setIsCopied(true)
+      setTimeout(() => setIsCopied(false), 1000)
+    })
+  }
+
+  const toggleFreeze = () => {
+    void trackEvent(ConsoleEvent.GRID_COLUMN_FREEZE, { source: "notebook" })
+    gridRef.current?.toggleFreezeLeft()
+  }
+
+  const moveColumnToFront = () => {
+    void trackEvent(ConsoleEvent.GRID_COLUMN_MOVE_TO_FRONT, {
+      source: "notebook",
+    })
+    gridRef.current?.shuffleFocusedColumnToFront()
+  }
+
+  const resetLayout = () => {
+    void trackEvent(ConsoleEvent.GRID_LAYOUT_RESET, { source: "notebook" })
+    gridRef.current?.resetLayout()
+  }
+
+  const reRun = () => {
+    void trackEvent(ConsoleEvent.GRID_REFRESH, { source: "notebook" })
+    onReRun?.()
+  }
+
+  const download = (format: "parquet" | "csv") => {
+    void trackEvent(
+      format === "parquet"
+        ? ConsoleEvent.GRID_PARQUET_DOWNLOAD
+        : ConsoleEvent.GRID_CSV_DOWNLOAD,
+      { source: "notebook" },
+    )
+    downloadQueryResult(expandGlobals(data.query, getVariables()), format)
+  }
+
+  return (
+    <ActionsBar>
+      <Tooltip delay={350} placement="bottom" content="Copy result to Markdown">
+        <ActionButton
+          skin="transparent"
+          aria-label="Copy result to Markdown"
+          onClick={copyMarkdown}
+        >
+          {isCopied ? <Check size="18px" /> : <Markdown size="18px" />}
+        </ActionButton>
+      </Tooltip>
+
+      <Tooltip delay={350} placement="bottom" content="Freeze left column">
+        <FreezeToggle
+          selected={isFrozen}
+          aria-label="Freeze left column"
+          onClick={toggleFreeze}
+        >
+          <TableFreezeColumn size="18px" style={{ transform: "scaleX(-1)" }} />
+        </FreezeToggle>
+      </Tooltip>
+
+      <Tooltip
+        delay={350}
+        placement="bottom"
+        content="Move selected column to the front"
+      >
+        <ActionButton
+          skin="transparent"
+          aria-label="Move selected column to the front"
+          disabled={!hasSelection}
+          onMouseDown={preventFocusSteal}
+          onClick={moveColumnToFront}
+        >
+          <HandPointLeft size="18px" />
+        </ActionButton>
+      </Tooltip>
+
+      <Tooltip delay={350} placement="bottom" content="Reset grid layout">
+        <ActionButton
+          skin="transparent"
+          aria-label="Reset grid layout"
+          onClick={resetLayout}
+        >
+          <Reset size="18px" />
+        </ActionButton>
+      </Tooltip>
+
+      <Tooltip delay={350} placement="bottom" content="Re-run cell">
+        <ActionButton
+          skin="transparent"
+          aria-label="Re-run cell"
+          disabled={isRunning || !onReRun}
+          onClick={reRun}
+        >
+          <Refresh size="18px" />
+        </ActionButton>
+      </Tooltip>
+
+      <DropdownMenu.Root modal={false}>
+        <DropdownMenu.Trigger asChild>
+          <ActionButton skin="transparent" aria-label="Download result">
+            <Download2 size="18px" />
+            <ArrowDownS size="14px" />
+          </ActionButton>
+        </DropdownMenu.Trigger>
+        <DropdownMenu.Portal>
+          <DropdownMenu.Content sideOffset={4} align="end">
+            <DropdownMenu.Item onSelect={() => download("parquet")}>
+              Download as Parquet
+            </DropdownMenu.Item>
+            <DropdownMenu.Item onSelect={() => download("csv")}>
+              Download as CSV
+            </DropdownMenu.Item>
+          </DropdownMenu.Content>
+        </DropdownMenu.Portal>
+      </DropdownMenu.Root>
+    </ActionsBar>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/result-table/ResultGridPanel.tsx b/src/scenes/Editor/Notebook/result-table/ResultGridPanel.tsx
new file mode 100644
index 000000000..93841fb78
--- /dev/null
+++ b/src/scenes/Editor/Notebook/result-table/ResultGridPanel.tsx
@@ -0,0 +1,114 @@
+import React, { useMemo, useRef, useState } from "react"
+import {
+  ResultGrid,
+  inMemoryDataSource,
+  type ResultGridHandle,
+} from "../../../../components/ResultGrid"
+import type { DqlQueryResult } from "../../../../store/notebook"
+import { trackEvent } from "../../../../modules/ConsoleEventTracker"
+import { ConsoleEvent } from "../../../../modules/ConsoleEventTracker/events"
+import { normalizeSql } from "../../../../utils/formatSql"
+import { sqlHash } from "../notebookUtils"
+import {
+  loadNotebookColumnLayout,
+  saveNotebookColumnLayout,
+  removeNotebookColumnLayout,
+} from "../notebookColumnLayoutStore"
+import { ResultActionsBar } from "./ResultActionsBar"
+
+type Props = {
+  data: DqlQueryResult
+  runToken?: number
+  isFocused?: boolean
+  bufferId?: number
+  cellId: string
+  isRunning?: boolean
+  onReRun?: () => void
+  onYieldFocus?: () => void
+}
+
+// Owns the grid ref and the per-result action state (selection enables
+// move-to-front, pinned count drives the freeze toggle). Mounted keyed by query
+// in InlineResultTable, so this state resets on result change without an effect.
+export const ResultGridPanel: React.FC<Props> = ({
+  data,
+  runToken,
+  isFocused,
+  bufferId,
+  cellId,
+  isRunning,
+  onReRun,
+  onYieldFocus,
+}) => {
+  const gridRef = useRef<ResultGridHandle | null>(null)
+
+  const dataSource = useMemo(
+    () => inMemoryDataSource(data.columns, data.dataset, data.timestamp ?? -1),
+    [data],
+  )
+  const queryKey = useMemo(() => {
+    try {
+      return "q" + sqlHash(normalizeSql(data.query, false))
+    } catch {
+      return "q" + sqlHash(data.query.trim())
+    }
+  }, [data.query])
+  const initialLayout = useMemo(
+    () => loadNotebookColumnLayout(bufferId, cellId, queryKey),
+    [bufferId, cellId, queryKey],
+  )
+
+  const [hasSelection, setHasSelection] = useState(false)
+  const [pinnedCount, setPinnedCount] = useState(
+    initialLayout?.pinnedColumns?.length ?? 0,
+  )
+
+  return (
+    <>
+      <ResultActionsBar
+        data={data}
+        gridRef={gridRef}
+        isFrozen={pinnedCount > 0}
+        hasSelection={hasSelection}
+        isRunning={isRunning}
+        onReRun={onReRun}
+      />
+      <ResultGrid
+        ref={gridRef}
+        dataSource={dataSource}
+        runToken={runToken}
+        isFocused={isFocused}
+        initialColumnSizing={initialLayout?.columnSizing}
+        initialColumnOrder={initialLayout?.columnOrder}
+        initialPinnedColumns={initialLayout?.pinnedColumns}
+        onColumnSizingCommit={(sizing) =>
+          saveNotebookColumnLayout(bufferId, cellId, queryKey, {
+            columnSizing: sizing,
+          })
+        }
+        onColumnOrderCommit={(order) =>
+          saveNotebookColumnLayout(bufferId, cellId, queryKey, {
+            columnOrder: order,
+          })
+        }
+        onPinnedColumnsCommit={(pinned) => {
+          saveNotebookColumnLayout(bufferId, cellId, queryKey, {
+            pinnedColumns: pinned,
+          })
+          setPinnedCount(pinned.length)
+        }}
+        onResetLayout={() =>
+          removeNotebookColumnLayout(bufferId, cellId, queryKey)
+        }
+        onSelectionChange={setHasSelection}
+        onYieldFocus={onYieldFocus}
+        onCellCopy={() =>
+          void trackEvent(ConsoleEvent.GRID_CELL_COPY, { source: "notebook" })
+        }
+        onColumnCopy={() =>
+          void trackEvent(ConsoleEvent.GRID_COLUMN_COPY, { source: "notebook" })
+        }
+      />
+    </>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/result-table/StatusNotification.tsx b/src/scenes/Editor/Notebook/result-table/StatusNotification.tsx
new file mode 100644
index 000000000..66954f9a6
--- /dev/null
+++ b/src/scenes/Editor/Notebook/result-table/StatusNotification.tsx
@@ -0,0 +1,140 @@
+import React from "react"
+import { Stop } from "@styled-icons/remix-line"
+import { Queue } from "@phosphor-icons/react"
+import { Box, Text } from "../../../../components"
+import Notification from "../../../Notifications/Notification"
+import { NotificationType } from "../../../../store/Query/types"
+import type { CellResult, SingleQueryResult } from "../../../../store/notebook"
+import QueryResult from "../../QueryResult"
+import { CancelButton, LiveRegion, NotificationContainer } from "./styles"
+
+const liveRegionMessage = (result: SingleQueryResult): string => {
+  switch (result.type) {
+    case "running":
+      return "Query running"
+    case "queued":
+      return "Query queued"
+    case "cancelled":
+      return "Query cancelled by user"
+    case "error":
+      return `Query failed: ${result.error}`
+    case "dql":
+      return `Query succeeded: ${result.dataset.length} rows`
+    default:
+      return "Query succeeded"
+  }
+}
+
+type Props = {
+  timestamp: number
+  activeResult: SingleQueryResult
+  activeIndex: CellResult["activeResultIndex"]
+  onCancelQuery?: (index: number) => void
+}
+
+export const StatusNotification: React.FC<Props> = ({
+  timestamp,
+  activeResult,
+  activeIndex,
+  onCancelQuery,
+}) => {
+  const { type } = activeResult
+  const isError = type === "error"
+  const isCancelled = type === "cancelled"
+
+  const baseProps = {
+    query: "@0-0" as const,
+    createdAt: new Date(timestamp),
+    compact: true,
+    isMinimized: true,
+  }
+
+  let body: React.ReactElement
+  if (type === "running") {
+    body = (
+      <Notification
+        {...baseProps}
+        content={
+          <Box gap="1rem" align="center">
+            <Text color="foreground">Running...</Text>
+            {onCancelQuery && (
+              <CancelButton
+                skin="error"
+                onClick={() => onCancelQuery(activeIndex)}
+              >
+                <Stop size="18px" />
+              </CancelButton>
+            )}
+          </Box>
+        }
+        type={NotificationType.LOADING}
+      />
+    )
+  } else if (type === "queued") {
+    body = (
+      <Notification
+        {...baseProps}
+        content={
+          <Box gap="1rem" align="center">
+            <Queue size={16} />
+            <Text color="foreground">Queued</Text>
+          </Box>
+        }
+        type={NotificationType.INFO}
+      />
+    )
+  } else if (isCancelled) {
+    body = (
+      <Notification
+        {...baseProps}
+        content={<span>Cancelled by user</span>}
+        type={NotificationType.ERROR}
+      />
+    )
+  } else if (isError) {
+    body = (
+      <Notification
+        {...baseProps}
+        content={<span>{activeResult.error}</span>}
+        type={NotificationType.ERROR}
+      />
+    )
+  } else if (activeResult.type === "dql" && activeResult.timings) {
+    body = (
+      <Notification
+        {...baseProps}
+        content={
+          <QueryResult
+            rowCount={activeResult.dataset.length}
+            totalRowCount={activeResult.count}
+            count={activeResult.timings.count}
+            compiler={activeResult.timings.compiler}
+            authentication={activeResult.timings.authentication}
+            execute={activeResult.timings.execute}
+            fetch={activeResult.timings.fetch}
+          />
+        }
+        type={NotificationType.SUCCESS}
+      />
+    )
+  } else {
+    body = (
+      <Notification
+        {...baseProps}
+        content={<span>OK</span>}
+        type={NotificationType.SUCCESS}
+      />
+    )
+  }
+
+  return (
+    <NotificationContainer
+      role={isError || isCancelled ? "alert" : "status"}
+      aria-live={isError || isCancelled ? "assertive" : "polite"}
+      aria-atomic="true"
+    >
+      <LiveRegion>{liveRegionMessage(activeResult)}</LiveRegion>
+      {body}
+    </NotificationContainer>
+  )
+}
diff --git a/src/scenes/Editor/Notebook/result-table/TabBar.tsx b/src/scenes/Editor/Notebook/result-table/TabBar.tsx
new file mode 100644
index 000000000..a5ecbbf64
--- /dev/null
+++ b/src/scenes/Editor/Notebook/result-table/TabBar.tsx
@@ -0,0 +1,81 @@
+import React from "react"
+import { CheckmarkOutline, CloseOutline } from "@styled-icons/evaicons-outline"
+import { Queue } from "@phosphor-icons/react"
+import type { CellResult, SingleQueryResult } from "../../../../store/notebook"
+import { LoadingIconSvg } from "../../Monaco/icons"
+import {
+  CancelledIcon,
+  Tab,
+  TabBarWrapper,
+  TabLabel,
+  TabSpinner,
+  TabStatusIcon,
+} from "./styles"
+
+const truncateQuery = (query: string, maxLen = 30): string => {
+  const oneLine = query.replace(/\s+/g, " ").trim()
+  return oneLine.length > maxLen
+    ? oneLine.substring(0, maxLen) + "..."
+    : oneLine
+}
+
+const StatusIcon: React.FC<{ type: SingleQueryResult["type"] }> = ({
+  type,
+}) => {
+  if (type === "running") {
+    return (
+      <TabSpinner>
+        <LoadingIconSvg />
+      </TabSpinner>
+    )
+  }
+  if (type === "queued") {
+    return (
+      <CancelledIcon>
+        <Queue size={18} />
+      </CancelledIcon>
+    )
+  }
+  if (type === "cancelled") {
+    return (
+      <CancelledIcon>
+        <CloseOutline size="18px" />
+      </CancelledIcon>
+    )
+  }
+  return (
+    <TabStatusIcon $success={type !== "error"}>
+      {type === "error" ? (
+        <CloseOutline size="18px" />
+      ) : (
+        <CheckmarkOutline size="18px" />
+      )}
+    </TabStatusIcon>
+  )
+}
+
+type Props = {
+  result: CellResult
+  onTabChange?: (index: number) => void
+}
+
+export const TabBar: React.FC<Props> = ({ result, onTabChange }) => (
+  <TabBarWrapper role="tablist">
+    {result.results.map((r, i) => (
+      <Tab
+        // Positional identity — duplicate SQL across statements is legal
+        // (e.g. `SELECT 1; SELECT 1;`) and would collapse if keyed on query.
+        // eslint-disable-next-line react/no-array-index-key
+        key={i}
+        $active={i === result.activeResultIndex}
+        onClick={() => onTabChange?.(i)}
+        title={r.query}
+        role="tab"
+        aria-selected={i === result.activeResultIndex}
+      >
+        <StatusIcon type={r.type} />
+        <TabLabel>{truncateQuery(r.query)}</TabLabel>
+      </Tab>
+    ))}
+  </TabBarWrapper>
+)
diff --git a/src/scenes/Editor/Notebook/result-table/index.ts b/src/scenes/Editor/Notebook/result-table/index.ts
new file mode 100644
index 000000000..b3b4127aa
--- /dev/null
+++ b/src/scenes/Editor/Notebook/result-table/index.ts
@@ -0,0 +1 @@
+export { InlineResultTable } from "./InlineResultTable"
diff --git a/src/scenes/Editor/Notebook/result-table/styles.ts b/src/scenes/Editor/Notebook/result-table/styles.ts
new file mode 100644
index 000000000..c77b4cfd9
--- /dev/null
+++ b/src/scenes/Editor/Notebook/result-table/styles.ts
@@ -0,0 +1,166 @@
+import styled, { css } from "styled-components"
+import { color } from "../../../../utils"
+import { Button, PrimaryToggleButton } from "../../../../components"
+
+export const ResultWrapper = styled.div`
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+`
+
+export const SuccessMessage = styled.div`
+  padding: 0.6rem 0.8rem;
+  color: ${color("green")};
+  font-size: ${({ theme }) => theme.fontSize.sm};
+  background: ${color("backgroundDarker")};
+`
+
+export const TabBarWrapper = styled.div`
+  display: flex;
+  flex-shrink: 0;
+  overflow-x: auto;
+  gap: 0;
+  height: 4rem;
+  border-top: 1px solid ${color("backgroundDarker")};
+
+  &::-webkit-scrollbar {
+    height: 0;
+  }
+`
+
+export const TabLabel = styled.span`
+  line-height: 1.2;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+`
+
+export const Tab = styled.button<{ $active: boolean }>`
+  display: flex;
+  align-items: center;
+  padding: 0.5rem 1rem;
+  border: none;
+  background: transparent;
+  color: ${color("gray2")};
+  cursor: pointer;
+  max-width: 20rem;
+  min-width: 15rem;
+  border-bottom: 2px solid transparent;
+
+  border-right: 1px solid ${color("selection")};
+  flex-shrink: 0;
+  gap: 0.8rem;
+  overflow: hidden;
+  position: relative;
+  transition: all 0.2s ease;
+
+  ${({ $active }) =>
+    $active &&
+    css`
+      color: ${color("foreground")};
+      background: ${color("selection")};
+      border-bottom: 2px solid ${color("pinkPrimary")};
+    `}
+
+  ${({ $active }) =>
+    !$active &&
+    css`
+      &:hover {
+        background: ${color("selectionDarker")};
+        border-bottom: 2px solid ${color("selection")};
+      }
+    `}
+`
+
+export const TabStatusIcon = styled.span<{ $success: boolean }>`
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: ${({ $success }) => ($success ? color("green") : color("red"))};
+`
+
+export const TabSpinner = styled.span`
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+  animation: tab-spin 3s linear infinite;
+
+  @keyframes tab-spin {
+    from {
+      transform: rotate(0deg);
+    }
+    to {
+      transform: rotate(360deg);
+    }
+  }
+
+  svg {
+    width: 18px;
+    height: 18px;
+  }
+`
+
+export const CancelledIcon = styled.span`
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: ${color("gray2")};
+`
+
+export const CancelButton = styled(Button)`
+  padding: 1.2rem 0.6rem;
+`
+
+export const NotificationContainer = styled.div`
+  border-top: 1px solid ${color("backgroundDarker")};
+  border-bottom: 1px solid ${color("backgroundDarker")};
+`
+
+export const LiveRegion = styled.div`
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+`
+
+export const ActionsBar = styled.div`
+  display: flex;
+  flex-shrink: 0;
+  align-items: center;
+  gap: 0.4rem;
+  height: 3.6rem;
+  padding: 0 0.8rem;
+  overflow-x: auto;
+  background: ${color("backgroundDarker")};
+  border-bottom: 1px solid ${color("selection")};
+
+  &::-webkit-scrollbar {
+    height: 0;
+  }
+
+  > *:first-child {
+    margin-left: auto;
+  }
+`
+
+export const ActionButton = styled(Button)`
+  flex-shrink: 0;
+  height: 2.8rem;
+  min-width: 2.8rem;
+  padding: 0 0.6rem;
+  gap: 0.3rem;
+`
+
+export const FreezeToggle = styled(PrimaryToggleButton)`
+  flex-shrink: 0;
+  height: 2.8rem;
+  width: 3.2rem;
+  padding: 0;
+`
diff --git a/src/scenes/Editor/Notebook/useCellExecution.ts b/src/scenes/Editor/Notebook/useCellExecution.ts
new file mode 100644
index 000000000..694ce4342
--- /dev/null
+++ b/src/scenes/Editor/Notebook/useCellExecution.ts
@@ -0,0 +1,434 @@
+import { useCallback, useEffect, useRef, useState } from "react"
+import type { Dispatch, MutableRefObject, SetStateAction } from "react"
+import type {
+  CellResult,
+  NotebookCell,
+  SingleQueryResult,
+} from "../../../store/notebook"
+import type { QueryExecResult } from "../../../hooks/useQueryExecution"
+import { eventBus } from "../../../modules/EventBus"
+import { EventType } from "../../../modules/EventBus/types"
+import { getQueriesFromText } from "../Monaco/utils"
+import {
+  buildInitialScriptResults,
+  capResultBytes,
+  NOTEBOOK_BYTE_CAP,
+  NOTEBOOK_ROW_CAP,
+  singleResultFromExec,
+  sqlHash,
+} from "./notebookUtils"
+import { persistCellSnapshot } from "./persistCellSnapshot"
+import { deleteCellSnapshot } from "../../../store/notebookResults"
+
+// Schema panel + completions listen for MSG_QUERY_SCHEMA to refresh.
+const publishSchemaIfMutating = (type: QueryExecResult["type"]): void => {
+  if (type === "ddl" || type === "dml") {
+    eventBus.publish(EventType.MSG_QUERY_SCHEMA)
+  }
+}
+
+const beginCellRun = (
+  runGenerationRef: MutableRefObject<Map<string, number>>,
+  cellId: string,
+) => {
+  const generation = (runGenerationRef.current.get(cellId) ?? 0) + 1
+  runGenerationRef.current.set(cellId, generation)
+
+  return () => runGenerationRef.current.get(cellId) === generation
+}
+
+const supersedeCellRun = (
+  runGenerationRef: MutableRefObject<Map<string, number>>,
+  cellId: string,
+) => {
+  runGenerationRef.current.set(
+    cellId,
+    (runGenerationRef.current.get(cellId) ?? 0) + 1,
+  )
+}
+
+const clearRunningCell = (
+  abortControllersRef: MutableRefObject<Map<string, AbortController[]>>,
+  autoFocusRef: MutableRefObject<Map<string, boolean>>,
+  setRunningCellIds: Dispatch<SetStateAction<Set<string>>>,
+  cellId: string,
+) => {
+  abortControllersRef.current.delete(cellId)
+  autoFocusRef.current.delete(cellId)
+  setRunningCellIds((prev) => {
+    const next = new Set(prev)
+    next.delete(cellId)
+    return next
+  })
+}
+
+type Options = {
+  bufferId: number
+  cellsRef: MutableRefObject<NotebookCell[]>
+  executeSingle: (
+    sql: string,
+    signal?: AbortSignal,
+    limit?: number,
+  ) => Promise<QueryExecResult>
+  updateCellResult: (
+    cellId: string,
+    index: number,
+    result: SingleQueryResult,
+    activeIndex?: number,
+  ) => void
+  updateCell: (cellId: string, updates: Partial<NotebookCell>) => void
+  updateCells: (updater: (prev: NotebookCell[]) => NotebookCell[]) => void
+  markCancelledAll: (cellId: string) => void
+  markCancelledOne: (cellId: string, index: number) => void
+  setScriptSummary: (
+    cellId: string,
+    summary: { successCount: number; failedCount: number; durationMs: number },
+  ) => void
+}
+
+export const useCellExecution = ({
+  bufferId,
+  cellsRef,
+  executeSingle,
+  updateCellResult,
+  updateCell,
+  updateCells,
+  markCancelledAll,
+  markCancelledOne,
+  setScriptSummary,
+}: Options) => {
+  const [runningCellIds, setRunningCellIds] = useState<Set<string>>(new Set())
+
+  const abortControllersRef = useRef<Map<string, AbortController[]>>(new Map())
+
+  const runGenerationRef = useRef<Map<string, number>>(new Map())
+
+  const autoFocusRef = useRef<Map<string, boolean>>(new Map())
+
+  // Persist a faithful, already-capped copy of the cell's result so it survives
+  // tab-switch / reload. One record per cell (mode-agnostic). Keyed to the
+  // executed SQL — not the cell's live value, which the user may have edited
+  // mid-run — so restore never attributes these rows to a different query.
+  const persistSnapshot = useCallback(
+    (cellId: string, executedSql: string, explicitResult?: CellResult) => {
+      const cell = cellsRef.current.find((c) => c.id === cellId)
+      if (!cell) return
+      const result = explicitResult ?? cell.result
+      if (!result) return
+      persistCellSnapshot({
+        bufferId,
+        cellId,
+        sqlHash: sqlHash(executedSql),
+        results: result.results,
+        savedAt: Date.now(),
+      })
+    },
+    [bufferId, cellsRef],
+  )
+
+  const runScript = useCallback(
+    async (
+      cellId: string,
+      queryText: string,
+      queries: string[],
+      externalSignal?: AbortSignal,
+    ): Promise<boolean> => {
+      if (queries.length === 0) return false
+
+      const prior = abortControllersRef.current.get(cellId)
+      prior?.forEach((c) => c.abort())
+
+      const isCurrentRun = beginCellRun(runGenerationRef, cellId)
+
+      // One AbortController per query so `cancelQuery(index)` cancels just that slot.
+      const controllers = queries.map(() => new AbortController())
+      const onExternalAbort = () =>
+        controllers.forEach((c) => c.abort(externalSignal?.reason))
+      if (externalSignal?.aborted) {
+        onExternalAbort()
+      } else {
+        externalSignal?.addEventListener("abort", onExternalAbort, {
+          once: true,
+        })
+      }
+      abortControllersRef.current.set(cellId, controllers)
+      autoFocusRef.current.set(cellId, true)
+
+      const startTime = Date.now()
+
+      const initialCellResult: CellResult = {
+        results: buildInitialScriptResults(queries),
+        activeResultIndex: 0,
+        timestamp: Date.now(),
+      }
+      updateCell(cellId, { result: initialCellResult })
+
+      setRunningCellIds((prev) => new Set(prev).add(cellId))
+
+      let successCount = 0
+      let failedCount = 0
+
+      try {
+        for (let i = 0; i < queries.length; i++) {
+          const perQuery = controllers[i]
+          if (perQuery.signal.aborted) {
+            for (let j = i; j < queries.length; j++) {
+              updateCellResult(cellId, j, {
+                type: "cancelled",
+                query: queries[j],
+              })
+            }
+            break
+          }
+
+          const sql = queries[i]
+          const isAuto = autoFocusRef.current.get(cellId)
+          updateCellResult(
+            cellId,
+            i,
+            { type: "running", query: sql },
+            isAuto ? i : undefined,
+          )
+
+          const result = await executeSingle(
+            sql,
+            perQuery.signal,
+            NOTEBOOK_ROW_CAP,
+          )
+          if (!isCurrentRun()) return failedCount === 0
+          updateCellResult(
+            cellId,
+            i,
+            capResultBytes(
+              singleResultFromExec(result, sql),
+              NOTEBOOK_BYTE_CAP,
+            ),
+          )
+          publishSchemaIfMutating(result.type)
+
+          if (result.type === "error") {
+            failedCount++
+            for (let j = i + 1; j < queries.length; j++) {
+              updateCellResult(cellId, j, {
+                type: "cancelled",
+                query: queries[j],
+              })
+            }
+            break
+          }
+          successCount++
+        }
+
+        setScriptSummary(cellId, {
+          successCount,
+          failedCount,
+          durationMs: Date.now() - startTime,
+        })
+        persistSnapshot(cellId, queryText)
+      } finally {
+        externalSignal?.removeEventListener("abort", onExternalAbort)
+        if (isCurrentRun()) {
+          clearRunningCell(
+            abortControllersRef,
+            autoFocusRef,
+            setRunningCellIds,
+            cellId,
+          )
+        }
+      }
+
+      return failedCount === 0
+    },
+    [
+      executeSingle,
+      updateCell,
+      updateCellResult,
+      setScriptSummary,
+      persistSnapshot,
+    ],
+  )
+
+  const runCell = useCallback(
+    async (
+      cellId: string,
+      sql?: string,
+      externalSignal?: AbortSignal,
+    ): Promise<boolean> => {
+      const cell = cellsRef.current.find((c) => c.id === cellId)
+      if (!cell) return false
+      // Markdown cells hold prose, not SQL — never execute them.
+      if (cell.type === "markdown") return false
+
+      const queryText = sql ?? cell.value
+      if (!queryText.trim()) return false
+      if (externalSignal?.aborted) return false
+
+      const queries = getQueriesFromText(queryText)
+      if (queries.length > 1) {
+        return runScript(cellId, queryText, queries, externalSignal)
+      }
+
+      const prior = abortControllersRef.current.get(cellId)
+      prior?.forEach((c) => c.abort())
+
+      const isCurrentRun = beginCellRun(runGenerationRef, cellId)
+
+      const ac = new AbortController()
+      const onExternalAbort = () => ac.abort(externalSignal?.reason)
+      externalSignal?.addEventListener("abort", onExternalAbort, {
+        once: true,
+      })
+      abortControllersRef.current.set(cellId, [ac])
+
+      const runningResult: CellResult = {
+        results: [{ type: "running", query: queryText }],
+        activeResultIndex: 0,
+        timestamp: Date.now(),
+      }
+      updateCell(cellId, { result: runningResult })
+
+      setRunningCellIds((prev) => new Set(prev).add(cellId))
+      try {
+        const execResult = await executeSingle(
+          queryText,
+          ac.signal,
+          NOTEBOOK_ROW_CAP,
+        )
+        // A newer run (or a cancel) superseded this one; don't write its result.
+        if (!isCurrentRun()) return execResult.type !== "error"
+        publishSchemaIfMutating(execResult.type)
+        // Mirrors setResultAt's guard on the script path: a null result means
+        // apply_notebook_state invalidated this cell mid-run; don't resurrect it.
+        const liveCell = cellsRef.current.find((c) => c.id === cellId)
+        if (!liveCell?.result) return execResult.type !== "error"
+        const cellResult: CellResult = {
+          results: [
+            capResultBytes(
+              singleResultFromExec(execResult, queryText),
+              NOTEBOOK_BYTE_CAP,
+            ),
+          ],
+          activeResultIndex: 0,
+          timestamp: Date.now(),
+        }
+        updateCell(cellId, { result: cellResult })
+        persistSnapshot(cellId, queryText, cellResult)
+        return execResult.type !== "error"
+      } finally {
+        externalSignal?.removeEventListener("abort", onExternalAbort)
+        if (isCurrentRun()) {
+          clearRunningCell(
+            abortControllersRef,
+            autoFocusRef,
+            setRunningCellIds,
+            cellId,
+          )
+        }
+      }
+    },
+    [cellsRef, executeSingle, updateCell, runScript, persistSnapshot],
+  )
+
+  const reRunResultAt = useCallback(
+    async (cellId: string, index: number): Promise<boolean> => {
+      const cell = cellsRef.current.find((c) => c.id === cellId)
+      if (!cell?.result) return false
+      const target = cell.result.results[index]
+      if (!target || !target.query.trim()) return false
+      const sql = target.query
+      const executedSql = cell.value
+
+      const controllers = abortControllersRef.current.get(cellId) ?? []
+      controllers[index]?.abort()
+      const ac = new AbortController()
+      controllers[index] = ac
+      abortControllersRef.current.set(cellId, controllers)
+
+      updateCellResult(cellId, index, { type: "running", query: sql })
+
+      const execResult = await executeSingle(sql, ac.signal, NOTEBOOK_ROW_CAP)
+      if (ac.signal.aborted) return execResult.type !== "error"
+      publishSchemaIfMutating(execResult.type)
+      const liveCell = cellsRef.current.find((c) => c.id === cellId)
+      if (!liveCell?.result) return execResult.type !== "error"
+      updateCellResult(
+        cellId,
+        index,
+        capResultBytes(
+          singleResultFromExec(execResult, sql),
+          NOTEBOOK_BYTE_CAP,
+        ),
+      )
+      persistSnapshot(cellId, executedSql)
+      return execResult.type !== "error"
+    },
+    [cellsRef, executeSingle, updateCellResult, persistSnapshot],
+  )
+
+  const cancelCell = useCallback(
+    (cellId: string) => {
+      const controllers = abortControllersRef.current.get(cellId)
+      if (!controllers) return
+      // Supersede the in-flight run so its late resolution can't write back
+      supersedeCellRun(runGenerationRef, cellId)
+      controllers.forEach((ac) => ac.abort())
+      clearRunningCell(
+        abortControllersRef,
+        autoFocusRef,
+        setRunningCellIds,
+        cellId,
+      )
+      markCancelledAll(cellId)
+      // The prior snapshot holds rows for a now-cancelled run; drop it so a
+      // reload shows the cancelled status, not stale success rows.
+      void deleteCellSnapshot(bufferId, cellId).catch(() => undefined)
+    },
+    [bufferId, markCancelledAll],
+  )
+
+  const cancelQuery = useCallback(
+    (cellId: string, index: number) => {
+      const controllers = abortControllersRef.current.get(cellId)
+      if (!controllers || !controllers[index]) return
+      controllers[index].abort()
+      markCancelledOne(cellId, index)
+    },
+    [markCancelledOne],
+  )
+
+  const setActiveResultIndex = useCallback(
+    (cellId: string, index: number) => {
+      autoFocusRef.current.set(cellId, false)
+      updateCells((prev) =>
+        prev.map((c) => {
+          if (c.id !== cellId || !c.result) return c
+          return { ...c, result: { ...c.result, activeResultIndex: index } }
+        }),
+      )
+    },
+    [updateCells],
+  )
+
+  useEffect(() => {
+    const controllersMap = abortControllersRef.current
+    return () => {
+      // Supersede before aborting so the in-flight continuations bail at their
+      // isCurrentRun() checks instead of overwriting the cell's last good
+      // snapshot with an abort-error (or a frozen "running" state) on unmount.
+      controllersMap.forEach((list, cellId) => {
+        supersedeCellRun(runGenerationRef, cellId)
+        list.forEach((c) => c.abort())
+      })
+      controllersMap.clear()
+    }
+  }, [])
+
+  return {
+    runningCellIds,
+    runCell,
+    reRunResultAt,
+    cancelCell,
+    cancelQuery,
+    setActiveResultIndex,
+  }
+}
diff --git a/src/scenes/Editor/Notebook/useCellsStore.ts b/src/scenes/Editor/Notebook/useCellsStore.ts
new file mode 100644
index 000000000..91ebd331a
--- /dev/null
+++ b/src/scenes/Editor/Notebook/useCellsStore.ts
@@ -0,0 +1,190 @@
+import { useCallback, useRef, useState } from "react"
+import type { ChartConfig } from "./CellChart/chartTypes"
+import type {
+  CellMode,
+  CellType,
+  NotebookCell,
+  SingleQueryResult,
+} from "../../../store/notebook"
+import {
+  attachScriptSummary,
+  cancelAllInCell,
+  cancelOneInCell,
+  duplicateCellAt,
+  insertCell,
+  removeCell,
+  setResultAt,
+  swapCellDown,
+  swapCellUp,
+} from "./notebookUtils"
+
+type Options = {
+  initialCells: NotebookCell[]
+  persistCells: (cells: NotebookCell[]) => void
+}
+
+export const useCellsStore = ({ initialCells, persistCells }: Options) => {
+  const [cells, setCells] = useState<NotebookCell[]>(initialCells)
+
+  const cellsRef = useRef(cells)
+  cellsRef.current = cells
+
+  const updateCells = useCallback(
+    (updater: (prev: NotebookCell[]) => NotebookCell[]) => {
+      setCells((prev) => {
+        const next = updater(prev)
+        persistCells(next)
+        return next
+      })
+    },
+    [persistCells],
+  )
+
+  // Hydration-only setter: restoring persisted result snapshots must NOT
+  // schedule a persist. Results are stripped from the persist payload, so the
+  // write would be pure churn — and because persistCells' identity changes with
+  // every EditorProvider render (via updateBuffer), a persisting hydrate effect
+  // re-triggers itself off its own buffer write, looping forever. Stable
+  // identity ([] deps) so the hydration effect runs once per mount.
+  const hydrateCells = useCallback(
+    (updater: (prev: NotebookCell[]) => NotebookCell[]) => setCells(updater),
+    [],
+  )
+
+  // Id generated up-front so the synchronous return matches the deferred state update.
+  const addCell = useCallback(
+    (afterCellId?: string, value?: string, type?: CellType): string => {
+      const id = crypto.randomUUID()
+      updateCells((prev) =>
+        insertCell(prev, afterCellId, undefined, { id, value, type }),
+      )
+      return id
+    },
+    [updateCells],
+  )
+
+  const removeCellById = useCallback(
+    (cellId: string) => {
+      updateCells((prev) => removeCell(prev, cellId))
+    },
+    [updateCells],
+  )
+
+  const updateCell = useCallback(
+    (cellId: string, updates: Partial<NotebookCell>) => {
+      updateCells((prev) =>
+        prev.map((c) => (c.id === cellId ? { ...c, ...updates } : c)),
+      )
+    },
+    [updateCells],
+  )
+
+  const moveCellUp = useCallback(
+    (cellId: string) => updateCells((prev) => swapCellUp(prev, cellId)),
+    [updateCells],
+  )
+
+  const moveCellDown = useCallback(
+    (cellId: string) => updateCells((prev) => swapCellDown(prev, cellId)),
+    [updateCells],
+  )
+
+  const duplicateCell = useCallback(
+    (cellId: string): string => {
+      const newId = crypto.randomUUID()
+      updateCells((prev) => duplicateCellAt(prev, cellId, newId))
+      return newId
+    },
+    [updateCells],
+  )
+
+  const updateCellResult = useCallback(
+    (
+      cellId: string,
+      index: number,
+      result: SingleQueryResult,
+      activeIndex?: number,
+    ) => {
+      updateCells((prev) =>
+        setResultAt(prev, cellId, index, result, activeIndex),
+      )
+    },
+    [updateCells],
+  )
+
+  const markCancelledAll = useCallback(
+    (cellId: string) => updateCells((prev) => cancelAllInCell(prev, cellId)),
+    [updateCells],
+  )
+
+  const markCancelledOne = useCallback(
+    (cellId: string, index: number) =>
+      updateCells((prev) => cancelOneInCell(prev, cellId, index)),
+    [updateCells],
+  )
+
+  const setScriptSummary = useCallback(
+    (
+      cellId: string,
+      summary: {
+        successCount: number
+        failedCount: number
+        durationMs: number
+      },
+    ) => updateCells((prev) => attachScriptSummary(prev, cellId, summary)),
+    [updateCells],
+  )
+
+  const patchCell = useCallback(
+    (cellId: string, patch: Partial<NotebookCell>) => {
+      updateCells((prev) =>
+        prev.map((c) => (c.id === cellId ? { ...c, ...patch } : c)),
+      )
+    },
+    [updateCells],
+  )
+
+  const setCellMode = useCallback(
+    (cellId: string, mode: CellMode) => patchCell(cellId, { mode }),
+    [patchCell],
+  )
+
+  const setCellChartConfig = useCallback(
+    (cellId: string, config: ChartConfig) =>
+      patchCell(cellId, { chartConfig: config }),
+    [patchCell],
+  )
+
+  const setCellAutoRefresh = useCallback(
+    (cellId: string, value: boolean) =>
+      patchCell(cellId, { autoRefresh: value }),
+    [patchCell],
+  )
+
+  const setCellChartMaximized = useCallback(
+    (cellId: string, value: boolean) =>
+      patchCell(cellId, { isChartMaximized: value }),
+    [patchCell],
+  )
+
+  return {
+    cells,
+    cellsRef,
+    updateCells,
+    hydrateCells,
+    updateCell,
+    updateCellResult,
+    addCell,
+    removeCellById,
+    moveCellUp,
+    moveCellDown,
+    duplicateCell,
+    markCancelledAll,
+    markCancelledOne,
+    setScriptSummary,
+    setCellMode,
+    setCellChartConfig,
+    setCellAutoRefresh,
+    setCellChartMaximized,
+  }
+}
diff --git a/src/scenes/Editor/Notebook/useNotebookPersistence.ts b/src/scenes/Editor/Notebook/useNotebookPersistence.ts
new file mode 100644
index 000000000..d27ffceec
--- /dev/null
+++ b/src/scenes/Editor/Notebook/useNotebookPersistence.ts
@@ -0,0 +1,126 @@
+import { useCallback, useEffect, useRef } from "react"
+import type { MutableRefObject } from "react"
+import type { useEditor } from "../../../providers/EditorProvider"
+import type { NotebookCell, NotebookSettings } from "../../../store/notebook"
+import { buildPersistPayload as buildPersistPayloadPure } from "./notebookUtils"
+
+const PERSIST_DEBOUNCE_MS = 300
+
+type UpdateBuffer = ReturnType<typeof useEditor>["updateBuffer"]
+
+type Options = {
+  bufferId: number
+  updateBuffer: UpdateBuffer
+  focusedCellIdRef: MutableRefObject<string | null>
+  maximizedCellIdRef: MutableRefObject<string | null>
+  settingsRef: MutableRefObject<NotebookSettings>
+}
+
+// On unmount, flushes any pending debounced write via refs so a tab
+// switch can't drop the last edit.
+export const useNotebookPersistence = ({
+  bufferId,
+  updateBuffer,
+  focusedCellIdRef,
+  maximizedCellIdRef,
+  settingsRef,
+}: Options) => {
+  const persistTimeoutRef = useRef<number | null>(null)
+  const pendingCellsRef = useRef<NotebookCell[] | null>(null)
+
+  const buildPayload = useCallback(
+    (cells: NotebookCell[]) =>
+      buildPersistPayloadPure(
+        cells,
+        focusedCellIdRef.current,
+        maximizedCellIdRef.current,
+        settingsRef.current,
+      ),
+    [],
+  )
+
+  const scheduleFlush = useCallback(() => {
+    if (persistTimeoutRef.current) {
+      window.clearTimeout(persistTimeoutRef.current)
+    }
+    persistTimeoutRef.current = window.setTimeout(() => {
+      const cells = pendingCellsRef.current
+      pendingCellsRef.current = null
+      persistTimeoutRef.current = null
+      if (cells === null) return
+      void updateBuffer(bufferId, {
+        notebookViewState: buildPayload(cells),
+      })
+    }, PERSIST_DEBOUNCE_MS)
+  }, [bufferId, updateBuffer, buildPayload])
+
+  const persistCells = useCallback(
+    (newCells: NotebookCell[]) => {
+      pendingCellsRef.current = newCells
+      scheduleFlush()
+    },
+    [scheduleFlush],
+  )
+
+  const persistDebounced = useCallback(
+    (cells: NotebookCell[]) => {
+      pendingCellsRef.current = pendingCellsRef.current ?? cells
+      scheduleFlush()
+    },
+    [scheduleFlush],
+  )
+
+  const persistImmediately = useCallback(
+    (cells: NotebookCell[]) => {
+      // A pending debounced write holds newer cells than callers' cellsRef
+      // (which only updates at render) — never replace it with older state.
+      const effective = pendingCellsRef.current ?? cells
+      if (persistTimeoutRef.current) {
+        window.clearTimeout(persistTimeoutRef.current)
+        persistTimeoutRef.current = null
+      }
+      pendingCellsRef.current = null
+      void updateBuffer(bufferId, {
+        notebookViewState: buildPayload(effective),
+      })
+    },
+    [bufferId, updateBuffer, buildPayload],
+  )
+
+  // Refs so the unmount-flush effect keeps stable deps and doesn't
+  // re-fire on every parent render.
+  const updateBufferRef = useRef(updateBuffer)
+  updateBufferRef.current = updateBuffer
+  const bufferIdRef = useRef(bufferId)
+  bufferIdRef.current = bufferId
+
+  const flushPending = useCallback(() => {
+    if (persistTimeoutRef.current === null) return
+    window.clearTimeout(persistTimeoutRef.current)
+    persistTimeoutRef.current = null
+    const cells = pendingCellsRef.current
+    pendingCellsRef.current = null
+    if (cells === null) return
+    void updateBufferRef.current(bufferIdRef.current, {
+      notebookViewState: buildPayload(cells),
+    })
+  }, [buildPayload])
+
+  useEffect(() => {
+    return flushPending
+  }, [flushPending])
+
+  useEffect(() => {
+    const onVisibilityChange = () => {
+      if (document.visibilityState === "hidden") flushPending()
+    }
+    window.addEventListener("pagehide", flushPending)
+    document.addEventListener("visibilitychange", onVisibilityChange)
+    return () => {
+      window.removeEventListener("pagehide", flushPending)
+      document.removeEventListener("visibilitychange", onVisibilityChange)
+    }
+  }, [flushPending])
+
+  return { persistCells, persistImmediately, persistDebounced }
+}
diff --git a/src/scenes/Editor/QueryResult/index.tsx b/src/scenes/Editor/QueryResult/index.tsx
index 38a8b2e42..26c15a606 100644
--- a/src/scenes/Editor/QueryResult/index.tsx
+++ b/src/scenes/Editor/QueryResult/index.tsx
@@ -36,6 +36,7 @@ type Props = Timings &
   Readonly<{
     count: number
     rowCount: number
+    totalRowCount?: number
   }>
 
 const Wrapper = styled.div`
@@ -62,6 +63,10 @@ const DetailsText = styled(Text)`
   margin-right: 0.5rem;
 `
 
+const TruncatedTag = styled.span`
+  color: ${color("orange")};
+`
+
 const roundTiming = (time: number): number =>
   Math.round((time + Number.EPSILON) * 100) / 100
 
@@ -100,14 +105,27 @@ const QueryResult = ({
   execute,
   fetch,
   rowCount,
+  totalRowCount,
 }: Props) => {
+  const truncated =
+    typeof totalRowCount === "number" && totalRowCount > rowCount
   return (
     <Wrapper _height={95} duration={TransitionDuration.FAST}>
       <div>
         <Text color="gray2">
-          {rowCount.toLocaleString()} row
-          {rowCount > 1 || rowCount === 0 ? "s" : ""} in&nbsp;
-          {formatTiming(fetch)}
+          {truncated ? (
+            <>
+              {rowCount.toLocaleString()} of {totalRowCount.toLocaleString()}{" "}
+              rows in&nbsp;{formatTiming(fetch)}&nbsp;
+              <TruncatedTag>(truncated)</TruncatedTag>
+            </>
+          ) : (
+            <>
+              {rowCount.toLocaleString()} row
+              {rowCount > 1 || rowCount === 0 ? "s" : ""} in&nbsp;
+              {formatTiming(fetch)}
+            </>
+          )}
         </Text>
       </div>
 
diff --git a/src/scenes/Editor/index.tsx b/src/scenes/Editor/index.tsx
index d508ab5cd..23b5046f9 100644
--- a/src/scenes/Editor/index.tsx
+++ b/src/scenes/Editor/index.tsx
@@ -39,8 +39,13 @@ import { useKeyPress } from "../../hooks"
 import Monaco from "./Monaco"
 import { Tabs } from "./Monaco/tabs"
 import { useEditor } from "../../providers/EditorProvider"
-import { useAIConversation } from "../../providers/AIConversationProvider"
+import {
+  useAIConversation,
+  useActiveConversationMessages,
+} from "../../providers/AIConversationProvider"
 import { Metrics } from "./Metrics"
+import { Notebook } from "./Notebook"
+import { NotebookWorkspaceBridge } from "./Notebook/NotebookWorkspaceBridge"
 import Notifications from "../../scenes/Notifications"
 import type { QueryKey } from "../../store/Query/types"
 import type { ErrorResult } from "../../utils"
@@ -127,7 +132,7 @@ const DiffViewWrapper = styled(PaneContent)`
   height: 100%;
   width: 100%;
   overflow: hidden;
-  background: #2c2e3d;
+  background: ${color("editorBackground")};
 `
 
 const DiffEditorContainer = styled.div`
@@ -188,10 +193,10 @@ const Editor = ({
   const {
     chatWindowState,
     getConversationMeta,
-    activeConversationMessages,
     acceptSuggestion,
     rejectSuggestion,
   } = useAIConversation()
+  const activeConversationMessages = useActiveConversationMessages()
   const activeSidebar = useSelector(selectors.console.getActiveSidebar)
   const queryNotifications = useSelector(selectors.query.getQueryNotifications)
   const activeNotification = useSelector(selectors.query.getActiveNotification)
@@ -241,7 +246,9 @@ const Editor = ({
   }, [])
 
   const isMonacoHidden =
-    !!activeBuffer.isPreviewBuffer || !!activeBuffer.metricsViewState
+    !!activeBuffer.isPreviewBuffer ||
+    !!activeBuffer.metricsViewState ||
+    !!activeBuffer.notebookViewState
 
   const isDiffPreview =
     activeBuffer.isPreviewBuffer && activeBuffer.previewContent?.type === "diff"
@@ -346,6 +353,7 @@ const Editor = ({
 
   return (
     <EditorPaneWrapper ref={innerRef} {...rest}>
+      <NotebookWorkspaceBridge />
       <EditorLeftPane>
         <Tabs />
         <EditorContent>
@@ -481,6 +489,9 @@ const Editor = ({
             )}
             {/* Metrics view */}
             {activeBuffer.metricsViewState && <Metrics key={activeBuffer.id} />}
+            {activeBuffer.notebookViewState && (
+              <Notebook key={activeBuffer.id} />
+            )}
             <Notifications
               onClearNotifications={handleClearNotifications}
               targetBufferId={targetNotificationsBufferId}
diff --git a/src/scenes/Footer/BuildVersion/index.tsx b/src/scenes/Footer/BuildVersion/index.tsx
index e54b9b3d8..35c7a2930 100644
--- a/src/scenes/Footer/BuildVersion/index.tsx
+++ b/src/scenes/Footer/BuildVersion/index.tsx
@@ -46,8 +46,22 @@ const Wrapper = styled.div`
 `
 const ReleaseNotesButton = styled(Button)<{ enterprise?: boolean }>`
   position: relative;
-  ${({ enterprise }) => (enterprise ? `background: #322733;` : ``)}
   gap: 0.5rem;
+  border-radius: 0.25rem;
+  border-color: rgba(255, 255, 255, 0.15);
+  border-bottom-width: 2px;
+  background: ${({ enterprise }) => (enterprise ? "#322733" : "transparent")};
+
+  &:hover:not([disabled]) {
+    background: ${({ enterprise }) =>
+      enterprise ? "#322733" : "rgba(255, 255, 255, 0.05)"};
+    border-color: rgba(255, 255, 255, 0.3);
+  }
+`
+
+const QuestDBLogo = styled.img`
+  width: 1.5rem;
+  height: auto;
 `
 
 const ReleaseLink = styled.a`
@@ -67,9 +81,11 @@ const versionButtons: {
   [key in Versions["type"]]: { label: string; icon?: React.ReactNode }
 } = {
   dev: {
+    icon: <QuestDBLogo src="assets/questdb.svg" alt="" />,
     label: "QuestDB Dev",
   },
   oss: {
+    icon: <QuestDBLogo src="assets/questdb.svg" alt="" />,
     label: "QuestDB",
   },
   enterprise: {
diff --git a/src/scenes/Footer/ConnectionStatus/index.tsx b/src/scenes/Footer/ConnectionStatus/index.tsx
index 65bbdd25a..6965fb5ff 100644
--- a/src/scenes/Footer/ConnectionStatus/index.tsx
+++ b/src/scenes/Footer/ConnectionStatus/index.tsx
@@ -14,11 +14,16 @@ const Wrapper = styled.div`
 
 const StatusIcon = styled.div<{ isConnected: boolean }>`
   display: block;
-  width: 0.6rem;
-  height: 0.6rem;
-  border-radius: 50%;
+  width: 0.8rem;
+  height: 0.8rem;
+  border-radius: 0.2rem;
   background-color: ${(props) =>
     props.isConnected ? color("green") : color("red")};
+  box-shadow: 0 0 0 1.5px
+    ${(props) =>
+      props.isConnected
+        ? "rgba(80, 250, 123, 0.32)"
+        : "rgba(255, 85, 85, 0.32)"};
   margin-right: 0.6rem;
 `
 
@@ -38,7 +43,7 @@ const ConnectionStatus = () => {
     <Wrapper>
       <StatusIcon isConnected={isConnected} />
       {isConnected ? (
-        <Text color="white">Connected</Text>
+        <Text color="white">QuestDB Connected</Text>
       ) : (
         <Text color="white">Error connecting to QuestDB</Text>
       )}
diff --git a/src/scenes/Footer/MCPBridgeStatus/PairPopover.tsx b/src/scenes/Footer/MCPBridgeStatus/PairPopover.tsx
new file mode 100644
index 000000000..ff89e6886
--- /dev/null
+++ b/src/scenes/Footer/MCPBridgeStatus/PairPopover.tsx
@@ -0,0 +1,460 @@
+import React, { forwardRef, useEffect, useState } from "react"
+import styled from "styled-components"
+import {
+  PlugsConnectedIcon,
+  PlugsIcon,
+  WarningIcon,
+} from "@phosphor-icons/react"
+import { Button, LoadingSpinner } from "../../../components"
+import { Input } from "../../../components/Input"
+import { useMCPBridge } from "../../../providers/MCPBridgeProvider"
+import { MAX_RECONNECT_ATTEMPTS } from "../../../utils/mcp/MCPBridgeClient"
+import { LOCALHOST_WS_RE, TOKEN_RE } from "../../../utils/mcp/pairValidation"
+import type { Permissions } from "../../../utils/tools/permissions"
+import { Tone, accentColor, deriveTone } from "./tone"
+import { PermissionsSection } from "./PermissionsSection"
+
+const permissionsEqual = (a: Permissions, b: Permissions): boolean =>
+  a.grantSchemaAccess === b.grantSchemaAccess &&
+  a.read === b.read &&
+  a.write === b.write
+
+const SUCCESS_AUTOCLOSE_MS = 3_000
+
+const DEFAULT_WS_URL_PREFIX = "ws://127.0.0.1:"
+
+const Root = styled.div`
+  background: ${({ theme }) => theme.color.backgroundDarker};
+  border: 1px solid ${({ theme }) => theme.color.selection};
+  border-radius: 0.8rem;
+  box-shadow: 0 12px 32px -8px ${({ theme }) => theme.color.black};
+  width: min(38rem, calc(100vw - 2rem));
+  z-index: 200;
+  display: flex;
+  flex-direction: column;
+  padding: 0;
+`
+
+const Header = styled.div`
+  display: flex;
+  align-items: center;
+  gap: 1.2rem;
+  padding: 1.6rem 1.6rem 1.2rem;
+`
+
+const IconBadge = styled.div<{ $tone: Tone }>`
+  width: 3.6rem;
+  height: 3.6rem;
+  border-radius: 0.8rem;
+  border: 1px solid ${({ theme, $tone }) => theme.color[accentColor($tone)]};
+  color: ${({ theme, $tone }) => theme.color[accentColor($tone)]};
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+`
+
+const HeaderText = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+  min-width: 0;
+`
+
+const Title = styled.div`
+  font-weight: 600;
+  font-size: 1.5rem;
+  color: ${({ theme }) => theme.color.foreground};
+`
+
+const Lede = styled.p`
+  margin: 0;
+  font-size: 1.2rem;
+  line-height: 1.4;
+  color: ${({ theme }) => theme.color.gray2};
+  word-break: break-word;
+`
+
+const Body = styled.div`
+  padding: 0 1.6rem 1.2rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1.2rem;
+`
+
+const Field = styled.label`
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+  font-size: 1.1rem;
+
+  > .label {
+    color: ${({ theme }) => theme.color.gray2};
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    font-weight: 600;
+  }
+`
+
+const FullWidthInput = styled(Input)`
+  width: 100%;
+  font-family: ${({ theme }) => theme.fontMonospace};
+  font-size: 1.3rem;
+`
+
+const StatusRow = styled.div<{ $tone: "info" | "danger" }>`
+  display: flex;
+  align-items: flex-start;
+  gap: 0.8rem;
+  width: 100%;
+  padding: 1.6rem;
+  background: ${({ theme, $tone }) =>
+    $tone === "danger" ? `${theme.color.red}1f` : theme.color.backgroundDarker};
+  color: ${({ theme, $tone }) =>
+    $tone === "danger" ? theme.color.foreground : theme.color.gray2};
+
+  svg {
+    flex-shrink: 0;
+    color: ${({ theme, $tone }) =>
+      $tone === "danger" ? theme.color.red : theme.color.pinkPrimary};
+  }
+
+  strong {
+    color: ${({ theme }) => theme.color.foreground};
+    font-weight: 600;
+  }
+`
+
+const StatusText = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+  min-width: 0;
+  line-height: 1.4;
+`
+
+const StatusDetail = styled.span`
+  font-size: 1.2rem;
+  color: ${({ theme }) => theme.color.gray2};
+  word-break: break-word;
+`
+
+const Footer = styled.div`
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 0.8rem;
+  padding: 1.2rem 1.6rem;
+  border-top: 1px solid ${({ theme }) => theme.color.selection};
+`
+
+const RightActions = styled.div`
+  display: flex;
+  align-items: center;
+  gap: 0.8rem;
+  margin-left: auto;
+`
+
+type Props = {
+  open: boolean
+  onClose: () => void
+}
+
+export const MCPBridgePairPopover = forwardRef<HTMLDivElement, Props>(
+  ({ open, onClose, ...rest }, ref) => {
+    const {
+      status,
+      lastError,
+      retryAttempt,
+      url,
+      token,
+      connect,
+      disconnect,
+      permissions,
+      setPermissions,
+    } = useMCPBridge()
+    const [draftUrl, setDraftUrl] = useState(DEFAULT_WS_URL_PREFIX)
+    const [draftToken, setDraftToken] = useState("")
+    const [draftPermissions, setDraftPermissions] = useState<Permissions>(
+      () => permissions,
+    )
+    const [validationError, setValidationError] = useState<string | null>(null)
+    const [submitted, setSubmitted] = useState(false)
+    const [succeeded, setSucceeded] = useState(false)
+
+    // Snapshot via refs so the [open] effect picks up the latest live
+    // values without re-running on later background url/token changes.
+    const urlRef = React.useRef(url)
+    urlRef.current = url
+    const tokenRef = React.useRef(token)
+    tokenRef.current = token
+    const permissionsRef = React.useRef(permissions)
+    permissionsRef.current = permissions
+    const sawDisconnectAfterSubmitRef = React.useRef(false)
+
+    useEffect(() => {
+      if (!open) return
+      setDraftUrl(urlRef.current || DEFAULT_WS_URL_PREFIX)
+      setDraftToken(tokenRef.current ?? "")
+      setDraftPermissions(permissionsRef.current)
+      setValidationError(null)
+      setSubmitted(false)
+      setSucceeded(false)
+      sawDisconnectAfterSubmitRef.current = false
+    }, [open])
+
+    useEffect(() => {
+      if (!submitted) {
+        sawDisconnectAfterSubmitRef.current = false
+        return
+      }
+      if (status !== "connected") {
+        sawDisconnectAfterSubmitRef.current = true
+      }
+    }, [submitted, status])
+
+    // In-render setState so the green icon, success title, and hidden
+    // body all commit in the same paint — no one-frame flicker.
+    if (
+      open &&
+      submitted &&
+      sawDisconnectAfterSubmitRef.current &&
+      status === "connected" &&
+      !succeeded
+    ) {
+      setSucceeded(true)
+    }
+
+    useEffect(() => {
+      if (!succeeded) return
+      const t = setTimeout(() => onClose(), SUCCESS_AUTOCLOSE_MS)
+      return () => clearTimeout(t)
+    }, [succeeded, onClose])
+
+    const isConnecting = status === "connecting" || status === "reconnecting"
+
+    const showConnecting = !succeeded && isConnecting
+    const showWsError =
+      !succeeded && !isConnecting && (lastError || retryAttempt > 0)
+
+    const credsDirty = draftUrl !== (url ?? "") || draftToken !== (token ?? "")
+    const permsDirty = !permissionsEqual(draftPermissions, permissions)
+    const isPaired = !!(url && token)
+    const inErrorState = !!lastError || retryAttempt > 0
+    const submitEnabled =
+      !isConnecting && (credsDirty || permsDirty || !isPaired || inErrorState)
+    const submitLabel = isConnecting ? "Connecting…" : "Connect"
+
+    const clearValidationError = () => {
+      if (validationError) setValidationError(null)
+    }
+
+    const onConnect = () => {
+      const isConnected = status === "connected"
+      const needsConnect = credsDirty || !isConnected
+      if (!needsConnect && permsDirty) {
+        setPermissions(draftPermissions)
+        onClose()
+        return
+      }
+      const nextUrl = draftUrl.trim()
+      const nextToken = draftToken.trim()
+      if (!nextUrl || !nextToken) {
+        setValidationError("Both URL and token are required.")
+        return
+      }
+      if (!LOCALHOST_WS_RE.test(nextUrl)) {
+        setValidationError(
+          "WebSocket URL must point to localhost (ws://127.0.0.1:<port> or ws://localhost:<port>).",
+        )
+        return
+      }
+      if (!TOKEN_RE.test(nextToken)) {
+        setValidationError(
+          "Token looks malformed — expected a long URL-safe string.",
+        )
+        return
+      }
+      setValidationError(null)
+      setSucceeded(false)
+      setSubmitted(true)
+      // Order matters: the rebuilt client reads perms in its initial hello.
+      if (permsDirty) setPermissions(draftPermissions)
+      connect(nextUrl, nextToken)
+    }
+
+    const onDisconnect = () => {
+      disconnect()
+      setDraftUrl(DEFAULT_WS_URL_PREFIX)
+      setDraftToken("")
+      setSubmitted(false)
+      setSucceeded(false)
+    }
+
+    // While connecting, Cancel must tear down the WS — otherwise the
+    // bridge keeps retrying in the background after close.
+    const onCancel = () => {
+      if (isConnecting) {
+        disconnect()
+        setDraftUrl(DEFAULT_WS_URL_PREFIX)
+        setDraftToken("")
+        setValidationError(null)
+        setSubmitted(false)
+        setSucceeded(false)
+      }
+      onClose()
+    }
+
+    const tone = deriveTone(isPaired, status)
+    const HeaderIcon = tone === "connected" ? PlugsConnectedIcon : PlugsIcon
+
+    const canDisconnect = isPaired && status === "connected"
+
+    const title = succeeded ? "MCP Bridge connected" : "MCP Bridge"
+
+    const lede = succeeded
+      ? "You can track the connection status from the bottom bar."
+      : "Paste the WebSocket URL and token your coding agent gave you, or click the deep link from the agent."
+
+    return (
+      <Root ref={ref} {...rest} data-hook="mcp-pair-popover">
+        <Header>
+          <IconBadge
+            $tone={tone}
+            data-hook={succeeded ? "mcp-pair-success-badge" : undefined}
+          >
+            <HeaderIcon size={20} weight="duotone" />
+          </IconBadge>
+          <HeaderText>
+            <Title>{title}</Title>
+            <Lede>{lede}</Lede>
+          </HeaderText>
+        </Header>
+
+        {!succeeded && (
+          <Body>
+            <Field>
+              <span className="label">WebSocket URL</span>
+              <FullWidthInput
+                name="mcp-pair-url"
+                value={draftUrl}
+                onChange={(e) => {
+                  setDraftUrl(e.target.value)
+                  clearValidationError()
+                }}
+                placeholder="ws://127.0.0.1:57123"
+                disabled={isConnecting}
+                data-hook="mcp-pair-url-input"
+                autoFocus
+              />
+            </Field>
+
+            <Field>
+              <span className="label">Token</span>
+              <FullWidthInput
+                name="mcp-pair-token"
+                value={draftToken}
+                onChange={(e) => {
+                  setDraftToken(e.target.value)
+                  clearValidationError()
+                }}
+                placeholder="Paste the token from the agent's reply"
+                disabled={isConnecting}
+                data-hook="mcp-pair-token-input"
+              />
+            </Field>
+
+            <PermissionsSection
+              value={draftPermissions}
+              onChange={(next) => {
+                setDraftPermissions(next)
+                clearValidationError()
+              }}
+              disabled={isConnecting}
+            />
+          </Body>
+        )}
+
+        {showConnecting && (
+          <StatusRow
+            $tone="info"
+            data-hook="mcp-pair-connecting"
+            role="status"
+            aria-live="polite"
+          >
+            <LoadingSpinner size="16px" />
+            <StatusText>
+              <span>Establishing WebSocket connection...</span>
+              {/* -1 on both sides so the counter shows retries-allowed,
+                  not total attempts (the first attempt isn't a retry). */}
+              {retryAttempt > 1 && (
+                <StatusDetail data-hook="mcp-pair-retries">
+                  (Retry {retryAttempt - 1} of {MAX_RECONNECT_ATTEMPTS - 1})
+                </StatusDetail>
+              )}
+            </StatusText>
+          </StatusRow>
+        )}
+
+        {!succeeded && validationError && (
+          <StatusRow
+            $tone="danger"
+            data-hook="mcp-pair-validation-error"
+            role="alert"
+          >
+            <WarningIcon size={16} weight="duotone" />
+            <StatusText>
+              <StatusDetail>{validationError}</StatusDetail>
+            </StatusText>
+          </StatusRow>
+        )}
+
+        {showWsError && (
+          <StatusRow $tone="danger" data-hook="mcp-pair-error" role="alert">
+            <WarningIcon size={16} weight="duotone" />
+            <StatusText>
+              <strong>Could not connect to MCP bridge</strong>
+              <StatusDetail>
+                {lastError ??
+                  `Bridge stopped responding after ${MAX_RECONNECT_ATTEMPTS} attempts. Click Try again, or ask your coding agent for a fresh deep link.`}
+              </StatusDetail>
+            </StatusText>
+          </StatusRow>
+        )}
+
+        {!succeeded && (
+          <Footer>
+            {canDisconnect && (
+              <Button
+                skin="danger"
+                onClick={onDisconnect}
+                dataHook="mcp-pair-disconnect"
+              >
+                Disconnect
+              </Button>
+            )}
+            <RightActions>
+              <Button
+                skin="secondary"
+                onClick={onCancel}
+                dataHook="mcp-pair-cancel"
+              >
+                Cancel
+              </Button>
+              <Button
+                skin="primary"
+                onClick={onConnect}
+                disabled={!submitEnabled}
+                dataHook="mcp-pair-submit"
+              >
+                {submitLabel}
+              </Button>
+            </RightActions>
+          </Footer>
+        )}
+      </Root>
+    )
+  },
+)
+
+MCPBridgePairPopover.displayName = "MCPBridgePairPopover"
diff --git a/src/scenes/Footer/MCPBridgeStatus/PermissionsSection.tsx b/src/scenes/Footer/MCPBridgeStatus/PermissionsSection.tsx
new file mode 100644
index 000000000..031b8e25b
--- /dev/null
+++ b/src/scenes/Footer/MCPBridgeStatus/PermissionsSection.tsx
@@ -0,0 +1,215 @@
+import React from "react"
+import styled from "styled-components"
+import { CaretDown } from "@styled-icons/boxicons-regular"
+import { Button } from "../../../components"
+import { DropdownMenu } from "../../../components/DropdownMenu"
+import type { Permissions } from "../../../utils/tools/permissions"
+
+type Level = "none" | "schema" | "read" | "write"
+
+const PERMISSIONS_BY_LEVEL: Record<Level, Permissions> = {
+  none: { grantSchemaAccess: false, read: false, write: false },
+  schema: { grantSchemaAccess: true, read: false, write: false },
+  read: { grantSchemaAccess: true, read: true, write: false },
+  write: { grantSchemaAccess: true, read: true, write: true },
+}
+
+const levelFromPermissions = (p: Permissions): Level => {
+  if (p.write) return "write"
+  if (p.read) return "read"
+  if (p.grantSchemaAccess) return "schema"
+  return "none"
+}
+
+type Option = {
+  level: Level
+  label: string
+  hint: string
+}
+
+const OPTIONS: Option[] = [
+  {
+    level: "none",
+    label: "None",
+    hint: "AI cannot read schema or data. Read-only queries it runs show results only in your console.",
+  },
+  {
+    level: "schema",
+    label: "Schema access",
+    hint: "Read table list, columns, and details. Can run read-only queries whose results stay in your console.",
+  },
+  {
+    level: "read",
+    label: "Read",
+    hint: "Read data and schema (DQL).",
+  },
+  {
+    level: "write",
+    label: "Write",
+    hint: "Read data and schema, modify data (DQL, DDL, DML).",
+  },
+]
+
+const Field = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+  font-size: 1.1rem;
+  width: 100%;
+`
+
+const FieldLabel = styled.span`
+  color: ${({ theme }) => theme.color.gray2};
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  font-weight: 600;
+`
+
+const RichTitle = styled.span`
+  font-size: 1.8rem;
+  font-weight: 600;
+  color: ${({ theme }) => theme.color.foreground};
+`
+
+const TriggerButton = styled(Button).attrs({ skin: "secondary" })`
+  justify-content: space-between;
+  width: 100%;
+  height: 5.5rem;
+  padding: 0.6rem 1.2rem;
+  gap: 1.2rem;
+  font-weight: 400;
+`
+
+const TriggerLabel = styled.span`
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.2rem;
+  min-width: 0;
+  text-align: left;
+`
+
+const TriggerTitle = styled.span`
+  font-size: 1.4rem;
+  color: ${({ theme }) => theme.color.foreground};
+`
+
+const TriggerHint = styled.span`
+  font-size: 1.1rem;
+  color: ${({ theme }) => theme.color.gray2};
+`
+
+const Content = styled(DropdownMenu.Content)`
+  background: ${({ theme }) => theme.color.backgroundDarker};
+  border: 1px solid ${({ theme }) => theme.color.selection};
+  box-shadow: 0 7px 30px -10px ${({ theme }) => theme.color.black};
+  padding: 0.4rem;
+  min-width: var(--radix-dropdown-menu-trigger-width);
+`
+
+const ItemRoot = styled.div`
+  position: relative;
+`
+
+const Item = styled(DropdownMenu.Item)`
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.2rem;
+  padding: 0.8rem 2.4rem 0.8rem 1rem;
+`
+
+const ItemLabel = styled.span`
+  font-size: 1.3rem;
+  font-weight: 500;
+  color: ${({ theme }) => theme.color.foreground};
+`
+
+const ItemHint = styled.span`
+  font-size: 1.2rem;
+  color: ${({ theme }) => theme.color.gray2};
+`
+
+const Check = styled.span`
+  position: absolute;
+  right: 1rem;
+  top: 50%;
+  transform: translateY(-50%);
+  color: ${({ theme }) => theme.color.pinkPrimary};
+  font-size: 1.3rem;
+  pointer-events: none;
+`
+
+type Props = {
+  value: Permissions
+  onChange: (next: Permissions) => void
+  disabled?: boolean
+  variant?: "compact" | "rich"
+}
+
+export const PermissionsSection: React.FC<Props> = ({
+  value,
+  onChange,
+  disabled = false,
+  variant = "compact",
+}) => {
+  const currentLevel = levelFromPermissions(value)
+  const current = OPTIONS.find((o) => o.level === currentLevel) ?? OPTIONS[0]
+
+  const handleSelect = (level: Level) => {
+    onChange(PERMISSIONS_BY_LEVEL[level])
+  }
+
+  const trigger = (
+    <DropdownMenu.Trigger asChild>
+      <TriggerButton disabled={disabled} dataHook="permissions-trigger">
+        <TriggerLabel>
+          <TriggerTitle>{current.label}</TriggerTitle>
+          <TriggerHint>{current.hint}</TriggerHint>
+        </TriggerLabel>
+        <CaretDown size={16} />
+      </TriggerButton>
+    </DropdownMenu.Trigger>
+  )
+
+  const content = (
+    <DropdownMenu.Portal>
+      <Content sideOffset={4} align="start">
+        {OPTIONS.map((opt) => (
+          <ItemRoot key={opt.level}>
+            <Item
+              onSelect={() => handleSelect(opt.level)}
+              data-hook={`permission-level-${opt.level}`}
+            >
+              <ItemLabel>{opt.label}</ItemLabel>
+              <ItemHint>{opt.hint}</ItemHint>
+            </Item>
+            {opt.level === currentLevel && <Check>✓</Check>}
+          </ItemRoot>
+        ))}
+      </Content>
+    </DropdownMenu.Portal>
+  )
+
+  if (variant === "rich") {
+    return (
+      <Field data-hook="permissions">
+        <RichTitle>Permissions</RichTitle>
+        <DropdownMenu.Root modal={false}>
+          {trigger}
+          {content}
+        </DropdownMenu.Root>
+      </Field>
+    )
+  }
+
+  return (
+    <Field data-hook="permissions">
+      <FieldLabel>Permissions</FieldLabel>
+      <DropdownMenu.Root modal={false}>
+        {trigger}
+        {content}
+      </DropdownMenu.Root>
+    </Field>
+  )
+}
diff --git a/src/scenes/Footer/MCPBridgeStatus/index.tsx b/src/scenes/Footer/MCPBridgeStatus/index.tsx
new file mode 100644
index 000000000..38817ef19
--- /dev/null
+++ b/src/scenes/Footer/MCPBridgeStatus/index.tsx
@@ -0,0 +1,130 @@
+import React, { forwardRef, useCallback, useState } from "react"
+import styled, { css, keyframes } from "styled-components"
+import { PlugsConnectedIcon, PlugsIcon } from "@phosphor-icons/react"
+import { PopperToggle } from "../../../components"
+import { useMCPBridge } from "../../../providers/MCPBridgeProvider"
+import { MCPBridgePairPopover } from "./PairPopover"
+import { Tone, accentColor, deriveTone, hexToRgba } from "./tone"
+
+const pulse = keyframes`
+  0%, 100% { opacity: 1; }
+  50%      { opacity: 0.45; }
+`
+
+const Wrapper = styled.button<{ $tone: Tone }>`
+  display: inline-flex;
+  align-items: center;
+  gap: 0.6rem;
+  height: 3rem;
+  padding: 0 1.1rem;
+  border: 1px solid
+    ${({ theme, $tone }) => hexToRgba(theme.color[accentColor($tone)], 0.1)};
+  border-bottom-width: 2px;
+  border-radius: 0.25rem;
+  background: ${({ theme, $tone }) =>
+    hexToRgba(theme.color[accentColor($tone)], 0.05)};
+  color: ${({ theme }) => theme.color.foreground};
+  font: inherit;
+  cursor: pointer;
+  transition:
+    background 0.15s ease,
+    border-color 0.15s ease;
+
+  &:hover {
+    background: ${({ theme, $tone }) =>
+      hexToRgba(theme.color[accentColor($tone)], 0.1)};
+    border-color: ${({ theme, $tone }) =>
+      hexToRgba(theme.color[accentColor($tone)], 0.25)};
+  }
+
+  &:focus-visible {
+    outline: 1px solid
+      ${({ theme, $tone }) =>
+        $tone === "idle" ? theme.color.cyan : theme.color[accentColor($tone)]};
+    outline-offset: 2px;
+  }
+
+  svg {
+    color: ${({ theme, $tone }) => theme.color[accentColor($tone)]};
+    flex-shrink: 0;
+    ${({ $tone }) =>
+      $tone === "connecting" &&
+      css`
+        animation: ${pulse} 1.2s ease-in-out infinite;
+      `}
+  }
+`
+
+type PillProps = {
+  tone: Tone
+  label: string
+  title: string
+}
+
+const Pill = forwardRef<
+  HTMLButtonElement,
+  PillProps & React.HTMLAttributes<HTMLButtonElement>
+>(({ tone, label, title, ...rest }, ref) => {
+  const Icon = tone === "connected" ? PlugsConnectedIcon : PlugsIcon
+  return (
+    <Wrapper
+      ref={ref}
+      type="button"
+      title={title}
+      aria-label={label}
+      data-hook="mcp-bridge-status-pill"
+      $tone={tone}
+      {...rest}
+    >
+      <Icon size={14} weight="duotone" />
+      <span>{label}</span>
+    </Wrapper>
+  )
+})
+Pill.displayName = "MCPBridgeStatusPill"
+
+const POPPER_MODIFIERS = [
+  { name: "offset", options: { offset: [0, 8] as [number, number] } },
+]
+
+export const MCPBridgeStatus: React.FC = () => {
+  const { status, url, token } = useMCPBridge()
+  const [popoverOpen, setPopoverOpen] = useState(false)
+  const paired = !!(url && token)
+  const tone = deriveTone(paired, status)
+
+  let label: string
+  let title: string
+
+  if (tone === "idle") {
+    label = "MCP not connected"
+    title =
+      "Click to enter MCP credentials manually, or ask Claude / Codex to pair this console."
+  } else if (tone === "connected") {
+    label = "MCP connected"
+    title = "Paired with the MCP bridge. Click to manage."
+  } else if (tone === "connecting") {
+    label = "MCP connecting…"
+    title = "Connecting to the bridge. Click to manage."
+  } else {
+    label = "MCP disconnected"
+    title =
+      "Click to re-enter MCP credentials, or ask Claude for a fresh pairing link."
+  }
+
+  const closePopover = useCallback(() => setPopoverOpen(false), [])
+
+  return (
+    <PopperToggle
+      placement="top-end"
+      modifiers={POPPER_MODIFIERS}
+      active={popoverOpen}
+      onToggle={setPopoverOpen}
+      trigger={<Pill tone={tone} label={label} title={title} />}
+    >
+      <MCPBridgePairPopover open={popoverOpen} onClose={closePopover} />
+    </PopperToggle>
+  )
+}
+
+export default MCPBridgeStatus
diff --git a/src/scenes/Footer/MCPBridgeStatus/tone.ts b/src/scenes/Footer/MCPBridgeStatus/tone.ts
new file mode 100644
index 000000000..a78d9a24f
--- /dev/null
+++ b/src/scenes/Footer/MCPBridgeStatus/tone.ts
@@ -0,0 +1,33 @@
+// Shared so the pill and popover never drift — both must render the
+// same tone for a given `MCPBridgeProvider` state.
+
+import type { MCPBridgeClientStatus } from "../../../utils/mcp/MCPBridgeClient"
+
+export type Tone = "connected" | "connecting" | "error" | "idle"
+
+export const hexToRgba = (hex: string, alpha: number) => {
+  const value = hex.replace("#", "")
+  const r = parseInt(value.slice(0, 2), 16)
+  const g = parseInt(value.slice(2, 4), 16)
+  const b = parseInt(value.slice(4, 6), 16)
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`
+}
+
+export const accentColor = (tone: Tone) =>
+  tone === "connected"
+    ? "green"
+    : tone === "connecting"
+      ? "pinkPrimary"
+      : tone === "error"
+        ? "red"
+        : "gray2"
+
+export const deriveTone = (
+  paired: boolean,
+  status: MCPBridgeClientStatus,
+): Tone => {
+  if (!paired) return "idle"
+  if (status === "connected") return "connected"
+  if (status === "connecting" || status === "reconnecting") return "connecting"
+  return "error"
+}
diff --git a/src/scenes/Footer/index.tsx b/src/scenes/Footer/index.tsx
index af3742319..0dc562de5 100644
--- a/src/scenes/Footer/index.tsx
+++ b/src/scenes/Footer/index.tsx
@@ -32,6 +32,7 @@ import { Link, Text, TransitionDuration } from "../../components"
 import CtaBanner from "./CtaBanner"
 import BuildVersion from "./BuildVersion"
 import ConnectionStatus from "./ConnectionStatus"
+import MCPBridgeStatus from "./MCPBridgeStatus"
 import { eventBus } from "../../modules/EventBus"
 import { EventType } from "../../modules/EventBus/types"
 import { useSettings } from "../../providers"
@@ -118,6 +119,7 @@ const Footer = () => {
         </Text>
       </LeftContainer>
       <RightContainer>
+        <MCPBridgeStatus />
         <ConnectionStatus />
         {showBuildVersion && <BuildVersion />}
         <Link
diff --git a/src/scenes/Layout/AIChatButton.tsx b/src/scenes/Layout/AIChatButton.tsx
index 009678330..102327dc6 100644
--- a/src/scenes/Layout/AIChatButton.tsx
+++ b/src/scenes/Layout/AIChatButton.tsx
@@ -2,7 +2,7 @@ import React from "react"
 import styled from "styled-components"
 import { PrimaryToggleButton, IconWithTooltip, Box } from "../../components"
 import { AISparkle } from "../../components/AISparkle"
-import { useAIConversation } from "../../providers/AIConversationProvider"
+import { useAIConversationActions } from "../../providers/AIConversationProvider"
 import { useAIStatus } from "../../providers/AIStatusProvider"
 import { useSelector } from "react-redux"
 import { selectors } from "../../store"
@@ -17,7 +17,8 @@ const TooltipWrapper = styled(Box).attrs({ justifyContent: "center" })`
 `
 
 export const AIChatButton = () => {
-  const { openOrCreateBlankChatWindow, closeChatWindow } = useAIConversation()
+  const { openOrCreateBlankChatWindow, closeChatWindow } =
+    useAIConversationActions()
   const { canUse } = useAIStatus()
   const activeSidebar = useSelector(selectors.console.getActiveSidebar)
 
diff --git a/src/scenes/Layout/index.tsx b/src/scenes/Layout/index.tsx
index 0d2f4f31d..fd8382691 100644
--- a/src/scenes/Layout/index.tsx
+++ b/src/scenes/Layout/index.tsx
@@ -47,6 +47,7 @@ import "allotment/dist/style.css"
 import { eventBus } from "../../modules/EventBus"
 import { EventType } from "../../modules/EventBus/types"
 import { AIStatusProvider } from "../../providers/AIStatusProvider"
+import { MCPBridgeProvider } from "../../providers/MCPBridgeProvider"
 
 const Page = styled.div`
   display: flex;
@@ -101,28 +102,30 @@ const Layout = () => {
       <EditorProvider>
         <AIConversationProvider>
           <AIStatusProvider>
-            <TopBar />
-            <Warnings />
-            <Root>
-              <Main>
-                <Page>
-                  <Console />
-                </Page>
-              </Main>
-
-              <Sidebar align="top">
-                <AIChatButton />
-                <TableDetailsButton />
-                <News />
-                <Help />
-              </Sidebar>
-              <TableDetailsDrawer />
-              <AIChatWindowLazy />
-            </Root>
-
-            <SideMenu />
-
-            <Footer />
+            <MCPBridgeProvider>
+              <TopBar />
+              <Warnings />
+              <Root>
+                <Main>
+                  <Page>
+                    <Console />
+                  </Page>
+                </Main>
+
+                <Sidebar align="top">
+                  <AIChatButton />
+                  <TableDetailsButton />
+                  <News />
+                  <Help />
+                </Sidebar>
+                <TableDetailsDrawer />
+                <AIChatWindowLazy />
+              </Root>
+
+              <SideMenu />
+
+              <Footer />
+            </MCPBridgeProvider>
           </AIStatusProvider>
         </AIConversationProvider>
       </EditorProvider>
diff --git a/src/scenes/News/index.tsx b/src/scenes/News/index.tsx
index 42730339e..c4793465e 100644
--- a/src/scenes/News/index.tsx
+++ b/src/scenes/News/index.tsx
@@ -4,6 +4,7 @@ import {
   IconWithTooltip,
   Loader,
   PrimaryToggleButton,
+  SafeMarkdown,
 } from "../../components"
 import styled from "styled-components"
 import React, { useEffect, useState, useContext } from "react"
@@ -11,7 +12,6 @@ import { QuestContext } from "../../providers"
 import { NewsItem } from "../../utils"
 import { useDispatch, useSelector } from "react-redux"
 import { selectors, actions } from "../../store"
-import ReactMarkdown from "react-markdown"
 import { db } from "../../store/db"
 import { UnreadItemsIcon } from "../../components/UnreadItemsIcon"
 import { Thumbnail } from "./thumbnail"
@@ -255,25 +255,11 @@ const News = () => {
                   )}
 
                 <NewsText>
-                  <ReactMarkdown
-                    components={{
-                      a: ({
-                        children,
-                        ...props
-                      }: React.ComponentProps<"a">) => (
-                        <a
-                          {...(props.href?.startsWith("http")
-                            ? { target: "_blank", rel: "noopener noreferrer" }
-                            : {})}
-                          {...props}
-                        >
-                          {children}
-                        </a>
-                      ),
-                    }}
-                  >
+                  {/* News bodies are non-GFM today; keep them so by passing an
+                      empty remark plugin set. Images preserved via allowImages. */}
+                  <SafeMarkdown allowImages remarkPlugins={[]}>
                     {newsItem.body}
-                  </ReactMarkdown>
+                  </SafeMarkdown>
                 </NewsText>
               </Item>
             ))}
diff --git a/src/scenes/Notifications/Notification/ErrorNotification/index.tsx b/src/scenes/Notifications/Notification/ErrorNotification/index.tsx
index 095a56194..fa3f68b8a 100644
--- a/src/scenes/Notifications/Notification/ErrorNotification/index.tsx
+++ b/src/scenes/Notifications/Notification/ErrorNotification/index.tsx
@@ -36,10 +36,21 @@ const CloseOutlineIcon = styled(CloseOutline)`
 `
 
 export const ErrorNotification = (props: NotificationShape) => {
-  const { createdAt, content, sideContent, isMinimized } = props
+  const {
+    createdAt,
+    content,
+    sideContent,
+    isMinimized,
+    compact,
+    hideTimestamp,
+  } = props
   return (
-    <Wrapper isMinimized={isMinimized} data-hook="error-notification">
-      <Timestamp createdAt={createdAt} />
+    <Wrapper
+      $isMinimized={isMinimized}
+      $compact={compact}
+      data-hook="error-notification"
+    >
+      {!hideTimestamp && <Timestamp createdAt={createdAt} />}
       <CloseOutlineIcon size="18px" />
       <Content>{content}</Content>
       <SideContent>{sideContent}</SideContent>
diff --git a/src/scenes/Notifications/Notification/InfoNotification/index.tsx b/src/scenes/Notifications/Notification/InfoNotification/index.tsx
index b38148e48..a34f6657f 100644
--- a/src/scenes/Notifications/Notification/InfoNotification/index.tsx
+++ b/src/scenes/Notifications/Notification/InfoNotification/index.tsx
@@ -28,10 +28,21 @@ import { NotificationShape } from "types"
 import { Timestamp } from "../Timestamp"
 
 export const InfoNotification = (props: NotificationShape) => {
-  const { createdAt, content, sideContent, isMinimized } = props
+  const {
+    createdAt,
+    content,
+    sideContent,
+    isMinimized,
+    compact,
+    hideTimestamp,
+  } = props
   return (
-    <Wrapper isMinimized={isMinimized} data-hook="info-notification">
-      <Timestamp createdAt={createdAt} />
+    <Wrapper
+      $isMinimized={isMinimized}
+      $compact={compact}
+      data-hook="info-notification"
+    >
+      {!hideTimestamp && <Timestamp createdAt={createdAt} />}
       <Content>{content}</Content>
       <SideContent>{sideContent}</SideContent>
     </Wrapper>
diff --git a/src/scenes/Notifications/Notification/LoadingNotification/index.tsx b/src/scenes/Notifications/Notification/LoadingNotification/index.tsx
index 075ffea5a..a7014e4c3 100644
--- a/src/scenes/Notifications/Notification/LoadingNotification/index.tsx
+++ b/src/scenes/Notifications/Notification/LoadingNotification/index.tsx
@@ -29,10 +29,21 @@ import { NotificationShape } from "types"
 import { Timestamp } from "../Timestamp"
 
 export const LoadingNotification = (props: NotificationShape) => {
-  const { createdAt, content, sideContent, isMinimized } = props
+  const {
+    createdAt,
+    content,
+    sideContent,
+    isMinimized,
+    compact,
+    hideTimestamp,
+  } = props
   return (
-    <Wrapper isMinimized={isMinimized} data-hook="loading-notification">
-      <Timestamp createdAt={createdAt} />
+    <Wrapper
+      $isMinimized={isMinimized}
+      $compact={compact}
+      data-hook="loading-notification"
+    >
+      {!hideTimestamp && <Timestamp createdAt={createdAt} />}
       <LoaderIcon />
       <Content>{content}</Content>
       <SideContent>{sideContent}</SideContent>
diff --git a/src/scenes/Notifications/Notification/NoticeNotification/index.tsx b/src/scenes/Notifications/Notification/NoticeNotification/index.tsx
index 3a4514719..8bec07094 100644
--- a/src/scenes/Notifications/Notification/NoticeNotification/index.tsx
+++ b/src/scenes/Notifications/Notification/NoticeNotification/index.tsx
@@ -36,10 +36,21 @@ const InfoOutlineIcon = styled(InfoOutline)`
 `
 
 export const NoticeNotification = (props: NotificationShape) => {
-  const { createdAt, content, sideContent, isMinimized } = props
+  const {
+    createdAt,
+    content,
+    sideContent,
+    isMinimized,
+    compact,
+    hideTimestamp,
+  } = props
   return (
-    <Wrapper isMinimized={isMinimized} data-hook="notice-notification">
-      <Timestamp createdAt={createdAt} />
+    <Wrapper
+      $isMinimized={isMinimized}
+      $compact={compact}
+      data-hook="notice-notification"
+    >
+      {!hideTimestamp && <Timestamp createdAt={createdAt} />}
       <InfoOutlineIcon size="18px" />
       <Content>{content}</Content>
       <SideContent>{sideContent}</SideContent>
diff --git a/src/scenes/Notifications/Notification/SuccessNotification/index.tsx b/src/scenes/Notifications/Notification/SuccessNotification/index.tsx
index 151d17dec..fe16c1c44 100644
--- a/src/scenes/Notifications/Notification/SuccessNotification/index.tsx
+++ b/src/scenes/Notifications/Notification/SuccessNotification/index.tsx
@@ -43,10 +43,22 @@ const ZapIcon = styled(Zap)`
 `
 
 export const SuccessNotification = (props: NotificationShape) => {
-  const { createdAt, content, sideContent, jitCompiled, isMinimized } = props
+  const {
+    createdAt,
+    content,
+    sideContent,
+    jitCompiled,
+    isMinimized,
+    compact,
+    hideTimestamp,
+  } = props
   return (
-    <Wrapper isMinimized={isMinimized} data-hook="success-notification">
-      <Timestamp createdAt={createdAt} />
+    <Wrapper
+      $isMinimized={isMinimized}
+      $compact={compact}
+      data-hook="success-notification"
+    >
+      {!hideTimestamp && <Timestamp createdAt={createdAt} />}
       {jitCompiled ? (
         <IconWithTooltip
           icon={<ZapIcon size="16px" />}
diff --git a/src/scenes/Notifications/Notification/styles.tsx b/src/scenes/Notifications/Notification/styles.tsx
index 682fe4796..9e729324f 100644
--- a/src/scenes/Notifications/Notification/styles.tsx
+++ b/src/scenes/Notifications/Notification/styles.tsx
@@ -27,14 +27,16 @@ import { NotificationShape } from "types"
 import { bezierTransition } from "../../../components"
 
 export const Wrapper = styled.div<{
-  isMinimized: NotificationShape["isMinimized"]
+  $isMinimized: NotificationShape["isMinimized"]
+  $compact?: boolean
 }>`
   display: flex;
   align-items: center;
   border-right: none;
-  height: ${({ isMinimized }) => (isMinimized ? "auto" : "4.5rem")};
-  border-bottom: ${({ isMinimized, theme }) =>
-    isMinimized ? "none" : `1px solid ${theme.color.backgroundDarker}`};
+  height: ${({ $isMinimized, $compact }) =>
+    $compact ? "4rem" : $isMinimized ? "auto" : "4.5rem"};
+  border-bottom: ${({ $isMinimized, theme }) =>
+    $isMinimized ? "none" : `1px solid ${theme.color.backgroundDarker}`};
   padding: 0 1rem;
   flex-shrink: 0;
   width: 100%;
diff --git a/src/scenes/Result/columnLayoutStore.ts b/src/scenes/Result/columnLayoutStore.ts
index 8979f0312..c02b1c4a3 100644
--- a/src/scenes/Result/columnLayoutStore.ts
+++ b/src/scenes/Result/columnLayoutStore.ts
@@ -1,14 +1,9 @@
 import type { ColumnDefinition } from "../../utils/questdb/types"
+import type { ColumnLayout } from "../../components/ResultGrid/types"
 
 const STORAGE_KEY = "result.grid.layout"
 const LRU_MAX = 50
 
-export type ColumnLayout = {
-  columnSizing?: Record<string, number>
-  columnOrder?: string[]
-  pinnedColumns?: string[]
-}
-
 type LayoutStore = Record<string, ColumnLayout>
 
 // Prefixed with a non-digit so the key is never an integer-like string: those
diff --git a/src/scenes/Result/index.tsx b/src/scenes/Result/index.tsx
index 536060bf1..4b316ae71 100644
--- a/src/scenes/Result/index.tsx
+++ b/src/scenes/Result/index.tsx
@@ -52,7 +52,7 @@ import {
   Tooltip,
 } from "../../components"
 import { actions, selectors } from "../../store"
-import { color, ErrorResult, RawErrorResult } from "../../utils"
+import { color, ErrorResult } from "../../utils"
 import * as QuestDB from "../../utils/questdb"
 import { ResultViewMode } from "scenes/Console/types"
 import type { IQuestDBGrid } from "../../js/console/grid.js"
@@ -65,7 +65,7 @@ import { NotificationType, RunningType } from "../../store/Query/types"
 import { copyToClipboard } from "../../utils/copyToClipboard"
 import { toast } from "../../components"
 import { useQueryExecutionState } from "../../hooks/useQueryExecutionState"
-import { API_VERSION } from "../../consts"
+import { downloadQueryResult } from "../../utils/downloadQueryResult"
 import { trackEvent } from "../../modules/ConsoleEventTracker"
 import { ConsoleEvent } from "../../modules/ConsoleEventTracker/events"
 import { useLocalStorage } from "../../providers/LocalStorageProvider"
@@ -378,42 +378,7 @@ const Result = ({ viewMode }: { viewMode: ResultViewMode }) => {
       return
     }
 
-    const url = `exp?${QuestDB.Client.encodeParams({
-      query: sql,
-      version: API_VERSION,
-      fmt: format,
-      filename: `questdb-query-${Date.now().toString()}`,
-      ...(format === "parquet" ? { rmode: "nodelay" } : {}),
-    })}`
-
-    const iframe = document.createElement("iframe")
-    iframe.style.display = "none"
-    document.body.appendChild(iframe)
-
-    iframe.onerror = (e) => {
-      if (typeof e === "object") {
-        toast.error(`An error occurred while downloading the file`)
-      }
-      const error = e as string
-      toast.error(`An error occurred while downloading the file: ${error}`)
-    }
-
-    iframe.onload = () => {
-      const content = iframe.contentDocument?.body?.textContent
-      if (content) {
-        let error = "An error occurred while downloading the file"
-        try {
-          const contentJson = JSON.parse(content) as RawErrorResult
-          error += `: ${contentJson.error ?? content}`
-        } catch (_) {
-          error += `: ${content}`
-        }
-        toast.error(error)
-      }
-      document.body.removeChild(iframe)
-    }
-
-    iframe.src = url
+    downloadQueryResult(sql, format)
   }
 
   return (
diff --git a/src/scenes/Search/SearchResults.tsx b/src/scenes/Search/SearchResults.tsx
index 37707e96f..9bfe51742 100644
--- a/src/scenes/Search/SearchResults.tsx
+++ b/src/scenes/Search/SearchResults.tsx
@@ -3,12 +3,20 @@ import styled from "styled-components"
 import type { SearchMatch } from "../../utils/textSearch"
 import { useEditor } from "../../providers"
 import { ChevronRight, ChevronDown } from "@styled-icons/boxicons-solid"
-import { FileTextIcon, ChartLineIcon } from "@phosphor-icons/react"
+import {
+  FileTextIcon,
+  ChartLineIcon,
+  NotebookIcon,
+} from "@phosphor-icons/react"
 import { Text } from "../../components"
 import {
   VirtualizedTree,
   VirtualizedTreeHandle,
 } from "../../components/VirtualizedTree"
+import { eventBus } from "../../modules/EventBus"
+import { EventType } from "../../modules/EventBus/types"
+import { requestCellReveal } from "../Editor/Notebook/cellReveal"
+import { waitForController } from "../../utils/notebookAIBridge"
 
 const ResultsContainer = styled.div`
   padding: 0;
@@ -116,6 +124,15 @@ const LineNumber = styled.span`
   min-width: 3.4rem;
 `
 
+const MatchType = styled.span`
+  color: ${({ theme }) => theme.color.comment};
+  margin-right: 0.8rem;
+  text-align: left;
+  font-size: 1.1rem;
+  min-width: 3.4rem;
+  flex-shrink: 0;
+`
+
 const MatchText = styled.span`
   color: ${({ theme }) => theme.color.foreground};
   font-family:
@@ -139,7 +156,7 @@ const NoResults = styled.div`
   text-align: center;
 `
 
-type FlattenedItem = { isMetricsMatch: boolean } & (
+type FlattenedItem = { isMetricsMatch: boolean; isNotebookMatch: boolean } & (
   | {
       type: "header"
       bufferId: number
@@ -155,6 +172,22 @@ type FlattenedItem = { isMetricsMatch: boolean } & (
   | { type: "title-match"; match: SearchMatch; id: string }
 )
 
+const renderResultIcon = (item: FlattenedItem) =>
+  item.isNotebookMatch ? (
+    <NotebookIcon />
+  ) : item.isMetricsMatch ? (
+    <ChartLineIcon />
+  ) : (
+    <FileTextIcon />
+  )
+
+const notebookMatchTypeLabel = (match: SearchMatch): string =>
+  match.notebookField === "chartName"
+    ? "Chart"
+    : match.cellType === "markdown"
+      ? "Text"
+      : "SQL"
+
 type SearchResultsProps = {
   groupedMatches: Map<number, SearchMatch[]>
   searchQuery: string
@@ -204,6 +237,7 @@ const SearchResultsComponent: React.FC<SearchResultsProps> = ({
             match,
             id: `title-match-${bufferId}-${index}`,
             isMetricsMatch: !!firstMatch.isMetricsMatch,
+            isNotebookMatch: !!firstMatch.isNotebookMatch,
           })
         })
       } else {
@@ -218,6 +252,7 @@ const SearchResultsComponent: React.FC<SearchResultsProps> = ({
           id: headerId,
           titleMatch,
           isMetricsMatch: !!firstMatch.isMetricsMatch,
+          isNotebookMatch: !!firstMatch.isNotebookMatch,
           isStale: staleBuffers.includes(bufferId),
         })
 
@@ -230,6 +265,7 @@ const SearchResultsComponent: React.FC<SearchResultsProps> = ({
                 id: `match-${bufferId}-${match.range.startLineNumber}-${match.range.startColumn}-${index}`,
                 parentId: headerId,
                 isMetricsMatch: !!match.isMetricsMatch,
+                isNotebookMatch: !!match.isNotebookMatch,
               })
             }
           })
@@ -331,12 +367,39 @@ const SearchResultsComponent: React.FC<SearchResultsProps> = ({
     ],
   )
 
+  const revealNotebookCell = useCallback(async (item: FlattenedItem) => {
+    if (item.type !== "match") return
+    const { match } = item
+    if (!match.cellId || !match.notebookField || !match.cellType) return
+    requestCellReveal({
+      bufferId: match.bufferId,
+      cellId: match.cellId,
+      range: match.range,
+      notebookField: match.notebookField,
+      cellType: match.cellType,
+    })
+    try {
+      await waitForController(match.bufferId)
+    } catch {
+      // Controller may never register (notebook closed/unmounted); the
+      // mount-drain still delivers the parked request when it does mount.
+    }
+    eventBus.publish(EventType.NOTEBOOK_REVEAL_CELL)
+  }, [])
+
   const positionEditorForItem = useCallback(
     (item: FlattenedItem) => {
       if (item.isMetricsMatch) {
         return
       }
 
+      if (item.isNotebookMatch) {
+        if (item.type === "match") {
+          void revealNotebookCell(item)
+        }
+        return
+      }
+
       if (item.type === "header" || item.type === "title-match") {
         editorRef.current?.revealPositionInCenter({ lineNumber: 1, column: 1 })
         editorRef.current?.setPosition({ lineNumber: 1, column: 1 })
@@ -368,7 +431,7 @@ const SearchResultsComponent: React.FC<SearchResultsProps> = ({
             ]) ?? []
       }
     },
-    [editorRef],
+    [editorRef, revealNotebookCell],
   )
 
   const handleClick = async (focusedIndex: number | null) => {
@@ -396,10 +459,10 @@ const SearchResultsComponent: React.FC<SearchResultsProps> = ({
     await openBufferFromItem(item, true)
     positionEditorForItem(item)
 
-    if (!item.isMetricsMatch) {
-      editorRef.current?.focus()
-    } else {
+    if (item.isMetricsMatch || item.isNotebookMatch) {
       setFocusedIndex(null)
+    } else {
+      editorRef.current?.focus()
     }
   }
 
@@ -495,9 +558,7 @@ const SearchResultsComponent: React.FC<SearchResultsProps> = ({
             >
               {isExpanded ? <ChevronDown /> : <ChevronRight />}
             </ChevronIcon>
-            <FileIcon aria-hidden="true">
-              {item.isMetricsMatch ? <ChartLineIcon /> : <FileTextIcon />}
-            </FileIcon>
+            <FileIcon aria-hidden="true">{renderResultIcon(item)}</FileIcon>
             <ItemText $isArchived={item.isArchived}>
               {item.titleMatch
                 ? renderHighlightedTextAtPosition(
@@ -525,14 +586,17 @@ const SearchResultsComponent: React.FC<SearchResultsProps> = ({
             data-active={isFocused}
             role="treeitem"
             aria-level={1}
-            aria-label={`${item.match.bufferLabel} ${item.match.isArchived ? "closed" : ""}`}
+            aria-label={`${item.isNotebookMatch ? "Notebook title: " : ""}${item.match.bufferLabel}${item.match.isArchived ? " closed" : ""}`}
           >
             <FileIcon
               data-hook="search-result-title-match-icon"
               aria-hidden="true"
             >
-              {item.isMetricsMatch ? <ChartLineIcon /> : <FileTextIcon />}
+              {renderResultIcon(item)}
             </FileIcon>
+            {item.isNotebookMatch && (
+              <MatchType aria-hidden="true">Title</MatchType>
+            )}
             <ItemText
               $isArchived={item.match.isArchived}
               data-hook="search-result-title-match-text"
@@ -559,14 +623,27 @@ const SearchResultsComponent: React.FC<SearchResultsProps> = ({
             data-active={isFocused}
             role="treeitem"
             aria-level={2}
-            aria-label={`Line ${item.match.range.startLineNumber}: ${item.match.previewText}`}
+            aria-label={
+              item.isNotebookMatch
+                ? `${notebookMatchTypeLabel(item.match)}: ${item.match.previewText}`
+                : `Line ${item.match.range.startLineNumber}: ${item.match.previewText}`
+            }
           >
-            <LineNumber
-              data-hook="search-result-line-number"
-              aria-hidden="true"
-            >
-              {item.match.range.startLineNumber}
-            </LineNumber>
+            {item.isNotebookMatch ? (
+              <MatchType
+                data-hook="search-result-match-type"
+                aria-hidden="true"
+              >
+                {notebookMatchTypeLabel(item.match)}
+              </MatchType>
+            ) : (
+              <LineNumber
+                data-hook="search-result-line-number"
+                aria-hidden="true"
+              >
+                {item.match.range.startLineNumber}
+              </LineNumber>
+            )}
             <MatchText>
               {renderHighlightedTextAtPosition(
                 item.match.previewText,
@@ -615,7 +692,8 @@ const SearchResultsComponent: React.FC<SearchResultsProps> = ({
           const target = event.target as HTMLElement | null
           if (
             target?.closest(".monaco-editor") ||
-            target?.closest(".metrics-root")
+            target?.closest(".metrics-root") ||
+            target?.closest("[data-notebook-root]")
           ) {
             await convertTemporaryToPermanent()
           } else {
diff --git a/src/scenes/Search/service.test.ts b/src/scenes/Search/service.test.ts
new file mode 100644
index 000000000..878d13d61
--- /dev/null
+++ b/src/scenes/Search/service.test.ts
@@ -0,0 +1,260 @@
+import { describe, it, expect } from "vitest"
+import {
+  SearchService,
+  getNotebookCellSearchTargets,
+  toNotebookSearchMatch,
+} from "./service"
+import type { Buffer } from "../../store/buffers"
+import type { NotebookCell, NotebookViewState } from "../../store/notebook"
+import type { TextMatch } from "../../utils/textSearch"
+
+const cell = (overrides: Partial<NotebookCell>): NotebookCell => ({
+  id: "cell-1",
+  position: 0,
+  value: "",
+  ...overrides,
+})
+
+const notebookBuffer = (
+  cells: NotebookCell[],
+  overrides: Partial<Buffer> = {},
+): Buffer => ({
+  id: 1,
+  label: "Trades dashboard",
+  value: "",
+  position: 0,
+  notebookViewState: { cells } as NotebookViewState,
+  ...overrides,
+})
+
+describe("getNotebookCellSearchTargets", () => {
+  it("returns the SQL source as a single 'cell' target", () => {
+    // Given a SQL cell with query text
+    const sqlCell = cell({ value: "SELECT price FROM trades" })
+
+    // When the searchable targets are derived
+    const targets = getNotebookCellSearchTargets(sqlCell)
+
+    // Then there is one 'cell' target typed as SQL
+    expect(targets).toEqual([
+      {
+        text: "SELECT price FROM trades",
+        notebookField: "cell",
+        cellType: "sql",
+      },
+    ])
+  })
+
+  it("returns the markdown source typed as 'markdown'", () => {
+    // Given a markdown cell
+    const mdCell = cell({ type: "markdown", value: "## Price notes" })
+
+    // When the searchable targets are derived
+    const targets = getNotebookCellSearchTargets(mdCell)
+
+    // Then the single target is typed as markdown
+    expect(targets).toEqual([
+      { text: "## Price notes", notebookField: "cell", cellType: "markdown" },
+    ])
+  })
+
+  it("adds a 'chartName' target after the cell value when a chart name exists", () => {
+    // Given a SQL cell that also has a named chart
+    const chartCell = cell({
+      value: "SELECT price FROM trades",
+      chartConfig: { xColumn: null, name: "BTC price", queries: [] },
+    })
+
+    // When the searchable targets are derived
+    const targets = getNotebookCellSearchTargets(chartCell)
+
+    // Then the cell value comes first, then the chart name
+    expect(targets).toEqual([
+      {
+        text: "SELECT price FROM trades",
+        notebookField: "cell",
+        cellType: "sql",
+      },
+      { text: "BTC price", notebookField: "chartName", cellType: "sql" },
+    ])
+  })
+
+  it("skips an empty value but still surfaces a chart name", () => {
+    // Given a cell whose query is empty but whose chart is named
+    const chartOnly = cell({
+      value: "",
+      chartConfig: { xColumn: null, name: "BTC price", queries: [] },
+    })
+
+    // When the searchable targets are derived
+    const targets = getNotebookCellSearchTargets(chartOnly)
+
+    // Then only the chart name target is produced
+    expect(targets).toEqual([
+      { text: "BTC price", notebookField: "chartName", cellType: "sql" },
+    ])
+  })
+
+  it("returns nothing for an empty cell with no chart", () => {
+    // Given an empty cell
+    const empty = cell({ value: "" })
+
+    // When the searchable targets are derived
+    // Then there are no targets
+    expect(getNotebookCellSearchTargets(empty)).toEqual([])
+  })
+})
+
+describe("toNotebookSearchMatch", () => {
+  it("maps a worker TextMatch to a notebook-tagged SearchMatch", () => {
+    // Given a buffer, cell, target and a raw text match
+    const buffer = notebookBuffer([], { id: 7, label: "Dash", archived: true })
+    const sqlCell = cell({ id: "cell-42" })
+    const textMatch: TextMatch = {
+      startOffset: 7,
+      endOffset: 12,
+      lineNumber: 1,
+      column: 8,
+      endLineNumber: 1,
+      endColumn: 13,
+      text: "price",
+      previewText: "SELECT price FROM",
+      matchStartInPreview: 7,
+      matchEndInPreview: 12,
+    }
+
+    // When it is mapped
+    const match = toNotebookSearchMatch(
+      buffer,
+      sqlCell,
+      { notebookField: "cell", cellType: "sql" },
+      textMatch,
+    )
+
+    // Then it carries the notebook addressing and the match range
+    expect(match).toMatchObject({
+      bufferId: 7,
+      bufferLabel: "Dash",
+      isNotebookMatch: true,
+      isArchived: true,
+      cellId: "cell-42",
+      cellType: "sql",
+      notebookField: "cell",
+      text: "price",
+      previewText: "SELECT price FROM",
+      range: {
+        startLineNumber: 1,
+        startColumn: 8,
+        endLineNumber: 1,
+        endColumn: 13,
+      },
+    })
+    expect(match.isMetricsMatch).toBeUndefined()
+  })
+})
+
+describe("SearchService.searchInSingleBuffer (notebook)", () => {
+  const search = (buffer: Buffer, query: string, maxMatches = 10000) =>
+    SearchService.searchInSingleBuffer(
+      buffer,
+      query,
+      {},
+      new AbortController().signal,
+      "test-search",
+      maxMatches,
+    )
+
+  it("finds matches in SQL, markdown and chart-name fields, tagged as notebook", async () => {
+    // Given a notebook with the query term in a SQL cell, a markdown cell and a chart name
+    const buffer = notebookBuffer([
+      cell({ id: "sql-cell", value: "SELECT price FROM trades" }),
+      cell({ id: "md-cell", type: "markdown", value: "## Price notes" }),
+      cell({
+        id: "chart-cell",
+        value: "SELECT ts, last FROM trades",
+        chartConfig: { xColumn: null, name: "BTC price", queries: [] },
+      }),
+    ])
+
+    // When searching for "price"
+    const matches = await search(buffer, "price")
+
+    // Then every match is a notebook match, never a metrics match
+    expect(matches.length).toBeGreaterThan(0)
+    expect(matches.every((m) => m.isNotebookMatch)).toBe(true)
+    expect(matches.some((m) => m.isMetricsMatch)).toBe(false)
+
+    // And each field surfaces with the right cell addressing
+    const byField = matches.map((m) => ({
+      cellId: m.cellId,
+      cellType: m.cellType,
+      notebookField: m.notebookField,
+    }))
+    expect(byField).toEqual(
+      expect.arrayContaining([
+        { cellId: "sql-cell", cellType: "sql", notebookField: "cell" },
+        { cellId: "md-cell", cellType: "markdown", notebookField: "cell" },
+        { cellId: "chart-cell", cellType: "sql", notebookField: "chartName" },
+      ]),
+    )
+  })
+
+  it("matches the notebook title and tags it as a notebook title match", async () => {
+    // Given a notebook whose label contains the query term
+    const buffer = notebookBuffer([cell({ value: "SELECT 1" })], {
+      label: "Price board",
+    })
+
+    // When searching for the term in the title
+    const matches = await search(buffer, "Price")
+
+    // Then a title match is produced and tagged as a notebook match
+    const titleMatch = matches.find((m) => m.isTitleMatch)
+    expect(titleMatch).toBeDefined()
+    expect(titleMatch?.isNotebookMatch).toBe(true)
+  })
+
+  it("respects the match capacity limit", async () => {
+    // Given a notebook with several occurrences of the term
+    const buffer = notebookBuffer([
+      cell({ id: "c1", value: "price price price" }),
+      cell({ id: "c2", value: "price price price" }),
+    ])
+
+    // When searching with a capacity of 2
+    const matches = await search(buffer, "price", 2)
+
+    // Then no more than 2 matches are returned
+    expect(matches.length).toBeLessThanOrEqual(2)
+  })
+
+  it("stops before the chart-name target once capacity is reached", async () => {
+    // Given a SQL cell whose value fills capacity and that also has a named chart
+    const buffer = notebookBuffer([
+      cell({
+        id: "c1",
+        value: "price price price",
+        chartConfig: { xColumn: null, name: "price chart", queries: [] },
+      }),
+    ])
+
+    // When searching with a capacity of 2
+    const matches = await search(buffer, "price", 2)
+
+    // Then capacity is filled by the cell value and the chart name is never reached
+    expect(matches).toHaveLength(2)
+    expect(matches.every((m) => m.notebookField === "cell")).toBe(true)
+  })
+
+  it("returns no content matches for a notebook with no cells", async () => {
+    // Given an empty notebook whose title still matches
+    const buffer = notebookBuffer([], { label: "Empty board" })
+
+    // When searching for a term present only in the title
+    const matches = await search(buffer, "board")
+
+    // Then the only match is the title match
+    expect(matches).toHaveLength(1)
+    expect(matches[0].isTitleMatch).toBe(true)
+  })
+})
diff --git a/src/scenes/Search/service.timeout.test.ts b/src/scenes/Search/service.timeout.test.ts
new file mode 100644
index 000000000..de596b3f9
--- /dev/null
+++ b/src/scenes/Search/service.timeout.test.ts
@@ -0,0 +1,110 @@
+import { describe, it, expect, vi, beforeEach } from "vitest"
+
+// Mock only findMatches; keep the real error classes so `instanceof` checks in
+// service.ts line up with what these tests throw.
+vi.mock("../../utils/textSearch", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../utils/textSearch")>()
+  return { ...actual, findMatches: vi.fn() }
+})
+
+import {
+  findMatches,
+  SearchTimeoutError,
+  SearchCancelledError,
+  type TextMatch,
+} from "../../utils/textSearch"
+import { SearchService } from "./service"
+import type { Buffer } from "../../store/buffers"
+import type { NotebookCell, NotebookViewState } from "../../store/notebook"
+
+const mockedFindMatches = vi.mocked(findMatches)
+
+const cell = (overrides: Partial<NotebookCell>): NotebookCell => ({
+  id: "cell-1",
+  position: 0,
+  value: "",
+  ...overrides,
+})
+
+const notebookBuffer = (cells: NotebookCell[]): Buffer => ({
+  id: 1,
+  label: "Notebook",
+  value: "",
+  position: 0,
+  notebookViewState: { cells } as NotebookViewState,
+})
+
+const textMatch = (text: string): TextMatch => ({
+  startOffset: 0,
+  endOffset: text.length,
+  lineNumber: 1,
+  column: 1,
+  endLineNumber: 1,
+  endColumn: text.length + 1,
+  text,
+  previewText: text,
+  matchStartInPreview: 0,
+  matchEndInPreview: text.length,
+})
+
+const run = (buffer: Buffer, query: string, signal: AbortSignal) =>
+  SearchService.searchInSingleBuffer(buffer, query, {}, signal, "t", 100)
+
+describe("searchInNotebookCells — timeout & cancellation", () => {
+  beforeEach(() => {
+    mockedFindMatches.mockReset()
+  })
+
+  it("re-throws accumulated partial matches when a cell search times out", async () => {
+    // Given a notebook where the first cell yields a match and the second times out
+    const buffer = notebookBuffer([
+      cell({ id: "c1", value: "price" }),
+      cell({ id: "c2", value: "price" }),
+    ])
+    let call = 0
+    mockedFindMatches.mockImplementation(() => {
+      call += 1
+      if (call === 1) return Promise.resolve([]) // title (buffer label)
+      if (call === 2) return Promise.resolve([textMatch("price")]) // c1 value
+      return Promise.reject(
+        new SearchTimeoutError("timed out", [textMatch("price")]),
+      ) // c2 value
+    })
+
+    // When searching
+    let thrown: unknown
+    try {
+      await run(buffer, "price", new AbortController().signal)
+    } catch (e) {
+      thrown = e
+    }
+
+    // Then a timeout error carries the matches gathered before the timeout
+    expect(thrown).toBeInstanceOf(SearchTimeoutError)
+    const partial = (thrown as SearchTimeoutError).partialSearchMatches ?? []
+    expect(partial).toHaveLength(2)
+    expect(partial.every((m) => m.isNotebookMatch)).toBe(true)
+  })
+
+  it("cancels mid-scan when the signal aborts between cells", async () => {
+    // Given a notebook being scanned cell by cell
+    const buffer = notebookBuffer([
+      cell({ id: "c1", value: "price" }),
+      cell({ id: "c2", value: "price" }),
+      cell({ id: "c3", value: "price" }),
+    ])
+    const controller = new AbortController()
+    let call = 0
+    mockedFindMatches.mockImplementation(() => {
+      call += 1
+      if (call === 2) controller.abort() // abort during c1's content search
+      return Promise.resolve([])
+    })
+
+    // When the signal aborts mid-flight
+    // Then the cell loop stops with a cancellation error
+    await expect(
+      run(buffer, "price", controller.signal),
+    ).rejects.toBeInstanceOf(SearchCancelledError)
+  })
+})
diff --git a/src/scenes/Search/service.ts b/src/scenes/Search/service.ts
index 7d9634b9d..3866b9913 100644
--- a/src/scenes/Search/service.ts
+++ b/src/scenes/Search/service.ts
@@ -1,11 +1,65 @@
-import type { SearchOptions, SearchMatch } from "../../utils/textSearch"
+import type {
+  SearchOptions,
+  SearchMatch,
+  TextMatch,
+} from "../../utils/textSearch"
 import type { Buffer } from "../../store/buffers"
+import type { NotebookCell } from "../../store/notebook"
 import {
   findMatches,
   SearchTimeoutError,
   SearchCancelledError,
 } from "../../utils/textSearch"
 
+type NotebookSearchTarget = {
+  text: string
+  notebookField: "cell" | "chartName"
+  cellType: "sql" | "markdown"
+}
+
+// The searchable strings of a single cell, in display order: its SQL/markdown
+// source, then the chart name when present. Chart config only exists on SQL cells.
+export const getNotebookCellSearchTargets = (
+  cell: NotebookCell,
+): NotebookSearchTarget[] => {
+  const cellType = cell.type === "markdown" ? "markdown" : "sql"
+  const targets: NotebookSearchTarget[] = []
+  if (cell.value) {
+    targets.push({ text: cell.value, notebookField: "cell", cellType })
+  }
+  const chartName = cell.chartConfig?.name
+  if (cellType === "sql" && chartName) {
+    targets.push({ text: chartName, notebookField: "chartName", cellType })
+  }
+  return targets
+}
+
+export const toNotebookSearchMatch = (
+  buffer: Buffer,
+  cell: NotebookCell,
+  target: Pick<NotebookSearchTarget, "notebookField" | "cellType">,
+  match: TextMatch,
+): SearchMatch => ({
+  bufferId: buffer.id!,
+  bufferLabel: buffer.label,
+  range: {
+    startLineNumber: match.lineNumber,
+    startColumn: match.column,
+    endLineNumber: match.endLineNumber,
+    endColumn: match.endColumn,
+  },
+  text: match.text,
+  previewText: match.previewText,
+  matchStartInPreview: match.matchStartInPreview,
+  matchEndInPreview: match.matchEndInPreview,
+  isArchived: buffer.archived || false,
+  archivedAt: buffer.archivedAt,
+  isNotebookMatch: true,
+  cellId: cell.id,
+  cellType: target.cellType,
+  notebookField: target.notebookField,
+})
+
 export type SearchResult = {
   query: string
   matches: SearchMatch[]
@@ -63,15 +117,26 @@ export class SearchService {
         )
       }
 
-      if (matches.length < maxMatches && buffer.value) {
+      if (matches.length < maxMatches) {
         const remainingCapacity = maxMatches - matches.length
-        const contentMatches = await this.searchInBuffer(
-          buffer,
-          query,
-          { caseSensitive, wholeWord, useRegex },
-          remainingCapacity,
-          searchId,
-        )
+        const contentMatches = buffer.notebookViewState
+          ? await this.searchInNotebookCells(
+              buffer,
+              query,
+              { caseSensitive, wholeWord, useRegex },
+              remainingCapacity,
+              searchId,
+              signal,
+            )
+          : buffer.value
+            ? await this.searchInBuffer(
+                buffer,
+                query,
+                { caseSensitive, wholeWord, useRegex },
+                remainingCapacity,
+                searchId,
+              )
+            : []
 
         if (signal?.aborted) {
           throw new SearchCancelledError()
@@ -320,6 +385,53 @@ export class SearchService {
     }
   }
 
+  private static async searchInNotebookCells(
+    buffer: Buffer,
+    query: string,
+    options: Pick<SearchOptions, "caseSensitive" | "wholeWord" | "useRegex">,
+    limit: number,
+    searchId: string,
+    signal: AbortSignal,
+  ): Promise<SearchMatch[]> {
+    const cells = buffer.notebookViewState?.cells
+    if (!cells || cells.length === 0) return []
+
+    const matches: SearchMatch[] = []
+
+    for (const cell of cells) {
+      if (matches.length >= limit) break
+      if (signal.aborted) throw new SearchCancelledError()
+      for (const target of getNotebookCellSearchTargets(cell)) {
+        if (matches.length >= limit) break
+        const remaining = limit - matches.length
+        try {
+          const textMatches = await findMatches(
+            target.text,
+            query,
+            options,
+            remaining,
+            searchId,
+          )
+          for (const textMatch of textMatches) {
+            matches.push(toNotebookSearchMatch(buffer, cell, target, textMatch))
+          }
+        } catch (e) {
+          if (e instanceof SearchTimeoutError) {
+            for (const textMatch of e.partialMatches ?? []) {
+              matches.push(
+                toNotebookSearchMatch(buffer, cell, target, textMatch),
+              )
+            }
+            throw new SearchTimeoutError(e.message, matches)
+          }
+          throw e
+        }
+      }
+    }
+
+    return matches
+  }
+
   static groupMatchesByBuffer(
     matches: SearchMatch[],
   ): Map<number, SearchMatch[]> {
@@ -357,6 +469,7 @@ export class SearchService {
       archivedAt: buffer.archivedAt,
       isTitleMatch: true,
       isMetricsMatch: !!buffer.metricsViewState,
+      isNotebookMatch: !!buffer.notebookViewState,
     }
   }
 
diff --git a/src/store/Query/types.ts b/src/store/Query/types.ts
index cf345bece..e7df2e74d 100644
--- a/src/store/Query/types.ts
+++ b/src/store/Query/types.ts
@@ -39,6 +39,8 @@ export type NotificationShape = Readonly<{
   isMinimized?: boolean
   isExplain?: boolean
   updateActiveNotification?: boolean
+  compact?: boolean
+  hideTimestamp?: boolean
 }>
 
 export type QueryNotifications = Readonly<{
diff --git a/src/store/aiConversations.ts b/src/store/aiConversations.ts
index 9a58aa923..e4c75cd6c 100644
--- a/src/store/aiConversations.ts
+++ b/src/store/aiConversations.ts
@@ -9,6 +9,9 @@ import type {
 export const aiConversationStore = {
   getAllMetas: () => db.ai_conversations.toArray(),
 
+  getMeta: (conversationId: ConversationId) =>
+    db.ai_conversations.get(conversationId),
+
   async getMessages(
     conversationId: ConversationId,
   ): Promise<ConversationMessage[]> {
diff --git a/src/store/buffers.ts b/src/store/buffers.ts
index 0e686d3e6..e9e427eb5 100644
--- a/src/store/buffers.ts
+++ b/src/store/buffers.ts
@@ -30,10 +30,13 @@ import {
   MetricViewMode,
   SampleBy,
 } from "scenes/Editor/Metrics/utils"
+import type { NotebookViewState } from "./notebook"
+import { createDefaultNotebookViewState } from "./notebook"
 
 export enum BufferType {
   SQL = "SQL",
   METRICS = "Metrics",
+  NOTEBOOK = "Notebook",
 }
 
 export type Metric = {
@@ -81,6 +84,7 @@ export type Buffer = {
   archivedAt?: number
   editorViewState?: editor.ICodeEditorViewState
   metricsViewState?: MetricsViewState
+  notebookViewState?: NotebookViewState
   isTemporary?: boolean
   isPreviewBuffer?: boolean
   previewContent?: PreviewContent
@@ -125,6 +129,7 @@ export const makeBuffer = ({
   value,
   editorViewState = defaultEditorViewState,
   metricsViewState,
+  notebookViewState,
   position,
   archived,
   archivedAt,
@@ -136,6 +141,7 @@ export const makeBuffer = ({
   value?: string
   editorViewState?: editor.ICodeEditorViewState
   metricsViewState?: MetricsViewState
+  notebookViewState?: NotebookViewState
   position: number
   archived?: boolean
   archivedAt?: number
@@ -146,8 +152,11 @@ export const makeBuffer = ({
   label,
   value: value ?? "",
   editorViewState:
-    metricsViewState || isPreviewBuffer ? undefined : editorViewState,
+    metricsViewState || notebookViewState || isPreviewBuffer
+      ? undefined
+      : editorViewState,
   metricsViewState,
+  notebookViewState,
   position,
   archived,
   archivedAt,
@@ -159,7 +168,13 @@ export const makeBuffer = ({
 export const makeFallbackBuffer = (bufferType: BufferType): Buffer => {
   return {
     id: 1,
-    ...makeBuffer({ label: bufferType, position: 0 }),
+    ...makeBuffer({
+      label: bufferType,
+      position: 0,
+      ...(bufferType === BufferType.NOTEBOOK
+        ? { notebookViewState: createDefaultNotebookViewState() }
+        : {}),
+    }),
   }
 }
 
@@ -178,7 +193,11 @@ export const bufferStore = {
       archived: buffer?.archived,
       archivedAt: buffer?.archivedAt,
       label: buffer?.label,
-      type: buffer?.metricsViewState ? BufferType.METRICS : BufferType.SQL,
+      type: buffer?.notebookViewState
+        ? BufferType.NOTEBOOK
+        : buffer?.metricsViewState
+          ? BufferType.METRICS
+          : BufferType.SQL,
     })),
 
   getActiveId: () =>
@@ -194,7 +213,11 @@ export const bufferStore = {
     db.buffers
       .get(id)
       .then((buffer) =>
-        buffer?.metricsViewState ? BufferType.METRICS : BufferType.SQL,
+        buffer?.notebookViewState
+          ? BufferType.NOTEBOOK
+          : buffer?.metricsViewState
+            ? BufferType.METRICS
+            : BufferType.SQL,
       ),
 
   update: (id: number, buffer: Partial<Buffer>) =>
diff --git a/src/store/db.ts b/src/store/db.ts
index 17dd2f9ca..6b323c678 100644
--- a/src/store/db.ts
+++ b/src/store/db.ts
@@ -29,6 +29,7 @@ import { makeBuffer, fallbackBuffer } from "./buffers"
 import { StoreKey } from "../utils/localStorage/types"
 import { getValue } from "../utils/localStorage"
 import type { AIConversation } from "../providers/AIConversationProvider/types"
+import type { NotebookResultSnapshot } from "./notebookResults"
 
 type EditorSettings = {
   key: string
@@ -54,6 +55,7 @@ export class Storage extends Dexie {
     { id?: number; created: number; name: string; props?: string },
     number
   >
+  notebook_results!: Table<NotebookResultSnapshot, [number, string]>
   ready: boolean = false
 
   constructor() {
@@ -107,6 +109,16 @@ export class Storage extends Dexie {
           meta.hasMessages = conversationIdsWithMessages.has(meta.id)
         })
     })
+    this.version(8).stores({
+      ai_conversations:
+        "id, bufferId, tableId, updatedAt, queryKey, notebookBufferId",
+    })
+    // Persisted, bounded per-cell result snapshots (compound key bufferId+cellId).
+    // Separate from `buffers` so the hot persist path stays light and the
+    // import/export buffer compatibility below is unaffected.
+    this.version(9).stores({
+      notebook_results: "[bufferId+cellId], bufferId, savedAt",
+    })
     // ──────────────────────────────────────────────────────────────────
     // ⚠️ IMPORTANT — Import/Export compatibility (https://github.com/dexie/Dexie.js/issues/1337)
     // If you add a new version here that changes the "buffers" table:
diff --git a/src/store/notebook.ts b/src/store/notebook.ts
new file mode 100644
index 000000000..7bed6cb87
--- /dev/null
+++ b/src/store/notebook.ts
@@ -0,0 +1,134 @@
+import type { editor } from "monaco-editor"
+import type { ColumnDefinition, Timings } from "../utils/questdb/types"
+import type { RunStatus } from "../utils/ai/runStatus"
+import type { ChartConfig } from "../scenes/Editor/Notebook/CellChart/chartTypes"
+
+export const MAX_NOTEBOOK_CELLS = 50
+
+export const MAX_CELL_LINES = 99_999
+
+export const exceedsCellLineLimit = (value: string): boolean =>
+  value.split("\n").length > MAX_CELL_LINES
+
+export type CellMode = "run" | "draw"
+
+// Cell kind. `undefined` means "sql" everywhere — code only ever tests
+// `=== "markdown"`, so old notebooks (no `type`) behave as SQL cells with no
+// migration. Markdown cells hold their source in `value` and are never executed.
+export type CellType = "sql" | "markdown"
+
+export type NotebookCell = {
+  id: string
+  position: number
+  value: string
+  type?: CellType
+  editorViewState?: editor.ICodeEditorViewState
+  result?: CellResult | null
+  topHeight?: number
+  bottomHeight?: number
+  topResized?: boolean
+  spotlightEditorRatio?: number
+  mode?: CellMode
+  chartConfig?: ChartConfig
+  autoRefresh?: boolean
+  isChartMaximized?: boolean
+  lastRunStatus?: RunStatus
+}
+
+export type DqlQueryResult = {
+  type: "dql"
+  query: string
+  columns: ColumnDefinition[]
+  dataset: (boolean | string | number | null)[][]
+  count: number
+  timestamp?: number
+  timings?: Timings
+}
+
+export type DdlDmlQueryResult = {
+  type: "ddl" | "dml"
+  query: string
+}
+
+export type ErrorQueryResult = {
+  type: "error"
+  query: string
+  error: string
+}
+
+export type TransientQueryResult = {
+  type: "running" | "queued" | "cancelled"
+  query: string
+}
+
+export type SingleQueryResult =
+  | DqlQueryResult
+  | DdlDmlQueryResult
+  | ErrorQueryResult
+  | TransientQueryResult
+
+export type CellResult = {
+  results: SingleQueryResult[]
+  activeResultIndex: number
+  error?: string
+  timestamp: number
+  script?: {
+    successCount: number
+    failedCount: number
+    durationMs: number
+  }
+}
+
+export type CellLayoutItem = {
+  i: string
+  x: number
+  y: number
+  w: number
+  h: number
+}
+
+export type NotebookLayoutMode = "list" | "grid"
+
+export type NotebookVariable = {
+  name: string
+  value: string
+}
+
+export type NotebookSettings = {
+  layoutMode?: NotebookLayoutMode
+  layout?: CellLayoutItem[]
+  variables?: NotebookVariable[]
+}
+
+export type NotebookViewState = {
+  cells: NotebookCell[]
+  focusedCellId?: string
+  maximizedCellId?: string
+  settings?: NotebookSettings
+}
+
+export const createCell = (position: number, value = ""): NotebookCell => ({
+  id: crypto.randomUUID(),
+  position,
+  value,
+})
+
+export const createDefaultNotebookViewState = (): NotebookViewState => ({
+  cells: [createCell(0)],
+})
+
+const isLegacyChartConfig = (cell: NotebookCell): boolean =>
+  cell.chartConfig != null && !Array.isArray(cell.chartConfig.queries)
+
+export const dropLegacyChartConfigs = (
+  state: NotebookViewState,
+): NotebookViewState => {
+  if (!state.cells.some(isLegacyChartConfig)) return state
+  const cells = state.cells.map((cell) => {
+    if (!isLegacyChartConfig(cell)) return cell
+    const next = { ...cell }
+    delete next.chartConfig
+    return next
+  })
+  return { ...state, cells }
+}
diff --git a/src/store/notebookResults.test.ts b/src/store/notebookResults.test.ts
new file mode 100644
index 000000000..412724349
--- /dev/null
+++ b/src/store/notebookResults.test.ts
@@ -0,0 +1,129 @@
+import "fake-indexeddb/auto"
+import { describe, it, expect, beforeEach, vi } from "vitest"
+
+// Stub browser globals before the db.ts singleton is constructed at import.
+vi.hoisted(() => {
+  const storage: Record<string, string> = {}
+  globalThis.localStorage = {
+    getItem: (k: string) => storage[k] ?? null,
+    setItem: (k: string, v: string) => {
+      storage[k] = v
+    },
+    removeItem: (k: string) => {
+      delete storage[k]
+    },
+    clear: () => {
+      Object.keys(storage).forEach((k) => delete storage[k])
+    },
+    get length() {
+      return Object.keys(storage).length
+    },
+    key: () => null,
+  } as Storage
+  globalThis.window = globalThis as unknown as Window & typeof globalThis
+  ;(globalThis as Record<string, unknown>).location = {
+    href: "http://localhost/",
+  }
+  ;(globalThis as Record<string, unknown>).history = {
+    replaceState: () => {},
+  }
+})
+
+import { db } from "./db"
+import {
+  saveCellSnapshot,
+  loadNotebookSnapshots,
+  deleteCellSnapshot,
+  deleteNotebookSnapshots,
+  pruneToRecentNotebooks,
+  type NotebookResultSnapshot,
+} from "./notebookResults"
+import type { SingleQueryResult } from "./notebook"
+
+const dqlResult: SingleQueryResult = {
+  type: "dql",
+  query: "select 1",
+  columns: [{ name: "x", type: "INT" }],
+  dataset: [[1], [2]],
+  count: 2,
+}
+
+const snap = (
+  bufferId: number,
+  cellId: string,
+  savedAt: number,
+  results: SingleQueryResult[] = [dqlResult],
+): NotebookResultSnapshot => ({
+  bufferId,
+  cellId,
+  sqlHash: "h",
+  results,
+  savedAt,
+})
+
+beforeEach(async () => {
+  await db.notebook_results.clear()
+})
+
+describe("notebookResults", () => {
+  it("round-trips a snapshot faithfully (dql + ddl + error)", async () => {
+    const results: SingleQueryResult[] = [
+      dqlResult,
+      { type: "ddl", query: "create table t (x int)" },
+      { type: "error", query: "bad", error: "boom" },
+    ]
+    await saveCellSnapshot(snap(1, "c1", 100, results))
+    const loaded = await loadNotebookSnapshots(1)
+    expect(loaded).toHaveLength(1)
+    expect(loaded[0].results).toEqual(results)
+  })
+
+  it("loadNotebookSnapshots returns only the given buffer's cells", async () => {
+    await saveCellSnapshot(snap(1, "c1", 100))
+    await saveCellSnapshot(snap(1, "c2", 100))
+    await saveCellSnapshot(snap(2, "c1", 100))
+    expect(
+      (await loadNotebookSnapshots(1)).map((s) => s.cellId).sort(),
+    ).toEqual(["c1", "c2"])
+    expect(await loadNotebookSnapshots(2)).toHaveLength(1)
+  })
+
+  it("put overwrites the same [bufferId+cellId]", async () => {
+    await saveCellSnapshot(snap(1, "c1", 100))
+    await saveCellSnapshot(snap(1, "c1", 200))
+    const loaded = await loadNotebookSnapshots(1)
+    expect(loaded).toHaveLength(1)
+    expect(loaded[0].savedAt).toBe(200)
+  })
+
+  it("deletes one cell, then a whole notebook", async () => {
+    await saveCellSnapshot(snap(1, "c1", 100))
+    await saveCellSnapshot(snap(1, "c2", 100))
+    await deleteCellSnapshot(1, "c1")
+    expect((await loadNotebookSnapshots(1)).map((s) => s.cellId)).toEqual([
+      "c2",
+    ])
+    await deleteNotebookSnapshots(1)
+    expect(await loadNotebookSnapshots(1)).toHaveLength(0)
+  })
+
+  it("prunes to the N most-recently-saved notebooks (recency = latest cell)", async () => {
+    await saveCellSnapshot(snap(1, "c1", 10))
+    await saveCellSnapshot(snap(2, "c1", 30))
+    await saveCellSnapshot(snap(2, "c2", 20))
+    await saveCellSnapshot(snap(3, "c1", 50))
+    await pruneToRecentNotebooks(2)
+    // buffers 3 (50) and 2 (30) kept; buffer 1 (10) evicted
+    expect(await loadNotebookSnapshots(1)).toHaveLength(0)
+    expect(await loadNotebookSnapshots(2)).toHaveLength(2)
+    expect(await loadNotebookSnapshots(3)).toHaveLength(1)
+  })
+
+  it("prune is a no-op under the budget", async () => {
+    await saveCellSnapshot(snap(1, "c1", 10))
+    await saveCellSnapshot(snap(2, "c1", 20))
+    await pruneToRecentNotebooks(10)
+    expect(await loadNotebookSnapshots(1)).toHaveLength(1)
+    expect(await loadNotebookSnapshots(2)).toHaveLength(1)
+  })
+})
diff --git a/src/store/notebookResults.ts b/src/store/notebookResults.ts
new file mode 100644
index 000000000..1d3df2c3e
--- /dev/null
+++ b/src/store/notebookResults.ts
@@ -0,0 +1,72 @@
+import { db } from "./db"
+import type { SingleQueryResult } from "./notebook"
+
+// A persisted, bounded copy of a cell's last run/draw result. One record per
+// cell (mode-agnostic: both the run grid and the draw chart render the same
+// rows). `results` is a faithful copy of the live `cell.result.results`, already
+// capped at the notebook row/byte limits before it is saved.
+export type NotebookResultSnapshot = {
+  bufferId: number
+  cellId: string
+  // Hash of the cell's SQL at save time; on restore we only reuse the snapshot
+  // when the cell's current SQL still matches.
+  sqlHash: string
+  results: SingleQueryResult[]
+  savedAt: number
+}
+
+// Only the N most-recently-saved notebooks keep persisted results; older ones
+// are evicted so IndexedDB can't grow unbounded across many notebooks.
+export const MAX_PERSISTED_NOTEBOOKS = 10
+
+export const saveCellSnapshot = async (
+  snapshot: NotebookResultSnapshot,
+): Promise<void> => {
+  await db.notebook_results.put(snapshot)
+}
+
+export const loadNotebookSnapshots = (
+  bufferId: number,
+): Promise<NotebookResultSnapshot[]> =>
+  db.notebook_results.where("bufferId").equals(bufferId).toArray()
+
+export const loadCellSnapshot = (
+  bufferId: number,
+  cellId: string,
+): Promise<NotebookResultSnapshot | undefined> =>
+  db.notebook_results.get([bufferId, cellId])
+
+export const deleteCellSnapshot = async (
+  bufferId: number,
+  cellId: string,
+): Promise<void> => {
+  await db.notebook_results.delete([bufferId, cellId])
+}
+
+export const deleteNotebookSnapshots = async (
+  bufferId: number,
+): Promise<void> => {
+  await db.notebook_results.where("bufferId").equals(bufferId).delete()
+}
+
+// Keep snapshots only for the `keep` most-recently-saved notebooks; a notebook's
+// recency is the latest `savedAt` among its cells. Iterates the `savedAt` index
+// keys only — snapshot payloads are never deserialized.
+export const pruneToRecentNotebooks = async (
+  keep: number = MAX_PERSISTED_NOTEBOOKS,
+): Promise<void> => {
+  const latestByBuffer = new Map<number, number>()
+  await db.notebook_results
+    .orderBy("savedAt")
+    .eachKey((savedAt, { primaryKey }) => {
+      // Ascending key order: the last write per buffer is its latest savedAt.
+      const [bufferId] = primaryKey
+      latestByBuffer.set(bufferId, savedAt as number)
+    })
+  if (latestByBuffer.size <= keep) return
+  const staleBuffers = Array.from(latestByBuffer.entries())
+    .sort((a, b) => b[1] - a[1]) // newest first
+    .slice(keep) // everything past the `keep` newest
+    .map(([bufferId]) => bufferId)
+  await db.notebook_results.where("bufferId").anyOf(staleBuffers).delete()
+}
diff --git a/src/styles/_editor.scss b/src/styles/_editor.scss
index ef9bad914..fdc88dda7 100644
--- a/src/styles/_editor.scss
+++ b/src/styles/_editor.scss
@@ -293,17 +293,16 @@
 
 
 .monaco-menu {
-  background: #343746;
+  background: #21222c;
   color: #f8f8f2;
 }
 
 .monaco-menu .action-menu-item {
-  border: 1px solid transparent;
   height: 3rem !important;
 
-  &:hover {
+  &:hover, &.focused {
     background: #043c5c !important;
-    border: 1px solid #8be9fd;
+    box-shadow: none !important;
   }
 
   &:not(.disabled) {
diff --git a/src/theme/global-styles/docsearch.ts b/src/theme/global-styles/docsearch.ts
index 919b445a0..e43434163 100644
--- a/src/theme/global-styles/docsearch.ts
+++ b/src/theme/global-styles/docsearch.ts
@@ -54,6 +54,15 @@ export const DocSearchStyles = css`
     }
   }
 
+  // Allotment clips its absolutely-positioned panes with overflow:hidden, which also
+  // makes the split view a scroll container; a collapsed-pane sash then pokes a few px
+  // past the edge and lets scrollIntoView/focus drag the whole shell. clip keeps the
+  // clipping but is not scrollable.
+  .split-view.split-view-vertical,
+  .split-view.split-view-horizontal {
+    overflow: clip;
+  }
+
   .DocSearch-Button {
     height: 3rem;
     border-radius: 0.4rem;
diff --git a/src/theme/index.ts b/src/theme/index.ts
index 321e5c357..cbdfc6b8b 100644
--- a/src/theme/index.ts
+++ b/src/theme/index.ts
@@ -43,11 +43,15 @@ const color: ColorShape = {
   selection: "#44475a",
   inputBorder: "#6b7280",
   selectionDarker: "#333544",
+  baseGrey: "#32343e",
   midnight: "#141725",
   comment: "#6272a4",
   red: "#ff5555",
   redDark: "#5a1d1d",
   redSecondary: "rgba(220, 40, 40, 0.72)",
+  dangerBackground: "rgba(220, 40, 40, 0.3)",
+  dangerBackgroundHover: "rgba(220, 40, 40, 0.4)",
+  dangerForeground: "#fa4d56",
   loginBackground: "#1D070E",
   orange10: "rgba(255, 165, 0, 0.10)",
   orangeDark: "#ff7f2a",
@@ -70,6 +74,7 @@ const color: ColorShape = {
   graphLegend: "#6e7078",
   offWhite: "#bdbdbd",
   offWhite2: "#d1d5db",
+  editorBackground: "#2c2e3d",
   aiStopButtonBg: "#da152832",
   aiStopButtonFg: "#da1e28",
   aiBadgeIconBg: "#290a13",
diff --git a/src/types/styled.d.ts b/src/types/styled.d.ts
index 709336cc0..a51869569 100644
--- a/src/types/styled.d.ts
+++ b/src/types/styled.d.ts
@@ -42,11 +42,15 @@ export type ColorShape = {
   selection: string
   inputBorder: string
   selectionDarker: string
+  baseGrey: string
   comment: string
   midnight: string
   red: string
   redDark: string
   redSecondary: string
+  dangerBackground: string
+  dangerBackgroundHover: string
+  dangerForeground: string
   loginBackground: string
   orange10: string
   orangeDark: string
@@ -69,6 +73,7 @@ export type ColorShape = {
   graphLegend: string
   offWhite: string
   offWhite2: string
+  editorBackground: string
   aiStopButtonBg: string
   aiStopButtonFg: string
   aiBadgeIconBg: string
diff --git a/src/utils/ai/anthropicProvider.test.ts b/src/utils/ai/anthropicProvider.test.ts
new file mode 100644
index 000000000..b6f0a523b
--- /dev/null
+++ b/src/utils/ai/anthropicProvider.test.ts
@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest"
+import { toNativeMessages } from "./anthropicProvider"
+import type { Message, ToolCall } from "./types"
+
+const toolCall = (over: Partial<ToolCall> = {}): ToolCall => ({
+  id: "call_1",
+  name: "run_query",
+  arguments: '{"sql":"SELECT 1"}',
+  timestamp: 0,
+  ...over,
+})
+
+describe("anthropicProvider.toNativeMessages", () => {
+  it("converts a plain user message to a user role param", () => {
+    // Given a single user message
+    const messages: Message[] = [{ role: "user", content: "hello" }]
+    // When converted to native shape
+    const native = toNativeMessages(messages)
+    // Then it becomes one user param with the raw string content
+    expect(native).toEqual([{ role: "user", content: "hello" }])
+  })
+
+  it("converts an assistant message with text and tool calls to text + tool_use blocks", () => {
+    // Given an assistant message carrying text and one tool call
+    const messages: Message[] = [
+      {
+        role: "assistant",
+        content: "running it",
+        tool_calls: [toolCall()],
+      },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then it becomes a single assistant param with text then tool_use
+    expect(native).toEqual([
+      {
+        role: "assistant",
+        content: [
+          { type: "text", text: "running it" },
+          {
+            type: "tool_use",
+            id: "call_1",
+            name: "run_query",
+            input: { sql: "SELECT 1" },
+          },
+        ],
+      },
+    ])
+  })
+
+  it("converts a tool-result message into a user tool_result block", () => {
+    // Given an assistant tool call followed by its tool result
+    const messages: Message[] = [
+      { role: "assistant", content: null, tool_calls: [toolCall()] },
+      { role: "tool", content: "1 row", tool_call_id: "call_1" },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then the result becomes a user message holding a tool_result block
+    expect(native).toEqual([
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool_use",
+            id: "call_1",
+            name: "run_query",
+            input: { sql: "SELECT 1" },
+          },
+        ],
+      },
+      {
+        role: "user",
+        content: [
+          { type: "tool_result", tool_use_id: "call_1", content: "1 row" },
+        ],
+      },
+    ])
+  })
+
+  it("merges a user message that lands between tool calls into the tool_result user message", () => {
+    // Given a tool result and an interleaved user message before the next turn
+    const messages: Message[] = [
+      { role: "assistant", content: null, tool_calls: [toolCall()] },
+      { role: "tool", content: "1 row", tool_call_id: "call_1" },
+      { role: "user", content: "now chart it" },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then both land in one user param with the tool_result ordered first
+    expect(native).toEqual([
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool_use",
+            id: "call_1",
+            name: "run_query",
+            input: { sql: "SELECT 1" },
+          },
+        ],
+      },
+      {
+        role: "user",
+        content: [
+          { type: "tool_result", tool_use_id: "call_1", content: "1 row" },
+          { type: "text", text: "now chart it" },
+        ],
+      },
+    ])
+  })
+
+  it("orders tool_result blocks before text when merging multiple user blocks", () => {
+    // Given a text user message followed by a tool result in the same user param
+    const messages: Message[] = [
+      { role: "user", content: "first text" },
+      { role: "tool", content: "result", tool_call_id: "call_1" },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then the merged user content puts the tool_result ahead of the text
+    expect(native).toEqual([
+      {
+        role: "user",
+        content: [
+          { type: "tool_result", tool_use_id: "call_1", content: "result" },
+          { type: "text", text: "first text" },
+        ],
+      },
+    ])
+  })
+
+  it("emits tool_use_id: undefined for a tool message missing tool_call_id (current behavior)", () => {
+    // Given a tool message with no tool_call_id
+    const messages: Message[] = [{ role: "tool", content: "orphan" }]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then the tool_result carries an undefined tool_use_id (locked-in behavior)
+    expect(native).toEqual([
+      {
+        role: "user",
+        content: [
+          { type: "tool_result", tool_use_id: undefined, content: "orphan" },
+        ],
+      },
+    ])
+  })
+})
diff --git a/src/utils/ai/anthropicProvider.ts b/src/utils/ai/anthropicProvider.ts
index 48a668f49..42a7bd742 100644
--- a/src/utils/ai/anthropicProvider.ts
+++ b/src/utils/ai/anthropicProvider.ts
@@ -12,16 +12,17 @@ import { getModelProps } from "./settings"
 import type { ProviderId } from "./settings"
 import {
   type AIProvider,
-  type FlowConfig,
+  type ExecuteFlowParams,
   type FlowResult,
   type ToolDefinition,
   type Message,
 } from "./types"
+import type { Permissions } from "../tools/permissions"
+import type { ValidateQueryResult } from "../questdb/types"
 import {
   StreamingError,
   RefusalError,
   MaxTokensError,
-  executeTool,
   safeJsonParse,
   CRITICAL_TOKEN_USAGE_MESSAGE,
   MAX_TOOL_CALL_ROUNDS,
@@ -29,12 +30,13 @@ import {
   getMessageTextLength,
   type ToolExecutionContext,
 } from "./shared"
+import { dispatchTool } from "../tools/dispatch"
 import {
   createHeaderFilteredFetch,
   ANTHROPIC_ALLOWED_HEADERS,
 } from "./fetchWithFilteredHeaders"
 
-function toNativeMessages(messages: Message[]): MessageParam[] {
+export function toNativeMessages(messages: Message[]): MessageParam[] {
   const result: MessageParam[] = []
 
   type UserBlock =
@@ -296,6 +298,8 @@ async function handleToolCalls(
   abortSignal?: AbortSignal,
   accumulatedTokens: TokenUsage = { inputTokens: 0, outputTokens: 0 },
   streaming?: StreamingCallback,
+  perms?: Permissions | (() => Permissions),
+  validateSql?: (sql: string) => Promise<ValidateQueryResult>,
   toolContext?: ToolExecutionContext,
   round: number = 1,
 ): Promise<AnthropicToolCallResult | AiAssistantAPIError> {
@@ -314,11 +318,14 @@ async function handleToolCalls(
 
   for (const toolUse of toolUseBlocks) {
     if ("name" in toolUse) {
-      const exec = await executeTool(
+      const exec = await dispatchTool(
         toolUse.name,
         toolUse.input,
         modelToolsClient,
         setStatus,
+        perms,
+        validateSql,
+        abortSignal,
         toolContext,
       )
 
@@ -426,6 +433,8 @@ async function handleToolCalls(
       abortSignal,
       newAccumulatedTokens,
       streaming,
+      perms,
+      validateSql,
       toolContext,
       round + 1,
     )
@@ -472,15 +481,10 @@ export function createAnthropicProvider(
       setStatus,
       abortSignal,
       streaming,
-    }: {
-      model: string
-      config: FlowConfig
-      modelToolsClient: ModelToolsClient
-      tools: ToolDefinition[]
-      setStatus: StatusCallback
-      abortSignal?: AbortSignal
-      streaming?: StreamingCallback
-    }): Promise<FlowResult | AiAssistantAPIError> {
+      perms,
+      validateSql,
+      toolContext: incomingToolContext,
+    }: ExecuteFlowParams): Promise<FlowResult | AiAssistantAPIError> {
       const initialMessages: MessageParam[] = []
       if (config.conversationHistory && config.conversationHistory.length > 0) {
         initialMessages.push(...toNativeMessages(config.conversationHistory))
@@ -494,7 +498,7 @@ export function createAnthropicProvider(
       const anthropicTools = toAnthropicTools(tools)
       const systemPrompt = config.systemInstructions
 
-      const toolContext: ToolExecutionContext = {}
+      const toolContext: ToolExecutionContext = incomingToolContext ?? {}
 
       const resolvedModel = toAnthropicModel(model)
 
@@ -535,6 +539,8 @@ export function createAnthropicProvider(
           abortSignal,
           { inputTokens: 0, outputTokens: 0 },
           streaming,
+          perms,
+          validateSql,
           toolContext,
         )
 
diff --git a/src/utils/ai/index.ts b/src/utils/ai/index.ts
index f4c51d3ed..f587f1556 100644
--- a/src/utils/ai/index.ts
+++ b/src/utils/ai/index.ts
@@ -7,7 +7,7 @@ export type {
   Message,
 } from "./types"
 export { createProvider } from "./registry"
-export { SCHEMA_TOOLS, DEFAULT_TOOLS, ALL_TOOLS } from "./tools"
+export { toolsForPermission } from "../tools/tools"
 export {
   RefusalError,
   MaxTokensError,
@@ -15,6 +15,7 @@ export {
   safeJsonParse,
   executeTool,
 } from "./shared"
+export { dispatchTool } from "../tools/dispatch"
 export {
   DOCS_INSTRUCTION,
   getUnifiedPrompt,
@@ -41,6 +42,8 @@ export {
   isAiAssistantConfigured,
   canUseAiAssistant,
   hasSchemaAccess,
+  getAiPermissions,
+  readLiveAiPermissions,
 } from "./settings"
 export type {
   ProviderId,
diff --git a/src/utils/ai/notebookSnapshot.test.ts b/src/utils/ai/notebookSnapshot.test.ts
new file mode 100644
index 000000000..f79318eda
--- /dev/null
+++ b/src/utils/ai/notebookSnapshot.test.ts
@@ -0,0 +1,455 @@
+import { describe, it, expect, beforeEach } from "vitest"
+import {
+  buildSnapshot,
+  formatDigest,
+  formatNotebookContextPrefix,
+  formatSnapshot,
+  type NotebookContextSnapshot,
+} from "./notebookSnapshot"
+import {
+  __resetNotebookAIBridgeForTests,
+  registerController,
+  type NotebookController,
+  type NotebookWorkspaceController,
+} from "../notebookAIBridge"
+import type {
+  NotebookCell,
+  NotebookSettings,
+  NotebookViewState,
+} from "../../store/notebook"
+import { createEmptyDigest } from "../../providers/AIConversationProvider/userActionDigest"
+
+const sql = (
+  id: string,
+  value = "",
+  overrides: Partial<NotebookCell> = {},
+): NotebookCell => ({
+  id,
+  position: 0,
+  value,
+  ...overrides,
+})
+
+const makeController = (
+  bufferId: number,
+  cells: NotebookCell[],
+  settings: NotebookSettings = {},
+  maximizedCellId: string | null = null,
+): NotebookController => ({
+  bufferId,
+  addCell: () => "c",
+  updateCell: () => undefined,
+  deleteCell: () => undefined,
+  moveCellUp: () => undefined,
+  moveCellDown: () => undefined,
+  duplicateCell: () => "c",
+  runCell: () =>
+    Promise.resolve({ success: true, queryCount: 1, results: ["success"] }),
+  setLayoutMode: () => undefined,
+  setVariables: () => undefined,
+  setCellLayout: () => undefined,
+  setCellMode: () => undefined,
+  setCellChartConfig: () => undefined,
+  setCellAutoRefresh: () => undefined,
+  setCellChartMaximized: () => undefined,
+  setCellMaximized: () => undefined,
+  applyNotebookState: () => ({
+    applied: { added: [], updated: [], deleted: [] },
+  }),
+  getCellsSnapshot: () => cells,
+  getSettings: () => settings,
+  getMaximizedCellId: () => maximizedCellId,
+})
+
+const makeWorkspace = (
+  stateByBuffer: Map<number, NotebookViewState>,
+  archivedSet = new Set<number>(),
+  deletedSet = new Set<number>(),
+): NotebookWorkspaceController => ({
+  createNotebook: () => Promise.resolve({ bufferId: 0, label: "x" }),
+  duplicateNotebook: () => Promise.resolve({ bufferId: 0, label: "x (copy)" }),
+  deleteNotebook: () => Promise.resolve(),
+  activateNotebook: () => Promise.resolve(true),
+  getBufferMeta(bufferId) {
+    if (deletedSet.has(bufferId)) return { kind: "deleted" }
+    if (archivedSet.has(bufferId))
+      return { kind: "archived", label: `nb-${bufferId}` }
+    const state = stateByBuffer.get(bufferId)
+    if (!state) return null
+    return {
+      kind: "inactive",
+      label: `nb-${bufferId}`,
+      notebookViewState: state,
+    }
+  },
+  listNotebookBuffers: () => [],
+})
+
+beforeEach(() => {
+  __resetNotebookAIBridgeForTests()
+})
+
+describe("buildSnapshot", () => {
+  it("returns null when no workspace is provided", () => {
+    expect(buildSnapshot(undefined, 1)).toBeNull()
+  })
+
+  it("returns { status: deleted } for a deleted buffer", () => {
+    const ws = makeWorkspace(new Map(), new Set(), new Set([1]))
+    const snap = buildSnapshot(ws, 1)
+    expect(snap?.status).toBe("deleted")
+  })
+
+  it("returns { status: archived, label } for an archived buffer", () => {
+    const ws = makeWorkspace(new Map(), new Set([1]))
+    const snap = buildSnapshot(ws, 1)
+    expect(snap).toEqual({ status: "archived", buffer_id: 1, label: "nb-1" })
+  })
+
+  it("prefers the mounted controller over persisted state", () => {
+    const ws = makeWorkspace(new Map([[1, { cells: [sql("a", "old")] }]]))
+    registerController(makeController(1, [sql("b", "new")]))
+    const snap = buildSnapshot(ws, 1)
+    expect(snap?.status).toBe("ok")
+    if (snap?.status === "ok") {
+      expect(snap.cells.map((c) => c.id)).toEqual(["b"])
+    }
+  })
+
+  it("falls back to persisted state when the controller is not mounted", () => {
+    const ws = makeWorkspace(new Map([[1, { cells: [sql("a", "persisted")] }]]))
+    const snap = buildSnapshot(ws, 1)
+    expect(snap?.status).toBe("ok")
+    if (snap?.status === "ok") {
+      expect(snap.cells[0].preview).toBe("persisted")
+    }
+  })
+
+  it("truncates previews to 120 chars and escapes newlines", () => {
+    const long = "a".repeat(200)
+    const withNewline = `line1\nline2`
+    const ws = makeWorkspace(
+      new Map([
+        [
+          1,
+          {
+            cells: [sql("a", long), sql("b", withNewline)],
+          },
+        ],
+      ]),
+    )
+    const snap = buildSnapshot(ws, 1)
+    if (snap?.status === "ok") {
+      expect(snap.cells[0].preview.length).toBeLessThanOrEqual(120)
+      expect(snap.cells[0].preview.endsWith("...")).toBe(true)
+      expect(snap.cells[1].preview).toBe("line1\\nline2")
+    } else {
+      throw new Error("expected ok snapshot")
+    }
+  })
+
+  it("trims last_run_error_summary to 200 chars and never leaks dataset/columns", () => {
+    const longErr = "x".repeat(300)
+    const cell = sql("a", "SELECT 1", {
+      result: {
+        results: [
+          {
+            type: "error",
+            query: "SELECT 1",
+            error: longErr,
+          },
+        ],
+        activeResultIndex: 0,
+        timestamp: 0,
+      },
+    })
+    const ws = makeWorkspace(new Map([[1, { cells: [cell] }]]))
+    const snap = buildSnapshot(ws, 1)
+    const json = JSON.stringify(snap)
+    expect(json).not.toContain("dataset")
+    expect(json).not.toContain("columns")
+    expect(json).not.toContain("count")
+    if (snap?.status === "ok") {
+      const c = snap.cells[0]
+      expect(c.last_run_status).toBe("error")
+      expect(c.last_run_error_summary?.length).toBeLessThanOrEqual(200)
+      expect(c.last_run_error_summary?.endsWith("...")).toBe(true)
+    } else {
+      throw new Error("expected ok snapshot")
+    }
+  })
+
+  it("includes grid positions only when layout_mode is 'grid'", () => {
+    const cells = [sql("a"), sql("b")]
+    const layout = [
+      { i: "a", x: 0, y: 0, w: 6, h: 4 },
+      { i: "b", x: 6, y: 0, w: 6, h: 4 },
+    ]
+    const listWs = makeWorkspace(
+      new Map([[1, { cells, settings: { layoutMode: "list", layout } }]]),
+    )
+    const gridWs = makeWorkspace(
+      new Map([[1, { cells, settings: { layoutMode: "grid", layout } }]]),
+    )
+    const listSnap = buildSnapshot(listWs, 1)
+    const gridSnap = buildSnapshot(gridWs, 1)
+    if (listSnap?.status === "ok" && gridSnap?.status === "ok") {
+      expect(listSnap.cells[0].grid).toBeUndefined()
+      expect(gridSnap.cells[0].grid).toEqual({ x: 0, y: 0, w: 6, h: 4 })
+    } else {
+      throw new Error("expected ok snapshots")
+    }
+  })
+
+  it("includes settings.variables when non-empty and omits when missing", () => {
+    const cells = [sql("a", "SELECT @x FROM trades")]
+    const withVars = makeWorkspace(
+      new Map([
+        [
+          1,
+          {
+            cells,
+            settings: {
+              variables: [
+                { name: "x", value: "10" },
+                { name: "sym", value: "'BTC'" },
+              ],
+            },
+          },
+        ],
+      ]),
+    )
+    const withoutVars = makeWorkspace(new Map([[2, { cells }]]))
+    const a = buildSnapshot(withVars, 1)
+    const b = buildSnapshot(withoutVars, 2)
+    if (a?.status === "ok" && b?.status === "ok") {
+      expect(a.variables).toEqual([
+        { name: "x", value: "10" },
+        { name: "sym", value: "'BTC'" },
+      ])
+      expect(b.variables).toBeUndefined()
+    } else {
+      throw new Error("expected ok snapshots")
+    }
+  })
+
+  it("surfaces the full chart config in wire shape (for PUT round-trip) without leaking series data", () => {
+    const cell = sql("a", "SELECT 1", {
+      mode: "draw",
+      autoRefresh: true,
+      isChartMaximized: false,
+      chartConfig: {
+        name: "Trades",
+        xColumn: "ts",
+        queries: [{ type: "line", yColumns: ["price", "volume"] }],
+      },
+    })
+    const ws = makeWorkspace(new Map([[1, { cells: [cell] }]]))
+    const snap = buildSnapshot(ws, 1)
+    if (snap?.status === "ok") {
+      // Snake-case wire shape the model can copy straight back into apply_notebook_state.
+      expect(snap.cells[0].chart_config).toEqual({
+        x_column: "ts",
+        name: "Trades",
+        queries: [{ type: "line", y_columns: ["price", "volume"] }],
+      })
+      expect(snap.cells[0].mode).toBe("draw")
+      expect(snap.cells[0].auto_refresh).toBe(true)
+    } else {
+      throw new Error("expected ok snapshot")
+    }
+  })
+})
+
+describe("formatSnapshot", () => {
+  it("emits a warning-variant block for archived status", () => {
+    const snap: NotebookContextSnapshot = {
+      status: "archived",
+      buffer_id: 7,
+      label: "Trades",
+    }
+    const out = formatSnapshot(snap)
+    expect(out).toContain("status: archived")
+    expect(out).toContain("buffer_id: 7")
+    expect(out).toContain("Trades")
+    expect(out).toContain("create_notebook")
+  })
+
+  it("emits a warning block for deleted status without label", () => {
+    const out = formatSnapshot({ status: "deleted", buffer_id: 9 })
+    expect(out).toContain("status: deleted")
+    expect(out).not.toMatch(/label:/)
+  })
+
+  it("serialises ok snapshots with cells and grid positions", () => {
+    const ws = makeWorkspace(
+      new Map([
+        [
+          1,
+          {
+            cells: [sql("a", "SELECT 1")],
+            settings: {
+              layoutMode: "grid",
+              layout: [{ i: "a", x: 0, y: 0, w: 12, h: 4 }],
+            },
+          },
+        ],
+      ]),
+    )
+    const snap = buildSnapshot(ws, 1)!
+    const out = formatSnapshot(snap)
+    expect(out).toContain("buffer_id: 1")
+    expect(out).toContain("layout_mode: grid")
+    expect(out).toContain("- id: a")
+    expect(out).toContain("grid: { x: 0, y: 0, w: 12, h: 4 }")
+  })
+
+  it("renders chart_config as one-line wire JSON the model can copy back", () => {
+    const cell = sql("a", "SELECT 1", {
+      mode: "draw",
+      chartConfig: {
+        xColumn: "ts",
+        queries: [{ type: "line", yColumns: ["price"] }],
+      },
+    })
+    const ws = makeWorkspace(new Map([[1, { cells: [cell] }]]))
+    const out = formatSnapshot(buildSnapshot(ws, 1)!)
+    expect(out).toContain(
+      'chart_config: {"x_column":"ts","queries":[{"type":"line","y_columns":["price"]}]}',
+    )
+  })
+
+  it("emits a variables block when present, omits when empty", () => {
+    const withVars = makeWorkspace(
+      new Map([
+        [
+          1,
+          {
+            cells: [sql("a", "SELECT @x")],
+            settings: {
+              variables: [
+                { name: "x", value: "10" },
+                { name: "sym", value: "'BTC'" },
+              ],
+            },
+          },
+        ],
+      ]),
+    )
+    const out = formatSnapshot(buildSnapshot(withVars, 1)!)
+    expect(out).toContain("variables:")
+    expect(out).toMatch(/x: "10"/)
+    expect(out).toMatch(/sym: "'BTC'"/)
+
+    const noVars = makeWorkspace(
+      new Map([[2, { cells: [sql("a", "SELECT 1")] }]]),
+    )
+    const out2 = formatSnapshot(buildSnapshot(noVars, 2)!)
+    expect(out2).not.toContain("variables:")
+  })
+})
+
+describe("formatDigest", () => {
+  it("returns empty string for an empty digest", () => {
+    expect(formatDigest(createEmptyDigest())).toBe("")
+  })
+
+  it("emits a block listing added/deleted/edited/ran/layout/status", () => {
+    const d = createEmptyDigest()
+    d.added.add("a1")
+    d.deleted.add("d1")
+    d.edited.add("e1")
+    d.ran.set("r1", "error")
+    d.layoutModeTo = "grid"
+    d.notebookStatusChange = "archived"
+    const out = formatDigest(d)
+    expect(out).toContain("added: [a1]")
+    expect(out).toContain("deleted: [d1]")
+    expect(out).toContain("edited: [e1]")
+    expect(out).toContain("ran: { r1: error }")
+    expect(out).toContain("layout_mode: grid")
+    expect(out).toContain("notebook_status: archived")
+  })
+})
+
+describe("formatNotebookContextPrefix", () => {
+  it("returns empty string when all inputs are empty", () => {
+    expect(formatNotebookContextPrefix(null, undefined)).toBe("")
+    expect(formatNotebookContextPrefix(null, createEmptyDigest())).toBe("")
+  })
+
+  it("combines snapshot + digest blocks with trailing newline", () => {
+    const snap: NotebookContextSnapshot = {
+      status: "ok",
+      buffer_id: 1,
+      label: "x",
+      layout_mode: "list",
+      maximized_cell_id: null,
+      cells: [],
+    }
+    const digest = createEmptyDigest()
+    digest.added.add("a")
+    const prefix = formatNotebookContextPrefix(snap, digest)
+    expect(prefix.endsWith("\n\n")).toBe(true)
+    expect(prefix).toContain("<notebook_context>")
+    expect(prefix).toContain("<user_events")
+  })
+
+  it("emits <workspace> first, then <notebook_context>, then <user_events>", () => {
+    const snap: NotebookContextSnapshot = {
+      status: "ok",
+      buffer_id: 2,
+      label: "Notebook 1",
+      layout_mode: "list",
+      maximized_cell_id: null,
+      cells: [],
+    }
+    const digest = createEmptyDigest()
+    digest.added.add("a")
+    const prefix = formatNotebookContextPrefix(snap, digest, {
+      notebooks: [
+        {
+          buffer_id: 2,
+          label: "Notebook 1",
+          archived: false,
+          bound_to_this_chat: true,
+        },
+      ],
+      active: { buffer_id: 2, label: "Notebook 1", kind: "notebook" },
+    })
+    const wsIdx = prefix.indexOf("<workspace>")
+    const ctxIdx = prefix.indexOf("<notebook_context>")
+    const evtIdx = prefix.indexOf("<user_events")
+    expect(wsIdx).toBeGreaterThan(-1)
+    expect(ctxIdx).toBeGreaterThan(wsIdx)
+    expect(evtIdx).toBeGreaterThan(ctxIdx)
+  })
+
+  it("emits <workspace> alone for unbound chats with notebook tabs", () => {
+    const prefix = formatNotebookContextPrefix(null, undefined, {
+      notebooks: [
+        { buffer_id: 5, label: "Sales", archived: false },
+        { buffer_id: 9, label: "Old", archived: true },
+      ],
+      active: { buffer_id: 5, label: "Sales", kind: "notebook" },
+    })
+    expect(prefix).toContain("<workspace>")
+    expect(prefix).not.toContain("<notebook_context>")
+    expect(prefix).not.toContain("<user_events")
+    expect(prefix).toContain('label: "Sales"')
+    expect(prefix).toContain("archived: true")
+    expect(prefix).toContain("kind: notebook")
+  })
+
+  it("workspace block quotes labels and exposes buffer_id / kind", () => {
+    const prefix = formatNotebookContextPrefix(null, undefined, {
+      notebooks: [{ buffer_id: 42, label: "Trades", archived: false }],
+      active: { buffer_id: 3, label: "Query 1", kind: "sql" },
+    })
+    expect(prefix).toContain(
+      'active: { buffer_id: 3, label: "Query 1", kind: sql }',
+    )
+    expect(prefix).toContain("buffer_id: 42")
+    expect(prefix).toContain('label: "Trades"')
+  })
+})
diff --git a/src/utils/ai/notebookSnapshot.ts b/src/utils/ai/notebookSnapshot.ts
new file mode 100644
index 000000000..0eb9ec0de
--- /dev/null
+++ b/src/utils/ai/notebookSnapshot.ts
@@ -0,0 +1,341 @@
+import {
+  getController,
+  type NotebookWorkspaceController,
+} from "../notebookAIBridge"
+import { sanitizeForPromptContext } from "./sanitizeForPromptContext"
+import type {
+  CellLayoutItem,
+  NotebookCell,
+  NotebookSettings,
+} from "../../store/notebook"
+import type { UserActionDigest } from "../../providers/AIConversationProvider/types"
+import type { WorkspaceInfo } from "../executeAIFlow"
+import { normalizeVariables } from "../../scenes/Editor/Notebook/declareUtils"
+import { getCellRunStatus, type RunStatus } from "./runStatus"
+import type { ChartConfig } from "../../scenes/Editor/Notebook/CellChart/chartTypes"
+
+type ChartQueryWire = {
+  type: string
+  y_columns: string[]
+  ohlc?: { open: string; high: string; low: string; close: string }
+  partition_by_column?: string
+  axis?: "left" | "right"
+  enabled?: boolean
+  name?: string
+}
+export type ChartConfigWire = {
+  x_column: string | null
+  name?: string
+  queries: (ChartQueryWire | null)[]
+  right_axis?: { name?: string; min?: number; max?: number }
+}
+
+// Structural data only — previews ≤ 120 chars, error summaries ≤ 200 chars.
+// Never includes columns/rows/count from query results.
+export type NotebookContextCell = {
+  id: string
+  preview: string
+  // Set only when the value exceeds PREVIEW_MAX. A preview is never the full
+  // value to echo back — read the cell with get_cell when rewriting it.
+  preview_truncated?: true
+  full_length?: number
+  // Omitted for SQL cells (the default); "markdown" for prose cells (rendered,
+  // never executed).
+  type?: "sql" | "markdown"
+  mode?: "run" | "draw"
+  auto_refresh?: boolean
+  is_chart_maximized?: boolean
+  chart_config?: ChartConfigWire
+  last_run_status?: RunStatus
+  last_run_error_summary?: string
+  grid?: { x: number; y: number; w: number; h: number }
+}
+
+export type NotebookContextSnapshot =
+  | {
+      status: "ok"
+      buffer_id: number
+      label: string
+      layout_mode: "list" | "grid"
+      maximized_cell_id: string | null
+      variables?: Array<{ name: string; value: string }>
+      cells: NotebookContextCell[]
+    }
+  | {
+      status: "archived" | "deleted"
+      buffer_id: number
+      label?: string
+    }
+
+const PREVIEW_MAX = 120
+const ERROR_MAX = 200
+
+const truncate = (s: string, max: number): string =>
+  s.length <= max ? s : `${s.slice(0, max - 3)}...`
+
+const escapeNewlines = (s: string): string => s.replace(/\n/g, "\\n")
+
+export { sanitizeForPromptContext }
+
+const preview = (value: string): string =>
+  sanitizeForPromptContext(escapeNewlines(truncate(value, PREVIEW_MAX)))
+
+export const toChartConfigWire = (cfg: ChartConfig): ChartConfigWire => ({
+  x_column: cfg.xColumn,
+  ...(cfg.name != null ? { name: cfg.name } : {}),
+  queries: cfg.queries.map((q) =>
+    q == null
+      ? null
+      : {
+          type: q.type,
+          y_columns: q.yColumns,
+          ...(q.ohlc ? { ohlc: q.ohlc } : {}),
+          ...(q.partitionByColumn
+            ? { partition_by_column: q.partitionByColumn }
+            : {}),
+          ...(q.axis ? { axis: q.axis } : {}),
+          ...(q.enabled === false ? { enabled: false } : {}),
+          ...(q.name != null ? { name: q.name } : {}),
+        },
+  ),
+  ...(cfg.rightAxis ? { right_axis: cfg.rightAxis } : {}),
+})
+
+// Forwards ONLY status + trimmed error — no columns, rows, or counts.
+const lastRunSummary = (
+  cell: NotebookCell,
+): Pick<NotebookContextCell, "last_run_status" | "last_run_error_summary"> => {
+  const { status, error } = getCellRunStatus(cell)
+  if (status === "error") {
+    return {
+      last_run_status: "error",
+      last_run_error_summary: sanitizeForPromptContext(
+        truncate(error ?? "", ERROR_MAX),
+      ),
+    }
+  }
+  return { last_run_status: status }
+}
+
+const buildCell = (
+  cell: NotebookCell,
+  gridByCellId: Map<string, CellLayoutItem>,
+  layoutMode: "list" | "grid",
+): NotebookContextCell => {
+  const out: NotebookContextCell = {
+    id: cell.id,
+    preview: preview(cell.value),
+    ...lastRunSummary(cell),
+  }
+  if (cell.value.length > PREVIEW_MAX) {
+    out.preview_truncated = true
+    out.full_length = cell.value.length
+  }
+  if (cell.type === "markdown") out.type = "markdown"
+  if (cell.mode === "draw" || cell.mode === "run") out.mode = cell.mode
+  if (typeof cell.autoRefresh === "boolean") out.auto_refresh = cell.autoRefresh
+  if (typeof cell.isChartMaximized === "boolean") {
+    out.is_chart_maximized = cell.isChartMaximized
+  }
+  const chartConfig = cell.chartConfig
+  if (chartConfig && Array.isArray(chartConfig.queries)) {
+    out.chart_config = toChartConfigWire(chartConfig)
+  }
+  if (layoutMode === "grid") {
+    const g = gridByCellId.get(cell.id)
+    if (g) out.grid = { x: g.x, y: g.y, w: g.w, h: g.h }
+  }
+  return out
+}
+
+// Prefers live controller (freshest); falls back to persisted view state so unmounted notebooks work without a tab switch.
+export const buildSnapshot = (
+  workspace: NotebookWorkspaceController | undefined,
+  bufferId: number,
+): NotebookContextSnapshot | null => {
+  if (!workspace) return null
+  const meta = workspace.getBufferMeta(bufferId)
+  if (meta === null) return null
+  if (meta.kind === "deleted") {
+    return { status: "deleted", buffer_id: bufferId }
+  }
+  if (meta.kind === "archived") {
+    return { status: "archived", buffer_id: bufferId, label: meta.label }
+  }
+
+  const controller = getController(bufferId)
+  const cells: NotebookCell[] = controller
+    ? controller.getCellsSnapshot()
+    : meta.notebookViewState.cells
+  const settings: NotebookSettings = controller
+    ? controller.getSettings()
+    : (meta.notebookViewState.settings ?? {})
+  const maximizedCellId = controller
+    ? controller.getMaximizedCellId()
+    : (meta.notebookViewState.maximizedCellId ?? null)
+
+  const layoutMode: "list" | "grid" = settings.layoutMode ?? "list"
+  const gridByCellId = new Map<string, CellLayoutItem>(
+    (settings.layout ?? []).map((l) => [l.i, l]),
+  )
+
+  const out: NotebookContextSnapshot = {
+    status: "ok",
+    buffer_id: bufferId,
+    label: meta.label,
+    layout_mode: layoutMode,
+    maximized_cell_id: maximizedCellId,
+    cells: cells.map((c) => buildCell(c, gridByCellId, layoutMode)),
+  }
+  const variables = normalizeVariables(settings.variables)
+  if (variables.length > 0) {
+    out.variables = variables
+  }
+  return out
+}
+
+// YAML-ish shape — stable regardless of escape characters in cell values.
+export const formatSnapshot = (snap: NotebookContextSnapshot): string => {
+  if (snap.status !== "ok") {
+    const lines = [
+      "<notebook_context>",
+      `  status: ${snap.status}`,
+      `  buffer_id: ${snap.buffer_id}`,
+    ]
+    if (snap.label)
+      lines.push(
+        `  label: ${JSON.stringify(sanitizeForPromptContext(snap.label))}`,
+      )
+    lines.push(
+      "  hint: Previously-attached notebook is unavailable. Call create_notebook if the user wants to continue.",
+    )
+    lines.push("</notebook_context>")
+    return lines.join("\n")
+  }
+
+  const lines: string[] = ["<notebook_context>"]
+  lines.push(`  buffer_id: ${snap.buffer_id}`)
+  lines.push(`  label: ${JSON.stringify(sanitizeForPromptContext(snap.label))}`)
+  lines.push(`  layout_mode: ${snap.layout_mode}`)
+  lines.push(
+    `  maximized_cell_id: ${
+      snap.maximized_cell_id ? JSON.stringify(snap.maximized_cell_id) : "null"
+    }`,
+  )
+  if (snap.variables && snap.variables.length > 0) {
+    lines.push("  variables:")
+    for (const { name, value } of snap.variables) {
+      lines.push(
+        `    ${name}: ${JSON.stringify(sanitizeForPromptContext(value))}`,
+      )
+    }
+  }
+  lines.push("  cells:")
+  for (const c of snap.cells) {
+    lines.push(`    - id: ${c.id}`)
+    lines.push(`      preview: ${JSON.stringify(c.preview)}`)
+    if (c.preview_truncated) {
+      lines.push(`      preview_truncated: true`)
+      lines.push(`      full_length: ${c.full_length}`)
+    }
+    if (c.type) lines.push(`      type: ${c.type}`)
+    if (c.mode) lines.push(`      mode: ${c.mode}`)
+    if (c.auto_refresh !== undefined)
+      lines.push(`      auto_refresh: ${c.auto_refresh}`)
+    if (c.is_chart_maximized !== undefined)
+      lines.push(`      is_chart_maximized: ${c.is_chart_maximized}`)
+    if (c.chart_config) {
+      lines.push(
+        `      chart_config: ${sanitizeForPromptContext(
+          JSON.stringify(c.chart_config),
+        )}`,
+      )
+    }
+    if (c.last_run_status)
+      lines.push(`      last_run_status: ${c.last_run_status}`)
+    if (c.last_run_error_summary)
+      lines.push(
+        `      last_run_error_summary: ${JSON.stringify(
+          c.last_run_error_summary,
+        )}`,
+      )
+    if (c.grid) {
+      lines.push(
+        `      grid: { x: ${c.grid.x}, y: ${c.grid.y}, w: ${c.grid.w}, h: ${c.grid.h} }`,
+      )
+    }
+  }
+  lines.push("</notebook_context>")
+  return lines.join("\n")
+}
+
+// Empty digest returns "" so the block is omitted entirely.
+export const formatDigest = (digest: UserActionDigest): string => {
+  const parts: string[] = []
+  if (digest.added.size > 0)
+    parts.push(`  added: [${Array.from(digest.added).join(", ")}]`)
+  if (digest.deleted.size > 0)
+    parts.push(`  deleted: [${Array.from(digest.deleted).join(", ")}]`)
+  if (digest.edited.size > 0)
+    parts.push(`  edited: [${Array.from(digest.edited).join(", ")}]`)
+  if (digest.ran.size > 0) {
+    const entries = Array.from(digest.ran.entries())
+      .map(([id, status]) => `${id}: ${status}`)
+      .join(", ")
+    parts.push(`  ran: { ${entries} }`)
+  }
+  if (digest.layoutModeTo) parts.push(`  layout_mode: ${digest.layoutModeTo}`)
+  if (digest.notebookStatusChange)
+    parts.push(`  notebook_status: ${digest.notebookStatusChange}`)
+  if (parts.length === 0) return ""
+  return [
+    `<user_events since_last_turn="true">`,
+    ...parts,
+    "</user_events>",
+  ].join("\n")
+}
+
+// Emitted even for unbound chats so the AI can resolve user-said labels to buffer_ids.
+export const formatWorkspace = (ws: WorkspaceInfo): string => {
+  const lines: string[] = ["<workspace>"]
+  if (ws.active) {
+    lines.push(
+      `  active: { buffer_id: ${ws.active.buffer_id}, label: ${JSON.stringify(
+        sanitizeForPromptContext(ws.active.label),
+      )}, kind: ${ws.active.kind} }`,
+    )
+  }
+  if (ws.notebooks.length > 0) {
+    lines.push("  notebooks:")
+    for (const nb of ws.notebooks) {
+      const parts = [
+        `buffer_id: ${nb.buffer_id}`,
+        `label: ${JSON.stringify(sanitizeForPromptContext(nb.label))}`,
+      ]
+      if (nb.archived) parts.push("archived: true")
+      if (nb.bound_to_this_chat) parts.push("bound_to_this_chat: true")
+      lines.push(`    - { ${parts.join(", ")} }`)
+    }
+  } else {
+    lines.push("  notebooks: []")
+  }
+  lines.push("</workspace>")
+  return lines.join("\n")
+}
+
+// Order matters: workspace first (label resolution), then snapshot, then digest.
+export const formatNotebookContextPrefix = (
+  snap: NotebookContextSnapshot | null,
+  digest: UserActionDigest | undefined,
+  workspace?: WorkspaceInfo,
+): string => {
+  const out: string[] = []
+  if (workspace) out.push(formatWorkspace(workspace))
+  if (snap) out.push(formatSnapshot(snap))
+  if (digest) {
+    const d = formatDigest(digest)
+    if (d) out.push(d)
+  }
+  if (out.length === 0) return ""
+  return `${out.join("\n")}\n\n`
+}
diff --git a/src/utils/ai/openaiChatCompletionsProvider.test.ts b/src/utils/ai/openaiChatCompletionsProvider.test.ts
new file mode 100644
index 000000000..9a218b077
--- /dev/null
+++ b/src/utils/ai/openaiChatCompletionsProvider.test.ts
@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest"
+import { toNativeMessages } from "./openaiChatCompletionsProvider"
+import type { Message, ToolCall } from "./types"
+
+const toolCall = (over: Partial<ToolCall> = {}): ToolCall => ({
+  id: "call_1",
+  name: "run_query",
+  arguments: '{"sql":"SELECT 1"}',
+  timestamp: 0,
+  ...over,
+})
+
+describe("openaiChatCompletionsProvider.toNativeMessages", () => {
+  it("converts a plain user message to a user role message", () => {
+    // Given a single user message
+    const messages: Message[] = [{ role: "user", content: "hello" }]
+    // When converted to Chat Completions shape
+    const native = toNativeMessages(messages)
+    // Then it becomes one user message with the raw string content
+    expect(native).toEqual([{ role: "user", content: "hello" }])
+  })
+
+  it("converts an assistant message with tool calls to assistant + tool_calls", () => {
+    // Given an assistant message with text and one tool call
+    const messages: Message[] = [
+      {
+        role: "assistant",
+        content: "running it",
+        tool_calls: [toolCall()],
+      },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then it becomes an assistant message carrying a function tool_call
+    expect(native).toEqual([
+      {
+        role: "assistant",
+        content: "running it",
+        tool_calls: [
+          {
+            id: "call_1",
+            type: "function",
+            function: { name: "run_query", arguments: '{"sql":"SELECT 1"}' },
+          },
+        ],
+      },
+    ])
+  })
+
+  it("nulls assistant content when only tool calls are present", () => {
+    // Given an assistant message with no text but a tool call
+    const messages: Message[] = [
+      { role: "assistant", content: null, tool_calls: [toolCall()] },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then content is null and the tool_calls are present
+    expect(native).toEqual([
+      {
+        role: "assistant",
+        content: null,
+        tool_calls: [
+          {
+            id: "call_1",
+            type: "function",
+            function: { name: "run_query", arguments: '{"sql":"SELECT 1"}' },
+          },
+        ],
+      },
+    ])
+  })
+
+  it("converts a tool message into a tool role message", () => {
+    // Given a tool result message
+    const messages: Message[] = [
+      { role: "tool", content: "1 row", tool_call_id: "call_1" },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then it becomes a tool message keyed by tool_call_id
+    expect(native).toEqual([
+      { role: "tool", tool_call_id: "call_1", content: "1 row" },
+    ])
+  })
+
+  it("defers a user message wedged between assistant(tool_calls) and the tool result", () => {
+    // Given a user message between an assistant tool call and its result
+    const messages: Message[] = [
+      { role: "assistant", content: null, tool_calls: [toolCall()] },
+      { role: "user", content: "wait, also chart it" },
+      { role: "tool", content: "1 row", tool_call_id: "call_1" },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then the tool message stays adjacent to its assistant call and the user
+    // message is flushed afterwards
+    expect(native).toEqual([
+      {
+        role: "assistant",
+        content: null,
+        tool_calls: [
+          {
+            id: "call_1",
+            type: "function",
+            function: { name: "run_query", arguments: '{"sql":"SELECT 1"}' },
+          },
+        ],
+      },
+      { role: "tool", tool_call_id: "call_1", content: "1 row" },
+      { role: "user", content: "wait, also chart it" },
+    ])
+  })
+
+  it("flushes a trailing deferred user message at the end of conversion", () => {
+    // Given an assistant tool call followed only by a deferred user message
+    const messages: Message[] = [
+      { role: "assistant", content: null, tool_calls: [toolCall()] },
+      { role: "user", content: "trailing" },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then the deferred user message is appended after the assistant message
+    expect(native).toEqual([
+      {
+        role: "assistant",
+        content: null,
+        tool_calls: [
+          {
+            id: "call_1",
+            type: "function",
+            function: { name: "run_query", arguments: '{"sql":"SELECT 1"}' },
+          },
+        ],
+      },
+      { role: "user", content: "trailing" },
+    ])
+  })
+
+  it("emits tool_call_id: undefined for a tool message missing tool_call_id (current behavior)", () => {
+    // Given a tool message with no tool_call_id
+    const messages: Message[] = [{ role: "tool", content: "orphan" }]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then the tool message carries an undefined tool_call_id (locked-in)
+    expect(native).toEqual([
+      { role: "tool", tool_call_id: undefined, content: "orphan" },
+    ])
+  })
+})
diff --git a/src/utils/ai/openaiChatCompletionsProvider.ts b/src/utils/ai/openaiChatCompletionsProvider.ts
index b2bb02dc7..c011cde11 100644
--- a/src/utils/ai/openaiChatCompletionsProvider.ts
+++ b/src/utils/ai/openaiChatCompletionsProvider.ts
@@ -5,7 +5,6 @@ import type {
 } from "openai/resources/chat/completions"
 import type {
   AiAssistantAPIError,
-  ModelToolsClient,
   StatusCallback,
   StreamingCallback,
   TokenUsage,
@@ -14,7 +13,7 @@ import { getModelProps } from "./settings"
 import type { ProviderId } from "./settings"
 import {
   type AIProvider,
-  type FlowConfig,
+  type ExecuteFlowParams,
   type FlowResult,
   type ToolDefinition,
   type Message,
@@ -24,13 +23,13 @@ import {
   RefusalError,
   MaxTokensError,
   safeJsonParse,
-  executeTool,
   CRITICAL_TOKEN_USAGE_MESSAGE,
   MAX_TOOL_CALL_ROUNDS,
   TOOL_CALL_LIMIT_MESSAGE,
   getMessageTextLength,
   type ToolExecutionContext,
 } from "./shared"
+import { dispatchTool } from "../tools/dispatch"
 import {
   classifyOpenAIError,
   countTokensFromNativePayload,
@@ -41,7 +40,9 @@ import {
   OPENAI_ALLOWED_HEADERS,
 } from "./fetchWithFilteredHeaders"
 
-function toNativeMessages(messages: Message[]): ChatCompletionMessageParam[] {
+export function toNativeMessages(
+  messages: Message[],
+): ChatCompletionMessageParam[] {
   const result: ChatCompletionMessageParam[] = []
   // Buffer user messages that appear between assistant(tool_calls) and tool results
   // so tool messages stay adjacent to their parent assistant
@@ -397,15 +398,10 @@ export function createOpenAIChatCompletionsProvider(
       setStatus,
       abortSignal,
       streaming,
-    }: {
-      model: string
-      config: FlowConfig
-      modelToolsClient: ModelToolsClient
-      tools: ToolDefinition[]
-      setStatus: StatusCallback
-      abortSignal?: AbortSignal
-      streaming?: StreamingCallback
-    }): Promise<FlowResult | AiAssistantAPIError> {
+      perms,
+      validateSql,
+      toolContext: incomingToolContext,
+    }: ExecuteFlowParams): Promise<FlowResult | AiAssistantAPIError> {
       const systemContent = config.systemInstructions
 
       const chatMessages: ChatCompletionMessageParam[] = [
@@ -422,7 +418,7 @@ export function createOpenAIChatCompletionsProvider(
       let totalInputTokens = 0
       let totalOutputTokens = 0
       let lastPromptTokens = 0
-      const toolContext: ToolExecutionContext = {}
+      const toolContext: ToolExecutionContext = incomingToolContext ?? {}
 
       const baseParams = {
         ...toChatCompletionsAPIProps(model),
@@ -464,11 +460,14 @@ export function createOpenAIChatCompletionsProvider(
         toolCallRound++
 
         for (const tc of result.toolCalls) {
-          const exec = await executeTool(
+          const exec = await dispatchTool(
             tc.name,
             safeJsonParse(tc.arguments),
             modelToolsClient,
             setStatus,
+            perms,
+            validateSql,
+            abortSignal,
             toolContext,
           )
 
diff --git a/src/utils/ai/openaiProvider.test.ts b/src/utils/ai/openaiProvider.test.ts
new file mode 100644
index 000000000..7ead21330
--- /dev/null
+++ b/src/utils/ai/openaiProvider.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest"
+import { toNativeMessages } from "./openaiProvider"
+import type { Message, ToolCall } from "./types"
+
+const toolCall = (over: Partial<ToolCall> = {}): ToolCall => ({
+  id: "call_1",
+  name: "run_query",
+  arguments: '{"sql":"SELECT 1"}',
+  timestamp: 0,
+  ...over,
+})
+
+describe("openaiProvider.toNativeMessages (Responses API)", () => {
+  it("converts a plain user message to a user input item", () => {
+    // Given a single user message
+    const messages: Message[] = [{ role: "user", content: "hello" }]
+    // When converted to the Responses input shape
+    const native = toNativeMessages(messages)
+    // Then it becomes one user item with the raw string content
+    expect(native).toEqual([{ role: "user", content: "hello" }])
+  })
+
+  it("converts assistant text into a message item and tool calls into function_call items", () => {
+    // Given an assistant message with text and one tool call
+    const messages: Message[] = [
+      {
+        role: "assistant",
+        content: "running it",
+        tool_calls: [toolCall()],
+      },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then text becomes an output_text message and the call a function_call
+    expect(native).toEqual([
+      {
+        type: "message",
+        role: "assistant",
+        content: [{ type: "output_text", text: "running it" }],
+      },
+      {
+        type: "function_call",
+        call_id: "call_1",
+        name: "run_query",
+        arguments: '{"sql":"SELECT 1"}',
+      },
+    ])
+  })
+
+  it("converts a tool message into a function_call_output item", () => {
+    // Given a tool result message
+    const messages: Message[] = [
+      { role: "tool", content: "1 row", tool_call_id: "call_1" },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then it becomes a function_call_output keyed by call_id
+    expect(native).toEqual([
+      { type: "function_call_output", call_id: "call_1", output: "1 row" },
+    ])
+  })
+
+  it("defers a user message that appears right after a function_call until after the tool output", () => {
+    // Given a user message wedged between a function_call and its output
+    const messages: Message[] = [
+      { role: "assistant", content: null, tool_calls: [toolCall()] },
+      { role: "user", content: "wait, also chart it" },
+      { role: "tool", content: "1 row", tool_call_id: "call_1" },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then the function_call_output stays adjacent to its call and the user
+    // item is flushed afterwards
+    expect(native).toEqual([
+      {
+        type: "function_call",
+        call_id: "call_1",
+        name: "run_query",
+        arguments: '{"sql":"SELECT 1"}',
+      },
+      { type: "function_call_output", call_id: "call_1", output: "1 row" },
+      { role: "user", content: "wait, also chart it" },
+    ])
+  })
+
+  it("flushes a trailing deferred user item at the end of conversion", () => {
+    // Given a function_call followed only by a deferred user message
+    const messages: Message[] = [
+      { role: "assistant", content: null, tool_calls: [toolCall()] },
+      { role: "user", content: "trailing" },
+    ]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then the deferred user item is appended after the function_call
+    expect(native).toEqual([
+      {
+        type: "function_call",
+        call_id: "call_1",
+        name: "run_query",
+        arguments: '{"sql":"SELECT 1"}',
+      },
+      { role: "user", content: "trailing" },
+    ])
+  })
+
+  it("emits call_id: undefined for a tool message missing tool_call_id (current behavior)", () => {
+    // Given a tool message with no tool_call_id
+    const messages: Message[] = [{ role: "tool", content: "orphan" }]
+    // When converted
+    const native = toNativeMessages(messages)
+    // Then the function_call_output carries an undefined call_id (locked-in)
+    expect(native).toEqual([
+      { type: "function_call_output", call_id: undefined, output: "orphan" },
+    ])
+  })
+})
diff --git a/src/utils/ai/openaiProvider.ts b/src/utils/ai/openaiProvider.ts
index 15c6238f1..6e4fb3bfc 100644
--- a/src/utils/ai/openaiProvider.ts
+++ b/src/utils/ai/openaiProvider.ts
@@ -2,7 +2,6 @@ import OpenAI from "openai"
 import type { ResponseOutputItem } from "openai/resources/responses/responses"
 import type {
   AiAssistantAPIError,
-  ModelToolsClient,
   StatusCallback,
   StreamingCallback,
 } from "../aiAssistant"
@@ -10,7 +9,7 @@ import { getModelProps } from "./settings"
 import type { ProviderId } from "./settings"
 import {
   type AIProvider,
-  type FlowConfig,
+  type ExecuteFlowParams,
   type FlowResult,
   type ToolDefinition,
   type Message,
@@ -18,13 +17,13 @@ import {
 import {
   StreamingError,
   safeJsonParse,
-  executeTool,
   CRITICAL_TOKEN_USAGE_MESSAGE,
   MAX_TOOL_CALL_ROUNDS,
   TOOL_CALL_LIMIT_MESSAGE,
   getMessageTextLength,
   type ToolExecutionContext,
 } from "./shared"
+import { dispatchTool } from "../tools/dispatch"
 import {
   classifyOpenAIError,
   countTokensFromNativePayload,
@@ -42,7 +41,9 @@ import {
  * - assistant tool_calls → { type: "function_call", call_id, name, arguments } per call
  * - tool messages → { type: "function_call_output", call_id, output }
  */
-function toNativeMessages(messages: Message[]): OpenAI.Responses.ResponseInput {
+export function toNativeMessages(
+  messages: Message[],
+): OpenAI.Responses.ResponseInput {
   const input: OpenAI.Responses.ResponseInput = []
   // Buffer user messages that appear between function_call and function_call_output
   // so tool outputs stay adjacent to their parent function calls
@@ -307,15 +308,10 @@ export function createOpenAIProvider(
       setStatus,
       abortSignal,
       streaming,
-    }: {
-      model: string
-      config: FlowConfig
-      modelToolsClient: ModelToolsClient
-      tools: ToolDefinition[]
-      setStatus: StatusCallback
-      abortSignal?: AbortSignal
-      streaming?: StreamingCallback
-    }): Promise<FlowResult | AiAssistantAPIError> {
+      perms,
+      validateSql,
+      toolContext: incomingToolContext,
+    }: ExecuteFlowParams): Promise<FlowResult | AiAssistantAPIError> {
       let input: OpenAI.Responses.ResponseInput = []
       if (config.conversationHistory && config.conversationHistory.length > 0) {
         input.push(...toNativeMessages(config.conversationHistory))
@@ -330,7 +326,7 @@ export function createOpenAIProvider(
 
       let totalInputTokens = 0
       let totalOutputTokens = 0
-      const toolContext: ToolExecutionContext = {}
+      const toolContext: ToolExecutionContext = incomingToolContext ?? {}
 
       const requestParams = {
         ...toResponsesAPIProps(model),
@@ -382,11 +378,14 @@ export function createOpenAIProvider(
         const tool_outputs: OpenAI.Responses.ResponseFunctionToolCallOutputItem[] =
           []
         for (const tc of toolCalls) {
-          const exec = await executeTool(
+          const exec = await dispatchTool(
             tc.name,
             safeJsonParse(tc.arguments),
             modelToolsClient,
             setStatus,
+            perms,
+            validateSql,
+            abortSignal,
             toolContext,
           )
 
diff --git a/src/utils/ai/prompts.ts b/src/utils/ai/prompts.ts
index ae98691de..2976c0d02 100644
--- a/src/utils/ai/prompts.ts
+++ b/src/utils/ai/prompts.ts
@@ -6,7 +6,10 @@ CRITICAL: Always follow this documentation approach:
 
 When a cookbook recipe matches the user's intent, ALWAYS use it as the foundation and adapt column/table names and use case to their schema.`
 
-export const getUnifiedPrompt = (grantSchemaAccess?: boolean) => {
+export const getUnifiedPrompt = (
+  grantSchemaAccess?: boolean,
+  perms?: { read: boolean; write: boolean },
+) => {
   const base = `You are a SQL expert coding assistant specializing in QuestDB, a high-performance time-series database. You help users with:
 - Generating QuestDB SQL queries from natural language descriptions
 - Explaining what QuestDB SQL queries do
@@ -59,9 +62,74 @@ export const getUnifiedPrompt = (grantSchemaAccess?: boolean) => {
 - Use the get_table_details tool to get detailed information for a specific table or a materialized view. Each property is described in meta functions docs.
 `
     : ""
-  return base + schemaAccess + DOCS_INSTRUCTION
+  const permsBlock = perms
+    ? `
+## Execution Permissions
+Your runtime scopes for this session: grantSchemaAccess=${grantSchemaAccess === true}, read=${perms.read}, write=${perms.write}.
+- grantSchemaAccess=false ⇒ never call get_tables / get_table_schema / get_table_details.
+- read=false ⇒ never call run_cell or add_cell with run:true on a DQL statement, and never call run_query for SELECT/SHOW.
+- write=false ⇒ never run DDL/DML (CREATE/INSERT/UPDATE/DELETE/DROP/…). DQL (SELECT, SHOW) is still allowed when read=true.
+- You can still GENERATE such SQL into cells — only execution is gated. validate_query is always available; use it to check syntax before proposing SQL.
+- Operations outside the granted scope return PERMISSION_DENIED. If you receive a PERMISSION_DENIED error, do not retry — explain to the user that the operation requires a scope they haven't granted, and tell them they can enable it from the AI Assistant settings modal.
+`
+    : ""
+  return (
+    base + schemaAccess + permsBlock + DOCS_INSTRUCTION + NOTEBOOK_INSTRUCTION
+  )
 }
 
+export const NOTEBOOK_INSTRUCTION = `
+
+## Notebook Authoring
+You can create and edit QuestDB notebooks (tabs of SQL cells with list/grid layouts, draw-mode charts, and markdown prose cells) using these tools:
+create_notebook, list_cells, get_cell, get_notebook_state, add_cell, update_cell, delete_cell, move_cell_up, move_cell_down, duplicate_cell, run_cell, set_layout_mode, set_cell_layout, set_cell_mode, set_cell_chart_config, set_cell_autorefresh, set_cell_chart_maximized, set_cell_maximized.
+
+CRITICAL — Do NOT expose buffer_id to the user
+- buffer_id is an internal identifier. NEVER ask the user for it, print it back, or mention it in any response.
+- Users refer to notebooks by LABEL ("Notebook 1", "Trades analysis"). Resolve labels to buffer_ids INTERNALLY using the <workspace> block, then pass the buffer_id to the tool.
+- If the user's label reference is ambiguous (multiple matches) or missing, ask the user by label — never by id.
+
+CRITICAL — No query data access
+- run_cell returns only { success, error? }. Never reason about columns, rows, or counts — the user reads the result; interpretation is theirs. Do not call run_cell to "inspect" data, only to execute.
+
+State blocks on every user turn
+- <workspace> — always injected when any notebook tab exists. Lists every notebook as { buffer_id, label, archived, bound_to_this_chat? } and the currently active tab as { buffer_id, label, kind } where kind is "notebook" | "sql" | "metrics" | "other". Read this FIRST — it's how you learn which notebooks exist.
+- <notebook_context> — detailed state of the notebook bound to this chat (layout, cells, last-run statuses). Only present when the chat is attached to a notebook.
+- <user_events> — coalesced summary of user actions since your last turn (added/deleted/edited/ran cells, layout switches, notebook archive/delete).
+- Call list_cells / get_cell / get_notebook_state only when you need detail beyond the snapshot.
+
+Picking which notebook to operate on
+1. If the user names a notebook by label, find it in <workspace>.notebooks and use its buffer_id.
+2. If the user refers to "this notebook" / "the notebook" / "the current one":
+   - Prefer <notebook_context>.buffer_id if present.
+   - Else if <workspace>.active.kind === "notebook", use <workspace>.active.buffer_id.
+   - Else ask the user which notebook by label.
+3. If the user asks to create a new notebook, call create_notebook. No existing buffer_id needed.
+
+When to use notebook tools
+- User explicitly asks for a notebook ("create a notebook …", "add a cell …", "go to Notebook 1 and …").
+- User asks for analysis that spans multiple queries or needs annotation.
+- A <notebook_context> block is present — the user is in a notebook chat; editing tools target that chat's bound notebook unless the user names another one.
+
+Editing discipline
+- update_cell overwrites preemptively — cells are auto-saved, there is no unsaved-dirty state to worry about. Be deliberate.
+- Cells containing DDL/DML (INSERT/UPDATE/CREATE/DROP/...) never auto-run via apply_notebook_state or add_cell — they are skipped. Confirm with the user, then call run_cell explicitly; run_cell is the only path that executes a write cell.
+- Markdown cells: add_cell (or apply_notebook_state) with type:"markdown" creates a rendered prose cell — its value is markdown text, it is NEVER executed (run_cell and auto-run are no-ops on it), and it must carry no mode/chart_config. Use them for titles, narrative, and explanations between query cells. In apply_notebook_state the cell kind is STICKY: omitting type preserves a cell's kind (a markdown cell stays markdown).
+- To fix a broken cell: update_cell with the fix, then run_cell. If run_cell returns success:false, read the error and try again. Cap repair attempts at two, then summarise and hand back to the user.
+- Draw-mode cells auto-run when their chart config changes. After set_cell_mode=draw + set_cell_chart_config, do NOT call run_cell.
+- apply_notebook_state is a full PUT: every cell you send is REPLACED wholesale and omitted/null fields are cleared, NOT merged from the current cell. To keep a draw cell's chart, re-send its full \`chart_config\` — copy the \`chart_config\` shown on that cell in <notebook_context> (it is already the exact wire shape). For a single targeted edit, prefer update_cell / set_cell_chart_config (a PATCH on chart_config) instead.
+- For a chart: add_cell with a SELECT that returns (x, y) data, then set_cell_mode=draw, then set_cell_chart_config with \`queries: [{ type, ... }]\` — one entry per \`;\`-split statement, index-aligned. A non-null \`queries\` array REPLACES the whole list, so always send the FULL array (one entry per statement) — never a partial subset, or the omitted statements lose their config and re-infer. A non-empty \`queries\` whose length ≠ the cell's statement count is REJECTED. Use \`queries:null\` to preserve the current config, \`queries:[]\` to reset every statement back to inference. Each query keeps its own type from line/area/stepLine/stepArea/bar/stackedBar/scatter/pie/candlestick.
+- COMBINE multiple types in one chart: put several SELECTs in the cell (\`;\`-separated). They AUTO-COMBINE sharing the first query's x-axis when the x-axis kind matches (all-temporal or all-categorical). Use \`axis:"right"\` (+ \`right_axis:{name,min,max}\`) for a series on a different scale (RSI 0..100, volume); \`enabled:false\` opts a query out. Example: \`SELECT ts,open,high,low,close ...; SELECT ts,vwap ...\` auto-combines OHLC + VWAP with no config; add RSI on a second axis with \`queries:[{type:"candlestick"},{type:"line"},{type:"line",axis:"right"}]\` + \`right_axis:{name:"RSI",min:0,max:100}\`.
+- For a candlestick query: pass \`ohlc:{open,high,low,close}\` (required; an OHLC chart needs an explicit ohlc mapping).
+
+Lifecycle
+- If <notebook_context> says status=archived or status=deleted, or a tool returns error_code archived|deleted, do NOT retry the same buffer. Offer the user create_notebook instead. Archived notebooks also appear in <workspace>.notebooks with \`archived: true\` — don't operate on them without asking the user to unarchive.
+- If a tool returns error_code unknown_cell, call list_cells to resync and retry with a valid id.
+
+Response
+- After tool calls, return a short natural-language summary of what you did, referring to notebooks by LABEL ("Updated the chart in Notebook 1"). Never print buffer_id. Do not restate the SQL you wrote — the user sees it in the cell. Keep the sql field null for notebook-only flows.
+`
+
 export const getExplainSchemaPrompt = (
   tableName: string,
   schema: string,
diff --git a/src/utils/ai/runStatus.test.ts b/src/utils/ai/runStatus.test.ts
new file mode 100644
index 000000000..c903b73b8
--- /dev/null
+++ b/src/utils/ai/runStatus.test.ts
@@ -0,0 +1,170 @@
+import { describe, it, expect } from "vitest"
+import {
+  getCellRunStatus,
+  deriveRunStatusFromResults,
+  createRunStatus,
+} from "./runStatus"
+
+describe("deriveRunStatus", () => {
+  it("returns none for empty/missing results", () => {
+    expect(deriveRunStatusFromResults(undefined)).toEqual({ status: "none" })
+    expect(deriveRunStatusFromResults(null)).toEqual({ status: "none" })
+    expect(deriveRunStatusFromResults([])).toEqual({ status: "none" })
+  })
+
+  // A single-statement write that the user cancels mid-run leaves only a
+  // cancelled entry, but the abort does NOT roll the write back server-side.
+  // Reporting "none" (never run) would invite an agent re-run → duplicate write.
+  it("reports cancelled (not none) for a single cancelled statement", () => {
+    expect(deriveRunStatusFromResults([{ type: "cancelled" }])).toEqual({
+      status: "cancelled",
+    })
+  })
+
+  it("returns success for a single committed statement", () => {
+    expect(deriveRunStatusFromResults([{ type: "dml" }])).toEqual({
+      status: "success",
+    })
+    expect(deriveRunStatusFromResults([{ type: "dql" }])).toEqual({
+      status: "success",
+    })
+    expect(deriveRunStatusFromResults([{ type: "ddl" }])).toEqual({
+      status: "success",
+    })
+  })
+
+  it("returns running while any statement is running/queued", () => {
+    expect(deriveRunStatusFromResults([{ type: "running" }])).toEqual({
+      status: "running",
+    })
+    expect(
+      deriveRunStatusFromResults([{ type: "dml" }, { type: "running" }]),
+    ).toEqual({
+      status: "running",
+    })
+    expect(
+      deriveRunStatusFromResults([{ type: "dml" }, { type: "queued" }]),
+    ).toEqual({
+      status: "running",
+    })
+  })
+
+  it("surfaces the first error with its message", () => {
+    expect(
+      deriveRunStatusFromResults([{ type: "error", error: "boom" }]),
+    ).toEqual({
+      status: "error",
+      error: "boom",
+    })
+  })
+
+  // A committed write followed by a trailing cancelled entry (user Stop on a
+  // multi-statement script) must NOT collapse to "none"; the run was interrupted,
+  // so "cancelled" is the truthful status (cancelled outranks committed).
+  it("reports cancelled for a committed write with a trailing cancelled (user Stop)", () => {
+    expect(
+      deriveRunStatusFromResults([{ type: "dml" }, { type: "cancelled" }]),
+    ).toEqual({
+      status: "cancelled",
+    })
+    expect(
+      deriveRunStatusFromResults([{ type: "ddl" }, { type: "cancelled" }]),
+    ).toEqual({
+      status: "cancelled",
+    })
+  })
+
+  it("reports error (not none) for a mid-script error with auto-cancelled tail", () => {
+    expect(
+      deriveRunStatusFromResults([
+        { type: "dml" },
+        { type: "error", error: "syntax" },
+        { type: "cancelled" },
+      ]),
+    ).toEqual({ status: "error", error: "syntax" })
+  })
+
+  it("takes the first error message when multiple errors exist", () => {
+    expect(
+      deriveRunStatusFromResults([
+        { type: "error", error: "first" },
+        { type: "error", error: "second" },
+      ]),
+    ).toEqual({ status: "error", error: "first" })
+  })
+
+  it("prefers error over committed when both present and nothing running", () => {
+    expect(
+      deriveRunStatusFromResults([
+        { type: "dml" },
+        { type: "error", error: "x" },
+      ]),
+    ).toEqual({ status: "error", error: "x" })
+  })
+})
+
+describe("ranEventStatus", () => {
+  const prior = { results: [{ type: "dql" }] }
+
+  it("reports cancelled when a fresh result ends cancelled (user Stop mid-run)", () => {
+    // Multi-statement: stmt 0 committed, user cancelled stmt 1. runScript's
+    // boolean is true (failedCount===0), but the truthful status is cancelled.
+    const fresh = { results: [{ type: "dml" }, { type: "cancelled" }] }
+    expect(createRunStatus(prior, fresh, true)).toBe("cancelled")
+  })
+
+  it("reports cancelled for a single cancelled statement even when ok=false", () => {
+    const fresh = { results: [{ type: "cancelled" }] }
+    expect(createRunStatus(prior, fresh, false)).toBe("cancelled")
+  })
+
+  it("reports success/error from the fresh result, ignoring the boolean", () => {
+    expect(createRunStatus(prior, { results: [{ type: "dml" }] }, false)).toBe(
+      "success",
+    )
+    expect(createRunStatus(prior, { results: [{ type: "error" }] }, true)).toBe(
+      "error",
+    )
+  })
+
+  it("falls back to the boolean for a no-op run (result unchanged)", () => {
+    // Empty cell run: runCell returns false without producing a new result.
+    expect(createRunStatus(prior, prior, false)).toBe("error")
+    expect(createRunStatus(null, null, true)).toBe("success")
+  })
+})
+
+describe("cellRunStatus", () => {
+  it("prefers the live result when present", () => {
+    expect(
+      getCellRunStatus({ result: { results: [{ type: "dml" }] } }),
+    ).toEqual({
+      status: "success",
+    })
+  })
+
+  // An unmounted notebook has its result stripped; the persisted enum must keep
+  // a committed write from reading back as "none" (which would invite a re-run).
+  it("falls back to the persisted lastRunStatus when result is stripped", () => {
+    expect(
+      getCellRunStatus({ result: undefined, lastRunStatus: "success" }),
+    ).toEqual({ status: "success" })
+    expect(getCellRunStatus({ result: null, lastRunStatus: "error" })).toEqual({
+      status: "error",
+    })
+  })
+
+  it("returns none when neither a result nor a persisted status exists", () => {
+    expect(getCellRunStatus({})).toEqual({ status: "none" })
+    expect(getCellRunStatus(undefined)).toEqual({ status: "none" })
+  })
+
+  it("prefers the live result over a stale persisted status", () => {
+    expect(
+      getCellRunStatus({
+        result: { results: [{ type: "error", error: "x" }] },
+        lastRunStatus: "success",
+      }),
+    ).toEqual({ status: "error", error: "x" })
+  })
+})
diff --git a/src/utils/ai/runStatus.ts b/src/utils/ai/runStatus.ts
new file mode 100644
index 000000000..8d4b71875
--- /dev/null
+++ b/src/utils/ai/runStatus.ts
@@ -0,0 +1,60 @@
+export type RunStatus = "success" | "error" | "none" | "running" | "cancelled"
+
+export type RanStatus = Exclude<RunStatus, "none" | "running">
+
+export const deriveRunStatusFromResults = (
+  results: ReadonlyArray<{ type: string; error?: string }> | null | undefined,
+): { status: RunStatus; error?: string } => {
+  if (!results || results.length === 0) return { status: "none" }
+  let running = false
+  let hasError = false
+  let firstError: string | undefined
+  let cancelled = false
+  let committed = false
+  for (const r of results) {
+    if (r.type === "running" || r.type === "queued") {
+      running = true
+    } else if (r.type === "error") {
+      if (!hasError) firstError = r.error
+      hasError = true
+    } else if (r.type === "cancelled") {
+      cancelled = true
+    } else if (r.type === "dql" || r.type === "ddl" || r.type === "dml") {
+      committed = true
+    }
+  }
+  if (running) return { status: "running" }
+  if (hasError) return { status: "error", error: firstError }
+  if (cancelled) return { status: "cancelled" }
+  if (committed) return { status: "success" }
+  return { status: "none" }
+}
+
+export const getCellRunStatus = (
+  cell:
+    | {
+        result?: {
+          results: ReadonlyArray<{ type: string; error?: string }>
+        } | null
+        lastRunStatus?: RunStatus
+      }
+    | null
+    | undefined,
+): { status: RunStatus; error?: string } => {
+  if (cell?.result) return deriveRunStatusFromResults(cell.result.results)
+  return { status: cell?.lastRunStatus ?? "none" }
+}
+
+export const createRunStatus = (
+  priorResult: { results: ReadonlyArray<{ type: string }> } | null | undefined,
+  freshResult: { results: ReadonlyArray<{ type: string }> } | null | undefined,
+  ok: boolean,
+): RanStatus => {
+  if (freshResult && freshResult !== priorResult) {
+    const { status } = deriveRunStatusFromResults(freshResult.results)
+    if (status === "success" || status === "error" || status === "cancelled") {
+      return status
+    }
+  }
+  return ok ? "success" : "error"
+}
diff --git a/src/utils/ai/sanitizeForPromptContext.ts b/src/utils/ai/sanitizeForPromptContext.ts
new file mode 100644
index 000000000..24761e3e7
--- /dev/null
+++ b/src/utils/ai/sanitizeForPromptContext.ts
@@ -0,0 +1,4 @@
+// Prompt-injection guard: `<`→`‹` (U+2039), `>`→`›` (U+203A) so user-controlled
+// strings can't forge closing tags. Applied AFTER truncation to keep length bounds.
+export const sanitizeForPromptContext = (s: string): string =>
+  s.replace(/</g, "‹").replace(/>/g, "›")
diff --git a/src/utils/ai/settings.test.ts b/src/utils/ai/settings.test.ts
index fdbe5b7dc..b12d75713 100644
--- a/src/utils/ai/settings.test.ts
+++ b/src/utils/ai/settings.test.ts
@@ -1,5 +1,10 @@
-import { describe, it, expect, afterEach } from "vitest"
-import { reconcileSettings, getSelectedModel, MODEL_OPTIONS } from "./settings"
+import { describe, it, expect, afterEach, beforeAll } from "vitest"
+import {
+  reconcileSettings,
+  getSelectedModel,
+  getAiPermissions,
+  MODEL_OPTIONS,
+} from "./settings"
 import type { ModelOption } from "./settings"
 
 import type { AiAssistantSettings } from "../../providers/LocalStorageProvider/types"
@@ -206,10 +211,13 @@ describe("getSelectedModel", () => {
  * when the app is updated with a different model list.
  */
 describe("version compatibility scenarios", () => {
+  // Snapshot once before any mutation — re-snapshotting per call leaks an empty baseline on throw.
   let originalOptions: ModelOption[]
+  beforeAll(() => {
+    originalOptions = [...MODEL_OPTIONS]
+  })
 
   function setModelOptions(options: ModelOption[]) {
-    originalOptions = [...MODEL_OPTIONS]
     MODEL_OPTIONS.length = 0
     MODEL_OPTIONS.push(...options)
   }
@@ -373,3 +381,116 @@ describe("version compatibility scenarios", () => {
     expect(reconciled.selectedModel).toBe("model-a")
   })
 })
+
+describe("getAiPermissions", () => {
+  it("returns all-false when no model is selected", () => {
+    const settings = makeSettings()
+    expect(getAiPermissions(settings)).toEqual({
+      grantSchemaAccess: false,
+      read: false,
+      write: false,
+    })
+  })
+
+  it("returns all-false when the selected model's provider has no settings", () => {
+    const settings = makeSettings({
+      selectedModel: "gpt-5-mini",
+      providers: {},
+    })
+    expect(getAiPermissions(settings)).toEqual({
+      grantSchemaAccess: false,
+      read: false,
+      write: false,
+    })
+  })
+
+  it("defaults read/write to false when only the legacy grantSchemaAccess is persisted", () => {
+    const settings = makeSettings({
+      selectedModel: "gpt-5-mini",
+      providers: {
+        openai: {
+          apiKey: "sk-test",
+          enabledModels: ["gpt-5-mini"],
+          grantSchemaAccess: true,
+        },
+      },
+    })
+    expect(getAiPermissions(settings)).toEqual({
+      grantSchemaAccess: true,
+      read: false,
+      write: false,
+    })
+  })
+
+  it("returns the three booleans verbatim when all are persisted on a built-in provider", () => {
+    const settings = makeSettings({
+      selectedModel: "gpt-5-mini",
+      providers: {
+        openai: {
+          apiKey: "sk-test",
+          enabledModels: ["gpt-5-mini"],
+          grantSchemaAccess: true,
+          read: true,
+          write: true,
+        },
+      },
+    })
+    expect(getAiPermissions(settings)).toEqual({
+      grantSchemaAccess: true,
+      read: true,
+      write: true,
+    })
+  })
+
+  it("reads permissions from a custom provider definition", () => {
+    const settings = makeSettings({
+      selectedModel: "custom-1:llm-a",
+      customProviders: {
+        "custom-1": {
+          type: "openai-chat-completions",
+          name: "Test",
+          baseURL: "http://localhost:11434/v1",
+          contextWindow: 100_000,
+          models: ["llm-a"],
+          grantSchemaAccess: true,
+          read: true,
+          write: false,
+        },
+      },
+      providers: {
+        "custom-1": {
+          apiKey: "",
+          enabledModels: ["custom-1:llm-a"],
+          grantSchemaAccess: true,
+          read: true,
+          write: false,
+        },
+      },
+    })
+    expect(getAiPermissions(settings)).toEqual({
+      grantSchemaAccess: true,
+      read: true,
+      write: false,
+    })
+  })
+
+  it("returns false for read when grantSchemaAccess is true but read is explicitly false", () => {
+    const settings = makeSettings({
+      selectedModel: "gpt-5-mini",
+      providers: {
+        openai: {
+          apiKey: "sk-test",
+          enabledModels: ["gpt-5-mini"],
+          grantSchemaAccess: true,
+          read: false,
+          write: false,
+        },
+      },
+    })
+    expect(getAiPermissions(settings)).toEqual({
+      grantSchemaAccess: true,
+      read: false,
+      write: false,
+    })
+  })
+})
diff --git a/src/utils/ai/settings.ts b/src/utils/ai/settings.ts
index 25f5160f4..65bdaf8bf 100644
--- a/src/utils/ai/settings.ts
+++ b/src/utils/ai/settings.ts
@@ -2,6 +2,9 @@ import type {
   AiAssistantSettings,
   CustomProviderDefinition,
 } from "../../providers/LocalStorageProvider/types"
+import type { Permissions } from "../tools/permissions"
+import { getValue } from "../localStorage"
+import { StoreKey } from "../localStorage/types"
 
 export type ProviderType = "anthropic" | "openai" | "openai-chat-completions"
 
@@ -43,8 +46,8 @@ export type ModelOption = {
 
 export const MODEL_OPTIONS: ModelOption[] = [
   {
-    label: "Claude Opus 4.6",
-    value: "claude-opus-4-6",
+    label: "Claude Opus 4.7",
+    value: "claude-opus-4-7",
     provider: "anthropic",
     isSlow: true,
     defaultEnabled: true,
@@ -369,3 +372,46 @@ export const hasSchemaAccess = (settings: AiAssistantSettings): boolean => {
     settings.customProviders?.[provider]?.grantSchemaAccess === true
   )
 }
+
+export const getAiPermissions = (
+  settings: AiAssistantSettings,
+): Permissions => {
+  const selectedModel = getSelectedModel(settings)
+  if (!selectedModel) {
+    return { grantSchemaAccess: false, read: false, write: false }
+  }
+  const provider = providerForModel(selectedModel, settings)
+  if (!provider) {
+    return { grantSchemaAccess: false, read: false, write: false }
+  }
+  const ps = settings.providers?.[provider]
+  const cs = settings.customProviders?.[provider]
+  return {
+    grantSchemaAccess:
+      ps?.grantSchemaAccess === true || cs?.grantSchemaAccess === true,
+    read: ps?.read === true || cs?.read === true,
+    write: ps?.write === true || cs?.write === true,
+  }
+}
+
+export const readLiveAiAssistantSettings = (): AiAssistantSettings | null => {
+  const stored = getValue(StoreKey.AI_ASSISTANT_SETTINGS)
+  if (!stored) return null
+  try {
+    const parsed = JSON.parse(stored) as AiAssistantSettings
+    return reconcileSettings({
+      selectedModel: parsed.selectedModel,
+      providers: parsed.providers || {},
+      ...(parsed.customProviders && {
+        customProviders: parsed.customProviders,
+      }),
+    })
+  } catch {
+    return null
+  }
+}
+
+export const readLiveAiPermissions = (fallback: Permissions): Permissions => {
+  const live = readLiveAiAssistantSettings()
+  return live ? getAiPermissions(live) : fallback
+}
diff --git a/src/utils/ai/shared.notebookTools.test.ts b/src/utils/ai/shared.notebookTools.test.ts
new file mode 100644
index 000000000..4dedf6468
--- /dev/null
+++ b/src/utils/ai/shared.notebookTools.test.ts
@@ -0,0 +1,2182 @@
+import { describe, it, expect, vi } from "vitest"
+import { dispatchTool } from "../tools/dispatch"
+import type { ModelToolsClient, StatusCallback } from "../aiAssistant"
+import {
+  NotebookToolError,
+  emitUserAction,
+  getUserActionSeq,
+  signalUserEdit,
+  type ApplyNotebookStateRequest,
+} from "../notebookAIBridge"
+import { dispatchMCPTool } from "../mcp/dispatchMCPTool"
+import { EXPECTED_BRIDGE_VERSION } from "../mcp/protocolVersion"
+import type { ToolExecutionContext } from "./shared"
+
+const makeClient = (
+  overrides: Partial<ModelToolsClient> = {},
+): ModelToolsClient => ({
+  validateQuery: () => Promise.resolve({ valid: true }),
+  validateSqlRaw: () =>
+    Promise.resolve({ query: "", columns: [], timestamp: 0 }),
+  runQueryRaw: () =>
+    Promise.resolve({
+      type: "dql" as const,
+      columns: [],
+      dataset: [],
+      count: 0,
+    }),
+  createNotebook: vi.fn(() =>
+    Promise.resolve({ bufferId: 1, label: "Notebook 1" }),
+  ),
+  duplicateNotebook: vi.fn(() =>
+    Promise.resolve({ bufferId: 2, label: "Notebook 1 (copy)" }),
+  ),
+  deleteNotebook: vi.fn(() => Promise.resolve()),
+  listCells: vi.fn(() => Promise.resolve([])),
+  getCell: vi.fn(() =>
+    Promise.resolve({ id: "c", type: "sql", value: "", position: 0 }),
+  ),
+  getNotebookState: vi.fn(() =>
+    Promise.resolve({
+      status: "ok" as const,
+      buffer_id: 1,
+      label: "x",
+      layout_mode: "list" as const,
+      maximized_cell_id: null,
+      cells: [],
+    }),
+  ),
+  addCell: vi.fn(() => Promise.resolve({ cellId: "new-cell" })),
+  updateCell: vi.fn(() => Promise.resolve()),
+  deleteCell: vi.fn(() => Promise.resolve()),
+  moveCellUp: vi.fn(() => Promise.resolve()),
+  moveCellDown: vi.fn(() => Promise.resolve()),
+  duplicateCell: vi.fn(() => Promise.resolve({ cellId: "dup" })),
+  runCell: vi.fn(() =>
+    Promise.resolve({
+      success: true,
+      queryCount: 1,
+      results: ["success"] as Array<"success">,
+    }),
+  ),
+  setLayoutMode: vi.fn(() => Promise.resolve()),
+  setCellLayout: vi.fn(() => Promise.resolve()),
+  setCellMode: vi.fn(() => Promise.resolve()),
+  setCellChartConfig: vi.fn(() => Promise.resolve()),
+  setCellAutoRefresh: vi.fn(() => Promise.resolve()),
+  setCellChartMaximized: vi.fn(() => Promise.resolve()),
+  setCellMaximized: vi.fn(() => Promise.resolve()),
+  applyNotebookState: vi.fn(() =>
+    Promise.resolve({ applied: { added: [], updated: [], deleted: [] } }),
+  ),
+  ...overrides,
+})
+
+const noopStatus: StatusCallback = () => undefined
+
+describe("dispatchTool — notebook tools (happy path)", () => {
+  it("create_notebook forwards label and returns the new buffer id", async () => {
+    const client = makeClient()
+    const res = await dispatchTool(
+      "create_notebook",
+      { label: "My notebook" },
+      client,
+      noopStatus,
+    )
+    expect(client.createNotebook).toHaveBeenCalledWith("My notebook")
+    expect(res.is_error).toBeUndefined()
+    expect(JSON.parse(res.content)).toEqual({
+      bufferId: 1,
+      label: "Notebook 1",
+    })
+  })
+
+  it("add_cell without run returns { cellId }", async () => {
+    const client = makeClient()
+    const res = await dispatchTool(
+      "add_cell",
+      { buffer_id: 1, sql: "SELECT 1" },
+      client,
+      noopStatus,
+    )
+    expect(client.addCell).toHaveBeenCalledWith(
+      1,
+      "SELECT 1",
+      undefined,
+      undefined,
+    )
+    expect(JSON.parse(res.content)).toEqual({ cellId: "new-cell" })
+  })
+
+  it("add_cell with run:true chains runCell and reports per-query status", async () => {
+    const client = makeClient({
+      runCell: vi.fn(() =>
+        Promise.resolve({
+          success: false,
+          queryCount: 3,
+          results: ["success", "ERROR: boom", "cancelled"],
+        }),
+      ),
+    })
+    const res = await dispatchTool(
+      "add_cell",
+      { buffer_id: 1, sql: "SELECT 1; SELECT bad; SELECT 2", run: true },
+      client,
+      noopStatus,
+    )
+    expect(client.runCell).toHaveBeenCalledWith(
+      1,
+      "new-cell",
+      undefined,
+      undefined,
+    )
+    expect(JSON.parse(res.content)).toEqual({
+      cellId: "new-cell",
+      ran: false,
+      queryCount: 3,
+      results: ["success", "ERROR: boom", "cancelled"],
+    })
+  })
+
+  it("update_cell sends only the value update", async () => {
+    const client = makeClient()
+    await dispatchTool(
+      "update_cell",
+      { buffer_id: 1, cell_id: "c", value: "SELECT 2" },
+      client,
+      noopStatus,
+    )
+    expect(client.updateCell).toHaveBeenCalledWith(1, "c", {
+      value: "SELECT 2",
+    })
+  })
+
+  it("run_cell serialises the explicit per-query shape and never leaks data keys", async () => {
+    const client = makeClient({
+      runCell: vi.fn(() =>
+        Promise.resolve({
+          success: false,
+          queryCount: 1,
+          results: ["ERROR: syntax"],
+        }),
+      ),
+    })
+    const res = await dispatchTool(
+      "run_cell",
+      { buffer_id: 1, cell_id: "c" },
+      client,
+      noopStatus,
+    )
+    const parsed = JSON.parse(res.content) as Record<string, unknown>
+    expect(parsed).toEqual({
+      success: false,
+      queryCount: 1,
+      results: ["ERROR: syntax"],
+    })
+    // No QuestDB result-row leak keys under any circumstance. `queryCount`
+    // (capital C) is intentional — won't match a case-sensitive `count` regex.
+    expect(res.content).not.toMatch(/columns|dataset|count|rows/)
+  })
+
+  // A superseded/backgrounded run yields unverified+note; the agent must see it
+  // on ALL run-bearing tools (not just run_cell) or it re-runs a committed write.
+  it("propagates unverified/note from runCell to run_cell, add_cell{run}, and apply runs", async () => {
+    const unverifiedRunCell = () =>
+      vi.fn(() =>
+        Promise.resolve({
+          success: false,
+          queryCount: 1,
+          results: ["pending"],
+          unverified: true,
+          note: "Run outcome unverified.",
+        }),
+      )
+
+    const runCellRes = await dispatchTool(
+      "run_cell",
+      { buffer_id: 1, cell_id: "c" },
+      makeClient({ runCell: unverifiedRunCell() }),
+      noopStatus,
+    )
+    const p1 = JSON.parse(runCellRes.content) as Record<string, unknown>
+    expect(p1.unverified).toBe(true)
+    expect(typeof p1.note).toBe("string")
+
+    const addRes = await dispatchTool(
+      "add_cell",
+      { buffer_id: 1, sql: "INSERT INTO t VALUES(1)", run: true },
+      makeClient({ runCell: unverifiedRunCell() }),
+      noopStatus,
+    )
+    const p2 = JSON.parse(addRes.content) as Record<string, unknown>
+    expect(p2.unverified).toBe(true)
+    expect(typeof p2.note).toBe("string")
+
+    const applyRes = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        cells: [{ id: "x", value: "INSERT INTO t VALUES(1)", mode: "run" }],
+      },
+      makeClient({ runCell: unverifiedRunCell() }),
+      noopStatus,
+    )
+    const p3 = JSON.parse(applyRes.content) as {
+      runs: Array<Record<string, unknown>>
+    }
+    expect(p3.runs[0].unverified).toBe(true)
+    expect(typeof p3.runs[0].note).toBe("string")
+  })
+
+  it("set_cell_chart_config forwards only fields the AI supplied (patch semantics)", async () => {
+    const client = makeClient()
+    await dispatchTool(
+      "set_cell_chart_config",
+      {
+        buffer_id: 1,
+        cell_id: "c",
+        x_column: "ts",
+        name: "Trades",
+        queries: [
+          {
+            type: "line",
+            y_columns: ["price", "volume"],
+            partition_by_column: "symbol",
+          },
+        ],
+      },
+      client,
+      noopStatus,
+    )
+    expect(client.setCellChartConfig).toHaveBeenCalledWith(1, "c", {
+      xColumn: "ts",
+      name: "Trades",
+      queries: [
+        {
+          type: "line",
+          yColumns: ["price", "volume"],
+          partitionByColumn: "symbol",
+        },
+      ],
+    })
+  })
+
+  it("run_query flags a transport-dropped error as unverified, a server error as not", async () => {
+    const transport = makeClient({
+      runQueryRaw: vi.fn(() =>
+        Promise.resolve({
+          type: "error" as const,
+          error: "QuestDB is not reachable [504]",
+        }),
+      ),
+    })
+    const t = await dispatchTool(
+      "run_query",
+      { buffer_id: 1, sql: "INSERT INTO t VALUES(1)" },
+      transport,
+      noopStatus,
+    )
+    expect((JSON.parse(t.content) as { unverified?: boolean }).unverified).toBe(
+      true,
+    )
+
+    const serverErr = makeClient({
+      runQueryRaw: vi.fn(() =>
+        Promise.resolve({
+          type: "error" as const,
+          error: "table does not exist [table=t]",
+        }),
+      ),
+    })
+    const s = await dispatchTool(
+      "run_query",
+      { buffer_id: 1, sql: "SELECT * FROM t" },
+      serverErr,
+      noopStatus,
+    )
+    expect(
+      (JSON.parse(s.content) as { unverified?: boolean }).unverified,
+    ).toBeUndefined()
+  })
+
+  it("run_query that throws flags a transport-dropped rejection as unverified, a server rejection as not", async () => {
+    // Given runQueryRaw rejects with a transport-dropped error
+    const transport = makeClient({
+      runQueryRaw: vi.fn(() =>
+        Promise.reject(new Error("QuestDB is not reachable [504]")),
+      ),
+    })
+    // When run_query is dispatched
+    const t = await dispatchTool(
+      "run_query",
+      { buffer_id: 1, sql: "INSERT INTO t VALUES(1)" },
+      transport,
+      noopStatus,
+    )
+    // Then the failure envelope is marked unverified
+    const transportPayload = JSON.parse(t.content) as {
+      error?: string
+      unverified?: boolean
+    }
+    expect(t.is_error).toBe(true)
+    expect(transportPayload.error).toContain("run_query failed:")
+    expect(transportPayload.unverified).toBe(true)
+
+    // Given runQueryRaw rejects with a deterministic server error
+    const serverErr = makeClient({
+      runQueryRaw: vi.fn(() =>
+        Promise.reject(new Error("table does not exist [table=t]")),
+      ),
+    })
+    // When run_query is dispatched
+    const s = await dispatchTool(
+      "run_query",
+      { buffer_id: 1, sql: "SELECT * FROM t" },
+      serverErr,
+      noopStatus,
+    )
+    // Then the failure envelope is NOT marked unverified
+    const serverPayload = JSON.parse(s.content) as {
+      error?: string
+      unverified?: boolean
+    }
+    expect(s.is_error).toBe(true)
+    expect(serverPayload.error).toContain("run_query failed:")
+    expect(serverPayload.unverified).toBeUndefined()
+  })
+
+  it("set_cell_chart_config with only `queries` does NOT send x/name defaults (no clobber)", async () => {
+    const client = makeClient()
+    await dispatchTool(
+      "set_cell_chart_config",
+      { buffer_id: 1, cell_id: "c", queries: [{ type: "bar" }] },
+      client,
+      noopStatus,
+    )
+    // Only `queries` goes over the wire; client-side merge preserves the cell's
+    // existing xColumn/name. Omitted top-level fields must not appear as defaults.
+    expect(client.setCellChartConfig).toHaveBeenCalledWith(1, "c", {
+      queries: [{ type: "bar", yColumns: [] }],
+    })
+  })
+
+  it("forwards explicit ohlc for candlestick", async () => {
+    const client = makeClient()
+    await dispatchTool(
+      "set_cell_chart_config",
+      {
+        buffer_id: 1,
+        cell_id: "c",
+        x_column: "ts",
+        queries: [
+          {
+            type: "candlestick",
+            ohlc: { open: "o", high: "h", low: "l", close: "cl" },
+          },
+        ],
+      },
+      client,
+      noopStatus,
+    )
+    expect(client.setCellChartConfig).toHaveBeenCalledWith(1, "c", {
+      xColumn: "ts",
+      queries: [
+        {
+          type: "candlestick",
+          yColumns: [],
+          ohlc: { open: "o", high: "h", low: "l", close: "cl" },
+        },
+      ],
+    })
+  })
+
+  it("rejects a candlestick query with no ohlc (no derive from y_columns)", async () => {
+    const client = makeClient()
+    const res = await dispatchTool(
+      "set_cell_chart_config",
+      {
+        buffer_id: 1,
+        cell_id: "c",
+        x_column: "ts",
+        queries: [
+          { type: "candlestick", y_columns: ["open", "high", "low", "close"] },
+        ],
+      },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as { error_code: string }
+    expect(parsed.error_code).toBe("validation")
+    expect(client.setCellChartConfig).not.toHaveBeenCalled()
+  })
+
+  it("treats null fields on set_cell_chart_config as 'omit' (not overwrite)", async () => {
+    // Strict tool schemas (OpenAI Structured Outputs) require every property
+    // in `required`; optional-ness is expressed via nullable types. The
+    // handler must treat null as "leave the cell's current value alone".
+    const client = makeClient()
+    await dispatchTool(
+      "set_cell_chart_config",
+      {
+        buffer_id: 1,
+        cell_id: "c",
+        x_column: null,
+        name: null,
+        right_axis: null,
+        queries: [
+          {
+            type: "line",
+            y_columns: null,
+            partition_by_column: null,
+            axis: null,
+            enabled: null,
+            name: null,
+            ohlc: null,
+          },
+        ],
+      },
+      client,
+      noopStatus,
+    )
+    expect(client.setCellChartConfig).toHaveBeenCalledWith(1, "c", {
+      queries: [{ type: "line", yColumns: [] }],
+    })
+  })
+
+  it("rejects a candlestick query with no ohlc (y_columns of a non-ohlc length)", async () => {
+    const client = makeClient()
+    const res = await dispatchTool(
+      "set_cell_chart_config",
+      {
+        buffer_id: 1,
+        cell_id: "c",
+        queries: [{ type: "candlestick", y_columns: ["a", "b"] }],
+      },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as { error_code: string }
+    expect(parsed.error_code).toBe("validation")
+    expect(client.setCellChartConfig).not.toHaveBeenCalled()
+  })
+
+  it("rejects a non-empty queries array whose length != the cell's statement count", async () => {
+    const client = makeClient({
+      getCellSql: () => "SELECT a FROM t; SELECT b FROM t",
+    })
+    const res = await dispatchTool(
+      "set_cell_chart_config",
+      {
+        buffer_id: 1,
+        cell_id: "c",
+        // One config for a two-statement cell — would silently drop Q2.
+        queries: [{ type: "line", y_columns: ["a"] }],
+      },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as { error_code: string }
+    expect(parsed.error_code).toBe("validation")
+    expect(client.setCellChartConfig).not.toHaveBeenCalled()
+  })
+
+  it("forwards a queries array that matches the cell's statement count", async () => {
+    const client = makeClient({
+      getCellSql: () => "SELECT a FROM t; SELECT b FROM t",
+    })
+    await dispatchTool(
+      "set_cell_chart_config",
+      {
+        buffer_id: 1,
+        cell_id: "c",
+        queries: [
+          { type: "line", y_columns: ["a"] },
+          { type: "bar", y_columns: ["b"] },
+        ],
+      },
+      client,
+      noopStatus,
+    )
+    expect(client.setCellChartConfig).toHaveBeenCalledWith(1, "c", {
+      queries: [
+        { type: "line", yColumns: ["a"] },
+        { type: "bar", yColumns: ["b"] },
+      ],
+    })
+  })
+
+  it("allows queries:[] (reset to inference) regardless of statement count", async () => {
+    const client = makeClient({
+      getCellSql: () => "SELECT a FROM t; SELECT b FROM t",
+    })
+    await dispatchTool(
+      "set_cell_chart_config",
+      { buffer_id: 1, cell_id: "c", queries: [] },
+      client,
+      noopStatus,
+    )
+    expect(client.setCellChartConfig).toHaveBeenCalledWith(1, "c", {
+      queries: [],
+    })
+  })
+
+  it("preserves a null queries entry (infer this statement) instead of crashing", async () => {
+    const client = makeClient({
+      getCellSql: () => "SELECT a FROM t; SELECT b FROM t",
+    })
+    await dispatchTool(
+      "set_cell_chart_config",
+      {
+        buffer_id: 1,
+        cell_id: "c",
+        // First statement left to inference (null), second configured explicitly.
+        queries: [null, { type: "bar", y_columns: ["b"] }],
+      },
+      client,
+      noopStatus,
+    )
+    expect(client.setCellChartConfig).toHaveBeenCalledWith(1, "c", {
+      queries: [null, { type: "bar", yColumns: ["b"] }],
+    })
+  })
+
+  it("apply_notebook_state translates snake_case wire shape to camelCase request", async () => {
+    const client = makeClient({
+      applyNotebookState: vi.fn(() =>
+        Promise.resolve({
+          applied: { added: ["a"], updated: ["b"], deleted: ["c"] },
+        }),
+      ),
+    })
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: "grid",
+        maximized_cell_id: null,
+        cells: [
+          {
+            id: "b",
+            value: "SELECT 1",
+            mode: "draw",
+            auto_refresh: true,
+            is_chart_maximized: true,
+            chart_config: {
+              x_column: "ts",
+              name: "Trades",
+              right_axis: null,
+              queries: [
+                {
+                  type: "line",
+                  y_columns: ["price"],
+                  partition_by_column: "symbol",
+                },
+              ],
+            },
+            grid: { x: 0, y: 0, w: 6, h: 6 },
+          },
+        ],
+      },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBeUndefined()
+    expect(client.applyNotebookState).toHaveBeenCalledWith(1, {
+      layoutMode: "grid",
+      maximizedCellId: null,
+      cells: [
+        {
+          id: "b",
+          value: "SELECT 1",
+          mode: "draw",
+          autoRefresh: true,
+          isChartMaximized: true,
+          chartConfig: {
+            xColumn: "ts",
+            name: "Trades",
+            queries: [
+              {
+                type: "line",
+                yColumns: ["price"],
+                partitionByColumn: "symbol",
+              },
+            ],
+          },
+          grid: { x: 0, y: 0, w: 6, h: 6 },
+        },
+      ],
+    })
+    expect(JSON.parse(res.content)).toEqual({
+      applied: { added: ["a"], updated: ["b"], deleted: ["c"] },
+      runs: [],
+    })
+  })
+
+  it("apply_notebook_state forwards ordered variables; null/undefined preserve, [] clears", async () => {
+    const client = makeClient()
+    const variables = [
+      { name: "x", value: "10" },
+      { name: "from_ts", value: "dateadd('d', -7, now())" },
+    ]
+    await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        variables,
+        cells: [{ value: "SELECT @x FROM trades WHERE ts > @from_ts" }],
+      },
+      client,
+      noopStatus,
+    )
+    expect(client.applyNotebookState).toHaveBeenCalledWith(
+      1,
+      expect.objectContaining({
+        variables,
+      }),
+    )
+
+    const client2 = makeClient()
+    await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        variables: null,
+        cells: [{ value: "SELECT 1" }],
+      },
+      client2,
+      noopStatus,
+    )
+    expect(client2.applyNotebookState).toHaveBeenCalledWith(
+      1,
+      expect.objectContaining({ variables: undefined }),
+    )
+
+    const client3 = makeClient()
+    await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        variables: [],
+        cells: [{ value: "SELECT 1" }],
+      },
+      client3,
+      noopStatus,
+    )
+    expect(client3.applyNotebookState).toHaveBeenCalledWith(
+      1,
+      expect.objectContaining({ variables: [] }),
+    )
+  })
+
+  it("apply_notebook_state rejects invalid variable names with a VALIDATION_ERROR", async () => {
+    const client = makeClient()
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        variables: [{ name: "bad-name", value: "1" }],
+        cells: [{ value: "SELECT 1" }],
+      },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as { error_code: string }
+    expect(parsed.error_code).toBe("validation")
+    expect(client.applyNotebookState).not.toHaveBeenCalled()
+  })
+
+  it("apply_notebook_state rejects invalid variable values via QuestDB validation", async () => {
+    for (const value of ["", "select", "(1,2,3)"]) {
+      const client = makeClient()
+      const validateSql = vi.fn(() =>
+        Promise.resolve({
+          query: "DECLARE @x := bad SELECT 1",
+          position: 14,
+          error: "bad variable value",
+        }),
+      )
+      const res = await dispatchTool(
+        "apply_notebook_state",
+        {
+          buffer_id: 1,
+          layout_mode: null,
+          maximized_cell_id: null,
+          variables: [{ name: "x", value }],
+          cells: [{ value: "SELECT 1" }],
+        },
+        client,
+        noopStatus,
+        undefined,
+        validateSql,
+      )
+      expect(res.is_error).toBe(true)
+      const parsed = JSON.parse(res.content) as { error_code: string }
+      expect(parsed.error_code).toBe("validation")
+      expect(client.applyNotebookState).not.toHaveBeenCalled()
+    }
+  })
+
+  it("apply_notebook_state rejects multi-assignment value injection before validateSql", async () => {
+    const client = makeClient()
+    const validateSql = vi.fn()
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        variables: [{ name: "x", value: "1, @evil := 999" }],
+        cells: [{ value: "SELECT 1" }],
+      },
+      client,
+      noopStatus,
+      undefined,
+      validateSql,
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as {
+      error_code: string
+      message: string
+    }
+    expect(parsed.error_code).toBe("validation")
+    expect(parsed.message).toContain("shape check failed")
+    expect(validateSql).not.toHaveBeenCalled()
+    expect(client.applyNotebookState).not.toHaveBeenCalled()
+  })
+
+  it("apply_notebook_state validates ordered variable prefixes with QuestDB", async () => {
+    const client = makeClient()
+    const validateSql = vi.fn(() =>
+      Promise.resolve({
+        query: "SELECT 1",
+        columns: [{ name: "1", type: "INT" }],
+        timestamp: 0,
+      }),
+    )
+    await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        variables: [
+          { name: "base", value: "10" },
+          { name: "derived", value: "@base + 1" },
+        ],
+        cells: [{ value: "SELECT @derived" }],
+      },
+      client,
+      noopStatus,
+      undefined,
+      validateSql,
+    )
+    expect(validateSql).toHaveBeenNthCalledWith(
+      1,
+      "DECLARE\n  @base := 10\nSELECT 1",
+    )
+    expect(validateSql).toHaveBeenNthCalledWith(
+      2,
+      "DECLARE\n  @base := 10,\n  @derived := @base + 1\nSELECT 1",
+    )
+    expect(client.applyNotebookState).toHaveBeenCalled()
+  })
+
+  it("apply_notebook_state rejects as STATE_STALE when the user edits during validation", async () => {
+    const client = makeClient()
+    // The user edits a cell (keystroke) while the per-variable validation awaits.
+    const validateSql = vi.fn(() => {
+      signalUserEdit()
+      return Promise.resolve({
+        query: "SELECT 1",
+        columns: [{ name: "1", type: "INT" }],
+        timestamp: 0,
+      })
+    })
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        variables: [{ name: "base", value: "10" }],
+        cells: [{ value: "SELECT @base" }],
+      },
+      client,
+      noopStatus,
+      undefined,
+      validateSql,
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as { error_code?: string }
+    expect(parsed.error_code).toBe("stale")
+    expect(client.applyNotebookState).not.toHaveBeenCalled()
+  })
+
+  it("apply_notebook_state rejects STATE_STALE on a user edit since the read baseline (in-app generation window)", async () => {
+    const client = makeClient()
+    const readSeq = getUserActionSeq()
+    emitUserAction({ kind: "user_added_cell", bufferId: 1, cellId: "x" })
+    const toolContext = { notebookReadSeq: readSeq }
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      { buffer_id: 1, cells: [{ value: "SELECT 1" }] },
+      client,
+      noopStatus,
+      undefined,
+      undefined,
+      undefined,
+      toolContext,
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as { error_code?: string }
+    expect(parsed.error_code).toBe("stale")
+    expect(client.applyNotebookState).not.toHaveBeenCalled()
+  })
+
+  it("update_cell rejects STATE_STALE when the user edited since the read baseline", async () => {
+    const client = makeClient()
+    const readSeq = getUserActionSeq()
+    signalUserEdit()
+    const res = await dispatchTool(
+      "update_cell",
+      { buffer_id: 1, cell_id: "c", value: "SELECT 2" },
+      client,
+      noopStatus,
+      undefined,
+      undefined,
+      undefined,
+      { notebookReadSeq: readSeq },
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as { error_code?: string }
+    expect(parsed.error_code).toBe("stale")
+    expect(client.updateCell).not.toHaveBeenCalled()
+  })
+
+  it("apply_notebook_state rejects after a user auto-refresh/maximize/spotlight toggle (signalUserEdit) since the read baseline", async () => {
+    const client = makeClient()
+    const readSeq = getUserActionSeq()
+    // handleAutoRefreshChange / handleChartMaximizedChange / the spotlight toggle
+    // all call signalUserEdit(); the agent's stale full-state apply must reject.
+    signalUserEdit()
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      { buffer_id: 1, cells: [{ value: "SELECT 1" }] },
+      client,
+      noopStatus,
+      undefined,
+      undefined,
+      undefined,
+      { notebookReadSeq: readSeq },
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as { error_code?: string }
+    expect(parsed.error_code).toBe("stale")
+    expect(client.applyNotebookState).not.toHaveBeenCalled()
+  })
+
+  it("update_cell rejects STATE_STALE when the user edits during validation", async () => {
+    const client = makeClient({
+      getCell: vi.fn(() => {
+        signalUserEdit()
+        return Promise.resolve({ id: "c", type: "sql", value: "", position: 0 })
+      }),
+    })
+    const validateSql = vi.fn(() =>
+      Promise.resolve({ query: "", columns: [], timestamp: 0 }),
+    )
+    const res = await dispatchTool(
+      "update_cell",
+      { buffer_id: 1, cell_id: "c", value: "SELECT 2" },
+      client,
+      noopStatus,
+      undefined,
+      validateSql,
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as { error_code?: string }
+    expect(parsed.error_code).toBe("stale")
+    expect(client.updateCell).not.toHaveBeenCalled()
+  })
+
+  it("apply_notebook_state does not derive ohlc from y_columns for candlestick", async () => {
+    const client = makeClient()
+    await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [
+          {
+            id: null,
+            value: "SELECT * FROM trades",
+            mode: "draw",
+            auto_refresh: null,
+            is_chart_maximized: null,
+            chart_config: {
+              x_column: "ts",
+              name: null,
+              right_axis: null,
+              queries: [
+                { type: "candlestick", y_columns: ["o", "h", "l", "c"] },
+              ],
+            },
+            grid: null,
+          },
+        ],
+      },
+      client,
+      noopStatus,
+    )
+    const mockFn = client.applyNotebookState as unknown as ReturnType<
+      typeof vi.fn
+    >
+    const req = mockFn.mock.calls[0][1] as {
+      cells: Array<{
+        chartConfig?: { queries?: Array<Record<string, unknown>> }
+      }>
+    }
+    expect(req.cells[0].chartConfig?.queries?.[0]).not.toHaveProperty("ohlc")
+  })
+
+  it("apply_notebook_state surfaces ApplyNotebookStateError as VALIDATION_ERROR", async () => {
+    const client = makeClient({
+      applyNotebookState: vi.fn(() => {
+        const e = new Error('Duplicate cell id "x" in request.')
+        e.name = "ApplyNotebookStateError"
+        return Promise.reject(e)
+      }),
+    })
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [
+          {
+            id: "x",
+            value: "a",
+            mode: null,
+            auto_refresh: null,
+            is_chart_maximized: null,
+            chart_config: null,
+            grid: null,
+          },
+        ],
+      },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as Record<string, unknown>
+    expect(parsed.error_code).toBe("validation")
+    expect(parsed.message).toMatch(/VALIDATION_ERROR/)
+  })
+
+  it("set_cell_maximized allows null to clear the spotlight", async () => {
+    const client = makeClient()
+    await dispatchTool(
+      "set_cell_maximized",
+      { buffer_id: 1, cell_id: null },
+      client,
+      noopStatus,
+    )
+    expect(client.setCellMaximized).toHaveBeenCalledWith(1, null)
+  })
+
+  it("denies run_cell when SQL cannot be resolved for permission classification", async () => {
+    const client = makeClient({
+      getCellSql: vi.fn(() => null),
+    })
+    const res = await dispatchTool(
+      "run_cell",
+      { buffer_id: 1, cell_id: "inactive" },
+      client,
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: false },
+      vi.fn().mockResolvedValue({ queryType: "DROP TABLE" }),
+    )
+    expect(res.is_error).toBe(true)
+    expect(res.content).toMatch(/could not resolve SQL/)
+    expect(client.runCell).not.toHaveBeenCalled()
+  })
+
+  it("denies set_cell_mode draw when cell SQL contains DDL/DML, even with write granted", async () => {
+    const client = makeClient({
+      getCellSql: vi.fn(() => "DROP TABLE victim"),
+    })
+    const res = await dispatchTool(
+      "set_cell_mode",
+      { buffer_id: 1, cell_id: "c", mode: "draw" },
+      client,
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: true },
+      vi.fn().mockResolvedValue({ queryType: "DROP TABLE" }),
+    )
+    expect(res.is_error).toBe(true)
+    expect(res.content).toMatch(/Cannot draw a write query/)
+    expect(client.setCellMode).not.toHaveBeenCalled()
+  })
+
+  it("denies update_cell on a draw cell when new SQL contains DDL/DML, even with write granted", async () => {
+    const client = makeClient({
+      getCell: vi.fn(() =>
+        Promise.resolve({
+          id: "c",
+          value: "SELECT 1",
+          position: 0,
+          mode: "draw" as const,
+        }),
+      ),
+    })
+    const res = await dispatchTool(
+      "update_cell",
+      { buffer_id: 1, cell_id: "c", value: "DROP TABLE victim" },
+      client,
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: true },
+      vi.fn().mockResolvedValue({ queryType: "DROP TABLE" }),
+    )
+    expect(res.is_error).toBe(true)
+    expect(res.content).toMatch(/Cannot draw a write query/)
+    expect(client.updateCell).not.toHaveBeenCalled()
+  })
+
+  it("denies apply_notebook_state with a draw cell containing DDL/DML, even with write granted", async () => {
+    const client = makeClient()
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [
+          {
+            id: null,
+            value: "DROP TABLE victim",
+            mode: "draw",
+            auto_refresh: null,
+            is_chart_maximized: null,
+            chart_config: { type: "line", x_column: "ts", y_columns: ["x"] },
+            grid: null,
+          },
+        ],
+      },
+      client,
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: true },
+      vi.fn().mockResolvedValue({ queryType: "DROP TABLE" }),
+    )
+    expect(res.is_error).toBe(true)
+    expect(res.content).toMatch(/Cannot draw a write query/)
+    expect(client.applyNotebookState).not.toHaveBeenCalled()
+  })
+
+  it("allows run_cell with SELECT when read and write are both denied", async () => {
+    const client = makeClient({
+      getCellSql: vi.fn(() => "SELECT 1"),
+      runCell: vi.fn(() =>
+        Promise.resolve({
+          success: true,
+          queryCount: 1,
+          results: ["success"] as Array<"success">,
+        }),
+      ),
+    })
+    const res = await dispatchTool(
+      "run_cell",
+      { buffer_id: 1, cell_id: "c" },
+      client,
+      noopStatus,
+      { grantSchemaAccess: false, read: false, write: false },
+      vi.fn().mockResolvedValue({
+        query: "SELECT 1",
+        columns: [{ name: "c1", type: "LONG" }],
+        timestamp: -1,
+      }),
+    )
+    expect(res.is_error).toBeFalsy()
+    // The exact authorization-checked SQL is threaded to execution.
+    expect(client.runCell).toHaveBeenCalledWith(1, "c", undefined, "SELECT 1")
+  })
+
+  it("run_cell executes the checked SQL, not a value swapped in during the validate round-trip", async () => {
+    // A run-mode cell starts at a read query the gate will allow.
+    let liveValue = "SELECT 1"
+    const client = makeClient({ getCellSql: vi.fn(() => liveValue) })
+    // Simulate a concurrent ungated update_cell landing while run_cell awaits
+    // the /sql/validate round-trip: the live cell value flips to a write
+    // between classification and execution.
+    const validateSql = vi.fn((sql: string) => {
+      liveValue = "DROP TABLE t"
+      return Promise.resolve({
+        query: sql,
+        columns: [{ name: "c1", type: "LONG" }],
+        timestamp: -1,
+      })
+    })
+    const res = await dispatchTool(
+      "run_cell",
+      { buffer_id: 1, cell_id: "c" },
+      client,
+      noopStatus,
+      { grantSchemaAccess: false, read: true, write: false },
+      validateSql,
+    )
+    expect(res.is_error).toBeFalsy()
+    // The race is real: the live value did change mid-flight...
+    expect(liveValue).toBe("DROP TABLE t")
+    // ...but the executor was handed the checked SELECT, never the DROP.
+    expect(client.runCell).toHaveBeenCalledWith(1, "c", undefined, "SELECT 1")
+  })
+
+  it("run_cell with no gate leaves execution to re-read the live cell", async () => {
+    const client = makeClient()
+    const res = await dispatchTool(
+      "run_cell",
+      { buffer_id: 1, cell_id: "c" },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBeFalsy()
+    // No gate ran, so no SQL is pinned — the executor re-reads the cell.
+    expect(client.runCell).toHaveBeenCalledWith(1, "c", undefined)
+  })
+
+  it("allows add_cell with run=true and SELECT when read and write are both denied", async () => {
+    const client = makeClient({
+      runCell: vi.fn(() =>
+        Promise.resolve({
+          success: true,
+          queryCount: 1,
+          results: ["success"] as Array<"success">,
+        }),
+      ),
+    })
+    const res = await dispatchTool(
+      "add_cell",
+      { buffer_id: 1, sql: "SELECT 1", run: true },
+      client,
+      noopStatus,
+      { grantSchemaAccess: false, read: false, write: false },
+      vi.fn().mockResolvedValue({
+        query: "SELECT 1",
+        columns: [{ name: "c1", type: "LONG" }],
+        timestamp: -1,
+      }),
+    )
+    expect(res.is_error).toBeFalsy()
+    const parsed = JSON.parse(res.content) as { ran?: boolean }
+    expect(parsed.ran).toBe(true)
+  })
+
+  it("skips add_cell run when the cell contains DDL/DML — the cell is still added", async () => {
+    const runCell = vi.fn()
+    const client = makeClient({ runCell })
+    const res = await dispatchTool(
+      "add_cell",
+      { buffer_id: 1, sql: "INSERT INTO t VALUES (1)", run: true },
+      client,
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: true },
+      vi.fn().mockResolvedValue({ queryType: "INSERT" }),
+    )
+    expect(res.is_error).toBeFalsy()
+    expect(client.addCell).toHaveBeenCalledWith(
+      1,
+      "INSERT INTO t VALUES (1)",
+      undefined,
+      undefined,
+    )
+    expect(runCell).not.toHaveBeenCalled()
+    const parsed = JSON.parse(res.content) as {
+      cellId: string
+      ran: boolean
+      skipped?: boolean
+      note?: string
+    }
+    expect(parsed).toMatchObject({
+      cellId: "new-cell",
+      ran: false,
+      skipped: true,
+    })
+    expect(parsed.note).toMatch(/run_cell/)
+  })
+
+  // SAFETY PRECONDITION — "agent flows never auto-run DDL/DML". The guard lives
+  // inside `if (perms && validateSql)`, so it protects the flow ONLY because
+  // every production call site threads BOTH args (anthropicProvider,
+  // openaiProvider, openaiChatCompletionsProvider, dispatchMCPTool). This pins
+  // both halves so a caller that drops the gate args — or a refactor of that
+  // condition — fails loudly here instead of silently auto-running a write.
+  it("auto-run write protection depends entirely on the gate args", async () => {
+    const ranWithGate = vi.fn()
+    const gated = await dispatchTool(
+      "add_cell",
+      { buffer_id: 1, sql: "INSERT INTO t VALUES (1)", run: true },
+      makeClient({ runCell: ranWithGate }),
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: true },
+      vi.fn().mockResolvedValue({ queryType: "INSERT" }),
+    )
+    expect(ranWithGate).not.toHaveBeenCalled()
+    expect(JSON.parse(gated.content)).toMatchObject({
+      ran: false,
+      skipped: true,
+    })
+
+    const ranWithoutGate = vi.fn(() =>
+      Promise.resolve({
+        success: true,
+        queryCount: 1,
+        results: ["success"] as Array<"success">,
+      }),
+    )
+    const ungated = await dispatchTool(
+      "add_cell",
+      { buffer_id: 1, sql: "INSERT INTO t VALUES (1)", run: true },
+      makeClient({ runCell: ranWithoutGate }),
+      noopStatus,
+    )
+    expect(ranWithoutGate).toHaveBeenCalled()
+    expect(JSON.parse(ungated.content)).toMatchObject({ ran: true })
+  })
+})
+
+describe("dispatchTool — apply_notebook_state auto-run", () => {
+  const dqlValidate = vi.fn().mockResolvedValue({
+    query: "SELECT 1",
+    columns: [{ name: "c1", type: "LONG" }],
+    timestamp: -1,
+  })
+
+  it("runs new cells with mode='run' (explicit) after apply", async () => {
+    const runCell = vi.fn(() =>
+      Promise.resolve({
+        success: true,
+        queryCount: 1,
+        results: ["success"] as Array<"success">,
+      }),
+    )
+    const client = makeClient({
+      runCell,
+      applyNotebookState: vi.fn(() =>
+        Promise.resolve({
+          applied: { added: ["new-1"], updated: [], deleted: [] },
+        }),
+      ),
+    })
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [{ id: null, value: "SELECT 1", mode: "run" }],
+      },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBeFalsy()
+    expect(runCell).toHaveBeenCalledWith(1, "new-1", undefined, undefined)
+    const parsed = JSON.parse(res.content) as {
+      runs: Array<{
+        cellId: string
+        success: boolean
+        queryCount?: number
+        results?: string[]
+      }>
+    }
+    expect(parsed.runs).toEqual([
+      { cellId: "new-1", success: true, queryCount: 1, results: ["success"] },
+    ])
+  })
+
+  it("defaults omitted mode to 'run' for new cells and runs them", async () => {
+    const runCell = vi.fn(() =>
+      Promise.resolve({
+        success: true,
+        queryCount: 1,
+        results: ["success"] as Array<"success">,
+      }),
+    )
+    const client = makeClient({
+      runCell,
+      applyNotebookState: vi.fn(() =>
+        Promise.resolve({
+          applied: { added: ["new-1"], updated: [], deleted: [] },
+        }),
+      ),
+    })
+    await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [{ id: null, value: "SELECT 1" }],
+      },
+      client,
+      noopStatus,
+    )
+    expect(runCell).toHaveBeenCalledWith(1, "new-1", undefined, undefined)
+  })
+
+  it("skips cells whose resolved mode is 'draw'", async () => {
+    const runCell = vi.fn(() =>
+      Promise.resolve({
+        success: true,
+        queryCount: 1,
+        results: ["success"] as Array<"success">,
+      }),
+    )
+    const client = makeClient({
+      runCell,
+      applyNotebookState: vi.fn(() =>
+        Promise.resolve({
+          applied: { added: ["new-1"], updated: [], deleted: [] },
+        }),
+      ),
+    })
+    await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [
+          {
+            id: null,
+            value: "SELECT 1",
+            mode: "draw",
+            chart_config: { type: "line", x_column: "ts", y_columns: ["c1"] },
+          },
+        ],
+      },
+      client,
+      noopStatus,
+    )
+    expect(runCell).not.toHaveBeenCalled()
+  })
+
+  it("skips cells with empty SQL", async () => {
+    const runCell = vi.fn(() =>
+      Promise.resolve({
+        success: true,
+        queryCount: 1,
+        results: ["success"] as Array<"success">,
+      }),
+    )
+    const client = makeClient({
+      runCell,
+      applyNotebookState: vi.fn(() =>
+        Promise.resolve({
+          applied: { added: ["new-1"], updated: [], deleted: [] },
+        }),
+      ),
+    })
+    await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [{ id: null, value: "   ", mode: "run" }],
+      },
+      client,
+      noopStatus,
+    )
+    expect(runCell).not.toHaveBeenCalled()
+  })
+
+  it("skips DDL/DML run cells regardless of the write permission", async () => {
+    const runCell = vi.fn(() =>
+      Promise.resolve({
+        success: true,
+        queryCount: 1,
+        results: ["success"] as Array<"success">,
+      }),
+    )
+    const client = makeClient({
+      runCell,
+      applyNotebookState: vi.fn(() =>
+        Promise.resolve({
+          applied: { added: ["new-1"], updated: [], deleted: [] },
+        }),
+      ),
+    })
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [{ id: null, value: "DROP TABLE victim", mode: "run" }],
+      },
+      client,
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: false },
+      vi.fn().mockResolvedValue({ queryType: "DROP TABLE" }),
+    )
+    expect(res.is_error).toBeFalsy()
+    expect(runCell).not.toHaveBeenCalled()
+    const parsed = JSON.parse(res.content) as {
+      runs: Array<{
+        cellId: string
+        success: boolean
+        skipped?: boolean
+        note?: string
+      }>
+    }
+    expect(parsed.runs).toHaveLength(1)
+    expect(parsed.runs[0]).toMatchObject({ success: true, skipped: true })
+    expect(parsed.runs[0].note).toMatch(/run_cell/)
+  })
+
+  it("skips DDL/DML cells regardless of run history (writes never auto-run)", async () => {
+    const runCell = vi.fn(() =>
+      Promise.resolve({
+        success: true,
+        queryCount: 1,
+        results: ["success"] as Array<"success">,
+      }),
+    )
+    const getCell = vi.fn(() =>
+      Promise.resolve({
+        id: "ins-1",
+        value: "INSERT INTO t VALUES (1)",
+        position: 0,
+        mode: "run" as const,
+        last_run_status: "success" as const,
+      }),
+    )
+    const client = makeClient({
+      runCell,
+      getCell,
+      applyNotebookState: vi.fn(() =>
+        Promise.resolve({
+          applied: { added: [], updated: ["ins-1"], deleted: [] },
+        }),
+      ),
+    })
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [{ id: "ins-1", value: "INSERT INTO t VALUES (1)" }],
+      },
+      client,
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: true },
+      vi.fn().mockResolvedValue({ queryType: "INSERT" }),
+    )
+    expect(res.is_error).toBeFalsy()
+    expect(runCell).not.toHaveBeenCalled()
+    const parsed = JSON.parse(res.content) as {
+      runs: Array<{
+        cellId: string
+        success: boolean
+        skipped?: boolean
+        note?: string
+      }>
+    }
+    expect(parsed.runs).toHaveLength(1)
+    expect(parsed.runs[0]).toMatchObject({
+      cellId: "ins-1",
+      success: true,
+      skipped: true,
+    })
+    expect(parsed.runs[0].note).toMatch(/run_cell/)
+  })
+
+  it("skips DDL/DML cells that never ran before (only run_cell executes writes)", async () => {
+    const runCell = vi.fn(() =>
+      Promise.resolve({
+        success: true,
+        queryCount: 1,
+        results: ["success"] as Array<"success">,
+      }),
+    )
+    const getCell = vi.fn(() =>
+      Promise.resolve({
+        id: "ins-1",
+        value: "INSERT INTO t VALUES (1)",
+        position: 0,
+        mode: "run" as const,
+        last_run_status: "none" as const,
+      }),
+    )
+    const client = makeClient({
+      runCell,
+      getCell,
+      applyNotebookState: vi.fn(() =>
+        Promise.resolve({
+          applied: { added: ["new-1"], updated: ["ins-1"], deleted: [] },
+        }),
+      ),
+    })
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [
+          { id: "ins-1", value: "INSERT INTO t VALUES (1)" },
+          { id: null, value: "INSERT INTO t VALUES (2)", mode: "run" },
+        ],
+      },
+      client,
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: true },
+      vi.fn().mockResolvedValue({ queryType: "INSERT" }),
+    )
+    expect(runCell).not.toHaveBeenCalled()
+    const parsed = JSON.parse(res.content) as {
+      runs: Array<{
+        cellId: string
+        success: boolean
+        skipped?: boolean
+        note?: string
+      }>
+    }
+    expect(parsed.runs).toHaveLength(2)
+    for (const run of parsed.runs) {
+      expect(run).toMatchObject({ success: true, skipped: true })
+      expect(run.note).toMatch(/run_cell/)
+    }
+  })
+
+  it("re-runs DQL cells that ran before (only writes are history-gated)", async () => {
+    const runCell = vi.fn(() =>
+      Promise.resolve({
+        success: true,
+        queryCount: 1,
+        results: ["success"] as Array<"success">,
+      }),
+    )
+    const getCell = vi.fn(() =>
+      Promise.resolve({
+        id: "sel-1",
+        value: "SELECT 1",
+        position: 0,
+        mode: "run" as const,
+        last_run_status: "success" as const,
+      }),
+    )
+    const client = makeClient({
+      runCell,
+      getCell,
+      applyNotebookState: vi.fn(() =>
+        Promise.resolve({
+          applied: { added: [], updated: ["sel-1"], deleted: [] },
+        }),
+      ),
+    })
+    await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [{ id: "sel-1", value: "SELECT 1" }],
+      },
+      client,
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: true },
+      dqlValidate,
+    )
+    expect(runCell).toHaveBeenCalledWith(1, "sel-1", undefined, "SELECT 1")
+  })
+
+  it("preserves existing mode when mode is omitted on an existing cell (draw stays draw, run stays run)", async () => {
+    const runCell = vi.fn(() =>
+      Promise.resolve({
+        success: true,
+        queryCount: 1,
+        results: ["success"] as Array<"success">,
+      }),
+    )
+    const getCell = vi.fn(
+      (
+        _buf: number,
+        id: string,
+      ): Promise<{
+        id: string
+        mode?: "run" | "draw"
+        value: string
+        position: number
+      }> =>
+        Promise.resolve({
+          id,
+          value: "",
+          position: 0,
+          mode: id === "draw-id" ? "draw" : "run",
+        }),
+    )
+    const client = makeClient({
+      runCell,
+      getCell,
+      applyNotebookState: vi.fn(() =>
+        Promise.resolve({
+          applied: { added: [], updated: ["run-id", "draw-id"], deleted: [] },
+        }),
+      ),
+    })
+    await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [
+          { id: "run-id", value: "SELECT 1" },
+          {
+            id: "draw-id",
+            value: "SELECT 2",
+            chart_config: { type: "line", x_column: "ts", y_columns: ["c1"] },
+          },
+        ],
+      },
+      client,
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: true },
+      dqlValidate,
+    )
+    expect(runCell).toHaveBeenCalledTimes(1)
+    expect(runCell).toHaveBeenCalledWith(1, "run-id", undefined, "SELECT 1")
+  })
+
+  it("dispatches run-mode cells in parallel — total wallclock equals slowest cell, not the sum", async () => {
+    const order: string[] = []
+    const finish: Record<string, () => void> = {}
+    const runCell = vi.fn(
+      (_buf: number, cellId: string) =>
+        new Promise<{
+          success: true
+          queryCount: number
+          results: Array<"success">
+        }>((resolve) => {
+          order.push(cellId)
+          finish[cellId] = () =>
+            resolve({ success: true, queryCount: 1, results: ["success"] })
+        }),
+    )
+    const client = makeClient({
+      runCell,
+      applyNotebookState: vi.fn(() =>
+        Promise.resolve({
+          applied: {
+            added: ["cell-1", "cell-2", "cell-3"],
+            updated: [],
+            deleted: [],
+          },
+        }),
+      ),
+    })
+    const pending = dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [
+          { id: null, value: "SELECT 1", mode: "run" },
+          { id: null, value: "SELECT 2", mode: "run" },
+          { id: null, value: "SELECT 3", mode: "run" },
+        ],
+      },
+      client,
+      noopStatus,
+    )
+    // Flush microtasks so dispatchTool resumes past applyNotebookState and
+    // fires every runCell concurrently.
+    await new Promise((r) => setTimeout(r, 0))
+    expect(order).toEqual(["cell-1", "cell-2", "cell-3"])
+    // Finish out of submission order — only possible if all three are in
+    // flight simultaneously.
+    finish["cell-3"]()
+    finish["cell-1"]()
+    finish["cell-2"]()
+    const res = await pending
+    const parsed = JSON.parse(res.content) as {
+      runs: Array<{ cellId: string; success: boolean }>
+    }
+    // Order in `runs` matches request order, not finish order.
+    expect(parsed.runs.map((r) => r.cellId)).toEqual([
+      "cell-1",
+      "cell-2",
+      "cell-3",
+    ])
+  })
+
+  it("reports per-cell runCell failure in the runs array with per-query results", async () => {
+    const runCell = vi.fn(() =>
+      Promise.resolve({
+        success: false,
+        queryCount: 3,
+        results: ["success", "ERROR: boom", "cancelled"],
+      }),
+    )
+    const client = makeClient({
+      runCell,
+      applyNotebookState: vi.fn(() =>
+        Promise.resolve({
+          applied: { added: ["new-1"], updated: [], deleted: [] },
+        }),
+      ),
+    })
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [
+          { id: null, value: "SELECT 1; SELECT bad; SELECT 2", mode: "run" },
+        ],
+      },
+      client,
+      noopStatus,
+    )
+    const parsed = JSON.parse(res.content) as {
+      runs: Array<{
+        cellId: string
+        success: boolean
+        queryCount?: number
+        results?: string[]
+      }>
+    }
+    expect(parsed.runs).toEqual([
+      {
+        cellId: "new-1",
+        success: false,
+        queryCount: 3,
+        results: ["success", "ERROR: boom", "cancelled"],
+      },
+    ])
+  })
+})
+
+describe("dispatchTool — NotebookToolError envelope", () => {
+  it("archived → { error_code: 'archived', hint, message }", async () => {
+    const client = makeClient({
+      runCell: vi.fn(() =>
+        Promise.reject(
+          new NotebookToolError("archived", 'Notebook "x" is archived.'),
+        ),
+      ),
+    })
+    const res = await dispatchTool(
+      "run_cell",
+      { buffer_id: 1, cell_id: "c" },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as Record<string, unknown>
+    expect(parsed.error_code).toBe("archived")
+    expect(parsed.hint).toMatch(/unarchive|create_notebook/)
+  })
+
+  it("deleted → error_code 'deleted'", async () => {
+    const client = makeClient({
+      listCells: vi.fn(() =>
+        Promise.reject(new NotebookToolError("deleted", "gone")),
+      ),
+    })
+    const res = await dispatchTool(
+      "list_cells",
+      { buffer_id: 1 },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBe(true)
+    expect(
+      (JSON.parse(res.content) as Record<string, unknown>).error_code,
+    ).toBe("deleted")
+  })
+
+  it("unknown_cell → error_code 'unknown_cell' with resync hint", async () => {
+    const client = makeClient({
+      deleteCell: vi.fn(() =>
+        Promise.reject(new NotebookToolError("unknown_cell", "no cell abc123")),
+      ),
+    })
+    const res = await dispatchTool(
+      "delete_cell",
+      { buffer_id: 1, cell_id: "abc123" },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBe(true)
+    const parsed = JSON.parse(res.content) as Record<string, unknown>
+    expect(parsed.error_code).toBe("unknown_cell")
+    expect(parsed.hint).toMatch(/list_cells/)
+  })
+})
+
+describe("dispatchTool — non-NotebookToolError falls through to default handler", () => {
+  it("is captured as a generic tool execution error", async () => {
+    const client = makeClient({
+      runCell: vi.fn(() => Promise.reject(new Error("network boom"))),
+    })
+    const res = await dispatchTool(
+      "run_cell",
+      { buffer_id: 1, cell_id: "c" },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBe(true)
+    expect(res.content).toMatch(/network boom/)
+  })
+})
+
+describe("dispatchTool — run_query replay guard (sqlWriteExecuted)", () => {
+  const runQuery = async (
+    sql: string,
+    rawType: "dql" | "dml" | "ddl",
+  ): Promise<ToolExecutionContext> => {
+    const client = makeClient({
+      runQueryRaw: vi.fn(() =>
+        rawType === "dql"
+          ? Promise.resolve({
+              type: "dql" as const,
+              columns: [],
+              dataset: [],
+              count: 0,
+            })
+          : Promise.resolve({ type: rawType }),
+      ),
+    })
+    const toolContext: ToolExecutionContext = {}
+    await dispatchTool(
+      "run_query",
+      { sql },
+      client,
+      noopStatus,
+      undefined,
+      undefined,
+      undefined,
+      toolContext,
+    )
+    return toolContext
+  }
+
+  it("flags sqlWriteExecuted when a DML statement executes", async () => {
+    const ctx = await runQuery("INSERT INTO t VALUES (1)", "dml")
+    expect(ctx.sqlWriteExecuted).toBe(true)
+  })
+
+  it("flags sqlWriteExecuted when a DDL statement executes", async () => {
+    const ctx = await runQuery("DROP TABLE t", "ddl")
+    expect(ctx.sqlWriteExecuted).toBe(true)
+  })
+
+  it("does not flag sqlWriteExecuted for a read-only (DQL) query", async () => {
+    const ctx = await runQuery("SELECT 1", "dql")
+    expect(ctx.sqlWriteExecuted).toBeUndefined()
+  })
+})
+
+// Data-leak regression — guards the no-data-fields invariant when notebook
+// tools are routed through the MCP path (browser ← bridge ← agent). The
+// MCP adapter (`dispatchMCPTool`) wraps `dispatchTool`'s output verbatim, so
+// the invariant is structural; this test locks it in case anyone ever
+// inlines a richer payload there.
+describe("dispatchMCPTool — data-leak invariant", () => {
+  const callOf = (name: string, args: Record<string, unknown> = {}) => ({
+    v: EXPECTED_BRIDGE_VERSION,
+    type: "tool_call" as const,
+    requestId: "r-" + name,
+    name,
+    arguments: args,
+    deadlineMs: 60_000,
+  })
+
+  const ctxFor = (client: ModelToolsClient) => ({
+    modelToolsClient: client,
+    freshness: {
+      get: () => "fresh" as const,
+      set: () => undefined,
+      getReadBuffer: () => 1,
+      setReadBuffer: () => undefined,
+    },
+    metaToolContext: {
+      getActiveBufferId: () => 1,
+      getWorkspace: () => null,
+      getDigest: () => null,
+      runQuery: null,
+    },
+  })
+
+  it("run_cell happy-path response carries no data field keys", async () => {
+    const client = makeClient({
+      runCell: vi.fn(() =>
+        Promise.resolve({
+          success: true,
+          queryCount: 1,
+          results: ["success"] as Array<"success">,
+        }),
+      ),
+    })
+    const result = await dispatchMCPTool(
+      callOf("run_cell", { buffer_id: 1, cell_id: "c" }),
+      ctxFor(client),
+    )
+    const wireText = JSON.stringify(result)
+    expect(wireText).not.toMatch(/columns|dataset|count|rows/)
+  })
+
+  it("run_cell error-path response carries no data field keys", async () => {
+    const client = makeClient({
+      runCell: vi.fn(() =>
+        Promise.resolve({
+          success: false,
+          queryCount: 1,
+          results: ["ERROR: syntax near (1)"],
+        }),
+      ),
+    })
+    const result = await dispatchMCPTool(
+      callOf("run_cell", { buffer_id: 1, cell_id: "c" }),
+      ctxFor(client),
+    )
+    const wireText = JSON.stringify(result)
+    expect(wireText).toMatch(/syntax/)
+    expect(wireText).not.toMatch(/columns|dataset|count|rows/)
+  })
+
+  it("add_cell with run:true similarly never leaks data fields", async () => {
+    const client = makeClient({
+      addCell: vi.fn(() => Promise.resolve({ cellId: "new" })),
+      runCell: vi.fn(() =>
+        Promise.resolve({
+          success: true,
+          queryCount: 1,
+          results: ["success"] as Array<"success">,
+        }),
+      ),
+    })
+    const result = await dispatchMCPTool(
+      callOf("add_cell", { buffer_id: 1, sql: "select 1", run: true }),
+      ctxFor(client),
+    )
+    expect(JSON.stringify(result)).not.toMatch(/columns|dataset|count|rows/)
+  })
+})
+
+describe("dispatchTool — get_cell content cap switch", () => {
+  it("forwards get_full_content: true to the client", async () => {
+    const client = makeClient()
+    await dispatchTool(
+      "get_cell",
+      { buffer_id: 1, cell_id: "c", get_full_content: true },
+      client,
+      noopStatus,
+    )
+    expect(client.getCell).toHaveBeenCalledWith(1, "c", true)
+  })
+
+  it("applies the cap when get_full_content is omitted or null", async () => {
+    const client = makeClient()
+    await dispatchTool(
+      "get_cell",
+      { buffer_id: 1, cell_id: "c" },
+      client,
+      noopStatus,
+    )
+    await dispatchTool(
+      "get_cell",
+      { buffer_id: 1, cell_id: "c", get_full_content: null },
+      client,
+      noopStatus,
+    )
+    expect(client.getCell).toHaveBeenNthCalledWith(1, 1, "c", false)
+    expect(client.getCell).toHaveBeenNthCalledWith(2, 1, "c", false)
+  })
+})
+
+describe("dispatchTool — apply_notebook_state preserve_value", () => {
+  const applyOk = (updated: string[]) =>
+    vi.fn((_bufferId: number, _request: ApplyNotebookStateRequest) =>
+      Promise.resolve({ applied: { added: [], updated, deleted: [] } }),
+    )
+
+  it("rejects a cell providing both value and preserve_value", async () => {
+    const client = makeClient()
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [{ id: "a", value: "SELECT 1", preserve_value: true }],
+      },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBe(true)
+    expect(res.content).toMatch(/exactly one/)
+    expect(client.applyNotebookState).not.toHaveBeenCalled()
+  })
+
+  it("rejects a cell providing neither value nor preserve_value", async () => {
+    const client = makeClient()
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [{ id: "a" }],
+      },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBe(true)
+    expect(res.content).toMatch(/has no value/)
+    expect(client.applyNotebookState).not.toHaveBeenCalled()
+  })
+
+  it("rejects preserve_value without an existing cell id", async () => {
+    const client = makeClient()
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [{ preserve_value: true }],
+      },
+      client,
+      noopStatus,
+    )
+    expect(res.is_error).toBe(true)
+    expect(res.content).toMatch(/without an existing cell id/)
+    expect(client.applyNotebookState).not.toHaveBeenCalled()
+  })
+
+  it("forwards preserve_value cells as preserveValue with no value", async () => {
+    const applyNotebookState = applyOk(["a"])
+    const client = makeClient({ applyNotebookState })
+    await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [{ id: "a", preserve_value: true }],
+      },
+      client,
+      noopStatus,
+    )
+    expect(applyNotebookState).toHaveBeenCalledTimes(1)
+    const sent = applyNotebookState.mock.calls[0][1]
+    expect(sent.cells[0]).toMatchObject({ id: "a", preserveValue: true })
+    expect(sent.cells[0]).not.toHaveProperty("value")
+  })
+
+  it("auto-run skips a preserved write cell, gating on its live SQL", async () => {
+    const runCell = vi.fn(() =>
+      Promise.resolve({
+        success: true,
+        queryCount: 1,
+        results: ["success"] as Array<"success">,
+      }),
+    )
+    const getCell = vi.fn(() =>
+      Promise.resolve({
+        id: "ins-1",
+        value: "INSERT INTO t VALUES (1)",
+        position: 0,
+        mode: "run" as const,
+        last_run_status: "success" as const,
+      }),
+    )
+    const getCellSql = vi.fn(() => "INSERT INTO t VALUES (1)")
+    const client = makeClient({
+      runCell,
+      getCell,
+      getCellSql,
+      applyNotebookState: applyOk(["ins-1"]),
+    })
+    const res = await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [{ id: "ins-1", preserve_value: true }],
+      },
+      client,
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: true },
+      vi.fn().mockResolvedValue({ queryType: "INSERT" }),
+    )
+    expect(res.is_error).toBeFalsy()
+    expect(runCell).not.toHaveBeenCalled()
+    const parsed = JSON.parse(res.content) as {
+      runs: Array<{ cellId: string; skipped?: boolean }>
+    }
+    expect(parsed.runs[0]).toMatchObject({ cellId: "ins-1", skipped: true })
+  })
+
+  it("auto-run executes a preserved DQL cell with its live SQL", async () => {
+    const runCell = vi.fn(() =>
+      Promise.resolve({
+        success: true,
+        queryCount: 1,
+        results: ["success"] as Array<"success">,
+      }),
+    )
+    const getCell = vi.fn(() =>
+      Promise.resolve({
+        id: "sel-1",
+        value: "SELECT 1",
+        position: 0,
+        mode: "run" as const,
+        last_run_status: "success" as const,
+      }),
+    )
+    const getCellSql = vi.fn(() => "SELECT 1")
+    const client = makeClient({
+      runCell,
+      getCell,
+      getCellSql,
+      applyNotebookState: applyOk(["sel-1"]),
+    })
+    await dispatchTool(
+      "apply_notebook_state",
+      {
+        buffer_id: 1,
+        layout_mode: null,
+        maximized_cell_id: null,
+        cells: [{ id: "sel-1", preserve_value: true }],
+      },
+      client,
+      noopStatus,
+      { grantSchemaAccess: true, read: true, write: true },
+      vi.fn().mockResolvedValue({
+        query: "SELECT 1",
+        columns: [{ name: "1", type: "INT" }],
+        timestamp: -1,
+      }),
+    )
+    expect(runCell).toHaveBeenCalledWith(1, "sel-1", undefined, "SELECT 1")
+  })
+})
diff --git a/src/utils/ai/shared.ts b/src/utils/ai/shared.ts
index 0e509a956..2b34221bb 100644
--- a/src/utils/ai/shared.ts
+++ b/src/utils/ai/shared.ts
@@ -71,6 +71,9 @@ export function getMessageTextLength(m: {
 
 export type ToolExecutionContext = {
   suggestedSQL?: string
+  notebookMutated?: boolean
+  sqlWriteExecuted?: boolean
+  notebookReadSeq?: number
 }
 
 export const executeTool = async (
diff --git a/src/utils/ai/tools.ts b/src/utils/ai/tools.ts
deleted file mode 100644
index a8c489dd0..000000000
--- a/src/utils/ai/tools.ts
+++ /dev/null
@@ -1,120 +0,0 @@
-import type { ToolDefinition } from "./types"
-
-export const DEFAULT_TOOLS: ToolDefinition[] = [
-  {
-    name: "suggest_query",
-    description:
-      "Suggest a SQL query to the user. The query will be displayed as a suggestion that the user can accept or reject. Always validate the query using validate_query before suggesting it.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: {
-          type: "string",
-          description: "The SQL query to suggest to the user",
-        },
-      },
-      required: ["query"],
-    },
-  },
-  {
-    name: "validate_query",
-    description:
-      "Validate the syntax correctness of a SQL query using QuestDB's SQL syntax validator. All generated SQL queries should be validated using this tool before responding to the user.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: {
-          type: "string",
-          description: "The SQL query to validate",
-        },
-      },
-      required: ["query"],
-    },
-  },
-  {
-    name: "get_questdb_toc",
-    description:
-      "Get a table of contents listing all available QuestDB functions, operators, and SQL keywords. Use this first to see what documentation is available before requesting specific items.",
-    inputSchema: {
-      type: "object",
-      properties: {},
-    },
-  },
-  {
-    name: "get_questdb_documentation",
-    description:
-      "Get documentation for specific QuestDB functions, operators, or SQL keywords. This is much more efficient than loading all documentation.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        category: {
-          type: "string",
-          enum: [
-            "functions",
-            "operators",
-            "sql",
-            "concepts",
-            "schema",
-            "cookbook",
-          ],
-          description: "The category of documentation to retrieve",
-        },
-        items: {
-          type: "array",
-          items: {
-            type: "string",
-          },
-          description:
-            "List of specific docs items in the category. IMPORTANT: Category of these items must match the category parameter. Name of these items should exactly match the entry in the table of contents you get with get_questdb_toc.",
-        },
-      },
-      required: ["category", "items"],
-    },
-  },
-]
-
-export const SCHEMA_TOOLS: ToolDefinition[] = [
-  {
-    name: "get_tables",
-    description:
-      "Get a list of all tables and materialized views in the QuestDB database",
-    inputSchema: {
-      type: "object",
-      properties: {},
-    },
-  },
-  {
-    name: "get_table_schema",
-    description:
-      "Get the full schema definition (DDL) for a specific table or materialized view",
-    inputSchema: {
-      type: "object",
-      properties: {
-        table_name: {
-          type: "string",
-          description:
-            "The name of the table or materialized view to get schema for",
-        },
-      },
-      required: ["table_name"],
-    },
-  },
-  {
-    name: "get_table_details",
-    description:
-      "Get the runtime details/statistics of a specific table or materialized view",
-    inputSchema: {
-      type: "object",
-      properties: {
-        table_name: {
-          type: "string",
-          description:
-            "The name of the table or materialized view to get details for",
-        },
-      },
-      required: ["table_name"],
-    },
-  },
-]
-
-export const ALL_TOOLS: ToolDefinition[] = [...DEFAULT_TOOLS, ...SCHEMA_TOOLS]
diff --git a/src/utils/ai/types.ts b/src/utils/ai/types.ts
index 0c7c5e281..c4af083a1 100644
--- a/src/utils/ai/types.ts
+++ b/src/utils/ai/types.ts
@@ -5,7 +5,12 @@ import type {
   StreamingCallback,
   TokenUsage,
 } from "../aiAssistant"
+import type { Permissions, ToolCategory } from "../tools/permissions"
+import type { ValidateQueryResult } from "../questdb/types"
 import type { ProviderId } from "./settings"
+import type { ToolExecutionContext } from "./shared"
+
+export type ToolSurface = "ai" | "mcp"
 
 export interface ToolDefinition {
   name: string
@@ -14,7 +19,14 @@ export interface ToolDefinition {
     type: "object"
     properties: Record<string, unknown>
     required?: string[]
+    // Required by OpenAI strict mode on every object schema.
+    additionalProperties?: boolean
   }
+  category: ToolCategory
+  surfaces?: ToolSurface[]
+  mutatesNotebook?: boolean
+  // Modifies existing cell content/arrangement in place
+  editsCells?: boolean
 }
 
 export type ToolCall = {
@@ -50,21 +62,28 @@ export interface FlowResult {
   tokenUsage: TokenUsage
 }
 
+export type ExecuteFlowParams = {
+  model: string
+  config: FlowConfig
+  modelToolsClient: ModelToolsClient
+  tools: ToolDefinition[]
+  setStatus: StatusCallback
+  abortSignal?: AbortSignal
+  streaming?: StreamingCallback
+  perms?: Permissions | (() => Permissions)
+  validateSql?: (sql: string) => Promise<ValidateQueryResult>
+  toolContext?: ToolExecutionContext
+}
+
 export interface AIProvider {
   readonly id: ProviderId
   readonly contextWindow: number
 
   toNativeMessages(messages: Message[]): unknown
 
-  executeFlow(params: {
-    model: string
-    config: FlowConfig
-    modelToolsClient: ModelToolsClient
-    tools: ToolDefinition[]
-    setStatus: StatusCallback
-    abortSignal?: AbortSignal
-    streaming?: StreamingCallback
-  }): Promise<FlowResult | AiAssistantAPIError>
+  executeFlow(
+    params: ExecuteFlowParams,
+  ): Promise<FlowResult | AiAssistantAPIError>
 
   generateTitle(params: {
     model: string
diff --git a/src/utils/aiAssistant.ts b/src/utils/aiAssistant.ts
index 9a7cff8fd..5a10eebda 100644
--- a/src/utils/aiAssistant.ts
+++ b/src/utils/aiAssistant.ts
@@ -1,8 +1,15 @@
 import { Client } from "./questdb/client"
-import { Type, Table, TableKind } from "./questdb/types"
+import {
+  Type,
+  Table,
+  TableKind,
+  ValidateQueryResult,
+  getTableKind,
+} from "./questdb/types"
+import { mapQueryRawToResult, type RunQueryRawResult } from "./tools/runQuery"
 import type { ProviderId } from "./ai"
 import type { AiAssistantSettings } from "../providers/LocalStorageProvider/types"
-import { formatSql } from "./formatSql"
+import { normalizeSql } from "./formatSql"
 import { AIOperationStatus, StatusArgs } from "../providers/AIStatusProvider"
 import type {
   ConversationId,
@@ -11,13 +18,39 @@ import type {
 import { compactConversationIfNeeded, toApiMessages } from "./contextCompaction"
 import {
   createProvider,
-  ALL_TOOLS,
-  DEFAULT_TOOLS,
+  toolsForPermission,
   getUnifiedPrompt,
+  getAiPermissions,
+  readLiveAiPermissions,
   BUILTIN_PROVIDERS,
 } from "./ai"
 import type { AIProvider } from "./ai"
-import { getTableKind } from "./questdb/types"
+import type { ToolExecutionContext } from "./ai/shared"
+import { getCellRunStatus, type RunStatus } from "./ai/runStatus"
+import {
+  getController,
+  getUserActionSeq,
+  getWorkspace,
+  NotebookToolError,
+  withBoundNotebook,
+  withBoundNotebookReadOnly,
+  type ApplyNotebookStateRequest,
+  type NotebookController,
+} from "./notebookAIBridge"
+import {
+  MAX_NOTEBOOK_CELLS,
+  MAX_CELL_LINES,
+  exceedsCellLineLimit,
+} from "../store/notebook"
+import type { CellMode, CellType } from "../store/notebook"
+import type { ChartConfig } from "../scenes/Editor/Notebook/CellChart/chartTypes"
+import {
+  buildSnapshot,
+  sanitizeForPromptContext,
+  toChartConfigWire,
+  type ChartConfigWire,
+  type NotebookContextSnapshot,
+} from "./ai/notebookSnapshot"
 
 export type ActiveProviderSettings = {
   model: string
@@ -47,11 +80,140 @@ export interface GeneratedSQL {
   tokenUsage?: TokenUsage
 }
 
+export type NotebookCellSummary = {
+  id: string
+  preview: string
+  position: number
+  // Omitted for SQL cells (the default); "markdown" for prose cells.
+  type?: "sql" | "markdown"
+  mode?: "run" | "draw"
+  last_run_status?: RunStatus
+}
+
+export type NotebookCellDetails = {
+  id: string
+  value: string
+  truncated?: true
+  full_length?: number
+  position: number
+  type?: "sql" | "markdown"
+  mode?: "run" | "draw"
+  auto_refresh?: boolean
+  is_chart_maximized?: boolean
+  chart_config?: ChartConfigWire
+  last_run_status?: RunStatus
+  last_run_error?: string
+}
+
 export interface ModelToolsClient {
   validateQuery: (query: string) => Promise<AiAssistantValidateQueryResult>
+  // The AI-flavored `validateQuery` above lacks queryType needed to classify DDL/DML.
+  validateSqlRaw: (query: string) => Promise<ValidateQueryResult>
+  runQueryRaw: (
+    sql: string,
+    requestedLimit: number,
+    signal?: AbortSignal,
+  ) => Promise<RunQueryRawResult>
   getTables?: () => Promise<Array<{ name: string; type: TableKind }>>
   getTableSchema?: (tableName: string) => Promise<string | null>
   getTableDetails?: (tableName: string) => Promise<Table | null>
+
+  createNotebook: (
+    label?: string,
+  ) => Promise<{ bufferId: number; label: string }>
+  duplicateNotebook: (
+    bufferId: number,
+  ) => Promise<{ bufferId: number; label: string }>
+  deleteNotebook: (bufferId: number) => Promise<void>
+  listCells: (bufferId: number) => Promise<NotebookCellSummary[]>
+  getCell: (
+    bufferId: number,
+    cellId: string,
+    getFullContent?: boolean,
+  ) => Promise<NotebookCellDetails>
+  getNotebookState: (bufferId: number) => Promise<NotebookContextSnapshot>
+  addCell: (
+    bufferId: number,
+    value: string,
+    afterCellId?: string,
+    type?: CellType,
+  ) => Promise<{ cellId: string }>
+  updateCell: (
+    bufferId: number,
+    cellId: string,
+    updates: { value: string },
+  ) => Promise<void>
+  deleteCell: (bufferId: number, cellId: string) => Promise<void>
+  moveCellUp: (bufferId: number, cellId: string) => Promise<void>
+  moveCellDown: (bufferId: number, cellId: string) => Promise<void>
+  duplicateCell: (
+    bufferId: number,
+    cellId: string,
+  ) => Promise<{ cellId: string }>
+  runCell: (
+    bufferId: number,
+    cellId: string,
+    signal?: AbortSignal,
+    sql?: string,
+  ) => Promise<{
+    success: boolean
+    queryCount: number
+    results: string[]
+    unverified?: boolean
+    note?: string
+  }>
+  setLayoutMode: (bufferId: number, mode: "list" | "grid") => Promise<void>
+  setCellLayout: (
+    bufferId: number,
+    cellId: string,
+    x: number,
+    y: number,
+    w: number,
+    h: number,
+  ) => Promise<void>
+  setCellMode: (
+    bufferId: number,
+    cellId: string,
+    mode: CellMode,
+  ) => Promise<void>
+  setCellChartConfig: (
+    bufferId: number,
+    cellId: string,
+    patch: Partial<ChartConfig>,
+  ) => Promise<void>
+  setCellAutoRefresh: (
+    bufferId: number,
+    cellId: string,
+    value: boolean,
+  ) => Promise<void>
+  setCellChartMaximized: (
+    bufferId: number,
+    cellId: string,
+    value: boolean,
+  ) => Promise<void>
+  setCellMaximized: (bufferId: number, cellId: string | null) => Promise<void>
+  // cells is the COMPLETE desired list — missing ids are deleted; validation is all-or-nothing.
+  applyNotebookState: (
+    bufferId: number,
+    request: ApplyNotebookStateRequest,
+  ) => Promise<{
+    applied: { added: string[]; updated: string[]; deleted: string[] }
+  }>
+  // null → gate falls through so the executor's not-found error wins.
+  getCellSql?: (bufferId: number, cellId: string) => string | null
+  // Cell kind, for tools that must treat markdown cells differently (e.g.
+  // run_cell skips them). null → cell not found.
+  getCellType?: (bufferId: number, cellId: string) => CellType | null
+}
+
+export type NotebookClientExtras = {
+  conversationId?: ConversationId
+  bindNotebook?: (
+    conversationId: ConversationId,
+    bufferId: number,
+  ) => Promise<void>
+  // Lets the Abort button cancel a pending waiter instead of blocking for the full waitForController timeout.
+  abortSignal?: AbortSignal
 }
 
 export type StatusCallback = (
@@ -72,15 +234,6 @@ export type StreamingCallback = {
   onBeforeStream?: () => void
 }
 
-export const normalizeSql = (sql: string, insertSemicolon: boolean = true) => {
-  if (!sql) return ""
-  let result = sql.trim()
-  if (result.endsWith(";")) {
-    result = result.slice(0, -1)
-  }
-  return formatSql(result) + (insertSemicolon ? ";" : "")
-}
-
 export function isAiAssistantError(
   response: AiAssistantAPIError | GeneratedSQL | Partial<GeneratedSQL>,
 ): response is AiAssistantAPIError {
@@ -90,10 +243,65 @@ export function isAiAssistantError(
   return false
 }
 
+const CELL_VALUE_MAX = 4096
+const FULL_CELL_VALUE_MAX = 1_000_000
+const LAST_ERROR_MAX = 200
+
+// Sanitize `<`/`>` so a server-echoed error can't smuggle closing tags into the tool response.
+const trimError = (msg: string | undefined): string | undefined => {
+  if (!msg) return undefined
+  const clipped =
+    msg.length <= LAST_ERROR_MAX
+      ? msg
+      : `${msg.slice(0, LAST_ERROR_MAX - 3)}...`
+  return sanitizeForPromptContext(clipped)
+}
+
+const lastRunStatusForCell = (
+  cell:
+    | {
+        result?: { results: Array<{ type: string; error?: string }> } | null
+        lastRunStatus?: RunStatus
+      }
+    | undefined,
+): {
+  status: RunStatus
+  error?: string
+} => {
+  const { status, error } = getCellRunStatus(cell)
+  return status === "error" ? { status, error: trimError(error) } : { status }
+}
+
+const requireCell = (controller: NotebookController, cellId: string) => {
+  const cell = controller.getCellsSnapshot().find((c) => c.id === cellId)
+  if (!cell) {
+    throw new NotebookToolError(
+      "unknown_cell",
+      `Cell ${cellId} is not in notebook ${controller.bufferId}.`,
+    )
+  }
+  return cell
+}
+
+const requireCellWithinLineLimit = (value: string) => {
+  if (exceedsCellLineLimit(value)) {
+    throw new NotebookToolError(
+      "cell_too_large",
+      `Cell content has ${value.split("\n").length} lines, over the ${MAX_CELL_LINES}-line limit. Split it into multiple cells.`,
+    )
+  }
+}
+
 export function createModelToolsClient(
   questClient: Client,
   tables?: Array<Table>,
+  extras?: NotebookClientExtras,
 ): ModelToolsClient {
+  const abortSignal = extras?.abortSignal
+  const bound = <T>(
+    bufferId: number,
+    fn: (controller: NotebookController) => Promise<T>,
+  ): Promise<T> => withBoundNotebook(bufferId, fn, abortSignal)
   return {
     async validateQuery(
       query: string,
@@ -127,6 +335,16 @@ export function createModelToolsClient(
         }
       }
     },
+    validateSqlRaw(query: string): Promise<ValidateQueryResult> {
+      return questClient.validateQuery(query)
+    },
+    runQueryRaw(
+      sql: string,
+      requestedLimit: number,
+      signal?: AbortSignal,
+    ): Promise<RunQueryRawResult> {
+      return mapQueryRawToResult(questClient, sql, requestedLimit, signal)
+    },
     ...(tables
       ? {
           getTables(): Promise<Array<{ name: string; type: TableKind }>> {
@@ -182,6 +400,309 @@ export function createModelToolsClient(
           },
         }
       : {}),
+
+    async createNotebook(label) {
+      const ws = getWorkspace()
+      if (!ws) {
+        throw new NotebookToolError(
+          "workspace_unavailable",
+          "Notebook workspace is not mounted.",
+        )
+      }
+      const res = await ws.createNotebook(label, abortSignal)
+      // First-binding-wins: bindNotebook no-ops on an already-bound conversation.
+      if (extras?.bindNotebook && extras.conversationId) {
+        await extras.bindNotebook(extras.conversationId, res.bufferId)
+      }
+      return res
+    },
+
+    async duplicateNotebook(bufferId) {
+      const ws = getWorkspace()
+      if (!ws) {
+        throw new NotebookToolError(
+          "workspace_unavailable",
+          "Notebook workspace is not mounted.",
+        )
+      }
+      return ws.duplicateNotebook(bufferId, abortSignal)
+    },
+
+    async deleteNotebook(bufferId) {
+      const ws = getWorkspace()
+      if (!ws) {
+        throw new NotebookToolError(
+          "workspace_unavailable",
+          "Notebook workspace is not mounted.",
+        )
+      }
+      await ws.deleteNotebook(bufferId)
+    },
+
+    listCells(bufferId) {
+      return withBoundNotebookReadOnly(
+        bufferId,
+        (view, ctrl) => {
+          const cells = ctrl ? ctrl.getCellsSnapshot() : view.cells
+          const summaries: NotebookCellSummary[] = cells.map((cell) => {
+            const runInfo = lastRunStatusForCell(cell)
+            const summary: NotebookCellSummary = {
+              id: cell.id,
+              preview:
+                cell.value.length <= 120
+                  ? cell.value
+                  : `${cell.value.slice(0, 117)}...`,
+              position: cell.position,
+              last_run_status: runInfo.status,
+            }
+            if (cell.type === "markdown") summary.type = "markdown"
+            if (cell.mode) summary.mode = cell.mode
+            return summary
+          })
+          return Promise.resolve(summaries)
+        },
+        abortSignal,
+      )
+    },
+
+    getCell(bufferId, cellId, getFullContent) {
+      return withBoundNotebookReadOnly(
+        bufferId,
+        (view, ctrl) => {
+          const cells = ctrl ? ctrl.getCellsSnapshot() : view.cells
+          const cell = cells.find((c) => c.id === cellId)
+          if (!cell) {
+            throw new NotebookToolError(
+              "unknown_cell",
+              `Cell ${cellId} not found in notebook ${bufferId}.`,
+            )
+          }
+          if (getFullContent && cell.value.length > FULL_CELL_VALUE_MAX) {
+            throw new NotebookToolError(
+              "cell_too_large",
+              `Cell ${cellId} is ${cell.value.length} chars — over the ${FULL_CELL_VALUE_MAX}-char get_full_content limit, so it cannot be read or edited via agent tools. In apply_notebook_state, keep it with preserve_value:true.`,
+            )
+          }
+          const truncated =
+            !getFullContent && cell.value.length > CELL_VALUE_MAX
+          const value = truncated
+            ? cell.value.slice(0, CELL_VALUE_MAX)
+            : cell.value
+          const runInfo = lastRunStatusForCell(cell)
+          const out: NotebookCellDetails = {
+            id: cell.id,
+            value,
+            position: cell.position,
+            last_run_status: runInfo.status,
+            last_run_error: runInfo.error,
+          }
+          if (truncated) {
+            out.truncated = true
+            out.full_length = cell.value.length
+          }
+          if (cell.type === "markdown") out.type = "markdown"
+          if (cell.mode) out.mode = cell.mode
+          if (typeof cell.autoRefresh === "boolean")
+            out.auto_refresh = cell.autoRefresh
+          if (typeof cell.isChartMaximized === "boolean")
+            out.is_chart_maximized = cell.isChartMaximized
+          if (cell.chartConfig && Array.isArray(cell.chartConfig.queries))
+            out.chart_config = toChartConfigWire(cell.chartConfig)
+          return Promise.resolve(out)
+        },
+        abortSignal,
+      )
+    },
+
+    getNotebookState(bufferId) {
+      return withBoundNotebookReadOnly(
+        bufferId,
+        () => {
+          const snap = buildSnapshot(getWorkspace(), bufferId)
+          if (!snap) {
+            throw new NotebookToolError(
+              "not_a_notebook",
+              `Buffer ${bufferId} has no notebook state.`,
+            )
+          }
+          return Promise.resolve(snap)
+        },
+        abortSignal,
+      )
+    },
+
+    addCell(bufferId, value, afterCellId, type) {
+      return bound(bufferId, (ctrl) => {
+        if (ctrl.getCellsSnapshot().length >= MAX_NOTEBOOK_CELLS) {
+          throw new NotebookToolError(
+            "cell_limit",
+            `Notebook ${bufferId} already has the maximum of ${MAX_NOTEBOOK_CELLS} cells. Delete a cell before adding another.`,
+          )
+        }
+        if (type !== "markdown") requireCellWithinLineLimit(value)
+        const cellId = ctrl.addCell(value, afterCellId, type)
+        return Promise.resolve({ cellId })
+      })
+    },
+
+    updateCell(bufferId, cellId, updates) {
+      return bound(bufferId, (ctrl) => {
+        const cell = requireCell(ctrl, cellId)
+        if (cell.type !== "markdown" && updates.value !== undefined) {
+          requireCellWithinLineLimit(updates.value)
+        }
+        ctrl.updateCell(cellId, updates)
+        return Promise.resolve()
+      })
+    },
+
+    deleteCell(bufferId, cellId) {
+      return bound(bufferId, (ctrl) => {
+        requireCell(ctrl, cellId)
+        if (ctrl.getCellsSnapshot().length <= 1) {
+          throw new NotebookToolError(
+            "last_cell",
+            `Cell ${cellId} is the only cell in notebook ${bufferId}; a notebook must keep at least one cell.`,
+          )
+        }
+        ctrl.deleteCell(cellId)
+        return Promise.resolve()
+      })
+    },
+
+    moveCellUp(bufferId, cellId) {
+      return bound(bufferId, (ctrl) => {
+        requireCell(ctrl, cellId)
+        ctrl.moveCellUp(cellId)
+        return Promise.resolve()
+      })
+    },
+
+    moveCellDown(bufferId, cellId) {
+      return bound(bufferId, (ctrl) => {
+        requireCell(ctrl, cellId)
+        ctrl.moveCellDown(cellId)
+        return Promise.resolve()
+      })
+    },
+
+    duplicateCell(bufferId, cellId) {
+      return bound(bufferId, (ctrl) => {
+        requireCell(ctrl, cellId)
+        if (ctrl.getCellsSnapshot().length >= MAX_NOTEBOOK_CELLS) {
+          throw new NotebookToolError(
+            "cell_limit",
+            `Notebook ${bufferId} already has the maximum of ${MAX_NOTEBOOK_CELLS} cells. Delete a cell before duplicating another.`,
+          )
+        }
+        const newId = ctrl.duplicateCell(cellId)
+        return Promise.resolve({ cellId: newId })
+      })
+    },
+
+    runCell(bufferId, cellId, signal, sql) {
+      return withBoundNotebook(
+        bufferId,
+        async (ctrl) => {
+          requireCell(ctrl, cellId)
+          return ctrl.runCell(cellId, signal, sql)
+        },
+        signal ?? abortSignal,
+      )
+    },
+
+    setLayoutMode(bufferId, mode) {
+      return bound(bufferId, (ctrl) => {
+        ctrl.setLayoutMode(mode)
+        return Promise.resolve()
+      })
+    },
+
+    setCellLayout(bufferId, cellId, x, y, w, h) {
+      return bound(bufferId, (ctrl) => {
+        requireCell(ctrl, cellId)
+        ctrl.setCellLayout(cellId, { x, y, w, h })
+        return Promise.resolve()
+      })
+    },
+
+    setCellMode(bufferId, cellId, mode) {
+      return bound(bufferId, (ctrl) => {
+        requireCell(ctrl, cellId)
+        ctrl.setCellMode(cellId, mode)
+        return Promise.resolve()
+      })
+    },
+
+    setCellChartConfig(bufferId, cellId, patch) {
+      return bound(bufferId, (ctrl) => {
+        const cell = requireCell(ctrl, cellId)
+        // Merge into existing config so partial calls preserve xColumn/queries/etc.
+        const base: ChartConfig = cell.chartConfig ?? {
+          xColumn: null,
+          queries: [],
+        }
+        const next: ChartConfig = { ...base, ...patch }
+        ctrl.setCellChartConfig(cellId, next)
+        return Promise.resolve()
+      })
+    },
+
+    setCellAutoRefresh(bufferId, cellId, value) {
+      return bound(bufferId, (ctrl) => {
+        requireCell(ctrl, cellId)
+        ctrl.setCellAutoRefresh(cellId, value)
+        return Promise.resolve()
+      })
+    },
+
+    setCellChartMaximized(bufferId, cellId, value) {
+      return bound(bufferId, (ctrl) => {
+        requireCell(ctrl, cellId)
+        ctrl.setCellChartMaximized(cellId, value)
+        return Promise.resolve()
+      })
+    },
+
+    setCellMaximized(bufferId, cellId) {
+      return bound(bufferId, (ctrl) => {
+        if (cellId !== null) requireCell(ctrl, cellId)
+        ctrl.setCellMaximized(cellId)
+        return Promise.resolve()
+      })
+    },
+
+    applyNotebookState(bufferId, request) {
+      return bound(bufferId, (ctrl) => {
+        const result = ctrl.applyNotebookState(request)
+        return Promise.resolve(result)
+      })
+    },
+
+    getCellSql(bufferId, cellId) {
+      const controller = getController(bufferId)
+      const meta = getWorkspace()?.getBufferMeta(bufferId)
+      const cells = controller
+        ? controller.getCellsSnapshot()
+        : meta && (meta.kind === "active" || meta.kind === "inactive")
+          ? meta.notebookViewState.cells
+          : undefined
+      const cell = cells?.find((c) => c.id === cellId)
+      return cell ? cell.value : null
+    },
+
+    getCellType(bufferId, cellId) {
+      const controller = getController(bufferId)
+      const meta = getWorkspace()?.getBufferMeta(bufferId)
+      const cells = controller
+        ? controller.getCellsSnapshot()
+        : meta && (meta.kind === "active" || meta.kind === "inactive")
+          ? meta.notebookViewState.cells
+          : undefined
+      const cell = cells?.find((c) => c.id === cellId)
+      if (!cell) return null
+      return cell.type ?? "sql"
+    },
   }
 }
 
@@ -207,6 +728,7 @@ const tryWithRetries = async <T>(
   provider: AIProvider,
   setStatus: StatusCallback,
   abortSignal?: AbortSignal,
+  isReplaySafe?: () => boolean,
 ): Promise<T | AiAssistantAPIError> => {
   let retries = 0
   while (retries <= MAX_RETRIES) {
@@ -228,7 +750,11 @@ const tryWithRetries = async <T>(
           : "Remaining retries: " + (MAX_RETRIES - retries) + ".",
       )
       retries++
-      if (retries > MAX_RETRIES || provider.isNonRetryableError(error)) {
+      if (
+        retries > MAX_RETRIES ||
+        provider.isNonRetryableError(error) ||
+        isReplaySafe?.() === false
+      ) {
         return provider.classifyError(error, setStatus)
       }
 
@@ -308,6 +834,7 @@ export const continueConversation = async ({
   setStatus,
   abortSignal,
   streaming,
+  notebookReadSeq,
 }: {
   userMessage: string
   conversationHistory: Array<ConversationMessage>
@@ -317,6 +844,7 @@ export const continueConversation = async ({
   abortSignal?: AbortSignal
   conversationId?: ConversationId
   streaming?: StreamingCallback
+  notebookReadSeq?: number
 }): Promise<
   (GeneratedSQL | AiAssistantAPIError) & {
     compactedConversationHistory?: Array<ConversationMessage>
@@ -355,10 +883,20 @@ export const continueConversation = async ({
     }
   }
 
+  const flowToolContext: ToolExecutionContext = {
+    notebookReadSeq: notebookReadSeq ?? getUserActionSeq(),
+  }
+
   return tryWithRetries(
     async () => {
       const grantSchemaAccess = !!modelToolsClient.getTables
-      const systemPrompt = getUnifiedPrompt(grantSchemaAccess)
+      const aiPerms = settings.aiAssistantSettings
+        ? getAiPermissions(settings.aiAssistantSettings)
+        : { grantSchemaAccess: false, read: false, write: false }
+      const systemPrompt = getUnifiedPrompt(grantSchemaAccess, {
+        read: aiPerms.read,
+        write: aiPerms.write,
+      })
 
       let workingConversationHistory = conversationHistory
       let isCompacted = false
@@ -413,14 +951,14 @@ export const continueConversation = async ({
         }
       }
 
-      const tools = grantSchemaAccess ? ALL_TOOLS : DEFAULT_TOOLS
+      const tools = toolsForPermission(aiPerms, "ai")
 
       streaming?.onBeforeStream?.()
 
       const result = await provider.executeFlow({
         model: settings.model,
         config: {
-          systemInstructions: getUnifiedPrompt(grantSchemaAccess),
+          systemInstructions: systemPrompt,
           initialUserContent: userMessage,
           conversationHistory: toApiMessages(
             workingConversationHistory.filter((m) => !m.isCompacted),
@@ -431,6 +969,9 @@ export const continueConversation = async ({
         setStatus,
         abortSignal,
         streaming,
+        perms: () => readLiveAiPermissions(aiPerms),
+        validateSql: modelToolsClient.validateSqlRaw,
+        toolContext: flowToolContext,
       })
 
       if (isAiAssistantError(result)) {
@@ -449,5 +990,6 @@ export const continueConversation = async ({
     provider,
     setStatus,
     abortSignal,
+    () => !flowToolContext.notebookMutated && !flowToolContext.sqlWriteExecuted,
   )
 }
diff --git a/src/utils/copyToClipboard.ts b/src/utils/copyToClipboard.ts
index b145899c1..8a8f7f236 100644
--- a/src/utils/copyToClipboard.ts
+++ b/src/utils/copyToClipboard.ts
@@ -1,3 +1,15 @@
+export const canReadFromClipboard = (): boolean =>
+  Boolean(navigator.clipboard) && window.isSecureContext
+
+export const readFromClipboard = (): Promise<string> => {
+  if (!canReadFromClipboard()) {
+    return Promise.reject(
+      new Error("Clipboard read requires HTTPS or a secure context."),
+    )
+  }
+  return navigator.clipboard.readText()
+}
+
 export const copyToClipboard = (textToCopy: string): Promise<void> => {
   return new Promise((resolve, reject) => {
     if (navigator.clipboard && window.isSecureContext) {
diff --git a/src/utils/downloadQueryResult.ts b/src/utils/downloadQueryResult.ts
new file mode 100644
index 000000000..31c44c1fb
--- /dev/null
+++ b/src/utils/downloadQueryResult.ts
@@ -0,0 +1,48 @@
+import * as QuestDB from "./questdb"
+import { toast } from "../components"
+import { API_VERSION } from "../consts"
+
+// Streams a query's full result from the server's `/exp` endpoint into a file
+// download. Uses a hidden iframe GET so the browser session carries auth — no
+// header token needed. Shared by the console Result toolbar and notebook cells.
+export const downloadQueryResult = (
+  query: string,
+  format: "csv" | "parquet",
+): void => {
+  const url = `exp?${QuestDB.Client.encodeParams({
+    query,
+    version: API_VERSION,
+    fmt: format,
+    filename: `questdb-query-${Date.now().toString()}`,
+    ...(format === "parquet" ? { rmode: "nodelay" } : {}),
+  })}`
+
+  const iframe = document.createElement("iframe")
+  iframe.style.display = "none"
+  document.body.appendChild(iframe)
+
+  iframe.onerror = (e) => {
+    if (typeof e === "object") {
+      toast.error("An error occurred while downloading the file")
+    }
+    const error = e as string
+    toast.error(`An error occurred while downloading the file: ${error}`)
+  }
+
+  iframe.onload = () => {
+    const content = iframe.contentDocument?.body?.textContent
+    if (content) {
+      let error = "An error occurred while downloading the file"
+      try {
+        const contentJson = JSON.parse(content) as { error?: string }
+        error += `: ${contentJson.error ?? content}`
+      } catch (_) {
+        error += `: ${content}`
+      }
+      toast.error(error)
+    }
+    document.body.removeChild(iframe)
+  }
+
+  iframe.src = url
+}
diff --git a/src/utils/executeAIFlow.buildUserMessage.test.ts b/src/utils/executeAIFlow.buildUserMessage.test.ts
new file mode 100644
index 000000000..4cf602077
--- /dev/null
+++ b/src/utils/executeAIFlow.buildUserMessage.test.ts
@@ -0,0 +1,140 @@
+import { describe, it, expect } from "vitest"
+import { buildUserMessage } from "./executeAIFlow"
+import type { NotebookContextSnapshot } from "./ai/notebookSnapshot"
+import { createEmptyDigest } from "../providers/AIConversationProvider/userActionDigest"
+
+const baseChatConfig = {
+  conversationId: "conv-1",
+  settings: { model: "m", apiKey: "k" },
+  questClient: {} as never,
+  hasSchemaAccess: false,
+} as const
+
+const okSnapshot: NotebookContextSnapshot = {
+  status: "ok",
+  buffer_id: 42,
+  label: "Trades",
+  layout_mode: "list",
+  maximized_cell_id: null,
+  cells: [],
+}
+
+describe("buildUserMessage — notebook prefix injection", () => {
+  it("omits the prefix entirely when notebookContext is absent", () => {
+    const out = buildUserMessage({
+      ...baseChatConfig,
+      type: "chat",
+      userMessage: "hi",
+      conversationHistory: [],
+      isFirstMessage: false,
+    })
+    expect(out.content).toBe("hi")
+    expect(out.content).not.toContain("<notebook_context>")
+  })
+
+  it("prepends snapshot block when notebookContext.snapshot is ok", () => {
+    const out = buildUserMessage({
+      ...baseChatConfig,
+      type: "chat",
+      userMessage: "add a cell",
+      conversationHistory: [],
+      isFirstMessage: false,
+      notebookContext: { snapshot: okSnapshot },
+    })
+    expect(out.content.startsWith("<notebook_context>")).toBe(true)
+    expect(out.content).toContain("buffer_id: 42")
+    expect(out.content).toContain("add a cell")
+  })
+
+  it("prepends warning block for archived snapshot", () => {
+    const out = buildUserMessage({
+      ...baseChatConfig,
+      type: "chat",
+      userMessage: "please continue",
+      conversationHistory: [],
+      isFirstMessage: false,
+      notebookContext: {
+        snapshot: { status: "archived", buffer_id: 7, label: "Old" },
+      },
+    })
+    expect(out.content).toContain("status: archived")
+    expect(out.content).toContain("create_notebook")
+  })
+
+  it("combines snapshot + user-events digest with a single blank line gap", () => {
+    const digest = createEmptyDigest()
+    digest.added.add("a1")
+    digest.ran.set("a1", "error")
+    const out = buildUserMessage({
+      ...baseChatConfig,
+      type: "chat",
+      userMessage: "fix it",
+      conversationHistory: [],
+      isFirstMessage: false,
+      notebookContext: { snapshot: okSnapshot, digest },
+    })
+    expect(out.content).toContain("<notebook_context>")
+    expect(out.content).toContain("<user_events")
+    expect(out.content).toContain("added: [a1]")
+    expect(out.content).toContain("ran: { a1: error }")
+    expect(out.content.trimEnd().endsWith("fix it")).toBe(true)
+  })
+
+  it("applies the prefix to explain/fix/schema_explain/health_issue flows too", () => {
+    const explain = buildUserMessage({
+      ...baseChatConfig,
+      type: "explain",
+      queryText: "SELECT 1",
+      notebookContext: { snapshot: okSnapshot },
+    })
+    expect(explain.content).toContain("<notebook_context>")
+    expect(explain.content).toContain("SELECT 1")
+
+    const fix = buildUserMessage({
+      ...baseChatConfig,
+      type: "fix",
+      queryText: "SELECT broken",
+      errorMessage: "syntax",
+      notebookContext: { snapshot: okSnapshot },
+    })
+    expect(fix.content).toContain("<notebook_context>")
+    expect(fix.content).toContain("SELECT broken")
+  })
+
+  it("empty digest + null snapshot + no workspace → no prefix", () => {
+    const out = buildUserMessage({
+      ...baseChatConfig,
+      type: "chat",
+      userMessage: "hey",
+      conversationHistory: [],
+      isFirstMessage: false,
+      notebookContext: { snapshot: null, digest: createEmptyDigest() },
+    })
+    expect(out.content).toBe("hey")
+  })
+
+  it("injects <workspace> alone for unbound chats with notebook tabs", () => {
+    const out = buildUserMessage({
+      ...baseChatConfig,
+      type: "chat",
+      userMessage: "go to Notebook 1 and add a cell",
+      conversationHistory: [],
+      isFirstMessage: false,
+      notebookContext: {
+        snapshot: null,
+        workspace: {
+          notebooks: [
+            { buffer_id: 2, label: "Notebook 1", archived: false },
+            { buffer_id: 7, label: "Archived one", archived: true },
+          ],
+          active: { buffer_id: 3, label: "Query 1", kind: "sql" },
+        },
+      },
+    })
+    expect(out.content).toContain("<workspace>")
+    // Unbound chats learn notebook labels via <workspace> without <notebook_context>.
+    expect(out.content).not.toContain("<notebook_context>")
+    expect(out.content).toContain('label: "Notebook 1"')
+    expect(out.content).toContain("go to Notebook 1")
+  })
+})
diff --git a/src/utils/executeAIFlow.ts b/src/utils/executeAIFlow.ts
index 579d61b55..7adde265e 100644
--- a/src/utils/executeAIFlow.ts
+++ b/src/utils/executeAIFlow.ts
@@ -6,7 +6,12 @@ import type {
   UserMessageDisplayType,
   SchemaDisplayData,
   HealthIssueDisplayData,
+  UserActionDigest,
 } from "../providers/AIConversationProvider/types"
+import {
+  formatNotebookContextPrefix,
+  type NotebookContextSnapshot,
+} from "./ai/notebookSnapshot"
 import type {
   OperationHistory,
   StatusArgs,
@@ -31,6 +36,28 @@ import { EventType } from "../modules/EventBus/types"
 import { trackEvent } from "../modules/ConsoleEventTracker"
 import { ConsoleEvent } from "../modules/ConsoleEventTracker/events"
 
+// Prepended onto every user turn. buffer_id is internal — the AI must never surface it to the user.
+export type NotebookFlowContext = {
+  snapshot: NotebookContextSnapshot | null
+  digest?: UserActionDigest
+  workspace?: WorkspaceInfo
+  readSeq?: number
+}
+
+export type WorkspaceInfo = {
+  notebooks: Array<{
+    buffer_id: number
+    label: string
+    archived: boolean
+    bound_to_this_chat?: boolean
+  }>
+  active?: {
+    buffer_id: number
+    label: string
+    kind: "notebook" | "sql" | "metrics" | "other"
+  }
+}
+
 type BaseFlowConfig = {
   conversationId: ConversationId
   settings: {
@@ -43,6 +70,8 @@ type BaseFlowConfig = {
   hasSchemaAccess: boolean
   abortSignal?: AbortSignal
   useLastMessage?: boolean
+  // Set only when the conversation has a notebookBufferId; absent keeps non-notebook flows unchanged.
+  notebookContext?: NotebookFlowContext
 }
 
 type ChatFlowConfig = BaseFlowConfig & {
@@ -131,6 +160,11 @@ export type AIFlowCallbacks = {
     lastUserMessage?: ConversationMessage
     lastAssistantMessage?: ConversationMessage
   }>
+  bindConversationToNotebook?: (
+    conversationId: ConversationId,
+    bufferId: number,
+  ) => Promise<void>
+  rotateUserActionDigest?: (conversationId: ConversationId) => void
 }
 
 export type AIFlowResult = {
@@ -182,7 +216,19 @@ function cleanupOrphanedToolCallsForTurn(params: {
   }
 }
 
-function buildUserMessage(config: AIFlowConfig): AIFlowUserMessage {
+export function buildUserMessage(config: AIFlowConfig): AIFlowUserMessage {
+  const prefix = formatNotebookContextPrefix(
+    config.notebookContext?.snapshot ?? null,
+    config.notebookContext?.digest,
+    config.notebookContext?.workspace,
+  )
+
+  const msg = buildFlowSpecificUserMessage(config)
+  if (!prefix) return msg
+  return { ...msg, content: `${prefix}${msg.content}` }
+}
+
+function buildFlowSpecificUserMessage(config: AIFlowConfig): AIFlowUserMessage {
   switch (config.type) {
     case "chat": {
       const { userMessage, currentSQL, isFirstMessage } = config
@@ -196,7 +242,8 @@ function buildUserMessage(config: AIFlowConfig): AIFlowUserMessage {
         }
       }
 
-      return { content: userMessage }
+      // displayUserMessage preserves the raw user input so prefix tags don't leak into chat bubbles.
+      return { content: userMessage, displayUserMessage: userMessage }
     }
 
     case "explain":
@@ -384,6 +431,8 @@ export async function executeAIFlow(
 
   const userMsg = buildUserMessage(config)
 
+  callbacks.rotateUserActionDigest?.(conversationId)
+
   if (useLastMessage && callbacks.getLastRoundMessages) {
     const { lastUserMessage, lastAssistantMessage } =
       await callbacks.getLastRoundMessages(conversationId)
@@ -455,9 +504,16 @@ export async function executeAIFlow(
     aiAssistantSettings: config.aiAssistantSettings,
   }
 
+  // Threads conversationId + bind callback so an AI-initiated notebook auto-binds an unbound chat.
+  // abortSignal lets a pending registration wait reject the moment the user presses Abort.
   const modelToolsClient = createModelToolsClient(
     questClient,
     hasSchemaAccess ? tables : undefined,
+    {
+      conversationId,
+      bindNotebook: callbacks.bindConversationToNotebook,
+      abortSignal,
+    },
   )
 
   let latestOperationHistory: OperationHistory = []
@@ -727,6 +783,7 @@ export async function executeAIFlow(
       setStatus: setStatusWithHistoryAndResetFlags,
       abortSignal,
       streaming: streamingCallback,
+      notebookReadSeq: config.notebookContext?.readSeq,
     })
 
     const flowResult = processResult({
diff --git a/src/utils/formatSql.ts b/src/utils/formatSql.ts
index dbbcd0d6c..9c84df5fa 100644
--- a/src/utils/formatSql.ts
+++ b/src/utils/formatSql.ts
@@ -6,3 +6,12 @@ export const formatSql = (statement: string, options?: FormatOptions) => {
     ...options,
   })
 }
+
+export const normalizeSql = (sql: string, insertSemicolon: boolean = true) => {
+  if (!sql) return ""
+  let result = sql.trim()
+  if (result.endsWith(";")) {
+    result = result.slice(0, -1)
+  }
+  return formatSql(result) + (insertSemicolon ? ";" : "")
+}
diff --git a/src/utils/mcp/MCPBridgeClient.test.ts b/src/utils/mcp/MCPBridgeClient.test.ts
new file mode 100644
index 000000000..3b309c40f
--- /dev/null
+++ b/src/utils/mcp/MCPBridgeClient.test.ts
@@ -0,0 +1,405 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { MCPBridgeClient } from "./MCPBridgeClient"
+import { EXPECTED_BRIDGE_VERSION } from "./protocolVersion"
+import { WS_CLOSE_CODES, type HelloMessage, type ToolSchema } from "./types"
+
+class FakeWebSocket {
+  static OPEN_CONSTANT = 1
+  readyState = 0
+  sent: string[] = []
+  url: string
+  private listeners: Record<string, Set<(ev: unknown) => void>> = {}
+  static get OPEN() {
+    return FakeWebSocket.OPEN_CONSTANT
+  }
+  constructor(url: string) {
+    this.url = url
+  }
+  addEventListener(type: string, listener: (ev: unknown) => void) {
+    let bag = this.listeners[type]
+    if (!bag) {
+      bag = new Set()
+      this.listeners[type] = bag
+    }
+    bag.add(listener)
+  }
+  send(data: string) {
+    if (this.readyState !== FakeWebSocket.OPEN_CONSTANT) {
+      throw new Error("send while not open")
+    }
+    this.sent.push(data)
+  }
+  close(_code?: number, _reason?: string) {
+    this.lastCloseArgs = { code: _code, reason: _reason }
+    if (this.readyState === 3) return
+    this.readyState = 3
+    this.dispatch("close", { code: _code ?? 1006, reason: _reason ?? "" })
+  }
+  open() {
+    this.readyState = FakeWebSocket.OPEN_CONSTANT
+    this.dispatch("open", {})
+  }
+  receive(payload: unknown) {
+    this.dispatch("message", { data: JSON.stringify(payload) })
+  }
+  dropFromServer(code: number = 1006, reason: string = "") {
+    this.readyState = 3
+    this.dispatch("close", { code, reason })
+  }
+  // Lets tests assert the close() code chosen (e.g. JS-legal 4005 vs the
+  // spec-forbidden 1006).
+  lastCloseArgs: { code?: number; reason?: string } | null = null
+  private dispatch(type: string, ev: unknown) {
+    const bag = this.listeners[type]
+    if (!bag) return
+    for (const fn of Array.from(bag)) fn(ev)
+  }
+}
+
+beforeEach(() => {
+  ;(globalThis as unknown as { WebSocket: typeof FakeWebSocket }).WebSocket =
+    FakeWebSocket as unknown as typeof FakeWebSocket
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+const tools: ToolSchema[] = [
+  { name: "add_cell", description: "x", inputSchema: { type: "object" } },
+]
+
+const makeClient = () => {
+  let lastSocket: FakeWebSocket | null = null
+  const client = new MCPBridgeClient({
+    url: "ws://127.0.0.1:57123?token=t",
+    token: "t",
+    tools,
+    consoleOrigin: "http://127.0.0.1:9000",
+    permissions: { grantSchemaAccess: true, read: true, write: true },
+    websocketFactory: (u) => {
+      lastSocket = new FakeWebSocket(u)
+      return lastSocket as unknown as WebSocket
+    },
+  })
+  return {
+    client,
+    socket: () => {
+      if (!lastSocket) throw new Error("socket not yet created")
+      return lastSocket
+    },
+  }
+}
+
+const handshake = (
+  client: MCPBridgeClient,
+  socket: FakeWebSocket,
+  sessionId = "s1",
+) => {
+  socket.open()
+  socket.receive({
+    v: EXPECTED_BRIDGE_VERSION,
+    type: "hello_ack",
+    sessionId,
+    heartbeatIntervalMs: 5_000,
+    seenToolCount: 1,
+  })
+  return client
+}
+
+describe("MCPBridgeClient", () => {
+  it("sends hello on open and flips to connected on hello_ack", () => {
+    const { client, socket } = makeClient()
+    const statuses: string[] = []
+    client.on("status", (s) => statuses.push(s))
+    client.connect()
+    expect(client.status).toBe("connecting")
+    socket().open()
+    expect(socket().sent.length).toBe(1)
+    const hello = JSON.parse(socket().sent[0]) as HelloMessage
+    expect(hello.type).toBe("hello")
+    expect(hello.token).toBe("t")
+    expect(hello.tools.length).toBe(1)
+    expect(client.status).toBe("connecting")
+    socket().receive({
+      v: EXPECTED_BRIDGE_VERSION,
+      type: "hello_ack",
+      sessionId: "s-1",
+      heartbeatIntervalMs: 5_000,
+      resumed: false,
+      seenToolCount: 1,
+    })
+    expect(client.status).toBe("connected")
+    expect(statuses).toContain("connected")
+  })
+
+  it("emits toolCall events from incoming messages", () => {
+    const { client, socket } = makeClient()
+    const calls: string[] = []
+    client.on("toolCall", (m) => calls.push(m.name))
+    client.connect()
+    handshake(client, socket())
+    socket().receive({
+      v: EXPECTED_BRIDGE_VERSION,
+      type: "tool_call",
+      requestId: "r1",
+      name: "add_cell",
+      arguments: { value: "x" },
+      deadlineMs: 15000,
+    })
+    expect(calls).toEqual(["add_cell"])
+  })
+
+  it("responds to ping with matching pong", () => {
+    const { client, socket } = makeClient()
+    client.connect()
+    handshake(client, socket())
+    socket().sent.length = 0
+    socket().receive({
+      v: EXPECTED_BRIDGE_VERSION,
+      type: "ping",
+      nonce: "abc",
+    })
+    expect(socket().sent.length).toBe(1)
+    const pong = JSON.parse(socket().sent[0]) as Record<string, unknown>
+    expect(pong).toMatchObject({ type: "pong", nonce: "abc" })
+  })
+
+  it("ignores unknown message types (forward-compat)", () => {
+    const { client, socket } = makeClient()
+    client.connect()
+    handshake(client, socket())
+    expect(() =>
+      socket().receive({
+        v: EXPECTED_BRIDGE_VERSION,
+        type: "future_unknown_message",
+        payload: { whatever: 1 },
+      }),
+    ).not.toThrow()
+    expect(client.status).toBe("connected")
+  })
+
+  it("accepts incoming frames regardless of `v` (major-mismatch handled via close 4004, not per-frame filtering)", () => {
+    // `v` carries the bridge semver; same-major drift is tolerated. True
+    // major mismatch hard-rejects at hello time via close code 4004.
+    const { client, socket } = makeClient()
+    const calls: string[] = []
+    client.on("toolCall", (m) => calls.push(m.name))
+    client.connect()
+    handshake(client, socket())
+    socket().receive({
+      v: "0.99.0",
+      type: "tool_call",
+      requestId: "r1",
+      name: "add_cell",
+      arguments: {},
+      deadlineMs: 15_000,
+    })
+    expect(calls).toEqual(["add_cell"])
+  })
+
+  it("queues tool_result while disconnected and flushes on reconnect", () => {
+    vi.useFakeTimers()
+    const { client, socket } = makeClient()
+    client.connect()
+    handshake(client, socket(), "session-A")
+    socket().dropFromServer()
+    expect(client.status).toBe("reconnecting")
+    client.sendToolResult({
+      v: EXPECTED_BRIDGE_VERSION,
+      type: "tool_result",
+      requestId: "r1",
+      content: [{ type: "text", text: "{}" }],
+      isError: false,
+    })
+    vi.advanceTimersByTime(5000)
+    // `socket()` returns the *latest* socket — the reconnect just created a
+    // new one, so this is NOT the original socket from before the drop.
+    handshake(client, socket(), "session-A")
+    const sentTypes = socket().sent.map(
+      (s) => (JSON.parse(s) as { type: string }).type,
+    )
+    expect(sentTypes).toContain("hello")
+    expect(sentTypes).toContain("tool_result")
+  })
+
+  it("carries lastSessionId on reconnect so the bridge takes over rather than rejecting", () => {
+    vi.useFakeTimers()
+    const { client, socket } = makeClient()
+    client.connect()
+    handshake(client, socket(), "session-A")
+    const firstConnectUrl = socket().url
+
+    socket().dropFromServer()
+    vi.advanceTimersByTime(5000)
+    // `socket()` is now the reconnect's fresh socket; its URL is fixed at construction.
+    const reconnectUrl = socket().url
+
+    expect(firstConnectUrl).not.toContain("lastSessionId")
+    expect(reconnectUrl).toContain("lastSessionId=session-A")
+  })
+
+  it("disconnect() closes the WS without sending a close frame", () => {
+    const { client, socket } = makeClient()
+    client.connect()
+    handshake(client, socket())
+    socket().sent.length = 0
+    client.disconnect("user_disconnect")
+    expect(client.status).toBe("disconnected")
+    // No JSON close frame sent — the WS close itself is the signal.
+    expect(socket().sent.length).toBe(0)
+  })
+
+  it("does not auto-reconnect after explicit disconnect()", () => {
+    vi.useFakeTimers()
+    const { client, socket } = makeClient()
+    client.connect()
+    handshake(client, socket())
+    client.disconnect("user_disconnect")
+    vi.advanceTimersByTime(60_000)
+    expect(client.status).toBe("disconnected")
+  })
+
+  it("schedules reconnect on close at the constant interval", () => {
+    vi.useFakeTimers()
+    const { client, socket } = makeClient()
+    client.connect()
+    handshake(client, socket())
+    socket().dropFromServer()
+    expect(client.status).toBe("reconnecting")
+    vi.advanceTimersByTime(5000)
+    expect(client.status).toBe("reconnecting")
+  })
+
+  it("emits latency on pong", () => {
+    vi.useFakeTimers()
+    const { client, socket } = makeClient()
+    const seen: number[] = []
+    client.on("latency", (ms) => seen.push(ms))
+    client.connect()
+    handshake(client, socket())
+    vi.advanceTimersByTime(5_000)
+    const ping = JSON.parse(socket().sent[socket().sent.length - 1]) as {
+      type: string
+      nonce: string
+    }
+    expect(ping.type).toBe("ping")
+    socket().receive({
+      v: EXPECTED_BRIDGE_VERSION,
+      type: "pong",
+      nonce: ping.nonce,
+    })
+    expect(seen.length).toBe(1)
+    expect(seen[0]).toBeGreaterThanOrEqual(0)
+  })
+
+  it("gives up after MAX consecutive failed reconnects (status → disconnected)", () => {
+    vi.useFakeTimers()
+    const { client, socket } = makeClient()
+    client.connect()
+    handshake(client, socket())
+    socket().dropFromServer()
+    expect(client.status).toBe("reconnecting")
+    for (let i = 0; i < 25; i++) {
+      vi.advanceTimersByTime(4_000)
+      try {
+        socket().dropFromServer()
+      } catch {
+        // No new socket created — we've given up.
+      }
+    }
+    expect(client.status).toBe("disconnected")
+  })
+
+  it("a successful helloAck resets the give-up counter", () => {
+    vi.useFakeTimers()
+    const { client, socket } = makeClient()
+    client.connect()
+    handshake(client, socket())
+    for (let i = 0; i < 5; i++) {
+      socket().dropFromServer()
+      vi.advanceTimersByTime(4_000)
+    }
+    expect(client.status).toBe("reconnecting")
+    handshake(client, socket())
+    expect(client.status).toBe("connected")
+    // Should NOT immediately give up — counter reset by the helloAck, so we
+    // have a full budget again.
+    socket().dropFromServer()
+    expect(client.status).toBe("reconnecting")
+  })
+
+  // Bridge-originated terminal close codes must NOT enter the reconnect
+  // loop — reconnecting hits the same wall. Stop retrying and surface a
+  // typed `error` so the UI can distinguish them from "bridge is dead".
+  describe("terminal bridge close codes", () => {
+    const cases: Array<{
+      code: number
+      label: string
+      expectInMessage: string
+    }> = [
+      {
+        code: WS_CLOSE_CODES.superseded,
+        label: "superseded (4001)",
+        expectInMessage: "Another browser tab is paired",
+      },
+      {
+        code: WS_CLOSE_CODES.token_invalid,
+        label: "token_invalid (4002)",
+        expectInMessage: "token is no longer valid",
+      },
+      {
+        code: WS_CLOSE_CODES.major_version_mismatch,
+        label: "major_version_mismatch (4004)",
+        expectInMessage: "Bridge major version doesn't match",
+      },
+    ]
+    for (const { code, label, expectInMessage } of cases) {
+      it(`stops retrying and emits error on ${label}`, () => {
+        vi.useFakeTimers()
+        const { client, socket } = makeClient()
+        const errors: Error[] = []
+        client.on("error", (e) => errors.push(e))
+        client.connect()
+        handshake(client, socket())
+        socket().dropFromServer(code)
+        expect(client.status).toBe("disconnected")
+        expect(errors.length).toBe(1)
+        expect(errors[0].message).toContain(expectInMessage)
+        // No scheduled retry: advancing the clock must not flip status.
+        vi.advanceTimersByTime(60_000)
+        expect(client.status).toBe("disconnected")
+      })
+    }
+
+    it("transient close (1006) still reconnects — only bridge-terminal codes opt out", () => {
+      vi.useFakeTimers()
+      const { client, socket } = makeClient()
+      client.connect()
+      handshake(client, socket())
+      socket().dropFromServer(1006)
+      expect(client.status).toBe("reconnecting")
+    })
+  })
+
+  it("pong-timeout closes the WS with a JS-legal app-range code (4005), not 1006", () => {
+    // Browsers only permit close codes 1000 or 3000-4999 from JS — passing
+    // 1006 throws InvalidAccessError, the WS stays OPEN, and the loop hangs
+    // until the bridge's own pong-timeout fires (~10s delay).
+    vi.useFakeTimers()
+    const { client, socket } = makeClient()
+    client.connect()
+    // Pin the original socket: scheduleReconnect creates a replacement and
+    // `socket()` would then return the new one.
+    const original = socket()
+    handshake(client, original)
+    vi.advanceTimersByTime(5_000)
+    const lastSent = original.sent[original.sent.length - 1]
+    expect((JSON.parse(lastSent) as { type: string }).type).toBe("ping")
+    vi.advanceTimersByTime(5_000)
+    expect(original.lastCloseArgs?.code).toBe(WS_CLOSE_CODES.protocol_violation)
+    expect(original.lastCloseArgs?.reason).toBe("pong_timeout")
+    // NOT 1006 — the spec-forbidden code that used to throw and no-op.
+    expect(original.lastCloseArgs?.code).not.toBe(1006)
+  })
+})
diff --git a/src/utils/mcp/MCPBridgeClient.ts b/src/utils/mcp/MCPBridgeClient.ts
new file mode 100644
index 000000000..81cb52f4d
--- /dev/null
+++ b/src/utils/mcp/MCPBridgeClient.ts
@@ -0,0 +1,496 @@
+import { EXPECTED_BRIDGE_VERSION } from "./protocolVersion"
+import type { Permissions } from "../tools/permissions"
+import {
+  WS_CLOSE_CODES,
+  type AnyMessage,
+  type CancelMessage,
+  type CloseReason,
+  type HelloAckMessage,
+  type HelloMessage,
+  type PingMessage,
+  type PongMessage,
+  type ToolCallMessage,
+  type ToolResultMessage,
+  type ToolSchema,
+} from "./types"
+
+// These close codes will never resolve without user action — reconnecting
+// just burns retries.
+const TERMINAL_BRIDGE_CLOSE_CODES = new Set<number>([
+  WS_CLOSE_CODES.superseded,
+  WS_CLOSE_CODES.token_invalid,
+  WS_CLOSE_CODES.major_version_mismatch,
+])
+
+const terminalCloseMessage = (code: number, reason: string): string => {
+  if (code === WS_CLOSE_CODES.superseded) {
+    return "Another browser tab is paired with this bridge. Disconnect the other tab or pair this one via a fresh link."
+  }
+  if (code === WS_CLOSE_CODES.token_invalid) {
+    return "Pairing token is no longer valid — the bridge likely restarted. Re-pair via a fresh deep link."
+  }
+  if (code === WS_CLOSE_CODES.major_version_mismatch) {
+    return (
+      `Bridge major version doesn't match what this console expects (${EXPECTED_BRIDGE_VERSION}). ` +
+      `Install a compatible bridge release, or update the console.`
+    )
+  }
+  return reason || `Bridge closed with code ${code}.`
+}
+
+export type MCPBridgeClientStatus =
+  | "disconnected"
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+
+type Listener<T> = (payload: T) => void
+
+type EventMap = {
+  status: MCPBridgeClientStatus
+  toolCall: ToolCallMessage
+  cancel: CancelMessage
+  helloAck: HelloAckMessage
+  latency: number
+  error: Error
+  retryAttempt: number
+}
+
+const HEARTBEAT_INTERVAL_MS = 5_000
+const PONG_TIMEOUT_MS = 10_000
+const RECONNECT_INTERVAL_MS = 3_000
+const JITTER = 0.25
+// Ephemeral bridge model (fresh port + token per Claude Code restart): a
+// vanished bridge can't return at the same URL, so longer retries just lie
+// via the status pill.
+export const MAX_RECONNECT_ATTEMPTS = 5
+
+const MAX_CONSECUTIVE_FAILED_ATTEMPTS = MAX_RECONNECT_ATTEMPTS
+
+const monotonicNow = (): number =>
+  typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now()
+
+const jittered = (base: number): number => {
+  const delta = base * JITTER
+  return Math.round(base + (Math.random() * 2 - 1) * delta)
+}
+
+const randomNonce = (): string => {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+    return crypto.randomUUID()
+  }
+  return Math.random().toString(36).slice(2)
+}
+
+export type MCPBridgeClientOptions = {
+  url: string
+  token: string
+  tools: ToolSchema[]
+  consoleOrigin: string
+  // Mutable post-connect via `setPermissions` so silent reconnects still
+  // announce the latest values to the bridge in the next hello.
+  permissions: Permissions
+  lastSessionId?: string
+  // Test seam — defaults to global WebSocket. Lets unit tests inject a fake.
+  websocketFactory?: (url: string) => WebSocket
+}
+
+export class MCPBridgeClient {
+  private readonly opts: MCPBridgeClientOptions
+  private permissions: Permissions
+  private sessionId: string | null
+  private ws: WebSocket | null = null
+  private _status: MCPBridgeClientStatus = "disconnected"
+  private _latencyMs: number | null = null
+  private listeners = new Map<
+    keyof EventMap,
+    Set<Listener<EventMap[keyof EventMap]>>
+  >()
+  private pendingResults: ToolResultMessage[] = []
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null
+  private pongTimer: ReturnType<typeof setTimeout> | null = null
+  private outstandingPing: { nonce: string; sentAt: number } | null = null
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private explicitlyClosed = false
+  private _consecutiveFailedAttempts = 0
+  private get consecutiveFailedAttempts(): number {
+    return this._consecutiveFailedAttempts
+  }
+  // Setter so every mutation also fires retryAttempt without a separate emit call.
+  private set consecutiveFailedAttempts(next: number) {
+    if (this._consecutiveFailedAttempts === next) return
+    this._consecutiveFailedAttempts = next
+    this.emit("retryAttempt", next)
+  }
+  private onVisibilityChange: (() => void) | null = null
+
+  constructor(opts: MCPBridgeClientOptions) {
+    this.opts = opts
+    this.permissions = opts.permissions
+    this.sessionId = opts.lastSessionId ?? null
+  }
+
+  // No push over the open WS — bridge sees changes on the next hello frame;
+  // runtime informing rides the dispatcher dirty notice.
+  setPermissions(next: Permissions): void {
+    this.permissions = next
+  }
+
+  get status(): MCPBridgeClientStatus {
+    return this._status
+  }
+
+  get latencyMs(): number | null {
+    return this._latencyMs
+  }
+
+  on<K extends keyof EventMap>(
+    event: K,
+    handler: Listener<EventMap[K]>,
+  ): () => void {
+    let bag = this.listeners.get(event)
+    if (!bag) {
+      bag = new Set()
+      this.listeners.set(event, bag)
+    }
+    bag.add(handler as Listener<EventMap[keyof EventMap]>)
+    return () => bag?.delete(handler as Listener<EventMap[keyof EventMap]>)
+  }
+
+  private emit<K extends keyof EventMap>(event: K, payload: EventMap[K]): void {
+    const bag = this.listeners.get(event)
+    if (!bag) return
+    for (const fn of Array.from(bag)) {
+      try {
+        ;(fn as Listener<EventMap[K]>)(payload)
+      } catch {
+        // One bad handler must not break the others.
+      }
+    }
+  }
+
+  private setStatus(next: MCPBridgeClientStatus): void {
+    if (this._status === next) return
+    this._status = next
+    this.emit("status", next)
+  }
+
+  connect(): void {
+    this.explicitlyClosed = false
+    this.attachVisibilityListener()
+    this.openSocket()
+  }
+
+  disconnect(reason: CloseReason = "user_disconnect"): void {
+    this.explicitlyClosed = true
+    this.cancelReconnect()
+    this.stopHeartbeat()
+    this.detachVisibilityListener()
+    if (this.ws && this.ws.readyState <= WebSocket.OPEN) {
+      try {
+        this.ws.close(1000, reason)
+      } catch {
+        // Some envs throw on double-close.
+      }
+    }
+    this.ws = null
+    this.pendingResults = []
+    this.setStatus("disconnected")
+  }
+
+  sendToolResult(msg: ToolResultMessage): void {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.send(msg)
+      return
+    }
+    this.pendingResults.push(msg)
+  }
+
+  private buildSocketUrl(): string {
+    // The bridge reads both params at the WS upgrade, before any hello: the
+    // token to authorize, and lastSessionId to take over the stale socket of a
+    // reconnect instead of rejecting it as a second console.
+    const base = this.opts.url
+    const params = new URLSearchParams({ token: this.opts.token })
+    if (this.sessionId !== null) {
+      params.set("lastSessionId", this.sessionId)
+    }
+    const sep = base.includes("?") ? "&" : "?"
+    return `${base}${sep}${params.toString()}`
+  }
+
+  private openSocket(): void {
+    if (this.ws && this.ws.readyState <= WebSocket.OPEN) return
+    this.setStatus(
+      this._status === "reconnecting" ? "reconnecting" : "connecting",
+    )
+    // Never log the URL — the query string carries the auth token.
+    const fullUrl = this.buildSocketUrl()
+    const factory =
+      this.opts.websocketFactory ?? ((u: string) => new WebSocket(u))
+    let socket: WebSocket
+    try {
+      socket = factory(fullUrl)
+    } catch (err) {
+      console.error("[MCPBridgeClient] WebSocket constructor threw:", err)
+      this.emit(
+        "error",
+        err instanceof Error ? err : new Error("WebSocket constructor failed"),
+      )
+      this.scheduleReconnect()
+      return
+    }
+    this.ws = socket
+    socket.addEventListener("open", this.onOpen)
+    socket.addEventListener("message", this.onMessage)
+    socket.addEventListener("close", this.onClose)
+    socket.addEventListener("error", this.onError)
+  }
+
+  private onOpen = (): void => {
+    // Never log the token, not even a prefix — 4 bytes is enough to
+    // confirm an exfiltrated token if a leak appears elsewhere.
+    const hello: HelloMessage = {
+      v: EXPECTED_BRIDGE_VERSION,
+      type: "hello",
+      token: this.opts.token,
+      userAgent:
+        typeof navigator !== "undefined" ? navigator.userAgent : "node",
+      expectedBridgeVersion: EXPECTED_BRIDGE_VERSION,
+      consoleOrigin: this.opts.consoleOrigin,
+      tools: this.opts.tools,
+      permissions: this.permissions,
+    }
+    this.send(hello)
+    // Stay in `connecting`/`reconnecting` until the bridge acks — consumers
+    // must not treat the session as usable before hello_ack.
+  }
+
+  private onMessage = (ev: MessageEvent): void => {
+    let parsed: AnyMessage
+    try {
+      parsed =
+        typeof ev.data === "string"
+          ? (JSON.parse(ev.data) as AnyMessage)
+          : (JSON.parse(String(ev.data)) as AnyMessage)
+    } catch {
+      // Forward-compat: tolerate malformed frames; let the bridge close us
+      // with `protocol_violation` if it cares.
+      return
+    }
+    if (typeof parsed !== "object" || parsed === null) return
+    // No strict `v` equality: `v` carries bridge semver; same-major drift
+    // is tolerated, major mismatches arrive as close code 4004.
+    switch (parsed.type) {
+      case "hello_ack":
+        this.handleHelloAck(parsed)
+        return
+      case "tool_call":
+        this.emit("toolCall", parsed)
+        return
+      case "cancel":
+        this.emit("cancel", parsed)
+        return
+      case "ping":
+        this.send({
+          v: EXPECTED_BRIDGE_VERSION,
+          type: "pong",
+          nonce: parsed.nonce,
+        } satisfies PongMessage)
+        return
+      case "pong":
+        this.handlePong(parsed)
+        return
+      default:
+        return
+    }
+  }
+
+  private onClose = (ev?: unknown): void => {
+    const code = (ev as { code?: number } | undefined)?.code ?? 0
+    const reason = (ev as { reason?: string } | undefined)?.reason ?? ""
+    // eslint-disable-next-line no-console
+    console.log("[MCPBridgeClient] WS close event:", {
+      code,
+      reason,
+      wasClean: (ev as { wasClean?: boolean } | undefined)?.wasClean,
+    })
+    this.stopHeartbeat()
+    this.ws = null
+    if (this.explicitlyClosed) {
+      this.setStatus("disconnected")
+      return
+    }
+    // Stop retrying and mark explicitlyClosed so the visibility listener
+    // doesn't resurrect the loop on tab focus — only a fresh deep-link
+    // re-pair can recover from these codes.
+    if (TERMINAL_BRIDGE_CLOSE_CODES.has(code)) {
+      this.cancelReconnect()
+      this.explicitlyClosed = true
+      this.emit("error", new Error(terminalCloseMessage(code, reason)))
+      this.setStatus("disconnected")
+      return
+    }
+    this.scheduleReconnect()
+  }
+
+  private onError = (ev?: unknown): void => {
+    console.error("[MCPBridgeClient] WS error event:", ev)
+    // Detail surfaces via the close event that follows.
+  }
+
+  private handleHelloAck(msg: HelloAckMessage): void {
+    this.sessionId = msg.sessionId
+    this.consecutiveFailedAttempts = 0
+    this.setStatus("connected")
+    this.emit("helloAck", msg)
+    if (this.pendingResults.length > 0) {
+      const flushing = this.pendingResults
+      this.pendingResults = []
+      for (const m of flushing) this.send(m)
+    }
+    this.startHeartbeat(msg.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS)
+  }
+
+  private handlePong(msg: PongMessage): void {
+    if (!this.outstandingPing || this.outstandingPing.nonce !== msg.nonce) {
+      return
+    }
+    const rtt = monotonicNow() - this.outstandingPing.sentAt
+    this._latencyMs = rtt
+    this.emit("latency", rtt)
+    this.outstandingPing = null
+    if (this.pongTimer) {
+      clearTimeout(this.pongTimer)
+      this.pongTimer = null
+    }
+  }
+
+  private startHeartbeat(intervalMs: number): void {
+    this.stopHeartbeat()
+    this.heartbeatTimer = setInterval(() => this.sendPing(), intervalMs)
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer)
+      this.heartbeatTimer = null
+    }
+    if (this.pongTimer) {
+      clearTimeout(this.pongTimer)
+      this.pongTimer = null
+    }
+    this.outstandingPing = null
+  }
+
+  private sendPing(): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return
+    if (this.outstandingPing) {
+      // Previous pong never came; force-terminate to fall into reconnect.
+      this.terminateAndReconnect()
+      return
+    }
+    const nonce = randomNonce()
+    const sentAt = monotonicNow()
+    this.outstandingPing = { nonce, sentAt }
+    this.send({
+      v: EXPECTED_BRIDGE_VERSION,
+      type: "ping",
+      nonce,
+    } satisfies PingMessage)
+    this.pongTimer = setTimeout(() => {
+      this.terminateAndReconnect()
+    }, PONG_TIMEOUT_MS)
+  }
+
+  private terminateAndReconnect(): void {
+    if (!this.ws) return
+    try {
+      // Browsers reject close codes outside 1000 and 3000-4999 with
+      // InvalidAccessError, leaving the WS OPEN and looping until the
+      // peer's pong-timeout fires. 4005 (protocol_violation) is in range.
+      this.ws.close(WS_CLOSE_CODES.protocol_violation, "pong_timeout")
+    } catch {
+      // close handler will still run.
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.explicitlyClosed) return
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
+    this.consecutiveFailedAttempts += 1
+    if (this.consecutiveFailedAttempts > MAX_CONSECUTIVE_FAILED_ATTEMPTS) {
+      this.setStatus("disconnected")
+      return
+    }
+    this.setStatus("reconnecting")
+    const delay = jittered(RECONNECT_INTERVAL_MS)
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null
+      this.openSocket()
+    }, delay)
+  }
+
+  private cancelReconnect(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+    this.consecutiveFailedAttempts = 0
+  }
+
+  // Background tabs throttle setInterval/setTimeout, so foregrounding
+  // the tab triggers an immediate retry instead of waiting up to several
+  // seconds for the scheduled one.
+  private attachVisibilityListener(): void {
+    if (typeof document === "undefined" || this.onVisibilityChange) return
+    const handler = (): void => {
+      if (document.visibilityState !== "visible") return
+      if (this.explicitlyClosed) return
+      if (this._status === "connected" || this._status === "connecting") return
+      // Don't resurrect a gave-up session on tab focus — the user must
+      // click "Try again" to opt back in.
+      if (this.consecutiveFailedAttempts > MAX_CONSECUTIVE_FAILED_ATTEMPTS) {
+        return
+      }
+      if (this.reconnectTimer) {
+        clearTimeout(this.reconnectTimer)
+        this.reconnectTimer = null
+      }
+      // Wake-from-sleep deserves a fresh retry budget.
+      this.consecutiveFailedAttempts = 0
+      this.openSocket()
+    }
+    document.addEventListener("visibilitychange", handler)
+    this.onVisibilityChange = handler
+  }
+
+  private detachVisibilityListener(): void {
+    if (typeof document === "undefined" || !this.onVisibilityChange) return
+    document.removeEventListener("visibilitychange", this.onVisibilityChange)
+    this.onVisibilityChange = null
+  }
+
+  private send(msg: AnyMessage): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      console.warn(
+        "[MCPBridgeClient] send dropped — ws not OPEN, type =",
+        msg.type,
+        "readyState =",
+        this.ws?.readyState,
+      )
+      return
+    }
+    try {
+      this.ws.send(JSON.stringify(msg))
+    } catch (err) {
+      console.error("[MCPBridgeClient] send threw:", err)
+      this.emit(
+        "error",
+        err instanceof Error ? err : new Error("WebSocket send failed"),
+      )
+    }
+  }
+}
diff --git a/src/utils/mcp/consumePendingPair.test.ts b/src/utils/mcp/consumePendingPair.test.ts
new file mode 100644
index 000000000..fd69f8308
--- /dev/null
+++ b/src/utils/mcp/consumePendingPair.test.ts
@@ -0,0 +1,114 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { consumePendingPairFromUrl } from "./consumePendingPair"
+import { readPendingPair } from "./mcpBridgeStorage"
+
+const makeStub = () => {
+  const store = new Map<string, string>()
+  return {
+    getItem: (k: string) => store.get(k) ?? null,
+    setItem: (k: string, v: string) => {
+      store.set(k, v)
+    },
+    removeItem: (k: string) => {
+      store.delete(k)
+    },
+    clear: () => store.clear(),
+  }
+}
+
+beforeEach(() => {
+  ;(globalThis as { sessionStorage?: unknown }).sessionStorage = makeStub()
+})
+
+afterEach(() => {
+  delete (globalThis as { sessionStorage?: unknown }).sessionStorage
+})
+
+const VALID_TOKEN = "abcdefghijklmnopqrst1234"
+
+describe("consumePendingPairFromUrl", () => {
+  it("returns no_params when mcp-pair is absent", () => {
+    const result = consumePendingPairFromUrl(
+      { search: "?other=foo", pathname: "/", hash: "" },
+      { replaceState: () => undefined },
+    )
+    expect(result).toEqual({ kind: "no_params" })
+  })
+
+  it("rejects when mcp-ws or mcp-token missing", () => {
+    expect(
+      consumePendingPairFromUrl(
+        { search: "?mcp-pair=1&mcp-token=t", pathname: "/", hash: "" },
+        { replaceState: () => undefined },
+      ),
+    ).toEqual({ kind: "rejected", reason: "missing_field" })
+    expect(
+      consumePendingPairFromUrl(
+        {
+          search: "?mcp-pair=1&mcp-ws=ws://127.0.0.1:1",
+          pathname: "/",
+          hash: "",
+        },
+        { replaceState: () => undefined },
+      ),
+    ).toEqual({ kind: "rejected", reason: "missing_field" })
+  })
+
+  it("rejects non-localhost mcp-ws (CSRF guard)", () => {
+    expect(
+      consumePendingPairFromUrl(
+        {
+          search: `?mcp-pair=1&mcp-ws=ws://attacker.com:443&mcp-token=${VALID_TOKEN}`,
+          pathname: "/",
+          hash: "",
+        },
+        { replaceState: () => undefined },
+      ),
+    ).toEqual({ kind: "rejected", reason: "invalid_ws" })
+  })
+
+  it("rejects malformed tokens", () => {
+    expect(
+      consumePendingPairFromUrl(
+        {
+          search: "?mcp-pair=1&mcp-ws=ws://127.0.0.1:1234&mcp-token=short",
+          pathname: "/",
+          hash: "",
+        },
+        { replaceState: () => undefined },
+      ),
+    ).toEqual({ kind: "rejected", reason: "invalid_token" })
+  })
+
+  it("accepts ws://127.0.0.1, ws://localhost, ws://[::1] with port", () => {
+    for (const host of ["127.0.0.1", "localhost", "[::1]"]) {
+      const result = consumePendingPairFromUrl(
+        {
+          search: `?mcp-pair=1&mcp-ws=ws://${host}:9876&mcp-token=${VALID_TOKEN}`,
+          pathname: "/",
+          hash: "",
+        },
+        { replaceState: () => undefined },
+      )
+      expect(result).toEqual({ kind: "consumed" })
+    }
+  })
+
+  it("persists pendingPair and scrubs the URL", () => {
+    const replace = vi.fn()
+    const result = consumePendingPairFromUrl(
+      {
+        search: `?mcp-pair=1&mcp-ws=ws://127.0.0.1:9876&mcp-token=${VALID_TOKEN}&keep=me`,
+        pathname: "/console",
+        hash: "#frag",
+      },
+      { replaceState: replace },
+    )
+    expect(result).toEqual({ kind: "consumed" })
+    const stored = readPendingPair()
+    expect(stored?.url).toBe("ws://127.0.0.1:9876")
+    expect(stored?.token).toBe(VALID_TOKEN)
+    expect(replace).toHaveBeenCalledOnce()
+    expect(replace).toHaveBeenCalledWith(null, "", "/console?keep=me#frag")
+  })
+})
diff --git a/src/utils/mcp/consumePendingPair.ts b/src/utils/mcp/consumePendingPair.ts
new file mode 100644
index 000000000..670ff6fe5
--- /dev/null
+++ b/src/utils/mcp/consumePendingPair.ts
@@ -0,0 +1,53 @@
+import { writePendingPair } from "./mcpBridgeStorage"
+import { LOCALHOST_WS_RE, TOKEN_RE } from "./pairValidation"
+
+// Moves deep-link pair params to sessionStorage so they survive the OIDC
+// redirect (which strips the URL), then scrubs the URL so reloads don't
+// re-trigger pairing.
+
+export type PendingPairOutcome =
+  | { kind: "consumed" }
+  | { kind: "no_params" }
+  | {
+      kind: "rejected"
+      reason: "invalid_ws" | "invalid_token" | "missing_field"
+    }
+
+export const consumePendingPairFromUrl = (
+  loc: { search: string; pathname: string; hash: string } = window.location,
+  history: {
+    replaceState: (s: unknown, t: string, url: string) => void
+  } = window.history,
+): PendingPairOutcome => {
+  const params = new URLSearchParams(loc.search)
+  if (params.get("mcp-pair") !== "1") return { kind: "no_params" }
+
+  const url = params.get("mcp-ws")
+  const token = params.get("mcp-token")
+
+  if (!url || !token) {
+    return { kind: "rejected", reason: "missing_field" }
+  }
+  if (!LOCALHOST_WS_RE.test(url)) {
+    return { kind: "rejected", reason: "invalid_ws" }
+  }
+  if (!TOKEN_RE.test(token)) {
+    return { kind: "rejected", reason: "invalid_token" }
+  }
+
+  writePendingPair({ url, token, receivedAt: Date.now() })
+
+  // Scrub so the token doesn't end up in the user's address bar.
+  params.delete("mcp-pair")
+  params.delete("mcp-ws")
+  params.delete("mcp-token")
+  const remaining = params.toString()
+  const cleanUrl =
+    loc.pathname + (remaining ? `?${remaining}` : "") + (loc.hash || "")
+  try {
+    history.replaceState(null, "", cleanUrl)
+  } catch {
+    // Some embeddings restrict history.
+  }
+  return { kind: "consumed" }
+}
diff --git a/src/utils/mcp/dispatchMCPTool.test.ts b/src/utils/mcp/dispatchMCPTool.test.ts
new file mode 100644
index 000000000..24f7cd3a2
--- /dev/null
+++ b/src/utils/mcp/dispatchMCPTool.test.ts
@@ -0,0 +1,373 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import {
+  dispatchMCPTool,
+  type DispatchContext,
+  type FreshnessGate,
+  type StateFreshness,
+} from "./dispatchMCPTool"
+import { EXPECTED_BRIDGE_VERSION } from "./protocolVersion"
+import type { ToolCallMessage } from "./types"
+import type { ModelToolsClient } from "../aiAssistant"
+import type { MetaToolContext } from "./metaResolvers"
+import type { UserActionDigest } from "../../providers/AIConversationProvider/types"
+import {
+  __resetNotebookAIBridgeForTests,
+  registerWorkspace,
+  unregisterWorkspace,
+} from "../notebookAIBridge"
+
+const makeFreshness = (
+  initial: StateFreshness,
+  readBuffer: number | null = 1,
+): FreshnessGate => {
+  let state = initial
+  let buf = readBuffer
+  return {
+    get: () => state,
+    set: (next) => {
+      state = next
+    },
+    getReadBuffer: () => buf,
+    setReadBuffer: (id) => {
+      buf = id
+    },
+  }
+}
+
+const emptyDigest = (): UserActionDigest => ({
+  added: new Set(),
+  deleted: new Set(),
+  edited: new Set(),
+  ran: new Map(),
+})
+
+const minimalMetaCtx = (): MetaToolContext => ({
+  getActiveBufferId: () => 1,
+  getWorkspace: () => ({
+    notebooks: [{ buffer_id: 1, label: "n1", archived: false }],
+    active: { buffer_id: 1, label: "n1", kind: "notebook" },
+  }),
+  getDigest: () => emptyDigest(),
+})
+
+const minimalWorkspace = () => ({
+  createNotebook: () => Promise.resolve({ bufferId: 1, label: "n1" }),
+  duplicateNotebook: () => Promise.resolve({ bufferId: 2, label: "n1 (copy)" }),
+  deleteNotebook: () => Promise.resolve(),
+  activateNotebook: () => Promise.resolve(true),
+  getBufferMeta: () => ({
+    kind: "active" as const,
+    label: "n1",
+    notebookViewState: {
+      cells: [],
+      settings: { layoutMode: "list" as const },
+    },
+  }),
+  listNotebookBuffers: () => [],
+})
+
+const makeCall = (
+  name: string,
+  args: Record<string, unknown> = {},
+): ToolCallMessage => ({
+  v: EXPECTED_BRIDGE_VERSION,
+  type: "tool_call",
+  requestId: "r-" + name,
+  name,
+  arguments: args,
+  deadlineMs: 15_000,
+})
+
+// `dispatchTool` is the cross-cutting AI dispatch we want to spy on without
+// faking the full ModelToolsClient. We mock the module to capture the call.
+vi.mock("../tools/dispatch", async () => {
+  const actual =
+    await vi.importActual<typeof import("../tools/dispatch")>(
+      "../tools/dispatch",
+    )
+  return {
+    ...actual,
+    dispatchTool: vi.fn(
+      (
+        name: string,
+        _args: unknown,
+      ): Promise<{ content: string; is_error?: boolean }> =>
+        Promise.resolve({
+          content: JSON.stringify({ ok: true, name }),
+          is_error: false,
+        }),
+    ),
+  }
+})
+
+import { dispatchTool as mockedDispatchTool } from "../tools/dispatch"
+
+const ctx = (
+  freshness: StateFreshness = "fresh",
+  meta: MetaToolContext = minimalMetaCtx(),
+): DispatchContext => ({
+  modelToolsClient: {} as unknown as ModelToolsClient,
+  freshness: makeFreshness(freshness),
+  metaToolContext: meta,
+})
+
+beforeEach(() => {
+  __resetNotebookAIBridgeForTests()
+  vi.mocked(mockedDispatchTool).mockClear()
+  registerWorkspace(minimalWorkspace())
+})
+
+afterEach(() => {
+  __resetNotebookAIBridgeForTests()
+  unregisterWorkspace()
+})
+
+describe("dispatchMCPTool — meta tools", () => {
+  it("get_workspace_state resolves locally and never calls dispatchTool", async () => {
+    const c = ctx("unfetched")
+    const out = await dispatchMCPTool(makeCall("get_workspace_state"), c)
+    expect(out.isError).toBe(false)
+    expect(out.content[0].text).toMatch(/<workspace>|<notebook_context>/)
+    expect(vi.mocked(mockedDispatchTool)).not.toHaveBeenCalled()
+  })
+
+  it("get_workspace_state flips freshness to fresh", async () => {
+    const c = ctx("unfetched")
+    await dispatchMCPTool(makeCall("get_workspace_state"), c)
+    expect(c.freshness.get()).toBe("fresh")
+  })
+
+  // Digest-only read (IDs, no cell values) is not a full re-sync, so it must
+  // leave a user-edit "stale" bit set — otherwise a later apply could overwrite
+  // the very edit it just reported.
+  it("get_recent_user_actions resolves locally and does NOT clear 'stale'", async () => {
+    const c = ctx("stale")
+    const out = await dispatchMCPTool(makeCall("get_recent_user_actions"), c)
+    expect(out.isError).toBe(false)
+    expect(out.content[0].text).toMatch(/<user_events/)
+    expect(c.freshness.get()).toBe("stale")
+  })
+})
+
+describe("dispatchMCPTool — state-freshness gate", () => {
+  const mutations = [
+    "add_cell",
+    "update_cell",
+    "delete_cell",
+    "duplicate_cell",
+    "move_cell_up",
+    "move_cell_down",
+    "run_cell",
+    "set_layout_mode",
+    "set_cell_layout",
+    "set_cell_mode",
+    "set_cell_chart_config",
+    "set_cell_autorefresh",
+    "set_cell_chart_maximized",
+    "set_cell_maximized",
+  ]
+
+  it("rejects every mutation tool when freshness is 'unfetched'", async () => {
+    for (const name of mutations) {
+      const c = ctx("unfetched")
+      const out = await dispatchMCPTool(makeCall(name), c)
+      expect(out.isError).toBe(true)
+      expect(out.content[0].text).toMatch(/STATE_NOT_FETCHED/)
+    }
+    expect(vi.mocked(mockedDispatchTool)).not.toHaveBeenCalled()
+  })
+
+  it("rejects every mutation tool when freshness is 'stale'", async () => {
+    for (const name of mutations) {
+      const c = ctx("stale")
+      const out = await dispatchMCPTool(makeCall(name), c)
+      expect(out.isError).toBe(true)
+      expect(out.content[0].text).toMatch(/STATE_STALE/)
+    }
+    expect(vi.mocked(mockedDispatchTool)).not.toHaveBeenCalled()
+  })
+
+  // create_notebook is exempt from the freshness gate so a fresh console (no
+  // notebook open, nothing to protect) can create its first notebook.
+  it("allows create_notebook even when freshness is 'unfetched'", async () => {
+    const c = ctx("unfetched")
+    const out = await dispatchMCPTool(makeCall("create_notebook"), c)
+    expect(out.isError).toBe(false)
+    expect(vi.mocked(mockedDispatchTool)).toHaveBeenCalledOnce()
+  })
+
+  it("forwards mutation tools when freshness is 'fresh'", async () => {
+    const c = ctx("fresh")
+    const out = await dispatchMCPTool(makeCall("add_cell"), c)
+    expect(out.isError).toBe(false)
+    expect(vi.mocked(mockedDispatchTool)).toHaveBeenCalledOnce()
+  })
+
+  it("does NOT flip freshness on a successful mutation", async () => {
+    const c = ctx("fresh")
+    await dispatchMCPTool(makeCall("add_cell"), c)
+    expect(c.freshness.get()).toBe("fresh")
+  })
+})
+
+describe("dispatchMCPTool — read tools through dispatchTool", () => {
+  const reads = ["list_cells", "get_cell", "get_notebook_state"]
+
+  it("forwards read tools to dispatchTool regardless of freshness", async () => {
+    for (const name of reads) {
+      vi.mocked(mockedDispatchTool).mockClear()
+      const c = ctx("unfetched")
+      const out = await dispatchMCPTool(makeCall(name), c)
+      expect(out.isError).toBe(false)
+      expect(vi.mocked(mockedDispatchTool)).toHaveBeenCalledOnce()
+    }
+  })
+
+  it("flips freshness to 'fresh' after a full-state read (get_notebook_state)", async () => {
+    const c = ctx("unfetched")
+    await dispatchMCPTool(makeCall("get_notebook_state"), c)
+    expect(c.freshness.get()).toBe("fresh")
+  })
+
+  // Partial reads must NOT clear a user-edit "stale" bit: they don't surface a
+  // concurrent edit to another cell, so clearing it would let a later
+  // apply_notebook_state silently overwrite that unseen edit.
+  it("does NOT clear 'stale' after a partial read (get_cell / list_cells)", async () => {
+    for (const name of ["get_cell", "list_cells"]) {
+      const c = ctx("stale")
+      await dispatchMCPTool(makeCall(name), c)
+      expect(c.freshness.get()).toBe("stale")
+    }
+  })
+})
+
+describe("dispatchMCPTool — buffer-scoped freshness", () => {
+  // C2: a fresh read of one buffer must not license a stale write to another.
+  it("rejects a mutation targeting a buffer other than the last full read", async () => {
+    const c = ctx("fresh") // readBuffer defaults to 1
+    const out = await dispatchMCPTool(
+      makeCall("apply_notebook_state", { buffer_id: 2, cells: [] }),
+      c,
+    )
+    expect(out.isError).toBe(true)
+    expect(out.content[0].text).toMatch(/STATE_NOT_FETCHED/)
+    expect(vi.mocked(mockedDispatchTool)).not.toHaveBeenCalled()
+  })
+
+  it("allows a mutation targeting the last fully-read buffer", async () => {
+    const c = ctx("fresh") // readBuffer = 1
+    const out = await dispatchMCPTool(
+      makeCall("apply_notebook_state", { buffer_id: 1, cells: [] }),
+      c,
+    )
+    expect(out.isError).toBe(false)
+    expect(vi.mocked(mockedDispatchTool)).toHaveBeenCalledOnce()
+  })
+
+  it("a successful get_notebook_state sets the fresh buffer to the one read", async () => {
+    const c = ctx("stale")
+    c.freshness.setReadBuffer(99)
+    await dispatchMCPTool(makeCall("get_notebook_state", { buffer_id: 7 }), c)
+    expect(c.freshness.get()).toBe("fresh")
+    expect(c.freshness.getReadBuffer()).toBe(7)
+  })
+
+  // Finding 2: a failed full-state read surfaced no state → must not clear it.
+  it("a FAILED get_notebook_state does NOT clear staleness", async () => {
+    vi.mocked(mockedDispatchTool).mockResolvedValueOnce({
+      content: "boom",
+      is_error: true,
+    })
+    const c = ctx("stale")
+    await dispatchMCPTool(makeCall("get_notebook_state", { buffer_id: 1 }), c)
+    expect(c.freshness.get()).toBe("stale")
+  })
+
+  // C1: get_workspace_state with no open notebook surfaces nothing → must not clear.
+  it("get_workspace_state with no open notebook does NOT clear staleness", async () => {
+    const meta: MetaToolContext = {
+      ...minimalMetaCtx(),
+      getActiveBufferId: () => null,
+    }
+    const c = ctx("stale", meta)
+    await dispatchMCPTool(makeCall("get_workspace_state"), c)
+    expect(c.freshness.get()).toBe("stale")
+  })
+})
+
+describe("dispatchMCPTool — envelope shape", () => {
+  it("wraps dispatchTool output in the wire ToolResultPayload shape", async () => {
+    vi.mocked(mockedDispatchTool).mockResolvedValueOnce({
+      content: '{"x":1}',
+      is_error: false,
+    })
+    const out = await dispatchMCPTool(makeCall("list_cells"), ctx("fresh"))
+    expect(out.content).toHaveLength(1)
+    expect(out.content[0].type).toBe("text")
+    // Tool body always comes first; the since_last_check suffix is appended.
+    expect(out.content[0].text).toMatch(/^\{"x":1\}/)
+    expect(out.isError).toBe(false)
+  })
+
+  it("propagates is_error=true from dispatchTool", async () => {
+    vi.mocked(mockedDispatchTool).mockResolvedValueOnce({
+      content: "boom",
+      is_error: true,
+    })
+    const out = await dispatchMCPTool(makeCall("list_cells"), ctx("fresh"))
+    expect(out.isError).toBe(true)
+    // Tool body still leads the payload; the suffix follows.
+    expect(out.content[0].text).toMatch(/^boom/)
+  })
+})
+
+describe("dispatchMCPTool — since_last_check suffix", () => {
+  it("appends current active_buffer to non-meta tool results", async () => {
+    const out = await dispatchMCPTool(makeCall("list_cells"), ctx("fresh"))
+    expect(out.content[0].text).toMatch(/<since_last_check>/)
+    expect(out.content[0].text).toMatch(/active_buffer/)
+    expect(out.content[0].text).toMatch(/"n1"/)
+  })
+
+  it("does NOT append the suffix to get_workspace_state (it owns the digest)", async () => {
+    const c = ctx("unfetched")
+    const out = await dispatchMCPTool(makeCall("get_workspace_state"), c)
+    expect(out.content[0].text).not.toMatch(/<since_last_check>/)
+  })
+
+  it("does NOT append the suffix to get_recent_user_actions", async () => {
+    const c = ctx("stale")
+    const out = await dispatchMCPTool(makeCall("get_recent_user_actions"), c)
+    expect(out.content[0].text).not.toMatch(/<since_last_check>/)
+  })
+
+  it("includes user events in the suffix when the digest has any", async () => {
+    const digestWithEdits = (): UserActionDigest => ({
+      added: new Set<string>(["c-1"]),
+      deleted: new Set<string>(),
+      edited: new Set<string>(["c-2"]),
+      ran: new Map<string, "success" | "error">(),
+    })
+    const meta: MetaToolContext = {
+      ...minimalMetaCtx(),
+      getDigest: () => digestWithEdits(),
+      consumeDigest: () => digestWithEdits(),
+    }
+    const out = await dispatchMCPTool(
+      makeCall("list_cells"),
+      ctx("fresh", meta),
+    )
+    expect(out.content[0].text).toMatch(/added: \[c-1\]/)
+    expect(out.content[0].text).toMatch(/edited: \[c-2\]/)
+  })
+
+  it("calls consumeDigest exactly once per non-meta dispatch", async () => {
+    const consume = vi.fn(emptyDigest)
+    const meta: MetaToolContext = {
+      ...minimalMetaCtx(),
+      consumeDigest: consume,
+    }
+    await dispatchMCPTool(makeCall("list_cells"), ctx("fresh", meta))
+    expect(consume).toHaveBeenCalledOnce()
+  })
+})
diff --git a/src/utils/mcp/dispatchMCPTool.ts b/src/utils/mcp/dispatchMCPTool.ts
new file mode 100644
index 000000000..c8cbf08b3
--- /dev/null
+++ b/src/utils/mcp/dispatchMCPTool.ts
@@ -0,0 +1,230 @@
+import type { ModelToolsClient } from "../aiAssistant"
+import { dispatchTool, STALE_RETRY_GUIDANCE } from "../tools/dispatch"
+import { formatDigest, sanitizeForPromptContext } from "../ai/notebookSnapshot"
+import type { UserActionDigest } from "../../providers/AIConversationProvider/types"
+import {
+  resolveGetRecentUserActions,
+  resolveGetWorkspaceState,
+  type MetaToolContext,
+} from "./metaResolvers"
+import { DEFAULT_GRANTED, type Permissions } from "../tools/permissions"
+import type { ToolCallMessage, ToolContent, ToolResultPayload } from "./types"
+import type { ValidateQueryResult } from "../questdb/types"
+import { isMcpMetaToolName, mutatesNotebook } from "../tools/tools"
+
+export type StateFreshness = "unfetched" | "fresh" | "stale"
+
+export type FreshnessGate = {
+  get: () => StateFreshness
+  set: (next: StateFreshness) => void
+  getReadBuffer: () => number | null
+  setReadBuffer: (bufferId: number | null) => void
+}
+
+export type PermissionsRefs = {
+  get: () => Permissions
+  // True when permissions changed since the last dispatch; the wrapper
+  // prepends a notice on the next call so the model learns mid-session.
+  consumeDirty: () => boolean
+}
+
+export type DispatchContext = {
+  modelToolsClient: ModelToolsClient
+  freshness: FreshnessGate
+  metaToolContext: MetaToolContext
+  permissions?: PermissionsRefs
+  validateSql?: (sql: string) => Promise<ValidateQueryResult>
+  signal?: AbortSignal
+}
+
+const FULL_STATE_READ_TOOLS = new Set<string>(["get_notebook_state"])
+
+const STATE_NOT_FETCHED_MESSAGE =
+  "STATE_NOT_FETCHED: Call get_workspace_state first to see the current " +
+  "notebook layout, cells, and any user edits. Then retry this tool."
+
+const STATE_STALE_MESSAGE =
+  "STATE_STALE: The user changed the notebook since your last fetch. Call " +
+  "get_workspace_state to re-sync, then retry this tool. " +
+  STALE_RETRY_GUIDANCE
+
+const STATE_WRONG_BUFFER_MESSAGE =
+  "STATE_NOT_FETCHED: Your last full read was of a different notebook. Call " +
+  "get_notebook_state for this buffer_id to see its current cells and any " +
+  "user edits, then retry this tool."
+
+const bufferIdOf = (args: unknown): number | null => {
+  const id = (args as { buffer_id?: unknown } | null | undefined)?.buffer_id
+  return typeof id === "number" ? id : null
+}
+
+const errorPayload = (text: string): ToolResultPayload => ({
+  content: [{ type: "text", text }],
+  isError: true,
+})
+
+const wrapDispatchToolOutput = (out: {
+  content: string
+  is_error?: boolean
+}): ToolResultPayload => ({
+  content: [{ type: "text", text: out.content }],
+  isError: out.is_error === true ? true : false,
+})
+
+// Includes active_buffer even on a "no events" call so the agent
+// notices a tab switch without needing a per-cell event.
+const buildSinceLastCheckBlock = (
+  meta: MetaToolContext,
+  digest: UserActionDigest | null,
+): string => {
+  const parts: string[] = []
+  const ws = meta.getWorkspace()
+  if (ws?.active) {
+    const label = sanitizeForPromptContext(ws.active.label)
+    parts.push(
+      `  active_buffer: { id: ${ws.active.buffer_id}, label: ${JSON.stringify(label)}, kind: ${ws.active.kind} }`,
+    )
+  }
+  if (digest) {
+    const text = formatDigest(digest)
+    if (text) {
+      // Strip formatDigest's own <user_events> wrapper so the outer
+      // <since_last_check> stays single-rooted.
+      const inner = text
+        .split("\n")
+        .filter((line) => !/^<\/?user_events/.test(line.trim()))
+        .map((line) => "  " + line.replace(/^\s*/, ""))
+      parts.push(...inner)
+    }
+  }
+  if (parts.length === 0) return ""
+  return [`<since_last_check>`, ...parts, `</since_last_check>`].join("\n")
+}
+
+const appendSinceLastCheck = (
+  payload: ToolResultPayload,
+  block: string,
+): ToolResultPayload => {
+  if (!block) return payload
+  const content: ToolContent[] = payload.content.map((c) => ({ ...c }))
+  if (content.length === 0) {
+    content.push({ type: "text", text: block })
+  } else {
+    const last = content[content.length - 1]
+    if (last.type === "text") {
+      last.text = `${last.text}\n\n${block}`
+    } else {
+      content.push({ type: "text", text: block })
+    }
+  }
+  return { ...payload, content }
+}
+
+const noopSetStatus = () => undefined
+
+// These tools already emit user-events themselves; skip the suffix.
+const DIGEST_OWNING_TOOLS = new Set<string>([
+  "get_workspace_state",
+  "get_recent_user_actions",
+])
+
+const buildPermissionsUpdatedBlock = (perms: Permissions): string =>
+  `[Permissions updated since last call: read=${perms.read}, write=${perms.write}. ` +
+  `Operations not covered will be refused with PERMISSION_DENIED.]`
+
+const prependPermissionsNotice = (
+  payload: ToolResultPayload,
+  notice: string,
+): ToolResultPayload => {
+  if (!notice) return payload
+  const content: ToolContent[] = payload.content.map((c) => ({ ...c }))
+  if (content.length === 0 || content[0].type !== "text") {
+    content.unshift({ type: "text", text: notice })
+  } else {
+    content[0] = { ...content[0], text: `${notice}\n\n${content[0].text}` }
+  }
+  return { ...payload, content }
+}
+
+export const dispatchMCPTool = async (
+  call: ToolCallMessage,
+  ctx: DispatchContext,
+): Promise<ToolResultPayload> => {
+  const result = await dispatchInner(call, ctx)
+  // Suppress dirty-notice on a denial — the deny reason already names
+  // the missing permission.
+  const dirty = ctx.permissions?.consumeDirty() ?? false
+  const withPermsNotice =
+    dirty && ctx.permissions && !result.isError
+      ? prependPermissionsNotice(
+          result,
+          buildPermissionsUpdatedBlock(ctx.permissions.get()),
+        )
+      : result
+
+  if (DIGEST_OWNING_TOOLS.has(call.name)) return withPermsNotice
+
+  const digest = ctx.metaToolContext.consumeDigest
+    ? ctx.metaToolContext.consumeDigest()
+    : ctx.metaToolContext.getDigest()
+  const block = buildSinceLastCheckBlock(ctx.metaToolContext, digest)
+  return appendSinceLastCheck(withPermsNotice, block)
+}
+
+const dispatchInner = async (
+  call: ToolCallMessage,
+  ctx: DispatchContext,
+): Promise<ToolResultPayload> => {
+  if (isMcpMetaToolName(call.name)) {
+    if (call.name === "get_workspace_state") {
+      const content = resolveGetWorkspaceState(
+        call.arguments as { include_user_events?: boolean } | undefined,
+        ctx.metaToolContext,
+      )
+      const activeId = ctx.metaToolContext.getActiveBufferId()
+      if (activeId !== null) {
+        ctx.freshness.set("fresh")
+        ctx.freshness.setReadBuffer(activeId)
+      }
+      return { content, isError: false }
+    }
+    // get_recent_user_actions returns only a digest of action IDs (no cell
+    // values), so it is NOT a full re-sync and must not clear "stale" — else a
+    // later apply_notebook_state could overwrite the unseen edit it just named.
+    return {
+      content: resolveGetRecentUserActions(ctx.metaToolContext),
+      isError: false,
+    }
+  }
+
+  // Mutations gate on freshness; the deny text is the recovery instruction.
+  // create_notebook is exempt: it makes a NEW notebook, so there is no existing
+  // buffer whose unseen user edit it could overwrite
+  if (mutatesNotebook(call.name) && call.name !== "create_notebook") {
+    const flag = ctx.freshness.get()
+    if (flag === "unfetched") return errorPayload(STATE_NOT_FETCHED_MESSAGE)
+    if (flag === "stale") return errorPayload(STATE_STALE_MESSAGE)
+    const target = bufferIdOf(call.arguments)
+    if (target !== null && ctx.freshness.getReadBuffer() !== target) {
+      return errorPayload(STATE_WRONG_BUFFER_MESSAGE)
+    }
+  }
+
+  const perms = ctx.permissions
+    ? (ctx.permissions.get() ?? DEFAULT_GRANTED)
+    : undefined
+  const out = await dispatchTool(
+    call.name,
+    call.arguments,
+    ctx.modelToolsClient,
+    noopSetStatus,
+    perms,
+    ctx.validateSql,
+    ctx.signal,
+  )
+  if (FULL_STATE_READ_TOOLS.has(call.name) && !out.is_error) {
+    ctx.freshness.set("fresh")
+    ctx.freshness.setReadBuffer(bufferIdOf(call.arguments))
+  }
+  return wrapDispatchToolOutput(out)
+}
diff --git a/src/utils/mcp/mcpBridgeStorage.test.ts b/src/utils/mcp/mcpBridgeStorage.test.ts
new file mode 100644
index 000000000..626c01444
--- /dev/null
+++ b/src/utils/mcp/mcpBridgeStorage.test.ts
@@ -0,0 +1,197 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import {
+  clearPendingPair,
+  markPendingPairConsented,
+  readPendingPair,
+  readPermissions,
+  writePendingPair,
+  writePermissions,
+} from "./mcpBridgeStorage"
+import { DEFAULT_GRANTED, type Permissions } from "../tools/permissions"
+
+const makeStubStorage = () => {
+  const store = new Map<string, string>()
+  return {
+    getItem: (k: string) => store.get(k) ?? null,
+    setItem: (k: string, v: string) => {
+      store.set(k, v)
+    },
+    removeItem: (k: string) => {
+      store.delete(k)
+    },
+    clear: () => store.clear(),
+  }
+}
+
+const makeStubSessionStorage = () => {
+  const store = new Map<string, string>()
+  return {
+    getItem: (k: string) => store.get(k) ?? null,
+    setItem: (k: string, v: string) => {
+      store.set(k, v)
+    },
+    removeItem: (k: string) => {
+      store.delete(k)
+    },
+    clear: () => store.clear(),
+  }
+}
+
+const KEY = "mcpBridgePendingPair"
+const PERMISSIONS_KEY = "mcp:permissions"
+
+beforeEach(() => {
+  ;(globalThis as { sessionStorage?: unknown }).sessionStorage =
+    makeStubSessionStorage()
+  ;(globalThis as { localStorage?: unknown }).localStorage = makeStubStorage()
+})
+
+afterEach(() => {
+  delete (globalThis as { sessionStorage?: unknown }).sessionStorage
+  delete (globalThis as { localStorage?: unknown }).localStorage
+})
+
+const PAIR = { url: "ws://127.0.0.1:1234", token: "tok", receivedAt: 0 }
+
+describe("mcpBridgeStorage", () => {
+  it("readPendingPair returns null when nothing stored", () => {
+    expect(readPendingPair()).toBeNull()
+  })
+
+  it("readPendingPair returns null on corrupt JSON", () => {
+    sessionStorage.setItem(KEY, "{not json")
+    expect(readPendingPair()).toBeNull()
+  })
+
+  it("readPendingPair returns null when shape is wrong", () => {
+    sessionStorage.setItem(KEY, JSON.stringify({ notUrl: true }))
+    expect(readPendingPair()).toBeNull()
+  })
+
+  it("write + read round-trip", () => {
+    writePendingPair(PAIR)
+    expect(readPendingPair()).toEqual(PAIR)
+  })
+
+  it("clearPendingPair removes the key", () => {
+    writePendingPair(PAIR)
+    clearPendingPair()
+    expect(sessionStorage.getItem(KEY)).toBeNull()
+    expect(readPendingPair()).toBeNull()
+  })
+
+  it("markPendingPairConsented promotes a pending pair without touching url/token/receivedAt", () => {
+    writePendingPair(PAIR)
+    markPendingPairConsented()
+    expect(readPendingPair()).toEqual({ ...PAIR, consented: true })
+  })
+
+  it("markPendingPairConsented is a no-op when no pair is stored", () => {
+    markPendingPairConsented()
+    expect(readPendingPair()).toBeNull()
+    expect(sessionStorage.getItem(KEY)).toBeNull()
+  })
+
+  it("markPendingPairConsented is idempotent", () => {
+    writePendingPair(PAIR)
+    markPendingPairConsented()
+    markPendingPairConsented()
+    expect(readPendingPair()).toEqual({ ...PAIR, consented: true })
+  })
+
+  it("consented pair survives a write+read round-trip with the flag intact", () => {
+    writePendingPair({ ...PAIR, consented: true })
+    expect(readPendingPair()).toEqual({ ...PAIR, consented: true })
+  })
+
+  it("consented flag from older record without the field defaults to undefined (not auto-consented)", () => {
+    sessionStorage.setItem(
+      KEY,
+      JSON.stringify({ url: PAIR.url, token: PAIR.token, receivedAt: 0 }),
+    )
+    const stored = readPendingPair()
+    expect(stored?.consented).toBeUndefined()
+  })
+})
+
+describe("mcpBridgeStorage permissions", () => {
+  it("readPermissions returns DEFAULT_GRANTED when nothing is stored", () => {
+    // Given an empty localStorage
+    // When permissions are read
+    // Then the granted default is returned
+    expect(readPermissions()).toEqual(DEFAULT_GRANTED)
+  })
+
+  it("write + read round-trips a valid permissions object", () => {
+    // Given a fully granted permissions object
+    const perms: Permissions = {
+      grantSchemaAccess: true,
+      read: true,
+      write: true,
+    }
+    // When written and read back
+    writePermissions(perms)
+    // Then the same object is returned
+    expect(readPermissions()).toEqual(perms)
+  })
+
+  it("readPermissions returns DEFAULT_GRANTED on corrupt JSON", () => {
+    // Given a corrupt stored value
+    localStorage.setItem(PERMISSIONS_KEY, "{not json")
+    // When permissions are read
+    // Then the granted default is returned
+    expect(readPermissions()).toEqual(DEFAULT_GRANTED)
+  })
+
+  it("readPermissions returns DEFAULT_GRANTED when a key is missing", () => {
+    // Given a stored object missing the write field
+    localStorage.setItem(
+      PERMISSIONS_KEY,
+      JSON.stringify({ grantSchemaAccess: true, read: true }),
+    )
+    // When permissions are read
+    // Then the granted default is returned
+    expect(readPermissions()).toEqual(DEFAULT_GRANTED)
+  })
+
+  it("readPermissions returns DEFAULT_GRANTED when a field is non-boolean", () => {
+    // Given a stored object with a non-boolean field
+    localStorage.setItem(
+      PERMISSIONS_KEY,
+      JSON.stringify({ grantSchemaAccess: true, read: "yes", write: false }),
+    )
+    // When permissions are read
+    // Then the granted default is returned
+    expect(readPermissions()).toEqual(DEFAULT_GRANTED)
+  })
+
+  it("readPermissions re-cascades a hand-edited impossible triple", () => {
+    // Given a hand-edited triple where write is on but read/schema are off
+    localStorage.setItem(
+      PERMISSIONS_KEY,
+      JSON.stringify({ grantSchemaAccess: false, read: false, write: true }),
+    )
+    // When permissions are read
+    // Then the cascade is re-applied and every scope is granted
+    expect(readPermissions()).toEqual({
+      grantSchemaAccess: true,
+      read: true,
+      write: true,
+    })
+  })
+
+  it("readPermissions re-cascades a hand-edited read-without-schema triple", () => {
+    // Given a hand-edited triple where read is on but schema is off
+    localStorage.setItem(
+      PERMISSIONS_KEY,
+      JSON.stringify({ grantSchemaAccess: false, read: true, write: false }),
+    )
+    // When permissions are read
+    // Then schema is forced on and write stays off
+    expect(readPermissions()).toEqual({
+      grantSchemaAccess: true,
+      read: true,
+      write: false,
+    })
+  })
+})
diff --git a/src/utils/mcp/mcpBridgeStorage.ts b/src/utils/mcp/mcpBridgeStorage.ts
new file mode 100644
index 000000000..dcce0d420
--- /dev/null
+++ b/src/utils/mcp/mcpBridgeStorage.ts
@@ -0,0 +1,104 @@
+// sessionStorage (not localStorage) for the pair: credentials must NOT
+// survive tab close or browser sync. Permissions (booleans, not creds)
+// live in localStorage under "mcp:permissions".
+
+import {
+  DEFAULT_GRANTED,
+  normalizePermissions,
+  type Permissions,
+} from "../tools/permissions"
+
+const KEY = "mcpBridgePendingPair"
+const PERMISSIONS_KEY = "mcp:permissions"
+
+export type StoredPendingPair = {
+  url: string
+  token: string
+  receivedAt: number
+  // `true` once helloAck arrives after a user-confirmed connect.
+  // Pre-consent records get re-prompted; consented records auto-restore.
+  consented?: boolean
+}
+
+const safeParsePair = (raw: string | null): StoredPendingPair | null => {
+  if (!raw) return null
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      typeof (parsed as Record<string, unknown>).url === "string" &&
+      typeof (parsed as Record<string, unknown>).token === "string"
+    ) {
+      return parsed as StoredPendingPair
+    }
+  } catch {
+    // Stale / corrupt — fall through to null.
+  }
+  return null
+}
+
+export const readPendingPair = (): StoredPendingPair | null => {
+  if (typeof sessionStorage === "undefined") return null
+  return safeParsePair(sessionStorage.getItem(KEY))
+}
+
+export const writePendingPair = (pair: StoredPendingPair): void => {
+  if (typeof sessionStorage === "undefined") return
+  sessionStorage.setItem(KEY, JSON.stringify(pair))
+}
+
+export const clearPendingPair = (): void => {
+  if (typeof sessionStorage === "undefined") return
+  sessionStorage.removeItem(KEY)
+}
+
+export const markPendingPairConsented = (): void => {
+  if (typeof sessionStorage === "undefined") return
+  const pair = safeParsePair(sessionStorage.getItem(KEY))
+  if (!pair) return
+  if (pair.consented) return
+  sessionStorage.setItem(KEY, JSON.stringify({ ...pair, consented: true }))
+}
+
+// Migration cleanup: very early versions wrote pair creds to localStorage.
+export const clearLegacyLocalStorage = (): void => {
+  if (typeof localStorage === "undefined") return
+  localStorage.removeItem("mcpBridge")
+}
+
+// No clearPermissions on purpose — disconnect is not a reason to
+// forget the user's policy preference.
+const safeParsePermissions = (raw: string | null): Permissions | null => {
+  if (!raw) return null
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      typeof (parsed as Record<string, unknown>).grantSchemaAccess ===
+        "boolean" &&
+      typeof (parsed as Record<string, unknown>).read === "boolean" &&
+      typeof (parsed as Record<string, unknown>).write === "boolean"
+    ) {
+      // Re-apply the cascade in case the stored value was hand-edited.
+      return normalizePermissions(parsed as Permissions)
+    }
+  } catch {
+    // Stale / corrupt — fall through to null.
+  }
+  return null
+}
+
+export const readPermissions = (): Permissions => {
+  if (typeof localStorage === "undefined") return DEFAULT_GRANTED
+  return (
+    safeParsePermissions(localStorage.getItem(PERMISSIONS_KEY)) ??
+    DEFAULT_GRANTED
+  )
+}
+
+export const writePermissions = (perms: Permissions): void => {
+  if (typeof localStorage === "undefined") return
+  localStorage.setItem(PERMISSIONS_KEY, JSON.stringify(perms))
+}
diff --git a/src/utils/mcp/metaResolvers.test.ts b/src/utils/mcp/metaResolvers.test.ts
new file mode 100644
index 000000000..71b18b071
--- /dev/null
+++ b/src/utils/mcp/metaResolvers.test.ts
@@ -0,0 +1,176 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import {
+  resolveGetRecentUserActions,
+  resolveGetWorkspaceState,
+  type MetaToolContext,
+} from "./metaResolvers"
+import type { UserActionDigest } from "../../providers/AIConversationProvider/types"
+import {
+  __resetNotebookAIBridgeForTests,
+  registerWorkspace,
+  unregisterWorkspace,
+} from "../notebookAIBridge"
+import type { NotebookViewState } from "../../store/notebook"
+
+const minimalWorkspace = (
+  override: Partial<{
+    notebookViewState: NotebookViewState
+    label: string
+    archived: boolean
+  }> = {},
+) => ({
+  createNotebook: () =>
+    Promise.resolve({ bufferId: 1, label: override.label ?? "n1" }),
+  duplicateNotebook: () =>
+    Promise.resolve({ bufferId: 2, label: `${override.label ?? "n1"} (copy)` }),
+  deleteNotebook: () => Promise.resolve(),
+  activateNotebook: () => Promise.resolve(true),
+  getBufferMeta: () => ({
+    kind: "active" as const,
+    label: override.label ?? "n1",
+    notebookViewState: override.notebookViewState ?? {
+      cells: [],
+      settings: { layoutMode: "list" as const },
+    },
+  }),
+  listNotebookBuffers: () => [],
+})
+
+const emptyDigest = (): UserActionDigest => ({
+  added: new Set(),
+  deleted: new Set(),
+  edited: new Set(),
+  ran: new Map(),
+})
+
+beforeEach(() => {
+  __resetNotebookAIBridgeForTests()
+})
+
+afterEach(() => {
+  __resetNotebookAIBridgeForTests()
+})
+
+describe("resolveGetWorkspaceState", () => {
+  it("returns no_notebook_open status when no active buffer", () => {
+    const ctx: MetaToolContext = {
+      getActiveBufferId: () => null,
+      getWorkspace: () => null,
+      getDigest: () => null,
+    }
+    const out = resolveGetWorkspaceState(undefined, ctx)
+    expect(out).toHaveLength(1)
+    expect(out[0].text).toMatch(/no_notebook_open/)
+    expect(out[0].text).toMatch(/create_notebook/)
+  })
+
+  it("lists openable notebooks when active tab is not a notebook", () => {
+    // Given the active tab is a SQL buffer but notebooks exist in the workspace
+    const ctx: MetaToolContext = {
+      getActiveBufferId: () => null,
+      getWorkspace: () => ({
+        notebooks: [
+          { buffer_id: 2, label: "Trades", archived: false },
+          { buffer_id: 5, label: "Latency", archived: false },
+        ],
+        active: { buffer_id: 9, label: "Query 1", kind: "sql" },
+      }),
+      getDigest: () => null,
+    }
+
+    // When workspace state is resolved
+    const out = resolveGetWorkspaceState(undefined, ctx)
+
+    // Then it surfaces the openable notebooks and how to target them by buffer_id
+    expect(out[0].text).toMatch(/no_notebook_open/)
+    expect(out[0].text).toContain("<workspace>")
+    expect(out[0].text).toContain("Trades")
+    expect(out[0].text).toContain("Latency")
+    expect(out[0].text).toMatch(/buffer_id/)
+  })
+
+  it("returns workspace + notebook_context when buffer is active", () => {
+    registerWorkspace(minimalWorkspace())
+    const ctx: MetaToolContext = {
+      getActiveBufferId: () => 1,
+      getWorkspace: () => ({
+        notebooks: [{ buffer_id: 1, label: "n1", archived: false }],
+        active: { buffer_id: 1, label: "n1", kind: "notebook" },
+      }),
+      getDigest: () => null,
+    }
+    const out = resolveGetWorkspaceState(undefined, ctx)
+    expect(out[0].text).toContain("<workspace>")
+    expect(out[0].text).toContain("<notebook_context>")
+    unregisterWorkspace()
+  })
+
+  it("appends user_events block when include_user_events is true", () => {
+    registerWorkspace(minimalWorkspace())
+    const digest = emptyDigest()
+    digest.added.add("cell-1")
+    const ctx: MetaToolContext = {
+      getActiveBufferId: () => 1,
+      getWorkspace: () => ({
+        notebooks: [{ buffer_id: 1, label: "n1", archived: false }],
+        active: { buffer_id: 1, label: "n1", kind: "notebook" },
+      }),
+      getDigest: () => digest,
+    }
+    const out = resolveGetWorkspaceState({ include_user_events: true }, ctx)
+    expect(out[0].text).toContain("<user_events")
+    expect(out[0].text).toContain("cell-1")
+    unregisterWorkspace()
+  })
+
+  it("omits user_events block when include_user_events is false / unset", () => {
+    registerWorkspace(minimalWorkspace())
+    const ctx: MetaToolContext = {
+      getActiveBufferId: () => 1,
+      getWorkspace: () => null,
+      getDigest: () => emptyDigest(),
+    }
+    const out = resolveGetWorkspaceState(undefined, ctx)
+    expect(out[0].text).not.toContain("<user_events")
+    unregisterWorkspace()
+  })
+})
+
+describe("resolveGetRecentUserActions", () => {
+  it("returns the empty placeholder when digest is null", () => {
+    const ctx: MetaToolContext = {
+      getActiveBufferId: () => 1,
+      getWorkspace: () => null,
+      getDigest: () => null,
+    }
+    const out = resolveGetRecentUserActions(ctx)
+    expect(out[0].text).toMatch(/<user_events/)
+    expect(out[0].text).toMatch(/no recent actions/)
+  })
+
+  it("returns the empty placeholder when digest is empty", () => {
+    const ctx: MetaToolContext = {
+      getActiveBufferId: () => 1,
+      getWorkspace: () => null,
+      getDigest: () => emptyDigest(),
+    }
+    const out = resolveGetRecentUserActions(ctx)
+    expect(out[0].text).toMatch(/no recent actions/)
+  })
+
+  it("formats a non-empty digest", () => {
+    const digest = emptyDigest()
+    digest.added.add("cell-A")
+    digest.deleted.add("cell-B")
+    digest.ran.set("cell-A", "success")
+    const ctx: MetaToolContext = {
+      getActiveBufferId: () => 1,
+      getWorkspace: () => null,
+      getDigest: () => digest,
+    }
+    const out = resolveGetRecentUserActions(ctx)
+    expect(out[0].text).toContain("cell-A")
+    expect(out[0].text).toContain("cell-B")
+    expect(out[0].text).toContain("success")
+  })
+})
diff --git a/src/utils/mcp/metaResolvers.ts b/src/utils/mcp/metaResolvers.ts
new file mode 100644
index 000000000..3c2ab0151
--- /dev/null
+++ b/src/utils/mcp/metaResolvers.ts
@@ -0,0 +1,69 @@
+import { getWorkspace } from "../notebookAIBridge"
+import type { WorkspaceInfo } from "../executeAIFlow"
+import {
+  buildSnapshot,
+  formatDigest,
+  formatSnapshot,
+  formatWorkspace,
+} from "../ai/notebookSnapshot"
+import type { ToolContent } from "./types"
+import type { UserActionDigest } from "../../providers/AIConversationProvider/types"
+
+export type MetaToolContext = {
+  getActiveBufferId: () => number | null
+  getWorkspace: () => WorkspaceInfo | null
+  getDigest: () => UserActionDigest | null
+  // Snapshot + reset in one shot; dispatchMCPTool uses this to avoid
+  // re-emitting the same actions in successive "since last check" blocks.
+  consumeDigest?: () => UserActionDigest | null
+}
+
+const noNotebookOpenPayload = (ws: WorkspaceInfo | null): ToolContent[] => {
+  const hasNotebooks = !!ws && ws.notebooks.length > 0
+  const status = JSON.stringify({
+    status: "no_notebook_open",
+    hint: hasNotebooks
+      ? "The active tab is not a notebook. Target any notebook listed in " +
+        "<workspace> by its buffer_id (e.g. call get_notebook_state with that " +
+        "buffer_id), or call create_notebook to start a new one."
+      : "Call create_notebook to start a new notebook, or ask the user to " +
+        "open an existing one.",
+  })
+  const parts = hasNotebooks ? [formatWorkspace(ws), status] : [status]
+  return [{ type: "text", text: parts.join("\n") }]
+}
+
+const emptyDigestText =
+  '<user_events since_last_turn="true">\n  (no recent actions)\n</user_events>'
+
+export const resolveGetWorkspaceState = (
+  args: { include_user_events?: boolean } | undefined,
+  ctx: MetaToolContext,
+): ToolContent[] => {
+  const ws = ctx.getWorkspace()
+  const bufferId = ctx.getActiveBufferId()
+  if (bufferId === null) return noNotebookOpenPayload(ws)
+
+  const workspaceController = getWorkspace()
+  const snapshot = buildSnapshot(workspaceController, bufferId)
+
+  const parts: string[] = []
+  if (ws) parts.push(formatWorkspace(ws))
+  if (snapshot) parts.push(formatSnapshot(snapshot))
+  if (args?.include_user_events) {
+    const digest = ctx.getDigest()
+    const digestText = digest ? formatDigest(digest) : ""
+    parts.push(digestText || emptyDigestText)
+  }
+
+  if (parts.length === 0) return noNotebookOpenPayload(ws)
+  return [{ type: "text", text: parts.join("\n") }]
+}
+
+export const resolveGetRecentUserActions = (
+  ctx: MetaToolContext,
+): ToolContent[] => {
+  const digest = ctx.getDigest()
+  const text = digest ? formatDigest(digest) : ""
+  return [{ type: "text", text: text || emptyDigestText }]
+}
diff --git a/src/utils/mcp/pairValidation.ts b/src/utils/mcp/pairValidation.ts
new file mode 100644
index 000000000..001e44b8f
--- /dev/null
+++ b/src/utils/mcp/pairValidation.ts
@@ -0,0 +1,7 @@
+// Loopback-only WS guards against reflected CSRF via attacker-controlled
+// ws:// deep links. Token floor matches the bridge's token-mint length.
+
+export const LOCALHOST_WS_RE =
+  /^ws:\/\/(127\.0\.0\.1|localhost|\[::1\]):\d+(\?.*)?$/
+
+export const TOKEN_RE = /^[a-zA-Z0-9_-]{20,}$/
diff --git a/src/utils/mcp/protocolVersion.ts b/src/utils/mcp/protocolVersion.ts
new file mode 100644
index 000000000..6c9405853
--- /dev/null
+++ b/src/utils/mcp/protocolVersion.ts
@@ -0,0 +1,5 @@
+// Bridge semver this console build was verified against. Stamped on every
+// WS frame as `v` and echoed in `hello.expectedBridgeVersion`. Bridge
+// compares same-major (connect + warning) vs different-major (close 4004).
+// Bump in lockstep with verified bridge releases.
+export const EXPECTED_BRIDGE_VERSION = "0.1.0"
diff --git a/src/utils/mcp/types.ts b/src/utils/mcp/types.ts
new file mode 100644
index 000000000..37a5895ad
--- /dev/null
+++ b/src/utils/mcp/types.ts
@@ -0,0 +1,124 @@
+// Wire-protocol types for the MCP Bridge WebSocket — must stay in sync
+// with the bridge's own types. The `v` field on every frame carries the
+// bridge semver; same-major drift is tolerated, different majors hard-
+// reject with close 4004.
+
+import type { Permissions } from "../tools/permissions"
+
+export type ToolSchema = {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+}
+
+export type ToolContent = {
+  type: "text"
+  text: string
+}
+
+export type ToolResultPayload = {
+  content: ToolContent[]
+  isError?: boolean
+}
+
+// browser → bridge on connect (carries the live notebook + meta tool schemas).
+export type HelloMessage = {
+  v: string
+  type: "hello"
+  token: string
+  userAgent: string
+  // Bridge semver this UI build was tested against. Major mismatch → 4004
+  // close; same-major drift → connect + warning via wait_for_pairing.
+  expectedBridgeVersion: string
+  consoleOrigin: string
+  tools: ToolSchema[]
+  // Always present — bridge requires it; provider seeds from localStorage
+  // (DEFAULT_GRANTED for new pairs) so a hello never lacks them.
+  permissions: Permissions
+}
+
+// bridge → browser, ack of hello with session metadata.
+export type HelloAckMessage = {
+  v: string
+  type: "hello_ack"
+  sessionId: string
+  heartbeatIntervalMs: number
+  // Count only — bridge does NOT validate or filter; don't treat as a
+  // "schemas accepted" signal.
+  seenToolCount: number
+}
+
+// bridge → browser, forwarded MCP tool call.
+export type ToolCallMessage = {
+  v: string
+  type: "tool_call"
+  requestId: string
+  name: string
+  arguments: Record<string, unknown>
+  // `null` ⇒ no deadline; positive number ⇒ cancel after N ms. Never
+  // treat a literal `0` as "abort immediately" — bridge will never send it.
+  deadlineMs: number | null
+}
+
+// browser → bridge, response (envelope mirrors `dispatchTool` output).
+export type ToolResultMessage = {
+  v: string
+  type: "tool_result"
+  requestId: string
+  content: ToolContent[]
+  isError?: boolean
+}
+
+// heartbeat — both directions.
+export type PingMessage = {
+  v: string
+  type: "ping"
+  nonce: string
+}
+
+export type PongMessage = {
+  v: string
+  type: "pong"
+  nonce: string
+}
+
+// bridge → browser, cancel an in-flight tool call (deadline / agent abort).
+export type CancelMessage = {
+  v: string
+  type: "cancel"
+  requestId: string
+}
+
+// Carried in the native WS close frame's `reason` field. NOT a JSON
+// envelope — browsers can't reliably deliver one on force-quit/crash/OS
+// sleep, so the TCP close + heartbeat are the authoritative signals.
+export type CloseReason =
+  | "version_mismatch"
+  | "token_invalid"
+  | "superseded"
+  | "browser_disconnected"
+  | "tab_closing"
+  | "protocol_violation"
+  | "user_disconnect"
+
+// Application-range (4000+) WS close codes. Must stay in sync with
+// `mcp-bridge/src/types.ts WS_CLOSE_CODES`. Bridge originates 4001/4002/
+// 4004/4005; UI may originate 4006/4007 (bridge accepts only). Origin
+// rejection happens pre-upgrade at the HTTP layer (403), no close code.
+export const WS_CLOSE_CODES = {
+  superseded: 4001,
+  token_invalid: 4002,
+  major_version_mismatch: 4004,
+  protocol_violation: 4005,
+  user_disconnect: 4006,
+  tab_closing: 4007,
+} as const
+
+export type AnyMessage =
+  | HelloMessage
+  | HelloAckMessage
+  | ToolCallMessage
+  | ToolResultMessage
+  | PingMessage
+  | PongMessage
+  | CancelMessage
diff --git a/src/utils/notebookAIBridge.test.ts b/src/utils/notebookAIBridge.test.ts
new file mode 100644
index 000000000..ecdbd57e7
--- /dev/null
+++ b/src/utils/notebookAIBridge.test.ts
@@ -0,0 +1,628 @@
+import { describe, it, expect, beforeEach, vi } from "vitest"
+import {
+  __resetNotebookAIBridgeForTests,
+  createNotebookController,
+  emitUserAction,
+  getController,
+  getWorkspace,
+  NotebookToolError,
+  on,
+  registerController,
+  registerWorkspace,
+  summarizeCellResults,
+  unregisterController,
+  unregisterWorkspace,
+  waitForController,
+  withBoundNotebook,
+  type NotebookController,
+  type NotebookWorkspaceController,
+  type UserActionEvent,
+} from "./notebookAIBridge"
+import {
+  MAX_NOTEBOOK_CELLS,
+  MAX_CELL_LINES,
+  type CellResult,
+  type NotebookCell,
+  type NotebookViewState,
+} from "../store/notebook"
+import { createModelToolsClient } from "./aiAssistant"
+
+const emptyState: NotebookViewState = { cells: [] }
+
+const makeController = (
+  bufferId: number,
+  overrides: Partial<NotebookController> = {},
+): NotebookController => ({
+  bufferId,
+  addCell: () => "c1",
+  updateCell: () => undefined,
+  deleteCell: () => undefined,
+  moveCellUp: () => undefined,
+  moveCellDown: () => undefined,
+  duplicateCell: () => "c2",
+  runCell: () =>
+    Promise.resolve({ success: true, queryCount: 1, results: ["success"] }),
+  setLayoutMode: () => undefined,
+  setVariables: () => undefined,
+  setCellLayout: () => undefined,
+  setCellMode: () => undefined,
+  setCellChartConfig: () => undefined,
+  setCellAutoRefresh: () => undefined,
+  setCellChartMaximized: () => undefined,
+  setCellMaximized: () => undefined,
+  applyNotebookState: () => ({
+    applied: { added: [], updated: [], deleted: [] },
+  }),
+  getCellsSnapshot: () => [],
+  getSettings: () => ({}),
+  getMaximizedCellId: () => null,
+  ...overrides,
+})
+
+const makeWorkspace = (
+  overrides: Partial<NotebookWorkspaceController> = {},
+): NotebookWorkspaceController => ({
+  createNotebook: (label) =>
+    Promise.resolve({ bufferId: 1, label: label ?? "Notebook" }),
+  duplicateNotebook: (bufferId) =>
+    Promise.resolve({ bufferId, label: "Notebook (copy)" }),
+  deleteNotebook: () => Promise.resolve(),
+  activateNotebook: () => Promise.resolve(true),
+  getBufferMeta: () => ({
+    kind: "active",
+    label: "test",
+    notebookViewState: emptyState,
+  }),
+  listNotebookBuffers: () => [],
+  ...overrides,
+})
+
+beforeEach(() => {
+  __resetNotebookAIBridgeForTests()
+})
+
+describe("controller registry", () => {
+  it("get returns the registered controller", () => {
+    const c = makeController(42)
+    registerController(c)
+    expect(getController(42)).toBe(c)
+  })
+
+  it("unregister removes the controller", () => {
+    registerController(makeController(42))
+    unregisterController(42)
+    expect(getController(42)).toBeUndefined()
+  })
+
+  it("re-register replaces the previous controller", () => {
+    const first = makeController(42, { getMaximizedCellId: () => "first" })
+    const second = makeController(42, { getMaximizedCellId: () => "second" })
+    registerController(first)
+    registerController(second)
+    expect(getController(42)?.getMaximizedCellId()).toBe("second")
+  })
+})
+
+describe("waitForController", () => {
+  it("resolves immediately when the controller is already registered", async () => {
+    const c = makeController(42)
+    registerController(c)
+    await expect(waitForController(42, 100)).resolves.toBe(c)
+  })
+
+  it("resolves a pending wait as soon as the controller registers", async () => {
+    const pending = waitForController(42, 500)
+    setTimeout(() => registerController(makeController(42)), 10)
+    await expect(pending).resolves.toMatchObject({ bufferId: 42 })
+  })
+
+  it("supports multiple concurrent waiters for the same bufferId", async () => {
+    const a = waitForController(42, 500)
+    const b = waitForController(42, 500)
+    const controller = makeController(42)
+    registerController(controller)
+    const [resA, resB] = await Promise.all([a, b])
+    expect(resA).toBe(controller)
+    expect(resB).toBe(controller)
+  })
+
+  it("rejects with a timeout error after timeoutMs", async () => {
+    await expect(waitForController(42, 20)).rejects.toThrow(
+      /did not register within 20ms/,
+    )
+  })
+
+  it("does not reject a waiter that already resolved before timeout fires", async () => {
+    const pending = waitForController(42, 50)
+    registerController(makeController(42))
+    await pending
+    // Wait past the original timeout to ensure no stale rejection fires.
+    await new Promise((r) => setTimeout(r, 60))
+    const second = waitForController(42, 50)
+    await expect(second).resolves.toMatchObject({ bufferId: 42 })
+  })
+})
+
+describe("workspace registry", () => {
+  it("registerWorkspace replaces the prior workspace", () => {
+    const a = makeWorkspace()
+    const b = makeWorkspace()
+    registerWorkspace(a)
+    registerWorkspace(b)
+    expect(getWorkspace()).toBe(b)
+  })
+
+  it("unregisterWorkspace clears it", () => {
+    registerWorkspace(makeWorkspace())
+    unregisterWorkspace()
+    expect(getWorkspace()).toBeUndefined()
+  })
+})
+
+describe("emitUserAction / on", () => {
+  it("fans out events to every subscriber", () => {
+    const seen: UserActionEvent[][] = [[], []]
+    on("user-action", (e) => seen[0].push(e))
+    on("user-action", (e) => seen[1].push(e))
+    const evt: UserActionEvent = {
+      kind: "user_added_cell",
+      bufferId: 1,
+      cellId: "c",
+    }
+    emitUserAction(evt)
+    expect(seen[0]).toEqual([evt])
+    expect(seen[1]).toEqual([evt])
+  })
+
+  it("returned unsubscribe removes the listener", () => {
+    const seen: UserActionEvent[] = []
+    const off = on("user-action", (e) => seen.push(e))
+    off()
+    emitUserAction({ kind: "user_added_cell", bufferId: 1, cellId: "c" })
+    expect(seen).toEqual([])
+  })
+
+  it("a throwing subscriber does not break other subscribers", () => {
+    const seen: UserActionEvent[] = []
+    on("user-action", () => {
+      throw new Error("boom")
+    })
+    on("user-action", (e) => seen.push(e))
+    emitUserAction({ kind: "user_added_cell", bufferId: 1, cellId: "c" })
+    expect(seen).toHaveLength(1)
+  })
+})
+
+describe("withBoundNotebook", () => {
+  it("throws workspace_unavailable when no workspace is registered", async () => {
+    const err: unknown = await withBoundNotebook(1, () =>
+      Promise.resolve("x"),
+    ).catch((e: unknown) => e)
+    expect(err).toBeInstanceOf(NotebookToolError)
+    expect((err as NotebookToolError).code).toBe("workspace_unavailable")
+  })
+
+  it("maps null meta to not_a_notebook", async () => {
+    registerWorkspace(makeWorkspace({ getBufferMeta: () => null }))
+    const err: unknown = await withBoundNotebook(1, () =>
+      Promise.resolve("x"),
+    ).catch((e: unknown) => e)
+    expect((err as NotebookToolError).code).toBe("not_a_notebook")
+  })
+
+  it("maps deleted meta to deleted", async () => {
+    registerWorkspace(
+      makeWorkspace({ getBufferMeta: () => ({ kind: "deleted" as const }) }),
+    )
+    const err: unknown = await withBoundNotebook(1, () =>
+      Promise.resolve("x"),
+    ).catch((e: unknown) => e)
+    expect((err as NotebookToolError).code).toBe("deleted")
+  })
+
+  it("maps archived meta to archived", async () => {
+    registerWorkspace(
+      makeWorkspace({
+        getBufferMeta: () => ({ kind: "archived", label: "x" }) as const,
+      }),
+    )
+    const err: unknown = await withBoundNotebook(1, () =>
+      Promise.resolve("x"),
+    ).catch((e: unknown) => e)
+    expect((err as NotebookToolError).code).toBe("archived")
+  })
+
+  it("passes the controller through when it is already mounted", async () => {
+    registerWorkspace(makeWorkspace())
+    const c = makeController(1)
+    registerController(c)
+    const out = await withBoundNotebook(1, (ctrl) =>
+      Promise.resolve(ctrl.bufferId),
+    )
+    expect(out).toBe(1)
+  })
+
+  it("activates the notebook and waits for the controller when not mounted", async () => {
+    const activateNotebook = vi.fn(() => {
+      setTimeout(() => registerController(makeController(1)), 5)
+      return Promise.resolve(true)
+    })
+    registerWorkspace(makeWorkspace({ activateNotebook }))
+    const out = await withBoundNotebook(1, (ctrl) =>
+      Promise.resolve(ctrl.bufferId),
+    )
+    expect(activateNotebook).toHaveBeenCalledWith(1)
+    expect(out).toBe(1)
+  })
+
+  it("throws activation_failed when activation returns false", async () => {
+    registerWorkspace(
+      makeWorkspace({ activateNotebook: () => Promise.resolve(false) }),
+    )
+    const err: unknown = await withBoundNotebook(1, () =>
+      Promise.resolve("x"),
+    ).catch((e: unknown) => e)
+    expect((err as NotebookToolError).code).toBe("activation_failed")
+  })
+
+  it("propagates errors thrown by the inner function", async () => {
+    registerWorkspace(makeWorkspace())
+    registerController(makeController(1))
+    await expect(
+      withBoundNotebook(1, () => Promise.reject(new Error("inner"))),
+    ).rejects.toThrow(/inner/)
+  })
+})
+
+describe("summarizeCellResults", () => {
+  const cellWith = (results: CellResult["results"]): NotebookCell =>
+    ({
+      id: "c1",
+      value: "select 1",
+      mode: "run",
+      result: { results, activeResultIndex: 0, timestamp: 0 },
+    }) as unknown as NotebookCell
+
+  it("reports success only when all entries are terminal-success", () => {
+    expect(
+      summarizeCellResults(
+        cellWith([{ type: "dql" } as never, { type: "ddl" } as never]),
+      ),
+    ).toEqual({ success: true, queryCount: 2, results: ["success", "success"] })
+  })
+
+  it("reports a non-terminal running/queued entry as pending, without success", () => {
+    // Reachable via a superseded agent run, or the notebook backgrounded mid-run.
+    // The agent isn't told success and sees `pending` verbatim; it is NOT flagged
+    // unverified — only an unverifiable-error marker does that.
+    const running = summarizeCellResults(
+      cellWith([{ type: "running" } as never]),
+    )
+    expect(running.success).toBe(false)
+    expect(running.results).toEqual(["pending"])
+    expect(running.unverified).toBeUndefined()
+    expect(
+      summarizeCellResults(cellWith([{ type: "queued" } as never])).unverified,
+    ).toBeUndefined()
+  })
+
+  it("does NOT mark a success/error-only result unverified", () => {
+    expect(
+      summarizeCellResults(
+        cellWith([{ type: "dml" } as never, { type: "dml" } as never]),
+      ).unverified,
+    ).toBeUndefined()
+    expect(
+      summarizeCellResults(
+        cellWith([
+          { type: "dml" } as never,
+          { type: "error", error: "x" },
+        ] as never),
+      ).unverified,
+    ).toBeUndefined()
+  })
+
+  // An unverifiable-error entry (the write may have committed server-side) is
+  // flagged unverified so the agent verifies instead of re-running a duplicate.
+  // A user cancel surfaces verbatim as `error: "Cancelled by user"`, a marker.
+  it("marks an unverifiable-error entry (Cancelled by user) unverified", () => {
+    const r = summarizeCellResults(
+      cellWith([
+        { type: "dml" } as never,
+        { type: "error", error: "Cancelled by user" } as never,
+      ]),
+    )
+    expect(r.success).toBe(false)
+    expect(r.unverified).toBe(true)
+    expect(typeof r.note).toBe("string")
+  })
+
+  it("flags a transport-dropped error (QuestDB is not reachable) unverified", () => {
+    const r = summarizeCellResults(
+      cellWith([
+        { type: "error", error: "QuestDB is not reachable [504]" } as never,
+      ]),
+    )
+    expect(r.unverified).toBe(true)
+    expect(typeof r.note).toBe("string")
+  })
+
+  it("surfaces cancelled (skipped) and plain-error entries verbatim, not unverified", () => {
+    const r = summarizeCellResults(
+      cellWith([
+        { type: "cancelled" } as never,
+        { type: "error", error: "boom" } as never,
+      ]),
+    )
+    expect(r.success).toBe(false)
+    expect(r.queryCount).toBe(2)
+    expect(r.results).toEqual(["cancelled", "ERROR: boom"])
+    expect(r.unverified).toBeUndefined()
+  })
+
+  it("reports failure for a cell with no result", () => {
+    expect(summarizeCellResults(undefined)).toEqual({
+      success: false,
+      queryCount: 0,
+      results: [],
+    })
+  })
+})
+
+describe("createNotebookController — applyNotebookState maximized cell id", () => {
+  const cellA: NotebookCell = { id: "a", position: 0, value: "SELECT 1" }
+  const cellB: NotebookCell = { id: "b", position: 1, value: "SELECT 2" }
+
+  const makeLiveActions = (
+    prevCells: NotebookCell[],
+    currentMaximizedId: string | null = null,
+  ) => ({
+    addCell: () => "new",
+    updateCell: () => undefined,
+    deleteCell: () => undefined,
+    moveCellUp: () => undefined,
+    moveCellDown: () => undefined,
+    duplicateCell: () => "dup",
+    runCell: () => Promise.resolve(true),
+    updateSettings: () => undefined,
+    setCellLayout: () => undefined,
+    setCellMode: () => undefined,
+    setCellChartConfig: () => undefined,
+    setCellAutoRefresh: () => undefined,
+    setCellChartMaximized: () => undefined,
+    setMaximizedCellId: vi.fn(),
+    updateCells: () => undefined,
+    getCellsSnapshot: () => prevCells,
+    getSettings: () => ({}),
+    getMaximizedCellId: () => currentMaximizedId,
+  })
+
+  it("clears a provided maximized id that does not survive the apply", () => {
+    const live = makeLiveActions([cellA, cellB])
+    const controller = createNotebookController(1, { current: live })
+    // Stale echo: cell "a" is dropped while the request still spotlights it.
+    controller.applyNotebookState({
+      cells: [{ id: "b", value: "SELECT 2" }],
+      maximizedCellId: "a",
+    })
+    expect(live.setMaximizedCellId).toHaveBeenCalledWith(null)
+  })
+
+  it("keeps a provided maximized id that exists in the applied cells", () => {
+    const live = makeLiveActions([cellA, cellB])
+    const controller = createNotebookController(1, { current: live })
+    controller.applyNotebookState({
+      cells: [
+        { id: "a", value: "SELECT 1" },
+        { id: "b", value: "SELECT 2" },
+      ],
+      maximizedCellId: "b",
+    })
+    expect(live.setMaximizedCellId).toHaveBeenCalledWith("b")
+  })
+
+  it("clears the current maximized id when the field is omitted and its cell is deleted", () => {
+    const live = makeLiveActions([cellA, cellB], "a")
+    const controller = createNotebookController(1, { current: live })
+    controller.applyNotebookState({ cells: [{ id: "b", value: "SELECT 2" }] })
+    expect(live.setMaximizedCellId).toHaveBeenCalledWith(null)
+  })
+})
+
+describe("createModelToolsClient — deleteCell last-cell guard", () => {
+  const stubQuestClient = {} as unknown as Parameters<
+    typeof createModelToolsClient
+  >[0]
+  const cellA: NotebookCell = { id: "a", position: 0, value: "SELECT 1" }
+  const cellB: NotebookCell = { id: "b", position: 1, value: "SELECT 2" }
+
+  it("refuses to delete the only cell with a last_cell error", async () => {
+    const deleteCell = vi.fn()
+    registerWorkspace(makeWorkspace())
+    registerController(
+      makeController(7, { getCellsSnapshot: () => [cellA], deleteCell }),
+    )
+    const client = createModelToolsClient(stubQuestClient)
+    await expect(client.deleteCell(7, "a")).rejects.toMatchObject({
+      code: "last_cell",
+    })
+    expect(deleteCell).not.toHaveBeenCalled()
+  })
+
+  it("deletes a cell when more than one remains", async () => {
+    const deleteCell = vi.fn()
+    registerWorkspace(makeWorkspace())
+    registerController(
+      makeController(7, { getCellsSnapshot: () => [cellA, cellB], deleteCell }),
+    )
+    const client = createModelToolsClient(stubQuestClient)
+    await client.deleteCell(7, "a")
+    expect(deleteCell).toHaveBeenCalledWith("a")
+  })
+
+  it("rejects an unknown cell id before the last-cell check", async () => {
+    registerWorkspace(makeWorkspace())
+    registerController(makeController(7, { getCellsSnapshot: () => [cellA] }))
+    const client = createModelToolsClient(stubQuestClient)
+    await expect(client.deleteCell(7, "nope")).rejects.toMatchObject({
+      code: "unknown_cell",
+    })
+  })
+})
+
+describe("createModelToolsClient — getCell value caps", () => {
+  const stubQuestClient = {} as unknown as Parameters<
+    typeof createModelToolsClient
+  >[0]
+
+  const registerWithCell = (cell: NotebookCell) => {
+    registerWorkspace(makeWorkspace())
+    registerController(makeController(7, { getCellsSnapshot: () => [cell] }))
+  }
+
+  it("returns short values verbatim with no truncation fields", async () => {
+    registerWithCell({ id: "a", position: 0, value: "SELECT 1" })
+    const client = createModelToolsClient(stubQuestClient)
+    const out = await client.getCell(7, "a")
+    expect(out.value).toBe("SELECT 1")
+    expect(out.truncated).toBeUndefined()
+    expect(out.full_length).toBeUndefined()
+  })
+
+  it("caps long values with a clean slice plus truncated and full_length", async () => {
+    registerWithCell({ id: "a", position: 0, value: "x".repeat(5000) })
+    const client = createModelToolsClient(stubQuestClient)
+    const out = await client.getCell(7, "a")
+    expect(out.value).toBe("x".repeat(4096))
+    expect(out.truncated).toBe(true)
+    expect(out.full_length).toBe(5000)
+  })
+
+  it("returns the verbatim full value when getFullContent is set", async () => {
+    registerWithCell({ id: "a", position: 0, value: "x".repeat(5000) })
+    const client = createModelToolsClient(stubQuestClient)
+    const out = await client.getCell(7, "a", true)
+    expect(out.value).toBe("x".repeat(5000))
+    expect(out.truncated).toBeUndefined()
+    expect(out.full_length).toBeUndefined()
+  })
+
+  it("refuses getFullContent above the 1 MB ceiling with cell_too_large", async () => {
+    registerWithCell({ id: "a", position: 0, value: "x".repeat(1_000_001) })
+    const client = createModelToolsClient(stubQuestClient)
+    await expect(client.getCell(7, "a", true)).rejects.toMatchObject({
+      code: "cell_too_large",
+    })
+  })
+})
+
+describe("createModelToolsClient — cell & line limits", () => {
+  const stubQuestClient = {} as unknown as Parameters<
+    typeof createModelToolsClient
+  >[0]
+  const overLimitValue = Array(MAX_CELL_LINES + 1)
+    .fill("x")
+    .join("\n")
+
+  const makeCells = (count: number): NotebookCell[] =>
+    Array.from({ length: count }, (_, i) => ({
+      id: `c${i}`,
+      position: i,
+      value: "SELECT 1",
+    }))
+
+  const register = (overrides: Partial<NotebookController>) => {
+    registerWorkspace(makeWorkspace())
+    registerController(makeController(7, overrides))
+  }
+
+  it("addCell rejects with cell_limit when the notebook is already full", async () => {
+    const addCell = vi.fn(() => "new")
+    register({ getCellsSnapshot: () => makeCells(MAX_NOTEBOOK_CELLS), addCell })
+    const client = createModelToolsClient(stubQuestClient)
+    await expect(client.addCell(7, "SELECT 1")).rejects.toMatchObject({
+      code: "cell_limit",
+    })
+    expect(addCell).not.toHaveBeenCalled()
+  })
+
+  it("addCell adds a cell when one slot remains", async () => {
+    const addCell = vi.fn(() => "new")
+    register({
+      getCellsSnapshot: () => makeCells(MAX_NOTEBOOK_CELLS - 1),
+      addCell,
+    })
+    const client = createModelToolsClient(stubQuestClient)
+    await expect(client.addCell(7, "SELECT 1")).resolves.toEqual({
+      cellId: "new",
+    })
+    expect(addCell).toHaveBeenCalled()
+  })
+
+  it("addCell rejects an oversized SQL value with cell_too_large", async () => {
+    const addCell = vi.fn(() => "new")
+    register({ getCellsSnapshot: () => [], addCell })
+    const client = createModelToolsClient(stubQuestClient)
+    await expect(client.addCell(7, overLimitValue)).rejects.toMatchObject({
+      code: "cell_too_large",
+    })
+    expect(addCell).not.toHaveBeenCalled()
+  })
+
+  it("addCell exempts markdown from the line limit", async () => {
+    const addCell = vi.fn(() => "new")
+    register({ getCellsSnapshot: () => [], addCell })
+    const client = createModelToolsClient(stubQuestClient)
+    await expect(
+      client.addCell(7, overLimitValue, undefined, "markdown"),
+    ).resolves.toEqual({ cellId: "new" })
+    expect(addCell).toHaveBeenCalled()
+  })
+
+  it("updateCell rejects an oversized value for a SQL cell", async () => {
+    const updateCell = vi.fn()
+    register({
+      getCellsSnapshot: () => [{ id: "a", position: 0, value: "SELECT 1" }],
+      updateCell,
+    })
+    const client = createModelToolsClient(stubQuestClient)
+    await expect(
+      client.updateCell(7, "a", { value: overLimitValue }),
+    ).rejects.toMatchObject({ code: "cell_too_large" })
+    expect(updateCell).not.toHaveBeenCalled()
+  })
+
+  it("updateCell exempts a markdown cell from the line limit", async () => {
+    const updateCell = vi.fn()
+    register({
+      getCellsSnapshot: () => [
+        { id: "a", position: 0, value: "# md", type: "markdown" },
+      ],
+      updateCell,
+    })
+    const client = createModelToolsClient(stubQuestClient)
+    await client.updateCell(7, "a", { value: overLimitValue })
+    expect(updateCell).toHaveBeenCalledWith("a", { value: overLimitValue })
+  })
+
+  it("duplicateCell rejects with cell_limit when the notebook is already full", async () => {
+    const duplicateCell = vi.fn(() => "dup")
+    register({
+      getCellsSnapshot: () => makeCells(MAX_NOTEBOOK_CELLS),
+      duplicateCell,
+    })
+    const client = createModelToolsClient(stubQuestClient)
+    await expect(client.duplicateCell(7, "c0")).rejects.toMatchObject({
+      code: "cell_limit",
+    })
+    expect(duplicateCell).not.toHaveBeenCalled()
+  })
+
+  it("duplicateCell rejects an unknown cell before the limit check", async () => {
+    register({ getCellsSnapshot: () => makeCells(MAX_NOTEBOOK_CELLS) })
+    const client = createModelToolsClient(stubQuestClient)
+    await expect(client.duplicateCell(7, "nope")).rejects.toMatchObject({
+      code: "unknown_cell",
+    })
+  })
+})
diff --git a/src/utils/notebookAIBridge.ts b/src/utils/notebookAIBridge.ts
new file mode 100644
index 000000000..6421b5e18
--- /dev/null
+++ b/src/utils/notebookAIBridge.ts
@@ -0,0 +1,567 @@
+import type {
+  CellMode,
+  CellType,
+  NotebookCell,
+  NotebookSettings,
+  NotebookVariable,
+  NotebookViewState,
+} from "../store/notebook"
+import type { ChartConfig } from "../scenes/Editor/Notebook/CellChart/chartTypes"
+import {
+  buildAppliedCells,
+  buildAppliedLayout,
+  isUnverifiableExecError,
+  UNVERIFIED_RUN_NOTE,
+} from "../scenes/Editor/Notebook/notebookUtils"
+import type { RanStatus } from "./ai/runStatus"
+import { sanitizeForPromptContext } from "./ai/sanitizeForPromptContext"
+
+// Bridges the AI tool-execution layer (plain async code, no React context)
+// to notebook React state. Two controllers live here:
+//
+//   NotebookController       — registered by the mounted NotebookProvider of a
+//                              specific buffer. Exposes cell/layout mutations
+//                              and snapshot reads for a single notebook.
+//
+//   NotebookWorkspaceController — registered once by NotebookWorkspaceBridge.
+//                                 Owns cross-notebook operations: create a new
+//                                 notebook buffer, activate one so it mounts,
+//                                 read any buffer's meta without mounting it.
+//
+// Tools always go through `withBoundNotebook(bufferId, fn)`: it maps missing /
+// deleted / archived / non-notebook buffers to a typed NotebookToolError, and
+// auto-activates the buffer if its controller isn't mounted yet.
+
+export type NotebookController = {
+  bufferId: number
+  addCell: (value: string, afterCellId?: string, type?: CellType) => string
+  updateCell: (cellId: string, updates: { value?: string }) => void
+  deleteCell: (cellId: string) => void
+  moveCellUp: (cellId: string) => void
+  moveCellDown: (cellId: string) => void
+  duplicateCell: (cellId: string) => string
+  runCell: (
+    cellId: string,
+    signal?: AbortSignal,
+    sql?: string,
+  ) => Promise<{
+    success: boolean
+    queryCount: number
+    results: string[]
+    unverified?: boolean
+    note?: string
+  }>
+  setLayoutMode: (mode: "list" | "grid") => void
+  setVariables: (variables: NotebookVariable[]) => void
+  setCellLayout: (
+    cellId: string,
+    pos: { x: number; y: number; w: number; h: number },
+  ) => void
+  setCellMode: (cellId: string, mode: CellMode) => void
+  setCellChartConfig: (cellId: string, config: ChartConfig) => void
+  setCellAutoRefresh: (cellId: string, value: boolean) => void
+  setCellChartMaximized: (cellId: string, value: boolean) => void
+  setCellMaximized: (cellId: string | null) => void
+  applyNotebookState: (request: ApplyNotebookStateRequest) => {
+    applied: { added: string[]; updated: string[]; deleted: string[] }
+  }
+  getCellsSnapshot: () => NotebookCell[]
+  getSettings: () => NotebookSettings
+  getMaximizedCellId: () => string | null
+}
+
+export type NotebookControllerActions = {
+  addCell: (afterCellId?: string, value?: string, type?: CellType) => string
+  updateCell: (cellId: string, updates: Partial<NotebookCell>) => void
+  deleteCell: (cellId: string) => void
+  moveCellUp: (cellId: string) => void
+  moveCellDown: (cellId: string) => void
+  duplicateCell: (cellId: string) => string
+  runCell: (
+    cellId: string,
+    sql?: string,
+    signal?: AbortSignal,
+  ) => Promise<boolean>
+  updateSettings: (updates: Partial<NotebookSettings>) => void
+  setCellLayout: (
+    cellId: string,
+    pos: { x: number; y: number; w: number; h: number },
+  ) => void
+  setCellMode: (cellId: string, mode: CellMode) => void
+  setCellChartConfig: (cellId: string, config: ChartConfig) => void
+  setCellAutoRefresh: (cellId: string, value: boolean) => void
+  setCellChartMaximized: (cellId: string, value: boolean) => void
+  setMaximizedCellId: (cellId: string | null) => void
+  updateCells: (updater: (prev: NotebookCell[]) => NotebookCell[]) => void
+  getCellsSnapshot: () => NotebookCell[]
+  getSettings: () => NotebookSettings
+  getMaximizedCellId: () => string | null
+}
+
+// Wire shape accepted by `applyNotebookState`. The fields are camelCase here
+// (controller-level); the snake_case JSON-schema shape is translated at the
+// dispatchTool boundary. Exactly one of value / preserveValue:true per cell.
+export type ApplyNotebookStateCellRequest = {
+  id?: string | null
+  value?: string | null
+  preserveValue?: boolean | null
+  type?: CellType | null
+  mode?: "run" | "draw" | null
+  autoRefresh?: boolean | null
+  isChartMaximized?: boolean | null
+  chartConfig?: ChartConfig | null
+  grid?: { x: number; y: number; w: number; h: number } | null
+}
+
+export type ApplyNotebookStateRequest = {
+  layoutMode?: "list" | "grid" | null
+  maximizedCellId?: string | null
+  variables?: NotebookVariable[] | null
+  cells: ApplyNotebookStateCellRequest[]
+}
+
+export const summarizeCellResults = (cell: NotebookCell | undefined) => {
+  const freshResult = cell?.result
+  if (!freshResult) {
+    return { success: false, queryCount: 0, results: [] }
+  }
+
+  const results = freshResult.results.map((r) => {
+    if (r.type === "cancelled") return "cancelled"
+    if (r.type === "running" || r.type === "queued") return "pending"
+    if (r.type === "error") {
+      const trimmed =
+        r.error.length > 200 ? `${r.error.slice(0, 197)}...` : r.error
+      return `ERROR: ${sanitizeForPromptContext(trimmed)}`
+    }
+    return "success"
+  })
+
+  const unverified = freshResult.results.some((r) => isUnverifiableExecError(r))
+  return {
+    success: results.length > 0 && results.every((r) => r === "success"),
+    queryCount: results.length,
+    results,
+    ...(unverified
+      ? {
+          unverified: true,
+          note: UNVERIFIED_RUN_NOTE,
+        }
+      : {}),
+  }
+}
+
+export const createNotebookController = (
+  bufferId: number,
+  liveActionsRef: { current: NotebookControllerActions },
+): NotebookController => ({
+  bufferId,
+  addCell: (valueArg, afterCellId, type) =>
+    liveActionsRef.current.addCell(afterCellId, valueArg, type),
+  updateCell: (cellId, updates) =>
+    liveActionsRef.current.updateCell(cellId, updates),
+  deleteCell: (cellId) => liveActionsRef.current.deleteCell(cellId),
+  moveCellUp: (cellId) => liveActionsRef.current.moveCellUp(cellId),
+  moveCellDown: (cellId) => liveActionsRef.current.moveCellDown(cellId),
+  duplicateCell: (cellId) => liveActionsRef.current.duplicateCell(cellId),
+  runCell: async (cellId, signal, sql) => {
+    const cellBefore = liveActionsRef.current
+      .getCellsSnapshot()
+      .find((c) => c.id === cellId)
+    const priorResult = cellBefore?.result ?? null
+
+    await liveActionsRef.current.runCell(cellId, sql, signal)
+
+    const cell = liveActionsRef.current
+      .getCellsSnapshot()
+      .find((c) => c.id === cellId)
+    const freshCell =
+      cell?.result && cell.result !== priorResult ? cell : undefined
+
+    return summarizeCellResults(freshCell)
+  },
+  setLayoutMode: (mode) =>
+    liveActionsRef.current.updateSettings({ layoutMode: mode }),
+  setVariables: (variables) =>
+    liveActionsRef.current.updateSettings({ variables }),
+  setCellLayout: (cellId, pos) =>
+    liveActionsRef.current.setCellLayout(cellId, pos),
+  setCellMode: (cellId, mode) => {
+    liveActionsRef.current.setCellMode(cellId, mode)
+    if (mode === "draw") {
+      liveActionsRef.current.setCellChartMaximized(cellId, false)
+    }
+  },
+  setCellChartConfig: (cellId, cfg) =>
+    liveActionsRef.current.setCellChartConfig(cellId, cfg),
+  setCellAutoRefresh: (cellId, value) =>
+    liveActionsRef.current.setCellAutoRefresh(cellId, value),
+  setCellChartMaximized: (cellId, value) =>
+    liveActionsRef.current.setCellChartMaximized(cellId, value),
+  setCellMaximized: (cellId) =>
+    liveActionsRef.current.setMaximizedCellId(cellId),
+  applyNotebookState: (request) => {
+    // All-or-nothing: buildAppliedCells throws before any mutation.
+    const prev = liveActionsRef.current.getCellsSnapshot()
+    const { nextCells, diff } = buildAppliedCells(prev, request)
+    const settings = liveActionsRef.current.getSettings()
+    const targetLayoutMode =
+      request.layoutMode === undefined || request.layoutMode === null
+        ? settings.layoutMode
+        : request.layoutMode
+
+    liveActionsRef.current.updateCells(() => nextCells)
+
+    if (targetLayoutMode === "grid") {
+      const nextLayout = buildAppliedLayout(
+        request,
+        nextCells,
+        settings.layout,
+        { gridCols: 12, rowHeight: 10, marginY: 20 },
+      )
+      liveActionsRef.current.updateSettings({
+        layoutMode: "grid",
+        layout: nextLayout,
+      })
+    } else if (
+      request.layoutMode !== undefined &&
+      request.layoutMode !== null
+    ) {
+      liveActionsRef.current.updateSettings({
+        layoutMode: request.layoutMode,
+      })
+    }
+
+    if (request.maximizedCellId !== undefined) {
+      const id = request.maximizedCellId
+      liveActionsRef.current.setMaximizedCellId(
+        id && nextCells.some((c) => c.id === id) ? id : null,
+      )
+    } else {
+      const maximizedCellId = liveActionsRef.current.getMaximizedCellId()
+      if (maximizedCellId && !nextCells.some((c) => c.id === maximizedCellId)) {
+        liveActionsRef.current.setMaximizedCellId(null)
+      }
+    }
+
+    if (request.variables !== undefined) {
+      liveActionsRef.current.updateSettings({
+        variables: request.variables ?? [],
+      })
+    }
+
+    return { applied: diff }
+  },
+  getCellsSnapshot: () => liveActionsRef.current.getCellsSnapshot(),
+  getSettings: () => ({ ...liveActionsRef.current.getSettings() }),
+  getMaximizedCellId: () => liveActionsRef.current.getMaximizedCellId(),
+})
+
+export type NotebookWorkspaceBufferMeta =
+  | {
+      kind: "active" | "inactive"
+      label: string
+      notebookViewState: NotebookViewState
+    }
+  | { kind: "archived"; label: string }
+  | { kind: "deleted" }
+  | null
+
+export type NotebookWorkspaceController = {
+  createNotebook: (
+    label?: string,
+    signal?: AbortSignal,
+  ) => Promise<{ bufferId: number; label: string }>
+  duplicateNotebook: (
+    bufferId: number,
+    signal?: AbortSignal,
+  ) => Promise<{ bufferId: number; label: string }>
+  deleteNotebook: (bufferId: number) => Promise<void>
+  activateNotebook: (bufferId: number) => Promise<boolean>
+  getBufferMeta: (bufferId: number) => NotebookWorkspaceBufferMeta
+  listNotebookBuffers: () => Array<{
+    bufferId: number
+    label: string
+    archived: boolean
+  }>
+}
+
+export type UserActionEvent =
+  | { kind: "user_added_cell"; bufferId: number; cellId: string }
+  | { kind: "user_deleted_cell"; bufferId: number; cellId: string }
+  | { kind: "user_updated_cell"; bufferId: number; cellId: string }
+  | {
+      kind: "user_ran_cell"
+      bufferId: number
+      cellId: string
+      status: RanStatus
+    }
+  | { kind: "user_moved_cell"; bufferId: number; cellId: string }
+  | {
+      kind: "user_duplicated_cell"
+      bufferId: number
+      cellId: string
+      newCellId: string
+    }
+  | {
+      kind: "user_changed_layout_mode"
+      bufferId: number
+      mode: "list" | "grid"
+    }
+  | {
+      kind: "user_changed_cell_mode"
+      bufferId: number
+      cellId: string
+      mode: CellMode
+    }
+  | { kind: "user_changed_grid_layout"; bufferId: number }
+  | { kind: "user_archived_notebook"; bufferId: number }
+  | { kind: "user_deleted_notebook"; bufferId: number }
+
+export type NotebookToolErrorCode =
+  | "unknown_buffer"
+  | "deleted"
+  | "archived"
+  | "not_a_notebook"
+  | "activation_failed"
+  | "unknown_cell"
+  | "workspace_unavailable"
+  | "last_tab"
+  | "last_cell"
+  | "cell_limit"
+  | "cell_too_large"
+
+export class NotebookToolError extends Error {
+  readonly code: NotebookToolErrorCode
+  constructor(code: NotebookToolErrorCode, message: string) {
+    super(message)
+    this.code = code
+    this.name = "NotebookToolError"
+  }
+}
+
+type Waiter = {
+  resolve: (c: NotebookController) => void
+  reject: (e: Error) => void
+  timer: ReturnType<typeof setTimeout>
+  // Removes any AbortSignal listener attached when the waiter was created.
+  // Called on resolve / timeout / abort so we never leak listeners.
+  cleanup?: () => void
+}
+
+type Listener = (evt: UserActionEvent) => void
+
+const controllers = new Map<number, NotebookController>()
+const waiters = new Map<number, Waiter[]>()
+const listeners = new Set<Listener>()
+let workspace: NotebookWorkspaceController | undefined
+
+let userActionSeq = 0
+export const getUserActionSeq = (): number => userActionSeq
+
+const editListeners = new Set<() => void>()
+export const onUserEdit = (cb: () => void): (() => void) => {
+  editListeners.add(cb)
+  return () => {
+    editListeners.delete(cb)
+  }
+}
+export const signalUserEdit = (): void => {
+  userActionSeq += 1
+  for (const cb of Array.from(editListeners)) {
+    try {
+      cb()
+    } catch {
+      // One bad subscriber must not break the others.
+    }
+  }
+}
+
+export const registerController = (controller: NotebookController): void => {
+  controllers.set(controller.bufferId, controller)
+  const pending = waiters.get(controller.bufferId)
+  if (pending && pending.length > 0) {
+    for (const w of pending) {
+      clearTimeout(w.timer)
+      w.cleanup?.()
+      w.resolve(controller)
+    }
+    waiters.delete(controller.bufferId)
+  }
+}
+
+export const unregisterController = (bufferId: number): void => {
+  controllers.delete(bufferId)
+}
+
+export const getController = (
+  bufferId: number,
+): NotebookController | undefined => controllers.get(bufferId)
+
+export const waitForController = (
+  bufferId: number,
+  timeoutMs = 3000,
+  signal?: AbortSignal,
+): Promise<NotebookController> => {
+  const existing = controllers.get(bufferId)
+  if (existing) return Promise.resolve(existing)
+  if (signal?.aborted) {
+    return Promise.reject(new DOMException("Aborted", "AbortError"))
+  }
+  return new Promise<NotebookController>((resolve, reject) => {
+    const removeFromWaiters = () => {
+      const list = waiters.get(bufferId)
+      if (!list) return
+      const filtered = list.filter((w) => w.timer !== timer)
+      if (filtered.length === 0) waiters.delete(bufferId)
+      else waiters.set(bufferId, filtered)
+    }
+    const onAbort = () => {
+      clearTimeout(timer)
+      removeFromWaiters()
+      reject(new DOMException("Aborted", "AbortError"))
+    }
+    const cleanup = signal
+      ? () => signal.removeEventListener("abort", onAbort)
+      : undefined
+    const timer = setTimeout(() => {
+      cleanup?.()
+      removeFromWaiters()
+      reject(
+        new Error(
+          `Notebook ${bufferId} did not register within ${timeoutMs}ms`,
+        ),
+      )
+    }, timeoutMs)
+    signal?.addEventListener("abort", onAbort, { once: true })
+    const list = waiters.get(bufferId) ?? []
+    list.push({ resolve, reject, timer, cleanup })
+    waiters.set(bufferId, list)
+  })
+}
+
+export const registerWorkspace = (
+  controller: NotebookWorkspaceController,
+): void => {
+  workspace = controller
+}
+
+export const unregisterWorkspace = (): void => {
+  workspace = undefined
+}
+
+export const getWorkspace = (): NotebookWorkspaceController | undefined =>
+  workspace
+
+export const on = (_event: "user-action", cb: Listener): (() => void) => {
+  listeners.add(cb)
+  return () => {
+    listeners.delete(cb)
+  }
+}
+
+export const emitUserAction = (evt: UserActionEvent): void => {
+  if (evt.kind !== "user_updated_cell") {
+    userActionSeq += 1
+  }
+  // Snapshot to guard against subscribers mutating the set during emit.
+  for (const cb of Array.from(listeners)) {
+    try {
+      cb(evt)
+    } catch {
+      // One bad subscriber must not break the others.
+    }
+  }
+}
+
+const resolveActiveMeta = (
+  bufferId: number,
+): Extract<NotebookWorkspaceBufferMeta, { kind: "active" | "inactive" }> => {
+  if (!workspace) {
+    throw new NotebookToolError(
+      "workspace_unavailable",
+      "Notebook workspace is not mounted yet.",
+    )
+  }
+  const meta = workspace.getBufferMeta(bufferId)
+  if (meta === null) {
+    throw new NotebookToolError(
+      "not_a_notebook",
+      `Buffer ${bufferId} exists but is not a notebook.`,
+    )
+  }
+  if (meta.kind === "deleted") {
+    throw new NotebookToolError(
+      "deleted",
+      `Notebook ${bufferId} no longer exists.`,
+    )
+  }
+  if (meta.kind === "archived") {
+    throw new NotebookToolError(
+      "archived",
+      `Notebook "${meta.label}" is archived.`,
+    )
+  }
+  return meta
+}
+
+// Single checkpoint every mutating notebook tool runs through. Reads the
+// buffer's meta, maps lifecycle states to typed errors, and auto-activates the
+// notebook if its controller isn't mounted yet. The optional `signal` rejects a
+// pending `waitForController` and skips `fn` when the user aborts the AI turn
+// — so stuck tools don't keep the chat spinning past the Abort button.
+export const withBoundNotebook = async <T>(
+  bufferId: number,
+  fn: (controller: NotebookController) => Promise<T>,
+  signal?: AbortSignal,
+): Promise<T> => {
+  if (signal?.aborted) {
+    throw new DOMException("Aborted", "AbortError")
+  }
+  resolveActiveMeta(bufferId)
+  let controller = controllers.get(bufferId)
+  if (!controller) {
+    const ok = await workspace!.activateNotebook(bufferId)
+    if (!ok) {
+      throw new NotebookToolError(
+        "activation_failed",
+        `Could not activate notebook ${bufferId}.`,
+      )
+    }
+    controller = await waitForController(bufferId, 3000, signal)
+  }
+  return fn(controller)
+}
+
+// Skips `activateNotebook`: silently switching the user's active tab to
+// satisfy a read-only AI lookup would lose their focus and scroll position.
+export const withBoundNotebookReadOnly = async <T>(
+  bufferId: number,
+  fn: (
+    view: NotebookViewState,
+    controller: NotebookController | undefined,
+  ) => Promise<T>,
+  signal?: AbortSignal,
+): Promise<T> => {
+  if (signal?.aborted) {
+    throw new DOMException("Aborted", "AbortError")
+  }
+  const meta = resolveActiveMeta(bufferId)
+  const controller = controllers.get(bufferId)
+  return fn(meta.notebookViewState, controller)
+}
+
+// Test-only reset. Clears every module-level slot so vitest runs start clean.
+export const __resetNotebookAIBridgeForTests = (): void => {
+  for (const [, list] of waiters) {
+    for (const w of list) {
+      clearTimeout(w.timer)
+      w.cleanup?.()
+      w.reject(new Error("Bridge reset"))
+    }
+  }
+  controllers.clear()
+  waiters.clear()
+  listeners.clear()
+  workspace = undefined
+}
diff --git a/src/utils/questdb/client.ts b/src/utils/questdb/client.ts
index 2f095f733..069b6d268 100644
--- a/src/utils/questdb/client.ts
+++ b/src/utils/questdb/client.ts
@@ -38,7 +38,6 @@ export class Client {
   private _nextQueryId: QueryId = 1
   private _activeQueryId: QueryId | null = null
   private commonHeaders: Record<string, string> = {}
-  onCancellableQueryStarted: ((queryId: QueryId) => void) | null = null
   private static refreshTokenPending = false
   private static numOfPendingQueries = 0
   refreshTokenMethod: () => Promise<Partial<AuthPayload>> = async (): Promise<
@@ -185,7 +184,6 @@ export class Client {
 
     if (options?.cancellable) {
       this._activeQueryId = queryId
-      this.onCancellableQueryStarted?.(queryId)
       return { promise, queryId }
     }
 
diff --git a/src/utils/questdb/queryExecutionManager.test.ts b/src/utils/questdb/queryExecutionManager.test.ts
new file mode 100644
index 000000000..e26bd92f1
--- /dev/null
+++ b/src/utils/questdb/queryExecutionManager.test.ts
@@ -0,0 +1,310 @@
+import { describe, expect, it, vi } from "vitest"
+import type { QueryKey } from "../../store/Query/types"
+import { QueryExecutionManager } from "./queryExecutionManager"
+
+const createManager = () => new QueryExecutionManager()
+
+const request = (
+  manager: QueryExecutionManager,
+  queryKey: QueryKey,
+  execute: () => void = vi.fn(),
+  options: {
+    abort?: () => void
+    onDismiss?: () => void
+    scopeKey?: string
+  } = {},
+) =>
+  manager.requestExecution({
+    abort: vi.fn(),
+    bufferId: 1,
+    execute,
+    queryKey,
+    ...options,
+  })
+
+describe("QueryExecutionManager", () => {
+  it("notifies pending execution when the confirmation dialog is dismissed", () => {
+    const manager = createManager()
+    const activeKey = "active@0-6" as QueryKey
+    const pendingKey = "pending@0-7" as QueryKey
+    const onDismiss = vi.fn()
+    const pendingExecute = vi.fn()
+
+    request(manager, activeKey)
+    request(manager, pendingKey, pendingExecute, { onDismiss })
+
+    expect(manager.getSnapshot().dialogOpen).toBe(true)
+
+    manager.dismissPending()
+
+    expect(onDismiss).toHaveBeenCalledTimes(1)
+    expect(pendingExecute).not.toHaveBeenCalled()
+    expect(manager.getSnapshot().dialogOpen).toBe(false)
+  })
+
+  it("updates the abort handler when markActive is called for the current key", async () => {
+    const manager = createManager()
+    const activeKey = "active@0-6" as QueryKey
+    const pendingKey = "pending@0-7" as QueryKey
+    const events: string[] = []
+
+    request(manager, activeKey, () => events.push("active"))
+    manager.markActive(1, activeKey, () => {
+      events.push("abort")
+      manager.releaseExecution(activeKey)
+    })
+    request(manager, pendingKey, () => events.push("pending"))
+
+    await manager.confirmPending()
+
+    expect(events).toEqual(["active", "abort", "pending"])
+  })
+
+  it("waits for the active execution to release before running the confirmed pending execution", async () => {
+    const manager = createManager()
+    const activeKey = "active@0-6" as QueryKey
+    const pendingKey = "pending@0-7" as QueryKey
+    const activeAbort = vi.fn()
+    const events: string[] = []
+
+    request(manager, activeKey, () => events.push("active"), {
+      abort: () => {
+        events.push("abort")
+        activeAbort()
+      },
+    })
+    request(manager, pendingKey, () => events.push("pending"))
+
+    const confirm = manager.confirmPending()
+    await Promise.resolve()
+
+    expect(activeAbort).toHaveBeenCalledTimes(1)
+    expect(events).toEqual(["active", "abort"])
+    expect(manager.getActive()?.queryKey).toBe(activeKey)
+
+    manager.releaseExecution(activeKey)
+    await confirm
+
+    expect(events).toEqual(["active", "abort", "pending"])
+    expect(manager.getActive()?.queryKey).toBe(pendingKey)
+  })
+
+  it("aborts and clears the active execution immediately for a scope", () => {
+    const manager = createManager()
+    const activeKey = "active@0-6" as QueryKey
+    const scopeKey = "notebook:1:cell-a"
+    const abort = vi.fn()
+
+    request(manager, activeKey, vi.fn(), { abort, scopeKey })
+
+    manager.abortActiveByScope(scopeKey)
+
+    expect(abort).toHaveBeenCalledTimes(1)
+    expect(manager.getActive(scopeKey)).toBeNull()
+    expect(manager.isAnyRunning(scopeKey)).toBe(false)
+  })
+
+  it("aborts only the requested scope", () => {
+    const manager = createManager()
+    const cellAKey = "cell-a@0-6" as QueryKey
+    const cellBKey = "cell-b@0-6" as QueryKey
+    const cellAScope = "notebook:1:cell-a"
+    const cellBScope = "notebook:1:cell-b"
+    const abortA = vi.fn()
+    const abortB = vi.fn()
+
+    request(manager, cellAKey, vi.fn(), {
+      abort: abortA,
+      scopeKey: cellAScope,
+    })
+    request(manager, cellBKey, vi.fn(), {
+      abort: abortB,
+      scopeKey: cellBScope,
+    })
+
+    manager.abortActiveByScope(cellAScope)
+
+    expect(abortA).toHaveBeenCalledTimes(1)
+    expect(abortB).not.toHaveBeenCalled()
+    expect(manager.getActive(cellAScope)).toBeNull()
+    expect(manager.getActive(cellBScope)?.queryKey).toBe(cellBKey)
+  })
+
+  it("cancelActive aborts and clears the default scope", () => {
+    const manager = createManager()
+    const activeKey = "active@0-6" as QueryKey
+    const abort = vi.fn()
+
+    request(manager, activeKey, vi.fn(), { abort })
+
+    manager.cancelActive()
+
+    expect(abort).toHaveBeenCalledTimes(1)
+    expect(manager.getActive()).toBeNull()
+    expect(manager.isAnyRunning()).toBe(false)
+  })
+
+  it("allows executions in different scopes to run at the same time", () => {
+    const manager = createManager()
+    const cellAKey = "cell-a@0-6" as QueryKey
+    const cellBKey = "cell-b@0-6" as QueryKey
+    const events: string[] = []
+
+    request(manager, cellAKey, () => events.push("cell-a"), {
+      scopeKey: "notebook:1:cell-a",
+    })
+    request(manager, cellBKey, () => events.push("cell-b"), {
+      scopeKey: "notebook:1:cell-b",
+    })
+
+    expect(events).toEqual(["cell-a", "cell-b"])
+    expect(manager.getSnapshot().dialogOpen).toBe(false)
+  })
+
+  it("releases only the requested scope", () => {
+    const manager = createManager()
+    const cellAKey = "cell-a@0-6" as QueryKey
+    const cellBKey = "cell-b@0-6" as QueryKey
+    const cellAScope = "notebook:1:cell-a"
+    const cellBScope = "notebook:1:cell-b"
+
+    request(manager, cellAKey, vi.fn(), { scopeKey: cellAScope })
+    request(manager, cellBKey, vi.fn(), { scopeKey: cellBScope })
+
+    manager.releaseExecution(cellAKey, cellAScope)
+
+    expect(manager.getActive(cellAScope)).toBeNull()
+    expect(manager.getActive(cellBScope)?.queryKey).toBe(cellBKey)
+  })
+
+  it("opens the confirmation dialog for executions in the same scope", () => {
+    const manager = createManager()
+    const firstKey = "first@0-5" as QueryKey
+    const secondKey = "second@0-6" as QueryKey
+    const secondExecute = vi.fn()
+
+    request(manager, firstKey, vi.fn(), {
+      scopeKey: "notebook:1:cell-a",
+    })
+    request(manager, secondKey, secondExecute, {
+      scopeKey: "notebook:1:cell-a",
+    })
+
+    expect(secondExecute).not.toHaveBeenCalled()
+    expect(manager.getSnapshot().dialogOpen).toBe(true)
+    expect(manager.getPending("notebook:1:cell-a")?.queryKey).toBe(secondKey)
+  })
+
+  it("replaces the existing pending execution in the same scope", () => {
+    const manager = createManager()
+    const firstKey = "first@0-5" as QueryKey
+    const secondKey = "second@0-6" as QueryKey
+    const thirdKey = "third@0-5" as QueryKey
+    const secondDismiss = vi.fn()
+    const secondExecute = vi.fn()
+    const thirdExecute = vi.fn()
+    const scopeKey = "notebook:1:cell-a"
+
+    request(manager, firstKey, vi.fn(), { scopeKey })
+    request(manager, secondKey, secondExecute, {
+      scopeKey,
+      onDismiss: secondDismiss,
+    })
+    request(manager, thirdKey, thirdExecute, { scopeKey })
+
+    expect(secondDismiss).toHaveBeenCalledTimes(1)
+    expect(secondExecute).not.toHaveBeenCalled()
+    expect(thirdExecute).not.toHaveBeenCalled()
+    expect(manager.getPending(scopeKey)?.queryKey).toBe(thirdKey)
+  })
+
+  it("does not release a newer active execution with a stale key from the same scope", () => {
+    const manager = createManager()
+    const firstKey = "first@0-5" as QueryKey
+    const secondKey = "second@0-6" as QueryKey
+    const scopeKey = "notebook:1:cell-a"
+
+    manager.markActive(1, firstKey, vi.fn(), scopeKey)
+    manager.markActive(1, secondKey, vi.fn(), scopeKey)
+    manager.releaseExecution(firstKey, scopeKey)
+
+    expect(manager.getActive(scopeKey)?.queryKey).toBe(secondKey)
+  })
+
+  it("does not run confirmed pending execution when a wrong active key is released", async () => {
+    const manager = createManager()
+    const activeKey = "active@0-6" as QueryKey
+    const wrongKey = "wrong@0-5" as QueryKey
+    const pendingKey = "pending@0-7" as QueryKey
+    const pendingExecute = vi.fn()
+    const scopeKey = "notebook:1:cell-a"
+
+    request(manager, activeKey, vi.fn(), { scopeKey })
+    request(manager, pendingKey, pendingExecute, { scopeKey })
+
+    const confirm = manager.confirmPending()
+    await Promise.resolve()
+
+    manager.releaseExecution(wrongKey, scopeKey)
+    await Promise.resolve()
+
+    expect(pendingExecute).not.toHaveBeenCalled()
+    expect(manager.getActive(scopeKey)?.queryKey).toBe(activeKey)
+
+    manager.releaseExecution(activeKey, scopeKey)
+    await confirm
+
+    expect(pendingExecute).toHaveBeenCalledTimes(1)
+    expect(manager.getActive(scopeKey)?.queryKey).toBe(pendingKey)
+  })
+
+  it("dismisses the visible pending execution when another scope opens the dialog", () => {
+    const manager = createManager()
+    const cellAFirstKey = "cell-a-first@0-12" as QueryKey
+    const cellASecondKey = "cell-a-second@0-13" as QueryKey
+    const cellBFirstKey = "cell-b-first@0-12" as QueryKey
+    const cellBSecondKey = "cell-b-second@0-13" as QueryKey
+    const onDismissA = vi.fn()
+
+    request(manager, cellAFirstKey, vi.fn(), {
+      scopeKey: "notebook:1:cell-a",
+    })
+    request(manager, cellASecondKey, vi.fn(), {
+      scopeKey: "notebook:1:cell-a",
+      onDismiss: onDismissA,
+    })
+    request(manager, cellBFirstKey, vi.fn(), {
+      scopeKey: "notebook:1:cell-b",
+    })
+    request(manager, cellBSecondKey, vi.fn(), {
+      scopeKey: "notebook:1:cell-b",
+    })
+
+    expect(onDismissA).toHaveBeenCalledTimes(1)
+    expect(manager.getPending("notebook:1:cell-a")).toBeNull()
+    expect(manager.getPending("notebook:1:cell-b")?.queryKey).toBe(
+      cellBSecondKey,
+    )
+  })
+
+  it("notifies subscribers when manager state changes", () => {
+    const manager = createManager()
+    const activeKey = "active@0-6" as QueryKey
+    const pendingKey = "pending@0-7" as QueryKey
+    const listener = vi.fn()
+
+    const unsubscribe = manager.subscribe(listener)
+
+    request(manager, activeKey)
+    request(manager, pendingKey)
+    manager.dismissPending()
+    manager.releaseExecution(activeKey)
+
+    expect(listener).toHaveBeenCalledTimes(4)
+
+    unsubscribe()
+    request(manager, "next@0-4" as QueryKey)
+
+    expect(listener).toHaveBeenCalledTimes(4)
+  })
+})
diff --git a/src/utils/questdb/queryExecutionManager.ts b/src/utils/questdb/queryExecutionManager.ts
index 5a33126e7..82aa0fa48 100644
--- a/src/utils/questdb/queryExecutionManager.ts
+++ b/src/utils/questdb/queryExecutionManager.ts
@@ -1,17 +1,29 @@
-import type { Client, QueryId } from "./client"
 import type { QueryKey } from "../../store/Query/types"
 
 type NotificationNamespaceKey = string | number
+type ScopeKey = string
+
+export const DEFAULT_QUERY_EXECUTION_SCOPE: ScopeKey = "query-execution"
 
 export type ActiveExecution = {
+  scopeKey: ScopeKey
   bufferId: NotificationNamespaceKey
   queryKey: QueryKey
-  queryId?: QueryId
-  onStop?: () => void
+  abort: () => void
 }
 
 type PendingExecution = ActiveExecution & {
   execute: () => void
+  onDismiss?: () => void
+}
+
+export type QueryExecutionRequest = {
+  abort: () => void
+  bufferId: NotificationNamespaceKey
+  execute: () => void
+  onDismiss?: () => void
+  queryKey: QueryKey
+  scopeKey?: ScopeKey
 }
 
 export type QueryExecutionSnapshot = {
@@ -21,9 +33,9 @@ export type QueryExecutionSnapshot = {
 }
 
 export class QueryExecutionManager {
-  private _active: ActiveExecution | null = null
-  private _pending: PendingExecution | null = null
-  private _dialogOpen = false
+  private _activeByScope = new Map<ScopeKey, ActiveExecution>()
+  private _pendingByScope = new Map<ScopeKey, PendingExecution>()
+  private _dialogScopeKey: ScopeKey | null = null
   private _listeners = new Set<() => void>()
   private _snapshot: QueryExecutionSnapshot = {
     active: null,
@@ -31,140 +43,182 @@ export class QueryExecutionManager {
     dialogOpen: false,
   }
 
-  private _idleWaiters: Array<() => void> = []
-
-  constructor(private client: Client) {
-    client.onCancellableQueryStarted = (queryId) => {
-      this.setActiveQueryId(queryId)
-    }
-  }
+  private _idleWaiters = new Map<ScopeKey, Array<() => void>>()
 
-  private waitForIdle(): Promise<void> {
-    if (this._active === null) return Promise.resolve()
+  private waitForIdle(scopeKey: ScopeKey): Promise<void> {
+    if (!this._activeByScope.has(scopeKey)) return Promise.resolve()
     return new Promise((resolve) => {
-      this._idleWaiters.push(resolve)
+      const waiters = this._idleWaiters.get(scopeKey) ?? []
+      waiters.push(resolve)
+      this._idleWaiters.set(scopeKey, waiters)
     })
   }
 
-  private flushIdleWaiters() {
-    if (this._idleWaiters.length === 0) return
-    const waiters = this._idleWaiters
-    this._idleWaiters = []
+  private flushIdleWaiters(scopeKey: ScopeKey) {
+    const waiters = this._idleWaiters.get(scopeKey)
+    if (!waiters || waiters.length === 0) return
+    this._idleWaiters.delete(scopeKey)
     waiters.forEach((resolve) => resolve())
   }
 
-  requestExecution = (
-    bufferId: NotificationNamespaceKey,
-    queryKey: QueryKey,
-    execute: () => void,
-  ): void => {
-    if (this._active === null) {
-      this._active = { bufferId, queryKey }
+  requestExecution = (request: QueryExecutionRequest): void => {
+    const scopeKey = request.scopeKey ?? DEFAULT_QUERY_EXECUTION_SCOPE
+    if (!this._activeByScope.has(scopeKey)) {
+      this._activeByScope.set(scopeKey, {
+        scopeKey,
+        bufferId: request.bufferId,
+        queryKey: request.queryKey,
+        abort: request.abort,
+      })
       this.refreshSnapshot()
-      execute()
+      request.execute()
       return
     }
 
-    this._pending = { bufferId, queryKey, execute }
-    this._dialogOpen = true
+    if (this._dialogScopeKey && this._dialogScopeKey !== scopeKey) {
+      this._pendingByScope.get(this._dialogScopeKey)?.onDismiss?.()
+      this._pendingByScope.delete(this._dialogScopeKey)
+    }
+
+    this._pendingByScope.get(scopeKey)?.onDismiss?.()
+    this._pendingByScope.set(scopeKey, {
+      scopeKey,
+      bufferId: request.bufferId,
+      queryKey: request.queryKey,
+      execute: request.execute,
+      abort: request.abort,
+      onDismiss: request.onDismiss,
+    })
+    this._dialogScopeKey = scopeKey
     this.refreshSnapshot()
   }
 
-  releaseExecution = (queryKey: QueryKey): void => {
-    if (this._active?.queryKey !== queryKey) return
-    this._active = null
+  releaseExecution = (
+    queryKey: QueryKey,
+    scopeKey: ScopeKey = DEFAULT_QUERY_EXECUTION_SCOPE,
+  ): void => {
+    if (this._activeByScope.get(scopeKey)?.queryKey !== queryKey) return
+    this._activeByScope.delete(scopeKey)
     this.refreshSnapshot()
-    this.flushIdleWaiters()
+    this.flushIdleWaiters(scopeKey)
   }
 
   // Mark a query as active without going through the confirmation dialog.
-  // Idempotent for the same key. Used by code paths that start queries
+  // Idempotent for the same key. Used by legacy code paths that start queries
   // outside of requestExecution (e.g. the Run button which dispatches
   // toggleRunning directly), so that subsequent requestExecution calls can
   // still detect the conflict.
   markActive = (
     bufferId: NotificationNamespaceKey,
     queryKey: QueryKey,
-    onStop?: () => void,
+    abort: () => void,
+    scopeKey: ScopeKey = DEFAULT_QUERY_EXECUTION_SCOPE,
   ): void => {
-    if (
-      this._active?.queryKey === queryKey &&
-      this._active?.bufferId === bufferId
-    ) {
+    const active = this._activeByScope.get(scopeKey)
+    if (active?.queryKey === queryKey && active?.bufferId === bufferId) {
+      if (abort && active.abort !== abort) {
+        this._activeByScope.set(scopeKey, { ...active, abort })
+        this.refreshSnapshot()
+      }
       return
     }
-    this._active = { bufferId, queryKey, onStop }
+    this._activeByScope.set(scopeKey, {
+      scopeKey,
+      bufferId,
+      queryKey,
+      abort,
+    })
     this.refreshSnapshot()
   }
 
-  private setActiveQueryId(queryId: QueryId): void {
-    if (this._active === null) return
-    this._active = { ...this._active, queryId }
-  }
-
-  private abortActive(): void {
-    if (this._active?.onStop) {
-      this._active.onStop()
-      return
-    }
-    if (this._active?.queryId !== undefined) {
-      this.client.abort(this._active.queryId)
-    } else {
-      this.client.abortActive()
-    }
+  private abortActive(scopeKey: ScopeKey): void {
+    const active = this._activeByScope.get(scopeKey)
+    if (!active) return
+    active.abort()
   }
 
-  cancelActive = (): void => {
-    if (this._active === null) return
-    this.abortActive()
-    this._active = null
+  abortActiveByScope = (
+    scopeKey: ScopeKey = DEFAULT_QUERY_EXECUTION_SCOPE,
+  ): void => {
+    if (!this._activeByScope.has(scopeKey)) return
+    this.abortActive(scopeKey)
+    this._activeByScope.delete(scopeKey)
     this.refreshSnapshot()
-    this.flushIdleWaiters()
+    this.flushIdleWaiters(scopeKey)
   }
 
+  cancelActive = (): void => this.abortActiveByScope()
+
   confirmPending = async (): Promise<void> => {
-    const pending = this._pending
-    if (pending === null) {
-      this._dialogOpen = false
+    const scopeKey = this._dialogScopeKey
+    const pending = scopeKey ? this._pendingByScope.get(scopeKey) : null
+    if (!scopeKey || !pending) {
+      this._dialogScopeKey = null
       this.refreshSnapshot()
       return
     }
 
-    this._pending = null
-    this._dialogOpen = false
+    this._pendingByScope.delete(scopeKey)
+    this._dialogScopeKey = null
     this.refreshSnapshot()
 
     // Wait for the aborted query's .catch/.finally to call releaseExecution
     // (which also dispatches stopRunning in its handler) before starting the
     // pending query. Otherwise execute() can fire toggleRunning(QUERY) while
     // running is still QUERY, producing a no-op useEffect.
-    const idle = this.waitForIdle()
-    this.abortActive()
+    const idle = this.waitForIdle(scopeKey)
+    this.abortActive(scopeKey)
     await idle
 
-    this._active = { bufferId: pending.bufferId, queryKey: pending.queryKey }
+    this._activeByScope.set(scopeKey, {
+      scopeKey,
+      bufferId: pending.bufferId,
+      queryKey: pending.queryKey,
+      abort: pending.abort,
+    })
     this.refreshSnapshot()
     pending.execute()
   }
 
-  dismissPending = (): void => {
-    this._pending = null
-    this._dialogOpen = false
+  dismissPending = (scopeKey?: ScopeKey): void => {
+    const targetScopeKey = scopeKey ?? this._dialogScopeKey
+    if (!targetScopeKey) return
+    this._pendingByScope.get(targetScopeKey)?.onDismiss?.()
+    this._pendingByScope.delete(targetScopeKey)
+    if (this._dialogScopeKey === targetScopeKey) {
+      this._dialogScopeKey = null
+    }
     this.refreshSnapshot()
   }
 
-  getActive = (): ActiveExecution | null => this._active
+  getActive = (
+    scopeKey: ScopeKey = DEFAULT_QUERY_EXECUTION_SCOPE,
+  ): ActiveExecution | null => this._activeByScope.get(scopeKey) ?? null
 
-  getPending = (): ActiveExecution | null =>
-    this._pending === null
+  getPending = (scopeKey?: ScopeKey): ActiveExecution | null => {
+    const targetScopeKey = scopeKey ?? this._dialogScopeKey
+    const pending = targetScopeKey
+      ? this._pendingByScope.get(targetScopeKey)
+      : null
+    return pending === undefined || pending === null
       ? null
-      : { bufferId: this._pending.bufferId, queryKey: this._pending.queryKey }
+      : {
+          scopeKey: pending.scopeKey,
+          bufferId: pending.bufferId,
+          queryKey: pending.queryKey,
+          abort: pending.abort,
+        }
+  }
 
-  isDialogOpen = (): boolean => this._dialogOpen
+  isDialogOpen = (): boolean => this._dialogScopeKey !== null
 
-  isAnyRunning = (): boolean => this._active !== null
+  isAnyRunning = (
+    scopeKey: ScopeKey = DEFAULT_QUERY_EXECUTION_SCOPE,
+  ): boolean => this._activeByScope.has(scopeKey)
 
-  runningQueryKey = (): QueryKey | null => this._active?.queryKey ?? null
+  runningQueryKey = (
+    scopeKey: ScopeKey = DEFAULT_QUERY_EXECUTION_SCOPE,
+  ): QueryKey | null => this.getActive(scopeKey)?.queryKey ?? null
 
   subscribe = (listener: () => void): (() => void) => {
     this._listeners.add(listener)
@@ -177,9 +231,9 @@ export class QueryExecutionManager {
 
   private refreshSnapshot() {
     this._snapshot = {
-      active: this._active,
+      active: this.getActive(),
       pending: this.getPending(),
-      dialogOpen: this._dialogOpen,
+      dialogOpen: this.isDialogOpen(),
     }
     this._listeners.forEach((listener) => listener())
   }
diff --git a/src/utils/runDetachedQuery.tsx b/src/utils/runDetachedQuery.tsx
index 0ae16e0e9..4b6ca9b70 100644
--- a/src/utils/runDetachedQuery.tsx
+++ b/src/utils/runDetachedQuery.tsx
@@ -11,6 +11,7 @@ import type {
   QueryAction,
 } from "../store/Query/types"
 import type { Client } from "./questdb/client"
+import type { QueryId } from "./questdb/client"
 import * as QuestDB from "./questdb"
 import type { ExecutionRefs } from "../scenes/Editor/index"
 import type { Dispatch } from "redux"
@@ -24,6 +25,7 @@ export type RunDetachedQueryConfig = {
   dispatch: Dispatch<QueryAction>
   executionRefs: React.MutableRefObject<ExecutionRefs>
   releaseExecution: (queryKey: QueryKey) => void
+  onQueryStarted?: (queryId: QueryId) => void
   onSettled?: () => void
 }
 
@@ -40,11 +42,12 @@ export async function runDetachedQuery(
     releaseExecution,
   } = config
 
-  const { promise } = quest.queryRaw(normalizedSQL, {
+  const { promise, queryId } = quest.queryRaw(normalizedSQL, {
     limit: "0,1000",
     explain: true,
     cancellable: true,
   })
+  config.onQueryStarted?.(queryId)
 
   try {
     const result = await promise
diff --git a/src/utils/textSearch.ts b/src/utils/textSearch.ts
index c12d073c9..15155727f 100644
--- a/src/utils/textSearch.ts
+++ b/src/utils/textSearch.ts
@@ -19,6 +19,10 @@ export type SearchMatch = {
   archivedAt?: number
   isTitleMatch?: boolean
   isMetricsMatch?: boolean
+  isNotebookMatch?: boolean
+  cellId?: string
+  cellType?: "sql" | "markdown"
+  notebookField?: "cell" | "chartName"
   isStale?: boolean
 }
 
@@ -327,6 +331,7 @@ async function findMatchesWithWorker(
 
     timeoutId = setTimeout(() => {
       cleanupHandlers()
+      terminateSearchWorker()
       reject(
         new SearchTimeoutError(
           "Search took too long and was interrupted. Try using simpler search patterns.",
@@ -343,6 +348,8 @@ async function findMatchesWithWorker(
         return
       }
 
+      clearTimeoutIfExists()
+      cleanupHandlers()
       if (e.data.success) {
         resolve(e.data.matches)
       } else {
diff --git a/src/utils/tools/dispatch.ts b/src/utils/tools/dispatch.ts
new file mode 100644
index 000000000..18a07d47a
--- /dev/null
+++ b/src/utils/tools/dispatch.ts
@@ -0,0 +1,1182 @@
+import type { ModelToolsClient, StatusCallback } from "../aiAssistant"
+import { AIOperationStatus } from "../../providers/AIStatusProvider"
+import {
+  getQuestDBTableOfContents,
+  getSpecificDocumentation,
+  parseDocItems,
+  DocCategory,
+} from "../questdbDocsRetrieval"
+import {
+  getUserActionSeq,
+  NotebookToolError,
+  type ApplyNotebookStateCellRequest,
+  type ApplyNotebookStateRequest,
+  type NotebookToolErrorCode,
+} from "../notebookAIBridge"
+import type { CellMode } from "../../store/notebook"
+import type { NotebookVariable } from "../../store/notebook"
+import type {
+  ChartConfig,
+  ChartType,
+  QueryChart,
+} from "../../scenes/Editor/Notebook/CellChart/chartTypes"
+import {
+  classifyAndCheckSqlForAutoRun,
+  classifyAndCheckSqlForExecution,
+  classifyAndCheckSqlForRunQuery,
+  denyReasonUnresolvedSql,
+  requireAllDQL,
+  runPermissionGate,
+  type PermissionDecision,
+  type Permissions,
+} from "./permissions"
+import { categoryFor, editsCells, mutatesNotebook } from "./tools"
+import { getQueriesFromText } from "../../scenes/Editor/Monaco/utils"
+import {
+  isUnverifiableExecError,
+  UNVERIFIED_RUN_NOTE,
+} from "../../scenes/Editor/Notebook/notebookUtils"
+import type { ValidateQueryResult } from "../questdb/types"
+import { buildRunQueryPayload, RUN_QUERY_DEFAULT_LIMIT } from "./runQuery"
+import {
+  isValidVariableName,
+  renderDeclareValidationQuery,
+  validateVariableShape,
+} from "../../scenes/Editor/Notebook/declareUtils"
+import { eventBus } from "../../modules/EventBus"
+import { EventType } from "../../modules/EventBus/types"
+import type { ToolExecutionContext } from "../ai/shared"
+import { formatSql } from "../formatSql"
+
+// Snake-case shapes the agent tools speak, and their mapping to the internal
+// camelCase ChartConfig. Shared by set_cell_chart_config and apply_notebook_state.
+type ToolQueryChart = {
+  type: ChartType
+  y_columns?: string[] | null
+  ohlc?: { open: string; high: string; low: string; close: string } | null
+  partition_by_column?: string | null
+  axis?: "left" | "right" | null
+  enabled?: boolean | null
+  name?: string | null
+}
+type ToolRightAxis = {
+  name?: string | null
+  min?: number | null
+  max?: number | null
+}
+
+const mapQueryChart = (q: ToolQueryChart): QueryChart => {
+  const out: QueryChart = { type: q.type, yColumns: q.y_columns ?? [] }
+  if (q.ohlc) out.ohlc = q.ohlc
+  if (q.partition_by_column) out.partitionByColumn = q.partition_by_column
+  if (q.axis) out.axis = q.axis
+  if (q.enabled === false) out.enabled = false
+  if (q.name) out.name = q.name
+  return out
+}
+
+const mapRightAxis = (ra: ToolRightAxis): ChartConfig["rightAxis"] => {
+  const out: NonNullable<ChartConfig["rightAxis"]> = {}
+  if (ra.name) out.name = ra.name
+  if (ra.min != null) out.min = ra.min
+  if (ra.max != null) out.max = ra.max
+  return out
+}
+
+const notebookErrorHint = (code: NotebookToolErrorCode): string => {
+  switch (code) {
+    case "archived":
+      return "Notebook is archived. Offer create_notebook, or ask the user to unarchive."
+    case "deleted":
+      return "Notebook no longer exists. Call create_notebook to start fresh."
+    case "unknown_buffer":
+      return "The buffer id is unknown. Call create_notebook or confirm the id from <notebook_context>."
+    case "not_a_notebook":
+      return "The buffer is not a notebook. Use create_notebook to scaffold one."
+    case "activation_failed":
+      return "Could not switch to the notebook tab. Ask the user to reopen it."
+    case "unknown_cell":
+      return "The cell id is not in the notebook. Call list_cells to resync, then retry."
+    case "workspace_unavailable":
+      return "The notebook workspace is not ready yet. Retry in a moment."
+    case "last_tab":
+      return "This is the only open tab. Call create_notebook first, then delete this one."
+    case "last_cell":
+      return "A notebook must keep at least one cell. Use update_cell to clear or replace it instead of deleting the last cell."
+    default:
+      return "Notebook tool failed."
+  }
+}
+
+const routeNotebookTool = async <T>(
+  op: () => Promise<T>,
+): Promise<{ content: string; is_error?: boolean }> => {
+  try {
+    const result = await op()
+    return { content: JSON.stringify(result ?? {}) }
+  } catch (e) {
+    if (e instanceof NotebookToolError) {
+      return {
+        is_error: true,
+        content: JSON.stringify({
+          error_code: e.code,
+          message: e.message,
+          hint: notebookErrorHint(e.code),
+        }),
+      }
+    }
+    const message = e instanceof Error ? e.message : String(e)
+    return {
+      is_error: true,
+      content: `Tool execution error: ${message}`,
+    }
+  }
+}
+
+const reSyncTool = (toolContext?: ToolExecutionContext): string =>
+  toolContext?.notebookReadSeq !== undefined
+    ? "get_notebook_state"
+    : "get_workspace_state"
+
+export const STALE_RETRY_GUIDANCE =
+  "When retrying apply_notebook_state, set preserve_value:true for every cell " +
+  "you are not changing; re-read cells you will rewrite with " +
+  "get_cell (get_full_content: true) first so the user's edits survive."
+
+const staleNotebookResult = (toolContext?: ToolExecutionContext) => ({
+  content: JSON.stringify({
+    error_code: "stale",
+    message:
+      "STATE_STALE: The user changed the notebook. " +
+      `Call ${reSyncTool(toolContext)} to re-sync, then retry. ` +
+      STALE_RETRY_GUIDANCE,
+  }),
+  is_error: true,
+})
+
+export const dispatchTool = async (
+  toolName: string,
+  input: unknown,
+  modelToolsClient: ModelToolsClient,
+  setStatus: StatusCallback,
+  permsOrResolver?: Permissions | (() => Permissions),
+  validateSql?: (sql: string) => Promise<ValidateQueryResult>,
+  signal?: AbortSignal,
+  toolContext?: ToolExecutionContext,
+): Promise<{ content: string; is_error?: boolean }> => {
+  const perms =
+    typeof permsOrResolver === "function" ? permsOrResolver() : permsOrResolver
+
+  if (perms) {
+    const decision = runPermissionGate(toolName, {
+      permissions: perms,
+      categoryFor,
+    })
+    if (!decision.granted) {
+      return { content: decision.reason, is_error: true }
+    }
+  }
+  if (toolContext && mutatesNotebook(toolName)) {
+    toolContext.notebookMutated = true
+  }
+  if (
+    toolContext?.notebookReadSeq !== undefined &&
+    editsCells(toolName) &&
+    getUserActionSeq() !== toolContext.notebookReadSeq
+  ) {
+    return staleNotebookResult(toolContext)
+  }
+  try {
+    switch (toolName) {
+      case "suggest_query": {
+        const query = (input as { query: string })?.query
+        if (!query) {
+          return {
+            content: "Error: query parameter is required",
+            is_error: true,
+          }
+        }
+        if (toolContext) {
+          toolContext.suggestedSQL = query
+        }
+        return {
+          content:
+            "Query suggestion registered. It will be shown to the user as a suggestion they can accept or reject.",
+        }
+      }
+      case "get_tables": {
+        setStatus(AIOperationStatus.RetrievingTables)
+        if (!modelToolsClient.getTables) {
+          return {
+            content:
+              "Error: Schema access is not granted. This tool is not available.",
+            is_error: true,
+          }
+        }
+        const result = await modelToolsClient.getTables()
+        const MAX_TABLES = 1000
+        if (result.length > MAX_TABLES) {
+          const truncated = result.slice(0, MAX_TABLES)
+          return {
+            content: JSON.stringify(
+              {
+                tables: truncated,
+                total_count: result.length,
+                truncated: true,
+                message: `Showing ${MAX_TABLES} of ${result.length} tables. Use get_table_schema with a specific table name to get details if you are interested in a specific table.`,
+              },
+              null,
+              2,
+            ),
+          }
+        }
+        return { content: JSON.stringify(result, null, 2) }
+      }
+      case "get_table_schema": {
+        const tableName = (input as { table_name: string })?.table_name
+        if (!modelToolsClient.getTableSchema) {
+          return {
+            content:
+              "Error: Schema access is not granted. This tool is not available.",
+            is_error: true,
+          }
+        }
+        if (!tableName) {
+          return {
+            content: "Error: table_name parameter is required",
+            is_error: true,
+          }
+        }
+        setStatus(AIOperationStatus.InvestigatingTable, {
+          name: tableName,
+          tableOpType: "schema",
+        })
+        const result = await modelToolsClient.getTableSchema(tableName)
+        return {
+          content:
+            result || `Table '${tableName}' not found or schema unavailable`,
+        }
+      }
+      case "get_table_details": {
+        const tableName = (input as { table_name: string })?.table_name
+        if (!modelToolsClient.getTableDetails) {
+          return {
+            content:
+              "Error: Schema access is not granted. This tool is not available.",
+            is_error: true,
+          }
+        }
+        if (!tableName) {
+          return {
+            content: "Error: table_name parameter is required",
+            is_error: true,
+          }
+        }
+        setStatus(AIOperationStatus.InvestigatingTable, {
+          name: tableName,
+          tableOpType: "details",
+        })
+        const result = await modelToolsClient.getTableDetails(tableName)
+        return {
+          content: result
+            ? JSON.stringify(result, null, 2)
+            : "Table details not found",
+          is_error: !result,
+        }
+      }
+      case "validate_query": {
+        setStatus(AIOperationStatus.ValidatingQuery)
+        const query = (input as { query: string })?.query
+        if (!query) {
+          return {
+            content: "Error: query parameter is required",
+            is_error: true,
+          }
+        }
+        const result = await modelToolsClient.validateQuery(query)
+        const content = {
+          valid: result.valid,
+          error: result.valid ? undefined : result.error,
+          position: result.valid ? undefined : result.position,
+        }
+        return { content: JSON.stringify(content, null, 2) }
+      }
+      case "get_questdb_toc": {
+        setStatus(AIOperationStatus.RetrievingDocumentation)
+        const tocContent = await getQuestDBTableOfContents()
+        return { content: tocContent }
+      }
+      case "get_questdb_documentation": {
+        const { category, items } =
+          (input as { category: string; items: string[] }) || {}
+        if (!category || !items || !Array.isArray(items)) {
+          return {
+            content: "Error: category and items parameters are required",
+            is_error: true,
+          }
+        }
+        const parsedItems = parseDocItems(items)
+
+        if (parsedItems.length > 0) {
+          setStatus(AIOperationStatus.InvestigatingDocs, { items: parsedItems })
+        } else {
+          setStatus(AIOperationStatus.InvestigatingDocs)
+        }
+        const documentation = await getSpecificDocumentation(
+          category as DocCategory,
+          items,
+        )
+        return { content: documentation }
+      }
+
+      case "create_notebook": {
+        const { label } = (input as { label?: string }) || {}
+        setStatus(AIOperationStatus.BuildingNotebook, { label })
+        return routeNotebookTool(() => modelToolsClient.createNotebook(label))
+      }
+      case "duplicate_notebook": {
+        const { buffer_id } = (input as { buffer_id: number }) || {}
+        setStatus(AIOperationStatus.DuplicatingNotebook)
+        return routeNotebookTool(() =>
+          modelToolsClient.duplicateNotebook(buffer_id),
+        )
+      }
+      case "delete_notebook": {
+        const { buffer_id } = (input as { buffer_id: number }) || {}
+        setStatus(AIOperationStatus.DeletingNotebook)
+        return routeNotebookTool(() =>
+          modelToolsClient.deleteNotebook(buffer_id),
+        )
+      }
+      case "list_cells": {
+        const { buffer_id } = (input as { buffer_id: number }) || {}
+        setStatus(AIOperationStatus.InspectingNotebook)
+        return routeNotebookTool(async () => ({
+          cells: await modelToolsClient.listCells(buffer_id),
+        }))
+      }
+      case "get_cell": {
+        const { buffer_id, cell_id, get_full_content } =
+          (input as {
+            buffer_id: number
+            cell_id: string
+            get_full_content?: boolean | null
+          }) || {}
+        setStatus(AIOperationStatus.InspectingNotebook, { cellId: cell_id })
+        return routeNotebookTool(() =>
+          modelToolsClient.getCell(
+            buffer_id,
+            cell_id,
+            get_full_content === true,
+          ),
+        )
+      }
+      case "get_notebook_state": {
+        const { buffer_id } = (input as { buffer_id: number }) || {}
+        setStatus(AIOperationStatus.InspectingNotebook)
+        const res = await routeNotebookTool(() =>
+          modelToolsClient.getNotebookState(buffer_id),
+        )
+        if (!res.is_error && toolContext) {
+          toolContext.notebookReadSeq = getUserActionSeq()
+        }
+        return res
+      }
+      case "add_cell": {
+        const { buffer_id, sql, after_cell_id, run, type } =
+          (input as {
+            buffer_id: number
+            sql: string
+            after_cell_id?: string | null
+            run?: boolean | null
+            type?: "sql" | "markdown" | null
+          }) || {}
+        setStatus(AIOperationStatus.AddingCell)
+        const cellType = type === "markdown" ? "markdown" : undefined
+        return routeNotebookTool(async () => {
+          const { cellId } = await modelToolsClient.addCell(
+            buffer_id,
+            sql,
+            after_cell_id ?? undefined,
+            cellType,
+          )
+          if (cellType === "markdown") {
+            // Markdown cells hold prose and are never executed — ignore `run`.
+            return run
+              ? {
+                  cellId,
+                  ran: false,
+                  skipped: true,
+                  note: "Markdown cells are not executable; `run` was ignored.",
+                }
+              : { cellId }
+          }
+          if (run) {
+            if (perms && validateSql) {
+              const decision = await classifyAndCheckSqlForAutoRun(
+                sql,
+                validateSql,
+              )
+              if (decision.action === "deny") {
+                return {
+                  cellId,
+                  ran: false,
+                  error: decision.reason,
+                }
+              }
+              if (decision.action === "skip") {
+                return {
+                  cellId,
+                  ran: false,
+                  skipped: true,
+                  note: decision.reason,
+                }
+              }
+            }
+            setStatus(AIOperationStatus.RunningCell, { cellId })
+            const r = await modelToolsClient.runCell(
+              buffer_id,
+              cellId,
+              signal,
+              perms && validateSql ? sql : undefined,
+            )
+            return {
+              cellId,
+              ran: r.success,
+              queryCount: r.queryCount,
+              results: r.results,
+              ...(r.unverified
+                ? { unverified: r.unverified, note: r.note }
+                : {}),
+            }
+          }
+          return { cellId }
+        })
+      }
+      case "update_cell": {
+        const { buffer_id, cell_id, value } =
+          (input as {
+            buffer_id: number
+            cell_id: string
+            value: string
+          }) || {}
+        setStatus(AIOperationStatus.UpdatingCell, { cellId: cell_id })
+        const updateBaseline =
+          toolContext?.notebookReadSeq ?? getUserActionSeq()
+        if (validateSql) {
+          const current = await modelToolsClient.getCell(buffer_id, cell_id)
+          if (current.mode === "draw") {
+            const decision = await requireAllDQL(value, validateSql)
+            if (!decision.granted) {
+              return { content: decision.reason, is_error: true }
+            }
+          }
+        }
+        if (getUserActionSeq() !== updateBaseline) {
+          return staleNotebookResult(toolContext)
+        }
+        return routeNotebookTool(() =>
+          modelToolsClient.updateCell(buffer_id, cell_id, { value }),
+        )
+      }
+      case "delete_cell": {
+        const { buffer_id, cell_id } =
+          (input as { buffer_id: number; cell_id: string }) || {}
+        setStatus(AIOperationStatus.DeletingCell, { cellId: cell_id })
+        return routeNotebookTool(() =>
+          modelToolsClient.deleteCell(buffer_id, cell_id),
+        )
+      }
+      case "move_cell_up": {
+        const { buffer_id, cell_id } =
+          (input as { buffer_id: number; cell_id: string }) || {}
+        setStatus(AIOperationStatus.ConfiguringLayout, { cellId: cell_id })
+        return routeNotebookTool(() =>
+          modelToolsClient.moveCellUp(buffer_id, cell_id),
+        )
+      }
+      case "move_cell_down": {
+        const { buffer_id, cell_id } =
+          (input as { buffer_id: number; cell_id: string }) || {}
+        setStatus(AIOperationStatus.ConfiguringLayout, { cellId: cell_id })
+        return routeNotebookTool(() =>
+          modelToolsClient.moveCellDown(buffer_id, cell_id),
+        )
+      }
+      case "duplicate_cell": {
+        const { buffer_id, cell_id } =
+          (input as { buffer_id: number; cell_id: string }) || {}
+        setStatus(AIOperationStatus.AddingCell, { cellId: cell_id })
+        return routeNotebookTool(() =>
+          modelToolsClient.duplicateCell(buffer_id, cell_id),
+        )
+      }
+      case "run_cell": {
+        const { buffer_id, cell_id } =
+          (input as { buffer_id: number; cell_id: string }) || {}
+        setStatus(AIOperationStatus.RunningCell, { cellId: cell_id })
+        if (modelToolsClient.getCellType?.(buffer_id, cell_id) === "markdown") {
+          return routeNotebookTool(() =>
+            Promise.resolve({
+              cellId: cell_id,
+              ran: false,
+              skipped: true,
+              note: "Markdown cells are not executable.",
+            }),
+          )
+        }
+        if (perms && validateSql) {
+          const cellSql = modelToolsClient.getCellSql
+            ? modelToolsClient.getCellSql(buffer_id, cell_id)
+            : null
+          if (cellSql === null) {
+            return {
+              content: denyReasonUnresolvedSql("run_cell"),
+              is_error: true,
+            }
+          }
+          const decision = await classifyAndCheckSqlForExecution(
+            cellSql,
+            perms,
+            validateSql,
+          )
+          if (!decision.granted) {
+            return { content: decision.reason, is_error: true }
+          }
+          return routeNotebookTool(() =>
+            modelToolsClient.runCell(buffer_id, cell_id, signal, cellSql),
+          )
+        }
+        return routeNotebookTool(() =>
+          modelToolsClient.runCell(buffer_id, cell_id, signal),
+        )
+      }
+      case "set_layout_mode": {
+        const { buffer_id, mode } =
+          (input as { buffer_id: number; mode: "list" | "grid" }) || {}
+        setStatus(AIOperationStatus.ConfiguringLayout)
+        return routeNotebookTool(() =>
+          modelToolsClient.setLayoutMode(buffer_id, mode),
+        )
+      }
+      case "set_cell_layout": {
+        const { buffer_id, cell_id, x, y, w, h } =
+          (input as {
+            buffer_id: number
+            cell_id: string
+            x: number
+            y: number
+            w: number
+            h: number
+          }) || {}
+        setStatus(AIOperationStatus.ConfiguringLayout, { cellId: cell_id })
+        return routeNotebookTool(() =>
+          modelToolsClient.setCellLayout(buffer_id, cell_id, x, y, w, h),
+        )
+      }
+      case "set_cell_mode": {
+        const { buffer_id, cell_id, mode } =
+          (input as {
+            buffer_id: number
+            cell_id: string
+            mode: CellMode
+          }) || {}
+        setStatus(AIOperationStatus.ConfiguringLayout, { cellId: cell_id })
+        if (mode === "draw" && validateSql) {
+          const cellSql = modelToolsClient.getCellSql
+            ? modelToolsClient.getCellSql(buffer_id, cell_id)
+            : null
+          if (cellSql === null) {
+            return {
+              content: denyReasonUnresolvedSql("set_cell_mode"),
+              is_error: true,
+            }
+          }
+          const decision = await requireAllDQL(cellSql, validateSql)
+          if (!decision.granted) {
+            return { content: decision.reason, is_error: true }
+          }
+        }
+        return routeNotebookTool(() =>
+          modelToolsClient.setCellMode(buffer_id, cell_id, mode),
+        )
+      }
+      case "set_cell_chart_config": {
+        const { buffer_id, cell_id, x_column, name, queries, right_axis } =
+          (input as {
+            buffer_id: number
+            cell_id: string
+            x_column?: string | null
+            name?: string | null
+            queries?: (ToolQueryChart | null)[] | null
+            right_axis?: ToolRightAxis | null
+          }) || {}
+        setStatus(AIOperationStatus.ConfiguringChart, { cellId: cell_id })
+        // Patch: top-level null = preserve; a non-null queries array replaces
+        // all per-query configs (queries:[] clears them, back to inference).
+        const patch: Partial<ChartConfig> = {}
+        if (x_column !== undefined && x_column !== null)
+          patch.xColumn = x_column
+        if (name !== undefined && name !== null) patch.name = name
+        if (queries !== undefined && queries !== null)
+          patch.queries = queries.map((q) => (q ? mapQueryChart(q) : null))
+        if (right_axis !== undefined && right_axis !== null)
+          patch.rightAxis = mapRightAxis(right_axis)
+        if (
+          patch.queries?.some(
+            (q) => q != null && q.type === "candlestick" && !q.ohlc,
+          )
+        ) {
+          return {
+            content: JSON.stringify({
+              error_code: "validation",
+              message:
+                "VALIDATION_ERROR: a candlestick query requires an ohlc mapping (open/high/low/close). Provide ohlc, or use a non-candlestick type.",
+            }),
+            is_error: true,
+          }
+        }
+        // A non-null queries array REPLACES every per-query config
+        if (patch.queries && patch.queries.length > 0) {
+          const cellSql = modelToolsClient.getCellSql
+            ? modelToolsClient.getCellSql(buffer_id, cell_id)
+            : null
+          if (cellSql !== null) {
+            const statementCount = getQueriesFromText(cellSql).length
+            if (statementCount > 0 && patch.queries.length !== statementCount) {
+              return {
+                content: JSON.stringify({
+                  error_code: "validation",
+                  message: `VALIDATION_ERROR: queries has ${patch.queries.length} ${
+                    patch.queries.length === 1 ? "entry" : "entries"
+                  } but the cell has ${statementCount} \`;\`-split statement${
+                    statementCount === 1 ? "" : "s"
+                  }. A non-null queries array replaces all per-query configs, so send exactly one entry per statement (index-aligned). Use queries:[] to reset to inference, or omit queries to preserve the existing config.`,
+                }),
+                is_error: true,
+              }
+            }
+          }
+        }
+        return routeNotebookTool(() =>
+          modelToolsClient.setCellChartConfig(buffer_id, cell_id, patch),
+        )
+      }
+      case "set_cell_autorefresh": {
+        const { buffer_id, cell_id, value } =
+          (input as {
+            buffer_id: number
+            cell_id: string
+            value: boolean
+          }) || {}
+        setStatus(AIOperationStatus.ConfiguringChart, { cellId: cell_id })
+        return routeNotebookTool(() =>
+          modelToolsClient.setCellAutoRefresh(buffer_id, cell_id, value),
+        )
+      }
+      case "set_cell_chart_maximized": {
+        const { buffer_id, cell_id, value } =
+          (input as {
+            buffer_id: number
+            cell_id: string
+            value: boolean
+          }) || {}
+        setStatus(AIOperationStatus.ConfiguringChart, { cellId: cell_id })
+        return routeNotebookTool(() =>
+          modelToolsClient.setCellChartMaximized(buffer_id, cell_id, value),
+        )
+      }
+      case "apply_notebook_state": {
+        const { buffer_id, layout_mode, maximized_cell_id, variables, cells } =
+          (input as {
+            buffer_id: number
+            layout_mode?: "list" | "grid" | null
+            maximized_cell_id?: string | null
+            variables?: NotebookVariable[] | null
+            cells: Array<{
+              id?: string | null
+              value?: string | null
+              preserve_value?: boolean | null
+              type?: "sql" | "markdown" | null
+              mode?: CellMode | null
+              auto_refresh?: boolean | null
+              is_chart_maximized?: boolean | null
+              chart_config?: {
+                x_column?: string | null
+                name?: string | null
+                queries?: (ToolQueryChart | null)[] | null
+                right_axis?: ToolRightAxis | null
+              } | null
+              grid?: { x: number; y: number; w: number; h: number } | null
+            }>
+          }) || {}
+        setStatus(AIOperationStatus.BuildingNotebook)
+        // The MCP freshness gate is checked once before dispatch, but the
+        // per-variable/per-cell validation below awaits server round-trips.
+        // Snapshot user edits now and re-check before the destructive commit.
+        const userActionSeqAtStart = getUserActionSeq()
+        if (!Array.isArray(cells)) {
+          return {
+            content: JSON.stringify({
+              error_code: "validation",
+              message:
+                "VALIDATION_ERROR: cells must be an array of desired cell states.",
+            }),
+            is_error: true,
+          }
+        }
+        // Refuse the wipe foot-gun even if a misbehaving agent bypasses the
+        // bridge's minItems:1. delete_cell per-cell is the explicit path.
+        if (cells.length === 0) {
+          return {
+            content: JSON.stringify({
+              error_code: "validation",
+              message:
+                "VALIDATION_ERROR: cells must contain at least one entry. " +
+                "To delete every cell, use delete_cell per-cell — apply_notebook_state " +
+                "with cells:[] is rejected to prevent accidental wipes.",
+            }),
+            is_error: true,
+          }
+        }
+        for (const [idx, c] of cells.entries()) {
+          const hasValue = typeof c.value === "string"
+          const preserves = c.preserve_value === true
+          if (preserves === hasValue) {
+            return {
+              content: JSON.stringify({
+                error_code: "validation",
+                message: preserves
+                  ? `VALIDATION_ERROR: cells[${idx}] provides both value and preserve_value:true. Send exactly one per cell.`
+                  : `VALIDATION_ERROR: cells[${idx}] has no value. Send the full SQL text, or preserve_value:true to keep an existing cell's value unchanged.`,
+              }),
+              is_error: true,
+            }
+          }
+          if (preserves && !(typeof c.id === "string" && c.id.length > 0)) {
+            return {
+              content: JSON.stringify({
+                error_code: "validation",
+                message: `VALIDATION_ERROR: cells[${idx}] sets preserve_value:true without an existing cell id. New cells must send value.`,
+              }),
+              is_error: true,
+            }
+          }
+        }
+        // preserve_value cells defer to the live notebook for their SQL; the
+        // gate input must be that same full text, never a truncated read.
+        const resolveCellSql = (c: (typeof cells)[number]): string | null =>
+          typeof c.value === "string"
+            ? c.value
+            : typeof c.id === "string" && modelToolsClient.getCellSql
+              ? modelToolsClient.getCellSql(buffer_id, c.id)
+              : null
+        if (
+          variables !== undefined &&
+          variables !== null &&
+          !Array.isArray(variables)
+        ) {
+          return {
+            content: JSON.stringify({
+              error_code: "validation",
+              message:
+                "VALIDATION_ERROR: variables must be an ordered array of {name,value} entries (or null to preserve).",
+            }),
+            is_error: true,
+          }
+        }
+        if (Array.isArray(variables)) {
+          const seen = new Set<string>()
+          for (const [idx, variable] of variables.entries()) {
+            if (
+              !variable ||
+              typeof variable !== "object" ||
+              typeof variable.name !== "string" ||
+              typeof variable.value !== "string"
+            ) {
+              return {
+                content: JSON.stringify({
+                  error_code: "validation",
+                  message: `VALIDATION_ERROR: variables[${idx}] must be an object with string name and value fields.`,
+                }),
+                is_error: true,
+              }
+            }
+            const { name } = variable
+            if (!isValidVariableName(name)) {
+              return {
+                content: JSON.stringify({
+                  error_code: "validation",
+                  message: `VALIDATION_ERROR: variables[${idx}].name "${name}" is not a valid QuestDB identifier. First char must be a letter, underscore, or non-ASCII Unicode char (U+0080..U+FFFF); remaining chars may also include digits. No leading '@'.`,
+                }),
+                is_error: true,
+              }
+            }
+            if (seen.has(name)) {
+              return {
+                content: JSON.stringify({
+                  error_code: "validation",
+                  message: `VALIDATION_ERROR: duplicate variable name "${name}". Variables are ordered, but each name may only appear once.`,
+                }),
+                is_error: true,
+              }
+            }
+            seen.add(name)
+          }
+          for (let idx = 0; idx < variables.length; idx += 1) {
+            const shapeError = validateVariableShape(variables[idx])
+            if (shapeError) {
+              return {
+                content: JSON.stringify({
+                  error_code: "validation",
+                  message: `VALIDATION_ERROR: variables[${idx}] (${variables[idx].name}) shape check failed (${shapeError.kind}). Each value must be a single expression with no embedded assignments, top-level commas, or DECLARE syntax. Use parentheses to group expressions if commas are needed.`,
+                }),
+                is_error: true,
+              }
+            }
+          }
+          if (validateSql) {
+            for (let idx = 0; idx < variables.length; idx += 1) {
+              const result = await validateSql(
+                renderDeclareValidationQuery(variables.slice(0, idx + 1)),
+              )
+              if ("error" in result) {
+                return {
+                  content: JSON.stringify({
+                    error_code: "validation",
+                    message: `VALIDATION_ERROR: variables[${idx}] (${variables[idx].name}) failed QuestDB validation: ${result.error}`,
+                  }),
+                  is_error: true,
+                }
+              }
+            }
+          }
+        }
+        // Shared by the draw-invariant gate (below) and the post-apply
+        // auto-run loop's mode resolution.
+        const existingModes = new Map<string, CellMode | undefined>()
+        if (validateSql) {
+          await Promise.all(
+            cells.map(async (c) => {
+              if (typeof c.id !== "string" || c.id.length === 0) return
+              try {
+                const existing = await modelToolsClient.getCell(buffer_id, c.id)
+                existingModes.set(c.id, existing.mode)
+              } catch {
+                // Let applyNotebookState's all-or-nothing validation surface
+                // the precise unknown-cell error.
+              }
+            }),
+          )
+          const drawCells = cells.filter((c) => {
+            const resolved =
+              c.mode === undefined || c.mode === null
+                ? typeof c.id === "string"
+                  ? existingModes.get(c.id)
+                  : undefined
+                : c.mode
+            return resolved === "draw"
+          })
+          const decisions = await Promise.all(
+            drawCells.map(async (c): Promise<PermissionDecision> => {
+              const sql = resolveCellSql(c)
+              if (sql === null) {
+                return {
+                  granted: false,
+                  reason: denyReasonUnresolvedSql("apply_notebook_state"),
+                }
+              }
+              return requireAllDQL(sql, validateSql)
+            }),
+          )
+          const denied = decisions.find((d) => !d.granted)
+          if (denied && !denied.granted) {
+            return { content: denied.reason, is_error: true }
+          }
+        }
+        const request: ApplyNotebookStateRequest = {
+          layoutMode: layout_mode ?? null,
+          maximizedCellId:
+            maximized_cell_id === undefined ? undefined : maximized_cell_id,
+          variables:
+            variables === undefined || variables === null
+              ? undefined
+              : variables,
+          cells: cells.map<ApplyNotebookStateCellRequest>((c) => {
+            const cell: ApplyNotebookStateCellRequest =
+              c.preserve_value === true
+                ? { preserveValue: true }
+                : { value: c.value }
+            if (c.id !== undefined && c.id !== null) cell.id = c.id
+            if (c.type === "sql" || c.type === "markdown") cell.type = c.type
+            if (c.mode !== undefined && c.mode !== null) cell.mode = c.mode
+            if (c.auto_refresh !== undefined && c.auto_refresh !== null)
+              cell.autoRefresh = c.auto_refresh
+            if (
+              c.is_chart_maximized !== undefined &&
+              c.is_chart_maximized !== null
+            )
+              cell.isChartMaximized = c.is_chart_maximized
+            if (c.chart_config) {
+              const cfg = c.chart_config
+              const chartConfig: ChartConfig = {
+                xColumn: cfg.x_column ?? null,
+                queries: (cfg.queries ?? []).map((q) =>
+                  q ? mapQueryChart(q) : null,
+                ),
+              }
+              if (cfg.name) chartConfig.name = cfg.name
+              if (cfg.right_axis)
+                chartConfig.rightAxis = mapRightAxis(cfg.right_axis)
+              cell.chartConfig = chartConfig
+            }
+            if (c.grid) cell.grid = c.grid
+            return cell
+          }),
+        }
+        if (signal?.aborted) {
+          return {
+            content: JSON.stringify({
+              error_code: "aborted",
+              message: "ABORTED: notebook state was not applied.",
+            }),
+            is_error: true,
+          }
+        }
+        const staleBaseline =
+          toolContext?.notebookReadSeq ?? userActionSeqAtStart
+        if (getUserActionSeq() !== staleBaseline) {
+          return {
+            content: JSON.stringify({
+              error_code: "stale",
+              message:
+                "STATE_STALE: The user changed the notebook while applying. " +
+                `Call ${reSyncTool(toolContext)} to re-sync, then retry. ` +
+                STALE_RETRY_GUIDANCE,
+            }),
+            is_error: true,
+          }
+        }
+        try {
+          const out = await modelToolsClient.applyNotebookState(
+            buffer_id,
+            request,
+          )
+          // buildAppliedCells pushes new-cell ids to `applied.added` in
+          type ResolvedRun = {
+            cellId: string
+            value: string
+            runnable: boolean
+          }
+          const resolved: ResolvedRun[] = []
+          let newCellIdx = 0
+          for (const c of cells) {
+            const requestedId =
+              typeof c.id === "string" && c.id.length > 0 ? c.id : undefined
+            const cellId = requestedId ?? out.applied.added[newCellIdx++]
+            if (!cellId) continue
+            // Undefined existing mode === "run" (NotebookCell.mode comment).
+            const resolvedMode: CellMode =
+              c.mode === undefined || c.mode === null
+                ? requestedId !== undefined
+                  ? (existingModes.get(requestedId) ?? "run")
+                  : "run"
+                : c.mode
+            // Post-apply, getCellSql sees the committed notebook, so preserved
+            // cells resolve to their kept full value here.
+            const value = resolveCellSql(c)
+            // Cell kind is sticky, so a preserved markdown cell (no type in the
+            // request) is still markdown post-apply — read it from the committed
+            // notebook and never auto-run prose as SQL.
+            const isMarkdown =
+              modelToolsClient.getCellType?.(buffer_id, cellId) === "markdown"
+            const runnable =
+              !isMarkdown &&
+              resolvedMode === "run" &&
+              value !== null &&
+              value.trim().length > 0
+            resolved.push({ cellId, value: value ?? "", runnable })
+          }
+          type RunEntry = {
+            cellId: string
+            success: boolean
+            queryCount?: number
+            results?: string[]
+            error?: string
+            unverified?: boolean
+            note?: string
+            skipped?: boolean
+          }
+          const settled = await Promise.all(
+            resolved.map(async (r): Promise<RunEntry | null> => {
+              if (!r.runnable) return null
+              if (perms && validateSql) {
+                const decision = await classifyAndCheckSqlForAutoRun(
+                  r.value,
+                  validateSql,
+                )
+                if (decision.action === "deny") {
+                  return {
+                    cellId: r.cellId,
+                    success: false,
+                    error: decision.reason,
+                  }
+                }
+                if (decision.action === "skip") {
+                  return {
+                    cellId: r.cellId,
+                    success: true,
+                    skipped: true,
+                    note: decision.reason,
+                  }
+                }
+              }
+              try {
+                const result = await modelToolsClient.runCell(
+                  buffer_id,
+                  r.cellId,
+                  signal,
+                  perms && validateSql ? r.value : undefined,
+                )
+                return {
+                  cellId: r.cellId,
+                  success: result.success,
+                  queryCount: result.queryCount,
+                  results: result.results,
+                  ...(result.unverified
+                    ? { unverified: result.unverified, note: result.note }
+                    : {}),
+                }
+              } catch (runErr) {
+                const message =
+                  runErr instanceof Error ? runErr.message : String(runErr)
+                return { cellId: r.cellId, success: false, error: message }
+              }
+            }),
+          )
+          const runs = settled.filter(
+            (entry): entry is RunEntry => entry !== null,
+          )
+          return { content: JSON.stringify({ ...out, runs }) }
+        } catch (e) {
+          if (e instanceof NotebookToolError) {
+            return {
+              is_error: true,
+              content: JSON.stringify({
+                error_code: e.code,
+                message: e.message,
+                hint: notebookErrorHint(e.code),
+              }),
+            }
+          }
+          if (e instanceof Error && e.name === "ApplyNotebookStateError") {
+            return {
+              is_error: true,
+              content: JSON.stringify({
+                error_code: "validation",
+                message: `VALIDATION_ERROR: ${e.message}`,
+                hint: "No state was changed. Fix the request and retry; remember the cells array is the COMPLETE desired list.",
+              }),
+            }
+          }
+          const message = e instanceof Error ? e.message : String(e)
+          return {
+            is_error: true,
+            content: `Tool execution error: ${message}`,
+          }
+        }
+      }
+      case "set_cell_maximized": {
+        const { buffer_id, cell_id } =
+          (input as { buffer_id: number; cell_id: string | null }) || {}
+        setStatus(AIOperationStatus.ConfiguringLayout, {
+          cellId: cell_id ?? undefined,
+        })
+        return routeNotebookTool(() =>
+          modelToolsClient.setCellMaximized(buffer_id, cell_id),
+        )
+      }
+      case "run_query": {
+        const { sql, limit } =
+          (input as { sql?: string; limit?: number | null }) || {}
+        if (typeof sql !== "string" || sql.trim().length === 0) {
+          return {
+            content: JSON.stringify({
+              error:
+                "sql parameter is required and must be a non-empty string.",
+            }),
+            is_error: true,
+          }
+        }
+        if (perms && validateSql) {
+          const decision = await classifyAndCheckSqlForRunQuery(
+            sql,
+            perms,
+            validateSql,
+          )
+          if (!decision.granted) {
+            return { content: decision.reason, is_error: true }
+          }
+        }
+        let formattedSql = sql
+        try {
+          formattedSql = formatSql(sql)
+        } catch {
+          // Fall back to raw SQL if the formatter can't parse it.
+        }
+        setStatus(AIOperationStatus.RunningQuery, { content: formattedSql })
+        try {
+          const requestedLimit =
+            typeof limit === "number" && Number.isFinite(limit)
+              ? limit
+              : RUN_QUERY_DEFAULT_LIMIT
+          const raw = await modelToolsClient.runQueryRaw(
+            sql,
+            requestedLimit,
+            signal,
+          )
+          // Schema panel listens for MSG_QUERY_SCHEMA and refreshes its cache.
+          if (raw.type === "ddl" || raw.type === "dml") {
+            if (toolContext) {
+              toolContext.sqlWriteExecuted = true
+            }
+            eventBus.publish(EventType.MSG_QUERY_SCHEMA)
+          }
+          const payload = buildRunQueryPayload(raw, requestedLimit)
+          const unverified =
+            raw.type === "error" && isUnverifiableExecError(raw)
+          return {
+            content: JSON.stringify(
+              unverified
+                ? { ...payload, unverified: true, note: UNVERIFIED_RUN_NOTE }
+                : payload,
+            ),
+            is_error: raw.type === "error" ? true : undefined,
+          }
+        } catch (e) {
+          const message = e instanceof Error ? e.message : String(e)
+          const unverified = isUnverifiableExecError({
+            type: "error",
+            error: message,
+          })
+          return {
+            content: JSON.stringify({
+              error: `run_query failed: ${message}`,
+              ...(unverified
+                ? { unverified: true, note: UNVERIFIED_RUN_NOTE }
+                : {}),
+            }),
+            is_error: true,
+          }
+        }
+      }
+      default:
+        return { content: `Unknown tool: ${toolName}`, is_error: true }
+    }
+  } catch (error) {
+    return {
+      content: `Tool execution error: ${error instanceof Error ? error.message : "Unknown error"}`,
+      is_error: true,
+    }
+  }
+}
diff --git a/src/utils/tools/permissions.test.ts b/src/utils/tools/permissions.test.ts
new file mode 100644
index 000000000..b0e37c506
--- /dev/null
+++ b/src/utils/tools/permissions.test.ts
@@ -0,0 +1,496 @@
+import { describe, it, expect, vi } from "vitest"
+import {
+  DEFAULT_DENIED,
+  DEFAULT_GRANTED,
+  checkToolPermission,
+  classifyAndCheckSqlForAutoRun,
+  classifyAndCheckSqlForExecution,
+  classifyAndCheckSqlForRunQuery,
+  classifyStatements,
+  normalizePermissions,
+  requireAllDQL,
+  runPermissionGate,
+  type Permissions,
+  type ToolCategory,
+} from "./permissions"
+import type { ValidateQueryResult } from "../questdb/types"
+
+// Three-scope state fixtures. Cascade: write ⇒ read ⇒ grantSchemaAccess.
+const ALL_OFF: Permissions = {
+  grantSchemaAccess: false,
+  read: false,
+  write: false,
+}
+const SCHEMA_ONLY: Permissions = {
+  grantSchemaAccess: true,
+  read: false,
+  write: false,
+}
+const READ_ONLY: Permissions = {
+  grantSchemaAccess: true,
+  read: true,
+  write: false,
+}
+const ALL_ON: Permissions = {
+  grantSchemaAccess: true,
+  read: true,
+  write: true,
+}
+
+const TEST_CATEGORY_MAP: Record<string, ToolCategory> = {
+  get_tables: "schema",
+  get_table_schema: "schema",
+  get_table_details: "schema",
+  run_query: "sql",
+  run_cell: "sql",
+}
+const testCategoryFor = (name: string): ToolCategory =>
+  TEST_CATEGORY_MAP[name] ?? "free"
+
+describe("normalizePermissions cascade (write ⇒ read ⇒ grantSchemaAccess)", () => {
+  it("write:true cascades to all true", () => {
+    // Given a permissions object with write enabled
+    // When normalized
+    // Then read and grantSchemaAccess are forced on
+    expect(normalizePermissions(ALL_ON)).toEqual(ALL_ON)
+  })
+
+  it("read:true (write:false) keeps write off but forces schema on", () => {
+    // Given read enabled without write
+    // When normalized
+    // Then grantSchemaAccess is forced on and write stays off
+    expect(normalizePermissions(READ_ONLY)).toEqual(READ_ONLY)
+  })
+
+  it("only grantSchemaAccess:true is left unchanged (read/write stay false)", () => {
+    // Given schema access alone
+    // When normalized
+    // Then nothing cascades up; read and write stay off
+    expect(normalizePermissions(SCHEMA_ONLY)).toEqual(SCHEMA_ONLY)
+  })
+
+  it("all false stays all false", () => {
+    // Given every scope denied
+    // When normalized
+    // Then the object is unchanged
+    expect(normalizePermissions(ALL_OFF)).toEqual(ALL_OFF)
+  })
+
+  it("impossible triple read:true with schema:false cascades up", () => {
+    // Given a hand-edited triple where read is on but schema was left off
+    const handEdited: Permissions = {
+      grantSchemaAccess: false,
+      read: true,
+      write: false,
+    }
+    // When normalized
+    // Then schema is forced on and write stays off
+    expect(normalizePermissions(handEdited)).toEqual(READ_ONLY)
+  })
+
+  it("impossible triple write:true with read/schema:false cascades to all true", () => {
+    // Given a hand-edited triple where write is on but read/schema were left off
+    const handEdited: Permissions = {
+      grantSchemaAccess: false,
+      read: false,
+      write: true,
+    }
+    // When normalized
+    // Then every scope is forced on
+    expect(normalizePermissions(handEdited)).toEqual(ALL_ON)
+  })
+
+  it("default constants match the cascade invariant", () => {
+    // Given the exported defaults
+    // When compared against the canonical fixtures
+    // Then they hold the cascade invariant
+    expect(DEFAULT_GRANTED).toEqual(READ_ONLY)
+    expect(DEFAULT_DENIED).toEqual(ALL_OFF)
+  })
+})
+
+describe("checkToolPermission(name, category, perms)", () => {
+  it("free tools are granted regardless of permissions", () => {
+    for (const perms of [ALL_OFF, SCHEMA_ONLY, READ_ONLY, ALL_ON]) {
+      expect(
+        checkToolPermission("apply_notebook_state", "free", perms),
+      ).toEqual({
+        granted: true,
+      })
+      expect(checkToolPermission("validate_query", "free", perms)).toEqual({
+        granted: true,
+      })
+    }
+  })
+
+  it("schema tools require grantSchemaAccess", () => {
+    expect(checkToolPermission("get_tables", "schema", ALL_OFF).granted).toBe(
+      false,
+    )
+    expect(checkToolPermission("get_tables", "schema", SCHEMA_ONLY)).toEqual({
+      granted: true,
+    })
+    expect(checkToolPermission("get_tables", "schema", READ_ONLY)).toEqual({
+      granted: true,
+    })
+    expect(checkToolPermission("get_tables", "schema", ALL_ON)).toEqual({
+      granted: true,
+    })
+  })
+
+  it("schema denial reason names the missing scope", () => {
+    const decision = checkToolPermission("get_tables", "schema", ALL_OFF)
+    if (decision.granted) throw new Error("expected deny")
+    expect(decision.reason).toMatch(/PERMISSION_DENIED/)
+    expect(decision.reason).toMatch(/get_tables/)
+    expect(decision.reason).toMatch(/'grantSchemaAccess'/)
+  })
+
+  it("sql-category tools fail closed under checkToolPermission — caller must use the SQL helpers", () => {
+    const decision = checkToolPermission("run_query", "sql", ALL_ON)
+    expect(decision.granted).toBe(false)
+  })
+})
+
+const dqlValidate = (sql = "SELECT 1"): ValidateQueryResult => ({
+  query: sql,
+  columns: [{ name: "c1", type: "LONG" }],
+  timestamp: -1,
+})
+const ddlValidate: ValidateQueryResult = { queryType: "CREATE TABLE" }
+const dmlValidate: ValidateQueryResult = { queryType: "INSERT" }
+const errorValidate: ValidateQueryResult = {
+  query: "BAD",
+  position: 0,
+  error: "syntax",
+}
+
+const validatorFor = (
+  map: Record<string, ValidateQueryResult>,
+): ((sql: string) => Promise<ValidateQueryResult>) => {
+  return (sql) => {
+    const trimmed = sql.trim()
+    const hit = map[trimmed]
+    return Promise.resolve(hit ?? dqlValidate(trimmed))
+  }
+}
+
+describe("classifyStatements", () => {
+  it("returns [] for empty input", async () => {
+    const validate = vi.fn()
+    expect(await classifyStatements("   \n", validate)).toEqual([])
+    expect(validate).not.toHaveBeenCalled()
+  })
+
+  it("classifies a single DQL statement as DQL", async () => {
+    const validate = vi.fn().mockResolvedValue(dqlValidate("SELECT 1"))
+    const out = await classifyStatements("SELECT 1", validate)
+    expect(out).toEqual([{ sql: "SELECT 1", klass: "DQL" }])
+  })
+
+  it("classifies a single DDL statement as DDL_DML with queryType", async () => {
+    const validate = vi.fn().mockResolvedValue(ddlValidate)
+    const out = await classifyStatements("CREATE TABLE t (a INT)", validate)
+    expect(out).toEqual([
+      {
+        sql: "CREATE TABLE t (a INT)",
+        klass: "DDL_DML",
+        queryType: "CREATE TABLE",
+      },
+    ])
+  })
+
+  it("classifies syntax errors as ERROR", async () => {
+    const validate = vi.fn().mockResolvedValue(errorValidate)
+    const out = await classifyStatements("BAD", validate)
+    expect(out).toEqual([{ sql: "BAD", klass: "ERROR" }])
+  })
+
+  it("splits and classifies each statement of a multi-statement cell", async () => {
+    const validate = validatorFor({
+      "DROP TABLE x": ddlValidate,
+      "SELECT 1": dqlValidate("SELECT 1"),
+      "INSERT INTO t VALUES (1)": dmlValidate,
+    })
+    const out = await classifyStatements(
+      "DROP TABLE x; SELECT 1; INSERT INTO t VALUES (1)",
+      validate,
+    )
+    expect(out).toEqual([
+      { sql: "DROP TABLE x", klass: "DDL_DML", queryType: "CREATE TABLE" },
+      { sql: "SELECT 1", klass: "DQL" },
+      {
+        sql: "INSERT INTO t VALUES (1)",
+        klass: "DDL_DML",
+        queryType: "INSERT",
+      },
+    ])
+  })
+
+  it("propagates validate failures (callers fail closed)", async () => {
+    const validate = vi.fn().mockRejectedValue(new Error("network down"))
+    await expect(classifyStatements("SELECT 1", validate)).rejects.toThrow(
+      /network down/,
+    )
+  })
+})
+
+describe("classifyAndCheckSqlForRunQuery", () => {
+  it("denies empty SQL without calling validate", async () => {
+    const validate = vi.fn()
+    const decision = await classifyAndCheckSqlForRunQuery(
+      "  ",
+      ALL_ON,
+      validate,
+    )
+    expect(decision.granted).toBe(false)
+    expect(validate).not.toHaveBeenCalled()
+  })
+
+  it("DQL with read but no write → granted", async () => {
+    const validate = vi.fn().mockResolvedValue(dqlValidate("SELECT 1"))
+    expect(
+      await classifyAndCheckSqlForRunQuery("SELECT 1", READ_ONLY, validate),
+    ).toEqual({ granted: true })
+  })
+
+  it("DQL with neither read nor write → denied for read", async () => {
+    const validate = vi.fn().mockResolvedValue(dqlValidate("SELECT 1"))
+    const decision = await classifyAndCheckSqlForRunQuery(
+      "SELECT 1",
+      SCHEMA_ONLY,
+      validate,
+    )
+    if (decision.granted) throw new Error("expected deny")
+    expect(decision.reason).toMatch(/'read' permission/)
+  })
+
+  it("DDL without write → denied; reason names the queryType", async () => {
+    const validate = vi.fn().mockResolvedValue(ddlValidate)
+    const decision = await classifyAndCheckSqlForRunQuery(
+      "CREATE TABLE t (a INT)",
+      READ_ONLY,
+      validate,
+    )
+    if (decision.granted) throw new Error("expected deny")
+    expect(decision.reason).toMatch(/CREATE TABLE/)
+    expect(decision.reason).toMatch(/'write' permission/)
+  })
+
+  it("DDL with write → granted", async () => {
+    const validate = vi.fn().mockResolvedValue(ddlValidate)
+    expect(
+      await classifyAndCheckSqlForRunQuery(
+        "CREATE TABLE t (a INT)",
+        ALL_ON,
+        validate,
+      ),
+    ).toEqual({ granted: true })
+  })
+
+  it("multi-statement mixed (DDL + DQL) → denies on DDL when no write", async () => {
+    const validate = validatorFor({
+      "DROP TABLE x": ddlValidate,
+      "SELECT 1": dqlValidate("SELECT 1"),
+    })
+    const decision = await classifyAndCheckSqlForRunQuery(
+      "DROP TABLE x; SELECT 1",
+      READ_ONLY,
+      validate,
+    )
+    expect(decision.granted).toBe(false)
+  })
+
+  it("validate failure → fail-closed deny", async () => {
+    const validate = vi.fn().mockRejectedValue(new Error("network down"))
+    const decision = await classifyAndCheckSqlForRunQuery(
+      "SELECT 1",
+      READ_ONLY,
+      validate,
+    )
+    if (decision.granted) throw new Error("expected deny")
+    expect(decision.reason).toMatch(/network down/)
+  })
+})
+
+describe("classifyAndCheckSqlForExecution", () => {
+  it("DQL is granted at every level — no rows return to the agent, results stay in the console", async () => {
+    const validate = vi.fn().mockResolvedValue(dqlValidate("SELECT 1"))
+    for (const perms of [ALL_OFF, SCHEMA_ONLY, READ_ONLY, ALL_ON]) {
+      expect(
+        await classifyAndCheckSqlForExecution("SELECT 1", perms, validate),
+      ).toEqual({ granted: true })
+    }
+  })
+
+  it("DDL without write → denied", async () => {
+    const validate = vi.fn().mockResolvedValue(ddlValidate)
+    const decision = await classifyAndCheckSqlForExecution(
+      "CREATE TABLE t (a INT)",
+      READ_ONLY,
+      validate,
+    )
+    if (decision.granted) throw new Error("expected deny")
+    expect(decision.reason).toMatch(/'write' permission/)
+  })
+
+  it("DML without write → denied", async () => {
+    const validate = vi.fn().mockResolvedValue(dmlValidate)
+    const decision = await classifyAndCheckSqlForExecution(
+      "INSERT INTO t VALUES (1)",
+      READ_ONLY,
+      validate,
+    )
+    expect(decision.granted).toBe(false)
+  })
+
+  it("DDL with write → granted", async () => {
+    const validate = vi.fn().mockResolvedValue(ddlValidate)
+    expect(
+      await classifyAndCheckSqlForExecution(
+        "CREATE TABLE t (a INT)",
+        ALL_ON,
+        validate,
+      ),
+    ).toEqual({ granted: true })
+  })
+
+  it("multi-statement mixed (DDL + DQL) → denies on DDL when no write", async () => {
+    const validate = validatorFor({
+      "DROP TABLE x": ddlValidate,
+      "SELECT 1": dqlValidate("SELECT 1"),
+    })
+    const decision = await classifyAndCheckSqlForExecution(
+      "DROP TABLE x; SELECT 1",
+      READ_ONLY,
+      validate,
+    )
+    expect(decision.granted).toBe(false)
+  })
+
+  it("validate failure → fail-closed deny", async () => {
+    const validate = vi.fn().mockRejectedValue(new Error("network down"))
+    const decision = await classifyAndCheckSqlForExecution(
+      "SELECT 1",
+      ALL_OFF,
+      validate,
+    )
+    if (decision.granted) throw new Error("expected deny")
+    expect(decision.reason).toMatch(/network down/)
+  })
+})
+
+describe("classifyAndCheckSqlForAutoRun (apply_notebook_state / add_cell)", () => {
+  it("DQL → run", async () => {
+    const validate = vi.fn().mockResolvedValue(dqlValidate("SELECT 1"))
+    expect(await classifyAndCheckSqlForAutoRun("SELECT 1", validate)).toEqual({
+      action: "run",
+    })
+  })
+
+  it("DML → skip, points at run_cell (writes never auto-run)", async () => {
+    const validate = vi.fn().mockResolvedValue(dmlValidate)
+    const decision = await classifyAndCheckSqlForAutoRun(
+      "INSERT INTO t VALUES (1)",
+      validate,
+    )
+    if (decision.action !== "skip") throw new Error("expected skip")
+    expect(decision.reason).toMatch(/AUTO_RUN_SKIPPED/)
+    expect(decision.reason).toMatch(/run_cell/)
+  })
+
+  it("mixed DQL + DML cell → skip (statement-level, not cell typing)", async () => {
+    const validate = validatorFor({
+      "SELECT 1": dqlValidate("SELECT 1"),
+      "INSERT INTO t VALUES (1)": dmlValidate,
+    })
+    const decision = await classifyAndCheckSqlForAutoRun(
+      "SELECT 1; INSERT INTO t VALUES (1)",
+      validate,
+    )
+    expect(decision.action).toBe("skip")
+  })
+
+  it("validate failure → fail-closed deny", async () => {
+    const validate = vi.fn().mockRejectedValue(new Error("network down"))
+    const decision = await classifyAndCheckSqlForAutoRun("SELECT 1", validate)
+    if (decision.action !== "deny") throw new Error("expected deny")
+    expect(decision.reason).toMatch(/network down/)
+  })
+})
+
+describe("requireAllDQL (draw invariant)", () => {
+  it("empty cell allowed", async () => {
+    const validate = vi.fn()
+    expect(await requireAllDQL("   \n", validate)).toEqual({ granted: true })
+    expect(validate).not.toHaveBeenCalled()
+  })
+
+  it("single DQL allowed", async () => {
+    const validate = vi.fn().mockResolvedValue(dqlValidate("SELECT 1"))
+    expect(await requireAllDQL("SELECT 1", validate)).toEqual({ granted: true })
+  })
+
+  it("single DDL denied regardless of permissions", async () => {
+    const validate = vi.fn().mockResolvedValue(ddlValidate)
+    const decision = await requireAllDQL("DROP TABLE x", validate)
+    if (decision.granted) throw new Error("expected deny")
+    expect(decision.reason).toMatch(/Cannot draw a write query/)
+    expect(decision.reason).toMatch(/CREATE TABLE/)
+  })
+
+  it("multi-statement with mixed DQL and DDL is denied", async () => {
+    const validate = validatorFor({
+      "SELECT 1": dqlValidate("SELECT 1"),
+      "DROP TABLE x": ddlValidate,
+    })
+    const decision = await requireAllDQL("SELECT 1; DROP TABLE x", validate)
+    expect(decision.granted).toBe(false)
+  })
+
+  it("statement with syntax error passes through (executor surfaces it)", async () => {
+    const validate = vi.fn().mockResolvedValue(errorValidate)
+    expect(await requireAllDQL("BAD", validate)).toEqual({ granted: true })
+  })
+
+  it("validate failure → fail-closed deny", async () => {
+    const validate = vi.fn().mockRejectedValue(new Error("network down"))
+    const decision = await requireAllDQL("SELECT 1", validate)
+    if (decision.granted) throw new Error("expected deny")
+    expect(decision.reason).toMatch(/Cannot classify cell SQL/)
+  })
+})
+
+describe("runPermissionGate", () => {
+  it("free tool short-circuits to granted", () => {
+    const decision = runPermissionGate("create_notebook", {
+      permissions: ALL_OFF,
+      categoryFor: testCategoryFor,
+    })
+    expect(decision).toEqual({ granted: true })
+  })
+
+  it("schema tool denied without grantSchemaAccess", () => {
+    const decision = runPermissionGate("get_tables", {
+      permissions: ALL_OFF,
+      categoryFor: testCategoryFor,
+    })
+    expect(decision.granted).toBe(false)
+  })
+
+  it("schema tool granted with grantSchemaAccess only", () => {
+    const decision = runPermissionGate("get_tables", {
+      permissions: SCHEMA_ONLY,
+      categoryFor: testCategoryFor,
+    })
+    expect(decision).toEqual({ granted: true })
+  })
+
+  it("sql-category tools pass the gate (their case bodies apply the SQL helpers)", () => {
+    const decision = runPermissionGate("run_query", {
+      permissions: ALL_OFF,
+      categoryFor: testCategoryFor,
+    })
+    expect(decision).toEqual({ granted: true })
+  })
+})
diff --git a/src/utils/tools/permissions.ts b/src/utils/tools/permissions.ts
new file mode 100644
index 000000000..7785ea92f
--- /dev/null
+++ b/src/utils/tools/permissions.ts
@@ -0,0 +1,251 @@
+import type {
+  ValidateQueryResult,
+  ValidateQuerySuccessResult,
+} from "../questdb/types"
+import { getQueriesFromText } from "../../scenes/Editor/Monaco/utils"
+
+export type Permissions = {
+  grantSchemaAccess: boolean
+  read: boolean
+  write: boolean
+}
+
+export type ToolCategory = "free" | "schema" | "sql"
+
+export const DEFAULT_GRANTED: Permissions = {
+  grantSchemaAccess: true,
+  read: true,
+  write: false,
+}
+
+export const DEFAULT_DENIED: Permissions = {
+  grantSchemaAccess: false,
+  read: false,
+  write: false,
+}
+
+export const normalizePermissions = (raw: Permissions): Permissions => {
+  if (raw.write) return { grantSchemaAccess: true, read: true, write: true }
+  if (raw.read) return { grantSchemaAccess: true, read: true, write: false }
+  return { grantSchemaAccess: raw.grantSchemaAccess, read: false, write: false }
+}
+
+export type PermissionDecision =
+  | { granted: true }
+  | { granted: false; reason: string }
+
+const denyReasonForSchemaTool = (tool: string): string =>
+  `PERMISSION_DENIED: tool '${tool}' requires the 'grantSchemaAccess' permission. ` +
+  "Ask the user to grant it in the QuestDB console (footer → MCP popover or AI Assistant settings)."
+
+const denyReasonForWriteSql = (queryType: string): string =>
+  `PERMISSION_DENIED: this SQL is '${queryType}' (write operation) and ` +
+  "requires the 'write' permission. Ask the user to grant it in the " +
+  "QuestDB console (footer → MCP popover or AI Assistant settings)."
+
+const denyReasonForReadSql = (): string =>
+  "PERMISSION_DENIED: this SQL needs the 'read' permission to execute. " +
+  "Ask the user to grant it in the QuestDB console (footer → MCP popover or AI Assistant settings)."
+
+const denyReasonNoSql = (tool: string): string =>
+  `PERMISSION_DENIED: tool '${tool}' requires a non-empty 'sql' argument.`
+
+export const denyReasonUnresolvedSql = (tool: string): string =>
+  `PERMISSION_DENIED: could not resolve SQL for tool '${tool}'. ` +
+  "Retry after refreshing notebook state; refusing to execute because the SQL cannot be classified safely."
+
+const denyReasonForDrawWrite = (queryType: string): string =>
+  `Cannot draw a write query ('${queryType}'). ` +
+  "Draw cells must contain only DQL (SELECT). Switch to Run mode to execute this SQL."
+
+const denyReasonFailClosedClassify = (
+  context: "execution" | "draw",
+  message: string,
+): string =>
+  context === "draw"
+    ? `Cannot classify cell SQL (validate request failed: ${message}). ` +
+      "Refusing to draw until the query can be classified safely."
+    : `PERMISSION_DENIED: could not classify SQL (validate request failed: ${message}). ` +
+      "Treating as a write to be safe; ask the user to grant 'write' or fix connectivity to QuestDB."
+
+export const checkToolPermission = (
+  tool: string,
+  category: ToolCategory,
+  perms: Permissions,
+): PermissionDecision => {
+  if (category === "free") return { granted: true }
+  if (category === "schema") {
+    return perms.grantSchemaAccess
+      ? { granted: true }
+      : { granted: false, reason: denyReasonForSchemaTool(tool) }
+  }
+  return {
+    granted: false,
+    reason: `PERMISSION_DENIED: tool '${tool}' requires SQL classification but was checked as a plain tool.`,
+  }
+}
+
+const isDqlResult = (
+  res: ValidateQuerySuccessResult,
+): res is Extract<ValidateQuerySuccessResult, { columns: unknown }> =>
+  "columns" in res
+
+export type StatementClass = "DQL" | "DDL_DML" | "ERROR"
+
+export type ClassifiedStatement = {
+  sql: string
+  klass: StatementClass
+  queryType?: string
+}
+
+export const classifyStatements = async (
+  sql: string,
+  validate: (sql: string) => Promise<ValidateQueryResult>,
+): Promise<ClassifiedStatement[]> => {
+  const statements = getQueriesFromText(sql)
+  if (statements.length === 0) return []
+  const results = await Promise.all(
+    statements.map(async (stmt): Promise<ClassifiedStatement> => {
+      const result = await validate(stmt)
+      if ("error" in result) return { sql: stmt, klass: "ERROR" }
+      if (isDqlResult(result)) return { sql: stmt, klass: "DQL" }
+      return { sql: stmt, klass: "DDL_DML", queryType: result.queryType }
+    }),
+  )
+  return results
+}
+
+export const classifyAndCheckSqlForRunQuery = async (
+  sql: string,
+  perms: Permissions,
+  validate: (sql: string) => Promise<ValidateQueryResult>,
+): Promise<PermissionDecision> => {
+  if (sql.trim() === "") {
+    return { granted: false, reason: denyReasonNoSql("run_query") }
+  }
+  let stmts: ClassifiedStatement[]
+  try {
+    stmts = await classifyStatements(sql, validate)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "validate failed"
+    return {
+      granted: false,
+      reason: denyReasonFailClosedClassify("execution", message),
+    }
+  }
+  const writeStmt = stmts.find((s) => s.klass === "DDL_DML")
+  if (writeStmt && !perms.write) {
+    return {
+      granted: false,
+      reason: denyReasonForWriteSql(writeStmt.queryType ?? "write"),
+    }
+  }
+  const hasDql = stmts.some((s) => s.klass === "DQL")
+  if (hasDql && !perms.read && !perms.write) {
+    return { granted: false, reason: denyReasonForReadSql() }
+  }
+  return { granted: true }
+}
+
+export const classifyAndCheckSqlForExecution = async (
+  sql: string,
+  perms: Permissions,
+  validate: (sql: string) => Promise<ValidateQueryResult>,
+): Promise<PermissionDecision> => {
+  if (sql.trim() === "") {
+    return { granted: false, reason: denyReasonNoSql("run_cell") }
+  }
+  let stmts: ClassifiedStatement[]
+  try {
+    stmts = await classifyStatements(sql, validate)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "validate failed"
+    return {
+      granted: false,
+      reason: denyReasonFailClosedClassify("execution", message),
+    }
+  }
+  const writeStmt = stmts.find((s) => s.klass === "DDL_DML")
+  if (writeStmt && !perms.write) {
+    return {
+      granted: false,
+      reason: denyReasonForWriteSql(writeStmt.queryType ?? "write"),
+    }
+  }
+  return { granted: true }
+}
+
+export type AutoRunDecision =
+  | { action: "run" }
+  | { action: "deny"; reason: string }
+  | { action: "skip"; reason: string }
+
+const skipReasonForWrite = (queryType: string): string =>
+  `AUTO_RUN_SKIPPED: this cell contains a '${queryType}' (write) statement, ` +
+  "so it was NOT executed — agent flows never auto-run DDL/DML. " +
+  "Confirm with the user, then call run_cell explicitly."
+
+export const classifyAndCheckSqlForAutoRun = async (
+  sql: string,
+  validate: (sql: string) => Promise<ValidateQueryResult>,
+): Promise<AutoRunDecision> => {
+  let stmts: ClassifiedStatement[]
+  try {
+    stmts = await classifyStatements(sql, validate)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "validate failed"
+    return {
+      action: "deny",
+      reason: denyReasonFailClosedClassify("execution", message),
+    }
+  }
+  const writeStmt = stmts.find((s) => s.klass === "DDL_DML")
+  if (!writeStmt) return { action: "run" }
+  return {
+    action: "skip",
+    reason: skipReasonForWrite(writeStmt.queryType ?? "write"),
+  }
+}
+
+// Permission-independent: drawing a write query is semantically incoherent,
+// not a perms question. Empty cells pass.
+export const requireAllDQL = async (
+  sql: string,
+  validate: (sql: string) => Promise<ValidateQueryResult>,
+): Promise<PermissionDecision> => {
+  let stmts: ClassifiedStatement[]
+  try {
+    stmts = await classifyStatements(sql, validate)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "validate failed"
+    return {
+      granted: false,
+      reason: denyReasonFailClosedClassify("draw", message),
+    }
+  }
+  if (stmts.length === 0) return { granted: true }
+  const bad = stmts.find((s) => s.klass === "DDL_DML")
+  if (bad) {
+    return {
+      granted: false,
+      reason: denyReasonForDrawWrite(bad.queryType ?? "write"),
+    }
+  }
+  return { granted: true }
+}
+
+export type PermissionGateContext = {
+  permissions: Permissions
+  categoryFor: (tool: string) => ToolCategory
+}
+
+// SQL-category tools are NOT gated here; they call the intent-specific SQL
+// helpers at the dispatch case so run_query vs run_cell apply different rules.
+export const runPermissionGate = (
+  tool: string,
+  ctx: PermissionGateContext,
+): PermissionDecision => {
+  const category = ctx.categoryFor(tool)
+  if (category === "free" || category === "sql") return { granted: true }
+  return checkToolPermission(tool, category, ctx.permissions)
+}
diff --git a/src/utils/tools/runQuery.test.ts b/src/utils/tools/runQuery.test.ts
new file mode 100644
index 000000000..f09fb6314
--- /dev/null
+++ b/src/utils/tools/runQuery.test.ts
@@ -0,0 +1,201 @@
+import { describe, expect, it, vi } from "vitest"
+import { Type } from "../questdb/types"
+import {
+  buildRunQueryPayload,
+  clampRunQueryLimit,
+  mapQueryRawToResult,
+  RUN_QUERY_MAX_LIMIT,
+  type RunQueryRawResult,
+} from "./runQuery"
+
+describe("buildRunQueryPayload", () => {
+  const dql = (
+    rowCount: number,
+    rowFactory: (i: number) => unknown[] = (i) => [i, `name-${i}`],
+  ): RunQueryRawResult => ({
+    type: "dql",
+    columns: [
+      { name: "id", type: "INT" },
+      { name: "name", type: "VARCHAR" },
+    ],
+    dataset: Array.from({ length: rowCount }, (_, i) => rowFactory(i)),
+    count: rowCount,
+    durationMs: 12,
+  })
+
+  it("returns DDL/DML/notice envelopes verbatim", () => {
+    expect(buildRunQueryPayload({ type: "ddl", durationMs: 5 }, 100)).toEqual({
+      type: "ddl",
+      ok: true,
+      message: null,
+      duration_ms: 5,
+    })
+    expect(
+      buildRunQueryPayload(
+        { type: "notice", durationMs: 1, message: "hi" },
+        100,
+      ),
+    ).toEqual({ type: "notice", ok: true, message: "hi", duration_ms: 1 })
+  })
+
+  it("returns error envelope with position", () => {
+    expect(
+      buildRunQueryPayload(
+        { type: "error", error: "bad sql", position: 7 },
+        100,
+      ),
+    ).toEqual({ error: "bad sql", position: 7 })
+  })
+
+  it("returns rows untruncated when within limit and size cap", () => {
+    const out = buildRunQueryPayload(dql(3), 100)
+    expect(out.type).toBe("dql")
+    expect(out.returned_count).toBe(3)
+    expect(out.total_count).toBe(3)
+    expect(out.truncated).toBe(false)
+  })
+
+  it("truncates rows to the requested limit and flags truncated=true", () => {
+    const out = buildRunQueryPayload(dql(150), 50)
+    expect(out.returned_count).toBe(50)
+    expect(out.total_count).toBe(150)
+    expect(out.truncated).toBe(true)
+  })
+
+  it("clamps limit at the hard cap (RUN_QUERY_MAX_LIMIT)", () => {
+    const out = buildRunQueryPayload(dql(15_000), 999_999)
+    expect(out.returned_count).toBe(RUN_QUERY_MAX_LIMIT)
+    expect(out.total_count).toBe(15_000)
+    expect(out.truncated).toBe(true)
+  })
+
+  it("does not clip long string cells (per-cell cap removed)", () => {
+    const longString = "x".repeat(2000)
+    const out = buildRunQueryPayload(
+      dql(1, () => [longString, "y"]),
+      100,
+    ) as { rows: string[][]; truncated: boolean }
+    expect(out.rows[0][0]).toBe(longString)
+    expect(out.rows[0][0].length).toBe(2000)
+  })
+
+  it("drops trailing rows to keep payload under ~1 MB", () => {
+    // ~2400 chars/row × 1000 rows ≈ 2.4 MB; cap should clip back to ≤ 1 MB.
+    const filler = "z".repeat(1200)
+    const out = buildRunQueryPayload(
+      dql(1000, () => [filler, filler]),
+      1000,
+    ) as { returned_count: number; truncated: boolean }
+    expect(out.returned_count).toBeLessThan(1000)
+    expect(out.truncated).toBe(true)
+  })
+
+  it("always includes the first row even when it alone exceeds the byte cap", () => {
+    // 2 MB string in a single cell — single-row payload exceeds the 1 MB
+    // cap. We still return that one row (empty `rows` confuses agents) and
+    // flag truncated:true.
+    const huge = "x".repeat(2_000_000)
+    const out = buildRunQueryPayload(
+      dql(3, () => [huge]),
+      10,
+    ) as { rows: string[][]; returned_count: number; truncated: boolean }
+    expect(out.returned_count).toBe(1)
+    expect(out.rows[0][0].length).toBe(2_000_000)
+    expect(out.truncated).toBe(true)
+  })
+
+  it("preserves native number / boolean / null values", () => {
+    const out = buildRunQueryPayload(
+      dql(1, () => [42, true, null, "ok"]),
+      10,
+    ) as { rows: unknown[][] }
+    expect(out.rows[0]).toEqual([42, true, null, "ok"])
+  })
+
+  it("flattens non-primitive cells (arrays/objects) to JSON strings", () => {
+    const out = buildRunQueryPayload(
+      dql(1, () => [{ a: 1 }, [1, 2, 3]]),
+      10,
+    ) as { rows: unknown[][] }
+    expect(out.rows[0]).toEqual(['{"a":1}', "[1,2,3]"])
+  })
+})
+
+describe("mapQueryRawToResult", () => {
+  const stubDqlReturn = () => ({
+    promise: Promise.resolve({
+      type: Type.DQL,
+      columns: [],
+      dataset: [],
+      count: 0,
+    }),
+    queryId: 1,
+  })
+
+  it("sends the requested row limit to /exec using the cancellable queryRaw overload", async () => {
+    const queryRaw = vi.fn().mockReturnValue(stubDqlReturn())
+    const abort = vi.fn()
+    await mapQueryRawToResult(
+      { queryRaw, abort } as never,
+      "SELECT * FROM x",
+      25,
+    )
+    expect(queryRaw).toHaveBeenCalledWith("SELECT * FROM x", {
+      limit: "0,25",
+      cancellable: true,
+    })
+  })
+
+  it("clamps the network limit before sending the request", async () => {
+    const queryRaw = vi.fn().mockReturnValue(stubDqlReturn())
+    const abort = vi.fn()
+    await mapQueryRawToResult(
+      { queryRaw, abort } as never,
+      "SELECT * FROM x",
+      99_999,
+    )
+    expect(queryRaw).toHaveBeenCalledWith("SELECT * FROM x", {
+      limit: `0,${RUN_QUERY_MAX_LIMIT}`,
+      cancellable: true,
+    })
+    expect(clampRunQueryLimit(0)).toBe(1)
+  })
+
+  it("aborts the live query via questClient.abort(queryId) when the caller signal fires", async () => {
+    const queryRaw = vi.fn().mockReturnValue(stubDqlReturn())
+    const abort = vi.fn()
+    const ac = new AbortController()
+    const done = mapQueryRawToResult(
+      { queryRaw, abort } as never,
+      "SELECT * FROM x",
+      10,
+      ac.signal,
+    )
+    ac.abort()
+    await done
+    expect(queryRaw).toHaveBeenCalledWith("SELECT * FROM x", {
+      limit: "0,10",
+      cancellable: true,
+    })
+    expect(abort).toHaveBeenCalledWith(1)
+  })
+
+  it("does not submit the query when the signal is already aborted (e.g. write revoked mid-validation)", async () => {
+    const queryRaw = vi.fn().mockReturnValue(stubDqlReturn())
+    const abort = vi.fn()
+    const ac = new AbortController()
+    ac.abort()
+    const res = await mapQueryRawToResult(
+      { queryRaw, abort } as never,
+      "DROP TABLE important",
+      10,
+      ac.signal,
+    )
+    expect(queryRaw).not.toHaveBeenCalled()
+    expect(abort).not.toHaveBeenCalled()
+    expect(res).toEqual({
+      type: "error",
+      error: "Query aborted before execution.",
+    })
+  })
+})
diff --git a/src/utils/tools/runQuery.ts b/src/utils/tools/runQuery.ts
new file mode 100644
index 000000000..5852a6e29
--- /dev/null
+++ b/src/utils/tools/runQuery.ts
@@ -0,0 +1,143 @@
+import type { Client } from "../questdb/client"
+import { Type } from "../questdb/types"
+
+export const RUN_QUERY_DEFAULT_LIMIT = 100
+export const RUN_QUERY_MAX_LIMIT = 10_000
+const RUN_QUERY_PAYLOAD_BYTE_CAP = 1_000_000
+
+export type RunQueryRawResult =
+  | {
+      type: "dql"
+      columns: Array<{ name: string; type?: string }>
+      dataset: Array<Array<unknown>>
+      count: number
+      durationMs?: number
+    }
+  | { type: "ddl" | "dml" | "notice"; durationMs?: number; message?: string }
+  | { type: "error"; error: string; position?: number }
+
+// Wire shape is (string | number | boolean | null)[] — array/object cells
+// (e.g. QuestDB ARRAY columns) get flattened to a JSON string so the agent
+// never has to handle nested structures in tool results.
+const flattenCellValue = (raw: unknown): string | number | boolean | null => {
+  if (raw === null || raw === undefined) return null
+  if (typeof raw === "number" || typeof raw === "boolean") return raw
+  if (typeof raw === "string") return raw
+  return JSON.stringify(raw)
+}
+
+export const buildRunQueryPayload = (
+  raw: RunQueryRawResult,
+  requestedLimit: number,
+): Record<string, unknown> => {
+  if (raw.type === "error") {
+    return { error: raw.error, position: raw.position ?? -1 }
+  }
+  if (raw.type !== "dql") {
+    return {
+      type: raw.type,
+      ok: true,
+      message: raw.message ?? null,
+      duration_ms: raw.durationMs ?? null,
+    }
+  }
+
+  const totalCount = raw.count
+  const limit = Math.min(
+    Math.max(1, Math.floor(requestedLimit)),
+    RUN_QUERY_MAX_LIMIT,
+  )
+  const rowsCapped = raw.dataset
+    .slice(0, limit)
+    .map((row) => row.map(flattenCellValue))
+
+  // Single-pass byte-budget aggregator: append rows while keeping the
+  // cumulative JSON size under the cap. Strict — the row that would push
+  // us over is dropped, not included. Exception: always keep the first
+  // row so a pathological wide row doesn't return `rows: []`.
+  const rows: typeof rowsCapped = []
+  let bytes = 0
+  let byteCapped = false
+  for (const row of rowsCapped) {
+    const rowBytes = JSON.stringify(row).length
+    if (rows.length > 0 && bytes + rowBytes > RUN_QUERY_PAYLOAD_BYTE_CAP) {
+      byteCapped = true
+      break
+    }
+    rows.push(row)
+    bytes += rowBytes
+  }
+
+  const rowCountClipped = totalCount > rowsCapped.length
+  return {
+    type: "dql",
+    columns: raw.columns,
+    rows,
+    returned_count: rows.length,
+    total_count: totalCount,
+    truncated: rowCountClipped || byteCapped,
+    duration_ms: raw.durationMs ?? null,
+  }
+}
+
+export const clampRunQueryLimit = (requestedLimit: number): number =>
+  Math.min(Math.max(1, Math.floor(requestedLimit)), RUN_QUERY_MAX_LIMIT)
+
+export const mapQueryRawToResult = async (
+  questClient: Client,
+  sql: string,
+  requestedLimit: number,
+  signal?: AbortSignal,
+): Promise<RunQueryRawResult> => {
+  const startedAt = performance.now()
+  try {
+    const limit = clampRunQueryLimit(requestedLimit)
+    if (signal?.aborted) {
+      return { type: "error", error: "Query aborted before execution." }
+    }
+    const { promise, queryId } = questClient.queryRaw(sql, {
+      limit: `0,${limit}`,
+      cancellable: true,
+    })
+    if (signal) {
+      signal.addEventListener("abort", () => questClient.abort(queryId), {
+        once: true,
+      })
+    }
+    const res = await promise
+    const durationMs = Math.round(performance.now() - startedAt)
+    if (res.type === Type.DQL) {
+      return {
+        type: "dql",
+        columns: res.columns,
+        dataset: res.dataset,
+        count: res.count,
+        durationMs,
+      }
+    }
+    if (res.type === Type.DDL || res.type === Type.DML) {
+      return { type: res.type, durationMs }
+    }
+    if (res.type === Type.NOTICE) {
+      return { type: "notice", durationMs, message: res.notice }
+    }
+    return { type: "error", error: res.error, position: res.position }
+  } catch (e) {
+    if (e && typeof e === "object" && "error" in e) {
+      const errLike = e as { error?: unknown; position?: unknown }
+      if (typeof errLike.error === "string") {
+        return {
+          type: "error",
+          error: errLike.error,
+          position:
+            typeof errLike.position === "number" ? errLike.position : -1,
+        }
+      }
+    }
+    return {
+      type: "error",
+      error: e instanceof Error ? e.message : "Unknown error",
+      position: -1,
+    }
+  }
+}
diff --git a/src/utils/tools/tools.strict.test.ts b/src/utils/tools/tools.strict.test.ts
new file mode 100644
index 000000000..dd03ffea8
--- /dev/null
+++ b/src/utils/tools/tools.strict.test.ts
@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest"
+import { ALL_DEFINITIONS, aiTools } from "./tools"
+
+type SchemaNode = {
+  type?: unknown
+  properties?: Record<string, SchemaNode>
+  required?: string[]
+  additionalProperties?: unknown
+  items?: SchemaNode
+}
+
+const isObjectNode = (node: SchemaNode): boolean =>
+  node.type === "object" ||
+  (Array.isArray(node.type) && node.type.includes("object"))
+
+const collectViolations = (
+  path: string,
+  node: SchemaNode | undefined,
+  out: string[],
+): void => {
+  if (!node || typeof node !== "object") return
+
+  if (isObjectNode(node) && node.properties) {
+    const props = Object.keys(node.properties)
+    const required = node.required ?? []
+    const missing = props.filter((p) => !required.includes(p))
+    if (missing.length > 0) {
+      out.push(`${path}: required missing [${missing.join(", ")}]`)
+    }
+    if (node.additionalProperties !== false) {
+      out.push(`${path}: additionalProperties is not false`)
+    }
+  }
+
+  if (node.items) collectViolations(`${path}.items`, node.items, out)
+  for (const key of Object.keys(node.properties ?? {})) {
+    collectViolations(`${path}.${key}`, node.properties![key], out)
+  }
+}
+
+describe("AI tool schemas satisfy OpenAI strict mode", () => {
+  it("every object node lists all properties in required and forbids extras", () => {
+    const violations: string[] = []
+    for (const tool of aiTools) {
+      collectViolations(tool.name, tool.inputSchema as SchemaNode, violations)
+    }
+    expect(violations).toEqual([])
+  })
+})
+
+describe("editsCells flag", () => {
+  it("every editsCells tool also mutatesNotebook (editsCells ⊆ mutatesNotebook)", () => {
+    const bad = ALL_DEFINITIONS.filter(
+      (t) => t.editsCells && !t.mutatesNotebook,
+    ).map((t) => t.name)
+    expect(bad).toEqual([])
+  })
+})
diff --git a/src/utils/tools/tools.ts b/src/utils/tools/tools.ts
new file mode 100644
index 000000000..f8f9a6690
--- /dev/null
+++ b/src/utils/tools/tools.ts
@@ -0,0 +1,57 @@
+import type { ToolDefinition, ToolSurface } from "../ai/types"
+import type { Permissions, ToolCategory } from "./permissions"
+import { RUN_QUERY_MAX_LIMIT } from "./runQuery"
+import sharedDefinitions from "../../consts/shared-definitions.json"
+
+export const ALL_DEFINITIONS: ToolDefinition[] =
+  sharedDefinitions as unknown as ToolDefinition[]
+
+// Fail fast if the JSON's numeric limit drifts from RUN_QUERY_MAX_LIMIT.
+const runQueryLimit = ALL_DEFINITIONS.find((d) => d.name === "run_query")
+  ?.inputSchema.properties.limit as { maximum?: number } | undefined
+if (runQueryLimit?.maximum !== RUN_QUERY_MAX_LIMIT) {
+  throw new Error(
+    `shared-definitions.json: run_query.limit.maximum (${runQueryLimit?.maximum}) ` +
+      `must equal RUN_QUERY_MAX_LIMIT (${RUN_QUERY_MAX_LIMIT})`,
+  )
+}
+
+const _DEF_BY_NAME = new Map(ALL_DEFINITIONS.map((d) => [d.name, d]))
+
+const surfacesFor = (def: ToolDefinition): readonly ("ai" | "mcp")[] =>
+  def.surfaces ?? ["ai", "mcp"]
+
+export const aiTools: ToolDefinition[] = ALL_DEFINITIONS.filter((d) =>
+  surfacesFor(d).includes("ai"),
+)
+export const mcpTools: ToolDefinition[] = ALL_DEFINITIONS.filter((d) =>
+  surfacesFor(d).includes("mcp"),
+)
+
+export const categoryFor = (name: string): ToolCategory =>
+  _DEF_BY_NAME.get(name)?.category ?? "free"
+
+export const mutatesNotebook = (name: string): boolean =>
+  !!_DEF_BY_NAME.get(name)?.mutatesNotebook
+
+export const editsCells = (name: string): boolean =>
+  !!_DEF_BY_NAME.get(name)?.editsCells
+
+export const MCP_META_TOOL_NAMES: readonly string[] = ALL_DEFINITIONS.filter(
+  (d) => d.surfaces?.length === 1 && d.surfaces[0] === "mcp",
+).map((d) => d.name)
+
+export const isMcpMetaToolName = (name: string): boolean =>
+  MCP_META_TOOL_NAMES.includes(name)
+
+export const toolsForPermission = (
+  perms: Permissions,
+  surface: ToolSurface = "ai",
+): ToolDefinition[] => {
+  const base = surface === "mcp" ? mcpTools : aiTools
+  if (perms.read || perms.write) return base
+  if (perms.grantSchemaAccess) {
+    return base.filter((t) => t.category === "free" || t.category === "schema")
+  }
+  return base.filter((t) => t.category === "free")
+}
diff --git a/yarn.lock b/yarn.lock
index 803d5bc74..9ccde26f3 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2544,13 +2544,13 @@ __metadata:
     "@tanstack/react-virtual": "npm:^3.14.2"
     "@types/babel__core": "npm:^7"
     "@types/draggabilly": "npm:^2.1.6"
-    "@types/echarts": "npm:^4.9.22"
     "@types/jquery": "npm:3.5.1"
     "@types/lodash.merge": "npm:^4.6.9"
     "@types/node": "npm:^18.0.0"
     "@types/ramda": "npm:0.27.40"
     "@types/react": "npm:17.0.2"
     "@types/react-dom": "npm:17.0.2"
+    "@types/react-grid-layout": "npm:^2.1.0"
     "@types/react-highlight-words": "npm:^0.16.7"
     "@types/react-redux": "npm:7.1.9"
     "@types/react-transition-group": "npm:4.4.0"
@@ -2573,7 +2573,8 @@ __metadata:
     dexie-react-hooks: "npm:^4.2.0"
     dotenv: "npm:^10.0.0"
     draggabilly: "npm:^3.0.0"
-    echarts: "npm:^5.2.2"
+    echarts: "npm:^5.6.0"
+    echarts-for-react: "npm:^3.0.6"
     eslint: "npm:^9.13.0"
     eslint-config-prettier: "npm:^10.1.8"
     eslint-plugin-jsx-a11y: "npm:^6.10.2"
@@ -2604,6 +2605,7 @@ __metadata:
     react: "npm:17.0.2"
     react-calendar: "npm:^4.0.0"
     react-dom: "npm:17.0.2"
+    react-grid-layout: "npm:^2.2.3"
     react-highlight-words: "npm:^0.20.0"
     react-hook-form: "npm:^7.56.0"
     react-is: "npm:^18.1.0"
@@ -3950,15 +3952,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/echarts@npm:^4.9.22":
-  version: 4.9.22
-  resolution: "@types/echarts@npm:4.9.22"
-  dependencies:
-    "@types/zrender": "npm:*"
-  checksum: 10/abc05f45b29afb019c33c2e5c96e553a43ca9bfa13b188d10e097a9005469aff10149c4ab7f8b8abeabdb95035817966446a97b78362a8c7f28fc910c080d135
-  languageName: node
-  linkType: hard
-
 "@types/estree@npm:1.0.8, @types/estree@npm:^1.0.0, @types/estree@npm:^1.0.6":
   version: 1.0.8
   resolution: "@types/estree@npm:1.0.8"
@@ -4105,6 +4098,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/react-grid-layout@npm:^2.1.0":
+  version: 2.1.0
+  resolution: "@types/react-grid-layout@npm:2.1.0"
+  dependencies:
+    react-grid-layout: "npm:*"
+  checksum: 10/aee72c50b1fbcc9efd8cfd72cc1f61e461adaebca9ca48d16e94990cebc503d7b10663f33440e0fbd9b27069383f2e0b3d283ca9fc1d8e56e35c46ac423b74fe
+  languageName: node
+  linkType: hard
+
 "@types/react-highlight-words@npm:^0.16.7":
   version: 0.16.7
   resolution: "@types/react-highlight-words@npm:0.16.7"
@@ -4193,13 +4195,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/zrender@npm:*":
-  version: 4.0.6
-  resolution: "@types/zrender@npm:4.0.6"
-  checksum: 10/07115466bf90d3f4fa86ad47bc5013b7c68371d2cb37e9411af0d8c4511025b56163d29efc36c19b9918e4672ee63c8a175eb50d299d9bcab193b879517d7ac7
-  languageName: node
-  linkType: hard
-
 "@typescript-eslint/eslint-plugin@npm:8.46.2":
   version: 8.46.2
   resolution: "@typescript-eslint/eslint-plugin@npm:8.46.2"
@@ -5456,7 +5451,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"clsx@npm:^2.0.0":
+"clsx@npm:^2.0.0, clsx@npm:^2.1.1":
   version: 2.1.1
   resolution: "clsx@npm:2.1.1"
   checksum: 10/cdfb57fa6c7649bbff98d9028c2f0de2f91c86f551179541cf784b1cfdc1562dcb951955f46d54d930a3879931a980e32a46b598acaea274728dbe068deca919
@@ -6054,7 +6049,20 @@ __metadata:
   languageName: node
   linkType: hard
 
-"echarts@npm:^5.2.2":
+"echarts-for-react@npm:^3.0.6":
+  version: 3.0.6
+  resolution: "echarts-for-react@npm:3.0.6"
+  dependencies:
+    fast-deep-equal: "npm:^3.1.3"
+    size-sensor: "npm:^1.0.1"
+  peerDependencies:
+    echarts: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0
+    react: ^15.0.0 || >=16.0.0
+  checksum: 10/e7c084f516ee6f4c32a1f9eff3ff4372616878aeb6bacaa495fc8d60d2114b54b4b255a31a81fee3e05bfb278f9d27d9a320bb33b8ff37c92e43ac9fd1e4b539
+  languageName: node
+  linkType: hard
+
+"echarts@npm:^5.6.0":
   version: 5.6.0
   resolution: "echarts@npm:5.6.0"
   dependencies:
@@ -6859,6 +6867,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"fast-equals@npm:^4.0.3":
+  version: 4.0.3
+  resolution: "fast-equals@npm:4.0.3"
+  checksum: 10/04c1ff47b79923314e9b63ec6c81beeaa5e3b9588ec230ee6aff7ece725ff834a72abf627055055127bd0f53ae8a92cc04c3a6e187783fd932dbef743f9b13bf
+  languageName: node
+  linkType: hard
+
 "fast-glob@npm:^3.2.5, fast-glob@npm:^3.2.9, fast-glob@npm:^3.3.2":
   version: 3.3.3
   resolution: "fast-glob@npm:3.3.3"
@@ -10375,7 +10390,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"prop-types@npm:^15.0.0, prop-types@npm:^15.5.8, prop-types@npm:^15.6.0, prop-types@npm:^15.6.2, prop-types@npm:^15.7.2, prop-types@npm:^15.8.1":
+"prop-types@npm:15.x, prop-types@npm:^15.0.0, prop-types@npm:^15.5.8, prop-types@npm:^15.6.0, prop-types@npm:^15.6.2, prop-types@npm:^15.7.2, prop-types@npm:^15.8.1":
   version: 15.8.1
   resolution: "prop-types@npm:15.8.1"
   dependencies:
@@ -10496,6 +10511,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"react-draggable@npm:^4.4.6, react-draggable@npm:^4.5.0":
+  version: 4.5.0
+  resolution: "react-draggable@npm:4.5.0"
+  dependencies:
+    clsx: "npm:^2.1.1"
+    prop-types: "npm:^15.8.1"
+  peerDependencies:
+    react: ">= 16.3.0"
+    react-dom: ">= 16.3.0"
+  checksum: 10/fd4080a082fad199103c6978c8a78c80154a0205dbd14ca2c7bb75634132a6afd83a3e4669f2d8fe54efe68569ef24a992439183289d83e71030b0a1791d3476
+  languageName: node
+  linkType: hard
+
 "react-fast-compare@npm:^3.0.1":
   version: 3.2.2
   resolution: "react-fast-compare@npm:3.2.2"
@@ -10503,6 +10531,23 @@ __metadata:
   languageName: node
   linkType: hard
 
+"react-grid-layout@npm:*, react-grid-layout@npm:^2.2.3":
+  version: 2.2.3
+  resolution: "react-grid-layout@npm:2.2.3"
+  dependencies:
+    clsx: "npm:^2.1.1"
+    fast-equals: "npm:^4.0.3"
+    prop-types: "npm:^15.8.1"
+    react-draggable: "npm:^4.4.6"
+    react-resizable: "npm:^3.1.3"
+    resize-observer-polyfill: "npm:^1.5.1"
+  peerDependencies:
+    react: ">= 16.3.0"
+    react-dom: ">= 16.3.0"
+  checksum: 10/90b66db889fc5889e038dd1b6198eb94cb093a9669335b0f617cee3999b6d0f37bf4683aba418235c8469967fba113461d6858e8c1f6165cf58af483236cb8d4
+  languageName: node
+  linkType: hard
+
 "react-highlight-words@npm:^0.20.0":
   version: 0.20.0
   resolution: "react-highlight-words@npm:0.20.0"
@@ -10641,6 +10686,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"react-resizable@npm:^3.1.3":
+  version: 3.1.3
+  resolution: "react-resizable@npm:3.1.3"
+  dependencies:
+    prop-types: "npm:15.x"
+    react-draggable: "npm:^4.5.0"
+  peerDependencies:
+    react: ">= 16.3"
+    react-dom: ">= 16.3"
+  checksum: 10/bc7126fabbd2f0ba422fa0da77fcfcebf2b4f28141d3faf02067632d258e345bc5f63891f9d5eca0e9ea31dc461b74ec69073a18f905b25bdd392ca6283577f9
+  languageName: node
+  linkType: hard
+
 "react-style-singleton@npm:^2.2.2, react-style-singleton@npm:^2.2.3":
   version: 2.2.3
   resolution: "react-style-singleton@npm:2.2.3"
@@ -10968,7 +11026,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"resize-observer-polyfill@npm:1.5.1":
+"resize-observer-polyfill@npm:1.5.1, resize-observer-polyfill@npm:^1.5.1":
   version: 1.5.1
   resolution: "resize-observer-polyfill@npm:1.5.1"
   checksum: 10/e10ee50cd6cf558001de5c6fb03fee15debd011c2f694564b71f81742eef03fb30d6c2596d1d5bf946d9991cb692fcef529b7bd2e4057041377ecc9636c753ce
@@ -11459,6 +11517,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"size-sensor@npm:^1.0.1":
+  version: 1.0.3
+  resolution: "size-sensor@npm:1.0.3"
+  checksum: 10/77a2a022b2b2030bec78405a0f0b5a2ed5f03a9d2373710d4f9333a77321b2f18d41f43db63a6c8202fb13dc68bb10d02925e23e5a9e249ca377b4b664fde995
+  languageName: node
+  linkType: hard
+
 "slash@npm:^3.0.0":
   version: 3.0.0
   resolution: "slash@npm:3.0.0"