From ec39a511b8e7b1151fd90542c233c1781f5b4b26 Mon Sep 17 00:00:00 2001
From: Flying Web Solutions <flyingweb.ie@gmail.com>
Date: Mon, 2 Nov 2026 17:58:57 +0000
Subject: [PATCH 1/6] =?UTF-8?q?=F0=9F=90=9B=20fix(mcp):=20keep=20agents=20?=
 =?UTF-8?q?connected=20to=20the=20editor=20and=20scope=20their=20scripts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agents reported the Instatic MCP tools "keep disconnecting". The cause was
the browser bridge, not the MCP endpoint:

- A browser tool failed instantly when the editor tab's stream was in a
  routine reconnect gap (idle recycle, network blip, restart). Calls now
  wait up to 15s for the workspace (waitForEditorWorkspace).
- Two open editor tabs stole the workspace from each other on every idle
  recycle, cancelling in-flight calls. Tabs now send a stable tabId and keep
  their claim across reconnects; superseded tabs stay connected and take
  over when the active tab closes.
- Interrupted calls surfaced the in-app chat message "AI chat stream ended
  before tool result arrived". The transport now raises a typed
  BrowserToolInterruptedError recording whether the editor received the
  call: undelivered calls retry once transparently, delivered ones tell the
  agent the edit may or may not have applied and to re-read first.

Agents now follow the God Mode build practice: single-page JS goes in the
new site_write_page_script tool (the page script the JS panel edits, loaded
only on that page), and a new script written with site_write_code_asset
must declare its runtime.scope instead of silently loading on every page.
MCP server instructions, the site system prompt, and docs are updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/features/agent.md                        |   7 +-
 docs/features/god-mode.md                     |   5 +
 docs/features/mcp-connectors.md               |  18 +-
 server/ai/mcp/editorBridge.test.ts            |  81 +++++++-
 server/ai/mcp/editorBridge.ts                 | 177 +++++++++++++++---
 server/ai/mcp/handlers/editorBridge.ts        |  18 +-
 server/ai/mcp/instructions.ts                 |  15 +-
 server/ai/mcp/server.test.ts                  |  80 +++++++-
 server/ai/mcp/server.ts                       | 127 ++++++++++---
 server/ai/mcp/tools/contextTool.ts            |   2 +-
 server/ai/runtime/index.ts                    |   1 +
 server/ai/runtime/transport.ts                |  44 ++++-
 server/ai/tools/site/systemPrompt.ts          |   6 +-
 server/ai/tools/site/writeTools.ts            |  14 +-
 .../data/contentCollectionStepUp.test.tsx     |   2 +-
 src/__tests__/agent/contentBridge.test.ts     |   2 +
 src/__tests__/agent/executor.test.ts          |  45 ++++-
 src/__tests__/ai/editorBridgeLease.test.ts    |   8 +-
 .../architecture/agent-tool-surface.test.ts   |   4 +-
 .../architecture/ai-tool-schema-ssot.test.ts  |   2 +
 src/admin/ai/useMcpWorkspaceBridge.ts         |  10 +-
 src/admin/pages/site/agent/codeAssetTools.ts  |  78 +++++++-
 src/admin/pages/site/agent/executor.ts        |   8 +-
 .../pages/site/agent/toolClassification.ts    |   1 +
 .../site/panels/AgentPanel/toolCallDisplay.ts |   2 +
 src/core/ai/index.ts                          |   2 +
 src/core/ai/toolSchemas.ts                    |  28 ++-
 27 files changed, 670 insertions(+), 117 deletions(-)

diff --git a/docs/features/agent.md b/docs/features/agent.md
index 127d117f1..94c28f383 100644
--- a/docs/features/agent.md
+++ b/docs/features/agent.md
@@ -454,11 +454,12 @@ Scripts and user stylesheets live in `site.files[]`; runtime targeting and loadi
 |------------------------|--------------------------------------------|-----------------------------------------|-------------------------------------------------------|
 | `site_list_code_assets`     | `{ type?: 'script' \| 'style' }`           | `{ assets }`                            | List runtime code assets with file ids, paths, full-content hashes, sizes, timestamps, and runtime config |
 | `site_read_code_asset`      | `{ fileId? \| path?, part?, maxChars? }`   | `{ fileId, path, type, content, hash, runtime, pageInfo }` | Read an exact script/stylesheet content slice. The `hash` is for the full file; page through with `pageInfo.nextPart` |
-| `site_write_code_asset`     | `{ path, type, content, runtime?, dependencies? }` | asset summary + `{ action, dependencies }` | Create or replace a runtime script/stylesheet and normalize its runtime config. Existing paths are updated, new paths are created. For module scripts, `dependencies` is a package-name → version/range map added to `site.packageJson.dependencies` |
+| `site_write_code_asset`     | `{ path, type, content, runtime?, dependencies? }` | asset summary + `{ action, dependencies }` | Create or replace a runtime script/stylesheet and normalize its runtime config. Existing paths are updated, new paths are created. A **new script** must pass `runtime.scope` (`pages`, `templates`, or `all-pages`); without it the call fails and points at `site_write_page_script`, so a script never silently loads on every page. For module scripts, `dependencies` is a package-name → version/range map added to `site.packageJson.dependencies` |
+| `site_write_page_script`    | `{ pageId?, content, dependencies? }`      | asset summary + `{ pageId, action, dependencies }` | Write the page script the God Mode JS panel edits (`findPageScript`): created on first write via `createPageScript` (file + page-only scope in one undo step), replaced afterwards. `pageId` defaults to the active page; a Visual Component document has no page script. The default home for single-page behavior |
 | `site_patch_code_asset`     | `{ fileId? \| path?, expectedHash, replacements }` | asset summary + `{ replacements }` | Apply exact text replacements only when `expectedHash` matches the latest content. Ambiguous matches require a wider `oldText` or explicit `replaceAll:true` |
 | `site_inspect_code_runtime` | `{ document?: { type, id } }`              | `{ pageId, document, scripts, styles }` | Report which runtime scripts/stylesheets apply to the current page/template or supplied page/template document ref |
 
-`site_insert_html` / `site_replace_node_html` intentionally strip `<script>` elements and inline event handlers (`onclick`, `onload`, etc.). When a request needs behavior, the agent should use `site_write_code_asset({ type: "script", ... })` and then `site_inspect_code_runtime`, not raw `<script>` tags or event attributes in HTML.
+`site_insert_html` / `site_replace_node_html` intentionally strip `<script>` elements and inline event handlers (`onclick`, `onload`, etc.). When a request needs behavior, the agent writes a script, never raw `<script>` tags or event attributes in HTML. JS loads only where it is used: single-page behavior goes in `site_write_page_script`; behavior shared by several pages or a template uses `site_write_code_asset({ type: "script", runtime: { scope } })` with the narrowest scope; `{ type: "all-pages" }` is for code every page needs. `site_inspect_code_runtime` confirms the targeting.
 
 Module scripts that need npm packages should import bare package specifiers and declare those packages in the same `site_write_code_asset` call:
 
@@ -467,7 +468,7 @@ site_write_code_asset({
   path: 'src/scripts/motion.js',
   type: 'script',
   content: `import { Motion } from '@motion.page/sdk';`,
-  runtime: { format: 'module' },
+  runtime: { format: 'module', scope: { type: 'pages', pageIds: ['<page id>'] } },
   dependencies: { '@motion.page/sdk': '1.2.4' },
 })
 ```
diff --git a/docs/features/god-mode.md b/docs/features/god-mode.md
index 33430ccbe..0665a6998 100644
--- a/docs/features/god-mode.md
+++ b/docs/features/god-mode.md
@@ -372,6 +372,11 @@ with no new publish path.
   changes (undo, the Code editor panel, a co-editor) re-sync the buffer via
   the same `useDocumentSync` hook the CSS panel uses (`code-dock/
   useDocumentSync.ts`).
+- **Agents** — the in-app agent and MCP clients write the same file through
+  `site_write_page_script` (`runWritePageScript` in
+  `src/admin/pages/site/agent/codeAssetTools.ts`): `findPageScript` to locate
+  it, `createPageScript` on first write. An agent's page behavior therefore
+  shows up in this panel and loads only on its page.
 
 ## Autocomplete
 
diff --git a/docs/features/mcp-connectors.md b/docs/features/mcp-connectors.md
index 0d40735d7..f8685a6fb 100644
--- a/docs/features/mcp-connectors.md
+++ b/docs/features/mcp-connectors.md
@@ -36,7 +36,11 @@ The endpoint uses the official v2 `createMcpHandler` Web-standard entry and serv
 
 The same handler keeps the SDK's `legacy: 'stateless'` fallback enabled. Clients speaking a 2025-era revision may still send an `initialize` request and then make independent authenticated POSTs, but no protocol session is created. This compatibility path can be removed when supported clients have all migrated.
 
-The server advertises `MCP_SERVER_INSTRUCTIONS` (`server/ai/mcp/instructions.ts`) to every client. External agents never see the in-app system prompt, so the styling rule travels with the connection: page and component CSS goes through `site_insert_html` / `site_replace_node_html` / `site_apply_css` so it lands as per-class style rules, never in a `site_write_code_asset type:"style"` file, whose rules the Selectors and CSS panels cannot show.
+The server advertises `MCP_SERVER_INSTRUCTIONS` (`server/ai/mcp/instructions.ts`) to every client. External agents never see the in-app system prompt, so the build rules travel with the connection:
+
+- page and component CSS goes through `site_insert_html` / `site_replace_node_html` / `site_apply_css` so it lands as per-class style rules (what the God Mode CSS panel edits), never in a `site_write_code_asset type:"style"` file, whose rules the Selectors and CSS panels cannot show;
+- single-page JS goes in `site_write_page_script` (the God Mode JS panel's page script, loaded only on that page); shared JS uses `site_write_code_asset type:"script"` with the narrowest `runtime.scope`;
+- how to read the bridge's failure messages (see "Tool execution model") instead of treating one failed call as a lost connection.
 
 Every request is bearer-authenticated before the SDK dispatches it. Browser-originated requests are also checked against Instatic's configured public-origin policy before authentication or dispatch; requests without `Origin` remain valid for native and server-to-server MCP clients.
 
@@ -146,7 +150,7 @@ executeAiTool(...) / live editor bridge
 | `contentAuthorization.ts` | Before a document tool is relayed to the browser, resolves the target row through `server/auth/dataAccess.ts` with the connection's own identity and capabilities (table family plus own-vs-any ownership), so the owner's admin cookie cannot widen the delegated grant. |
 | `transports/http.ts` | Authenticated, Origin-validated `createMcpHandler` entry for MCP 2026-07-28 plus the stateless 2025 fallback. |
 | `server.ts` / `registry.ts` | Low-level SDK server, TypeBox input schemas, catalog deduplication, and capability filtering. |
-| `editorBridge.ts` | Per-user, per-scope live workspace bridge. Tool requests are delivered **serially** (the next is pushed only once the previous settles, matching the editor's one-at-a-time execution), so each call's 90s timeout measures the editor's actual work, not time queued behind slower calls. The stream carries an **idle lease** (120s, re-armed by every relayed tool request and never expiring while a call is pending) so an active batch is never cut mid-flight; only quiet streams recycle. The workspace's reconnect loop (`useMcpWorkspaceBridge`) reopens a recycled healthy stream immediately off the stream-end network event — deliberately timer-free, because hidden webviews (backgrounded browser tabs) clamp timers to minutes while network events still fire — and a tab becoming visible short-circuits any pending retry delay. |
+| `editorBridge.ts` | Per-user, per-scope live workspace bridge. Each tab sends a stable `tabId` and keeps its **claim** across reconnects: calls route to the most recently opened tab, a tab reconnecting after an idle recycle never steals the workspace back, superseded tabs stay connected (their in-flight calls finish) and take over when the active tab closes. `waitForEditorWorkspace` lets a call wait for a tab to (re)connect. Tool requests are delivered **serially** (the next is pushed only once the previous settles, matching the editor's one-at-a-time execution), so each call's 90s timeout measures the editor's actual work, not time queued behind slower calls. The stream carries an **idle lease** (120s, re-armed by every relayed tool request and never expiring while a call is pending) so an active batch is never cut mid-flight; only quiet streams recycle. The workspace's reconnect loop (`useMcpWorkspaceBridge`) reopens a recycled healthy stream immediately off the stream-end network event — deliberately timer-free, because hidden webviews (backgrounded browser tabs) clamp timers to minutes while network events still fire — and a tab becoming visible short-circuits any pending retry delay. |
 | `tools/publishTool.ts` | Explicit canonical full-site publish with MCP audit metadata. |
 | `tools/uploadMediaTool.ts` | Server-resolved image upload (`media_upload`) — inline base64 or SSRF-guarded `sourceUrl` download, through the shared media pipeline. |
 
@@ -158,7 +162,15 @@ Server-resolved tools work without an editor open. They include content reads, `
 
 `media_upload` is the one server-resolved write that mutates outside the live editor draft: it adds an image to the Media library through the same `acceptUploadedMedia` core the HTTP route uses (magic-byte sniffing, SVG sanitisation, storage dispatch, responsive variants). Bytes arrive inline (base64) or via an https `sourceUrl` the host downloads under the plugin network layer's SSRF blocklist — https-only, DNS-resolved, per-redirect-hop re-validation, size-capped. It requires `ai.tools.write` plus `media.write`.
 
-Browser tools run against the connection owner's live workspace. Site structure, HTML/CSS, page lifecycle, design-token, content mutation, code-asset, and live-DOM tools route to the matching open Site or Content workspace. If that workspace is not open, the tool returns a scope-specific error while headless tools remain available. `tools/list` states that requirement in each browser tool's description, so a client learns the precondition when it picks the tool rather than from a failed call.
+Browser tools run against the connection owner's live workspace. Site structure, HTML/CSS, page lifecycle, design-token, content mutation, code-asset, and live-DOM tools route to the matching open Site or Content workspace. `tools/list` states that requirement in each browser tool's description, so a client learns the precondition when it picks the tool rather than from a failed call.
+
+An open workspace's stream has routine gaps (idle recycle, reconnect after a network blip, server restart), so a browser tool **waits up to 15 seconds** for the workspace to connect before failing with a scope-specific "ask the user to open it" error; headless tools remain available meanwhile. Interrupted calls are reported by what the agent can rely on (`BrowserToolInterruptedError.delivered` in `server/ai/runtime/transport.ts`):
+
+| Situation | Behaviour |
+|---|---|
+| The tab's stream closed before the call was pushed to it | Nothing ran; the server retries once on whichever tab is live, transparently. |
+| The tab disconnected while running the call | Error: the edit may or may not have applied; re-read before retrying. |
+| The editor exceeded the 90-second per-call limit | Error: the edit may still complete; re-read before retrying; split large edits. |
 
 There is intentionally no headless page-tree mutation path. The open editor store is the single source of truth for draft edits; a second DB mutation path would desynchronize node state and overwrite the live document. Relayed edits need no post-tool save step: store mutations stream to the collab relay the moment they land, and every headless read (plus `site_publish`) flushes the relay server-side before it touches the DB — so a following read or publish always observes the edit. There is no client-side save flush, and no window in which the MCP caller can see stale data.
 
diff --git a/server/ai/mcp/editorBridge.test.ts b/server/ai/mcp/editorBridge.test.ts
index d7e5e5a54..d0cc14a87 100644
--- a/server/ai/mcp/editorBridge.test.ts
+++ b/server/ai/mcp/editorBridge.test.ts
@@ -1,6 +1,11 @@
 import { describe, expect, it } from 'bun:test'
 import { resolveBridgeToolResult } from '../runtime'
-import { createEditorBridgeStream, getEditorBridgeForUser, hasEditorBridge } from './editorBridge'
+import {
+  createEditorBridgeStream,
+  getEditorWorkspace,
+  hasEditorBridge,
+  waitForEditorWorkspace,
+} from './editorBridge'
 
 const dec = new TextDecoder()
 
@@ -28,7 +33,7 @@ async function readUntil(
 describe('editor bridge', () => {
   it('registers a bridge for the user on connect and clears it on disconnect', async () => {
     const userId = `u_${Math.floor(performance.now())}`
-    expect(getEditorBridgeForUser(userId, 'site')).toBeNull()
+    expect(getEditorWorkspace(userId, 'site')?.bridge ?? null).toBeNull()
     expect(hasEditorBridge(userId, 'site')).toBe(false)
 
     const ctrl = new AbortController()
@@ -36,12 +41,12 @@ describe('editor bridge', () => {
     const reader = stream.getReader()
     const ready = await readUntil(reader, (e) => e.type === 'bridgeReady')
     expect(typeof ready.bridgeId).toBe('string')
-    expect(getEditorBridgeForUser(userId, 'site')).not.toBeNull()
+    expect(getEditorWorkspace(userId, 'site')?.bridge ?? null).not.toBeNull()
 
     ctrl.abort()
     // Give the abort listener a tick to run.
     await reader.read().catch(() => {})
-    expect(getEditorBridgeForUser(userId, 'site')).toBeNull()
+    expect(getEditorWorkspace(userId, 'site')?.bridge ?? null).toBeNull()
   })
 
   it('relays a tool call to the stream and resolves on the result POST', async () => {
@@ -52,7 +57,7 @@ describe('editor bridge', () => {
     const ready = await readUntil(reader, (e) => e.type === 'bridgeReady')
     const bridgeId = ready.bridgeId as string
 
-    const bridge = getEditorBridgeForUser(userId, 'site')!
+    const bridge = getEditorWorkspace(userId, 'site')!.bridge
     const callPromise = bridge.callBrowser('site_insert_html', { html: '<p>hi</p>' })
 
     const toolRequest = await readUntil(reader, (e) => e.type === 'toolRequest')
@@ -131,4 +136,70 @@ describe('editor bridge', () => {
     await secondReader.cancel()
     expect(hasEditorBridge(userId, 'site')).toBe(false)
   })
+
+  it('keeps routing to the newest-opened tab when an older tab reconnects', async () => {
+    const userId = `u_${Math.floor(performance.now())}_tabs`
+    const olderCtrl = new AbortController()
+    const older = createEditorBridgeStream(userId, 'site', olderCtrl.signal, { tabId: 'older' }).getReader()
+    await readUntil(older, (e) => e.type === 'bridgeReady')
+
+    const newerCtrl = new AbortController()
+    const newer = createEditorBridgeStream(userId, 'site', newerCtrl.signal, { tabId: 'newer' }).getReader()
+    const newerReady = await readUntil(newer, (e) => e.type === 'bridgeReady')
+
+    // The older tab's stream recycles and reconnects with the same tabId.
+    olderCtrl.abort()
+    await older.read().catch(() => {})
+    const olderAgainCtrl = new AbortController()
+    const olderAgain = createEditorBridgeStream(userId, 'site', olderAgainCtrl.signal, { tabId: 'older' }).getReader()
+    await readUntil(olderAgain, (e) => e.type === 'bridgeReady')
+
+    const call = getEditorWorkspace(userId, 'site')!.bridge.callBrowser('probe', {})
+    const request = await readUntil(newer, (e) => e.type === 'toolRequest')
+    expect(resolveBridgeToolResult(newerReady.bridgeId as string, request.requestId as string, { ok: true })).toBe(true)
+    expect((await call).ok).toBe(true)
+
+    // Closing the active tab hands the workspace to the remaining one.
+    newerCtrl.abort()
+    await newer.read().catch(() => {})
+    expect(hasEditorBridge(userId, 'site')).toBe(true)
+
+    olderAgainCtrl.abort()
+    await olderAgain.read().catch(() => {})
+    expect(hasEditorBridge(userId, 'site')).toBe(false)
+  })
+
+  it('does not cancel a superseded tab\'s in-flight call when a new tab opens', async () => {
+    const userId = `u_${Math.floor(performance.now())}_inflight`
+    const firstCtrl = new AbortController()
+    const first = createEditorBridgeStream(userId, 'site', firstCtrl.signal, { tabId: 'first' }).getReader()
+    const firstReady = await readUntil(first, (e) => e.type === 'bridgeReady')
+    const call = getEditorWorkspace(userId, 'site')!.bridge.callBrowser('slow', {})
+    const request = await readUntil(first, (e) => e.type === 'toolRequest')
+
+    const secondCtrl = new AbortController()
+    const second = createEditorBridgeStream(userId, 'site', secondCtrl.signal, { tabId: 'second' }).getReader()
+    await readUntil(second, (e) => e.type === 'bridgeReady')
+
+    expect(resolveBridgeToolResult(firstReady.bridgeId as string, request.requestId as string, { ok: true })).toBe(true)
+    expect((await call).ok).toBe(true)
+
+    firstCtrl.abort()
+    secondCtrl.abort()
+    await Promise.all([first.read().catch(() => {}), second.read().catch(() => {})])
+  })
+
+  it('waits for a workspace to connect, and gives up after the timeout', async () => {
+    const userId = `u_${Math.floor(performance.now())}_wait`
+    expect(await waitForEditorWorkspace(userId, 'site', { timeoutMs: 20 })).toBeNull()
+
+    const waiting = waitForEditorWorkspace(userId, 'site', { timeoutMs: 2_000 })
+    const ctrl = new AbortController()
+    const reader = createEditorBridgeStream(userId, 'site', ctrl.signal).getReader()
+    await readUntil(reader, (e) => e.type === 'bridgeReady')
+    expect(await waiting).not.toBeNull()
+
+    ctrl.abort()
+    await reader.read().catch(() => {})
+  })
 })
diff --git a/server/ai/mcp/editorBridge.ts b/server/ai/mcp/editorBridge.ts
index ebdc2bcf3..d99946bb0 100644
--- a/server/ai/mcp/editorBridge.ts
+++ b/server/ai/mcp/editorBridge.ts
@@ -7,7 +7,7 @@
  * the editor holds a long-lived newline-delimited JSON stream open while
  * mounted. Its HTTP response is advertised as an event stream so reverse
  * proxies preserve incremental delivery. This module keeps one bridge per user
- * and workspace (the newest open instance wins) and lets the MCP server relay a
+ * and workspace and lets the MCP server relay a
  * browser tool call to the correct workspace before awaiting its result.
  *
  * Reuses the chat bridge machinery wholesale: `createBridge` issues the
@@ -15,6 +15,14 @@
  * the existing `/admin/api/ai/tool-result`), and `encodeStreamEvent` frames the
  * NDJSON the editor reads with `readNdjsonStream`.
  *
+ * Several tabs may hold a stream for the same workspace. Each tab sends a
+ * stable `tabId` and keeps its claim across reconnects: tool calls route to
+ * the most recently *opened* tab, and a tab merely reconnecting after an idle
+ * recycle never steals the workspace back. Superseded tabs stay connected (so
+ * in-flight calls finish) and take over automatically when the active tab
+ * closes. Callers that land in a reconnect gap wait briefly
+ * (`waitForEditorWorkspace`) instead of failing at once.
+ *
  * Security: the registry is keyed by `userId` + workspace scope, so an MCP
  * connector can only ever reach the open workspace of its OWN owner and a
  * content tool can never be dispatched to the site editor (or vice versa).
@@ -23,15 +31,29 @@ import { MAIN_BRANCH_ID } from '@core/branches'
 import type { AiBrowserBridge, AiStreamEvent } from '../runtime/types'
 import { createBridge, encodeStreamEvent } from '../runtime'
 
-interface EditorBridgeEntry {
-  bridgeId: string
+export type EditorBridgeScope = 'site' | 'content'
+
+/** The live workspace a browser tool is relayed to. */
+export interface EditorWorkspace {
   bridge: AiBrowserBridge
   /** The branch the connected workspace has open; browser tools act in it. */
   branchId: string
-  destroy: () => void
 }
 
-export type EditorBridgeScope = 'site' | 'content'
+interface WorkspaceConnection extends EditorWorkspace {
+  bridgeId: string
+  tabId: string
+  /** Claim order: the highest claim among live connections is active. */
+  claim: number
+  close: () => void
+}
+
+interface TabClaim {
+  claim: number
+  /** When the tab's last connection closed; null while one is live. */
+  releasedAt: number | null
+}
+
 /**
  * How long a stream may sit with NO tool traffic before the server drops it.
  * This is an IDLE lease: every relayed tool request re-arms it, so an active
@@ -43,23 +65,119 @@ export type EditorBridgeScope = 'site' | 'content'
  */
 const STREAM_IDLE_LEASE_MS = 120_000
 
-const byUser = new Map<string, Map<EditorBridgeScope, EditorBridgeEntry>>()
+/**
+ * How long a disconnected tab keeps its claim. Long enough to cover any
+ * reconnect (idle recycle, deploy, laptop sleep) so the tab resumes its place
+ * instead of jumping ahead of a tab opened after it.
+ */
+const TAB_CLAIM_MEMORY_MS = 10 * 60_000
+
+const connections = new Map<string, Map<string, WorkspaceConnection>>()
+const claims = new Map<string, Map<string, TabClaim>>()
+const waiters = new Map<string, Set<() => void>>()
+let claimSequence = 0
+
+function workspaceKey(userId: string, scope: EditorBridgeScope): string {
+  return `${scope}\u0000${userId}`
+}
+
+function activeConnection(key: string): WorkspaceConnection | null {
+  let active: WorkspaceConnection | null = null
+  for (const connection of connections.get(key)?.values() ?? []) {
+    // `>=`: on a tie (one tab, two streams) the later registration wins.
+    if (!active || connection.claim >= active.claim) active = connection
+  }
+  return active
+}
+
+/** The live workspace for a user and scope, or null when none is connected. */
+export function getEditorWorkspace(userId: string, scope: EditorBridgeScope): EditorWorkspace | null {
+  const active = activeConnection(workspaceKey(userId, scope))
+  return active ? { bridge: active.bridge, branchId: active.branchId } : null
+}
 
-/** The live workspace bridge for a user and scope, or null when disconnected. */
-export function getEditorBridgeForUser(
+export function hasEditorBridge(userId: string, scope: EditorBridgeScope): boolean {
+  return activeConnection(workspaceKey(userId, scope)) !== null
+}
+
+/**
+ * The live workspace, waiting up to `timeoutMs` for one to connect. Covers
+ * the routine gaps in a workspace's stream (idle recycle, a reconnect after a
+ * network blip or server restart) so a tool call landing in one does not fail.
+ */
+export function waitForEditorWorkspace(
   userId: string,
   scope: EditorBridgeScope,
-): AiBrowserBridge | null {
-  return byUser.get(userId)?.get(scope)?.bridge ?? null
+  options: { timeoutMs: number; signal?: AbortSignal },
+): Promise<EditorWorkspace | null> {
+  const ready = getEditorWorkspace(userId, scope)
+  if (ready || options.timeoutMs <= 0 || options.signal?.aborted) return Promise.resolve(ready)
+
+  const key = workspaceKey(userId, scope)
+  return new Promise((resolve) => {
+    const set = waiters.get(key) ?? new Set<() => void>()
+    waiters.set(key, set)
+    const finish = (): void => {
+      clearTimeout(timer)
+      options.signal?.removeEventListener('abort', finish)
+      set.delete(finish)
+      if (set.size === 0) waiters.delete(key)
+      resolve(getEditorWorkspace(userId, scope))
+    }
+    const timer = setTimeout(finish, options.timeoutMs)
+    options.signal?.addEventListener('abort', finish, { once: true })
+    set.add(finish)
+  })
 }
 
-export function hasEditorBridge(userId: string, scope: EditorBridgeScope): boolean {
-  return byUser.get(userId)?.has(scope) ?? false
+function notifyWaiters(key: string): void {
+  for (const finish of [...(waiters.get(key) ?? [])]) finish()
 }
 
-/** The branch the user's live workspace has open, or null when disconnected. */
-export function getEditorBridgeBranch(userId: string, scope: EditorBridgeScope): string | null {
-  return byUser.get(userId)?.get(scope)?.branchId ?? null
+function pruneClaims(key: string, now: number): void {
+  const tabClaims = claims.get(key)
+  if (!tabClaims) return
+  for (const [tabId, claim] of tabClaims) {
+    if (claim.releasedAt !== null && now - claim.releasedAt > TAB_CLAIM_MEMORY_MS) tabClaims.delete(tabId)
+  }
+  if (tabClaims.size === 0) claims.delete(key)
+}
+
+function register(key: string, connection: Omit<WorkspaceConnection, 'claim'>): WorkspaceConnection {
+  const now = Date.now()
+  pruneClaims(key, now)
+
+  // A tab runs one stream at a time, so an older stream from the same tab is
+  // one the browser already abandoned. Close it rather than leave it as a
+  // routing candidate. (Closing unregisters it, which may drop the key's map,
+  // so the map is looked up only afterwards.)
+  for (const other of [...(connections.get(key)?.values() ?? [])]) {
+    if (other.tabId === connection.tabId) other.close()
+  }
+  const live = connections.get(key) ?? new Map<string, WorkspaceConnection>()
+  connections.set(key, live)
+
+  const tabClaims = claims.get(key) ?? new Map<string, TabClaim>()
+  claims.set(key, tabClaims)
+  const existing = tabClaims.get(connection.tabId)
+  const claim = existing?.claim ?? ++claimSequence
+  tabClaims.set(connection.tabId, { claim, releasedAt: null })
+
+  const entry: WorkspaceConnection = { ...connection, claim }
+  live.set(entry.bridgeId, entry)
+  notifyWaiters(key)
+  return entry
+}
+
+function unregister(key: string, bridgeId: string): void {
+  const live = connections.get(key)
+  const entry = live?.get(bridgeId)
+  if (!live || !entry) return
+  live.delete(bridgeId)
+  if (live.size === 0) connections.delete(key)
+  const tabStillLive = [...live.values()].some((other) => other.tabId === entry.tabId)
+  const tabClaim = claims.get(key)?.get(entry.tabId)
+  if (tabClaim && !tabStillLive) tabClaim.releasedAt = Date.now()
 }
 
 /**
@@ -74,11 +192,17 @@ export function createEditorBridgeStream(
   options: {
     /** The branch the workspace has open (its `X-Instatic-Branch`); main when absent. */
     branchId?: string
+    /**
+     * Stable id of the browser tab across its reconnects. Absent (older
+     * clients, tests) → each stream counts as a newly opened tab.
+     */
+    tabId?: string
     /** Test seam: the idle lease shrinks to milliseconds in unit tests. */
     idleLeaseMs?: number
   } = {},
 ): ReadableStream<Uint8Array> {
   const { branchId = MAIN_BRANCH_ID, idleLeaseMs = STREAM_IDLE_LEASE_MS } = options
+  const key = workspaceKey(userId, scope)
   let closeStream: (() => void) | null = null
 
   return new ReadableStream<Uint8Array>({
@@ -99,14 +223,7 @@ export function createEditorBridgeStream(
         if (lease) clearTimeout(lease)
         signal.removeEventListener('abort', cleanup)
         destroyBridge()
-
-        // Only evict if we're still the current bridge for this scope. Keep
-        // the user's other workspace registered until its own stream closes.
-        const liveUserBridges = byUser.get(userId)
-        if (liveUserBridges?.get(scope)?.bridgeId === bridgeId) {
-          liveUserBridges.delete(scope)
-          if (liveUserBridges.size === 0) byUser.delete(userId)
-        }
+        unregister(key, bridgeId)
         try {
           controller.close()
         } catch {
@@ -149,13 +266,13 @@ export function createEditorBridgeStream(
       destroyBridge = created.destroy
       pendingCount = created.pendingCount
 
-      // Newest instance of this workspace wins. The user's other workspace
-      // remains connected, so Site and Content may serve MCP simultaneously.
-      const userBridges = byUser.get(userId) ?? new Map<EditorBridgeScope, EditorBridgeEntry>()
-      const previous = userBridges.get(scope)
-      if (previous) previous.destroy()
-      userBridges.set(scope, { bridgeId, bridge: created.bridge, branchId, destroy: destroyBridge })
-      byUser.set(userId, userBridges)
+      register(key, {
+        bridgeId,
+        tabId: options.tabId ?? bridgeId,
+        bridge: created.bridge,
+        branchId,
+        close: cleanup,
+      })
 
       emit({ type: 'bridgeReady', bridgeId })
 
diff --git a/server/ai/mcp/handlers/editorBridge.ts b/server/ai/mcp/handlers/editorBridge.ts
index d2fd49826..1b4871d64 100644
--- a/server/ai/mcp/handlers/editorBridge.ts
+++ b/server/ai/mcp/handlers/editorBridge.ts
@@ -30,6 +30,8 @@ const EditorBridgeScopeSchema = Type.Union([
   Type.Literal('site'),
   Type.Literal('content'),
 ])
+// Opaque per-tab id the client generates once and reuses across reconnects.
+const TabIdSchema = Type.String({ pattern: '^[A-Za-z0-9_-]{1,64}$' })
 
 // Mirrors the Content workspace entry gate in `src/admin/access.ts` and
 // `requireDataAccess` in the server's data access layer.
@@ -59,10 +61,8 @@ async function handle(req: Request, db: DbClient): Promise<Response> {
   const userOrResponse = await requireAuthenticatedUser(req, db)
   if (userOrResponse instanceof Response) return userOrResponse
 
-  const scopeResult = safeParseValue(
-    EditorBridgeScopeSchema,
-    new URL(req.url).searchParams.get('scope'),
-  )
+  const searchParams = new URL(req.url).searchParams
+  const scopeResult = safeParseValue(EditorBridgeScopeSchema, searchParams.get('scope'))
   if (!scopeResult.ok) {
     return jsonResponse(
       { error: 'Query parameter `scope` is required (one of: site, content)' },
@@ -70,6 +70,11 @@ async function handle(req: Request, db: DbClient): Promise<Response> {
     )
   }
   const scope: EditorBridgeScope = scopeResult.value
+  const rawTabId = searchParams.get('tabId')
+  const tabIdResult = rawTabId === null ? null : safeParseValue(TabIdSchema, rawTabId)
+  if (tabIdResult && !tabIdResult.ok) {
+    return jsonResponse({ error: 'Query parameter `tabId` is invalid' }, { status: 400 })
+  }
 
   // Hosting a bridge requires access to the workspace whose live state the
   // browser tool will read or mutate.
@@ -85,7 +90,10 @@ async function handle(req: Request, db: DbClient): Promise<Response> {
   const branch = await resolveBranchScope(req, db)
   if (branch instanceof Response) return branch
 
-  const stream = createEditorBridgeStream(userOrResponse.id, scope, req.signal, { branchId: branch.branchId })
+  const stream = createEditorBridgeStream(userOrResponse.id, scope, req.signal, {
+    branchId: branch.branchId,
+    tabId: tabIdResult?.value,
+  })
   return new Response(stream, {
     status: 200,
     headers: {
diff --git a/server/ai/mcp/instructions.ts b/server/ai/mcp/instructions.ts
index eae23d045..a52d836d1 100644
--- a/server/ai/mcp/instructions.ts
+++ b/server/ai/mcp/instructions.ts
@@ -1,11 +1,16 @@
 /**
  * Server instructions advertised to MCP clients at `initialize`. External
  * agents never see the in-app system prompt, so the rules that keep a site
- * editable in the visual editor have to travel with the connection.
+ * editable in the visual editor — and lean on the published page — have to
+ * travel with the connection.
  */
 export const MCP_SERVER_INSTRUCTIONS = [
-  'Instatic is a visual editor: every style should stay editable per class in the Selectors and CSS panels.',
-  'Style pages and components through site_insert_html / site_replace_node_html (class= attributes plus a <style> block in the same call) and site_apply_css. These become reusable style rules, one per class, attached to the elements that wear them.',
-  'Do NOT put page or component styling in a stylesheet file with site_write_code_asset type:"style". Those files load site-wide but are opaque to the editor: the CSS panel and class pills show empty rules, and editing one element means editing a minified file. Reserve file stylesheets for third-party or vendor CSS you must keep verbatim.',
-  'Before restyling, call site_read_document and reuse the existing classes instead of adding a second rule for the same element.',
+  'Instatic is a visual editor: every style and script should stay editable in the editor panels (Selectors, CSS, JS), and published pages should load only the code they use.',
+  'Start with get_context: it reports whether the Site editor is open. Editing tools (site_*) run in that open editor tab; if none connects within 15 seconds the call fails, so ask the user to open the Site editor. Short reconnects are absorbed automatically: do not treat one failed call as a lost connection.',
+  'If a call reports the editor disconnected while it was running, the edit may or may not have applied: re-read the document (site_read_document) before retrying instead of repeating the write blindly.',
+  'CSS: style pages and components through site_insert_html / site_replace_node_html (class= attributes plus a <style> block in the same call) and site_apply_css. These become reusable style rules, one per class, shown in the CSS panel; the publisher only ships rules for classes the site actually uses.',
+  'Do NOT put page or component styling in a stylesheet file with site_write_code_asset type:"style". Those files are opaque to the editor: the CSS panel and class pills show empty rules. Reserve file stylesheets for third-party or vendor CSS you must keep verbatim.',
+  'JS: behavior for one page (sliders, tabs, accordions, forms, animations) goes in site_write_page_script — the page script the JS panel edits, loaded only on that page. Shared behavior uses site_write_code_asset type:"script" with the narrowest runtime.scope (pages or templates); { type:"all-pages" } only for code every page needs. Never put <script> or on* handlers in HTML: they are stripped.',
+  'Scripts run at DOM-ready as modules: select the elements they drive by class or data attribute and return early when none are present.',
+  'Before restyling, call site_read_document and reuse the existing classes instead of adding a second rule for the same element. Edits stay drafts until site_publish.',
 ].join('\n')
diff --git a/server/ai/mcp/server.test.ts b/server/ai/mcp/server.test.ts
index d34a2b3f1..03d319cf7 100644
--- a/server/ai/mcp/server.test.ts
+++ b/server/ai/mcp/server.test.ts
@@ -47,8 +47,9 @@ async function connectClient(
   db: DbClient,
   capabilities: Parameters<typeof buildMcpServer>[0]['capabilities'],
   userId = 'u1',
+  workspaceWaitMs = 50,
 ) {
-  const server = buildMcpServer({ db, userId, connectorId: 'c1', capabilities })
+  const server = buildMcpServer({ db, userId, connectorId: 'c1', capabilities, workspaceWaitMs })
   const [clientT, serverT] = InMemoryTransport.createLinkedPair()
   await server.connect(serverT)
   const client = new Client({ name: 'test', version: '0' })
@@ -63,6 +64,7 @@ describe('mcp server', () => {
   it('advertises styling instructions so external agents keep CSS in editable rules', async () => {
     const client = await connectClient(db, ['ai.chat', 'site.read'])
     expect(client.getInstructions()).toContain('site_write_code_asset')
+    expect(client.getInstructions()).toContain('site_write_page_script')
     await client.close()
   })
 
@@ -195,12 +197,86 @@ describe('mcp server', () => {
 
     const result = await call
     expect(result.isError).toBe(true)
-    expect(JSON.stringify(result.content)).toContain('before tool result arrived')
+    const text = JSON.stringify(result.content)
+    expect(text).toContain('Site editor tab disconnected while')
+    expect(text).toContain('may or may not have been applied')
 
     await client.close()
     await reader.read().catch(() => {})
   })
 
+  it('waits for the workspace to connect instead of failing inside a reconnect gap', async () => {
+    const userId = 'u1-late-workspace'
+    const client = await connectClient(
+      db,
+      ['ai.chat', 'ai.tools.write', 'site.structure.edit'],
+      userId,
+      2_000,
+    )
+
+    const call = client.callTool({
+      name: 'site_insert_html',
+      arguments: { parentId: 'root', html: '<p>late</p>' },
+    })
+    // The editor reconnects only after the call has started waiting.
+    await new Promise((resolve) => setTimeout(resolve, 30))
+    const controller = new AbortController()
+    const reader = createEditorBridgeStream(userId, 'site', controller.signal).getReader()
+    const ready = await readUntil(reader, (event) => event.type === 'bridgeReady')
+    const request = await readUntil(reader, (event) => event.type === 'toolRequest')
+    resolveBridgeToolResult(ready.bridgeId as string, request.requestId as string, { ok: true, data: { inserted: 1 } })
+
+    const result = await call
+    expect(result.isError).toBeFalsy()
+    expect(JSON.stringify(result.content)).toContain('inserted')
+
+    controller.abort()
+    await client.close()
+    await reader.read().catch(() => {})
+  })
+
+  it('retries a call the closing tab never received on the tab that replaces it', async () => {
+    const userId = 'u1-undelivered-retry'
+    const firstCtrl = new AbortController()
+    const first = createEditorBridgeStream(userId, 'site', firstCtrl.signal, { tabId: 'tab-a' }).getReader()
+    await readUntil(first, (event) => event.type === 'bridgeReady')
+    const client = await connectClient(
+      db,
+      ['ai.chat', 'ai.tools.write', 'site.structure.edit'],
+      userId,
+      2_000,
+    )
+
+    // Occupy the serial bridge so the second call queues undelivered.
+    const busy = client.callTool({ name: 'site_insert_html', arguments: { parentId: 'root', html: '<p>1</p>' } })
+    await readUntil(first, (event) => event.type === 'toolRequest')
+    const queued = client.callTool({ name: 'site_delete_node', arguments: { nodeId: 'n1' } })
+    await new Promise((resolve) => setTimeout(resolve, 20))
+
+    // The same tab reconnects: its old stream closes with one delivered and one queued call.
+    const secondCtrl = new AbortController()
+    const second = createEditorBridgeStream(userId, 'site', secondCtrl.signal, { tabId: 'tab-a' }).getReader()
+    // The retry is pushed right behind bridgeReady, often in the same chunk.
+    let ready: { [k: string]: unknown } = {}
+    const retried = await readUntil(second, (event) => {
+      if (event.type === 'bridgeReady') ready = event
+      return event.type === 'toolRequest'
+    })
+    expect(retried.toolName).toBe('site_delete_node')
+    resolveBridgeToolResult(ready.bridgeId as string, retried.requestId as string, { ok: true, data: { deleted: 1 } })
+
+    const busyResult = await busy
+    expect(busyResult.isError).toBe(true)
+    expect(JSON.stringify(busyResult.content)).toContain('may or may not have been applied')
+    const queuedResult = await queued
+    expect(queuedResult.isError).toBeFalsy()
+
+    firstCtrl.abort()
+    secondCtrl.abort()
+    await client.close()
+    await Promise.all([first.read().catch(() => {}), second.read().catch(() => {})])
+  })
+
   it('enforces an own-only connector grant before relaying through a full-power owner browser', async () => {
     await db`
       insert into users (id, email, email_normalized, display_name, password_hash, role_id)
diff --git a/server/ai/mcp/server.ts b/server/ai/mcp/server.ts
index 918ce3deb..16fc3dda0 100644
--- a/server/ai/mcp/server.ts
+++ b/server/ai/mcp/server.ts
@@ -18,11 +18,12 @@ import type { DbClient } from '../../db/client'
 import type { CoreCapability } from '@core/capabilities'
 import { getErrorMessage } from '@core/utils/errorMessage'
 import type { AiBrowserBridge, AiTool, AiToolOutput } from '../runtime/types'
+import { BrowserToolInterruptedError } from '../runtime'
 import { executeAiTool } from '../drivers/http/execTool'
 import { mcpToolsForCapabilities } from './registry'
 import { MCP_SERVER_INSTRUCTIONS } from './instructions'
 import { authorizeMcpContentTool } from './contentAuthorization'
-import { getEditorBridgeBranch, getEditorBridgeForUser, type EditorBridgeScope } from './editorBridge'
+import { waitForEditorWorkspace, type EditorBridgeScope, type EditorWorkspace } from './editorBridge'
 import { runPublishFlush } from '../../publish/publishFlush'
 import { MAIN_SCOPE } from '../../branches/scope'
 
@@ -32,8 +33,18 @@ export interface McpServerContext {
   connectorId: string
   capabilities: readonly CoreCapability[]
   uploadsDir?: string
+  /** Test seam: how long a browser tool waits for its workspace to (re)connect. */
+  workspaceWaitMs?: number
 }
 
+/**
+ * How long a browser tool waits for the owner's workspace to connect before
+ * failing. An open editor's stream has routine gaps — the idle recycle, a
+ * reconnect after a network blip, a server restart — that last a few seconds;
+ * failing instantly inside one reads to the agent as "the tool disconnected".
+ */
+const WORKSPACE_WAIT_MS = 15_000
+
 // Used for server-resolved tools, which never call the bridge.
 const NOOP_BRIDGE: AiBrowserBridge = {
   callBrowser: async () => {
@@ -41,9 +52,46 @@ const NOOP_BRIDGE: AiBrowserBridge = {
   },
 }
 
+const WORKSPACE_LABEL: Record<EditorBridgeScope, string> = {
+  site: 'Site editor',
+  content: 'Content workspace',
+}
+
+const STATE_CHECK_HINT: Record<EditorBridgeScope, string> = {
+  site: 'Check the current state (site_read_document, site_list_code_assets) before retrying.',
+  content: 'Re-read the affected entry before retrying.',
+}
+
 const NO_WORKSPACE_MESSAGE: Record<EditorBridgeScope, string> = {
-  site: 'This tool runs in the Instatic Site editor. Open the Site editor in a browser (signed in as the connector owner) and try again.',
-  content: 'This tool runs in the Instatic Content workspace. Open the Content workspace in a browser (signed in as the connector owner) and try again.',
+  site: 'No Instatic Site editor connected within 15 seconds. This tool runs in the Site editor: ask the user to open it in a browser (signed in as the connector owner), then retry. Headless tools such as get_context keep working meanwhile.',
+  content: 'No Instatic Content workspace connected within 15 seconds. This tool runs in the Content workspace: ask the user to open it in a browser (signed in as the connector owner), then retry. Headless tools such as get_context keep working meanwhile.',
+}
+
+/**
+ * Explain an interrupted browser call in terms an external agent can act on.
+ * The transport's own messages are written for the in-app chat stream; over
+ * MCP the important fact is whether the edit could have been applied.
+ */
+function interruptionMessage(
+  err: BrowserToolInterruptedError,
+  toolName: string,
+  scope: EditorBridgeScope,
+): string {
+  const label = WORKSPACE_LABEL[scope]
+  if (!err.delivered) {
+    return `The ${label} disconnected before running "${toolName}"; nothing was applied. Retry the call. If it fails again, ask the user to check that the ${label} is open.`
+  }
+  if (err.reason === 'timeout') {
+    return `The ${label} did not finish "${toolName}" within 90 seconds. The edit may still complete. ${STATE_CHECK_HINT[scope]} Split very large edits into smaller calls.`
+  }
+  if (err.reason === 'aborted') {
+    return `"${toolName}" was cancelled before the ${label} returned a result; the edit may or may not have been applied. ${STATE_CHECK_HINT[scope]}`
+  }
+  return `The ${label} tab disconnected while "${toolName}" was running, so the result is unknown: the edit may or may not have been applied. ${STATE_CHECK_HINT[scope]}`
+}
+
+function isUndeliveredClosure(err: unknown): boolean {
+  return err instanceof BrowserToolInterruptedError && !err.delivered && err.reason === 'closed'
 }
 
 /**
@@ -149,6 +197,7 @@ export function buildMcpServer(ctx: McpServerContext): Server {
     // actionable error. Browser tools currently belong only to Site or
     // Content; keep that invariant explicit instead of guessing a bridge.
     let bridge = NOOP_BRIDGE
+    let browserScope: EditorBridgeScope | null = null
     if (tool.execution === 'browser') {
       if (tool.scope !== 'site' && tool.scope !== 'content') {
         return project({
@@ -156,31 +205,52 @@ export function buildMcpServer(ctx: McpServerContext): Server {
           content: [{ type: 'text', text: `Browser tool "${tool.name}" has unsupported scope "${tool.scope}".` }],
         })
       }
-      const browserScope: EditorBridgeScope = tool.scope
-      const live = getEditorBridgeForUser(ctx.userId, browserScope)
-      if (!live) {
+      const scope: EditorBridgeScope = tool.scope
+      browserScope = scope
+      const signal = requestContext.mcpReq.signal
+      const waitMs = ctx.workspaceWaitMs ?? WORKSPACE_WAIT_MS
+      const connect = () => waitForEditorWorkspace(ctx.userId, scope, { timeoutMs: waitMs, signal })
+
+      const initial = await connect()
+      if (!initial) {
         return project({
           isError: true,
-          content: [{ type: 'text', text: NO_WORKSPACE_MESSAGE[browserScope] }],
+          content: [{ type: 'text', text: NO_WORKSPACE_MESSAGE[scope] }],
         })
       }
-      bridge = browserScope === 'content'
-        ? {
-            callBrowser: async (toolName, input) => {
-              await authorizeMcpContentTool(
-                ctx.db,
-                ctx.userId,
-                ctx.capabilities,
-                toolName,
-                input,
-                { branchId: getEditorBridgeBranch(ctx.userId, browserScope) ?? MAIN_SCOPE.branchId },
-              )
-              const current = getEditorBridgeForUser(ctx.userId, browserScope)
-              if (!current) throw new Error(NO_WORKSPACE_MESSAGE[browserScope])
-              return current.callBrowser(toolName, input)
-            },
+
+      const run = async (
+        workspace: EditorWorkspace,
+        toolName: string,
+        input: unknown,
+      ): Promise<AiToolOutput> => {
+        if (scope === 'content') {
+          await authorizeMcpContentTool(
+            ctx.db,
+            ctx.userId,
+            ctx.capabilities,
+            toolName,
+            input,
+            { branchId: workspace.branchId },
+          )
+        }
+        return workspace.bridge.callBrowser(toolName, input)
+      }
+
+      bridge = {
+        callBrowser: async (toolName, input) => {
+          try {
+            return await run(initial, toolName, input)
+          } catch (err) {
+            // The tab's stream closed before the call was pushed to it, so the
+            // editor never saw it: retry once on whichever tab is live now.
+            if (!isUndeliveredClosure(err)) throw err
+            const next = await connect()
+            if (!next) throw new Error(NO_WORKSPACE_MESSAGE[scope], { cause: err })
+            return run(next, toolName, input)
           }
-        : live
+        },
+      }
     } else {
       // Headless reads hit the DB directly, but live co-editing persists on an
       // ~800 ms debounce — flush the relay first so a headless read reflects
@@ -208,13 +278,10 @@ export function buildMcpServer(ctx: McpServerContext): Server {
       // surrounding provider loop to terminate. Translate the same transport
       // failure into the protocol's normal tool-error result instead of
       // letting the request handler reject with an internal MCP error.
-      return project({
-        isError: true,
-        content: [{
-          type: 'text',
-          text: getErrorMessage(err, `Browser tool "${tool.name}" could not return a result.`),
-        }],
-      })
+      const text = err instanceof BrowserToolInterruptedError && browserScope
+        ? interruptionMessage(err, tool.name, browserScope)
+        : getErrorMessage(err, `Browser tool "${tool.name}" could not return a result.`)
+      return project({ isError: true, content: [{ type: 'text', text }] })
     }
 
     if (!output.ok) {
diff --git a/server/ai/mcp/tools/contextTool.ts b/server/ai/mcp/tools/contextTool.ts
index 632e556d5..79a6184fe 100644
--- a/server/ai/mcp/tools/contextTool.ts
+++ b/server/ai/mcp/tools/contextTool.ts
@@ -51,7 +51,7 @@ export const contextMcpTools: AiTool[] = [
   {
     name: 'get_context',
     description:
-      'Orient yourself before editing: reports whether the Site editor and Content workspace are connected (browser tools require their matching workspace), and which templates wrap pages — an "everywhere" template applies a nav/footer/etc. to every page, so anything you author is in addition to it. Pass entryId to also learn whether a template wraps that specific page. Headless — no editor needed. Call this first if a browser tool returns an "open the workspace" error.',
+      'Orient yourself before editing: reports whether the Site editor and Content workspace are connected (browser tools require their matching workspace), and which templates wrap pages — an "everywhere" template applies a nav/footer/etc. to every page, so anything you author is in addition to it. Pass entryId to also learn whether a template wraps that specific page. Headless — no editor needed. Browser tools wait up to 15 seconds for the matching workspace to (re)connect; if this reports it disconnected, ask the user to open it rather than retrying in a loop.',
     scope: 'site',
     execution: 'server',
     inputSchema: GetContextInput,
diff --git a/server/ai/runtime/index.ts b/server/ai/runtime/index.ts
index aa4471957..6dc757733 100644
--- a/server/ai/runtime/index.ts
+++ b/server/ai/runtime/index.ts
@@ -3,6 +3,7 @@
  */
 
 export {
+  BrowserToolInterruptedError,
   createBridge,
   encodeStreamEvent,
   resolveBridgeToolResult,
diff --git a/server/ai/runtime/transport.ts b/server/ai/runtime/transport.ts
index 284ec72d7..97a609708 100644
--- a/server/ai/runtime/transport.ts
+++ b/server/ai/runtime/transport.ts
@@ -43,11 +43,37 @@ export function encodeStreamEvent(event: AiStreamEvent): Uint8Array {
  */
 const BROWSER_TOOL_TIMEOUT_MS = 90_000
 
+/** Why a browser tool call settled without a result. */
+export type BrowserToolInterruption = 'closed' | 'aborted' | 'timeout'
+
+/**
+ * A browser tool call that never produced a result. `delivered` records
+ * whether the request had already been pushed to the browser: an undelivered
+ * call never ran and is safe to retry; a delivered one may or may not have
+ * applied its mutation.
+ */
+export class BrowserToolInterruptedError extends Error {
+  readonly reason: BrowserToolInterruption
+  readonly delivered: boolean
+
+  constructor(message: string, reason: BrowserToolInterruption, delivered: boolean) {
+    super(message)
+    this.name = 'BrowserToolInterruptedError'
+    this.reason = reason
+    this.delivered = delivered
+  }
+}
+
+const STREAM_ENDED_MESSAGE = 'AI chat stream ended before tool result arrived.'
+const STREAM_ABORTED_MESSAGE = 'AI chat stream aborted before tool result arrived.'
+
 interface PendingToolResolver {
   resolve(result: AiToolOutput): void
   reject(err: Error): void
   /** Clear the per-call timeout + abort listener. Idempotent. */
   cleanup(): void
+  /** Whether the request has been emitted to the browser. */
+  delivered(): boolean
 }
 
 interface BridgeEntry {
@@ -131,12 +157,12 @@ export function createBridge(
   const bridge: AiBrowserBridge = {
     callBrowser(toolName, input) {
       if (destroyed) {
-        return Promise.reject(new Error('AI chat stream ended before tool result arrived.'))
+        return Promise.reject(new BrowserToolInterruptedError(STREAM_ENDED_MESSAGE, 'closed', false))
       }
       const requestId = nanoid()
       return new Promise<AiToolOutput>((resolve, reject) => {
         if (signal?.aborted) {
-          reject(new Error('AI chat stream aborted before tool result arrived.'))
+          reject(new BrowserToolInterruptedError(STREAM_ABORTED_MESSAGE, 'aborted', false))
           return
         }
         let timer: ReturnType<typeof setTimeout> | null = null
@@ -151,11 +177,16 @@ export function createBridge(
           live.cleanup()
           reject(err)
         }
-        const onAbort = () => settle(new Error('AI chat stream aborted before tool result arrived.'))
+        const onAbort = () =>
+          settle(new BrowserToolInterruptedError(STREAM_ABORTED_MESSAGE, 'aborted', started))
         const start = () => {
           started = true
           timer = setTimeout(
-            () => settle(new Error(`Browser tool "${toolName}" result timed out.`)),
+            () => settle(new BrowserToolInterruptedError(
+              `Browser tool "${toolName}" result timed out.`,
+              'timeout',
+              true,
+            )),
             timeoutMs,
           )
           emit({ type: 'toolRequest', requestId, toolName, input })
@@ -171,7 +202,7 @@ export function createBridge(
         }
 
         signal?.addEventListener('abort', onAbort, { once: true })
-        entry.pending.set(requestId, { resolve, reject, cleanup })
+        entry.pending.set(requestId, { resolve, reject, cleanup, delivered: () => started })
         acquire(start)
       })
     },
@@ -191,8 +222,9 @@ export function createBridge(
       )
     }
     for (const pending of live.pending.values()) {
+      const delivered = pending.delivered()
       pending.cleanup()
-      pending.reject(new Error('AI chat stream ended before tool result arrived.'))
+      pending.reject(new BrowserToolInterruptedError(STREAM_ENDED_MESSAGE, 'closed', delivered))
     }
     live.pending.clear()
     activeBridges.delete(bridgeId)
diff --git a/server/ai/tools/site/systemPrompt.ts b/server/ai/tools/site/systemPrompt.ts
index 17015d060..372c9e41f 100644
--- a/server/ai/tools/site/systemPrompt.ts
+++ b/server/ai/tools/site/systemPrompt.ts
@@ -39,8 +39,10 @@ Structure as HTML, styling as CSS:
 
 Behavior and runtime code:
 - site_insert_html/site_replace_node_html deliberately strip <script> and inline event handlers (onclick/onload/etc). NEVER try to add behavior with <script>, onclick, or custom inline JS in HTML.
-- To add behavior such as theme toggles, tabs, menus, filters, or DOM-ready interactions, use site_write_code_asset({ type:"script", path:"src/scripts/...", content, runtime }). The script file is stored in the site file layer and loaded through site.runtime.
-- For npm packages in module scripts, import bare package specifiers (e.g. import { Motion } from "@motion.page/sdk") and include dependencies: { "@motion.page/sdk": "1.2.4" } in the SAME site_write_code_asset call. Do not use npm CDN URLs like esm.sh/unpkg/jsDelivr for packages that belong in the site dependency manifest.
+- JS loads only where it is used. Behavior for one page (sliders, tabs, accordions, filters, forms, animations) goes in that page's script: site_write_page_script({ pageId?, content }), the same file the God Mode JS panel edits. It loads only on that page.
+- Behavior several pages or a template share goes in site_write_code_asset({ type:"script", path:"src/scripts/...", content, runtime:{ scope } }) with the narrowest scope: { type:"pages", pageIds:[...] } or { type:"templates", templatePageIds:[...] }. Use { type:"all-pages" } only for behavior every page needs (site-wide nav toggle, analytics). New scripts must pass a scope.
+- Scripts run at DOM-ready as modules: select the elements they drive by class or data attribute and return early when none are on the page.
+- For npm packages in module scripts, import bare package specifiers (e.g. import { Motion } from "@motion.page/sdk") and include dependencies: { "@motion.page/sdk": "1.2.4" } in the SAME write call. Do not use npm CDN URLs like esm.sh/unpkg/jsDelivr for packages that belong in the site dependency manifest.
 - Never put page or component styling in a stylesheet file (site_write_code_asset type:"style"): the editor's Selectors and CSS panels cannot see it. Styling belongs in class rules via <style>/class= on inserts or site_apply_css. Use style files only for vendor CSS kept verbatim.
 - Before changing existing scripts or user stylesheets, call site_list_code_assets/site_read_code_asset. Patch exact spans with site_patch_code_asset using the latest hash; if the text occurs multiple times, use a larger oldText span or replaceAll:true intentionally.
 - Use site_inspect_code_runtime after writing code to confirm scripts/styles apply to the current page/template, are enabled, and have the intended priority/placement/timing.
diff --git a/server/ai/tools/site/writeTools.ts b/server/ai/tools/site/writeTools.ts
index 958343b8e..570af6e34 100644
--- a/server/ai/tools/site/writeTools.ts
+++ b/server/ai/tools/site/writeTools.ts
@@ -37,6 +37,7 @@ import {
   ListCodeAssetsInputSchema,
   ReadCodeAssetInputSchema,
   WriteCodeAssetInputSchema,
+  WritePageScriptInputSchema,
   PatchCodeAssetInputSchema,
   InspectCodeRuntimeInputSchema,
   AddPageInputSchema,
@@ -246,10 +247,20 @@ const writeCodeAssetTool: AiTool = {
   execution: 'browser',
   requiredCapabilities: SITE_STRUCTURE_CAPS,
   description:
-    'Create or replace a runtime script/style file in site.files and attach normalized site.runtime config. Use `type:"script"` for behavior such as theme toggles, menus, tabs, analytics hooks, and DOM-ready interactions; use `type:"style"` ONLY for third-party/vendor CSS that must stay verbatim as a file. Never use it for page or component styling: rules inside a stylesheet file are invisible to the Selectors and CSS panels, so each element becomes hard to edit. Style the page with site_insert_html/site_replace_node_html (class= plus a <style> block) or site_apply_css instead. `path` is a safe site-relative path such as src/scripts/theme-toggle.js or src/styles/theme.css. `runtime` is optional and merges with existing/default config. For module scripts that import npm packages, use bare package imports in `content` and declare them in `dependencies` (package name → semver/range) so they are added to the site dependency manifest; do not use npm CDN URLs for npm packages.',
+    'Create or replace a runtime script/style file in site.files and attach normalized site.runtime config. For behavior on ONE page, prefer site_write_page_script (the page script the God Mode JS panel edits). Use this tool for behavior shared by several pages or a template, or site-wide behavior. A NEW script must pass runtime.scope so it only loads where it is used: { type:"pages", pageIds:[...] }, { type:"templates", templatePageIds:[...] }, or { type:"all-pages" } only for behavior every page needs (site-wide nav, analytics). Use `type:"style"` ONLY for third-party/vendor CSS that must stay verbatim as a file. Never use it for page or component styling: rules inside a stylesheet file are invisible to the Selectors and CSS panels, so each element becomes hard to edit. Style the page with site_insert_html/site_replace_node_html (class= plus a <style> block) or site_apply_css instead. `path` is a safe site-relative path such as src/scripts/theme-toggle.js or src/styles/theme.css. `runtime` merges with existing/default config. For module scripts that import npm packages, use bare package imports in `content` and declare them in `dependencies` (package name → semver/range) so they are added to the site dependency manifest; do not use npm CDN URLs for npm packages.',
   inputSchema: WriteCodeAssetInputSchema,
 }
 
+const writePageScriptTool: AiTool = {
+  name: 'site_write_page_script',
+  scope: 'site',
+  execution: 'browser',
+  requiredCapabilities: SITE_STRUCTURE_CAPS,
+  description:
+    'Write the page script for one page: the same file the God Mode JS panel edits, scoped so it loads ONLY on that page (published and in the canvas). This is the default home for page behavior — sliders, tabs, accordions, forms, animations. Creates the script on first write and replaces its full content afterwards (read it first with site_read_code_asset if you are extending it). `pageId` defaults to the page open in the editor. The script is a module running at DOM-ready; query the elements it drives by class or data attribute and exit early when they are absent. For npm packages, use bare imports and declare them in `dependencies`.',
+  inputSchema: WritePageScriptInputSchema,
+}
+
 const patchCodeAssetTool: AiTool = {
   name: 'site_patch_code_asset',
   scope: 'site',
@@ -426,6 +437,7 @@ export const siteWriteTools: AiTool[] = [
   listCodeAssetsTool,
   readCodeAssetTool,
   writeCodeAssetTool,
+  writePageScriptTool,
   patchCodeAssetTool,
   inspectCodeRuntimeTool,
   addPageTool,
diff --git a/src/__tests__/admin/data/contentCollectionStepUp.test.tsx b/src/__tests__/admin/data/contentCollectionStepUp.test.tsx
index 1c7c922c3..53e02857f 100644
--- a/src/__tests__/admin/data/contentCollectionStepUp.test.tsx
+++ b/src/__tests__/admin/data/contentCollectionStepUp.test.tsx
@@ -120,7 +120,7 @@ describe('Content collection step-up flow', () => {
     globalThis.fetch = mock(async (input: RequestInfo | URL, init?: RequestInit) => {
       const url = String(input)
 
-      if (url === '/admin/api/ai/editor-bridge?scope=content') {
+      if (url.startsWith('/admin/api/ai/editor-bridge?scope=content&tabId=')) {
         contentBridgeRequests += 1
         return json({ error: 'Unauthorized' }, 401)
       }
diff --git a/src/__tests__/agent/contentBridge.test.ts b/src/__tests__/agent/contentBridge.test.ts
index 54beef6ba..7fcc5aa15 100644
--- a/src/__tests__/agent/contentBridge.test.ts
+++ b/src/__tests__/agent/contentBridge.test.ts
@@ -226,6 +226,7 @@ describe('runMcpWorkspaceBridgeConnection', () => {
         async () => ({ ok: true }),
         undefined,
         lifecycleController.signal,
+        'tab-1',
       )).rejects.toThrow('The editor bridge no longer owns this request.')
 
       expect(lifecycleController.signal.aborted).toBe(false)
@@ -236,6 +237,7 @@ describe('runMcpWorkspaceBridgeConnection', () => {
         async () => ({ ok: true }),
         undefined,
         lifecycleController.signal,
+        'tab-1',
       )).resolves.toBe('auth')
       expect(connectionSignals[1]?.aborted).toBe(true)
       expect(requestCount).toBe(3)
diff --git a/src/__tests__/agent/executor.test.ts b/src/__tests__/agent/executor.test.ts
index 03855339a..8f427009d 100644
--- a/src/__tests__/agent/executor.test.ts
+++ b/src/__tests__/agent/executor.test.ts
@@ -15,6 +15,7 @@ import { useEditorStore } from '@site/store/store'
 import { executeAgentTool } from '@site/agent'
 import type { AiToolOutput } from '@core/ai'
 import { classNamesForClassIds } from '@core/page-tree'
+import { findPageScript } from '@core/site-runtime'
 import '@modules/base'
 
 // ---------------------------------------------------------------------------
@@ -373,6 +374,45 @@ describe('executeAgentTool — style-only payloads', () => {
 // ---------------------------------------------------------------------------
 
 describe('executeAgentTool — code assets', () => {
+  it('write_code_asset refuses a new script without an explicit scope', async () => {
+    freshStore()
+    const result = await executeAgentTool('site_write_code_asset', {
+      path: 'src/scripts/slider.js',
+      type: 'script',
+      content: 'console.info("slider")',
+    })
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain('site_write_page_script')
+    expect(useEditorStore.getState().site!.files.some((file) => file.path === 'src/scripts/slider.js')).toBe(false)
+  })
+
+  it('write_page_script creates the page-only script the JS panel edits, then replaces it', async () => {
+    freshStore()
+    const pageId = useEditorStore.getState().activePageId!
+    const created = expectToolData<{ fileId: string; action: string; pageId: string }>(
+      await executeAgentTool('site_write_page_script', { content: 'const a = 1' }),
+    )
+    expect(created.action).toBe('created')
+    expect(created.pageId).toBe(pageId)
+    const state = useEditorStore.getState()
+    expect(findPageScript(state.site!.files, state.siteRuntime, pageId)?.id).toBe(created.fileId)
+    expect(state.siteRuntime.scripts[created.fileId]?.scope).toEqual({ type: 'pages', pageIds: [pageId] })
+
+    const updated = expectToolData<{ fileId: string; action: string }>(
+      await executeAgentTool('site_write_page_script', { pageId, content: 'const a = 2' }),
+    )
+    expect(updated).toMatchObject({ fileId: created.fileId, action: 'updated' })
+    const file = useEditorStore.getState().site!.files.find((item) => item.id === created.fileId)!
+    expect(file.content).toBe('const a = 2')
+  })
+
+  it('write_page_script rejects an unknown page', async () => {
+    freshStore()
+    const result = await executeAgentTool('site_write_page_script', { pageId: 'missing', content: '' })
+    expect(result.ok).toBe(false)
+    expect(result.error).toContain('Page not found')
+  })
+
   it('write_code_asset creates a runtime script with config and list/read expose it', async () => {
     freshStore()
     const result = await executeAgentTool('site_write_code_asset', {
@@ -439,7 +479,7 @@ describe('executeAgentTool — code assets', () => {
       path: 'src/scripts/motion.js',
       type: 'script',
       content: `import { Motion } from '@motion.page/sdk';\nwindow.Motion = Motion;`,
-      runtime: { format: 'module' },
+      runtime: { format: 'module', scope: { type: 'all-pages' } },
       dependencies: { '@motion.page/sdk': '1.2.4' },
     })
 
@@ -501,6 +541,7 @@ describe('executeAgentTool — code assets', () => {
       path: 'src/scripts/long.js',
       type: 'script',
       content,
+      runtime: { scope: { type: 'all-pages' } },
     })
     const hash = expectHash(write)
 
@@ -535,6 +576,7 @@ describe('executeAgentTool — code assets', () => {
       path: 'src/scripts/theme-toggle.js',
       type: 'script',
       content: 'const initial = "light";\nconst next = "dark";\n',
+      runtime: { scope: { type: 'all-pages' } },
     })
     const oldHash = expectHash(write)
 
@@ -570,6 +612,7 @@ describe('executeAgentTool — code assets', () => {
       path: 'src/scripts/repeated.js',
       type: 'script',
       content: 'theme = "light";\ntheme = "light";\n',
+      runtime: { scope: { type: 'all-pages' } },
     })
     const oldHash = expectHash(write)
 
diff --git a/src/__tests__/ai/editorBridgeLease.test.ts b/src/__tests__/ai/editorBridgeLease.test.ts
index c6066e949..272a96b90 100644
--- a/src/__tests__/ai/editorBridgeLease.test.ts
+++ b/src/__tests__/ai/editorBridgeLease.test.ts
@@ -8,7 +8,7 @@
 import { describe, expect, it } from 'bun:test'
 import {
   createEditorBridgeStream,
-  getEditorBridgeForUser,
+  getEditorWorkspace,
   hasEditorBridge,
 } from '../../../server/ai/mcp/editorBridge'
 import { resolveBridgeToolResult } from '../../../server/ai/runtime/transport'
@@ -74,7 +74,7 @@ describe('editor bridge idle lease', () => {
     // Tool traffic every ~40ms for well past the 80ms lease: the stream must
     // survive because every relayed request re-arms the idle lease.
     for (let i = 0; i < 6; i++) {
-      const bridge = getEditorBridgeForUser(userId, 'site')
+      const bridge = getEditorWorkspace(userId, 'site')?.bridge ?? null
       expect(bridge).not.toBeNull()
       await bridge?.callBrowser('noop_tool', {})
       await sleep(40)
@@ -114,7 +114,7 @@ describe('editor bridge batch delivery', () => {
 
     // Four calls pushed together take ~200ms to execute serially — well past
     // the 80ms lease. Every one must still succeed.
-    const bridge = getEditorBridgeForUser(userId, 'site')
+    const bridge = getEditorWorkspace(userId, 'site')?.bridge ?? null
     const results = await Promise.all(
       ['a', 'b', 'c', 'd'].map((name) => bridge!.callBrowser(name, {})),
     )
@@ -133,7 +133,7 @@ describe('editor bridge batch delivery', () => {
 
     // Nothing answers: the call stays pending far past the lease. Closing the
     // stream now would reject it while the editor may still be working on it.
-    const pending = getEditorBridgeForUser(userId, 'site')!.callBrowser('slow_tool', {})
+    const pending = getEditorWorkspace(userId, 'site')!.bridge.callBrowser('slow_tool', {})
     pending.catch(() => {})
     await sleep(150)
     expect(hasEditorBridge(userId, 'site')).toBe(true)
diff --git a/src/__tests__/architecture/agent-tool-surface.test.ts b/src/__tests__/architecture/agent-tool-surface.test.ts
index 3a148b8e1..57a890789 100644
--- a/src/__tests__/architecture/agent-tool-surface.test.ts
+++ b/src/__tests__/architecture/agent-tool-surface.test.ts
@@ -90,7 +90,7 @@ describe('agent-tool-surface gate', () => {
     expect(toolNames).toContain('site_clear_page_template')
   })
 
-  it('total tool count is 29 (document, HTML, node, CSS, code asset, page, template, token, and snapshot tools)', () => {
-    expect(toolNames).toHaveLength(29)
+  it('total tool count is 30 (document, HTML, node, CSS, code asset, page script, page, template, token, and snapshot tools)', () => {
+    expect(toolNames).toHaveLength(30)
   })
 })
diff --git a/src/__tests__/architecture/ai-tool-schema-ssot.test.ts b/src/__tests__/architecture/ai-tool-schema-ssot.test.ts
index 9a1ffaf2c..a1b89b02a 100644
--- a/src/__tests__/architecture/ai-tool-schema-ssot.test.ts
+++ b/src/__tests__/architecture/ai-tool-schema-ssot.test.ts
@@ -48,6 +48,7 @@ import {
   ListCodeAssetsInputSchema,
   ReadCodeAssetInputSchema,
   WriteCodeAssetInputSchema,
+  WritePageScriptInputSchema,
   PatchCodeAssetInputSchema,
   InspectCodeRuntimeInputSchema,
   AddPageInputSchema,
@@ -83,6 +84,7 @@ const EXPECTED_SCHEMA_BY_TOOL = {
   site_list_code_assets: ListCodeAssetsInputSchema,
   site_read_code_asset: ReadCodeAssetInputSchema,
   site_write_code_asset: WriteCodeAssetInputSchema,
+  site_write_page_script: WritePageScriptInputSchema,
   site_patch_code_asset: PatchCodeAssetInputSchema,
   site_inspect_code_runtime: InspectCodeRuntimeInputSchema,
   site_add_page: AddPageInputSchema,
diff --git a/src/admin/ai/useMcpWorkspaceBridge.ts b/src/admin/ai/useMcpWorkspaceBridge.ts
index 7245225f4..b562752cd 100644
--- a/src/admin/ai/useMcpWorkspaceBridge.ts
+++ b/src/admin/ai/useMcpWorkspaceBridge.ts
@@ -5,6 +5,7 @@
  * through the site executor (or vice versa).
  */
 import { useEffect } from 'react'
+import { nanoid } from 'nanoid'
 import { Type } from '@core/utils/typeboxHelpers'
 import type { AiToolOutput } from '@core/ai'
 import { getErrorMessage } from '@core/utils/errorMessage'
@@ -77,13 +78,15 @@ export async function runMcpWorkspaceBridgeConnection(
   dispatchTool: McpToolDispatcher,
   afterSuccessfulTool: McpAfterSuccessfulTool | undefined,
   lifecycleSignal: AbortSignal,
+  tabId: string,
 ): Promise<McpBridgeConnectionOutcome> {
   const connectionController = new AbortController()
   const signal = AbortSignal.any([lifecycleSignal, connectionController.signal])
   let bridgeId = ''
 
   try {
-    const res = await fetch(`${MCP_BRIDGE_PATH}?scope=${scope}`, withAmbientHeaders({
+    const query = new URLSearchParams({ scope, tabId })
+    const res = await fetch(`${MCP_BRIDGE_PATH}?${query}`, withAmbientHeaders({
       method: 'GET',
       credentials: 'same-origin',
       // The bridge body stays newline-delimited JSON, but the event-stream
@@ -132,6 +135,10 @@ export function useMcpWorkspaceBridge(
     if (!enabled) return undefined
 
     const lifecycleController = new AbortController()
+    // Stable across this mount's reconnects: the server keeps a tab's place
+    // in line by this id, so an idle-recycle reconnect never steals the
+    // workspace from a tab opened later.
+    const tabId = nanoid()
     let stopped = false
     let reconnectTimer: ReturnType<typeof setTimeout> | null = null
 
@@ -144,6 +151,7 @@ export function useMcpWorkspaceBridge(
         dispatchTool,
         afterSuccessfulTool,
         lifecycleController.signal,
+        tabId,
       )
     }
 
diff --git a/src/admin/pages/site/agent/codeAssetTools.ts b/src/admin/pages/site/agent/codeAssetTools.ts
index fb767fcce..e5af1879b 100644
--- a/src/admin/pages/site/agent/codeAssetTools.ts
+++ b/src/admin/pages/site/agent/codeAssetTools.ts
@@ -7,6 +7,7 @@ import {
   type PatchCodeAssetInput,
   type ReadCodeAssetInput,
   type WriteCodeAssetInput,
+  type WritePageScriptInput,
 } from '@core/ai'
 import type { SiteFile } from '@core/files/schemas'
 import { isSafePath, normalizePath } from '@core/files/pathValidation'
@@ -15,6 +16,7 @@ import {
   DEFAULT_SCRIPT_RUNTIME_CONFIG,
   DEFAULT_STYLE_RUNTIME_CONFIG,
   assetScopeAppliesToPage,
+  findPageScript,
   normalizeScriptRuntimeConfig,
   normalizeSiteRuntimeConfig,
   normalizeStyleRuntimeConfig,
@@ -142,7 +144,7 @@ function setRuntimeForCodeAsset(
 }
 
 function normalizeRequestedRuntimeDependencies(
-  input: WriteCodeAssetInput,
+  input: { type: CodeAssetType; dependencies?: Record<string, string> },
 ): { ok: true; dependencies: Record<string, string> } | { ok: false; error: string } {
   const entries = Object.entries(input.dependencies ?? {})
   if (entries.length === 0) return { ok: true, dependencies: {} }
@@ -259,6 +261,23 @@ const STYLE_FILE_CLASS_RULES_WARNING =
   'so each element becomes hard to edit. Move page/component styling into style rules: a <style> block via ' +
   'site_insert_html/site_replace_node_html, or site_apply_css. Keep files only for vendor CSS that must stay verbatim.'
 
+/**
+ * A new script must say where it loads. The runtime default is every page,
+ * which is wrong for most behavior (a slider, a form, an animation lives on
+ * one page), so the agent has to choose instead of inheriting it silently.
+ */
+const NEW_SCRIPT_SCOPE_REQUIRED =
+  'A new script needs an explicit runtime.scope so it only loads where it is used. ' +
+  'For behavior on one page, use site_write_page_script instead (the page script the God Mode JS panel edits). ' +
+  'For several pages pass runtime.scope { type:"pages", pageIds:[...] }; for a template pass ' +
+  '{ type:"templates", templatePageIds:[...] }; only behavior every page needs (site-wide nav, analytics) should use { type:"all-pages" }.'
+
+function setRuntimeDependencies(dependencies: Record<string, string>): void {
+  for (const [name, version] of Object.entries(dependencies)) {
+    getStoreState().setDependency(name, version, false)
+  }
+}
+
 export async function runWriteCodeAsset(input: WriteCodeAssetInput): Promise<AiToolOutput> {
   const store = getStoreState()
   const site = store.site
@@ -283,6 +302,9 @@ export async function runWriteCodeAsset(input: WriteCodeAssetInput): Promise<AiT
     fileId = existing.id
     action = 'updated'
   } else {
+    if (input.type === 'script' && input.runtime?.scope === undefined) {
+      return aiToolError(NEW_SCRIPT_SCOPE_REQUIRED)
+    }
     fileId = store.createFile(path, input.type, input.content)
     action = 'created'
   }
@@ -293,10 +315,7 @@ export async function runWriteCodeAsset(input: WriteCodeAssetInput): Promise<AiT
     return aiToolError(`Code asset write failed for ${path}.`)
   }
   setRuntimeForCodeAsset(afterContentStore, file, input.runtime)
-
-  for (const [name, version] of Object.entries(requestedDependencies.dependencies)) {
-    getStoreState().setDependency(name, version, false)
-  }
+  setRuntimeDependencies(requestedDependencies.dependencies)
 
   const afterRuntimeStore = getStoreState()
   const finalFile = afterRuntimeStore.site?.files.find((candidate) => candidate.id === fileId)
@@ -313,6 +332,55 @@ export async function runWriteCodeAsset(input: WriteCodeAssetInput): Promise<AiT
   })
 }
 
+/**
+ * Write the page script: the script scoped to exactly one page, which the God
+ * Mode JS panel edits. Creates it on first write (file + page scope in one
+ * undo step, same as the panel) and replaces its content afterwards.
+ */
+export function runWritePageScript(input: WritePageScriptInput): AiToolOutput {
+  const store = getStoreState()
+  const site = store.site
+  if (!site) return aiToolError('No active site.')
+
+  let pageId = input.pageId
+  if (!pageId) {
+    if (store.activeDocument?.kind === 'visualComponent') {
+      return aiToolError(
+        'A Visual Component has no page script. Pass pageId for the page that uses it, or open that page first.',
+      )
+    }
+    pageId = activeRenderPage(store)?.id
+  }
+  if (!pageId) return aiToolError('No active page. Pass pageId.')
+  if (!site.pages.some((page) => page.id === pageId)) return aiToolError(`Page not found: ${pageId}`)
+
+  const requestedDependencies = normalizeRequestedRuntimeDependencies({
+    type: 'script',
+    dependencies: input.dependencies,
+  })
+  if (!requestedDependencies.ok) return aiToolError(requestedDependencies.error)
+
+  const existing = findPageScript(site.files, store.siteRuntime, pageId)
+  let fileId: string
+  if (existing) {
+    store.updateFileContent(existing.id, input.content)
+    fileId = existing.id
+  } else {
+    fileId = store.createPageScript(pageId, input.content)
+  }
+  setRuntimeDependencies(requestedDependencies.dependencies)
+
+  const after = getStoreState()
+  const file = after.site?.files.find((candidate) => candidate.id === fileId)
+  if (!file || !isCodeAssetFile(file)) return aiToolError(`Page script write failed for page ${pageId}.`)
+  return aiToolOk({
+    ...describeCodeAsset(after, file),
+    pageId,
+    action: existing ? 'updated' : 'created',
+    dependencies: requestedDependencies.dependencies,
+  })
+}
+
 export async function runPatchCodeAsset(input: PatchCodeAssetInput): Promise<AiToolOutput> {
   const store = getStoreState()
   const resolved = resolveCodeAsset(store, input)
diff --git a/src/admin/pages/site/agent/executor.ts b/src/admin/pages/site/agent/executor.ts
index bb58de022..a4bf7a48b 100644
--- a/src/admin/pages/site/agent/executor.ts
+++ b/src/admin/pages/site/agent/executor.ts
@@ -38,6 +38,7 @@ import {
   ListCodeAssetsInputSchema,
   ReadCodeAssetInputSchema,
   WriteCodeAssetInputSchema,
+  WritePageScriptInputSchema,
   PatchCodeAssetInputSchema,
   InspectCodeRuntimeInputSchema,
   AddPageInputSchema,
@@ -87,6 +88,7 @@ import {
   runPatchCodeAsset,
   runReadCodeAsset,
   runWriteCodeAsset,
+  runWritePageScript,
 } from './codeAssetTools'
 import { runRenderSnapshotAtBreakpoint } from './renderSnapshotAtBreakpoint'
 import { parseImportedStyleCss, runApplyCss } from './cssTools'
@@ -236,7 +238,7 @@ function runInsertHtml(input: InsertHtmlInput): AiToolOutput {
       return aiToolOk({ cssRulesCreated: result.created, cssRulesUpdated: result.updated })
     }
     const scriptHint = stripped.scripts > 0 || stripped.inlineHandlers > 0
-      ? ' Scripts and inline event handlers are stripped from HTML imports; create runtime behavior with site_write_code_asset({ type:"script", ... }) instead.'
+      ? ' Scripts and inline event handlers are stripped from HTML imports; add behavior with site_write_page_script (loads only on this page) or, for shared behavior, site_write_code_asset({ type:"script", runtime:{ scope } }) instead.'
       : ''
     return aiToolError(`HTML contained no importable elements or style rules.${scriptHint}`)
   }
@@ -376,7 +378,7 @@ function runReplaceNodeHtml(input: ReplaceNodeHtmlInput): AiToolOutput {
       return aiToolOk({ cssRulesCreated: result.created, cssRulesUpdated: result.updated })
     }
     const scriptHint = stripped.scripts > 0 || stripped.inlineHandlers > 0
-      ? ' Scripts and inline event handlers are stripped from HTML imports; create runtime behavior with site_write_code_asset({ type:"script", ... }) instead.'
+      ? ' Scripts and inline event handlers are stripped from HTML imports; add behavior with site_write_page_script (loads only on this page) or, for shared behavior, site_write_code_asset({ type:"script", runtime:{ scope } }) instead.'
       : ''
     return aiToolError(`HTML contained no importable elements or style rules.${scriptHint}`)
   }
@@ -635,6 +637,8 @@ export async function executeAgentTool(
         return await runReadCodeAsset(parseValue(ReadCodeAssetInputSchema, rawInput))
       case 'site_write_code_asset':
         return await runWriteCodeAsset(parseValue(WriteCodeAssetInputSchema, rawInput))
+      case 'site_write_page_script':
+        return runWritePageScript(parseValue(WritePageScriptInputSchema, rawInput))
       case 'site_patch_code_asset':
         return await runPatchCodeAsset(parseValue(PatchCodeAssetInputSchema, rawInput))
       case 'site_inspect_code_runtime':
diff --git a/src/admin/pages/site/agent/toolClassification.ts b/src/admin/pages/site/agent/toolClassification.ts
index 3d71f7057..8e19ecb00 100644
--- a/src/admin/pages/site/agent/toolClassification.ts
+++ b/src/admin/pages/site/agent/toolClassification.ts
@@ -59,5 +59,6 @@ export const SITE_MUTATION_TOOLS: ReadonlySet<string> = new Set([
   'site_set_type_scale',
   'site_set_spacing_scale',
   'site_write_code_asset',
+  'site_write_page_script',
   'site_patch_code_asset',
 ])
diff --git a/src/admin/pages/site/panels/AgentPanel/toolCallDisplay.ts b/src/admin/pages/site/panels/AgentPanel/toolCallDisplay.ts
index e0fbdc73b..667625e83 100644
--- a/src/admin/pages/site/panels/AgentPanel/toolCallDisplay.ts
+++ b/src/admin/pages/site/panels/AgentPanel/toolCallDisplay.ts
@@ -91,6 +91,8 @@ export function getToolCallDisplay(actionType: string, params: unknown): ToolCal
       return display('Reading code asset', codeAssetDetail(p), 'code', 'read')
     case 'write_code_asset':
       return display('Writing code asset', codeAssetDetail(p), 'code', 'write')
+    case 'write_page_script':
+      return display('Writing page script', pageDetail(p.pageId), 'code', 'write')
     case 'patch_code_asset':
       return display('Patching code asset', codeAssetDetail(p), 'code', 'write')
     case 'inspect_code_runtime':
diff --git a/src/core/ai/index.ts b/src/core/ai/index.ts
index 636fe323e..6cd121372 100644
--- a/src/core/ai/index.ts
+++ b/src/core/ai/index.ts
@@ -60,6 +60,7 @@ export {
   ListCodeAssetsInputSchema,
   ReadCodeAssetInputSchema,
   WriteCodeAssetInputSchema,
+  WritePageScriptInputSchema,
   PatchCodeAssetInputSchema,
   InspectCodeRuntimeInputSchema,
   AddPageInputSchema,
@@ -93,6 +94,7 @@ export type {
   ListCodeAssetsInput,
   ReadCodeAssetInput,
   WriteCodeAssetInput,
+  WritePageScriptInput,
   PatchCodeAssetInput,
   InspectCodeRuntimeInput,
   AddPageInput,
diff --git a/src/core/ai/toolSchemas.ts b/src/core/ai/toolSchemas.ts
index 217377e7b..a7b35fbc9 100644
--- a/src/core/ai/toolSchemas.ts
+++ b/src/core/ai/toolSchemas.ts
@@ -243,22 +243,34 @@ export const ReadCodeAssetInputSchema = Type.Composite([
 ])
 export type ReadCodeAssetInput = Static<typeof ReadCodeAssetInputSchema>
 
+const RuntimeDependenciesInputSchema = Type.Record(
+  Type.String(),
+  Type.String({ minLength: 1 }),
+  {
+    description:
+      'Runtime npm dependencies required by a module script. Keys are package names, values are semver versions/ranges. Only valid for scripts.',
+  },
+)
+
 export const WriteCodeAssetInputSchema = Type.Object({
   path: Type.String({ minLength: 1 }),
   type: CodeAssetTypeSchema,
   content: Type.String(),
   runtime: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
-  dependencies: Type.Optional(Type.Record(
-    Type.String(),
-    Type.String({ minLength: 1 }),
-    {
-      description:
-        'Runtime npm dependencies required by a module script. Keys are package names, values are semver versions/ranges. Only valid when type is "script".',
-    },
-  )),
+  dependencies: Type.Optional(RuntimeDependenciesInputSchema),
 })
 export type WriteCodeAssetInput = Static<typeof WriteCodeAssetInputSchema>
 
+export const WritePageScriptInputSchema = Type.Object({
+  pageId: Type.Optional(Type.String({
+    minLength: 1,
+    description: 'Page or template whose script to write. Defaults to the page open in the editor.',
+  })),
+  content: Type.String({ description: 'The full script source. Replaces the existing page script.' }),
+  dependencies: Type.Optional(RuntimeDependenciesInputSchema),
+})
+export type WritePageScriptInput = Static<typeof WritePageScriptInputSchema>
+
 export const PatchCodeAssetInputSchema = Type.Composite([
   CodeAssetRefInputSchema,
   Type.Object({

From afa311cd9a4c8a6b9eb64a3c5894ddac22d33456 Mon Sep 17 00:00:00 2001
From: Flying Web Solutions <flyingweb.ie@gmail.com>
Date: Mon, 2 Nov 2026 18:17:06 +0000
Subject: [PATCH 2/6] =?UTF-8?q?=E2=9C=A8=20feat(cli):=20add=20the=20instat?=
 =?UTF-8?q?ic=20CLI=20for=20terminals=20and=20AI=20agents?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A new npm package, `instatic` (packages/cli), run with `npx instatic` or
`bunx instatic`. It is a thin client of the existing /_instatic/mcp
endpoint using a personal access token, so capability checks, the editor
bridge, and drafts-until-publish behave exactly as for any MCP client.

Commands: login/logout/profiles, status, guide (prints the server's build
rules, which shell agents otherwise never see), wait-editor, tools, call,
publish, upload, and `mcp` — a local stdio MCP proxy for desktop clients
that replaces mcp-remote and reconnects after site restarts.

Reliability: failures are classified (auth / unreachable / server) into
stable exit codes; reads retry on network and gateway errors; tool calls
are re-sent only when the request provably never reached the server, so a
write is never applied twice; tool calls get a 150s timeout to cover the
server's editor wait plus its 90s per-call limit.

The bundle (scripts/build-cli.ts, `bun run cli:build`) inlines every
dependency into one file for Node 20+. The MCP SDK import gate now scans
packages/ and allows packages/cli/. Publishing to npm stays a manual step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/README.md                                |   2 +
 docs/features/cli.md                          | 102 ++++
 docs/features/mcp-connectors.md               |   4 +-
 package.json                                  |   2 +
 packages/cli/README.md                        |  77 +++
 packages/cli/package.json                     |  33 ++
 packages/cli/src/args.ts                      |  73 +++
 packages/cli/src/cli.test.ts                  | 273 ++++++++++
 packages/cli/src/cli.ts                       | 513 ++++++++++++++++++
 packages/cli/src/config.ts                    | 132 +++++
 packages/cli/src/connection.ts                | 233 ++++++++
 packages/cli/src/index.ts                     |  38 ++
 packages/cli/src/stdioProxy.ts                | 126 +++++
 packages/cli/tsconfig.json                    |  22 +
 scripts/build-cli.ts                          |  37 ++
 .../architecture/ai-driver-isolation.test.ts  |  16 +-
 tsconfig.json                                 |   3 +-
 17 files changed, 1677 insertions(+), 9 deletions(-)
 create mode 100644 docs/features/cli.md
 create mode 100644 packages/cli/README.md
 create mode 100644 packages/cli/package.json
 create mode 100644 packages/cli/src/args.ts
 create mode 100644 packages/cli/src/cli.test.ts
 create mode 100644 packages/cli/src/cli.ts
 create mode 100644 packages/cli/src/config.ts
 create mode 100644 packages/cli/src/connection.ts
 create mode 100644 packages/cli/src/index.ts
 create mode 100644 packages/cli/src/stdioProxy.ts
 create mode 100644 packages/cli/tsconfig.json
 create mode 100644 scripts/build-cli.ts

diff --git a/docs/README.md b/docs/README.md
index 90e3cd6cf..4187f1ad4 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -33,6 +33,7 @@ docs/
 │   ├── dashboard.md                ← Dashboard workspace + widget registry
 │   ├── spotlight.md                ← Cmd+K command palette
 │   ├── agent.md                    ← AI agent integration
+│   ├── cli.md                      ← the `instatic` npm CLI (terminal + agent client)
 │   ├── templates.md                ← entry templates + dynamic bindings
 │   ├── loops.md                    ← base.loop + loop sources
 │   ├── cms-native-forms.md         ← visual form primitives + data_rows submissions
@@ -153,6 +154,7 @@ Three categories, three voices:
 | [features/god-mode.md](features/god-mode.md)                     | God Mode: Code Dock (HTML \| CSS \| JS) replacing the properties sidebar |
 | [features/agent.md](features/agent.md)                           | AI agent integration and provider-agnostic runtime                   |
 | [features/mcp-connectors.md](features/mcp-connectors.md)         | Instatic as an MCP server — external AI clients drive the CMS over MCP |
+| [features/cli.md](features/cli.md)                               | The `instatic` CLI: terminal and AI-agent client for a site, plus a local stdio MCP proxy |
 | [features/templates.md](features/templates.md)                   | Entry templates + dynamic bindings + token interpolation             |
 | [features/loops.md](features/loops.md)                           | `base.loop` + loop entity sources                                    |
 | [features/cms-native-forms.md](features/cms-native-forms.md)     | Visual form primitives and secure public submissions                 |
diff --git a/docs/features/cli.md b/docs/features/cli.md
new file mode 100644
index 000000000..8f37bdc14
--- /dev/null
+++ b/docs/features/cli.md
@@ -0,0 +1,102 @@
+# `instatic` CLI
+
+A command-line client for an Instatic site, published to npm as `instatic` and run with `npx instatic` or `bunx instatic`. It lets a person in a terminal, or an AI agent that works through a shell, use the same tools MCP clients get: inspect the site, run editing tools in the open editor, upload media, and publish. `instatic mcp` also runs it as a local stdio MCP server for desktop clients.
+
+The CLI is a thin client of the [MCP endpoint](mcp-connectors.md). It holds no editing logic and no second protocol: every command is an authenticated MCP request to `/_instatic/mcp`, so capability checks, the editor bridge, and drafts-until-publish all behave exactly as they do for any MCP client.
+
+## Why a CLI next to MCP
+
+- **Shell-based agents.** Many coding agents are most reliable with a command that prints JSON and returns an exit code. `instatic call <tool> '<json>'` gives them that without an MCP client.
+- **Build rules in the terminal.** MCP clients receive the server instructions automatically; shell agents do not. `instatic guide` prints them (the CSS/JS build rules from `server/ai/mcp/instructions.ts`) plus CLI usage notes.
+- **Waiting for the editor.** Editing tools need the Site editor open in a browser. `instatic wait-editor` blocks until it is, so an agent can ask the user once instead of failing call after call.
+- **A first-party stdio bridge.** `instatic mcp` replaces the generic `mcp-remote` bridge for desktop clients and adds safe retries.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `login --url <site> [--token <t> \| --token-stdin] [--profile <name>]` | Verifies the token against the site (`get_context`), then saves the profile and makes it current. Prompts for the token without echo when run in a terminal. |
+| `logout [--profile <name>]` | Forgets a saved profile. Does not revoke the token server-side. |
+| `profiles [use <name>]` | Lists saved profiles (current marked `*`) or switches the current one. |
+| `status [--json]` | Site name, URL, profile, whether the Site editor and Content workspace are connected, tool count. |
+| `guide` | Prints the server's build rules and CLI usage notes. |
+| `wait-editor [--scope site\|content] [--timeout <s>]` | Polls `get_context` every 2 s until the workspace is connected (default timeout 120 s). |
+| `tools [<name>] [--json]` | Lists tools, or prints one tool's description and input schema. |
+| `call <tool> [<json> \| --input <file> \| -] [--json] [--images-dir <dir>]` | Runs a tool. Text results print to stdout (pretty-printed JSON); error results print to stderr. Image results (e.g. `site_render_snapshot`) are saved to `--images-dir`. |
+| `publish` | Runs `site_publish`. |
+| `upload <file> [--alt <text>] [--name <filename>]` | Uploads an image with `media_upload` (inline base64). |
+| `mcp` | Runs a stdio MCP server that forwards `tools/list` and `tools/call` to the site and advertises the site's own instructions. |
+
+Global options: `--profile`, `--url`, `--token`, `--json`, `--help`, `--version`.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success. |
+| 1 | The tool ran and reported an error (message on stderr). |
+| 2 | Usage error: bad arguments, not logged in, unknown command. |
+| 3 | Authentication failed: token expired, revoked, or wrong. |
+| 4 | The site could not be reached. |
+| 5 | `wait-editor` timed out. |
+| 6 | Any other server or protocol failure. |
+
+## Configuration
+
+Profiles live in one JSON file, written with owner-only permissions (`0600`) because it holds personal access tokens:
+
+1. `$INSTATIC_CONFIG`, else
+2. `$XDG_CONFIG_HOME/instatic/config.json`, else
+3. `~/.config/instatic/config.json`.
+
+The shape is `{ current?, profiles: { <name>: { url, token } } }`, validated with TypeBox on read. Every command resolves its connection as: `--url` / `--token` flags, then `INSTATIC_URL` / `INSTATIC_TOKEN`, then the selected profile (`--profile`, `INSTATIC_PROFILE`, or the saved current one). URLs are normalized, so a site origin and the full `…/_instatic/mcp` URL copied from the admin UI both work. `login` warns when a non-local URL is plain HTTP.
+
+Tokens are the same personal access tokens as any MCP client: **AI → MCP → Create access token**. Hosted OAuth is not used by the CLI.
+
+## Reliability rules
+
+`packages/cli/src/connection.ts` wraps the MCP SDK client:
+
+- The client pins MCP `2026-07-28` (the only revision Instatic serves as modern), so there is no version probe or fallback.
+- Failures are classified as `auth`, `unreachable`, or `server`. The SDK nests the real network error under `data.cause` as well as `cause`; the classifier walks both.
+- **Discovery and reads** (`connect`, `tools/list`) retry twice (500 ms, then 1.5 s) on network failures and gateway statuses (502/503/504). Each attempt builds a fresh client, since an SDK transport starts once.
+- **Tool calls retry only when the request never reached the server**: connection refused, DNS failure, or a gateway status. A connection reset after sending is not retried, so a write is never applied twice.
+- Tool calls use a 150 s timeout, above the server's own budget (up to 15 s waiting for the editor tab plus 90 s for the editor to run the tool). The SDK default of 60 s would cut slow editor calls off.
+
+`instatic mcp` (`stdioProxy.ts`) opens the remote session lazily and reopens it after an `unreachable` failure, so the desktop client keeps a live stdio server through site restarts. Connection failures during `tools/call` come back as tool errors with the classified message instead of protocol errors. The proxy exits cleanly when the desktop client closes its stdin.
+
+## Package layout
+
+```text
+packages/cli/
+  package.json        name "instatic", bin "instatic" → dist/instatic.js, Node >= 20
+  tsconfig.json       own strict project, referenced from the root tsconfig (tsc -b)
+  README.md           npm package page
+  src/index.ts        executable: wires process streams, hidden token prompt
+  src/cli.ts          command dispatch; all I/O injected through CliIo
+  src/args.ts         minimal argv parser
+  src/config.ts       profiles, URL normalization, connection resolution
+  src/connection.ts   MCP session, failure classification, safe retries
+  src/stdioProxy.ts   `instatic mcp`
+  src/cli.test.ts     end-to-end tests against the real handleMcpHttp
+```
+
+`scripts/build-cli.ts` (`bun run cli:build`) bundles `src/index.ts` with `Bun.build` into a single minified `dist/instatic.js` for Node. Every dependency (the MCP SDK packages, TypeBox) is inlined, so the published package has no runtime dependencies and `npx` installs one file. `bun run cli` runs the TypeScript source directly during development.
+
+The MCP SDK packages are allowed here as well as under `server/ai/mcp/`: the CLI is a client of that server. `ai-driver-isolation.test.ts` scans `packages/` and allows the `packages/cli/` prefix.
+
+## Tests
+
+`packages/cli/src/cli.test.ts` runs every command in-process with `fetch` routed into `handleMcpHttp` over an in-memory SQLite site: login and the `0600` config file, auth/unreachable/usage exit codes, gateway retries, `guide`, `tools`, headless and editor-relayed `call` (with a simulated editor bridge), stdin arguments, `wait-editor`, profiles, and the stdio proxy over an in-memory transport.
+
+## Publishing
+
+Publishing is a manual step:
+
+```sh
+cd packages/cli
+npm version <patch|minor|major>   # bumps packages/cli/package.json
+npm publish --access public        # prepublishOnly builds dist/ first
+```
+
+The CLI is versioned independently of the Instatic server. It depends only on the MCP wire protocol and the tool names it shortcuts (`get_context`, `site_publish`, `media_upload`).
diff --git a/docs/features/mcp-connectors.md b/docs/features/mcp-connectors.md
index f8685a6fb..5319d0bbb 100644
--- a/docs/features/mcp-connectors.md
+++ b/docs/features/mcp-connectors.md
@@ -108,7 +108,9 @@ claude mcp add instatic --transport http http://localhost:3000/_instatic/mcp \
   --header "Authorization: Bearer imcp_pat_…"
 ```
 
-Claude Desktop can also reach a local server through a local stdio bridge. The UI generates a ready-to-copy `mcp-remote` configuration that keeps the token in an environment variable instead of embedding it in the command arguments.
+Claude Desktop can also reach a local server through a local stdio bridge. The UI generates a ready-to-copy `mcp-remote` configuration that keeps the token in an environment variable instead of embedding it in the command arguments. The first-party alternative is `instatic mcp` from the [`instatic` CLI](cli.md), a stdio proxy that adds the CLI's safe retries and reconnects.
+
+Agents that work through a shell rather than MCP can use the same token with the [`instatic` CLI](cli.md) (`instatic call <tool> '<json>'`).
 
 Personal tokens are deliberately not the hosted-connector setup path. The hosted Claude connector form does not provide a general custom-header field, and a cloud-hosted connector cannot reach a local-only endpoint.
 
diff --git a/package.json b/package.json
index fbda64f52..f5aec3829 100644
--- a/package.json
+++ b/package.json
@@ -44,6 +44,8 @@
     "bootstrap:sync": "bun run scripts/sync-plugin-bootstrap.ts",
     "bootstrap:check": "bun run scripts/sync-plugin-bootstrap.ts --check",
     "instatic-plugin": "bun run src/core/plugin-sdk/cli/index.ts",
+    "cli": "bun run packages/cli/src/index.ts",
+    "cli:build": "bun run scripts/build-cli.ts",
     "bench": "bun run scripts/bench/index.ts",
     "bench:bundle": "bun run scripts/bench/index.ts --only=bundle",
     "bench:publisher": "bun run scripts/bench/index.ts --only=publisher",
diff --git a/packages/cli/README.md b/packages/cli/README.md
new file mode 100644
index 000000000..6cb67486a
--- /dev/null
+++ b/packages/cli/README.md
@@ -0,0 +1,77 @@
+# instatic
+
+Command-line client for [Instatic](https://github.com/flyingwebie/Instatic) sites. Drive the visual editor, upload media, and publish from a terminal — or let an AI agent do it.
+
+```sh
+npx instatic login --url https://your-site.com
+# or: bunx instatic login --url https://your-site.com
+```
+
+Create the access token in Instatic under **AI → MCP → Create access token**. `login` asks for it without echoing, or takes `--token` / `--token-stdin`.
+
+## For AI agents
+
+```sh
+instatic guide                       # the site's build rules — read first
+instatic wait-editor                 # block until the Site editor is open in a browser
+instatic tools                       # list tools
+instatic tools site_insert_html      # one tool's input schema
+instatic call site_read_document '{}'
+instatic call site_insert_html --input section.json
+instatic publish                     # drafts go live
+```
+
+`call` prints the tool's JSON result to stdout. Exit codes are stable:
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | The tool reported an error (message on stderr) |
+| 2 | Usage error / not logged in |
+| 3 | Token rejected (expired or revoked) |
+| 4 | Site unreachable |
+| 5 | `wait-editor` timed out |
+| 6 | Other server error |
+
+Editing tools run inside the Site editor, which must be open in a browser and signed in as the token's owner. Reads, `upload`, and `publish` work without it.
+
+## Desktop MCP clients
+
+`instatic mcp` runs a local stdio MCP server that forwards to your site, for clients such as Claude Desktop or Cursor:
+
+```json
+{
+  "mcpServers": {
+    "instatic": {
+      "command": "npx",
+      "args": ["-y", "instatic", "mcp"],
+      "env": {
+        "INSTATIC_URL": "https://your-site.com",
+        "INSTATIC_TOKEN": "imcp_pat_…"
+      }
+    }
+  }
+}
+```
+
+## Commands
+
+```text
+login --url <site> [--token <t> | --token-stdin] [--profile <name>]
+logout [--profile <name>]
+profiles [use <name>]
+status [--json]
+guide
+wait-editor [--scope site|content] [--timeout <seconds>]
+tools [<name>] [--json]
+call <tool> [<json> | --input <file> | -] [--json] [--images-dir <dir>]
+publish
+upload <file> [--alt <text>] [--name <filename>]
+mcp
+```
+
+Global options: `--profile <name>`, `--url <site>`, `--token <token>`, `--json`.
+
+Connections resolve from flags, then `INSTATIC_URL` / `INSTATIC_TOKEN`, then the saved profile. Profiles are stored in `~/.config/instatic/config.json` (or `$XDG_CONFIG_HOME/instatic/`, or `$INSTATIC_CONFIG`) with owner-only permissions.
+
+Requires Node 20+ or Bun.
diff --git a/packages/cli/package.json b/packages/cli/package.json
new file mode 100644
index 000000000..b47ab7e09
--- /dev/null
+++ b/packages/cli/package.json
@@ -0,0 +1,33 @@
+{
+  "name": "instatic",
+  "version": "0.1.0",
+  "description": "Command-line client for Instatic sites: drive the visual editor, publish, and upload media from a terminal or an AI agent.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "instatic": "dist/instatic.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flyingwebie/Instatic.git",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "instatic",
+    "cms",
+    "mcp",
+    "cli",
+    "ai-agents"
+  ],
+  "scripts": {
+    "build": "bun run ../../scripts/build-cli.ts",
+    "prepublishOnly": "bun run build"
+  }
+}
diff --git a/packages/cli/src/args.ts b/packages/cli/src/args.ts
new file mode 100644
index 000000000..dfe320815
--- /dev/null
+++ b/packages/cli/src/args.ts
@@ -0,0 +1,73 @@
+/**
+ * Minimal argv parser: positionals plus `--flag`, `--flag value`, and
+ * `--flag=value`. Boolean flags are declared up front so `--json tools` does
+ * not swallow `tools` as the flag's value.
+ */
+
+export interface ParsedArgs {
+  positionals: string[]
+  flags: Map<string, string | true>
+}
+
+const BOOLEAN_FLAGS = new Set(['json', 'help', 'version', 'token-stdin', 'all'])
+
+export function parseArgs(argv: readonly string[]): ParsedArgs {
+  const positionals: string[] = []
+  const flags = new Map<string, string | true>()
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--') {
+      positionals.push(...argv.slice(i + 1))
+      break
+    }
+    if (arg === '-h') {
+      flags.set('help', true)
+      continue
+    }
+    if (!arg.startsWith('--') || arg === '--') {
+      positionals.push(arg)
+      continue
+    }
+
+    const body = arg.slice(2)
+    const eq = body.indexOf('=')
+    if (eq !== -1) {
+      flags.set(body.slice(0, eq), body.slice(eq + 1))
+      continue
+    }
+    if (BOOLEAN_FLAGS.has(body)) {
+      flags.set(body, true)
+      continue
+    }
+    const next = argv[i + 1]
+    if (next === undefined || next.startsWith('--')) {
+      flags.set(body, true)
+      continue
+    }
+    flags.set(body, next)
+    i++
+  }
+
+  return { positionals, flags }
+}
+
+/** A string flag's value, or undefined. A bare `--flag` with no value is a usage error. */
+export function stringFlag(args: ParsedArgs, name: string): string | undefined {
+  const value = args.flags.get(name)
+  if (value === undefined) return undefined
+  if (value === true) throw new UsageError(`--${name} needs a value.`)
+  return value
+}
+
+export function booleanFlag(args: ParsedArgs, name: string): boolean {
+  return args.flags.get(name) === true
+}
+
+/** Wrong invocation: printed with a hint, exits with `EXIT.usage`. */
+export class UsageError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'UsageError'
+  }
+}
diff --git a/packages/cli/src/cli.test.ts b/packages/cli/src/cli.test.ts
new file mode 100644
index 000000000..c11d9b6b1
--- /dev/null
+++ b/packages/cli/src/cli.test.ts
@@ -0,0 +1,273 @@
+/**
+ * The CLI end to end against the real MCP handler: every command runs
+ * in-process with `fetch` routed straight into `handleMcpHttp` over an
+ * in-memory SQLite site, so the wire protocol, auth, and tool engine are the
+ * production ones.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Client, InMemoryTransport } from '@modelcontextprotocol/client'
+import { createSqliteClient } from '../../../server/db/sqlite'
+import { sqliteMigrations } from '../../../server/db/migrations-sqlite'
+import { runMigrations } from '../../../server/db/runMigrations'
+import type { DbClient } from '../../../server/db/client'
+import { handleMcpHttp } from '../../../server/ai/mcp'
+import { createBearerConnection } from '../../../server/ai/mcp/connectors/store'
+import { generatePersonalAccessToken, hashMcpSecret } from '../../../server/ai/mcp/connectors/token'
+import { createEditorBridgeStream } from '../../../server/ai/mcp/editorBridge'
+import { resolveBridgeToolResult } from '../../../server/ai/runtime'
+import { EXIT, runCli, type CliIo } from './cli'
+import { classifyFailure } from './connection'
+import { createProxyServer } from './stdioProxy'
+
+const SITE = 'http://localhost'
+
+let db: DbClient
+let token: string
+let configDir: string
+let userId: string
+
+beforeEach(async () => {
+  db = createSqliteClient(':memory:')
+  await runMigrations(db, sqliteMigrations)
+  userId = `cli-user-${Math.random().toString(36).slice(2)}`
+  await db`
+    insert into users (id, email, email_normalized, display_name, password_hash, role_id)
+    values (${userId}, ${`${userId}@example.com`}, ${`${userId}@example.com`}, 'CLI User', 'x', 'owner')
+  `
+  token = generatePersonalAccessToken()
+  await createBearerConnection(db, {
+    userId,
+    label: 'CLI test',
+    capabilities: ['ai.chat', 'ai.tools.write', 'site.read', 'site.structure.edit', 'content.manage', 'pages.edit'],
+    tokenHash: await hashMcpSecret(token),
+  })
+  configDir = await mkdtemp(join(tmpdir(), 'instatic-cli-'))
+})
+
+afterEach(async () => {
+  await rm(configDir, { recursive: true, force: true })
+})
+
+const handlerFetch = async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+  const res = await handleMcpHttp(new Request(input, init), db)
+  return res ?? new Response(null, { status: 404 })
+}
+
+async function run(argv: string[], overrides: Partial<CliIo> = {}) {
+  let stdout = ''
+  let stderr = ''
+  const code = await runCli({
+    argv,
+    env: { INSTATIC_CONFIG: join(configDir, 'config.json') },
+    stdout: (text) => { stdout += text },
+    stderr: (text) => { stderr += text },
+    readStdin: async () => '',
+    stdinIsTty: false,
+    fetch: handlerFetch,
+    sleep: async () => {},
+    ...overrides,
+  })
+  return { code, stdout, stderr }
+}
+
+async function login() {
+  const result = await run(['login', '--url', SITE, '--token', token])
+  expect(result.code).toBe(EXIT.ok)
+}
+
+/** Play the Site editor: answer every relayed tool request with `answer`. */
+async function openSiteEditor(answer: (toolName: string) => unknown) {
+  const controller = new AbortController()
+  const reader = createEditorBridgeStream(userId, 'site', controller.signal)
+    .pipeThrough(new TextDecoderStream())
+    .getReader()
+  let bridgeId = ''
+  let buffer = ''
+  const ready = Promise.withResolvers<void>()
+  void (async () => {
+    try {
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) return
+        buffer += value
+        let nl: number
+        while ((nl = buffer.indexOf('\n')) !== -1) {
+          const line = buffer.slice(0, nl).trim()
+          buffer = buffer.slice(nl + 1)
+          if (!line) continue
+          const event = JSON.parse(line)
+          if (event.type === 'bridgeReady') {
+            bridgeId = event.bridgeId
+            ready.resolve()
+          }
+          if (event.type === 'toolRequest') {
+            resolveBridgeToolResult(bridgeId, event.requestId, { ok: true, data: answer(event.toolName) })
+          }
+        }
+      }
+    } catch {
+      /* torn down by the test */
+    }
+  })()
+  await ready.promise
+  return () => controller.abort()
+}
+
+describe('instatic CLI', () => {
+  it('logs in, saves an owner-only profile, and reports status', async () => {
+    const login = await run(['login', '--url', `${SITE}/_instatic/mcp`, '--token', token])
+    expect(login.code).toBe(EXIT.ok)
+    expect(login.stdout).toContain('Logged in to http://localhost')
+    expect(login.stdout).toContain('Site editor is not open')
+
+    const configFile = join(configDir, 'config.json')
+    const saved = JSON.parse(await readFile(configFile, 'utf8'))
+    expect(saved).toEqual({ current: 'default', profiles: { default: { url: SITE, token } } })
+    expect((await stat(configFile)).mode & 0o777).toBe(0o600)
+
+    const status = await run(['status', '--json'])
+    expect(status.code).toBe(EXIT.ok)
+    const parsed = JSON.parse(status.stdout)
+    expect(parsed).toMatchObject({ url: SITE, profile: 'default', siteEditorConnected: false })
+    expect(parsed.tools).toBeGreaterThan(10)
+  })
+
+  it('exits with the auth code when the token is rejected', async () => {
+    const result = await run(['login', '--url', SITE, '--token', 'imcp_pat_wrong'])
+    expect(result.code).toBe(EXIT.auth)
+    expect(result.stderr).toContain('rejected the access token')
+  })
+
+  it('retries, then exits with the unreachable code when a gateway says the site is down', async () => {
+    let requests = 0
+    const result = await run(['status', '--url', SITE, '--token', token], {
+      fetch: async () => {
+        requests++
+        return new Response('upstream down', { status: 503 })
+      },
+    })
+    expect(result.code).toBe(EXIT.unreachable)
+    expect(result.stderr).toContain('Could not reach')
+    expect(requests).toBe(3)
+  })
+
+  it('classifies Node\'s refused-connection error as unreachable', () => {
+    const refused = new TypeError('fetch failed', {
+      cause: Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:3000'), { code: 'ECONNREFUSED' }),
+    })
+    expect(classifyFailure(refused, SITE).kind).toBe('unreachable')
+    expect(classifyFailure(new Error('boom'), SITE).kind).toBe('server')
+  })
+
+  it('tells the user to log in when no connection is configured', async () => {
+    const result = await run(['status'])
+    expect(result.code).toBe(EXIT.usage)
+    expect(result.stderr).toContain('instatic login')
+  })
+
+  it('prints the build rules plus CLI usage in guide', async () => {
+    await login()
+    const result = await run(['guide'])
+    expect(result.code).toBe(EXIT.ok)
+    expect(result.stdout).toContain('site_write_page_script')
+    expect(result.stdout).toContain('instatic call <tool>')
+  })
+
+  it('lists tools and shows one tool\'s schema', async () => {
+    await login()
+    const list = await run(['tools'])
+    expect(list.stdout).toContain('get_context')
+    const one = await run(['tools', 'site_write_page_script'])
+    expect(one.code).toBe(EXIT.ok)
+    expect(one.stdout).toContain('Input schema')
+    expect((await run(['tools', 'no_such_tool'])).code).toBe(EXIT.usage)
+  })
+
+  it('calls a headless tool and prints its JSON result', async () => {
+    await login()
+    const result = await run(['call', 'get_context', '{}'])
+    expect(result.code).toBe(EXIT.ok)
+    expect(JSON.parse(result.stdout)).toHaveProperty('editor')
+  })
+
+  it('relays a browser tool through the open editor', async () => {
+    await login()
+    const close = await openSiteEditor((toolName) => ({ ran: toolName }))
+    try {
+      const result = await run(['call', 'site_write_page_script', '{"content":"console.info(1)"}'])
+      expect(result.code).toBe(EXIT.ok)
+      expect(JSON.parse(result.stdout)).toEqual({ ran: 'site_write_page_script' })
+    } finally {
+      close()
+    }
+  })
+
+  it('reports tool errors on stderr with exit code 1', async () => {
+    await login()
+    const result = await run(['call', 'not_a_tool'])
+    expect(result.code).toBe(EXIT.toolError)
+    expect(result.stderr).toContain('Unknown tool')
+  })
+
+  it('rejects tool arguments that are not a JSON object', async () => {
+    await login()
+    expect((await run(['call', 'get_context', '[1]'])).code).toBe(EXIT.usage)
+    expect((await run(['call', 'get_context', '{bad'])).code).toBe(EXIT.usage)
+  })
+
+  it('reads tool arguments from stdin', async () => {
+    await login()
+    const result = await run(['call', 'get_context', '-'], { readStdin: async () => '{"entryId":"x"}' })
+    expect(result.code).toBe(EXIT.ok)
+    expect(JSON.parse(result.stdout).page).toMatchObject({ found: false })
+  })
+
+  it('wait-editor times out when no editor opens, and succeeds once one is open', async () => {
+    await login()
+    const missing = await run(['wait-editor', '--timeout', '0'])
+    expect(missing.code).toBe(EXIT.editorMissing)
+
+    const close = await openSiteEditor(() => null)
+    try {
+      const ready = await run(['wait-editor', '--timeout', '0'])
+      expect(ready.code).toBe(EXIT.ok)
+      expect(ready.stdout).toContain('Site editor connected')
+    } finally {
+      close()
+    }
+  })
+
+  it('switches and forgets profiles', async () => {
+    await login()
+    expect((await run(['login', '--profile', 'staging', '--url', SITE, '--token', token])).code).toBe(EXIT.ok)
+    expect((await run(['profiles'])).stdout).toContain('* staging')
+    expect((await run(['profiles', 'use', 'default'])).code).toBe(EXIT.ok)
+    expect((await run(['profiles'])).stdout).toContain('* default')
+    expect((await run(['logout', '--profile', 'staging'])).code).toBe(EXIT.ok)
+    expect((await run(['profiles', '--json'])).stdout).not.toContain('staging')
+  })
+
+  it('serves the site over a local MCP proxy with the site\'s own instructions and tools', async () => {
+    const { server, close } = await createProxyServer(
+      { url: SITE, token, profile: null },
+      { clientVersion: 'test', fetch: handlerFetch, log: () => {} },
+    )
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
+    await server.connect(serverTransport)
+    const client = new Client({ name: 'desktop', version: '0' })
+    await client.connect(clientTransport)
+    try {
+      expect(client.getInstructions()).toContain('site_write_page_script')
+      const { tools } = await client.listTools()
+      expect(tools.some((tool) => tool.name === 'get_context')).toBe(true)
+      const result = await client.callTool({ name: 'get_context', arguments: {} })
+      expect(result.isError).toBeFalsy()
+    } finally {
+      await client.close()
+      await close()
+    }
+  })
+})
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
new file mode 100644
index 000000000..402386fcf
--- /dev/null
+++ b/packages/cli/src/cli.ts
@@ -0,0 +1,513 @@
+/**
+ * Command dispatch for the `instatic` CLI.
+ *
+ * Everything the commands touch — argv, env, streams, stdin, the network — is
+ * injected through `CliIo`, so the whole CLI runs in-process under test
+ * against the real MCP handler. `index.ts` wires the real process.
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import type { FetchLike } from '@modelcontextprotocol/client'
+import { booleanFlag, parseArgs, stringFlag, UsageError, type ParsedArgs } from './args'
+import {
+  configPath,
+  DEFAULT_PROFILE,
+  isInsecureRemote,
+  normalizeSiteUrl,
+  readConfig,
+  resolveConnection,
+  selectedProfileName,
+  writeConfig,
+  type Env,
+  type ResolvedConnection,
+} from './config'
+import { ConnectionError, InstaticSession, resultText, type ToolCallResult } from './connection'
+import { runStdioProxy } from './stdioProxy'
+import pkg from '../package.json' with { type: 'json' }
+
+export const CLI_VERSION: string = pkg.version
+
+export const EXIT = {
+  ok: 0,
+  /** The tool ran and reported an error. */
+  toolError: 1,
+  usage: 2,
+  auth: 3,
+  unreachable: 4,
+  /** `wait-editor` timed out. */
+  editorMissing: 5,
+  server: 6,
+} as const
+
+export interface CliIo {
+  argv: readonly string[]
+  env: Env
+  stdout: (text: string) => void
+  stderr: (text: string) => void
+  readStdin: () => Promise<string>
+  stdinIsTty: boolean
+  /** Ask for a secret without echoing it. Absent when there is no terminal. */
+  promptSecret?: (question: string) => Promise<string>
+  /** Test seam: replaces the network. */
+  fetch?: FetchLike
+  /** Test seam for `wait-editor` polling. */
+  sleep?: (ms: number) => Promise<void>
+}
+
+const HELP = `instatic ${CLI_VERSION} — drive an Instatic site from the terminal or an AI agent
+
+Usage: instatic <command> [options]
+
+Setup
+  login --url <site> [--token <t> | --token-stdin]   Save and verify a connection
+  logout                                             Forget the selected profile
+  profiles [use <name>]                              List or switch saved profiles
+  status                                             Site, editor connection, tool count
+
+Agent workflow
+  guide                         Print the site's build rules (read this first)
+  wait-editor [--scope site|content] [--timeout <s>]
+                                Wait until the editor tab is open and connected
+  tools [<name>]                List tools, or show one tool's input schema
+  call <tool> [<json> | --input <file> | -]
+                                Run a tool; prints its JSON result
+  publish                       Publish the site (drafts go live)
+  upload <file> [--alt <text>] [--name <filename>]
+                                Add an image to the Media library
+
+Integrations
+  mcp                           Run as a local stdio MCP server (Claude Desktop,
+                                Cursor, …) that forwards to the site
+
+Global options
+  --profile <name>   Saved profile to use (default: the current one)
+  --url <site>       Site URL, overrides the profile (env INSTATIC_URL)
+  --token <token>    Access token, overrides the profile (env INSTATIC_TOKEN)
+  --json             Machine-readable output where supported
+  -h, --help         Show help    --version  Show version
+
+Exit codes: 0 ok · 1 tool error · 2 usage · 3 auth · 4 unreachable ·
+            5 editor not connected · 6 server error
+
+Create a token in Instatic under AI → MCP → Create access token.`
+
+const CLI_GUIDE_NOTE = `
+
+Using these tools from the instatic CLI:
+- instatic call <tool> '<json args>' runs one tool and prints its JSON result.
+- instatic tools <tool> shows a tool's input schema.
+- Editing tools (site_*) need the Site editor open in a browser:
+  run instatic wait-editor before a batch of edits.
+- Exit code 1 means the tool reported an error (message on stderr); read it
+  before retrying.`
+
+function globalConnectionFlags(args: ParsedArgs) {
+  return {
+    url: stringFlag(args, 'url'),
+    token: stringFlag(args, 'token'),
+    profile: stringFlag(args, 'profile'),
+  }
+}
+
+async function connect(args: ParsedArgs, io: CliIo): Promise<{ session: InstaticSession; connection: ResolvedConnection }> {
+  const config = await readConfig(configPath(io.env))
+  const connection = resolveConnection(globalConnectionFlags(args), io.env, config)
+  const session = await InstaticSession.open(connection, { clientVersion: CLI_VERSION, fetch: io.fetch })
+  return { session, connection }
+}
+
+async function withSession<T>(
+  args: ParsedArgs,
+  io: CliIo,
+  run: (session: InstaticSession, connection: ResolvedConnection) => Promise<T>,
+): Promise<T> {
+  const { session, connection } = await connect(args, io)
+  try {
+    return await run(session, connection)
+  } finally {
+    await session.close()
+  }
+}
+
+function printJson(io: CliIo, value: unknown): void {
+  io.stdout(`${JSON.stringify(value, null, 2)}\n`)
+}
+
+/** A tool result's text, pretty-printed when it is JSON. */
+function formatResultText(text: string): string {
+  try {
+    return JSON.stringify(JSON.parse(text), null, 2)
+  } catch {
+    return text
+  }
+}
+
+interface EditorContext {
+  site: { name: string } | null
+  editor: { siteConnected: boolean; contentConnected: boolean }
+}
+
+function parseContext(result: ToolCallResult): EditorContext | null {
+  if (result.isError) return null
+  try {
+    const parsed: unknown = JSON.parse(resultText(result))
+    if (typeof parsed !== 'object' || parsed === null || !('editor' in parsed)) return null
+    const { site, editor } = parsed as { site?: unknown; editor?: unknown }
+    if (typeof editor !== 'object' || editor === null) return null
+    const flags = editor as Record<string, unknown>
+    return {
+      site: typeof site === 'object' && site !== null && typeof (site as { name?: unknown }).name === 'string'
+        ? { name: (site as { name: string }).name }
+        : null,
+      editor: {
+        siteConnected: flags.siteConnected === true,
+        contentConnected: flags.contentConnected === true,
+      },
+    }
+  } catch {
+    return null
+  }
+}
+
+async function readContext(session: InstaticSession): Promise<EditorContext | null> {
+  return parseContext(await session.callTool('get_context', {}))
+}
+
+async function emitToolResult(io: CliIo, args: ParsedArgs, result: ToolCallResult): Promise<number> {
+  if (booleanFlag(args, 'json')) {
+    printJson(io, result)
+    return result.isError ? EXIT.toolError : EXIT.ok
+  }
+
+  const imagesDir = stringFlag(args, 'images-dir')
+  let imageIndex = 0
+  for (const block of result.content) {
+    if (block.type === 'text' && typeof block.text === 'string') {
+      const text = formatResultText(block.text)
+      if (result.isError) io.stderr(`${text}\n`)
+      else io.stdout(`${text}\n`)
+      continue
+    }
+    if (block.type === 'image' && typeof block.data === 'string') {
+      imageIndex++
+      const extension = block.mimeType?.split('/')[1]?.split('+')[0] ?? 'bin'
+      if (imagesDir) {
+        await mkdir(imagesDir, { recursive: true })
+        const path = join(imagesDir, `image-${imageIndex}.${extension}`)
+        await writeFile(path, Buffer.from(block.data, 'base64'))
+        io.stderr(`Saved image to ${path}\n`)
+      } else {
+        io.stderr(`[image ${imageIndex}: ${block.mimeType ?? 'unknown type'}; pass --images-dir <dir> to save it]\n`)
+      }
+    }
+  }
+  return result.isError ? EXIT.toolError : EXIT.ok
+}
+
+async function readToolInput(args: ParsedArgs, io: CliIo): Promise<Record<string, unknown>> {
+  const inline = args.positionals[2]
+  const inputFile = stringFlag(args, 'input')
+  if (inline !== undefined && inputFile !== undefined) {
+    throw new UsageError('Pass tool arguments either inline or with --input, not both.')
+  }
+
+  let raw: string
+  if (inputFile === '-' || inline === '-') raw = await io.readStdin()
+  else if (inputFile !== undefined) raw = await readFile(inputFile, 'utf8')
+  else if (inline !== undefined) raw = inline
+  else return {}
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new UsageError('Tool arguments must be a JSON object, e.g. \'{"pageId":"abc"}\'.')
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new UsageError('Tool arguments must be a JSON object, e.g. \'{"pageId":"abc"}\'.')
+  }
+  return parsed as Record<string, unknown>
+}
+
+async function readToken(args: ParsedArgs, io: CliIo): Promise<string> {
+  const flag = stringFlag(args, 'token')
+  if (flag) return flag
+  if (booleanFlag(args, 'token-stdin')) return (await io.readStdin()).trim()
+  if (io.env.INSTATIC_TOKEN) return io.env.INSTATIC_TOKEN
+  if (io.stdinIsTty && io.promptSecret) {
+    return (await io.promptSecret('Access token (Instatic → AI → MCP → Create access token): ')).trim()
+  }
+  throw new UsageError('No token given. Pass --token <token>, --token-stdin, or set INSTATIC_TOKEN.')
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+async function cmdLogin(args: ParsedArgs, io: CliIo): Promise<number> {
+  const rawUrl = stringFlag(args, 'url') ?? args.positionals[1] ?? io.env.INSTATIC_URL
+  if (!rawUrl) throw new UsageError('Pass the site URL: instatic login --url https://your-site.com')
+  const url = normalizeSiteUrl(rawUrl)
+  const token = await readToken(args, io)
+  if (!token) throw new UsageError('The token is empty.')
+  if (isInsecureRemote(url)) {
+    io.stderr(`Warning: ${url} is not HTTPS, so the token travels unencrypted.\n`)
+  }
+
+  const session = await InstaticSession.open({ url, token, profile: null }, { clientVersion: CLI_VERSION, fetch: io.fetch })
+  let context: EditorContext | null
+  try {
+    context = await readContext(session)
+  } finally {
+    await session.close()
+  }
+
+  const path = configPath(io.env)
+  const config = await readConfig(path)
+  const name = stringFlag(args, 'profile') ?? DEFAULT_PROFILE
+  config.profiles[name] = { url, token }
+  config.current = name
+  await writeConfig(path, config)
+
+  io.stdout(`Logged in to ${url}${context?.site ? ` (${context.site.name})` : ''} as profile "${name}".\n`)
+  if (context && !context.editor.siteConnected) {
+    io.stdout('The Site editor is not open yet: editing tools need it open in a browser.\n')
+  }
+  io.stdout('Next: instatic guide\n')
+  return EXIT.ok
+}
+
+async function cmdLogout(args: ParsedArgs, io: CliIo): Promise<number> {
+  const path = configPath(io.env)
+  const config = await readConfig(path)
+  const name = selectedProfileName(stringFlag(args, 'profile'), io.env, config)
+  if (!config.profiles[name]) {
+    io.stderr(`No saved profile "${name}".\n`)
+    return EXIT.usage
+  }
+  delete config.profiles[name]
+  if (config.current === name) delete config.current
+  await writeConfig(path, config)
+  io.stdout(`Removed profile "${name}". Revoke its token in Instatic under AI → MCP if it is no longer needed.\n`)
+  return EXIT.ok
+}
+
+async function cmdProfiles(args: ParsedArgs, io: CliIo): Promise<number> {
+  const path = configPath(io.env)
+  const config = await readConfig(path)
+
+  if (args.positionals[1] === 'use') {
+    const name = args.positionals[2]
+    if (!name) throw new UsageError('Usage: instatic profiles use <name>')
+    if (!config.profiles[name]) throw new UsageError(`No saved profile "${name}".`)
+    config.current = name
+    await writeConfig(path, config)
+    io.stdout(`Now using profile "${name}" (${config.profiles[name].url}).\n`)
+    return EXIT.ok
+  }
+
+  const names = Object.keys(config.profiles).sort()
+  if (booleanFlag(args, 'json')) {
+    printJson(io, names.map((name) => ({ name, url: config.profiles[name].url, current: name === config.current })))
+    return EXIT.ok
+  }
+  if (names.length === 0) {
+    io.stdout('No saved profiles. Run: instatic login --url <site>\n')
+    return EXIT.ok
+  }
+  for (const name of names) {
+    io.stdout(`${name === config.current ? '*' : ' '} ${name}  ${config.profiles[name].url}\n`)
+  }
+  return EXIT.ok
+}
+
+async function cmdStatus(args: ParsedArgs, io: CliIo): Promise<number> {
+  return withSession(args, io, async (session, connection) => {
+    const [context, tools] = await Promise.all([readContext(session), session.listTools()])
+    const status = {
+      url: connection.url,
+      profile: connection.profile,
+      server: session.serverVersion() ?? null,
+      site: context?.site?.name ?? null,
+      siteEditorConnected: context?.editor.siteConnected ?? null,
+      contentWorkspaceConnected: context?.editor.contentConnected ?? null,
+      tools: tools.length,
+    }
+    if (booleanFlag(args, 'json')) {
+      printJson(io, status)
+      return EXIT.ok
+    }
+    const yesNo = (value: boolean | null) => (value === null ? 'unknown' : value ? 'connected' : 'not open')
+    io.stdout(
+      [
+        `Site:              ${status.site ?? '(unknown)'} — ${status.url}`,
+        `Profile:           ${status.profile ?? '(from flags/env)'}`,
+        `Site editor:       ${yesNo(status.siteEditorConnected)}`,
+        `Content workspace: ${yesNo(status.contentWorkspaceConnected)}`,
+        `Tools available:   ${status.tools}`,
+      ].join('\n') + '\n',
+    )
+    return EXIT.ok
+  })
+}
+
+async function cmdGuide(args: ParsedArgs, io: CliIo): Promise<number> {
+  return withSession(args, io, async (session) => {
+    io.stdout(`${session.instructions()}${CLI_GUIDE_NOTE}\n`)
+    return EXIT.ok
+  })
+}
+
+async function cmdTools(args: ParsedArgs, io: CliIo): Promise<number> {
+  return withSession(args, io, async (session) => {
+    const tools = await session.listTools()
+    const name = args.positionals[1]
+    if (name) {
+      const tool = tools.find((candidate) => candidate.name === name)
+      if (!tool) {
+        io.stderr(`Unknown tool "${name}". Run instatic tools to list them.\n`)
+        return EXIT.usage
+      }
+      if (booleanFlag(args, 'json')) printJson(io, tool)
+      else io.stdout(`${tool.name}\n\n${tool.description ?? ''}\n\nInput schema:\n${JSON.stringify(tool.inputSchema, null, 2)}\n`)
+      return EXIT.ok
+    }
+    if (booleanFlag(args, 'json')) {
+      printJson(io, tools.map((tool) => ({ name: tool.name, description: tool.description ?? '' })))
+      return EXIT.ok
+    }
+    const width = Math.max(...tools.map((tool) => tool.name.length))
+    for (const tool of [...tools].sort((a, b) => a.name.localeCompare(b.name))) {
+      const summary = (tool.description ?? '').split(/(?<=\.)\s/)[0] ?? ''
+      io.stdout(`${tool.name.padEnd(width)}  ${summary}\n`)
+    }
+    return EXIT.ok
+  })
+}
+
+async function cmdCall(args: ParsedArgs, io: CliIo): Promise<number> {
+  const name = args.positionals[1]
+  if (!name) throw new UsageError('Usage: instatic call <tool> [<json> | --input <file> | -]')
+  const input = await readToolInput(args, io)
+  return withSession(args, io, async (session) => emitToolResult(io, args, await session.callTool(name, input)))
+}
+
+async function cmdPublish(args: ParsedArgs, io: CliIo): Promise<number> {
+  return withSession(args, io, async (session) => emitToolResult(io, args, await session.callTool('site_publish', {})))
+}
+
+async function cmdUpload(args: ParsedArgs, io: CliIo): Promise<number> {
+  const file = args.positionals[1]
+  if (!file) throw new UsageError('Usage: instatic upload <file> [--alt <text>] [--name <filename>]')
+  const bytes = await readFile(file)
+  const input: Record<string, unknown> = {
+    filename: stringFlag(args, 'name') ?? basename(file),
+    data: bytes.toString('base64'),
+  }
+  const alt = stringFlag(args, 'alt')
+  if (alt !== undefined) input.altText = alt
+  return withSession(args, io, async (session) => emitToolResult(io, args, await session.callTool('media_upload', input)))
+}
+
+async function cmdWaitEditor(args: ParsedArgs, io: CliIo): Promise<number> {
+  const scope = stringFlag(args, 'scope') ?? 'site'
+  if (scope !== 'site' && scope !== 'content') throw new UsageError('--scope must be site or content.')
+  const timeoutRaw = stringFlag(args, 'timeout') ?? '120'
+  const timeoutSeconds = Number(timeoutRaw)
+  if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 0) throw new UsageError('--timeout must be a number of seconds.')
+  const sleep = io.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)))
+  const label = scope === 'site' ? 'Site editor' : 'Content workspace'
+
+  return withSession(args, io, async (session) => {
+    const deadline = Date.now() + timeoutSeconds * 1000
+    let announced = false
+    for (;;) {
+      const context = await readContext(session)
+      if (!context) {
+        io.stderr('This token cannot read the editor status (get_context is unavailable).\n')
+        return EXIT.server
+      }
+      const connected = scope === 'site' ? context.editor.siteConnected : context.editor.contentConnected
+      if (connected) {
+        io.stdout(`${label} connected.\n`)
+        return EXIT.ok
+      }
+      if (Date.now() >= deadline) {
+        io.stderr(`${label} did not connect within ${timeoutSeconds}s. Open it in a browser, signed in as the token's owner.\n`)
+        return EXIT.editorMissing
+      }
+      if (!announced) {
+        io.stderr(`Waiting for the ${label} to be opened in a browser…\n`)
+        announced = true
+      }
+      await sleep(2000)
+    }
+  })
+}
+
+async function cmdMcp(args: ParsedArgs, io: CliIo): Promise<number> {
+  const config = await readConfig(configPath(io.env))
+  const connection = resolveConnection(globalConnectionFlags(args), io.env, config)
+  await runStdioProxy(connection, { clientVersion: CLI_VERSION, fetch: io.fetch, log: io.stderr })
+  return EXIT.ok
+}
+
+const COMMANDS: Record<string, (args: ParsedArgs, io: CliIo) => Promise<number>> = {
+  login: cmdLogin,
+  logout: cmdLogout,
+  profiles: cmdProfiles,
+  status: cmdStatus,
+  guide: cmdGuide,
+  tools: cmdTools,
+  call: cmdCall,
+  publish: cmdPublish,
+  upload: cmdUpload,
+  'wait-editor': cmdWaitEditor,
+  mcp: cmdMcp,
+}
+
+const EXIT_FOR_FAILURE = {
+  auth: EXIT.auth,
+  unreachable: EXIT.unreachable,
+  server: EXIT.server,
+} as const
+
+export async function runCli(io: CliIo): Promise<number> {
+  let args: ParsedArgs
+  try {
+    args = parseArgs(io.argv)
+  } catch (err) {
+    io.stderr(`${(err as Error).message}\n`)
+    return EXIT.usage
+  }
+
+  if (booleanFlag(args, 'version')) {
+    io.stdout(`${CLI_VERSION}\n`)
+    return EXIT.ok
+  }
+  const command = args.positionals[0]
+  if (!command || booleanFlag(args, 'help') || command === 'help') {
+    io.stdout(`${HELP}\n`)
+    return EXIT.ok
+  }
+  const run = COMMANDS[command]
+  if (!run) {
+    io.stderr(`Unknown command "${command}". Run instatic --help.\n`)
+    return EXIT.usage
+  }
+
+  try {
+    return await run(args, io)
+  } catch (err) {
+    if (err instanceof UsageError) {
+      io.stderr(`${err.message}\n`)
+      return EXIT.usage
+    }
+    if (err instanceof ConnectionError) {
+      io.stderr(`${err.message}\n`)
+      return EXIT_FOR_FAILURE[err.kind]
+    }
+    io.stderr(`${err instanceof Error ? err.message : String(err)}\n`)
+    return EXIT.server
+  }
+}
diff --git a/packages/cli/src/config.ts b/packages/cli/src/config.ts
new file mode 100644
index 000000000..051e237a3
--- /dev/null
+++ b/packages/cli/src/config.ts
@@ -0,0 +1,132 @@
+/**
+ * Saved connection profiles.
+ *
+ * One JSON file (`$INSTATIC_CONFIG`, else `$XDG_CONFIG_HOME/instatic/config.json`,
+ * else `~/.config/instatic/config.json`) holds named profiles — one per site —
+ * and the current one. It stores personal access tokens, so it is written with
+ * owner-only permissions.
+ *
+ * Resolution for every command, highest priority first: `--url` / `--token`
+ * flags, then `INSTATIC_URL` / `INSTATIC_TOKEN`, then the selected profile
+ * (`--profile`, `INSTATIC_PROFILE`, or the saved current one).
+ */
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { Type, type Static } from '@sinclair/typebox'
+import { Value } from '@sinclair/typebox/value'
+import { UsageError } from './args'
+
+const ProfileSchema = Type.Object({
+  url: Type.String({ minLength: 1 }),
+  token: Type.String({ minLength: 1 }),
+})
+export type Profile = Static<typeof ProfileSchema>
+
+const ConfigFileSchema = Type.Object({
+  current: Type.Optional(Type.String()),
+  profiles: Type.Record(Type.String(), ProfileSchema),
+})
+export type ConfigFile = Static<typeof ConfigFileSchema>
+
+export type Env = Readonly<Record<string, string | undefined>>
+
+export const DEFAULT_PROFILE = 'default'
+const MCP_PATH = '/_instatic/mcp'
+
+export function configPath(env: Env): string {
+  if (env.INSTATIC_CONFIG) return env.INSTATIC_CONFIG
+  const base = env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  return join(base, 'instatic', 'config.json')
+}
+
+export async function readConfig(path: string): Promise<ConfigFile> {
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return { profiles: {} }
+    throw err
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (err) {
+    throw new Error(`Config file ${path} is not valid JSON. Fix or delete it.`, { cause: err })
+  }
+  if (!Value.Check(ConfigFileSchema, parsed)) {
+    throw new Error(`Config file ${path} has an unexpected shape. Fix or delete it.`)
+  }
+  return parsed
+}
+
+export async function writeConfig(path: string, config: ConfigFile): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+  await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
+  // `mode` only applies when the file is created; tighten an existing one too.
+  await chmod(path, 0o600)
+}
+
+/**
+ * Normalize what a user pastes — `https://site.com`, `site.com/`, or the full
+ * `https://site.com/_instatic/mcp` from the admin UI — to the site origin.
+ */
+export function normalizeSiteUrl(input: string): string {
+  const trimmed = input.trim()
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`
+  let url: URL
+  try {
+    url = new URL(withScheme)
+  } catch {
+    throw new UsageError(`Not a valid URL: ${input}`)
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new UsageError(`URL must be http(s): ${input}`)
+  }
+  let path = url.pathname.replace(/\/+$/, '')
+  if (path.endsWith(MCP_PATH)) path = path.slice(0, -MCP_PATH.length)
+  return `${url.origin}${path}`
+}
+
+export function mcpEndpoint(siteUrl: string): URL {
+  return new URL(`${siteUrl}${MCP_PATH}`)
+}
+
+/** True when a token would travel in clear text to a non-local host. */
+export function isInsecureRemote(siteUrl: string): boolean {
+  const url = new URL(siteUrl)
+  if (url.protocol === 'https:') return false
+  return !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)
+}
+
+export function selectedProfileName(flagProfile: string | undefined, env: Env, config: ConfigFile): string {
+  return flagProfile ?? env.INSTATIC_PROFILE ?? config.current ?? DEFAULT_PROFILE
+}
+
+export interface ResolvedConnection {
+  url: string
+  token: string
+  /** Profile the values came from, when any did. */
+  profile: string | null
+}
+
+export function resolveConnection(
+  flags: { url?: string; token?: string; profile?: string },
+  env: Env,
+  config: ConfigFile,
+): ResolvedConnection {
+  const name = selectedProfileName(flags.profile, env, config)
+  const saved = config.profiles[name]
+  if (flags.profile && !saved) {
+    throw new UsageError(`No saved profile "${flags.profile}". Run: instatic login --profile ${flags.profile} --url <site>`)
+  }
+  const url = flags.url ?? env.INSTATIC_URL ?? saved?.url
+  const token = flags.token ?? env.INSTATIC_TOKEN ?? saved?.token
+  if (!url || !token) {
+    throw new UsageError(
+      'Not logged in. Run: instatic login --url <site> (create a token in Instatic under AI → MCP), ' +
+        'or set INSTATIC_URL and INSTATIC_TOKEN.',
+    )
+  }
+  return { url: normalizeSiteUrl(url), token, profile: saved ? name : null }
+}
diff --git a/packages/cli/src/connection.ts b/packages/cli/src/connection.ts
new file mode 100644
index 000000000..1e825d655
--- /dev/null
+++ b/packages/cli/src/connection.ts
@@ -0,0 +1,233 @@
+/**
+ * One authenticated MCP session against an Instatic site.
+ *
+ * Instatic's endpoint is stateless (MCP 2026-07-28): every request is an
+ * independent authenticated POST, so a "session" is just a configured client.
+ * This module adds what a terminal or agent needs on top of the SDK:
+ *
+ *   - failures classified into auth / unreachable / server, so callers can
+ *     map them to exit codes and actionable messages;
+ *   - retries that are safe: discovery and reads retry on any network error,
+ *     but a tool call is re-sent only when the request provably never reached
+ *     the server (connection refused, DNS failure, gateway said upstream is
+ *     down) — a write must never be applied twice;
+ *   - a tool-call timeout above the server's own budget (up to 15 s waiting
+ *     for the editor tab plus 90 s for the editor to run the tool).
+ */
+import {
+  Client,
+  SdkHttpError,
+  StreamableHTTPClientTransport,
+  UnauthorizedError,
+  type FetchLike,
+  type Tool,
+} from '@modelcontextprotocol/client'
+import { mcpEndpoint, type ResolvedConnection } from './config'
+
+const PROTOCOL_VERSION = '2026-07-28'
+/** Above the server's 15 s workspace wait + 90 s per-call editor limit. */
+const TOOL_CALL_TIMEOUT_MS = 150_000
+const READ_TIMEOUT_MS = 30_000
+const RETRY_DELAYS_MS = [500, 1500]
+
+export type FailureKind = 'auth' | 'unreachable' | 'server'
+
+export class ConnectionError extends Error {
+  readonly kind: FailureKind
+
+  constructor(kind: FailureKind, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'ConnectionError'
+    this.kind = kind
+  }
+}
+
+/** Codes meaning the TCP connection was never established — nothing was sent. */
+const NEVER_SENT_CODES = new Set(['ECONNREFUSED', 'ConnectionRefused', 'ENOTFOUND', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT'])
+const NETWORK_CODES = new Set([
+  ...NEVER_SENT_CODES,
+  'ECONNRESET',
+  'ETIMEDOUT',
+  'EPIPE',
+  'UND_ERR_SOCKET',
+])
+const GATEWAY_STATUSES = new Set([502, 503, 504])
+
+/**
+ * The error plus everything it wraps. The SDK nests the underlying failure
+ * under `data.cause` (version-negotiation errors) as well as the standard
+ * `cause`.
+ */
+function errorChain(err: unknown): unknown[] {
+  const chain: unknown[] = []
+  let current: unknown = err
+  while (current && chain.length < 8 && !chain.includes(current)) {
+    chain.push(current)
+    const next = (current as { cause?: unknown }).cause
+      ?? ((current as { data?: { cause?: unknown } }).data?.cause)
+    current = next
+  }
+  return chain
+}
+
+function errorCodes(err: unknown): string[] {
+  return errorChain(err)
+    .map((link) => (link as { code?: unknown }).code)
+    .filter((code): code is string => typeof code === 'string')
+}
+
+function httpStatus(err: unknown): number | null {
+  for (const link of errorChain(err)) {
+    if (link instanceof SdkHttpError) return link.status
+  }
+  return null
+}
+
+function isNetworkFailure(err: unknown): boolean {
+  if (errorCodes(err).some((code) => NETWORK_CODES.has(code))) return true
+  // Node's undici surfaces a failed connection as a bare `TypeError: fetch failed`.
+  return errorChain(err).some(
+    (link) => link instanceof TypeError && /fetch failed|unable to connect/i.test(link.message),
+  )
+}
+
+/** Worth retrying for an idempotent request (discovery, reads). */
+function isTransient(err: unknown): boolean {
+  const status = httpStatus(err)
+  return isNetworkFailure(err) || (status !== null && GATEWAY_STATUSES.has(status))
+}
+
+function neverSent(err: unknown): boolean {
+  if (errorCodes(err).some((code) => NEVER_SENT_CODES.has(code))) return true
+  const status = httpStatus(err)
+  return status !== null && GATEWAY_STATUSES.has(status)
+}
+
+/** Turn any SDK / network failure into a `ConnectionError` with a next step. */
+export function classifyFailure(err: unknown, siteUrl: string): ConnectionError {
+  if (err instanceof ConnectionError) return err
+  const status = httpStatus(err)
+  if (err instanceof UnauthorizedError || status === 401 || status === 403) {
+    return new ConnectionError(
+      'auth',
+      `${siteUrl} rejected the access token. It may be expired or revoked: create a new one in Instatic under AI → MCP, then run instatic login.`,
+      { cause: err },
+    )
+  }
+  if ((status !== null && GATEWAY_STATUSES.has(status)) || isNetworkFailure(err)) {
+    return new ConnectionError(
+      'unreachable',
+      `Could not reach ${siteUrl}. Check the URL and that the server is running.`,
+      { cause: err },
+    )
+  }
+  const message = err instanceof Error ? err.message : String(err)
+  return new ConnectionError('server', `Request to ${siteUrl} failed: ${message}`, { cause: err })
+}
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+async function withRetry<T>(run: () => Promise<T>, retryable: (err: unknown) => boolean): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await run()
+    } catch (err) {
+      const delay = RETRY_DELAYS_MS[attempt]
+      if (delay === undefined || !retryable(err)) throw err
+      await sleep(delay)
+    }
+  }
+}
+
+export interface ToolCallResult {
+  isError: boolean
+  content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>
+}
+
+export interface SessionOptions {
+  clientVersion: string
+  /** Test seam: replaces the network for every request. */
+  fetch?: FetchLike
+}
+
+export class InstaticSession {
+  readonly siteUrl: string
+  private readonly client: Client
+
+  private constructor(siteUrl: string, client: Client) {
+    this.siteUrl = siteUrl
+    this.client = client
+  }
+
+  static async open(connection: ResolvedConnection, options: SessionOptions): Promise<InstaticSession> {
+    // A transport starts once, so every attempt builds a fresh client.
+    const attempt = async (): Promise<Client> => {
+      const client = new Client(
+        { name: 'instatic-cli', version: options.clientVersion },
+        { versionNegotiation: { mode: { pin: PROTOCOL_VERSION } } },
+      )
+      const transport = new StreamableHTTPClientTransport(mcpEndpoint(connection.url), {
+        requestInit: { headers: { Authorization: `Bearer ${connection.token}` } },
+        fetch: options.fetch,
+      })
+      try {
+        await client.connect(transport, { timeout: READ_TIMEOUT_MS })
+        return client
+      } catch (err) {
+        await client.close().catch(() => {})
+        throw err
+      }
+    }
+    try {
+      return new InstaticSession(connection.url, await withRetry(attempt, isTransient))
+    } catch (err) {
+      throw classifyFailure(err, connection.url)
+    }
+  }
+
+  /** The build rules the server advertises to every agent. */
+  instructions(): string {
+    return this.client.getInstructions() ?? ''
+  }
+
+  serverVersion(): { name: string; version: string } | undefined {
+    return this.client.getServerVersion()
+  }
+
+  async listTools(): Promise<Tool[]> {
+    try {
+      const { tools } = await withRetry(
+        () => this.client.listTools(undefined, { timeout: READ_TIMEOUT_MS }),
+        isTransient,
+      )
+      return tools
+    } catch (err) {
+      throw classifyFailure(err, this.siteUrl)
+    }
+  }
+
+  async callTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult> {
+    try {
+      const result = await withRetry(
+        () => this.client.callTool({ name, arguments: args }, { timeout: TOOL_CALL_TIMEOUT_MS }),
+        neverSent,
+      )
+      const content = Array.isArray(result.content) ? (result.content as ToolCallResult['content']) : []
+      return { isError: result.isError === true, content }
+    } catch (err) {
+      throw classifyFailure(err, this.siteUrl)
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.client.close().catch(() => {})
+  }
+}
+
+/** The text payload of a tool result, joined. */
+export function resultText(result: ToolCallResult): string {
+  return result.content
+    .filter((block) => block.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('\n')
+}
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
new file mode 100644
index 000000000..83a1413bc
--- /dev/null
+++ b/packages/cli/src/index.ts
@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * `instatic` executable: wires the real process into `runCli`.
+ */
+import { createInterface } from 'node:readline'
+import { runCli } from './cli'
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = []
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk))
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+/** Read one line from the terminal without echoing it. */
+function promptSecret(question: string): Promise<string> {
+  return new Promise((resolve) => {
+    process.stderr.write(question)
+    const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true })
+    // Swallow the echo of typed characters; readline still collects them.
+    ;(rl as unknown as { _writeToOutput: (text: string) => void })._writeToOutput = () => {}
+    rl.question('', (answer) => {
+      rl.close()
+      process.stderr.write('\n')
+      resolve(answer)
+    })
+  })
+}
+
+const code = await runCli({
+  argv: process.argv.slice(2),
+  env: process.env,
+  stdout: (text) => process.stdout.write(text),
+  stderr: (text) => process.stderr.write(text),
+  readStdin,
+  stdinIsTty: Boolean(process.stdin.isTTY),
+  promptSecret,
+})
+process.exitCode = code
diff --git a/packages/cli/src/stdioProxy.ts b/packages/cli/src/stdioProxy.ts
new file mode 100644
index 000000000..0b681240c
--- /dev/null
+++ b/packages/cli/src/stdioProxy.ts
@@ -0,0 +1,126 @@
+/**
+ * `instatic mcp` — a local stdio MCP server that forwards to an Instatic site.
+ *
+ * Desktop MCP clients (Claude Desktop, Cursor, …) launch local servers over
+ * stdio and cannot always attach an `Authorization` header to a remote URL.
+ * This proxy holds the token, advertises the site's own instructions and tool
+ * list unchanged, and forwards each `tools/call` with the same safe-retry
+ * rules as the CLI. A dropped connection is reopened on the next request
+ * instead of killing the stdio server, so the desktop client never sees the
+ * Instatic server "disconnect".
+ */
+import { Server, type CallToolResult } from '@modelcontextprotocol/server'
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'
+import type { FetchLike } from '@modelcontextprotocol/client'
+import type { ResolvedConnection } from './config'
+import { ConnectionError, InstaticSession } from './connection'
+
+export interface ProxyOptions {
+  clientVersion: string
+  fetch?: FetchLike
+  log: (text: string) => void
+}
+
+/** Opens the remote session lazily and reopens it after a connection failure. */
+class RemoteSession {
+  private current: Promise<InstaticSession> | null = null
+  private readonly connection: ResolvedConnection
+  private readonly options: ProxyOptions
+
+  constructor(connection: ResolvedConnection, options: ProxyOptions) {
+    this.connection = connection
+    this.options = options
+  }
+
+  get(): Promise<InstaticSession> {
+    if (!this.current) {
+      const opening = InstaticSession.open(this.connection, {
+        clientVersion: this.options.clientVersion,
+        fetch: this.options.fetch,
+      })
+      // A failed open must not be cached: the next request tries again.
+      opening.catch(() => {
+        if (this.current === opening) this.current = null
+      })
+      this.current = opening
+    }
+    return this.current
+  }
+
+  /** Drop the session after a transport failure so the next call reconnects. */
+  reset(): void {
+    const stale = this.current
+    this.current = null
+    void stale?.then((session) => session.close()).catch(() => {})
+  }
+
+  async close(): Promise<void> {
+    const session = await this.current?.catch(() => null)
+    await session?.close()
+  }
+}
+
+function errorResult(message: string): CallToolResult {
+  return { isError: true, content: [{ type: 'text', text: message }] }
+}
+
+/** Build the proxy server. Connects to the site first to learn its instructions. */
+export async function createProxyServer(
+  connection: ResolvedConnection,
+  options: ProxyOptions,
+): Promise<{ server: Server; close: () => Promise<void> }> {
+  const remote = new RemoteSession(connection, options)
+  const first = await remote.get()
+  const server = new Server(
+    { name: 'instatic', version: options.clientVersion },
+    { capabilities: { tools: {} }, instructions: first.instructions() },
+  )
+
+  server.setRequestHandler('tools/list', async () => {
+    try {
+      const session = await remote.get()
+      return { tools: await session.listTools() }
+    } catch (err) {
+      if (err instanceof ConnectionError && err.kind === 'unreachable') remote.reset()
+      throw err
+    }
+  })
+
+  server.setRequestHandler('tools/call', async (request): Promise<CallToolResult> => {
+    const { name, arguments: args } = request.params
+    try {
+      const session = await remote.get()
+      const result = await session.callTool(name, args ?? {})
+      return server.projectCallToolResult(
+        { isError: result.isError, content: result.content as CallToolResult['content'] },
+        undefined,
+      )
+    } catch (err) {
+      if (err instanceof ConnectionError) {
+        if (err.kind === 'unreachable') remote.reset()
+        options.log(`[instatic mcp] ${err.message}\n`)
+        return errorResult(err.message)
+      }
+      throw err
+    }
+  })
+
+  return { server, close: () => remote.close() }
+}
+
+export async function runStdioProxy(connection: ResolvedConnection, options: ProxyOptions): Promise<void> {
+  const { server, close } = await createProxyServer(connection, options)
+  const transport = new StdioServerTransport()
+  // The desktop client ends the session by closing our stdin; the transport
+  // does not report that on its own.
+  const closed = new Promise<void>((resolve) => {
+    transport.onclose = () => resolve()
+    process.stdin.once('end', () => resolve())
+    process.stdin.once('close', () => resolve())
+  })
+  await server.connect(transport)
+  options.log(`[instatic mcp] forwarding to ${connection.url}\n`)
+  await closed
+  await server.close()
+  await close()
+}
diff --git a/packages/cli/tsconfig.json b/packages/cli/tsconfig.json
new file mode 100644
index 000000000..cdfba7010
--- /dev/null
+++ b/packages/cli/tsconfig.json
@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "../../node_modules/.tmp/tsconfig.cli.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "module": "esnext",
+    "types": ["node", "bun"],
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"]
+}
diff --git a/scripts/build-cli.ts b/scripts/build-cli.ts
new file mode 100644
index 000000000..5ae6d8e1d
--- /dev/null
+++ b/scripts/build-cli.ts
@@ -0,0 +1,37 @@
+/**
+ * Bundle the `instatic` CLI (`packages/cli`) into one self-contained file for
+ * npm. Every dependency — the MCP client/server SDKs, TypeBox — is inlined, so
+ * `npx instatic` / `bunx instatic` install nothing but this file. Targets Node
+ * (>= 20); Bun runs the same output.
+ */
+import { chmod, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const cliDir = join(import.meta.dir, '..', 'packages', 'cli')
+const outdir = join(cliDir, 'dist')
+
+await rm(outdir, { recursive: true, force: true })
+
+const result = await Bun.build({
+  entrypoints: [join(cliDir, 'src', 'index.ts')],
+  outdir,
+  naming: 'instatic.js',
+  target: 'node',
+  format: 'esm',
+  minify: true,
+  sourcemap: 'none',
+})
+
+if (!result.success) {
+  for (const log of result.logs) console.error('[build-cli]', log)
+  process.exit(1)
+}
+
+const output = join(outdir, 'instatic.js')
+const text = await Bun.file(output).text()
+if (!text.startsWith('#!')) {
+  console.error('[build-cli] bundle lost its #!/usr/bin/env node line')
+  process.exit(1)
+}
+await chmod(output, 0o755)
+console.info(`[build-cli] wrote ${output} (${(text.length / 1024).toFixed(0)} KiB)`)
diff --git a/src/__tests__/architecture/ai-driver-isolation.test.ts b/src/__tests__/architecture/ai-driver-isolation.test.ts
index cfad28043..e1316f5f5 100644
--- a/src/__tests__/architecture/ai-driver-isolation.test.ts
+++ b/src/__tests__/architecture/ai-driver-isolation.test.ts
@@ -24,10 +24,12 @@
  *   - `@modelcontextprotocol/*`         — the official split v2 packages are
  *                                         allowed ONLY under `server/ai/mcp/`,
  *                                         where Instatic implements an MCP
- *                                         *server* (a real wire protocol — a
- *                                         legitimate SDK use). Still banned in
- *                                         the drivers and the browser, which
- *                                         must never speak MCP.
+ *                                         *server*, and `packages/cli/`, the
+ *                                         `instatic` CLI that is a client of
+ *                                         that server (a real wire protocol —
+ *                                         a legitimate SDK use). Still banned
+ *                                         in the drivers and the browser,
+ *                                         which must never speak MCP.
  */
 
 import { describe, it, expect } from 'bun:test'
@@ -35,7 +37,7 @@ import { readdirSync, readFileSync, statSync, existsSync } from 'fs'
 import { join, extname, relative } from 'path'
 
 const REPO_ROOT = join(import.meta.dir, '../../../')
-const SCAN_DIRS = ['src', 'server']
+const SCAN_DIRS = ['src', 'server', 'packages']
 
 interface PackageRule {
   /** Display name in error messages. */
@@ -77,9 +79,9 @@ const RULES: PackageRule[] = [
   {
     label: '@modelcontextprotocol/*',
     importRe: /from\s+['"]@modelcontextprotocol\/(?:server|client|core|node|sdk)(?:\/[^'"]*)?['"]|require\s*\(\s*['"]@modelcontextprotocol\/(?:server|client|core|node|sdk)(?:\/[^'"]*)?['"]\s*\)/,
-    // Allowed only inside the MCP server module — banned everywhere else.
+    // Allowed only inside the MCP server module and the CLI that talks to it.
     allowed: [],
-    allowedPrefixes: ['server/ai/mcp/'],
+    allowedPrefixes: ['server/ai/mcp/', 'packages/cli/'],
   },
   {
     label: 'zod',
diff --git a/tsconfig.json b/tsconfig.json
index d770cb20f..fdfcc69c0 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -3,7 +3,8 @@
   "references": [
     { "path": "./tsconfig.app.json" },
     { "path": "./tsconfig.node.json" },
-    { "path": "./tests/e2e" }
+    { "path": "./tests/e2e" },
+    { "path": "./packages/cli" }
   ],
   "compilerOptions": {
     "paths": {

From 9e3b0187f9e09793a41d1fcfb7930d057fee1bb5 Mon Sep 17 00:00:00 2001
From: Flying Web Solutions <flyingweb.ie@gmail.com>
Date: Tue, 3 Nov 2026 13:03:42 +0000
Subject: [PATCH 3/6] =?UTF-8?q?=F0=9F=90=9B=20fix(mcp):=20name=20the=20OAu?=
 =?UTF-8?q?th=20issuer,=20mark=20missing-editor=20errors,=20honor=20upload?=
 =?UTF-8?q?=20policy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- OAuth redirects (approve and deny) carry `iss` and the metadata
  advertises authorization_response_iss_parameter_supported (RFC 9207),
  so a client signed in to several sites can reject a mixed-up code.
- The "no workspace connected" tool error carries
  `_meta: { "instatic/error": "workspace_not_connected" }`, so clients can
  tell "open the editor, then retry" from other errors without matching
  message text. The retry path's fallback returns the same result.
- media_upload accepts the installation's upload policy (Settings →
  Uploads) instead of a hardcoded image list, matching the Media workspace.
- handleMcpHttp gains a workspaceWaitMs test seam.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/features/mcp-connectors.md               | 10 ++--
 server/ai/mcp/handlers/oauthAuthorization.ts  |  5 ++
 server/ai/mcp/oauth/handler.test.ts           |  1 +
 server/ai/mcp/oauth/handler.ts                |  1 +
 server/ai/mcp/server.test.ts                  |  3 +-
 server/ai/mcp/server.ts                       | 36 ++++++++++---
 server/ai/mcp/tools/uploadMediaTool.test.ts   | 38 +++++++++----
 server/ai/mcp/tools/uploadMediaTool.ts        | 54 +++++++++----------
 server/ai/mcp/transports/http.ts              |  3 ++
 .../ai/mcpOAuthAuthorizationHandler.test.ts   |  2 +
 10 files changed, 105 insertions(+), 48 deletions(-)

diff --git a/docs/features/mcp-connectors.md b/docs/features/mcp-connectors.md
index 5319d0bbb..3f798f1c6 100644
--- a/docs/features/mcp-connectors.md
+++ b/docs/features/mcp-connectors.md
@@ -12,7 +12,7 @@ The UI exposes two credential lifecycles instead of a cosmetic local/remote swit
 
 | Mode | Intended client | Authentication | Lifecycle |
 |---|---|---|---|
-| Hosted OAuth | Claude custom connectors and other remote MCP clients | OAuth authorization code with S256 PKCE | The client discovers the authorization server, dynamically registers, and sends the user to Instatic for consent. Access tokens last up to one hour; refresh tokens rotate; the grant expires after 90 days. |
+| Hosted OAuth | Claude custom connectors, the [`instatic` CLI](cli.md), and other remote MCP clients | OAuth authorization code with S256 PKCE | The client discovers the authorization server, dynamically registers, and sends the user to Instatic for consent. Access tokens last up to one hour; refresh tokens rotate; the grant expires after 90 days. |
 | Personal access token | Claude Code, Codex, Cursor, local bridges, and clients that accept an explicit header | `Authorization: Bearer imcp_pat_…` | Created after step-up authentication, shown once, scoped to selected capabilities, configurable expiry, independently revocable. |
 
 Both modes resolve to the same persistent connection grant and the same `toolAllowedForCapabilities` gate. OAuth does not create a wider tool path.
@@ -59,6 +59,8 @@ Instatic implements the MCP authorization-server surface directly:
 | `/admin/ai/oauth/authorize` | Signed-in consent screen. |
 | `/_instatic/oauth/token` | Form-encoded authorization-code and refresh-token exchange. |
 
+Every redirect back to the client — approval and denial alike — carries `iss` (RFC 9207), and the authorization-server metadata advertises `authorization_response_iss_parameter_supported: true`. A client signed in to several sites uses it to reject a code that came from a different authorization server than the one it started with (the mix-up attack).
+
 The issuer, the `resource` value, and every URL in these documents come from the configured public origin (`PUBLIC_ORIGIN`, auto-detected from `RENDER_EXTERNAL_URL` / `RAILWAY_PUBLIC_DOMAIN` on Render and Railway), never from the inbound `Host` header. Remote OAuth connectors therefore require `PUBLIC_ORIGIN`. Without it, both discovery endpoints answer `503` with `{ "error": "MCP OAuth needs PUBLIC_ORIGIN to be configured for this deployment." }`, the token endpoint answers `503` with `temporarily_unavailable`, the `401` challenge on `/_instatic/mcp` carries `scope="mcp"` but no `resource_metadata`, and OAuth access tokens do not authenticate. Personal access tokens keep working. Requests addressed to a loopback host (`localhost`, `127.0.0.1`, `::1`) are exempt and use their own origin so local development keeps working; the server warns at boot when no public origin is configured.
 
 The authorization sequence is:
@@ -154,7 +156,7 @@ executeAiTool(...) / live editor bridge
 | `server.ts` / `registry.ts` | Low-level SDK server, TypeBox input schemas, catalog deduplication, and capability filtering. |
 | `editorBridge.ts` | Per-user, per-scope live workspace bridge. Each tab sends a stable `tabId` and keeps its **claim** across reconnects: calls route to the most recently opened tab, a tab reconnecting after an idle recycle never steals the workspace back, superseded tabs stay connected (their in-flight calls finish) and take over when the active tab closes. `waitForEditorWorkspace` lets a call wait for a tab to (re)connect. Tool requests are delivered **serially** (the next is pushed only once the previous settles, matching the editor's one-at-a-time execution), so each call's 90s timeout measures the editor's actual work, not time queued behind slower calls. The stream carries an **idle lease** (120s, re-armed by every relayed tool request and never expiring while a call is pending) so an active batch is never cut mid-flight; only quiet streams recycle. The workspace's reconnect loop (`useMcpWorkspaceBridge`) reopens a recycled healthy stream immediately off the stream-end network event — deliberately timer-free, because hidden webviews (backgrounded browser tabs) clamp timers to minutes while network events still fire — and a tab becoming visible short-circuits any pending retry delay. |
 | `tools/publishTool.ts` | Explicit canonical full-site publish with MCP audit metadata. |
-| `tools/uploadMediaTool.ts` | Server-resolved image upload (`media_upload`) — inline base64 or SSRF-guarded `sourceUrl` download, through the shared media pipeline. |
+| `tools/uploadMediaTool.ts` | Server-resolved media upload (`media_upload`), under the installation's upload policy — inline base64 or SSRF-guarded `sourceUrl` download, through the shared media pipeline. |
 
 ## Tool execution model
 
@@ -162,11 +164,11 @@ MCP exposes the full deduplicated tool catalog, filtered by the connection's cap
 
 Server-resolved tools work without an editor open. They include content reads, `get_context`, `site_list_documents`, `site_read_styles`, `site_list_breakpoints`, `media_upload`, and explicit `site_publish`. Publishing requires `ai.tools.write` plus `pages.publish`, runs the canonical full-site pipeline, swaps the static slot atomically, and records the connection id in the publish audit event.
 
-`media_upload` is the one server-resolved write that mutates outside the live editor draft: it adds an image to the Media library through the same `acceptUploadedMedia` core the HTTP route uses (magic-byte sniffing, SVG sanitisation, storage dispatch, responsive variants). Bytes arrive inline (base64) or via an https `sourceUrl` the host downloads under the plugin network layer's SSRF blocklist — https-only, DNS-resolved, per-redirect-hop re-validation, size-capped. It requires `ai.tools.write` plus `media.write`.
+`media_upload` is the one server-resolved write that mutates outside the live editor draft: it adds a file to the Media library through the same `acceptUploadedMedia` core the HTTP route uses (magic-byte sniffing, SVG sanitisation, storage dispatch, responsive variants). It accepts exactly the types the installation's upload policy allows (**Settings → Uploads**, see [media](media.md) → "Accepted file types"), so documents, video, and fonts work wherever the Media workspace accepts them. Bytes arrive inline (base64) or via an https `sourceUrl` the host downloads under the plugin network layer's SSRF blocklist — https-only, DNS-resolved, per-redirect-hop re-validation, size-capped. It requires `ai.tools.write` plus `media.write`.
 
 Browser tools run against the connection owner's live workspace. Site structure, HTML/CSS, page lifecycle, design-token, content mutation, code-asset, and live-DOM tools route to the matching open Site or Content workspace. `tools/list` states that requirement in each browser tool's description, so a client learns the precondition when it picks the tool rather than from a failed call.
 
-An open workspace's stream has routine gaps (idle recycle, reconnect after a network blip, server restart), so a browser tool **waits up to 15 seconds** for the workspace to connect before failing with a scope-specific "ask the user to open it" error; headless tools remain available meanwhile. Interrupted calls are reported by what the agent can rely on (`BrowserToolInterruptedError.delivered` in `server/ai/runtime/transport.ts`):
+An open workspace's stream has routine gaps (idle recycle, reconnect after a network blip, server restart), so a browser tool **waits up to 15 seconds** for the workspace to connect before failing with a scope-specific "ask the user to open it" error; headless tools remain available meanwhile. That error result carries `_meta: { "instatic/error": "workspace_not_connected" }` (`WORKSPACE_NOT_CONNECTED_META` in `server.ts`), so a client can tell "open the editor, then retry" from other tool errors without matching message text. Interrupted calls are reported by what the agent can rely on (`BrowserToolInterruptedError.delivered` in `server/ai/runtime/transport.ts`):
 
 | Situation | Behaviour |
 |---|---|
diff --git a/server/ai/mcp/handlers/oauthAuthorization.ts b/server/ai/mcp/handlers/oauthAuthorization.ts
index da43df31c..db1be2be1 100644
--- a/server/ai/mcp/handlers/oauthAuthorization.ts
+++ b/server/ai/mcp/handlers/oauthAuthorization.ts
@@ -12,6 +12,7 @@ import { createOAuthAuthorizationGrant, findOAuthClient } from '../oauth/store'
 import { OAUTH_GRANT_TTL_DAYS } from '../connectors/store'
 import {
   isValidPkceChallenge,
+  mcpIssuer,
   mcpIssuerUnavailableResponse,
   mcpResource,
   normalizeMcpScope,
@@ -65,6 +66,7 @@ async function handleDecision(req: Request, db: DbClient): Promise<Response> {
         error: 'access_denied',
         error_description: 'The resource owner denied the request.',
         state: body.request.state,
+        iss: mcpIssuer(req) ?? undefined,
       }),
     })
   }
@@ -111,6 +113,9 @@ async function handleDecision(req: Request, db: DbClient): Promise<Response> {
       redirectUrl: oauthRedirect(resolved.request.redirectUri, {
         code,
         state: resolved.request.state,
+        // RFC 9207: name the issuer so a client signed in to several sites
+        // can tell which one answered (authorization-server mix-up defence).
+        iss: mcpIssuer(req) ?? undefined,
       }),
     })
   } catch (err) {
diff --git a/server/ai/mcp/oauth/handler.test.ts b/server/ai/mcp/oauth/handler.test.ts
index e1a505dbc..e4801ef0c 100644
--- a/server/ai/mcp/oauth/handler.test.ts
+++ b/server/ai/mcp/oauth/handler.test.ts
@@ -87,6 +87,7 @@ describe('MCP OAuth protocol endpoints', () => {
     expect(serverBody.registration_endpoint).toBe('https://cms.example.com/_instatic/oauth/register')
     expect(serverBody.code_challenge_methods_supported).toEqual(['S256'])
     expect(serverBody.token_endpoint_auth_methods_supported).toEqual(['none'])
+    expect(serverBody.authorization_response_iss_parameter_supported).toBe(true)
   })
 
   it('dynamically registers a public Claude client', async () => {
diff --git a/server/ai/mcp/oauth/handler.ts b/server/ai/mcp/oauth/handler.ts
index 671521dd3..8f2d99e57 100644
--- a/server/ai/mcp/oauth/handler.ts
+++ b/server/ai/mcp/oauth/handler.ts
@@ -84,6 +84,7 @@ function authorizationServerMetadata(req: Request): Response {
     code_challenge_methods_supported: ['S256'],
     token_endpoint_auth_methods_supported: ['none'],
     scopes_supported: [...MCP_OAUTH_SUPPORTED_SCOPES],
+    authorization_response_iss_parameter_supported: true,
   })
 }
 
diff --git a/server/ai/mcp/server.test.ts b/server/ai/mcp/server.test.ts
index 03d319cf7..60de0286a 100644
--- a/server/ai/mcp/server.test.ts
+++ b/server/ai/mcp/server.test.ts
@@ -7,7 +7,7 @@ import { runMigrations } from '../../db/runMigrations'
 import type { DbClient } from '../../db/client'
 import { createDataRow } from '../../repositories/data'
 import { resolveBridgeToolResult } from '../runtime'
-import { buildMcpServer } from './server'
+import { buildMcpServer, WORKSPACE_NOT_CONNECTED_META } from './server'
 import { createEditorBridgeStream } from './editorBridge'
 import { MAIN_SCOPE } from '../../branches/scope'
 
@@ -102,6 +102,7 @@ describe('mcp server', () => {
     expect(result.isError).toBe(true)
     const text = (result.content as Array<{ type: string; text: string }>)[0].text
     expect(text).toContain('Site editor')
+    expect(result._meta).toMatchObject(WORKSPACE_NOT_CONNECTED_META)
     await client.close()
   })
 
diff --git a/server/ai/mcp/server.ts b/server/ai/mcp/server.ts
index 16fc3dda0..ecd89caa8 100644
--- a/server/ai/mcp/server.ts
+++ b/server/ai/mcp/server.ts
@@ -90,6 +90,32 @@ function interruptionMessage(
   return `The ${label} tab disconnected while "${toolName}" was running, so the result is unknown: the edit may or may not have been applied. ${STATE_CHECK_HINT[scope]}`
 }
 
+/**
+ * `_meta` marker on the "no workspace connected" result, so a client can tell
+ * "open the editor, then retry" apart from every other tool error without
+ * matching message text. The instatic CLI maps it to its own exit code.
+ */
+export const WORKSPACE_NOT_CONNECTED_META = { 'instatic/error': 'workspace_not_connected' } as const
+
+function workspaceNotConnected(scope: EditorBridgeScope): CallToolResult {
+  return {
+    isError: true,
+    content: [{ type: 'text', text: NO_WORKSPACE_MESSAGE[scope] }],
+    _meta: { ...WORKSPACE_NOT_CONNECTED_META },
+  }
+}
+
+/** The editor tab closed before the call reached it and no other tab took over. */
+class WorkspaceNotConnectedError extends Error {
+  readonly scope: EditorBridgeScope
+
+  constructor(scope: EditorBridgeScope, options?: { cause?: unknown }) {
+    super(NO_WORKSPACE_MESSAGE[scope], options)
+    this.name = 'WorkspaceNotConnectedError'
+    this.scope = scope
+  }
+}
+
 function isUndeliveredClosure(err: unknown): boolean {
   return err instanceof BrowserToolInterruptedError && !err.delivered && err.reason === 'closed'
 }
@@ -212,12 +238,7 @@ export function buildMcpServer(ctx: McpServerContext): Server {
       const connect = () => waitForEditorWorkspace(ctx.userId, scope, { timeoutMs: waitMs, signal })
 
       const initial = await connect()
-      if (!initial) {
-        return project({
-          isError: true,
-          content: [{ type: 'text', text: NO_WORKSPACE_MESSAGE[scope] }],
-        })
-      }
+      if (!initial) return project(workspaceNotConnected(scope))
 
       const run = async (
         workspace: EditorWorkspace,
@@ -246,7 +267,7 @@ export function buildMcpServer(ctx: McpServerContext): Server {
             // editor never saw it: retry once on whichever tab is live now.
             if (!isUndeliveredClosure(err)) throw err
             const next = await connect()
-            if (!next) throw new Error(NO_WORKSPACE_MESSAGE[scope], { cause: err })
+            if (!next) throw new WorkspaceNotConnectedError(scope, { cause: err })
             return run(next, toolName, input)
           }
         },
@@ -274,6 +295,7 @@ export function buildMcpServer(ctx: McpServerContext): Server {
         snapshot: null,
       })
     } catch (err) {
+      if (err instanceof WorkspaceNotConnectedError) return project(workspaceNotConnected(err.scope))
       // Browser bridge rejection is terminal for a chat turn, but MCP has no
       // surrounding provider loop to terminate. Translate the same transport
       // failure into the protocol's normal tool-error result instead of
diff --git a/server/ai/mcp/tools/uploadMediaTool.test.ts b/server/ai/mcp/tools/uploadMediaTool.test.ts
index c066e2686..cccfbf88c 100644
--- a/server/ai/mcp/tools/uploadMediaTool.test.ts
+++ b/server/ai/mcp/tools/uploadMediaTool.test.ts
@@ -1,13 +1,23 @@
-import { describe, expect, it, spyOn } from 'bun:test'
+import { beforeAll, describe, expect, it, spyOn } from 'bun:test'
 import { uploadMediaMcpTool } from './uploadMediaTool'
 import type { ToolContext } from '../../runtime/types'
+import type { DbClient } from '../../../db/client'
+import { createSqliteClient } from '../../../db/sqlite'
+import { sqliteMigrations } from '../../../db/migrations-sqlite'
+import { runMigrations } from '../../../db/runMigrations'
+import { setAllowedUploadMimes } from '../../../repositories/mediaUploadPolicy'
 
 // The handler validates input, the source selector, and the SSRF guard BEFORE
-// it ever touches `ctx.db` or the storage layer, so these paths need no real
-// db/network/DNS. IP-literal hosts short-circuit DNS resolution, letting us
-// exercise the blocklist deterministically.
+// it touches the storage layer, so these paths need no network/DNS: the db is
+// only read for the upload policy. IP-literal hosts short-circuit DNS
+// resolution, letting us exercise the blocklist deterministically.
+let db: DbClient
+beforeAll(async () => {
+  db = createSqliteClient(':memory:')
+  await runMigrations(db, sqliteMigrations)
+})
+
 const baseCtx = {
-  db: {} as never,
   userId: 'user-1',
   capabilities: [],
   scope: 'content' as const,
@@ -19,7 +29,7 @@ function upload(
   input: Record<string, unknown>,
   signal = new AbortController().signal,
 ): Promise<unknown> {
-  const ctx: ToolContext = { ...baseCtx, signal }
+  const ctx: ToolContext = { ...baseCtx, db, signal }
   return uploadMediaMcpTool.handler!(input, ctx)
 }
 
@@ -45,10 +55,20 @@ describe('media_upload', () => {
     }
   })
 
-  it('rejects inline bytes that are not a supported image', async () => {
+  it('rejects inline bytes that are not a supported file type', async () => {
     // "AAAA" decodes to 3 zero bytes — no magic-byte signature matches, so the
-    // shared upload core rejects it before any storage/db work.
-    await expect(upload({ filename: 'x.png', data: 'AAAA' })).rejects.toThrow(/JPEG|PNG|image/i)
+    // shared upload core rejects it before any storage work.
+    await expect(upload({ filename: 'x.png', data: 'AAAA' })).rejects.toThrow(/can be uploaded/i)
+  })
+
+  it('follows the site upload policy instead of a fixed image list', async () => {
+    const pdf = Buffer.from('%PDF-1.7\n%\xE2\xE3\xCF\xD3\n1 0 obj\n<<>>\nendobj\n', 'latin1').toString('base64')
+    await setAllowedUploadMimes(db, ['image/png'], null)
+    try {
+      await expect(upload({ filename: 'spec.pdf', data: pdf })).rejects.toThrow(/Only PNG/)
+    } finally {
+      await setAllowedUploadMimes(db, ['image/png', 'application/pdf'], null)
+    }
   })
 
   it('rejects malformed base64 instead of silently decoding it', async () => {
diff --git a/server/ai/mcp/tools/uploadMediaTool.ts b/server/ai/mcp/tools/uploadMediaTool.ts
index af06cffa0..25c77823f 100644
--- a/server/ai/mcp/tools/uploadMediaTool.ts
+++ b/server/ai/mcp/tools/uploadMediaTool.ts
@@ -2,12 +2,14 @@
  * Media upload tool for MCP connectors.
  *
  * The rest of the MCP surface can *list* and *assign* existing media but never
- * create it — an external agent building a page had no way to get an image into
- * the library. This server-side tool closes that gap: it accepts image bytes
+ * create it — an external agent building a page had no way to get a file into
+ * the library. This server-side tool closes that gap: it accepts file bytes
  * either inline (base64) or by an https `sourceUrl` the host downloads, then
  * runs them through the exact same `acceptUploadedMedia` core the HTTP media
  * route uses (magic-byte MIME sniffing, SVG sanitisation, storage dispatch,
- * responsive variants). No new byte-handling path is introduced.
+ * responsive variants). No new byte-handling path is introduced, and the
+ * accepted file types are the installation's upload policy (Settings →
+ * Uploads), exactly as for an upload from the Media workspace.
  *
  * The `sourceUrl` branch is the sharp edge: letting the server fetch an
  * arbitrary URL is a classic SSRF vector (`http://169.254.169.254/…` cloud
@@ -19,12 +21,10 @@
 import { Type } from '@core/utils/typeboxHelpers'
 import type { Static } from '@core/utils/typeboxHelpers'
 import type { AiTool, ToolContext } from '../../runtime/types'
-import {
-  IMAGE_MIMES,
-  MAX_MEDIA_BYTES,
-  acceptUploadedMedia,
-} from '../../../handlers/cms/mediaUpload'
+import { describeAllowedMediaTypes } from '@core/media-types'
+import { MAX_MEDIA_BYTES, acceptUploadedMedia } from '../../../handlers/cms/mediaUpload'
 import { updateMediaAssetMetadata } from '../../../repositories/media'
+import { getAllowedUploadMimes } from '../../../repositories/mediaUploadPolicy'
 import { downloadRemoteMedia } from '../../../media/remoteDownload'
 
 const MAX_FILENAME_CHARS = 255
@@ -32,7 +32,7 @@ const MAX_SOURCE_URL_CHARS = 2_048
 const MAX_ALT_TEXT_CHARS = 4_096
 const MAX_DATA_URI_PREFIX_CHARS = 256
 const MAX_BASE64_CHARS = 4 * Math.ceil(MAX_MEDIA_BYTES / 3)
-const MAX_INLINE_IMAGE_DATA_CHARS = MAX_BASE64_CHARS + MAX_DATA_URI_PREFIX_CHARS
+const MAX_INLINE_DATA_CHARS = MAX_BASE64_CHARS + MAX_DATA_URI_PREFIX_CHARS
 const CANONICAL_BASE64 =
   /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
 
@@ -46,22 +46,22 @@ const UploadMediaInput = Type.Object(
     }),
     data: Type.Optional(
       Type.String({
-        maxLength: MAX_INLINE_IMAGE_DATA_CHARS,
+        maxLength: MAX_INLINE_DATA_CHARS,
         description:
-          'Base64-encoded image bytes (a bare `data:` URI prefix is also accepted). Provide EITHER `data` OR `sourceUrl`, not both.',
+          'Base64-encoded file bytes (a bare `data:` URI prefix is also accepted). Provide EITHER `data` OR `sourceUrl`, not both.',
       }),
     ),
     sourceUrl: Type.Optional(
       Type.String({
         maxLength: MAX_SOURCE_URL_CHARS,
         description:
-          'https URL the server downloads the image from (SSRF-guarded: private/loopback/link-local hosts are refused). Provide EITHER `data` OR `sourceUrl`, not both.',
+          'https URL the server downloads the file from (SSRF-guarded: private/loopback/link-local hosts are refused). Provide EITHER `data` OR `sourceUrl`, not both.',
       }),
     ),
     altText: Type.Optional(
       Type.String({
         maxLength: MAX_ALT_TEXT_CHARS,
-        description: 'Accessible alt text stored on the media asset.',
+        description: 'Accessible alt text stored on the media asset (images).',
       }),
     ),
   },
@@ -75,29 +75,29 @@ function inlineBase64Payload(data: string): string {
 
   const comma = data.indexOf(',')
   if (comma < 0 || comma + 1 > MAX_DATA_URI_PREFIX_CHARS) {
-    throw new Error('Inline image data URI is invalid.')
+    throw new Error('Inline data URI is invalid.')
   }
   const prefix = data.slice(0, comma + 1)
   if (!/^data:[^,]*;base64,$/i.test(prefix)) {
-    throw new Error('Inline image data URI must use base64 encoding.')
+    throw new Error('Inline data URI must use base64 encoding.')
   }
   return data.slice(comma + 1)
 }
 
 /** Decode canonical base64 only, rejecting oversized input before allocating bytes. */
-function decodeInlineImage(data: string): Uint8Array<ArrayBuffer> {
-  if (data.length > MAX_INLINE_IMAGE_DATA_CHARS) {
-    throw new Error('Inline image data exceeds the 50 MB hard limit.')
+function decodeInlineData(data: string): Uint8Array<ArrayBuffer> {
+  if (data.length > MAX_INLINE_DATA_CHARS) {
+    throw new Error('Inline data exceeds the 50 MB hard limit.')
   }
   const base64 = inlineBase64Payload(data)
   if (base64.length % 4 !== 0 || !CANONICAL_BASE64.test(base64)) {
-    throw new Error('Inline image data is not valid base64.')
+    throw new Error('Inline data is not valid base64.')
   }
 
   const padding = base64.endsWith('==') ? 2 : base64.endsWith('=') ? 1 : 0
   const decodedBytes = (base64.length / 4) * 3 - padding
   if (decodedBytes > MAX_MEDIA_BYTES) {
-    throw new Error('Inline image data exceeds the 50 MB hard limit.')
+    throw new Error('Inline data exceeds the 50 MB hard limit.')
   }
 
   const buf = Buffer.from(base64, 'base64')
@@ -109,7 +109,7 @@ function decodeInlineImage(data: string): Uint8Array<ArrayBuffer> {
 export const uploadMediaMcpTool: AiTool = {
   name: 'media_upload',
   description:
-    'Upload a new image into the Media library and return its id + publicPath so you can reference or assign it. Provide the bytes as base64 in `data`, OR an https `sourceUrl` the server downloads. Accepts JPEG, PNG, GIF, WebP, and SVG (SVG is sanitised); the file type is sniffed from the bytes, not the filename. Requires the connector to have media.write.',
+    'Upload a new file (image, document, video, audio, font, …) into the Media library and return its id + publicPath so you can reference or assign it. Provide the bytes as base64 in `data`, OR an https `sourceUrl` the server downloads. Accepted types follow the site\'s upload settings (Settings → Uploads; by default images, MP4/WebM video, web fonts, PDF and office documents; SVG is sanitised); the type is sniffed from the bytes, not the filename. Requires the connector to have media.write.',
   scope: 'content',
   execution: 'server',
   mutates: true,
@@ -125,27 +125,27 @@ export const uploadMediaMcpTool: AiTool = {
 
     ctx.signal.throwIfAborted()
     const bytes = hasData
-      ? decodeInlineImage(args.data!)
+      ? decodeInlineData(args.data!)
       : await downloadRemoteMedia(args.sourceUrl!, {
           signal: ctx.signal,
           maxBytes: MAX_MEDIA_BYTES,
           label: 'MCP media_upload',
         })
     if (bytes.length === 0) {
-      throw new Error('Decoded image is empty.')
+      throw new Error('Decoded file is empty.')
     }
 
     const file = new File([bytes], args.filename)
     ctx.signal.throwIfAborted()
+    const allowedMimes = await getAllowedUploadMimes(ctx.db)
     const result = await acceptUploadedMedia(ctx.db, {
       file,
       maxBytes: MAX_MEDIA_BYTES,
-      allowedMimes: IMAGE_MIMES,
+      allowedMimes,
       role: 'original',
       uploadedByUserId: ctx.userId,
-      oversizedMessage: 'Image exceeds the 50 MB hard limit',
-      unsupportedMessage:
-        'Only JPEG, PNG, GIF, WebP, and SVG images can be uploaded through this tool',
+      oversizedMessage: 'File exceeds the 50 MB hard limit',
+      unsupportedMessage: describeAllowedMediaTypes(allowedMimes, { settingsHint: true }),
     })
     // `acceptUploadedMedia` returns a ready-to-send error Response on any policy
     // failure. MCP has no HTTP surface, so surface the envelope message as a
diff --git a/server/ai/mcp/transports/http.ts b/server/ai/mcp/transports/http.ts
index d2c72aaef..26519212f 100644
--- a/server/ai/mcp/transports/http.ts
+++ b/server/ai/mcp/transports/http.ts
@@ -33,6 +33,8 @@ interface McpHttpOptions {
   uploadsDir?: string
   /** Test seam; production uses the hard endpoint-wide limit above. */
   maxRequestBytes?: number
+  /** Test seam; production waits the server default for an editor tab. */
+  workspaceWaitMs?: number
 }
 
 function payloadTooLargeResponse(maxBytes: number): Response {
@@ -74,6 +76,7 @@ export async function handleMcpHttp(
       connectorId: auth.connectorId,
       capabilities: auth.capabilities,
       uploadsDir: options.uploadsDir,
+      ...(options.workspaceWaitMs !== undefined ? { workspaceWaitMs: options.workspaceWaitMs } : {}),
     }),
     {
       legacy: 'stateless',
diff --git a/src/__tests__/ai/mcpOAuthAuthorizationHandler.test.ts b/src/__tests__/ai/mcpOAuthAuthorizationHandler.test.ts
index cf4eb379a..5f70cc998 100644
--- a/src/__tests__/ai/mcpOAuthAuthorizationHandler.test.ts
+++ b/src/__tests__/ai/mcpOAuthAuthorizationHandler.test.ts
@@ -78,6 +78,7 @@ describe('MCP OAuth authorization consent handler', () => {
     expect(`${redirect.origin}${redirect.pathname}`).toBe(CALLBACK)
     expect(redirect.searchParams.get('code')).toMatch(/^imcp_ac_/)
     expect(redirect.searchParams.get('state')).toBe('client-state')
+    expect(redirect.searchParams.get('iss')).toBe(new URL(request.resource).origin)
 
     const overview = await readJson<McpConnectionOverview>(await harness.ai(CONNECTIONS, { cookie }))
     expect(overview.connections).toHaveLength(1)
@@ -103,6 +104,7 @@ describe('MCP OAuth authorization consent handler', () => {
     expect(`${redirect.origin}${redirect.pathname}`).toBe(CALLBACK)
     expect(redirect.searchParams.get('error')).toBe('access_denied')
     expect(redirect.searchParams.get('state')).toBe('client-state')
+    expect(redirect.searchParams.get('iss')).toBe(new URL(request.resource).origin)
 
     const overview = await readJson<McpConnectionOverview>(await harness.ai(CONNECTIONS, { cookie }))
     expect(overview.connections).toHaveLength(0)

From c694d0ed7d042906ac8de24152ba5ab848203787 Mon Sep 17 00:00:00 2001
From: Flying Web Solutions <flyingweb.ie@gmail.com>
Date: Tue, 3 Nov 2026 13:03:42 +0000
Subject: [PATCH 4/6] =?UTF-8?q?=E2=9C=A8=20feat(cli):=20browser=20sign-in,?=
 =?UTF-8?q?=20batch=20calls,=20and=20editor-aware=20exit=20codes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- `instatic login --url <site>` signs in through the browser (OAuth 2.1 +
  PKCE, loopback callback, dynamic client registration, constant-time
  state check, RFC 9207 iss check, resource taken from the site's own
  metadata). `--with-token` / `--token` keep personal access tokens;
  `--no-browser` and `--port` cover SSH.
- OAuth profiles refresh themselves. Rotated refresh tokens must never be
  reused, so the profile is read from disk per request and refreshes run
  only under a cross-process config lock after re-reading it; every config
  write is locked and atomic. One renew-and-resend after a 401.
- A profile's credentials are never sent to a different --url.
- `instatic batch` runs many tool calls over one connection (JSON array or
  NDJSON), one JSON line per result, stop-on-failure or --keep-going.
- Exit code 5 when a call needs the editor and none is open; per-command
  --help; `call --timeout`; `tools --json --schemas`.
- README and --help state the CLI is unofficial; README lists all tools.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/features/cli.md            |  78 +++++--
 packages/cli/README.md          |  62 ++++--
 packages/cli/package.json       |   2 +-
 packages/cli/src/args.ts        |   2 +-
 packages/cli/src/cli.test.ts    | 178 ++++++++++++++-
 packages/cli/src/cli.ts         | 379 ++++++++++++++++++++++++++------
 packages/cli/src/config.ts      | 125 +++++++++--
 packages/cli/src/connection.ts  |  99 ++++++---
 packages/cli/src/credentials.ts | 190 ++++++++++++++++
 packages/cli/src/errors.ts      |  12 +
 packages/cli/src/index.ts       |  29 +++
 packages/cli/src/oauthLogin.ts  | 206 +++++++++++++++++
 packages/cli/src/stdioProxy.ts  |   9 +-
 13 files changed, 1208 insertions(+), 163 deletions(-)
 create mode 100644 packages/cli/src/credentials.ts
 create mode 100644 packages/cli/src/errors.ts
 create mode 100644 packages/cli/src/oauthLogin.ts

diff --git a/docs/features/cli.md b/docs/features/cli.md
index 8f37bdc14..217e42634 100644
--- a/docs/features/cli.md
+++ b/docs/features/cli.md
@@ -1,33 +1,38 @@
 # `instatic` CLI
 
+> Unofficial: published from this fork, not by the Instatic project. The npm README (`packages/cli/README.md`) says so at the top, and so does `instatic --help`.
+
 A command-line client for an Instatic site, published to npm as `instatic` and run with `npx instatic` or `bunx instatic`. It lets a person in a terminal, or an AI agent that works through a shell, use the same tools MCP clients get: inspect the site, run editing tools in the open editor, upload media, and publish. `instatic mcp` also runs it as a local stdio MCP server for desktop clients.
 
-The CLI is a thin client of the [MCP endpoint](mcp-connectors.md). It holds no editing logic and no second protocol: every command is an authenticated MCP request to `/_instatic/mcp`, so capability checks, the editor bridge, and drafts-until-publish all behave exactly as they do for any MCP client.
+The CLI is a thin client of the [MCP endpoint](mcp-connectors.md). It holds no editing logic and no second protocol: every command is an authenticated MCP request to `/_instatic/mcp`, so capability checks, the editor bridge, and drafts-until-publish all behave exactly as they do for any MCP client. Anything an agent needs that the tools cannot do belongs in a new MCP tool on the server, so every client gets it, not in CLI-only logic.
 
 ## Why a CLI next to MCP
 
 - **Shell-based agents.** Many coding agents are most reliable with a command that prints JSON and returns an exit code. `instatic call <tool> '<json>'` gives them that without an MCP client.
 - **Build rules in the terminal.** MCP clients receive the server instructions automatically; shell agents do not. `instatic guide` prints them (the CSS/JS build rules from `server/ai/mcp/instructions.ts`) plus CLI usage notes.
 - **Waiting for the editor.** Editing tools need the Site editor open in a browser. `instatic wait-editor` blocks until it is, so an agent can ask the user once instead of failing call after call.
+- **One connection for many calls.** `instatic batch` runs a list of tool calls in one process, instead of one handshake per `call`.
 - **A first-party stdio bridge.** `instatic mcp` replaces the generic `mcp-remote` bridge for desktop clients and adds safe retries.
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `login --url <site> [--token <t> \| --token-stdin] [--profile <name>]` | Verifies the token against the site (`get_context`), then saves the profile and makes it current. Prompts for the token without echo when run in a terminal. |
-| `logout [--profile <name>]` | Forgets a saved profile. Does not revoke the token server-side. |
-| `profiles [use <name>]` | Lists saved profiles (current marked `*`) or switches the current one. |
+| `login --url <site> [--profile <name>] [--no-browser] [--port <n>]` | Browser sign-in (OAuth, see below), then verifies it with `get_context` and saves the profile as current. |
+| `login --url <site> (--with-token \| --token <t>) [--profile <name>]` | Same with a personal access token. `--with-token` prompts without echo in a terminal, else reads stdin. |
+| `logout [--profile <name>]` | Forgets a saved profile. Does not revoke the sign-in or token server-side (revoke it under AI → MCP). |
+| `profiles [use <name>]` | Lists saved profiles (current marked `*`, with `token` or `oauth`) or switches the current one. |
 | `status [--json]` | Site name, URL, profile, whether the Site editor and Content workspace are connected, tool count. |
 | `guide` | Prints the server's build rules and CLI usage notes. |
 | `wait-editor [--scope site\|content] [--timeout <s>]` | Polls `get_context` every 2 s until the workspace is connected (default timeout 120 s). |
-| `tools [<name>] [--json]` | Lists tools, or prints one tool's description and input schema. |
-| `call <tool> [<json> \| --input <file> \| -] [--json] [--images-dir <dir>]` | Runs a tool. Text results print to stdout (pretty-printed JSON); error results print to stderr. Image results (e.g. `site_render_snapshot`) are saved to `--images-dir`. |
+| `tools [<name>] [--json [--schemas]]` | Lists tools, or prints one tool's description and input schema. `--json --schemas` prints every tool with its schema. |
+| `call <tool> [<json> \| --input <file> \| -] [--json] [--images-dir <dir>] [--timeout <s>]` | Runs a tool. Text results print to stdout (pretty-printed JSON); error results print to stderr. Image results (e.g. `site_render_snapshot`) are saved to `--images-dir`. |
+| `batch [<file> \| -] [--keep-going] [--images-dir <dir>] [--timeout <s>]` | Runs a JSON array, or one `{"tool", "args"}` object per line, over one session. Prints one JSON line per call (`{index, tool, ok, result}` or `{index, tool, ok: false, error, editorNotOpen}`). Stops at the first failure unless `--keep-going`; exits with the first failure's code. |
 | `publish` | Runs `site_publish`. |
-| `upload <file> [--alt <text>] [--name <filename>]` | Uploads an image with `media_upload` (inline base64). |
+| `upload <file> [--alt <text>] [--name <filename>]` | Uploads a file with `media_upload` (inline base64). Accepted types are the site's upload policy (Settings → Uploads). |
 | `mcp` | Runs a stdio MCP server that forwards `tools/list` and `tools/call` to the site and advertises the site's own instructions. |
 
-Global options: `--profile`, `--url`, `--token`, `--json`, `--help`, `--version`.
+Global options: `--profile`, `--url`, `--token`, `--json`, `--help`, `--version`. `instatic <command> --help` (or `instatic help <command>`) prints one command's usage.
 
 ### Exit codes
 
@@ -36,22 +41,42 @@ Global options: `--profile`, `--url`, `--token`, `--json`, `--help`, `--version`
 | 0 | Success. |
 | 1 | The tool ran and reported an error (message on stderr). |
 | 2 | Usage error: bad arguments, not logged in, unknown command. |
-| 3 | Authentication failed: token expired, revoked, or wrong. |
+| 3 | Authentication failed: the token or sign-in expired, was revoked, or is wrong. |
 | 4 | The site could not be reached. |
-| 5 | `wait-editor` timed out. |
+| 5 | The Site editor / Content workspace is not open: `wait-editor` timed out, or a `call` / `batch` step needed it (the server marks that result with `_meta["instatic/error"] = "workspace_not_connected"`). |
 | 6 | Any other server or protocol failure. |
 
 ## Configuration
 
-Profiles live in one JSON file, written with owner-only permissions (`0600`) because it holds personal access tokens:
+Profiles live in one JSON file, with owner-only permissions (`0600`) on macOS and Linux because it holds credentials. On Windows the mode is advisory and the user-profile folder's ACL protects it.
 
 1. `$INSTATIC_CONFIG`, else
 2. `$XDG_CONFIG_HOME/instatic/config.json`, else
 3. `~/.config/instatic/config.json`.
 
-The shape is `{ current?, profiles: { <name>: { url, token } } }`, validated with TypeBox on read. Every command resolves its connection as: `--url` / `--token` flags, then `INSTATIC_URL` / `INSTATIC_TOKEN`, then the selected profile (`--profile`, `INSTATIC_PROFILE`, or the saved current one). URLs are normalized, so a site origin and the full `…/_instatic/mcp` URL copied from the admin UI both work. `login` warns when a non-local URL is plain HTTP.
+The shape is `{ current?, profiles: { <name>: { url, token } | { url, oauth } } }`, validated with TypeBox on read. `oauth` holds the issuer, the exact `resource`, the token endpoint, the dynamically registered `clientId`, the access and refresh tokens, and the access token's expiry.
+
+Every command resolves its connection as follows. `--token` / `INSTATIC_TOKEN`, together with `--url` / `INSTATIC_URL`, wins. Otherwise the selected profile is used (`--profile`, `INSTATIC_PROFILE`, or the saved current one). A `--url` that differs from the profile's site is a usage error rather than a reason to send that profile's credentials elsewhere. URLs are normalized, so a site origin and the full `…/_instatic/mcp` URL copied from the admin UI both work. `login` warns when a non-local URL is plain HTTP.
+
+Several processes may share the file: an agent running calls in parallel next to a long-lived `instatic mcp`. So every write goes through `updateConfig`: a lock file (`config.json.lock`, created exclusively, treated as stale after 120 s) serializes writers, and the new content replaces the old by atomic rename.
+
+### Browser sign-in (OAuth)
+
+`login` without a token uses the site's own OAuth authorization server ([MCP connectors](mcp-connectors.md) → "Hosted OAuth flow"), in `packages/cli/src/oauthLogin.ts`:
 
-Tokens are the same personal access tokens as any MCP client: **AI → MCP → Create access token**. Hosted OAuth is not used by the CLI.
+1. **Discover** the authorization server from the MCP endpoint (RFC 9728, then RFC 8414). The `resource` comes from the site's metadata, and it must equal the URL the user typed; otherwise `login` names the site's real public address (for example `www.` against the bare domain). A site without `PUBLIC_ORIGIN` offers no metadata, so `login` says so and points to `--with-token`.
+2. **Listen** on `127.0.0.1` (random port, or `--port` for SSH forwarding). Register a public client for that loopback callback (dynamic client registration, `token_endpoint_auth_method: none`).
+3. **Open** the consent page (PKCE S256, scope `mcp offline_access`, a 32-byte random `state`). The browser is started without a shell (`open`, `rundll32 url.dll,FileProtocolHandler`, or `xdg-open`) and is skipped on a display-less Linux. The URL is always printed as well.
+4. **Check the callback.** It must carry the same `state`, compared in constant time; any other request is refused without ending the wait. The SDK's code exchange validates `iss` (RFC 9207) against the issuer, and the server always sends it. The wait lasts 10 minutes, long enough for a step-up prompt on the consent page.
+
+### Refreshing without self-revocation
+
+The server rotates refresh tokens and treats a reused one as stolen, revoking the whole grant. `credentials.ts` follows one protocol so parallel processes can never trigger that:
+
+- The profile is read from disk on every request, never cached in memory. A long-lived `instatic mcp` therefore picks up tokens rotated by other processes.
+- The access token is refreshed 60 s before expiry, and once more after a `401`. A `401` means nothing ran, so the request is safely re-sent once.
+- A refresh runs only while holding the config lock, and only after re-reading the profile inside it. If another process already rotated the tokens, those are used and no second refresh is sent. A refresh request times out after 30 s, well under the lock's stale threshold, so a lock is never stolen mid-refresh.
+- `invalid_grant` therefore means the sign-in itself is gone (revoked or past its 90 days), not that a race was lost. The CLI exits `3` and asks to run `login` again.
 
 ## Reliability rules
 
@@ -59,9 +84,10 @@ Tokens are the same personal access tokens as any MCP client: **AI → MCP → C
 
 - The client pins MCP `2026-07-28` (the only revision Instatic serves as modern), so there is no version probe or fallback.
 - Failures are classified as `auth`, `unreachable`, or `server`. The SDK nests the real network error under `data.cause` as well as `cause`; the classifier walks both.
+- The bearer token comes from `credentials.ts` per request, through a `fetch` wrapper. Errors raised by the credentials (for example an expired sign-in) are already classified and are found anywhere in the SDK's error chain.
 - **Discovery and reads** (`connect`, `tools/list`) retry twice (500 ms, then 1.5 s) on network failures and gateway statuses (502/503/504). Each attempt builds a fresh client, since an SDK transport starts once.
 - **Tool calls retry only when the request never reached the server**: connection refused, DNS failure, or a gateway status. A connection reset after sending is not retried, so a write is never applied twice.
-- Tool calls use a 150 s timeout, above the server's own budget (up to 15 s waiting for the editor tab plus 90 s for the editor to run the tool). The SDK default of 60 s would cut slow editor calls off.
+- Tool calls use a 150 s timeout (`--timeout` overrides it), above the server's own budget (up to 15 s waiting for the editor tab plus 90 s for the editor to run the tool). The SDK default of 60 s would cut slow editor calls off.
 
 `instatic mcp` (`stdioProxy.ts`) opens the remote session lazily and reopens it after an `unreachable` failure, so the desktop client keeps a live stdio server through site restarts. Connection failures during `tools/call` come back as tool errors with the classified message instead of protocol errors. The proxy exits cleanly when the desktop client closes its stdin.
 
@@ -72,10 +98,13 @@ packages/cli/
   package.json        name "instatic", bin "instatic" → dist/instatic.js, Node >= 20
   tsconfig.json       own strict project, referenced from the root tsconfig (tsc -b)
   README.md           npm package page
-  src/index.ts        executable: wires process streams, hidden token prompt
-  src/cli.ts          command dispatch; all I/O injected through CliIo
+  src/index.ts        executable: wires process streams, hidden token prompt, browser opener
+  src/cli.ts          command dispatch and per-command help; all I/O injected through CliIo
   src/args.ts         minimal argv parser
-  src/config.ts       profiles, URL normalization, connection resolution
+  src/config.ts       profiles, lock + atomic writes, URL normalization, connection resolution
+  src/credentials.ts  bearer tokens; OAuth refresh under the lock
+  src/oauthLogin.ts   browser sign-in (discovery, loopback callback, PKCE, code exchange)
+  src/errors.ts       ConnectionError (auth / unreachable / server)
   src/connection.ts   MCP session, failure classification, safe retries
   src/stdioProxy.ts   `instatic mcp`
   src/cli.test.ts     end-to-end tests against the real handleMcpHttp
@@ -87,7 +116,14 @@ The MCP SDK packages are allowed here as well as under `server/ai/mcp/`: the CLI
 
 ## Tests
 
-`packages/cli/src/cli.test.ts` runs every command in-process with `fetch` routed into `handleMcpHttp` over an in-memory SQLite site: login and the `0600` config file, auth/unreachable/usage exit codes, gateway retries, `guide`, `tools`, headless and editor-relayed `call` (with a simulated editor bridge), stdin arguments, `wait-editor`, profiles, and the stdio proxy over an in-memory transport.
+`packages/cli/src/cli.test.ts` runs every command in-process, with `fetch` routed into `handleMcpHttp` and the OAuth endpoints over an in-memory SQLite site. It covers:
+
+- **Logging in:** token login and the `0600` config file; browser sign-in end to end, with the test approving consent and following the redirect to the real loopback listener, and a forged-`state` callback that is refused.
+- **Refreshing:** an expired token refreshed by five parallel commands without revoking the sign-in; renewal after a `401`; a revoked sign-in exiting `3`.
+- **Credentials:** a profile's credentials never going to another `--url`.
+- **Exit codes and retries:** auth, unreachable, and usage exit codes; gateway retries.
+- **Tool calls:** `guide`, `tools`, headless and editor-relayed `call` (with a simulated editor bridge), stdin arguments, `batch` (stop and `--keep-going`), and exit `5` when no editor is open.
+- **The rest:** `wait-editor`, profiles, per-command help, and the stdio proxy over an in-memory transport.
 
 ## Publishing
 
@@ -99,4 +135,8 @@ npm version <patch|minor|major>   # bumps packages/cli/package.json
 npm publish --access public        # prepublishOnly builds dist/ first
 ```
 
-The CLI is versioned independently of the Instatic server. It depends only on the MCP wire protocol and the tool names it shortcuts (`get_context`, `site_publish`, `media_upload`).
+The CLI is versioned independently of the Instatic server. It depends only on:
+
+- the MCP wire protocol and the OAuth endpoints;
+- the tool names it shortcuts (`get_context`, `site_publish`, `media_upload`);
+- the `instatic/error` result marker.
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 6cb67486a..42bddb500 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -1,77 +1,105 @@
 # instatic
 
-Command-line client for [Instatic](https://github.com/flyingwebie/Instatic) sites. Drive the visual editor, upload media, and publish from a terminal — or let an AI agent do it.
+> **Unofficial.** This CLI is a community project. It is **not** made, endorsed, or supported by the [Instatic](https://github.com/CoreBunch/Instatic) project or its maintainers. Please report problems with it to [this fork](https://github.com/flyingwebie/Instatic), not upstream.
+
+Command-line client for Instatic sites. Drive the visual editor, upload media, and publish from a terminal, or let an AI agent do it.
 
 ```sh
 npx instatic login --url https://your-site.com
 # or: bunx instatic login --url https://your-site.com
 ```
 
-Create the access token in Instatic under **AI → MCP → Create access token**. `login` asks for it without echoing, or takes `--token` / `--token-stdin`.
+`login` opens your browser on the site's consent page. Approve access there; you need to be an Instatic admin. The CLI keeps the sign-in fresh by itself for 90 days. Browser sign-in needs `PUBLIC_ORIGIN` set on the server.
+
+To use an access token instead (Instatic → **AI → MCP → Create access token**):
+
+```sh
+instatic login --url https://your-site.com --with-token   # prompts, or reads stdin
+```
+
+On a remote machine over SSH, pass `--no-browser --port 8765`, forward the port (`ssh -L 8765:127.0.0.1:8765 <host>`), and open the printed URL locally. In CI, skip `login` and set `INSTATIC_URL` and `INSTATIC_TOKEN`.
 
 ## For AI agents
 
 ```sh
-instatic guide                       # the site's build rules — read first
+instatic guide                       # the site's build rules: read first
 instatic wait-editor                 # block until the Site editor is open in a browser
 instatic tools                       # list tools
 instatic tools site_insert_html      # one tool's input schema
 instatic call site_read_document '{}'
 instatic call site_insert_html --input section.json
+instatic batch steps.jsonl           # many calls over one connection
 instatic publish                     # drafts go live
 ```
 
-`call` prints the tool's JSON result to stdout. Exit codes are stable:
+`call` prints the tool's JSON result to stdout. `batch` reads a JSON array, or one `{"tool": …, "args": {…}}` object per line, and prints one JSON result line per call. It stops at the first failure unless you pass `--keep-going`. Exit codes are stable:
 
 | Code | Meaning |
 |---|---|
 | 0 | Success |
 | 1 | The tool reported an error (message on stderr) |
 | 2 | Usage error / not logged in |
-| 3 | Token rejected (expired or revoked) |
+| 3 | Sign-in or token rejected (expired or revoked) |
 | 4 | Site unreachable |
-| 5 | `wait-editor` timed out |
+| 5 | The Site editor is not open (`wait-editor` timed out, or a tool needed it) |
 | 6 | Other server error |
 
 Editing tools run inside the Site editor, which must be open in a browser and signed in as the token's owner. Reads, `upload`, and `publish` work without it.
 
+## Tools
+
+`instatic tools` lists what your connection may use. A token or sign-in only sees the tools its granted capabilities allow. With every capability, a site offers these 54:
+
+| Area | Tools |
+|---|---|
+| Orientation | `get_context`, `site_list_documents`, `site_read_document`, `site_open_document`, `site_list_modules`, `site_list_breakpoints`, `site_list_post_types`, `site_list_loop_sources` |
+| Page structure | `site_insert_html`, `site_get_node_html`, `site_replace_node_html`, `site_update_node_props`, `site_move_node`, `site_duplicate_node`, `site_rename_node`, `site_delete_node` |
+| Pages and templates | `site_add_page`, `site_duplicate_page`, `site_rename_page`, `site_delete_page`, `site_set_page_template`, `site_clear_page_template` |
+| CSS and design tokens | `site_read_styles`, `site_apply_css`, `site_assign_class`, `site_remove_class`, `site_set_color_tokens`, `site_set_font_tokens`, `site_set_type_scale`, `site_set_spacing_scale` |
+| Scripts and code files | `site_write_page_script`, `site_list_code_assets`, `site_read_code_asset`, `site_write_code_asset`, `site_patch_code_asset`, `site_inspect_code_runtime` |
+| Verify and publish | `site_render_snapshot`, `site_publish` |
+| Content | `content_list_collections`, `content_get_collection_schema`, `content_list_documents`, `content_get_document`, `content_search_documents`, `content_create_document`, `content_set_document_field`, `content_set_document_fields`, `content_set_document_status`, `content_set_document_author`, `content_delete_document`, `content_set_active_document`, `content_set_active_collection`, `content_list_users` |
+| Media | `media_upload`, `content_list_media` |
+
+Every tool runs through `instatic call <tool>` or `instatic batch`. `publish` and `upload` are shortcuts for `site_publish` and `media_upload`. `upload` accepts whatever file types the site's **Settings → Uploads** allows.
+
 ## Desktop MCP clients
 
-`instatic mcp` runs a local stdio MCP server that forwards to your site, for clients such as Claude Desktop or Cursor:
+`instatic mcp` runs a local stdio MCP server that forwards to your site, for clients such as Claude Desktop or Cursor. Log in once, then:
 
 ```json
 {
   "mcpServers": {
     "instatic": {
       "command": "npx",
-      "args": ["-y", "instatic", "mcp"],
-      "env": {
-        "INSTATIC_URL": "https://your-site.com",
-        "INSTATIC_TOKEN": "imcp_pat_…"
-      }
+      "args": ["-y", "instatic", "mcp"]
     }
   }
 }
 ```
 
+Add `"--profile", "<name>"` to `args` for a non-default profile. You can also skip `login` and pass `"env": { "INSTATIC_URL": "https://your-site.com", "INSTATIC_TOKEN": "imcp_pat_…" }`.
+
 ## Commands
 
 ```text
-login --url <site> [--token <t> | --token-stdin] [--profile <name>]
+login --url <site> [--profile <name>] [--no-browser] [--port <n>]
+login --url <site> (--with-token | --token <t>) [--profile <name>]
 logout [--profile <name>]
 profiles [use <name>]
 status [--json]
 guide
 wait-editor [--scope site|content] [--timeout <seconds>]
-tools [<name>] [--json]
-call <tool> [<json> | --input <file> | -] [--json] [--images-dir <dir>]
+tools [<name>] [--json [--schemas]]
+call <tool> [<json> | --input <file> | -] [--json] [--images-dir <dir>] [--timeout <seconds>]
+batch [<file> | -] [--keep-going] [--images-dir <dir>] [--timeout <seconds>]
 publish
 upload <file> [--alt <text>] [--name <filename>]
 mcp
 ```
 
-Global options: `--profile <name>`, `--url <site>`, `--token <token>`, `--json`.
+`instatic <command> --help` explains one command. Global options: `--profile <name>`, `--url <site>`, `--token <token>`, `--json`.
 
-Connections resolve from flags, then `INSTATIC_URL` / `INSTATIC_TOKEN`, then the saved profile. Profiles are stored in `~/.config/instatic/config.json` (or `$XDG_CONFIG_HOME/instatic/`, or `$INSTATIC_CONFIG`) with owner-only permissions.
+Connections resolve from `--token` / `INSTATIC_TOKEN` (with `--url` / `INSTATIC_URL`), then the saved profile. A profile's credentials are only ever sent to that profile's site. Profiles are stored in `~/.config/instatic/config.json` (or `$XDG_CONFIG_HOME/instatic/`, or `$INSTATIC_CONFIG`). On macOS and Linux the file is readable only by you. On Windows it relies on your user folder's permissions.
 
 Requires Node 20+ or Bun.
diff --git a/packages/cli/package.json b/packages/cli/package.json
index b47ab7e09..1e415eaac 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,7 +1,7 @@
 {
   "name": "instatic",
   "version": "0.1.0",
-  "description": "Command-line client for Instatic sites: drive the visual editor, publish, and upload media from a terminal or an AI agent.",
+  "description": "Unofficial command-line client for Instatic sites: drive the visual editor, publish, and upload media from a terminal or an AI agent. Not affiliated with the Instatic project.",
   "license": "MIT",
   "type": "module",
   "bin": {
diff --git a/packages/cli/src/args.ts b/packages/cli/src/args.ts
index dfe320815..2dc86a00a 100644
--- a/packages/cli/src/args.ts
+++ b/packages/cli/src/args.ts
@@ -9,7 +9,7 @@ export interface ParsedArgs {
   flags: Map<string, string | true>
 }
 
-const BOOLEAN_FLAGS = new Set(['json', 'help', 'version', 'token-stdin', 'all'])
+const BOOLEAN_FLAGS = new Set(['json', 'help', 'version', 'with-token', 'no-browser', 'schemas', 'keep-going'])
 
 export function parseArgs(argv: readonly string[]): ParsedArgs {
   const positionals: string[] = []
diff --git a/packages/cli/src/cli.test.ts b/packages/cli/src/cli.test.ts
index c11d9b6b1..d87ecbe0b 100644
--- a/packages/cli/src/cli.test.ts
+++ b/packages/cli/src/cli.test.ts
@@ -5,7 +5,8 @@
  * production ones.
  */
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import { mkdtemp, readFile, rm, stat } from 'node:fs/promises'
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { get as httpGet } from 'node:http'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Client, InMemoryTransport } from '@modelcontextprotocol/client'
@@ -14,11 +15,14 @@ import { sqliteMigrations } from '../../../server/db/migrations-sqlite'
 import { runMigrations } from '../../../server/db/runMigrations'
 import type { DbClient } from '../../../server/db/client'
 import { handleMcpHttp } from '../../../server/ai/mcp'
+import { tryHandleMcpOAuth } from '../../../server/ai/mcp/oauth/handler'
+import { createOAuthAuthorizationGrant } from '../../../server/ai/mcp/oauth/store'
+import { parseOAuthAuthorizationRequest } from '../../../server/ai/mcp/oauth/schemas'
 import { createBearerConnection } from '../../../server/ai/mcp/connectors/store'
 import { generatePersonalAccessToken, hashMcpSecret } from '../../../server/ai/mcp/connectors/token'
 import { createEditorBridgeStream } from '../../../server/ai/mcp/editorBridge'
 import { resolveBridgeToolResult } from '../../../server/ai/runtime'
-import { EXIT, runCli, type CliIo } from './cli'
+import { EXIT, parseBatch, runCli, type CliIo } from './cli'
 import { classifyFailure } from './connection'
 import { createProxyServer } from './stdioProxy'
 
@@ -41,7 +45,7 @@ beforeEach(async () => {
   await createBearerConnection(db, {
     userId,
     label: 'CLI test',
-    capabilities: ['ai.chat', 'ai.tools.write', 'site.read', 'site.structure.edit', 'content.manage', 'pages.edit'],
+    capabilities: [...CAPABILITIES],
     tokenHash: await hashMcpSecret(token),
   })
   configDir = await mkdtemp(join(tmpdir(), 'instatic-cli-'))
@@ -51,11 +55,61 @@ afterEach(async () => {
   await rm(configDir, { recursive: true, force: true })
 })
 
+const CAPABILITIES = ['ai.chat', 'ai.tools.write', 'site.read', 'site.structure.edit', 'content.manage', 'pages.edit'] as const
+
+/** The site's MCP endpoint and OAuth surface, in-process. */
 const handlerFetch = async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
-  const res = await handleMcpHttp(new Request(input, init), db)
+  const req = new Request(input, init)
+  const oauth = await tryHandleMcpOAuth(req, db, new URL(req.url).pathname)
+  if (oauth) return oauth
+  const res = await handleMcpHttp(req, db, { workspaceWaitMs: 20 })
   return res ?? new Response(null, { status: 404 })
 }
 
+/**
+ * Play the user in the browser: approve the consent request the CLI opened
+ * (as the admin consent page would) and follow the redirect to the CLI's
+ * loopback callback.
+ */
+async function approveInBrowser(url: string): Promise<boolean> {
+  const request = parseOAuthAuthorizationRequest(new URL(url).searchParams)
+  if (!request) throw new Error(`not an authorization URL: ${url}`)
+  const { code } = await createOAuthAuthorizationGrant(db, {
+    userId,
+    clientName: 'instatic CLI',
+    capabilities: [...CAPABILITIES],
+    request,
+  })
+  // A callback that is not ours (wrong state) is refused and does not end the wait.
+  expect(await browserGet(`${request.redirectUri}?code=forged&state=wrong`)).toBe(400)
+  const callback = new URL(request.redirectUri)
+  callback.searchParams.set('code', code)
+  callback.searchParams.set('state', request.state ?? '')
+  callback.searchParams.set('iss', SITE)
+  expect(await browserGet(callback.href)).toBe(200)
+  return true
+}
+
+/** GET a loopback URL like a browser following a redirect (the test preload's fetch enforces CORS). */
+function browserGet(url: string): Promise<number> {
+  return new Promise((resolve, reject) => {
+    httpGet(url, (res) => {
+      res.resume()
+      resolve(res.statusCode ?? 0)
+    }).on('error', reject)
+  })
+}
+
+async function readSavedConfig() {
+  return JSON.parse(await readFile(join(configDir, 'config.json'), 'utf8'))
+}
+
+async function editSavedOAuth(change: (oauth: Record<string, unknown>) => void) {
+  const config = await readSavedConfig()
+  change(config.profiles.default.oauth)
+  await writeFile(join(configDir, 'config.json'), JSON.stringify(config))
+}
+
 async function run(argv: string[], overrides: Partial<CliIo> = {}) {
   let stdout = ''
   let stderr = ''
@@ -250,9 +304,123 @@ describe('instatic CLI', () => {
     expect((await run(['profiles', '--json'])).stdout).not.toContain('staging')
   })
 
+  it('signs in through the browser and saves an OAuth profile', async () => {
+    let log = ''
+    const result = await run(['login', '--url', SITE], {
+      openBrowser: approveInBrowser,
+      stderr: (text) => { log += text },
+    })
+    expect(result.code).toBe(EXIT.ok)
+    expect(result.stdout).toContain('(browser sign-in)')
+    expect(log).toContain('Opened your browser')
+
+    const saved = await readSavedConfig()
+    expect(saved.current).toBe('default')
+    expect(saved.profiles.default.url).toBe(SITE)
+    expect(saved.profiles.default.oauth).toMatchObject({
+      resource: `${SITE}/_instatic/mcp`,
+      accessToken: expect.stringMatching(/^imcp_at_/),
+      refreshToken: expect.any(String),
+    })
+    expect(JSON.stringify(saved)).not.toContain('imcp_pat_')
+    expect((await run(['profiles'])).stdout).toContain('(oauth)')
+    expect((await run(['call', 'get_context', '{}'])).code).toBe(EXIT.ok)
+  })
+
+  it('refreshes an expiring sign-in, once, even with parallel commands', async () => {
+    expect((await run(['login', '--url', SITE], { openBrowser: approveInBrowser })).code).toBe(EXIT.ok)
+    const before = (await readSavedConfig()).profiles.default.oauth
+    await editSavedOAuth((oauth) => { oauth.expiresAt = 0 })
+
+    // Five processes find the token expired at the same moment. Only one may
+    // refresh: a second refresh would reuse a rotated token, which the server
+    // treats as theft and answers by revoking the sign-in.
+    const results = await Promise.all(Array.from({ length: 5 }, () => run(['call', 'get_context', '{}'])))
+    expect(results.map((r) => r.code)).toEqual([0, 0, 0, 0, 0])
+
+    const after = (await readSavedConfig()).profiles.default.oauth
+    expect(after.accessToken).not.toBe(before.accessToken)
+    expect(after.refreshToken).not.toBe(before.refreshToken)
+    expect(after.expiresAt).toBeGreaterThan(Date.now())
+    expect((await run(['status'])).code).toBe(EXIT.ok)
+  })
+
+  it('renews after the server rejects a not-yet-expired access token', async () => {
+    expect((await run(['login', '--url', SITE], { openBrowser: approveInBrowser })).code).toBe(EXIT.ok)
+    await editSavedOAuth((oauth) => { oauth.accessToken = 'imcp_at_revoked' })
+    const result = await run(['call', 'get_context', '{}'])
+    expect(result.code).toBe(EXIT.ok)
+    expect((await readSavedConfig()).profiles.default.oauth.accessToken).not.toBe('imcp_at_revoked')
+  })
+
+  it('asks to log in again once the sign-in is revoked', async () => {
+    expect((await run(['login', '--url', SITE], { openBrowser: approveInBrowser })).code).toBe(EXIT.ok)
+    await db`update ai_mcp_connectors set revoked_at = ${new Date().toISOString()}`
+    await editSavedOAuth((oauth) => { oauth.expiresAt = 0 })
+    const result = await run(['call', 'get_context', '{}'])
+    expect(result.code).toBe(EXIT.auth)
+    expect(result.stderr).toContain('instatic login')
+  })
+
+  it('logs in with an access token from stdin', async () => {
+    const result = await run(['login', '--url', SITE, '--with-token'], { readStdin: async () => `${token}\n` })
+    expect(result.code).toBe(EXIT.ok)
+    expect(result.stdout).toContain('(access token)')
+    expect((await readSavedConfig()).profiles.default).toEqual({ url: SITE, token })
+  })
+
+  it('never sends a profile\'s credentials to a different --url', async () => {
+    await login()
+    const result = await run(['status', '--url', 'https://other.example'])
+    expect(result.code).toBe(EXIT.usage)
+    expect(result.stderr).toContain('is for http://localhost')
+  })
+
+  it('runs a batch over one connection and stops at the first failure', async () => {
+    await login()
+    const batch = [
+      JSON.stringify({ tool: 'get_context', args: {} }),
+      JSON.stringify({ tool: 'not_a_tool' }),
+      JSON.stringify({ tool: 'get_context' }),
+    ].join('\n')
+    const result = await run(['batch', '-'], { readStdin: async () => batch })
+    expect(result.code).toBe(EXIT.toolError)
+    const lines = result.stdout.trim().split('\n').map((line) => JSON.parse(line))
+    expect(lines).toHaveLength(2)
+    expect(lines[0]).toMatchObject({ index: 0, tool: 'get_context', ok: true })
+    expect(lines[0].result).toHaveProperty('editor')
+    expect(lines[1]).toMatchObject({ index: 1, ok: false, editorNotOpen: false })
+
+    const all = await run(['batch', '-', '--keep-going'], { readStdin: async () => batch })
+    expect(all.stdout.trim().split('\n')).toHaveLength(3)
+    expect(parseBatch('[{"tool":"a"}]')).toEqual([{ tool: 'a', args: {} }])
+    expect(() => parseBatch('{"args":{}}')).toThrow(/tool/)
+  })
+
+  it('exits 5 when a tool needs the editor and none is open', async () => {
+    await login()
+    const result = await run(['call', 'site_write_page_script', '{"content":"1"}'])
+    expect(result.code).toBe(EXIT.editorMissing)
+    expect(result.stderr).toContain('Site editor')
+
+    const batch = await run(['batch', '-'], {
+      readStdin: async () => JSON.stringify([{ tool: 'site_write_page_script', args: { content: '1' } }]),
+    })
+    expect(batch.code).toBe(EXIT.editorMissing)
+    expect(JSON.parse(batch.stdout)).toMatchObject({ ok: false, editorNotOpen: true })
+  })
+
+  it('prints help for one command', async () => {
+    const help = await run(['batch', '--help'])
+    expect(help.code).toBe(EXIT.ok)
+    expect(help.stdout).toContain('--keep-going')
+    expect((await run(['help', 'login'])).stdout).toContain('--with-token')
+    expect((await run(['--help'])).stdout).toContain('Unofficial')
+  })
+
   it('serves the site over a local MCP proxy with the site\'s own instructions and tools', async () => {
     const { server, close } = await createProxyServer(
-      { url: SITE, token, profile: null },
+      { url: SITE, auth: { kind: 'token', token }, profile: null },
       { clientVersion: 'test', fetch: handlerFetch, log: () => {} },
     )
     const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 402386fcf..88082a04c 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -17,11 +17,14 @@ import {
   readConfig,
   resolveConnection,
   selectedProfileName,
-  writeConfig,
+  updateConfig,
   type Env,
   type ResolvedConnection,
 } from './config'
-import { ConnectionError, InstaticSession, resultText, type ToolCallResult } from './connection'
+import { InstaticSession, resultText, type ToolCallResult } from './connection'
+import { saveOAuthProfile } from './credentials'
+import { ConnectionError } from './errors'
+import { oauthLogin } from './oauthLogin'
 import { runStdioProxy } from './stdioProxy'
 import pkg from '../package.json' with { type: 'json' }
 
@@ -34,7 +37,7 @@ export const EXIT = {
   usage: 2,
   auth: 3,
   unreachable: 4,
-  /** `wait-editor` timed out. */
+  /** The Site editor / Content workspace is not open: `wait-editor` timed out, or a tool needed it. */
   editorMissing: 5,
   server: 6,
 } as const
@@ -48,6 +51,8 @@ export interface CliIo {
   stdinIsTty: boolean
   /** Ask for a secret without echoing it. Absent when there is no terminal. */
   promptSecret?: (question: string) => Promise<string>
+  /** Open a URL in the user's browser; false when none could be started. */
+  openBrowser?: (url: string) => Promise<boolean>
   /** Test seam: replaces the network. */
   fetch?: FetchLike
   /** Test seam for `wait-editor` polling. */
@@ -55,25 +60,27 @@ export interface CliIo {
 }
 
 const HELP = `instatic ${CLI_VERSION} — drive an Instatic site from the terminal or an AI agent
+Unofficial community tool; not affiliated with the Instatic project.
 
-Usage: instatic <command> [options]
+Usage: instatic <command> [options]      instatic <command> --help for details
 
 Setup
-  login --url <site> [--token <t> | --token-stdin]   Save and verify a connection
-  logout                                             Forget the selected profile
-  profiles [use <name>]                              List or switch saved profiles
-  status                                             Site, editor connection, tool count
+  login --url <site>            Sign in through the browser (OAuth)
+  login --url <site> --with-token
+                                Sign in with an access token instead
+  logout                        Forget the selected profile
+  profiles [use <name>]         List or switch saved profiles
+  status                        Site, editor connection, tool count
 
 Agent workflow
   guide                         Print the site's build rules (read this first)
-  wait-editor [--scope site|content] [--timeout <s>]
-                                Wait until the editor tab is open and connected
+  wait-editor                   Wait until the editor tab is open and connected
   tools [<name>]                List tools, or show one tool's input schema
   call <tool> [<json> | --input <file> | -]
                                 Run a tool; prints its JSON result
+  batch [<file> | -]            Run many tool calls over one connection
   publish                       Publish the site (drafts go live)
-  upload <file> [--alt <text>] [--name <filename>]
-                                Add an image to the Media library
+  upload <file>                 Add a file to the Media library
 
 Integrations
   mcp                           Run as a local stdio MCP server (Claude Desktop,
@@ -81,25 +88,109 @@ Integrations
 
 Global options
   --profile <name>   Saved profile to use (default: the current one)
-  --url <site>       Site URL, overrides the profile (env INSTATIC_URL)
+  --url <site>       Site URL (env INSTATIC_URL)
   --token <token>    Access token, overrides the profile (env INSTATIC_TOKEN)
   --json             Machine-readable output where supported
   -h, --help         Show help    --version  Show version
 
 Exit codes: 0 ok · 1 tool error · 2 usage · 3 auth · 4 unreachable ·
-            5 editor not connected · 6 server error
-
-Create a token in Instatic under AI → MCP → Create access token.`
+            5 editor not open · 6 server error`
+
+const COMMAND_HELP: Record<string, string> = {
+  login: `instatic login --url <site> [--profile <name>] [--no-browser] [--port <n>]
+instatic login --url <site> --with-token [--profile <name>]
+instatic login --url <site> --token <token> [--profile <name>]
+
+Signs in and saves the connection as a profile (default "default"), then makes
+it the current one.
+
+Without a token, login signs in through the browser: approve access on the
+Instatic consent page (you need to be an admin there). The CLI keeps the
+sign-in fresh by itself for 90 days. Browser sign-in needs PUBLIC_ORIGIN set
+on the server.
+
+  --no-browser   Print the sign-in URL instead of opening a browser
+  --port <n>     Fixed local callback port, e.g. to forward it over SSH:
+                 ssh -L <n>:127.0.0.1:<n> <remote>, then open the URL locally
+  --with-token   Use an access token (Instatic → AI → MCP → Create access
+                 token): prompted for in a terminal, else read from stdin
+  --token <t>    Pass the access token directly (visible in shell history)
+
+For CI and scripts, skip login: set INSTATIC_URL and INSTATIC_TOKEN.`,
+  logout: `instatic logout [--profile <name>]
+
+Forgets a saved profile. The sign-in or token stays valid on the server until
+you revoke it in Instatic under AI → MCP.`,
+  profiles: `instatic profiles [--json]
+instatic profiles use <name>
+
+Lists saved profiles (the current one is marked *), or switches the current one.`,
+  status: `instatic status [--json]
+
+Shows the site, the profile, whether the Site editor and Content workspace are
+open, and how many tools the connection may use.`,
+  guide: `instatic guide
+
+Prints the site's build rules for agents (where CSS and JS belong, how to
+verify work) and notes on using them from this CLI. Read it before editing.`,
+  'wait-editor': `instatic wait-editor [--scope site|content] [--timeout <seconds>]
+
+Waits until the Site editor (default) or Content workspace is open in a
+browser, signed in as the token's owner. Default timeout 120 s; exit code 5 on
+timeout. Editing tools need it open; reads, upload and publish do not.`,
+  tools: `instatic tools [--json [--schemas]]
+instatic tools <name> [--json]
+
+Lists the tools this connection may use, or shows one tool's description and
+input schema. --json --schemas prints every tool with its schema at once.`,
+  call: `instatic call <tool> [<json> | --input <file> | -] [--json] [--images-dir <dir>] [--timeout <seconds>]
+
+Runs one tool. Arguments are a JSON object: inline, from a file (--input), or
+from stdin (- or --input -). Prefer a file or stdin for large HTML.
+
+Prints the result's JSON to stdout. A tool error prints to stderr with exit
+code 1; exit code 5 means the tool needs the editor open (run wait-editor,
+then retry). Images (site_render_snapshot) are saved with --images-dir.
+--json prints the raw MCP result instead. Default timeout 150 s.`,
+  batch: `instatic batch [<file> | -] [--keep-going] [--images-dir <dir>] [--timeout <seconds>]
+
+Runs several tool calls over one connection, in order. The input (a file, or
+stdin) is a JSON array, or one JSON object per line:
+
+  {"tool": "site_add_page", "args": {"title": "About"}}
+  {"tool": "site_insert_html", "args": {"parentId": "root", "html": "<section>…</section>"}}
+
+Prints one JSON line per call: {"index", "tool", "ok", "result"} on success,
+{"index", "tool", "ok": false, "error", "editorNotOpen"} on failure.
+Stops at the first failure unless --keep-going. The exit code is the first
+failure's (1 tool error, 5 editor not open), or 0.`,
+  publish: `instatic publish
+
+Publishes the saved site draft: every edit so far goes live.`,
+  upload: `instatic upload <file> [--alt <text>] [--name <filename>]
+
+Uploads a file to the Media library and prints its id and public path. Allowed
+types follow the site's Settings → Uploads (by default images, MP4/WebM, web
+fonts, PDF and office documents).`,
+  mcp: `instatic mcp
+
+Runs a local stdio MCP server that forwards to the site, for desktop MCP
+clients such as Claude Desktop or Cursor. Uses the selected profile (log in
+first) or INSTATIC_URL / INSTATIC_TOKEN.`,
+}
 
 const CLI_GUIDE_NOTE = `
 
 Using these tools from the instatic CLI:
 - instatic call <tool> '<json args>' runs one tool and prints its JSON result.
+  Pass large arguments from a file (--input args.json) or stdin (-).
+- instatic batch runs many calls over one connection (instatic batch --help).
 - instatic tools <tool> shows a tool's input schema.
 - Editing tools (site_*) need the Site editor open in a browser:
   run instatic wait-editor before a batch of edits.
 - Exit code 1 means the tool reported an error (message on stderr); read it
-  before retrying.`
+  before retrying. Exit code 5 means the editor is not open: run
+  instatic wait-editor, then retry.`
 
 function globalConnectionFlags(args: ParsedArgs) {
   return {
@@ -109,9 +200,13 @@ function globalConnectionFlags(args: ParsedArgs) {
   }
 }
 
+async function resolve(args: ParsedArgs, io: CliIo): Promise<ResolvedConnection> {
+  const path = configPath(io.env)
+  return resolveConnection(globalConnectionFlags(args), io.env, await readConfig(path), path)
+}
+
 async function connect(args: ParsedArgs, io: CliIo): Promise<{ session: InstaticSession; connection: ResolvedConnection }> {
-  const config = await readConfig(configPath(io.env))
-  const connection = resolveConnection(globalConnectionFlags(args), io.env, config)
+  const connection = await resolve(args, io)
   const session = await InstaticSession.open(connection, { clientVersion: CLI_VERSION, fetch: io.fetch })
   return { session, connection }
 }
@@ -173,35 +268,55 @@ async function readContext(session: InstaticSession): Promise<EditorContext | nu
   return parseContext(await session.callTool('get_context', {}))
 }
 
+function resultExitCode(result: ToolCallResult): number {
+  if (result.workspaceNotConnected) return EXIT.editorMissing
+  return result.isError ? EXIT.toolError : EXIT.ok
+}
+
+/** Save a result's image blocks to `dir`; returns the paths. */
+async function saveImages(result: ToolCallResult, dir: string, prefix: string): Promise<string[]> {
+  const paths: string[] = []
+  for (const block of result.content) {
+    if (block.type !== 'image' || typeof block.data !== 'string') continue
+    const extension = block.mimeType?.split('/')[1]?.split('+')[0] ?? 'bin'
+    await mkdir(dir, { recursive: true })
+    const path = join(dir, `${prefix}${paths.length + 1}.${extension}`)
+    await writeFile(path, Buffer.from(block.data, 'base64'))
+    paths.push(path)
+  }
+  return paths
+}
+
 async function emitToolResult(io: CliIo, args: ParsedArgs, result: ToolCallResult): Promise<number> {
   if (booleanFlag(args, 'json')) {
     printJson(io, result)
-    return result.isError ? EXIT.toolError : EXIT.ok
+    return resultExitCode(result)
   }
 
-  const imagesDir = stringFlag(args, 'images-dir')
-  let imageIndex = 0
   for (const block of result.content) {
     if (block.type === 'text' && typeof block.text === 'string') {
       const text = formatResultText(block.text)
       if (result.isError) io.stderr(`${text}\n`)
       else io.stdout(`${text}\n`)
-      continue
-    }
-    if (block.type === 'image' && typeof block.data === 'string') {
-      imageIndex++
-      const extension = block.mimeType?.split('/')[1]?.split('+')[0] ?? 'bin'
-      if (imagesDir) {
-        await mkdir(imagesDir, { recursive: true })
-        const path = join(imagesDir, `image-${imageIndex}.${extension}`)
-        await writeFile(path, Buffer.from(block.data, 'base64'))
-        io.stderr(`Saved image to ${path}\n`)
-      } else {
-        io.stderr(`[image ${imageIndex}: ${block.mimeType ?? 'unknown type'}; pass --images-dir <dir> to save it]\n`)
-      }
     }
   }
-  return result.isError ? EXIT.toolError : EXIT.ok
+  const imagesDir = stringFlag(args, 'images-dir')
+  const imageCount = result.content.filter((block) => block.type === 'image').length
+  if (imagesDir) {
+    for (const path of await saveImages(result, imagesDir, 'image-')) io.stderr(`Saved image to ${path}\n`)
+  } else if (imageCount > 0) {
+    io.stderr(`[${imageCount} image(s) in the result; pass --images-dir <dir> to save them]\n`)
+  }
+  return resultExitCode(result)
+}
+
+/** `--timeout <seconds>` for tool calls, in milliseconds. */
+function callTimeoutMs(args: ParsedArgs): number | undefined {
+  const raw = stringFlag(args, 'timeout')
+  if (raw === undefined) return undefined
+  const seconds = Number(raw)
+  if (!Number.isFinite(seconds) || seconds <= 0) throw new UsageError('--timeout must be a positive number of seconds.')
+  return seconds * 1000
 }
 
 async function readToolInput(args: ParsedArgs, io: CliIo): Promise<Record<string, unknown>> {
@@ -229,15 +344,18 @@ async function readToolInput(args: ParsedArgs, io: CliIo): Promise<Record<string
   return parsed as Record<string, unknown>
 }
 
-async function readToken(args: ParsedArgs, io: CliIo): Promise<string> {
+/** The access token for `login`, or null to sign in through the browser. */
+async function readLoginToken(args: ParsedArgs, io: CliIo): Promise<string | null> {
   const flag = stringFlag(args, 'token')
   if (flag) return flag
-  if (booleanFlag(args, 'token-stdin')) return (await io.readStdin()).trim()
-  if (io.env.INSTATIC_TOKEN) return io.env.INSTATIC_TOKEN
-  if (io.stdinIsTty && io.promptSecret) {
-    return (await io.promptSecret('Access token (Instatic → AI → MCP → Create access token): ')).trim()
+  if (booleanFlag(args, 'with-token')) {
+    if (io.stdinIsTty && io.promptSecret) {
+      return (await io.promptSecret('Access token (Instatic → AI → MCP → Create access token): ')).trim()
+    }
+    return (await io.readStdin()).trim()
   }
-  throw new UsageError('No token given. Pass --token <token>, --token-stdin, or set INSTATIC_TOKEN.')
+  if (io.env.INSTATIC_TOKEN) return io.env.INSTATIC_TOKEN
+  return null
 }
 
 // ---------------------------------------------------------------------------
@@ -248,28 +366,47 @@ async function cmdLogin(args: ParsedArgs, io: CliIo): Promise<number> {
   const rawUrl = stringFlag(args, 'url') ?? args.positionals[1] ?? io.env.INSTATIC_URL
   if (!rawUrl) throw new UsageError('Pass the site URL: instatic login --url https://your-site.com')
   const url = normalizeSiteUrl(rawUrl)
-  const token = await readToken(args, io)
-  if (!token) throw new UsageError('The token is empty.')
+  const name = stringFlag(args, 'profile') ?? DEFAULT_PROFILE
+  const path = configPath(io.env)
+  const token = await readLoginToken(args, io)
+  if (token === '') throw new UsageError('The token is empty.')
   if (isInsecureRemote(url)) {
-    io.stderr(`Warning: ${url} is not HTTPS, so the token travels unencrypted.\n`)
+    io.stderr(`Warning: ${url} is not HTTPS, so credentials travel unencrypted.\n`)
+  }
+
+  if (token === null) {
+    const portRaw = stringFlag(args, 'port')
+    const port = portRaw === undefined ? 0 : Number(portRaw)
+    if (!Number.isInteger(port) || port < 0 || port > 65535) throw new UsageError('--port must be a port number.')
+    const session = await oauthLogin(url, {
+      fetch: io.fetch,
+      openBrowser: booleanFlag(args, 'no-browser') ? undefined : io.openBrowser,
+      log: io.stderr,
+      port,
+    })
+    await saveOAuthProfile(path, name, url, session)
   }
 
-  const session = await InstaticSession.open({ url, token, profile: null }, { clientVersion: CLI_VERSION, fetch: io.fetch })
+  // Verify the saved credentials end to end (and read the site name).
+  const connection: ResolvedConnection = token === null
+    ? { url, auth: { kind: 'oauth', configPath: path, profile: name }, profile: name }
+    : { url, auth: { kind: 'token', token }, profile: name }
+  const session = await InstaticSession.open(connection, { clientVersion: CLI_VERSION, fetch: io.fetch })
   let context: EditorContext | null
   try {
     context = await readContext(session)
   } finally {
     await session.close()
   }
+  if (token !== null) {
+    await updateConfig(path, (config) => {
+      config.profiles[name] = { url, token }
+      config.current = name
+    })
+  }
 
-  const path = configPath(io.env)
-  const config = await readConfig(path)
-  const name = stringFlag(args, 'profile') ?? DEFAULT_PROFILE
-  config.profiles[name] = { url, token }
-  config.current = name
-  await writeConfig(path, config)
-
-  io.stdout(`Logged in to ${url}${context?.site ? ` (${context.site.name})` : ''} as profile "${name}".\n`)
+  const method = token === null ? 'browser sign-in' : 'access token'
+  io.stdout(`Logged in to ${url}${context?.site ? ` (${context.site.name})` : ''} as profile "${name}" (${method}).\n`)
   if (context && !context.editor.siteConnected) {
     io.stdout('The Site editor is not open yet: editing tools need it open in a browser.\n')
   }
@@ -279,16 +416,19 @@ async function cmdLogin(args: ParsedArgs, io: CliIo): Promise<number> {
 
 async function cmdLogout(args: ParsedArgs, io: CliIo): Promise<number> {
   const path = configPath(io.env)
-  const config = await readConfig(path)
-  const name = selectedProfileName(stringFlag(args, 'profile'), io.env, config)
-  if (!config.profiles[name]) {
-    io.stderr(`No saved profile "${name}".\n`)
+  const removed = await updateConfig(path, (config) => {
+    const name = selectedProfileName(stringFlag(args, 'profile'), io.env, config)
+    const profile = config.profiles[name]
+    if (!profile) return { name, kind: null }
+    delete config.profiles[name]
+    if (config.current === name) delete config.current
+    return { name, kind: 'token' in profile ? 'token' : 'sign-in' }
+  })
+  if (!removed.kind) {
+    io.stderr(`No saved profile "${removed.name}".\n`)
     return EXIT.usage
   }
-  delete config.profiles[name]
-  if (config.current === name) delete config.current
-  await writeConfig(path, config)
-  io.stdout(`Removed profile "${name}". Revoke its token in Instatic under AI → MCP if it is no longer needed.\n`)
+  io.stdout(`Removed profile "${removed.name}". Its ${removed.kind} stays valid on the server: revoke it in Instatic under AI → MCP if it is no longer needed.\n`)
   return EXIT.ok
 }
 
@@ -300,15 +440,23 @@ async function cmdProfiles(args: ParsedArgs, io: CliIo): Promise<number> {
     const name = args.positionals[2]
     if (!name) throw new UsageError('Usage: instatic profiles use <name>')
     if (!config.profiles[name]) throw new UsageError(`No saved profile "${name}".`)
-    config.current = name
-    await writeConfig(path, config)
+    await updateConfig(path, (latest) => {
+      if (!latest.profiles[name]) throw new UsageError(`No saved profile "${name}".`)
+      latest.current = name
+    })
     io.stdout(`Now using profile "${name}" (${config.profiles[name].url}).\n`)
     return EXIT.ok
   }
 
   const names = Object.keys(config.profiles).sort()
+  const authOf = (name: string) => ('token' in config.profiles[name] ? 'token' : 'oauth')
   if (booleanFlag(args, 'json')) {
-    printJson(io, names.map((name) => ({ name, url: config.profiles[name].url, current: name === config.current })))
+    printJson(io, names.map((name) => ({
+      name,
+      url: config.profiles[name].url,
+      auth: authOf(name),
+      current: name === config.current,
+    })))
     return EXIT.ok
   }
   if (names.length === 0) {
@@ -316,7 +464,7 @@ async function cmdProfiles(args: ParsedArgs, io: CliIo): Promise<number> {
     return EXIT.ok
   }
   for (const name of names) {
-    io.stdout(`${name === config.current ? '*' : ' '} ${name}  ${config.profiles[name].url}\n`)
+    io.stdout(`${name === config.current ? '*' : ' '} ${name}  ${config.profiles[name].url}  (${authOf(name)})\n`)
   }
   return EXIT.ok
 }
@@ -373,7 +521,12 @@ async function cmdTools(args: ParsedArgs, io: CliIo): Promise<number> {
       return EXIT.ok
     }
     if (booleanFlag(args, 'json')) {
-      printJson(io, tools.map((tool) => ({ name: tool.name, description: tool.description ?? '' })))
+      const withSchemas = booleanFlag(args, 'schemas')
+      printJson(io, tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description ?? '',
+        ...(withSchemas ? { inputSchema: tool.inputSchema } : {}),
+      })))
       return EXIT.ok
     }
     const width = Math.max(...tools.map((tool) => tool.name.length))
@@ -389,7 +542,88 @@ async function cmdCall(args: ParsedArgs, io: CliIo): Promise<number> {
   const name = args.positionals[1]
   if (!name) throw new UsageError('Usage: instatic call <tool> [<json> | --input <file> | -]')
   const input = await readToolInput(args, io)
-  return withSession(args, io, async (session) => emitToolResult(io, args, await session.callTool(name, input)))
+  const timeoutMs = callTimeoutMs(args)
+  return withSession(args, io, async (session) =>
+    emitToolResult(io, args, await session.callTool(name, input, { timeoutMs })))
+}
+
+interface BatchStep {
+  tool: string
+  args: Record<string, unknown>
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function parseBatchStep(value: unknown, position: string): BatchStep {
+  if (!isRecord(value) || typeof value.tool !== 'string' || !value.tool) {
+    throw new UsageError(`${position}: each step must be {"tool": "<name>", "args": {…}}.`)
+  }
+  if (value.args !== undefined && !isRecord(value.args)) {
+    throw new UsageError(`${position}: "args" must be a JSON object.`)
+  }
+  return { tool: value.tool, args: value.args ?? {} }
+}
+
+/** A JSON array of steps, or one JSON object per line. */
+export function parseBatch(raw: string): BatchStep[] {
+  const trimmed = raw.trim()
+  if (!trimmed) throw new UsageError('The batch is empty.')
+  if (trimmed.startsWith('[')) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(trimmed)
+    } catch {
+      throw new UsageError('The batch is not valid JSON.')
+    }
+    if (!Array.isArray(parsed)) throw new UsageError('The batch must be a JSON array of steps.')
+    return parsed.map((step, index) => parseBatchStep(step, `Step ${index}`))
+  }
+  return trimmed.split(/\r?\n/).flatMap((line, index) => {
+    if (!line.trim()) return []
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(line)
+    } catch {
+      throw new UsageError(`Line ${index + 1} is not valid JSON.`)
+    }
+    return [parseBatchStep(parsed, `Line ${index + 1}`)]
+  })
+}
+
+/** The result payload as a value: parsed JSON when the text is JSON. */
+function resultValue(result: ToolCallResult): unknown {
+  const text = resultText(result)
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+async function cmdBatch(args: ParsedArgs, io: CliIo): Promise<number> {
+  const source = args.positionals[1] ?? stringFlag(args, 'input') ?? '-'
+  const steps = parseBatch(source === '-' ? await io.readStdin() : await readFile(source, 'utf8'))
+  const keepGoing = booleanFlag(args, 'keep-going')
+  const imagesDir = stringFlag(args, 'images-dir')
+  const timeoutMs = callTimeoutMs(args)
+
+  return withSession(args, io, async (session) => {
+    let firstFailure: number = EXIT.ok
+    for (const [index, step] of steps.entries()) {
+      const result = await session.callTool(step.tool, step.args, { timeoutMs })
+      const images = imagesDir ? await saveImages(result, imagesDir, `step-${index}-image-`) : []
+      const line = result.isError
+        ? { index, tool: step.tool, ok: false, error: resultText(result), editorNotOpen: result.workspaceNotConnected }
+        : { index, tool: step.tool, ok: true, result: resultValue(result), ...(images.length ? { images } : {}) }
+      io.stdout(`${JSON.stringify(line)}\n`)
+      if (!result.isError) continue
+      if (firstFailure === EXIT.ok) firstFailure = resultExitCode(result)
+      if (!keepGoing) break
+    }
+    return firstFailure
+  })
 }
 
 async function cmdPublish(args: ParsedArgs, io: CliIo): Promise<number> {
@@ -446,8 +680,7 @@ async function cmdWaitEditor(args: ParsedArgs, io: CliIo): Promise<number> {
 }
 
 async function cmdMcp(args: ParsedArgs, io: CliIo): Promise<number> {
-  const config = await readConfig(configPath(io.env))
-  const connection = resolveConnection(globalConnectionFlags(args), io.env, config)
+  const connection = await resolve(args, io)
   await runStdioProxy(connection, { clientVersion: CLI_VERSION, fetch: io.fetch, log: io.stderr })
   return EXIT.ok
 }
@@ -460,6 +693,7 @@ const COMMANDS: Record<string, (args: ParsedArgs, io: CliIo) => Promise<number>>
   guide: cmdGuide,
   tools: cmdTools,
   call: cmdCall,
+  batch: cmdBatch,
   publish: cmdPublish,
   upload: cmdUpload,
   'wait-editor': cmdWaitEditor,
@@ -486,8 +720,9 @@ export async function runCli(io: CliIo): Promise<number> {
     return EXIT.ok
   }
   const command = args.positionals[0]
-  if (!command || booleanFlag(args, 'help') || command === 'help') {
-    io.stdout(`${HELP}\n`)
+  const helpTopic = command === 'help' ? args.positionals[1] : booleanFlag(args, 'help') ? command : undefined
+  if (!command || command === 'help' || booleanFlag(args, 'help')) {
+    io.stdout(`${(helpTopic && COMMAND_HELP[helpTopic]) || HELP}\n`)
     return EXIT.ok
   }
   const run = COMMANDS[command]
diff --git a/packages/cli/src/config.ts b/packages/cli/src/config.ts
index 051e237a3..6ec701344 100644
--- a/packages/cli/src/config.ts
+++ b/packages/cli/src/config.ts
@@ -3,24 +3,53 @@
  *
  * One JSON file (`$INSTATIC_CONFIG`, else `$XDG_CONFIG_HOME/instatic/config.json`,
  * else `~/.config/instatic/config.json`) holds named profiles — one per site —
- * and the current one. It stores personal access tokens, so it is written with
- * owner-only permissions.
+ * and the current one. A profile signs in either with a personal access token
+ * or with OAuth (browser sign-in; the access token is refreshed automatically).
+ * It holds credentials, so it is written with owner-only permissions.
+ *
+ * Several `instatic` processes may share the file (an agent running calls in
+ * parallel next to a long-lived `instatic mcp`), so every write goes through
+ * `updateConfig`: a lock file serializes writers, and the new content replaces
+ * the old with an atomic rename, so a reader never sees a half-written file.
  *
  * Resolution for every command, highest priority first: `--url` / `--token`
  * flags, then `INSTATIC_URL` / `INSTATIC_TOKEN`, then the selected profile
  * (`--profile`, `INSTATIC_PROFILE`, or the saved current one).
  */
-import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { chmod, mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { Type, type Static } from '@sinclair/typebox'
 import { Value } from '@sinclair/typebox/value'
 import { UsageError } from './args'
 
-const ProfileSchema = Type.Object({
+const TokenProfileSchema = Type.Object({
   url: Type.String({ minLength: 1 }),
   token: Type.String({ minLength: 1 }),
 })
+
+const OAuthSessionSchema = Type.Object({
+  /** Authorization server (the site's issuer) the tokens come from. */
+  authorizationServerUrl: Type.String({ minLength: 1 }),
+  /** The exact MCP resource the tokens are bound to. */
+  resource: Type.String({ minLength: 1 }),
+  /** Where refresh requests go (from the server's RFC 8414 metadata). */
+  tokenEndpoint: Type.String({ minLength: 1 }),
+  clientId: Type.String({ minLength: 1 }),
+  accessToken: Type.String({ minLength: 1 }),
+  refreshToken: Type.Optional(Type.String({ minLength: 1 })),
+  /** Epoch milliseconds when the access token expires. */
+  expiresAt: Type.Number(),
+  scope: Type.Optional(Type.String()),
+})
+export type OAuthSession = Static<typeof OAuthSessionSchema>
+
+const OAuthProfileSchema = Type.Object({
+  url: Type.String({ minLength: 1 }),
+  oauth: OAuthSessionSchema,
+})
+
+const ProfileSchema = Type.Union([TokenProfileSchema, OAuthProfileSchema])
 export type Profile = Static<typeof ProfileSchema>
 
 const ConfigFileSchema = Type.Object({
@@ -60,11 +89,65 @@ export async function readConfig(path: string): Promise<ConfigFile> {
   return parsed
 }
 
-export async function writeConfig(path: string, config: ConfigFile): Promise<void> {
+/** Replace the config file atomically. Callers hold the lock (see `updateConfig`). */
+export async function writeConfigFile(path: string, config: ConfigFile): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`
+  await writeFile(temp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
+  // `mode` only applies when a file is created (and is advisory on Windows,
+  // where the user-profile directory's ACL protects the file instead).
+  await chmod(temp, 0o600)
+  await rename(temp, path)
+}
+
+/** A lock older than this is from a crashed process; refreshes time out well before. */
+const LOCK_STALE_MS = 120_000
+const LOCK_WAIT_MS = 60_000
+const LOCK_POLL_MS = 50
+
+/** Run `fn` while holding the config file's lock (one writer at a time across processes). */
+export async function withConfigLock<T>(path: string, fn: () => Promise<T>): Promise<T> {
   await mkdir(dirname(path), { recursive: true, mode: 0o700 })
-  await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
-  // `mode` only applies when the file is created; tighten an existing one too.
-  await chmod(path, 0o600)
+  const lockPath = `${path}.lock`
+  const deadline = Date.now() + LOCK_WAIT_MS
+  for (;;) {
+    try {
+      const handle = await open(lockPath, 'wx', 0o600)
+      await handle.writeFile(String(process.pid))
+      await handle.close()
+      break
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err
+      const age = await stat(lockPath).then((info) => Date.now() - info.mtimeMs, () => 0)
+      if (age > LOCK_STALE_MS) {
+        await rm(lockPath, { force: true })
+        continue
+      }
+      if (Date.now() > deadline) {
+        throw new Error(`Timed out waiting for ${lockPath}. If no other instatic command is running, delete it.`, { cause: err })
+      }
+      await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS))
+    }
+  }
+  try {
+    return await fn()
+  } finally {
+    await rm(lockPath, { force: true })
+  }
+}
+
+/**
+ * Read, change, and write the config under the lock. `mutate` receives the
+ * latest content on disk, so concurrent processes never overwrite each
+ * other's changes.
+ */
+export async function updateConfig<T>(path: string, mutate: (config: ConfigFile) => Promise<T> | T): Promise<T> {
+  return withConfigLock(path, async () => {
+    const config = await readConfig(path)
+    const result = await mutate(config)
+    await writeConfigFile(path, config)
+    return result
+  })
 }
 
 /**
@@ -103,9 +186,14 @@ export function selectedProfileName(flagProfile: string | undefined, env: Env, c
   return flagProfile ?? env.INSTATIC_PROFILE ?? config.current ?? DEFAULT_PROFILE
 }
 
+/** How a command authenticates. OAuth credentials live in the profile and are refreshed in place. */
+export type ConnectionAuth =
+  | { kind: 'token'; token: string }
+  | { kind: 'oauth'; configPath: string; profile: string }
+
 export interface ResolvedConnection {
   url: string
-  token: string
+  auth: ConnectionAuth
   /** Profile the values came from, when any did. */
   profile: string | null
 }
@@ -114,6 +202,7 @@ export function resolveConnection(
   flags: { url?: string; token?: string; profile?: string },
   env: Env,
   config: ConfigFile,
+  path: string,
 ): ResolvedConnection {
   const name = selectedProfileName(flags.profile, env, config)
   const saved = config.profiles[name]
@@ -121,12 +210,20 @@ export function resolveConnection(
     throw new UsageError(`No saved profile "${flags.profile}". Run: instatic login --profile ${flags.profile} --url <site>`)
   }
   const url = flags.url ?? env.INSTATIC_URL ?? saved?.url
-  const token = flags.token ?? env.INSTATIC_TOKEN ?? saved?.token
-  if (!url || !token) {
+  const token = flags.token ?? env.INSTATIC_TOKEN
+  if (url && token) return { url: normalizeSiteUrl(url), auth: { kind: 'token', token }, profile: null }
+  if (!url || !saved) {
     throw new UsageError(
-      'Not logged in. Run: instatic login --url <site> (create a token in Instatic under AI → MCP), ' +
-        'or set INSTATIC_URL and INSTATIC_TOKEN.',
+      'Not logged in. Run: instatic login --url <site> (signs in through the browser), ' +
+        'or set INSTATIC_URL and INSTATIC_TOKEN (a token from Instatic → AI → MCP).',
     )
   }
-  return { url: normalizeSiteUrl(url), token, profile: saved ? name : null }
+  const siteUrl = normalizeSiteUrl(url)
+  if (siteUrl !== normalizeSiteUrl(saved.url)) {
+    throw new UsageError(`Profile "${name}" is for ${saved.url}, not ${siteUrl}. Pass a token or run instatic login --url ${siteUrl}.`)
+  }
+  const auth: ConnectionAuth = 'token' in saved
+    ? { kind: 'token', token: saved.token }
+    : { kind: 'oauth', configPath: path, profile: name }
+  return { url: siteUrl, auth, profile: name }
 }
diff --git a/packages/cli/src/connection.ts b/packages/cli/src/connection.ts
index 1e825d655..fe90879d7 100644
--- a/packages/cli/src/connection.ts
+++ b/packages/cli/src/connection.ts
@@ -23,25 +23,15 @@ import {
   type Tool,
 } from '@modelcontextprotocol/client'
 import { mcpEndpoint, type ResolvedConnection } from './config'
+import { createCredentials, type Credentials } from './credentials'
+import { ConnectionError } from './errors'
 
 const PROTOCOL_VERSION = '2026-07-28'
 /** Above the server's 15 s workspace wait + 90 s per-call editor limit. */
-const TOOL_CALL_TIMEOUT_MS = 150_000
+export const TOOL_CALL_TIMEOUT_MS = 150_000
 const READ_TIMEOUT_MS = 30_000
 const RETRY_DELAYS_MS = [500, 1500]
 
-export type FailureKind = 'auth' | 'unreachable' | 'server'
-
-export class ConnectionError extends Error {
-  readonly kind: FailureKind
-
-  constructor(kind: FailureKind, message: string, options?: { cause?: unknown }) {
-    super(message, options)
-    this.name = 'ConnectionError'
-    this.kind = kind
-  }
-}
-
 /** Codes meaning the TCP connection was never established — nothing was sent. */
 const NEVER_SENT_CODES = new Set(['ECONNREFUSED', 'ConnectionRefused', 'ENOTFOUND', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT'])
 const NETWORK_CODES = new Set([
@@ -104,15 +94,17 @@ function neverSent(err: unknown): boolean {
 }
 
 /** Turn any SDK / network failure into a `ConnectionError` with a next step. */
-export function classifyFailure(err: unknown, siteUrl: string): ConnectionError {
-  if (err instanceof ConnectionError) return err
+export function classifyFailure(
+  err: unknown,
+  siteUrl: string,
+  rejectedMessage = `${siteUrl} rejected the access token. Run instatic login.`,
+): ConnectionError {
+  // Credentials raise their own classified errors from inside the SDK's fetch.
+  const classified = errorChain(err).find((link) => link instanceof ConnectionError)
+  if (classified) return classified as ConnectionError
   const status = httpStatus(err)
   if (err instanceof UnauthorizedError || status === 401 || status === 403) {
-    return new ConnectionError(
-      'auth',
-      `${siteUrl} rejected the access token. It may be expired or revoked: create a new one in Instatic under AI → MCP, then run instatic login.`,
-      { cause: err },
-    )
+    return new ConnectionError('auth', rejectedMessage, { cause: err })
   }
   if ((status !== null && GATEWAY_STATUSES.has(status)) || isNetworkFailure(err)) {
     return new ConnectionError(
@@ -142,6 +134,32 @@ async function withRetry<T>(run: () => Promise<T>, retryable: (err: unknown) =>
 export interface ToolCallResult {
   isError: boolean
   content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>
+  /** The tool needs the Site editor / Content workspace and none was open. */
+  workspaceNotConnected: boolean
+  _meta?: Record<string, unknown>
+}
+
+/** Server marker on "no workspace connected" results (server/ai/mcp/server.ts). */
+const WORKSPACE_NOT_CONNECTED = 'workspace_not_connected'
+
+/**
+ * `fetch` that sends the current bearer token, and after a 401 renews the
+ * credentials once and re-sends. A 401 means the server refused the request
+ * before running anything, so re-sending is always safe.
+ */
+function authorizedFetch(base: FetchLike, credentials: Credentials): FetchLike {
+  return async (input, init) => {
+    const send = (token: string) => {
+      const headers = new Headers(init?.headers)
+      headers.set('Authorization', `Bearer ${token}`)
+      return base(input, { ...init, headers })
+    }
+    const token = await credentials.bearer()
+    const response = await send(token)
+    if (response.status !== 401 || !(await credentials.renew(token))) return response
+    await response.body?.cancel().catch(() => {})
+    return send(await credentials.bearer())
+  }
 }
 
 export interface SessionOptions {
@@ -153,23 +171,25 @@ export interface SessionOptions {
 export class InstaticSession {
   readonly siteUrl: string
   private readonly client: Client
+  private readonly rejectedMessage: string
 
-  private constructor(siteUrl: string, client: Client) {
+  private constructor(siteUrl: string, client: Client, rejectedMessage: string) {
     this.siteUrl = siteUrl
     this.client = client
+    this.rejectedMessage = rejectedMessage
   }
 
   static async open(connection: ResolvedConnection, options: SessionOptions): Promise<InstaticSession> {
+    const credentials = createCredentials(connection.auth, { fetch: options.fetch })
+    const rejectedMessage = credentials.rejectedMessage(connection.url)
+    const fetchFn = authorizedFetch(options.fetch ?? fetch, credentials)
     // A transport starts once, so every attempt builds a fresh client.
     const attempt = async (): Promise<Client> => {
       const client = new Client(
         { name: 'instatic-cli', version: options.clientVersion },
         { versionNegotiation: { mode: { pin: PROTOCOL_VERSION } } },
       )
-      const transport = new StreamableHTTPClientTransport(mcpEndpoint(connection.url), {
-        requestInit: { headers: { Authorization: `Bearer ${connection.token}` } },
-        fetch: options.fetch,
-      })
+      const transport = new StreamableHTTPClientTransport(mcpEndpoint(connection.url), { fetch: fetchFn })
       try {
         await client.connect(transport, { timeout: READ_TIMEOUT_MS })
         return client
@@ -179,9 +199,9 @@ export class InstaticSession {
       }
     }
     try {
-      return new InstaticSession(connection.url, await withRetry(attempt, isTransient))
+      return new InstaticSession(connection.url, await withRetry(attempt, isTransient), rejectedMessage)
     } catch (err) {
-      throw classifyFailure(err, connection.url)
+      throw classifyFailure(err, connection.url, rejectedMessage)
     }
   }
 
@@ -202,20 +222,35 @@ export class InstaticSession {
       )
       return tools
     } catch (err) {
-      throw classifyFailure(err, this.siteUrl)
+      throw classifyFailure(err, this.siteUrl, this.rejectedMessage)
     }
   }
 
-  async callTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult> {
+  async callTool(
+    name: string,
+    args: Record<string, unknown>,
+    options: { timeoutMs?: number } = {},
+  ): Promise<ToolCallResult> {
     try {
       const result = await withRetry(
-        () => this.client.callTool({ name, arguments: args }, { timeout: TOOL_CALL_TIMEOUT_MS }),
+        () => this.client.callTool(
+          { name, arguments: args },
+          { timeout: options.timeoutMs ?? TOOL_CALL_TIMEOUT_MS },
+        ),
         neverSent,
       )
       const content = Array.isArray(result.content) ? (result.content as ToolCallResult['content']) : []
-      return { isError: result.isError === true, content }
+      const meta = typeof result._meta === 'object' && result._meta !== null
+        ? (result._meta as Record<string, unknown>)
+        : undefined
+      return {
+        isError: result.isError === true,
+        content,
+        workspaceNotConnected: result.isError === true && meta?.['instatic/error'] === WORKSPACE_NOT_CONNECTED,
+        ...(meta ? { _meta: meta } : {}),
+      }
     } catch (err) {
-      throw classifyFailure(err, this.siteUrl)
+      throw classifyFailure(err, this.siteUrl, this.rejectedMessage)
     }
   }
 
diff --git a/packages/cli/src/credentials.ts b/packages/cli/src/credentials.ts
new file mode 100644
index 000000000..9deedfdb5
--- /dev/null
+++ b/packages/cli/src/credentials.ts
@@ -0,0 +1,190 @@
+/**
+ * The bearer token for each request.
+ *
+ * A personal access token is used as is. An OAuth profile holds a one-hour
+ * access token plus a refresh token, and the server treats a refresh token
+ * presented twice as stolen: it revokes the whole sign-in. Several CLI
+ * processes can share one profile, so refreshing follows one protocol:
+ *
+ *   1. read the profile from disk on every request (never trust a copy held
+ *      in memory — another process may have rotated the tokens since);
+ *   2. refresh only while holding the config lock, and only after re-reading
+ *      the profile inside the lock: if another process already refreshed,
+ *      use its tokens instead of refreshing again.
+ *
+ * Refresh happens ahead of expiry, and once more after a 401 in case the
+ * server revoked the access token early.
+ */
+import type { FetchLike } from '@modelcontextprotocol/client'
+import { Type } from '@sinclair/typebox'
+import { Value } from '@sinclair/typebox/value'
+import {
+  readConfig,
+  updateConfig,
+  withConfigLock,
+  writeConfigFile,
+  type ConnectionAuth,
+  type OAuthSession,
+  type Profile,
+} from './config'
+import { ConnectionError } from './errors'
+
+/** Refresh when the access token has less than this left. */
+const REFRESH_MARGIN_MS = 60_000
+/** Well under the config lock's stale threshold, so a lock is never stolen mid-refresh. */
+const REFRESH_TIMEOUT_MS = 30_000
+
+export interface Credentials {
+  /** The token for the next request, refreshed first when it is about to expire. */
+  bearer(): Promise<string>
+  /**
+   * The server rejected `rejected`. Returns true when a different token is now
+   * available to retry with.
+   */
+  renew(rejected: string): Promise<boolean>
+  /** What to tell the user when the server keeps rejecting the credentials. */
+  rejectedMessage(siteUrl: string): string
+}
+
+export function createCredentials(auth: ConnectionAuth, options: { fetch?: FetchLike } = {}): Credentials {
+  if (auth.kind === 'token') {
+    return {
+      bearer: async () => auth.token,
+      renew: async () => false,
+      rejectedMessage: (siteUrl) =>
+        `${siteUrl} rejected the access token. It may be expired or revoked: create a new one in Instatic under AI → MCP, or run instatic login --url ${siteUrl} to sign in through the browser.`,
+    }
+  }
+  return new OAuthCredentials(auth.configPath, auth.profile, options.fetch)
+}
+
+function oauthSessionOf(profile: Profile | undefined, name: string): OAuthSession {
+  if (!profile || !('oauth' in profile)) {
+    throw new ConnectionError('auth', `Profile "${name}" is no longer signed in. Run instatic login.`)
+  }
+  return profile.oauth
+}
+
+function needsRefresh(session: OAuthSession, now: number): boolean {
+  return session.expiresAt - now < REFRESH_MARGIN_MS
+}
+
+class OAuthCredentials implements Credentials {
+  private readonly configPath: string
+  private readonly profile: string
+  private readonly fetchFn: FetchLike | undefined
+
+  constructor(configPath: string, profile: string, fetchFn: FetchLike | undefined) {
+    this.configPath = configPath
+    this.profile = profile
+    this.fetchFn = fetchFn
+  }
+
+  private async current(): Promise<OAuthSession> {
+    const config = await readConfig(this.configPath)
+    return oauthSessionOf(config.profiles[this.profile], this.profile)
+  }
+
+  async bearer(): Promise<string> {
+    const session = await this.current()
+    if (!needsRefresh(session, Date.now())) return session.accessToken
+    return (await this.refresh(null)).accessToken
+  }
+
+  async renew(rejected: string): Promise<boolean> {
+    const session = await this.refresh(rejected)
+    return session.accessToken !== rejected
+  }
+
+  rejectedMessage(siteUrl: string): string {
+    return `${siteUrl} no longer accepts this sign-in (it expired or was revoked in AI → MCP). Run: instatic login --url ${siteUrl}`
+  }
+
+  /**
+   * Refresh under the lock. `rejected` is an access token the server just
+   * refused: refresh even if it has not expired yet — unless the profile on
+   * disk already holds a different one.
+   */
+  private async refresh(rejected: string | null): Promise<OAuthSession> {
+    return withConfigLock(this.configPath, async () => {
+      const config = await readConfig(this.configPath)
+      const session = oauthSessionOf(config.profiles[this.profile], this.profile)
+      const stillGood = rejected === null
+        ? !needsRefresh(session, Date.now())
+        : session.accessToken !== rejected
+      if (stillGood) return session
+      if (!session.refreshToken) {
+        throw new ConnectionError('auth', `The sign-in for profile "${this.profile}" expired. Run instatic login.`)
+      }
+
+      const tokens = await requestRefresh(session, this.profile, this.fetchFn ?? fetch)
+
+      const next: OAuthSession = {
+        ...session,
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token ?? session.refreshToken,
+        expiresAt: Date.now() + (tokens.expires_in ?? 3600) * 1000,
+        ...(tokens.scope ? { scope: tokens.scope } : {}),
+      }
+      // Already inside the lock: write directly rather than re-entering it.
+      config.profiles[this.profile] = { url: config.profiles[this.profile]!.url, oauth: next }
+      await writeConfigFile(this.configPath, config)
+      return next
+    })
+  }
+}
+
+const TokenResponseSchema = Type.Object({
+  access_token: Type.String({ minLength: 1 }),
+  refresh_token: Type.Optional(Type.String({ minLength: 1 })),
+  expires_in: Type.Optional(Type.Number()),
+  scope: Type.Optional(Type.String()),
+})
+
+const TokenErrorSchema = Type.Object({ error: Type.String() })
+
+/** One refresh-token grant against the site's token endpoint (public client, RFC 6749 §6 + RFC 8707). */
+async function requestRefresh(session: OAuthSession, profile: string, fetchFn: FetchLike) {
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: session.refreshToken ?? '',
+    client_id: session.clientId,
+    resource: session.resource,
+  })
+  let response: Response
+  try {
+    response = await fetchFn(session.tokenEndpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+      body,
+      signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS),
+    })
+  } catch (err) {
+    throw new ConnectionError('unreachable', `Could not reach ${session.tokenEndpoint} to refresh the sign-in.`, { cause: err })
+  }
+  const json: unknown = await response.json().catch(() => null)
+  if (response.ok && Value.Check(TokenResponseSchema, json)) return json
+  // The token we sent is the latest on disk (we hold the lock), so a rejected
+  // grant means the sign-in itself is gone, not that another process won a race.
+  if (Value.Check(TokenErrorSchema, json) && json.error === 'invalid_grant') {
+    throw new ConnectionError('auth', `The sign-in for profile "${profile}" expired or was revoked. Run instatic login.`)
+  }
+  if (response.status >= 502 && response.status <= 504) {
+    throw new ConnectionError('unreachable', `Could not reach ${session.tokenEndpoint} to refresh the sign-in.`)
+  }
+  const reason = Value.Check(TokenErrorSchema, json) ? json.error : `HTTP ${response.status}`
+  throw new ConnectionError('server', `Refreshing the sign-in failed (${reason}).`)
+}
+
+/** Save a freshly signed-in OAuth session as profile `name` and make it current. */
+export async function saveOAuthProfile(
+  configPath: string,
+  name: string,
+  url: string,
+  session: OAuthSession,
+): Promise<void> {
+  await updateConfig(configPath, (config) => {
+    config.profiles[name] = { url, oauth: session }
+    config.current = name
+  })
+}
diff --git a/packages/cli/src/errors.ts b/packages/cli/src/errors.ts
new file mode 100644
index 000000000..7b99345ab
--- /dev/null
+++ b/packages/cli/src/errors.ts
@@ -0,0 +1,12 @@
+/** A failure talking to the site, classified so callers can map it to an exit code. */
+export type FailureKind = 'auth' | 'unreachable' | 'server'
+
+export class ConnectionError extends Error {
+  readonly kind: FailureKind
+
+  constructor(kind: FailureKind, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'ConnectionError'
+    this.kind = kind
+  }
+}
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 83a1413bc..b3d297399 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -2,6 +2,7 @@
 /**
  * `instatic` executable: wires the real process into `runCli`.
  */
+import { spawn } from 'node:child_process'
 import { createInterface } from 'node:readline'
 import { runCli } from './cli'
 
@@ -26,6 +27,33 @@ function promptSecret(question: string): Promise<string> {
   })
 }
 
+/**
+ * Open `url` in the default browser. Never through a shell: the URL is one
+ * argv entry, so characters like & or " cannot change the command.
+ */
+function openBrowser(url: string): Promise<boolean> {
+  const command = process.platform === 'darwin'
+    ? { file: 'open', args: [url] }
+    : process.platform === 'win32'
+      ? { file: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', url] }
+      : { file: 'xdg-open', args: [url] }
+  // Linux without a display (SSH, containers): nothing to open a browser on.
+  if (
+    command.file === 'xdg-open' &&
+    !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY && !process.env.WSL_DISTRO_NAME
+  ) {
+    return Promise.resolve(false)
+  }
+  return new Promise((resolve) => {
+    const child = spawn(command.file, command.args, { stdio: 'ignore', detached: true, shell: false })
+    child.once('error', () => resolve(false))
+    child.once('spawn', () => {
+      child.unref()
+      resolve(true)
+    })
+  })
+}
+
 const code = await runCli({
   argv: process.argv.slice(2),
   env: process.env,
@@ -34,5 +62,6 @@ const code = await runCli({
   readStdin,
   stdinIsTty: Boolean(process.stdin.isTTY),
   promptSecret,
+  openBrowser,
 })
 process.exitCode = code
diff --git a/packages/cli/src/oauthLogin.ts b/packages/cli/src/oauthLogin.ts
new file mode 100644
index 000000000..a2e555cd9
--- /dev/null
+++ b/packages/cli/src/oauthLogin.ts
@@ -0,0 +1,206 @@
+/**
+ * `instatic login` through the browser (OAuth 2.1 authorization code + PKCE).
+ *
+ * The site is its own authorization server. The CLI:
+ *
+ *   1. discovers it from the MCP endpoint (RFC 9728 → RFC 8414) and takes the
+ *      `resource` from the site's own metadata, so a URL typed differently
+ *      from the site's public address (www vs bare domain) is caught up front
+ *      instead of failing at the token exchange;
+ *   2. listens on 127.0.0.1 for the redirect and registers itself as a public
+ *      client with that loopback callback (dynamic client registration);
+ *   3. opens the consent page; the user approves in the Instatic admin;
+ *   4. checks `state` (constant-time) and `iss` (RFC 9207, inside the SDK's
+ *      code exchange), then trades the code for tokens.
+ *
+ * Nothing secret is printed: the authorize URL carries only the PKCE challenge.
+ */
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { hostname } from 'node:os'
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import {
+  discoverOAuthServerInfo,
+  exchangeAuthorization,
+  registerClient,
+  startAuthorization,
+  type FetchLike,
+} from '@modelcontextprotocol/client'
+import { mcpEndpoint, type OAuthSession } from './config'
+import { UsageError } from './args'
+import { ConnectionError } from './errors'
+
+const SCOPE = 'mcp offline_access'
+/** Long enough to sign in and pass a step-up prompt on the consent page. */
+export const LOGIN_TIMEOUT_MS = 10 * 60_000
+
+export interface OAuthLoginOptions {
+  fetch?: FetchLike
+  /** Open the consent page. Returns false when no browser could be started. */
+  openBrowser?: (url: string) => Promise<boolean>
+  log: (text: string) => void
+  /** Fixed loopback port (for SSH port forwarding); 0 picks a free one. */
+  port?: number
+  timeoutMs?: number
+}
+
+/** The callback page the browser lands on. Plain text; nothing from the query is echoed. */
+function finish(res: ServerResponse, status: number, message: string): void {
+  res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store' })
+  res.end(`${message}\n`)
+}
+
+function sameSecret(a: string, b: string): boolean {
+  const left = Buffer.from(a)
+  const right = Buffer.from(b)
+  return left.length === right.length && timingSafeEqual(left, right)
+}
+
+interface CallbackResult {
+  code: string
+  iss?: string
+}
+
+interface LoopbackListener {
+  redirectUrl: string
+  /** Resolves with the first callback that carries the expected `state`. */
+  result: Promise<CallbackResult>
+  close: () => void
+}
+
+async function listenForCallback(state: string, port: number, timeoutMs: number): Promise<LoopbackListener> {
+  // Not Promise.withResolvers: the package supports Node 20.
+  let resolveResult!: (value: CallbackResult) => void
+  let rejectResult!: (reason: unknown) => void
+  const result = new Promise<CallbackResult>((resolve, reject) => {
+    resolveResult = resolve
+    rejectResult = reject
+  })
+  // A timeout can fire before anyone awaits `result`; that is not unhandled.
+  result.catch(() => {})
+  const outcome = { resolve: resolveResult, reject: rejectResult }
+  const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+    const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+    if (req.method !== 'GET' || url.pathname !== '/callback') return finish(res, 404, 'Not found.')
+    const returnedState = url.searchParams.get('state') ?? ''
+    // Anything without our state is not the redirect we started: ignore it
+    // without revealing why, and keep waiting for the real one.
+    if (!sameSecret(returnedState, state)) return finish(res, 400, 'This sign-in link is not for the waiting instatic command.')
+    const error = url.searchParams.get('error')
+    if (error) {
+      finish(res, 200, 'Sign-in was cancelled. You can close this tab.')
+      const reason = error === 'access_denied' ? 'Sign-in was denied in the browser.' : `Sign-in failed (${error}).`
+      outcome.reject(new ConnectionError('auth', reason))
+      return
+    }
+    const code = url.searchParams.get('code')
+    if (!code) return finish(res, 400, 'The sign-in response had no authorization code.')
+    finish(res, 200, 'Signed in to Instatic. You can close this tab and return to the terminal.')
+    const iss = url.searchParams.get('iss')
+    outcome.resolve({ code, ...(iss ? { iss } : {}) })
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', (err: NodeJS.ErrnoException) => {
+      reject(err.code === 'EADDRINUSE'
+        ? new UsageError(`Port ${port} is already in use. Pick another with --port.`)
+        : err)
+    })
+    server.listen(port, '127.0.0.1', () => resolve())
+  })
+  const { port: bound } = server.address() as AddressInfo
+  const timer = setTimeout(() => {
+    outcome.reject(new ConnectionError('auth', `Timed out after ${Math.round(timeoutMs / 60_000)} minutes waiting for the browser sign-in.`))
+  }, timeoutMs)
+  const close = () => {
+    clearTimeout(timer)
+    server.close()
+    server.closeAllConnections?.()
+  }
+  return { redirectUrl: `http://127.0.0.1:${bound}/callback`, result, close }
+}
+
+/** Run the browser sign-in for `siteUrl` and return the session to save. */
+export async function oauthLogin(siteUrl: string, options: OAuthLoginOptions): Promise<OAuthSession> {
+  const fetchFn = options.fetch
+  const serverUrl = mcpEndpoint(siteUrl)
+
+  let info
+  try {
+    info = await discoverOAuthServerInfo(serverUrl, { fetchFn })
+  } catch (err) {
+    throw new ConnectionError('server', `Could not start the browser sign-in for ${siteUrl}: ${(err as Error).message}`, { cause: err })
+  }
+  const metadata = info.authorizationServerMetadata
+  const advertised = info.resourceMetadata?.resource
+  if (!metadata || !advertised) {
+    throw new ConnectionError(
+      'server',
+      `${siteUrl} does not offer browser sign-in (the server needs PUBLIC_ORIGIN configured). ` +
+        'Use a token instead: instatic login --url <site> --with-token',
+    )
+  }
+  const resource = new URL(advertised)
+  if (resource.href !== serverUrl.href) {
+    throw new UsageError(
+      `${siteUrl} says its public address is ${resource.origin}. Run: instatic login --url ${resource.origin}`,
+    )
+  }
+
+  const state = randomBytes(32).toString('base64url')
+  const timeoutMs = options.timeoutMs ?? LOGIN_TIMEOUT_MS
+  const listener = await listenForCallback(state, options.port ?? 0, timeoutMs)
+  try {
+    const clientInformation = await registerClient(info.authorizationServerUrl, {
+      metadata,
+      clientMetadata: {
+        client_name: `instatic CLI (${hostname()})`,
+        redirect_uris: [listener.redirectUrl],
+        grant_types: ['authorization_code', 'refresh_token'],
+        response_types: ['code'],
+        token_endpoint_auth_method: 'none',
+        scope: SCOPE,
+      },
+      fetchFn,
+    })
+    const { authorizationUrl, codeVerifier } = await startAuthorization(info.authorizationServerUrl, {
+      metadata,
+      clientInformation,
+      redirectUrl: listener.redirectUrl,
+      scope: SCOPE,
+      state,
+      resource,
+    })
+
+    const opened = options.openBrowser ? await options.openBrowser(authorizationUrl.href) : false
+    options.log(
+      opened
+        ? `Opened your browser to approve access. If it did not open, visit:\n  ${authorizationUrl.href}\n`
+        : `Open this URL in a browser on this machine to approve access:\n  ${authorizationUrl.href}\n`,
+    )
+    options.log('Waiting for you to approve in the browser…\n')
+
+    const callback = await listener.result
+    const tokens = await exchangeAuthorization(info.authorizationServerUrl, {
+      metadata,
+      clientInformation,
+      authorizationCode: callback.code,
+      ...(callback.iss ? { iss: callback.iss } : {}),
+      codeVerifier,
+      redirectUri: listener.redirectUrl,
+      resource,
+      fetchFn,
+    })
+    return {
+      authorizationServerUrl: info.authorizationServerUrl,
+      resource: resource.href,
+      tokenEndpoint: metadata.token_endpoint,
+      clientId: clientInformation.client_id,
+      accessToken: tokens.access_token,
+      ...(tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {}),
+      expiresAt: Date.now() + (tokens.expires_in ?? 3600) * 1000,
+      ...(tokens.scope ? { scope: tokens.scope } : {}),
+    }
+  } finally {
+    listener.close()
+  }
+}
diff --git a/packages/cli/src/stdioProxy.ts b/packages/cli/src/stdioProxy.ts
index 0b681240c..a0bf66bc2 100644
--- a/packages/cli/src/stdioProxy.ts
+++ b/packages/cli/src/stdioProxy.ts
@@ -13,7 +13,8 @@ import { Server, type CallToolResult } from '@modelcontextprotocol/server'
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'
 import type { FetchLike } from '@modelcontextprotocol/client'
 import type { ResolvedConnection } from './config'
-import { ConnectionError, InstaticSession } from './connection'
+import { InstaticSession } from './connection'
+import { ConnectionError } from './errors'
 
 export interface ProxyOptions {
   clientVersion: string
@@ -92,7 +93,11 @@ export async function createProxyServer(
       const session = await remote.get()
       const result = await session.callTool(name, args ?? {})
       return server.projectCallToolResult(
-        { isError: result.isError, content: result.content as CallToolResult['content'] },
+        {
+          isError: result.isError,
+          content: result.content as CallToolResult['content'],
+          ...(result._meta ? { _meta: result._meta } : {}),
+        },
         undefined,
       )
     } catch (err) {

From f44599a82ecdb86fd1a20760e1b8fbe3da817647 Mon Sep 17 00:00:00 2001
From: Flying Web Solutions <flyingweb.ie@gmail.com>
Date: Tue, 3 Nov 2026 13:11:38 +0000
Subject: [PATCH 5/6] =?UTF-8?q?=F0=9F=94=A7=20chore(cli):=20publish=20as?=
 =?UTF-8?q?=20@flyingwebie/instatic?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

npm rejects the unscoped name as too similar to the existing ecstatic
package. The command stays `instatic`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/features/cli.md      | 4 ++--
 packages/cli/README.md    | 8 +++++---
 packages/cli/package.json | 2 +-
 3 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/features/cli.md b/docs/features/cli.md
index 217e42634..aed7b7167 100644
--- a/docs/features/cli.md
+++ b/docs/features/cli.md
@@ -2,7 +2,7 @@
 
 > Unofficial: published from this fork, not by the Instatic project. The npm README (`packages/cli/README.md`) says so at the top, and so does `instatic --help`.
 
-A command-line client for an Instatic site, published to npm as `instatic` and run with `npx instatic` or `bunx instatic`. It lets a person in a terminal, or an AI agent that works through a shell, use the same tools MCP clients get: inspect the site, run editing tools in the open editor, upload media, and publish. `instatic mcp` also runs it as a local stdio MCP server for desktop clients.
+A command-line client for an Instatic site, published to npm as `@flyingwebie/instatic` (npm refuses the unscoped `instatic` as too close to the existing `ecstatic` package) and run with `npx @flyingwebie/instatic` or `bunx @flyingwebie/instatic`; a global install (`npm install -g @flyingwebie/instatic`) provides the plain `instatic` command. It lets a person in a terminal, or an AI agent that works through a shell, use the same tools MCP clients get: inspect the site, run editing tools in the open editor, upload media, and publish. `instatic mcp` also runs it as a local stdio MCP server for desktop clients.
 
 The CLI is a thin client of the [MCP endpoint](mcp-connectors.md). It holds no editing logic and no second protocol: every command is an authenticated MCP request to `/_instatic/mcp`, so capability checks, the editor bridge, and drafts-until-publish all behave exactly as they do for any MCP client. Anything an agent needs that the tools cannot do belongs in a new MCP tool on the server, so every client gets it, not in CLI-only logic.
 
@@ -95,7 +95,7 @@ The server rotates refresh tokens and treats a reused one as stolen, revoking th
 
 ```text
 packages/cli/
-  package.json        name "instatic", bin "instatic" → dist/instatic.js, Node >= 20
+  package.json        name "@flyingwebie/instatic", bin "instatic" → dist/instatic.js, Node >= 20
   tsconfig.json       own strict project, referenced from the root tsconfig (tsc -b)
   README.md           npm package page
   src/index.ts        executable: wires process streams, hidden token prompt, browser opener
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 42bddb500..60e4e286f 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -5,10 +5,12 @@
 Command-line client for Instatic sites. Drive the visual editor, upload media, and publish from a terminal, or let an AI agent do it.
 
 ```sh
-npx instatic login --url https://your-site.com
-# or: bunx instatic login --url https://your-site.com
+npx @flyingwebie/instatic login --url https://your-site.com
+# or: bunx @flyingwebie/instatic login --url https://your-site.com
 ```
 
+To get a plain `instatic` command, install it globally: `npm install -g @flyingwebie/instatic`. The examples below assume that; with `npx`, write `npx @flyingwebie/instatic …` instead of `instatic …`.
+
 `login` opens your browser on the site's consent page. Approve access there; you need to be an Instatic admin. The CLI keeps the sign-in fresh by itself for 90 days. Browser sign-in needs `PUBLIC_ORIGIN` set on the server.
 
 To use an access token instead (Instatic → **AI → MCP → Create access token**):
@@ -72,7 +74,7 @@ Every tool runs through `instatic call <tool>` or `instatic batch`. `publish` an
   "mcpServers": {
     "instatic": {
       "command": "npx",
-      "args": ["-y", "instatic", "mcp"]
+      "args": ["-y", "@flyingwebie/instatic", "mcp"]
     }
   }
 }
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 1e415eaac..d3badd56c 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "instatic",
+  "name": "@flyingwebie/instatic",
   "version": "0.1.0",
   "description": "Unofficial command-line client for Instatic sites: drive the visual editor, publish, and upload media from a terminal or an AI agent. Not affiliated with the Instatic project.",
   "license": "MIT",

From 1654934d6501bc6645636f94cd7560fac8a5960b Mon Sep 17 00:00:00 2001
From: Flying Web Solutions <flyingweb.ie@gmail.com>
Date: Tue, 3 Nov 2026 13:14:39 +0000
Subject: [PATCH 6/6] =?UTF-8?q?=F0=9F=94=96=20chore(cli):=20release=20@fly?=
 =?UTF-8?q?ingwebie/instatic=200.1.1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Republish so the npm package page picks up the README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/cli/README.md    | 4 +++-
 packages/cli/package.json | 2 +-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/cli/README.md b/packages/cli/README.md
index 60e4e286f..0dabe3ebb 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -1,4 +1,6 @@
-# instatic
+# @flyingwebie/instatic
+
+The `instatic` command-line client for [Instatic](https://github.com/CoreBunch/Instatic) sites.
 
 > **Unofficial.** This CLI is a community project. It is **not** made, endorsed, or supported by the [Instatic](https://github.com/CoreBunch/Instatic) project or its maintainers. Please report problems with it to [this fork](https://github.com/flyingwebie/Instatic), not upstream.
 
diff --git a/packages/cli/package.json b/packages/cli/package.json
index d3badd56c..717310807 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@flyingwebie/instatic",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Unofficial command-line client for Instatic sites: drive the visual editor, publish, and upload media from a terminal or an AI agent. Not affiliated with the Instatic project.",
   "license": "MIT",
   "type": "module",