@overaihq/cli 0.14.12 → 0.14.13

package/README.md

@@ -170,6 +170,12 @@ overai best-practices webPages  # one guide (add a section name to narrow it)
 overai review                   # before every push
 ```
 
+Clone also writes `.overai/base/`, a pristine copy of every resource file that
+backs `diff`, `restore`, and push's stale-base check. Never edit it by hand. The
+clone writes `.overai/.gitignore` and `.overai/.ignore` so git and ripgrep-based
+agents skip the folder. If you already committed `.overai/`, run
+`git rm -r --cached .overai` once.
+
 When platform behavior blocks progress, agents can send detailed feedback with
 `overai report bug -` or `overai report feature -` and the report body on stdin.
 Reports include CLI, runtime, organization, and cloned-workspace identifiers,

package/dist/index.js

@@ -62373,13 +62373,21 @@ var pinOrgFromClone = () => {
   } catch {
   }
 };
+var IGNORE_FILES = [".ignore", ".gitignore"];
+var IGNORE_ALL = "*\n";
 var writeManifest = (root, manifest) => {
-  mkdirSync2(join3(root, MANIFEST_DIR), { recursive: true });
+  const dir = join3(root, MANIFEST_DIR);
+  mkdirSync2(dir, { recursive: true });
   writeFileSync2(
-    join3(root, MANIFEST_DIR, MANIFEST_FILE),
+    join3(dir, MANIFEST_FILE),
     `${JSON.stringify(manifest, null, 2)}
 `
   );
+  for (const name2 of IGNORE_FILES) {
+    const path = join3(dir, name2);
+    if (!existsSync2(path) || readFileSync4(path, "utf8") !== IGNORE_ALL)
+      writeFileSync2(path, IGNORE_ALL);
+  }
 };
 var basePath = (root, relPath) => join3(root, MANIFEST_DIR, BASE_DIR, relPath);
 var writeSynced = (root, relPath, content) => {
@@ -65063,7 +65071,9 @@ var workflow = `# CLI editing workflow
    step users can feel; push freely, deploy deliberately.
 
 Never edit .overai/ by hand \u2014 it holds the manifest and pristine base copies
-that make status/diff/fast-forward work.
+that make status/diff/fast-forward work. \`.overai/base/\` mirrors every
+resource file as last synced; edit the working copy, never the base. Git and
+ripgrep skip the folder through its own ignore files.
 
 A push conflict does not deploy anything. Normal push sends the manifest base
 to an atomic server check; only explicit --force omits it. Never use --force as
@@ -65553,7 +65563,7 @@ Users who prefer their own editor or an AI coding agent (Claude Code, Cursor) ca
 
 Clone includes accessible, non-archived descendants under \`workspaces/<slug>.<workspaceId>/\`, each with its own manifest and overview. Commands use the nearest workspace folder: change into a child to work there. Add \`--recursive\` to status/diff/pull/push to include the live accessible subtree; recursive pull clones new children and matches existing folders by workspace ID. Recursive push saves only and rejects --deploy; deploy/restore remain single-workspace. Conflicts or failures exit nonzero while preserving local edits and successful work. Unavailable or moved-out workspaces stay on disk and are skipped. Local file moves do not move resources between workspaces in OverAI.
 
-The loop is git-shaped: \`overai clone <workspaceId>\` writes the workspace overview to \`WORKSPACE.md\` and materializes automations, functions, web pages, printable pages, and agents as local files; \`status\`/\`diff\`/\`pull\` track local resource edits against remote drift; \`push -m "why"\` creates new versions and \`deploy\` makes them live \u2014 **pushing alone changes nothing users see**. \`overai create <type>\` creates any current resource, while \`resource show|update <id>\` handles mutable metadata. \`workspace show [workspaceId]\` reads the current overview, and \`workspace users [workspaceId]\` lists effective, direct, and inherited access; inside a clone the id is optional. Resource-specific commands invoke functions and agents, trigger automations, run SQL, append/query streams, upload/download files, configure integrations, render printable pages, and pair or use runners. \`overai review\` validates changed resources before a push, and \`overai best-practices\` serves these same doc topics, plus the CLI's own workflow guide, to the local agent.
+The loop is git-shaped: \`overai clone <workspaceId>\` writes the workspace overview to \`WORKSPACE.md\` and materializes automations, functions, web pages, printable pages, and agents as local files (\`.overai/\` holds sync state and is ignored by git); \`status\`/\`diff\`/\`pull\` track local resource edits against remote drift; \`push -m "why"\` creates new versions and \`deploy\` makes them live \u2014 **pushing alone changes nothing users see**. \`overai create <type>\` creates any current resource, while \`resource show|update <id>\` handles mutable metadata. \`workspace show [workspaceId]\` reads the current overview, and \`workspace users [workspaceId]\` lists effective, direct, and inherited access; inside a clone the id is optional. Resource-specific commands invoke functions and agents, trigger automations, run SQL, append/query streams, upload/download files, configure integrations, render printable pages, and pair or use runners. \`overai review\` validates changed resources before a push, and \`overai best-practices\` serves these same doc topics, plus the CLI's own workflow guide, to the local agent.
 
 Point users here when they ask about editing outside the browser, using a local AI coding agent, version-controlling a workspace, or scripting against the platform. Everything the CLI does is also doable in the Architect \u2014 it is an alternative surface, not a required one. Full command list: \`overai help\`; the user-facing guide is the help center article at \`/<orgId>/help/cli\`.
 `
@@ -65775,6 +65785,10 @@ Two optional JSON Schemas declare the function's contract:
 
 The deployed version's schemas type \`env.FNxxx.call()\` everywhere authors call this function: the envelope's \`body\` member types the call body, and the output schema types \`res.json()\`. Declare the output schema whenever the response shape is stable \u2014 callers get autocomplete and typo-catching lint instead of \`any\` \u2014 and keep both schemas in sync with what the code actually reads and returns. They describe the base path; a router's sub-paths are outside the declared contract.
 
+Autocomplete and deployed-schema types cover functions owned by or shared into this workspace. A manually named \`env.FNxxx\` (or \`env.fnxxx\`) outside that list has a generic call type, not the target's schema. Static unlisted references warn through \`architect/unlisted-function\`; an intentional cross-workspace call may be valid, but verify the ID and the deployed caller access against the actual caller. Do not claim access was verified without checking, change sharing or caller access just to silence the warning, or invoke a side-effecting function merely to test it. After verification, acknowledge a known reference with \`// eslint-disable-next-line architect/unlisted-function -- <verified reason>\` directly above it. Give a concrete reason; avoid casts, \`@ts-ignore\`, and blanket suppressions. Dynamic IDs are outside this static check.
+
+If the warning gives a listed function's spelling, use that spelling instead of suppressing it; different casing loses its deployed-schema types.
+
 Lint enforces the output side: when an output schema is declared, a handler whose return value doesn't match it gets a lint error (both on code edits and on schema edits). Returning the plain JSON value (the runtime wraps it in a 200 response) keeps the check active; a hand-built \`Response\` passes unchecked because its payload is invisible to the type checker. Enum values are checked as their base type (\`string\`, not the exact members), and \`null\`/missing-return code paths are not caught \u2014 verify those yourself.
 
 Callers can also name the declared shapes: the deployed schemas generate \`Env.FNxxx.Input\` (the call body) and \`Env.FNxxx.Output\` (the response) for annotating payloads and results.
@@ -66599,8 +66613,6 @@ Saves reject a stale editing base without discarding your draft. Incorporate the
 
 \`\`\`typescript
 declare global {
-  const filterData: { id: string; attributes: { id: string; attributeId: string; value: string; }[]; }[] | null;
-  const dataFile: Record<string, unknown> | null;
   const searchParams: Record<string, unknown>;
   const setSearchParam: { (key: string, value: string | null): void; (params: Record<string, string | null>): void }; // pass null to delete a param; pass an object to set/delete several in one URL update
   const navigateToPage: (webPageId: string, queryParameters?: Record<string, string>, options?: { newTab?: boolean }) => void; // { newTab: true } opens the page in a new browser tab \u2014 use it instead of hand-building URLs with window.open
@@ -66614,6 +66626,8 @@ declare global {
   /** @deprecated Use useLLMText, useLLMObject, or useLLMChat instead. */
   const llmCompletion: (message: string, systemPrompt?: string, model?: string) => Promise<Record<string, unknown>>;
   const callFunction: (functionId: string, options?: { body?: unknown; method?: string; query?: Record<string, string>; path?: string }) => Promise<Response>;
+  // Start a deployed automation. \`inputs\` maps onto its event node's declared outputs (e.g. { fileUrl } for a file-upload trigger \u2014 upload with env.STORAGE.upload first). Throws on non-2xx.
+  const startAutomation: (automationId: string, inputs?: Record<string, unknown>) => Promise<{ automationRunId: string }>;
 
   // Imperative AI functions
   // Prefer stream: false for one-shot generateText calls \u2014 errors (invalid PDF, prompt too long, rate limit) come back as HTTP errors with a friendly message instead of an empty body. Only stream when you wire onChunk for progressive UI.
@@ -66630,20 +66644,10 @@ declare global {
   const callAgentGenerateObject: (agentId: string, message: string, schema: Record<string, unknown>) => Promise<{ object: unknown; model: string; finishReason: string; usage: { promptTokens: number; completionTokens: number; totalTokens: number }; toolResults: { toolName: string; input: unknown; output: unknown; error: unknown }[] }>;
   const callAgentChat: (agentId: string, messages: { role: string; parts: { type: string; text?: string }[] }[], options?: { conversationId?: string; onChunk?: (accumulated: string) => void }) => Promise<string>;
 
-  // Agent Hook \u2014 multi-turn streaming chat with an OverAI Agent.
-  // Every turn is persisted server-side for a signed-in viewer. Pass conversationId
-  // to resume a past thread (its full transcript, tool calls included, loads on
-  // mount). Omit it to start fresh \u2014 a conversation is created on the first send and
-  // returned as conversationId. messages[].parts holds full UI parts for loaded turns;
-  // the live-streaming turn carries text only.
-  // On a PUBLIC page there is no viewer identity: chat works, but the transcript
-  // lives in the hook for the tab's life, conversationId stays null, and the
-  // conversation helpers below throw. See "Public pages" below.
+  // Agent Hook \u2014 multi-turn streaming chat with an OverAI Agent; persistence and resume are explained below the block. messages[].parts holds full UI parts for loaded turns; the live-streaming turn carries text only.
   const useAgentChat: (agentId: string, options?: { conversationId?: string }) => { messages: { id?: string; role: string; text: string; parts?: { type: string; text?: string; toolName?: string; toolCallId?: string; state?: string; input?: unknown; output?: unknown }[] }[]; sendMessage: (text: string) => void; clearMessages: () => void; loading: boolean; error: string | null; conversationId: string | null };
 
-  // Agent conversation management \u2014 list/read/manage a signed-in user's chat threads
-  // with an agent. Unavailable on public pages (no identity owns a thread):
-  // useAgentConversations returns an empty list, the rest throw.
+  // Agent conversation management \u2014 list/read/manage a signed-in user's chat threads with an agent.
   const useAgentConversations: (agentId: string) => { conversations: { id: string; title: string; updatedAt: string }[]; loading: boolean; error: string | null; refresh: () => Promise<void> };
   const listAgentConversations: (agentId: string) => Promise<{ id: string; title: string; updatedAt: string }[]>;
   const getAgentConversationMessages: (conversationId: string) => Promise<{ id?: string; role: string; text: string; parts?: { type: string; text?: string }[] }[]>;
@@ -66665,9 +66669,12 @@ declare global {
         /** Escape hatch for dynamic SQL. Caller is responsible for parameterizing. */
         unsafe: <Row = any>(query: string, params?: unknown[]) => Promise<{ rows: Row[]; rowCount: number }>;
       };
+      /** Several statements that must all land or none do. Pass lazy \`sql\` fragments; resolves to { results, executionId, durationMs } with results[i] = { rows, rowCount }. Any failure rolls everything back and throws. */
+      transaction: (statements: readonly unknown[]) => Promise<{ results: { rows: Record<string, unknown>[]; rowCount: number }[]; executionId: string; durationMs: number }>;
       /** @deprecated Use \`sql\` \u2014 it auto-parameterizes interpolated values and returns rows directly. query returns camelCased columns (sql returns snake_case); do not mix the two. */
       query: (sql: TemplateStringsArray, ...values: unknown[]) => Promise<Response>;
     };
+    [automationId: \`AT\${string}\`]: { start: (inputs?: Record<string, unknown>) => Promise<{ automationRunId: string }> };
     /** \`path\` routes to a sub-path inside the function (e.g. "/features/123") for functions that ship their own router; omit it to hit the base path. Method still defaults to POST. */
     [functionId: \`FN\${string}\`]: { call: (options?: { body?: unknown; method?: string; query?: Record<string, string>; path?: string }) => Promise<Response> };
     [agentId: \`AG\${string}\`]: { generateText: (message: string) => Promise<{ text: string; model: string; finishReason: string; usage: { promptTokens: number; completionTokens: number; totalTokens: number }; toolResults: { toolName: string; input: unknown; output: unknown; error: unknown }[] }>; generateObject: (message: string, schema: Record<string, unknown>) => Promise<{ object: unknown; model: string; finishReason: string; usage: { promptTokens: number; completionTokens: number; totalTokens: number }; toolResults: { toolName: string; input: unknown; output: unknown; error: unknown }[] }> };
@@ -66684,8 +66691,6 @@ declare global {
     };
   };
   const React: typeof import("react");
-  const useDataFile: () => Record<string, unknown> | null;
-  const useFilterData: () => { id: string; attributes: { id: string; attributeId: string; value: string; }[]; }[] | null;
   const useCurrentUser: () => { id: string; email: string; name: string; } | null;
   // useTheme re-renders on the app's light/dark toggle. The page root already carries a \`dark\` class (Tailwind darkMode: "class"), so style with \`dark:\` variants \u2014 e.g. bg-white dark:bg-slate-900 \u2014 and reach for the hook only for JS-driven styling (chart palettes, canvas, map tiles).
   // Two things a light-only page gets wrong in dark mode: a border or divide utility with no color class falls back to Tailwind's default light gray, so \`border-b\` alone stays a bright rule \u2014 pair it, e.g. border-b border-gray-200 dark:border-gray-700. And if the page loads daisyUI, its theme drives the inherited text color, so a hardcoded bg-white left to inherit turns light-on-white; give every surface a dark counterpart.
@@ -66698,19 +66703,29 @@ declare global {
   const useLocalStorageState: <T>(key: string, initialValue: T) => [T, React.Dispatch<React.SetStateAction<T>>];
   // useSessionStorageState is a useState-like hook backed by sessionStorage. Persists for the lifetime of the tab. REQUIRES noSandbox: true in the page config.
   const useSessionStorageState: <T>(key: string, initialValue: T) => [T, React.Dispatch<React.SetStateAction<T>>];
+
+  // Legacy \u2014 populated only by the deprecated dataSourceUrl / filter page settings (see "Legacy data sources" below). New pages use env instead.
+  const dataFile: Record<string, unknown> | null;
+  const useDataFile: () => Record<string, unknown> | null;
+  const filterData: { id: string; attributes: { id: string; attributeId: string; value: string; }[]; }[] | null;
+  const useFilterData: () => { id: string; attributes: { id: string; attributeId: string; value: string; }[]; }[] | null;
 }
 \`\`\`
 
-IMPORTANT: Use the hooks (useDataFile, useFilterData, useSearchParamState) instead of the global variables when you need the component to re-render when data or URL state changes. URL state belongs in search params (via useSearchParamState), not local React state, so links and reloads preserve it.
+IMPORTANT: Use useSearchParamState instead of the searchParams global when the component must re-render as the URL changes. URL state belongs in search params (via useSearchParamState), not local React state, so links and reloads preserve it.
 
 IMPORTANT: callFunction and env.FNxxx.call return a Response object (like fetch) \u2014 call .json() or .text() to get the data. Date/timestamp values come back as ISO 8601 strings (e.g., "2026-04-06T00:00:00.000Z"). When the function declares input/output schemas, env.FNxxx.call types the body and .json() from them (the deployed version's declaration) \u2014 no annotation needed.
 
+Function autocomplete and deployed-schema types cover functions owned by or shared into this workspace. A manually named \`env.FNxxx\` or \`env.fnxxx\` outside that list remains a generic call, not a typed discovery of organization functions. A static unlisted reference raises advisory \`architect/unlisted-function\`; dynamic IDs are not checked. Verify the ID and deployed caller access for the page's actual caller before using an intentional cross-workspace reference. Never claim unverified access, change sharing or authorization just to silence the warning, or invoke a side-effecting function merely to test it. Once verified, acknowledge the reference with \`// eslint-disable-next-line architect/unlisted-function -- <verified reason>\` directly above it. Prefer a concrete reason, not casts, \`@ts-ignore\`, or blanket suppression.
+
+If the warning gives a listed function's spelling, use that spelling instead of suppressing it; different casing loses its deployed-schema types.
+
 The \`env\` proxy matches the API available in Functions and Automations \u2014 the same code works in all three.
 
 For AI in React components, prefer the reactive hooks (useLLMText, useLLMObject, useLLMChat, useAgentChat) \u2014 they re-render as the response streams in. In event handlers or imperative code, call generateText/generateObject (or env.AI.*) directly.
 useAgentChat persists every turn server-side for a signed-in viewer: pass a conversationId to resume a past thread (full transcript, tool calls included, loads automatically), or omit it to start fresh and read the new thread's id off the returned conversationId. useAgentConversations(agentId) backs a history sidebar \u2014 call its refresh() after a first send so the newly created thread appears. listAgentConversations, getAgentConversationMessages, createAgentConversation, renameAgentConversation, and deleteAgentConversation are the imperative equivalents. On a public page none of that persistence exists (see Public pages) \u2014 useAgentChat still streams, holding the transcript in memory.
 All AI functions/hooks accept optional File[] attachments for images/PDFs, and webSearch: true to enable web search.
-Available models: the model ids this workspace can use. Omit \`model\` to use this workspace's default.
+Available models: read \`availableModelIds\` from the \`getWebPageContext\` data tool. Omit \`model\` to use this workspace's default.
 
 IMPORTANT: Keep generateObject / useLLMObject / agent generateObject schemas simple. Anthropic models reject schemas with more than 16 nullable or union-typed fields (this includes optional fields the AI SDK emits as \`type: [..., "null"]\`). Prefer non-nullable fields, split into multiple calls, or switch to a non-Anthropic model from the list above for larger schemas.
 
@@ -66786,25 +66801,16 @@ const { rows } = await env.TBS123.sql.unsafe(
 
 Pages render UI; they don't perform server-side actions directly. To do anything with side effects beyond table-space SQL (send email, hit a third-party API, post to Slack, etc.), call a Function or trigger an Automation. Table spaces are the exception: read AND write them directly with env.TBSxxx.sql as shown above.
 
-- **Common actions** like sending email, Slack messages, SMS, or HTTP calls are first-class Automation nodes. \`SEND_EMAIL\` and \`HTTP\` need no integration; \`SLACK_SEND_MESSAGE\` and \`TWILIO_SEND_SMS\` require their respective integration to be configured. Build a webhook-triggered automation and trigger it from the page (snippet below).
+- **Common actions** like sending email, Slack messages, SMS, or HTTP calls are first-class Automation nodes. \`SEND_EMAIL\` and \`HTTP\` need no integration; \`SLACK_SEND_MESSAGE\` and \`TWILIO_SEND_SMS\` require their respective integration to be configured. Build the automation, deploy it, and start it from the page with \`env.ATxxx.start(inputs)\` (snippet below) \u2014 never hand-build its webhook URL.
 - **Custom server logic** belongs in a Function. Call it from the page via \`callFunction('FN123', { body: {...} })\` or \`env.FN123.call({ body: {...} })\`. A Function that ships its own router serves many routes \u2014 reach one with \`path\`: \`env.FN123.call({ method: 'GET', path: '/features/123' })\`. Omit \`path\` for the base path; the method defaults to POST either way.
 - **Action runners** (\`env.ACTIONS.run\`) are server-only \u2014 not available on a page. To run an action runner action from a page, put the \`env.ACTIONS.run(...)\` call in a Function and invoke that Function from the page.
 - **Email** (\`env.EMAIL.send\`) is server-only for the same reason. Put the \`env.EMAIL.send(...)\` call in a Function and invoke that Function from the page.
 - **Integrations** are credentials/config consumed *by* automation nodes or functions \u2014 they are not available directly in the page context. Only reach for an Integration when the work requires authenticated access to a specific third-party service.
 
 \`\`\`typescript
-// Trigger a webhook-triggered automation from a page. The full webhook URL
-// is shown in the automation editor \u2014 webhook automations are unauthenticated,
-// so the URL itself is the credential.
-const response = await fetch(
-  'https://api.overai.com/v1/automation/webhook/ORG123/AT123',
-  {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ recipient: 'user@example.com' }),
-  },
-);
-const { automationRunId } = await response.json();
+// Start a deployed automation. inputs maps onto its event node's declared
+// outputs; for a file-upload trigger, upload first and pass the url.
+const { automationRunId } = await env.AT123.start({ recipient: 'user@example.com' });
 
 // To use an integration's credentials, call a Function that reads the integration config server-side.
 const config = await callFunction('FN123', { body: { integrationId: 'IN123' } });
@@ -66844,17 +66850,13 @@ Page settings (\`authorizationMode\`, \`noSandbox\`, \`hideTopBar\`, \`runtime\`
 
 \`runtime: "v2"\` serves the page from its own origin instead of the sandboxed srcdoc iframe: separate renderer process, real localStorage/sessionStorage and cookies with no noSandbox flag needed. It is versioned like every other setting \u2014 save and deploy to publish. Public (/public/:id) links always use v1 regardless of the toggle. Only v2 reaches browser devices: Web Serial, WebUSB and WebHID always work there; camera, microphone, geolocation, display-capture, fullscreen and screen-wake-lock work once listed in \`permissions\`.
 
-**\`dataSourceUrl\` and \`filter\` are legacy.** They populate the \`data\` and \`items\` globals, frozen at render start; \`filter\` reads the old item/attribute model, which builders can no longer create or manage. For new pages use \`env\` instead \u2014 \`env.TBSxxx.sql\` for tabular data, \`env.DFxxx\` for data files. That path can depend on search params, re-query on demand, and report its own errors. Don't rewrite a working page just to migrate it.
-
-\`dataSourceUrl\` is fetched **verbatim** and its response becomes the \`data\` global. It is a plain static URL, not a template:
+### Legacy data sources: \`dataSourceUrl\`, \`filter\`, \`data\`, \`items\`
 
-- It does **not** substitute search params. Neither \`{x}\` nor Liquid \`{{ x }}\` is interpolated \u2014 the URL is fetched exactly as written. (\`filter\` does support Liquid; \`dataSourceUrl\` does not.)
-- If your data depends on a search param or anything else known only at render time, don't use \`dataSourceUrl\` \u2014 fetch it in the page with \`useEffect\` + \`env\`/\`fetch\`, which is the normal path anyway.
-- To clear it, pass JSON \`null\`. The string \`"null"\` is a four-character URL, not an empty value, and it fails at fetch time.
+These populate the \`data\`/\`items\` globals once, at render start, from the old item/attribute model that builders can no longer create. New pages use \`env\` (\`env.TBSxxx.sql\`, \`env.DFxxx\`), which can depend on search params, re-query on demand and report its own errors. Don't rewrite a working page just to migrate it. If you must touch them:
 
-\`filter\`, unlike \`dataSourceUrl\`, **does** evaluate Liquid \u2014 in every string value it holds, against \`now\` (a Date rounded down to the minute, so it doesn't move mid-session) plus every search param by name. Use \`{{ now | minus: 1209600000 | toISOString }}\` for a relative date, \`{{ since }}\` for \`?since=\`. A template that won't evaluate, or that evaluates to nothing because its variable isn't on the URL, fails the whole page rather than quietly querying on an empty value.
-
-A templated filter is **not** an access boundary. On a public or portal page the visitor supplies the search params, so \`{"orgUnit": {"_eq": "{{ tenant }}"}}\` reads like tenant scoping but is editable from the URL bar. Scope with the workspace's own access, not with a filter.
+- \`dataSourceUrl\` is fetched verbatim \u2014 no \`{x}\` or Liquid interpolation. Anything that depends on a search param belongs in a page-side fetch instead. Clear it with JSON \`null\`; the string \`"null"\` is a four-character URL.
+- \`filter\` evaluates Liquid in every string value against \`now\` (rounded to the minute) and each search param by name, e.g. \`{{ now | minus: 1209600000 | toISOString }}\` or \`{{ since }}\`. A template whose variable is missing from the URL fails the whole page rather than querying on an empty value.
+- A templated filter is **not** an access boundary: on a public or portal page the visitor controls the search params, so \`{{ tenant }}\` scoping is editable from the URL bar. Scope with the workspace's own access.
 
 ## Critical Rules
 
@@ -66867,13 +66869,13 @@ A templated filter is **not** an access boundary. On a public or portal page the
    | \`useSessionStorageState(key, init)\` | Single-tab session state (wizard progress, scroll restoration) | Reload (same tab); cleared on tab close | **Requires \`noSandbox: true\`** |
    | \`useState\` | Truly ephemeral UI (hover, animation step, in-flight form field before submit) | Nothing | Lost on every navigation |
 
-   When the page uses \`useLocalStorageState\` or \`useSessionStorageState\`, set \`noSandbox: true\` in the page config first \u2014 the hooks throw a clear error otherwise.
+   When the page uses \`useLocalStorageState\` or \`useSessionStorageState\` on the default v1 runtime, set \`noSandbox: true\` in the page config first \u2014 the hooks throw a clear error otherwise. A \`runtime: "v2"\` page needs no flag.
 
 2. **DO NOT import React or hooks.** React, useState, useEffect, useRef, useMemo, useCallback, and useReducer are all globally available. Importing them will cause errors.
 3. **The main component MUST be named \`App\` and MUST NOT be exported.** Write \`function App() { ... }\` \u2014 no \`export\`.
 4. **Use Tailwind CSS for styling.** It's built in.
 5. **Import external libraries from esm.sh.** Example: \`import confetti from "https://esm.sh/canvas-confetti@1.9.3"\`. Imports must be absolute https URLs \u2014 the sandbox cannot resolve bare or relative specifiers.
-6. **Sandbox restrictions.** The page runs in a sandboxed iframe (allow-scripts only). Raw \`localStorage\`, \`sessionStorage\`, cookies, alert/confirm/prompt, and form submissions are blocked. Use \`useLocalStorageState\` / \`useSessionStorageState\` for storage (both require disabling the sandbox \u2014 see Rule 1). Set \`noSandbox: true\` in the page config to disable the sandbox when any of these are needed.
+6. **Sandbox restrictions (v1 runtime).** By default the page runs in a sandboxed iframe (allow-scripts only). Raw \`localStorage\`, \`sessionStorage\`, cookies, alert/confirm/prompt, and form submissions are blocked. Use \`useLocalStorageState\` / \`useSessionStorageState\` for storage (both require disabling the sandbox \u2014 see Rule 1). Set \`noSandbox: true\` to lift the sandbox, or \`runtime: "v2"\` (see Web Page Configuration) when the page also needs its own origin or browser devices.
 7. **Read code before editing.** Reading a large page's config returns its outline instead of the code \u2014 then read only the blocks or line ranges you are about to change. Edits return the changed lines, numbered, so don't re-read to verify. Prefer small, targeted edits \u2014 insert or search-replace \u2014 over rewriting a whole block.
 8. **Decompose large pages.** When a page exceeds ~200 lines, break it into multiple top-level function components (e.g., \`function DataTable() { ... }\` used inside \`function App() { ... }\`), so each can be read and edited on its own.
 9. **Add TSDoc comments to every top-level declaration.** Write a \`/** brief description */\` comment above each function, component, and constant. Code outlines show these comments, giving structural context without reading the full code. Always add or update these when creating or modifying a block.
@@ -66884,6 +66886,46 @@ A templated filter is **not** an access boundary. On a public or portal page the
 12. **Sanity-check chart math with console.log.** You cannot see the rendered output. When building or debugging visualizations, log intermediate values (scales, domains, ranges, computed positions, angles) and verify they make sense before saving. For example: \`console.log("gauge", { min, max, value, fraction, startAngle, endAngle, valueAngle })\`. Remove logs once the chart is working.
 13. **Rebuild imported HTML natively \u2014 never embed it.** When the user brings HTML from somewhere else (an exported dashboard, a design mockup, a page from another tool), recreate it as a native page: an \`App\` component, Tailwind, d3 for charts. Pay close attention to preserving the original styling \u2014 colors, spacing, type scale, layout. Do NOT load a foreign HTML file into a \`srcDoc\` iframe or inject it into the DOM. Embedded HTML is opaque to code outlines and reachable only by blind string patches that silently do nothing when the source drifts \u2014 so every later request turns into guesswork. Port it once and every edit after that is a normal edit. (A Liquid printable page is the exception: Liquid is HTML templating, so imported markup becomes the template body directly.)
 
+## Best Practices
+
+**Decide the page's purpose first, then design for it.** A page answers one question; several questions become tabs or separate pages. Most pages are one of three kinds, and each wants a different shape:
+
+- **Single-flow page** \u2014 one task, start to finish (submit a request, review an item, check in). Keep it simple: one column, one primary action per screen, generous spacing. Think consumer app, not admin panel.
+- **KPI dashboard** \u2014 a few measures that matter, seen from several angles (trend, breakdown, against target). Users don't want to read a number, they want to feel it: a dense, color-accented table or a chart built for the specific question beats a row of big-number tiles. Add headline tiles only when asked.
+- **Command center** \u2014 operators who live in the page and need to act fast. Information density is the point: compact rows, inline status, filters and actions within reach, no decorative whitespace.
+
+Name the kind to the user when you propose a design; if the request mixes kinds, split it rather than compromising all three.
+
+**Build a clear hierarchy.** Size is only one tool. Group related elements and separate unrelated ones with spacing, borders or dividers; order sections by importance, with the thing the user came for first; distinguish primary actions from secondary ones; mute labels and metadata so values stand out. The visible structure should mirror the data model underneath, so relationships between concepts are obvious. A reader should see what matters before reading a word.
+
+**Spend pixels on data, not decoration.** Don't repeat a label on every row or card when a column header or section title carries it. Use color sparingly and for meaning: if problems are red, tune the thresholds so only real problems are, or the signal is lost. No emojis. Add a tooltip where a value's origin or calculation isn't obvious. Disable a control the user can't use right now instead of hiding it, so the page teaches what it can do.
+
+**Choose the layout deliberately.**
+
+- A scrolling document, or a command center where panels scroll independently inside a fixed viewport? For the latter, use CSS grid over flex, fill the viewport, and don't cap the page with a top-level max-width.
+- Tables for rows the user compares; cards or grids for non-uniform items. Size each column for its content and decide which wrap and which truncate.
+- Drill in with a drawer when the surrounding context should stay visible, a large modal when the user needs focus. Make the background inert while a modal is open.
+- Decide whether the page must work on a small screen; not every page does, but check the ones that will be opened on a phone.
+- Style for both themes: the page root carries a \`dark\` class, so pair every surface and border with a \`dark:\` variant (see \`useTheme\` above).
+
+**Represent data accurately.** A page that looks right but misreports the data is worse than one that shows an error. Common failures:
+
+- **A query \`LIMIT\` is not a count.** Loading \`LIMIT 1000\` and labeling it "1000 items" misreports every larger table. Run a separate \`count(*)\` for totals, and label a truncated list as such ("Showing 1,000 of 14,212").
+- **Offer "Load more" when there is more.** Prefer a subtle "Load more" control over numbered pagination; either way the user must be able to reach every row.
+- **Dates are not timestamps \u2014 check the time zone before you format.** A \`date\` column (a calendar day, no time) arrives from \`env.TBSxxx.sql\` as a JS \`Date\` at 00:00 UTC, so \`toLocaleDateString()\` in any zone west of UTC shows the previous day. Format a day from its UTC fields (\`d.toISOString().slice(0, 10)\` or \`Intl.DateTimeFormat(undefined, { timeZone: "UTC", dateStyle: "medium" })\`), and never pass it through local-time math. A \`timestamptz\` is a real instant: format it in the viewer's zone and show the zone (\`timeZoneName: "short"\`) when readers may be in different places. A \`timestamp\` without zone is ambiguous \u2014 ask which zone it was written in rather than guessing. Function responses carry dates as ISO strings; the same rules apply after \`new Date(iso)\`. Day-boundary filters (\`today\`, \`this week\`) must be computed in the business's zone, in SQL via \`AT TIME ZONE\`, not in the browser's. Tell the user which columns are days and which are instants, and label the zone in the UI.
+- **Never fall back to a value that hides a data problem.** \`?? 0\`, \`?? "N/A"\`, \`?? []\` make a broken query or a missing column look like a legitimate result. Show an explicit empty or error state, and when a value is unexpectedly null, surface it (a dash, an "unknown" badge) rather than inventing a default.
+
+**Embed PDFs with \`<object>\` on a v2 page.** When \`runtime: "v2"\`, render a PDF with \`<object data={url} type="application/pdf" />\` rather than an \`<iframe>\`.
+
+**Link stored files through the app host.** Storage URLs are persisted as \`https://api.<host>/v1/storage/...\`, where the browser holds no session. Before rendering one as a link, embed or download, rewrite it to the app origin's proxy, \`https://app.<host>/api/v1/storage/...\`:
+
+\`\`\`typescript
+const browserStorageUrl = (url: string) =>
+  url.replace(/^https:\\/\\/api\\.([^/]+)\\/v1\\/storage\\//, "https://app.$1/api/v1/storage/");
+\`\`\`
+
+The edge also redirects a credential-less api.* read there, so an unrewritten link degrades to an extra hop rather than failing. The proxy authenticates with the signed-in session cookie, so it works for workspace members only. On a public page the visitor has no session: use \`presignFile\` for links there. Page code calling \`fetchFile\`, \`env.STORAGE.fetch\` or \`presignFile\` is unaffected either way \u2014 those carry their own credentials.
+
 ## Known-Good Libraries
 
 These libraries are tested and work from \`https://esm.sh/...\`. Do NOT import React \u2014 it's already global.
@@ -66893,10 +66935,15 @@ These libraries are tested and work from \`https://esm.sh/...\`. Do NOT import R
 - **date-fns** \u2014 \`import { format, parseISO } from "https://esm.sh/date-fns@4"\` \u2014 Date formatting and manipulation.
 - **papaparse** \u2014 \`import Papa from "https://esm.sh/papaparse@5"\` \u2014 CSV parsing.
 
-### Do NOT use these libraries (broken ESM imports):
+### Do NOT use libraries that depend on React
+
+An esm.sh build of a React library imports its own React (\`import "/react@>=16.8"\`), a second copy beside the page's global one, so every hook inside it fails with "Invalid hook call". The page has no import map to redirect that specifier, so there is no workaround. This rules out, among others:
+
 - **react-resize-detector** \u2014 Use a \`ResizeObserver\` hook instead (see pattern below).
 - **@tanstack/react-table** \u2014 Build tables with plain \`<table>\` + Tailwind + \`useState\` for sorting/filtering/pagination.
-- **recharts, visx** \u2014 Use d3 directly instead.
+- **recharts, visx, and any other React chart or component kit** \u2014 Use d3 directly instead.
+
+React-free libraries (d3, date-fns, papaparse) import fine.
 
 ### Responsive chart pattern
 
@@ -67727,7 +67774,8 @@ Usage:
   overai sql credential rotate|revoke <credentialId>
 
 Workspace sync (edit resources as local files):
-  overai clone <workspaceId> [dir]     Clone workspace and accessible descendants
+  overai clone <workspaceId> [dir]     Clone workspace and accessible descendants;
+                                       .overai/ holds sync state, ignored by git
   overai status [--recursive]          Local edits + remote drift
   overai diff [filter] [--from <ref>] [--to <ref>] [--recursive]
                                        Diff versions (refs: N, base, local, deployed, latest;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overaihq/cli",
-  "version": "0.14.12",
+  "version": "0.14.13",
   "description": "Create, edit, deploy, and run OverAI workspace resources from the command line",
   "type": "module",
   "homepage": "https://overai.com",