@agent-native/core 0.121.2 → 0.122.0

package/src/server/auth.ts

@@ -81,7 +81,7 @@ import {
 } from "../mcp/route-paths.js";
 import { readBody } from "../server/h3-helpers.js";
 import { putSetting } from "../settings/store.js";
-import { DEFAULT_SSR_CACHE_HEADERS } from "../shared/cache-control.js";
+import { resolveSsrCacheHeaders } from "../shared/cache-control.js";
 import { extractOAuthStateAppId } from "../shared/oauth-state.js";
 import {
   AGENT_NATIVE_SOCIAL_IMAGE_ALT,
@@ -1658,8 +1658,9 @@ function loginHtmlResponse(loginHtml: string, event: H3Event): Response {
         // template roots do not invoke origin just to render anonymous login UI.
         // The login markup is env-INDEPENDENT (a Google-only app always renders
         // a working button); the analytics script is public build configuration,
-        // not user/session state. Never downgrade this to private/no-store.
-        ...DEFAULT_SSR_CACHE_HEADERS,
+        // not user/session state. Never vary this per request — the
+        // deployment-wide override inside the resolver is the only knob.
+        ...resolveSsrCacheHeaders(),
         "X-Robots-Tag": "noindex, nofollow",
       },
     },

package/src/server/builder-browser.ts

@@ -1630,8 +1630,16 @@ export async function runBuilderAgent(
       "Builder project ID is not configured. Set DISPATCH_BUILDER_PROJECT_ID, BUILDER_BRANCH_PROJECT_ID, or BUILDER_PROJECT_ID.",
     );
   }
-  const builderUserId = args.userId || creds.userId || undefined;
-  const builderUserEmail = builderUserId ? undefined : args.userEmail;
+  // The requesting user's email must win over any stored BUILDER_USER_ID.
+  // The connect flow always persists BUILDER_USER_ID, so preferring it here
+  // attributed every branch to whoever connected the credential — at org scope
+  // that is the admin, not the person who asked. Builder resolves userEmail
+  // against Space membership, so fall back to the credential's user id when
+  // there is no session email or the email is not a member.
+  const requestedEmail = args.userEmail?.trim() || undefined;
+  const fallbackUserId = args.userId || creds.userId || undefined;
+  const builderUserEmail = requestedEmail;
+  const builderUserId = requestedEmail ? undefined : fallbackUserId;
   if (!builderUserEmail && !builderUserId) {
     throw new Error("userEmail or userId is required");
   }
@@ -1639,27 +1647,47 @@ export async function runBuilderAgent(
   const url = new URL("/agents/run", getBuilderApiHost());
   url.searchParams.set("apiKey", creds.publicKey);
 
-  const body: Record<string, unknown> = {
-    userMessage: { userPrompt: args.prompt },
-    projectId,
+  const postRun = async (actor: { userEmail?: string; userId?: string }) => {
+    const body: Record<string, unknown> = {
+      userMessage: { userPrompt: args.prompt },
+      projectId,
+    };
+    if (args.branchName) body.branchName = args.branchName;
+    if (actor.userEmail) body.userEmail = actor.userEmail;
+    if (actor.userId) body.userId = actor.userId;
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${creds.privateKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+    const parsed = (await response.json().catch(() => ({}))) as Record<
+      string,
+      unknown
+    >;
+    return { response, parsed };
   };
-  if (args.branchName) body.branchName = args.branchName;
-  if (builderUserEmail) body.userEmail = builderUserEmail;
-  if (builderUserId) body.userId = builderUserId;
 
-  const response = await fetch(url, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${creds.privateKey}`,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(body),
+  let { response, parsed } = await postRun({
+    userEmail: builderUserEmail,
+    userId: builderUserId,
   });
 
-  const parsed = (await response.json().catch(() => ({}))) as Record<
-    string,
-    unknown
-  >;
+  // Builder rejects an email that is not a member of the Space (403/404). Retry
+  // once as the connected credential's user so a non-member still gets a branch,
+  // rather than losing the run entirely.
+  if (
+    !response.ok &&
+    (response.status === 403 || response.status === 404) &&
+    builderUserEmail &&
+    fallbackUserId
+  ) {
+    ({ response, parsed } = await postRun({ userId: fallbackUserId }));
+  }
+
   if (!response.ok) {
     const msg =
       typeof parsed.error === "string"

package/src/server/core-routes-plugin.ts

@@ -86,8 +86,8 @@ import {
   deleteUserSetting,
 } from "../settings/user-settings.js";
 import {
-  DEFAULT_SSR_CACHE_HEADERS,
   EMPTY_SPECULATION_RULES,
+  resolveSsrCacheHeaders,
 } from "../shared/cache-control.js";
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
 import { llmConnectionTrackingProperties } from "../shared/llm-connection.js";
@@ -1614,7 +1614,7 @@ export function createCoreRoutesPlugin(
             "application/speculationrules+json; charset=utf-8",
           );
           for (const [name, value] of Object.entries(
-            DEFAULT_SSR_CACHE_HEADERS,
+            resolveSsrCacheHeaders(),
           )) {
             setResponseHeader(event, name, value);
           }

package/src/server/credential-provider.ts

@@ -288,6 +288,23 @@ async function readBuilderCredentialScope(
   };
 }
 
+/**
+ * A transient org_members read failure makes getOrgContext report no org, which
+ * would otherwise hide an org-scoped Builder connection behind a permanent-
+ * sounding "not configured" error. resolveOrgIdForEmail honors an explicit
+ * Personal selection, so this cannot promote a user into an org they left.
+ */
+async function resolveOrgIdForRequestEmail(
+  email: string,
+): Promise<string | null> {
+  try {
+    const { resolveOrgIdForEmail } = await import("../org/context.js");
+    return await resolveOrgIdForEmail(email);
+  } catch {
+    return null;
+  }
+}
+
 async function resolveScopedBuilderCredential(
   key: string,
 ): Promise<{ value: string; source: "user" | "org" | "workspace" } | null> {
@@ -317,12 +334,20 @@ async function resolveScopedBuilderCredential(
       return { value: userSecret.value, source: "user" };
     }
 
+    let orgId: string | null | undefined = getRequestOrgId();
+    let orgSource: "request" | "email-fallback" | "none" = orgId
+      ? "request"
+      : "none";
+    if (!orgId) {
+      orgId = await resolveOrgIdForRequestEmail(email);
+      if (orgId) orgSource = "email-fallback";
+    }
+
     // 2. Per-org shared credential: when one teammate connects Builder
     //    as an owner/admin we write the OAuth result at org scope so
     //    every member of that org gets the AI chat working without
     //    re-running the connect flow. Resolution falls back here
     //    silently — the caller never has to know which scope answered.
-    const orgId = getRequestOrgId();
     if (orgId) {
       scopeAttempted = "org";
       const orgSecret = await readAppSecret({
@@ -333,7 +358,7 @@ async function resolveScopedBuilderCredential(
       if (orgSecret) {
         if (traceLookup) {
           console.log(
-            `[builder-credential] key=${key} email=${email} orgId=${orgId} scope=org hit=true`,
+            `[builder-credential] key=${key} email=${email} orgId=${orgId} orgSource=${orgSource} scope=org hit=true`,
           );
         }
         return { value: orgSecret.value, source: "org" };
@@ -351,36 +376,40 @@ async function resolveScopedBuilderCredential(
       if (workspaceSecret) {
         if (traceLookup) {
           console.log(
-            `[builder-credential] key=${key} email=${email} orgId=${orgId} scope=workspace hit=true`,
+            `[builder-credential] key=${key} email=${email} orgId=${orgId} orgSource=${orgSource} scope=workspace hit=true`,
           );
         }
         return { value: workspaceSecret.value, source: "workspace" };
       }
       if (traceLookup) {
         console.log(
-          `[builder-credential] key=${key} email=${email} orgId=${orgId} miss tried=user,org,workspace`,
+          `[builder-credential] key=${key} email=${email} orgId=${orgId} orgSource=${orgSource} miss tried=user,org,workspace`,
         );
       }
-    } else {
-      scopeAttempted = "workspace-solo";
-      const soloWorkspaceSecret = await readAppSecret({
-        key,
-        scope: "workspace",
-        scopeId: `solo:${email}`,
-      });
-      if (soloWorkspaceSecret) {
-        if (traceLookup) {
-          console.log(
-            `[builder-credential] key=${key} email=${email} scope=workspace-solo hit=true`,
-          );
-        }
-        return { value: soloWorkspaceSecret.value, source: "workspace" };
-      }
+    }
+
+    // 3. Solo-workspace fallback: always checked, even when an org id was
+    //    found above. Older no-org connect flows wrote here, so a credential
+    //    written before the user joined/created an org must not become
+    //    unreachable once that org exists.
+    scopeAttempted = "workspace-solo";
+    const soloWorkspaceSecret = await readAppSecret({
+      key,
+      scope: "workspace",
+      scopeId: `solo:${email}`,
+    });
+    if (soloWorkspaceSecret) {
       if (traceLookup) {
         console.log(
-          `[builder-credential] key=${key} email=${email} orgId=(none) miss tried=user,workspace-solo`,
+          `[builder-credential] key=${key} email=${email} orgId=${orgId ?? "(none)"} orgSource=${orgSource} scope=workspace-solo hit=true`,
         );
       }
+      return { value: soloWorkspaceSecret.value, source: "workspace" };
+    }
+    if (traceLookup) {
+      console.log(
+        `[builder-credential] key=${key} email=${email} orgId=${orgId ?? "(none)"} orgSource=${orgSource} miss tried=${orgId ? "user,org,workspace,workspace-solo" : "user,workspace-solo"}`,
+      );
     }
   } catch (err) {
     if (traceLookup) {
@@ -393,18 +422,32 @@ async function resolveScopedBuilderCredential(
   return null;
 }
 
-async function resolveScopedBuilderCredentials(): Promise<BuilderResolvedCredentials | null> {
+interface ScopedBuilderCredentialsResult {
+  creds: BuilderResolvedCredentials | null;
+  /**
+   * True when reading the credential store itself threw (db timeout, etc),
+   * as opposed to the store answering cleanly with "no row". Callers must
+   * report this as retryable rather than "not configured".
+   */
+  lookupFailed: boolean;
+}
+
+async function resolveScopedBuilderCredentials(): Promise<ScopedBuilderCredentialsResult> {
   const email = getRequestUserEmail();
-  if (!email) return null;
+  if (!email) return { creds: null, lookupFailed: false };
 
   const traceLookup = shouldTraceCredentialResolve();
   let scopeAttempted = "user";
   try {
     const { readAppSecrets } = await import("../secrets/storage.js");
-    const traceScope = (creds: BuilderResolvedCredentials, scopeId: string) => {
+    const traceScope = (
+      creds: BuilderResolvedCredentials,
+      scopeId: string,
+      extra = "",
+    ) => {
       if (!traceLookup) return;
       console.log(
-        `[builder-credential] scope=${creds.source} scopeId=${scopeId} email=${email} complete=${isCompleteBuilderConnection(creds)} private=${Boolean(creds.privateKey)} public=${Boolean(creds.publicKey)}`,
+        `[builder-credential] scope=${creds.source} scopeId=${scopeId} email=${email}${extra} complete=${isCompleteBuilderConnection(creds)} private=${Boolean(creds.privateKey)} public=${Boolean(creds.publicKey)}`,
       );
     };
 
@@ -414,9 +457,19 @@ async function resolveScopedBuilderCredentials(): Promise<BuilderResolvedCredent
       email,
     );
     traceScope(userCreds, email);
-    if (isCompleteBuilderConnection(userCreds)) return userCreds;
+    if (isCompleteBuilderConnection(userCreds)) {
+      return { creds: userCreds, lookupFailed: false };
+    }
+
+    let orgId: string | null | undefined = getRequestOrgId();
+    let orgSource: "request" | "email-fallback" | "none" = orgId
+      ? "request"
+      : "none";
+    if (!orgId) {
+      orgId = await resolveOrgIdForRequestEmail(email);
+      if (orgId) orgSource = "email-fallback";
+    }
 
-    const orgId = getRequestOrgId();
     if (orgId) {
       scopeAttempted = "org";
       const orgCreds = await readBuilderCredentialScope(
@@ -424,8 +477,10 @@ async function resolveScopedBuilderCredentials(): Promise<BuilderResolvedCredent
         "org",
         orgId,
       );
-      traceScope(orgCreds, orgId);
-      if (isCompleteBuilderConnection(orgCreds)) return orgCreds;
+      traceScope(orgCreds, orgId, ` orgSource=${orgSource}`);
+      if (isCompleteBuilderConnection(orgCreds)) {
+        return { creds: orgCreds, lookupFailed: false };
+      }
 
       scopeAttempted = "workspace";
       const workspaceCreds = await readBuilderCredentialScope(
@@ -433,18 +488,29 @@ async function resolveScopedBuilderCredentials(): Promise<BuilderResolvedCredent
         "workspace",
         orgId,
       );
-      traceScope(workspaceCreds, orgId);
-      if (isCompleteBuilderConnection(workspaceCreds)) return workspaceCreds;
-    } else {
-      scopeAttempted = "workspace-solo";
-      const scopeId = `solo:${email}`;
-      const workspaceCreds = await readBuilderCredentialScope(
-        readAppSecrets,
-        "workspace",
-        scopeId,
-      );
-      traceScope(workspaceCreds, scopeId);
-      if (isCompleteBuilderConnection(workspaceCreds)) return workspaceCreds;
+      traceScope(workspaceCreds, orgId, ` orgSource=${orgSource}`);
+      if (isCompleteBuilderConnection(workspaceCreds)) {
+        return { creds: workspaceCreds, lookupFailed: false };
+      }
+    }
+
+    // Solo-workspace fallback: always checked, even when an org id was found
+    // above. See resolveScopedBuilderCredential for why this must not be
+    // gated behind "no org".
+    scopeAttempted = "workspace-solo";
+    const soloScopeId = `solo:${email}`;
+    const soloCreds = await readBuilderCredentialScope(
+      readAppSecrets,
+      "workspace",
+      soloScopeId,
+    );
+    traceScope(
+      soloCreds,
+      soloScopeId,
+      ` orgId=${orgId ?? "(none)"} orgSource=${orgSource}`,
+    );
+    if (isCompleteBuilderConnection(soloCreds)) {
+      return { creds: soloCreds, lookupFailed: false };
     }
   } catch (err) {
     if (traceLookup) {
@@ -452,8 +518,9 @@ async function resolveScopedBuilderCredentials(): Promise<BuilderResolvedCredent
         `[builder-credential] email=${email} scope=${scopeAttempted} credentials error=${(err as Error)?.message ?? err}`,
       );
     }
+    return { creds: null, lookupFailed: true };
   }
-  return null;
+  return { creds: null, lookupFailed: false };
 }
 
 /**
@@ -519,20 +586,11 @@ export async function resolveHasCompleteBuilderConnection(): Promise<boolean> {
  * status UIs don't report a mixed user/org credential set as connected.
  */
 export async function resolveBuilderCredentialSource(): Promise<BuilderCredentialSource | null> {
-  const scoped = await resolveScopedBuilderCredentials();
-  if (scoped) return scoped.source;
-  return canUseBuilderDeployCredentialFallbackForRequest() &&
-    process.env.BUILDER_PRIVATE_KEY
-    ? "env"
-    : null;
+  const detailed = await resolveBuilderCredentialsDetailed();
+  return detailed.source;
 }
 
-/**
- * Resolve the Builder assistant credential bundle from one complete scope.
- * A partial user row is treated as a miss so the org-shared connection can
- * still power the assistant for teammates.
- */
-export async function resolveBuilderCredentials(): Promise<{
+export interface BuilderCredentialsDetailed {
   privateKey: string | null;
   publicKey: string | null;
   userId: string | null;
@@ -543,8 +601,27 @@ export async function resolveBuilderCredentials(): Promise<{
   subscriptionName: string | null;
   isEnterprise: boolean | null;
   isFreeAccount: boolean | null;
-}> {
-  const scoped = await resolveScopedBuilderCredentials();
+  /** Which scope answered, or null when nothing did. */
+  source: BuilderCredentialSource | null;
+  /**
+   * True when reading the credential store itself failed (db timeout, etc).
+   * Callers must report this as retryable rather than "not configured".
+   */
+  lookupFailed: boolean;
+}
+
+/**
+ * Resolve the Builder assistant credential bundle from one complete scope,
+ * plus where it came from and whether the credential-store read itself
+ * failed. A partial user row is treated as a miss so the org-shared
+ * connection can still power the assistant for teammates.
+ *
+ * Callers that only need the plain credential bundle (the historical shape)
+ * should use `resolveBuilderCredentials()` instead.
+ */
+export async function resolveBuilderCredentialsDetailed(): Promise<BuilderCredentialsDetailed> {
+  const { creds: scoped, lookupFailed } =
+    await resolveScopedBuilderCredentials();
   if (scoped) {
     const {
       privateKey,
@@ -557,6 +634,7 @@ export async function resolveBuilderCredentials(): Promise<{
       subscriptionName,
       isEnterprise,
       isFreeAccount,
+      source,
     } = scoped;
     return {
       privateKey,
@@ -569,42 +647,90 @@ export async function resolveBuilderCredentials(): Promise<{
       subscriptionName,
       isEnterprise,
       isFreeAccount,
+      source,
+      lookupFailed: false,
     };
   }
-  const privateKey = canUseBuilderDeployCredentialFallbackForRequest()
+  const canUseEnv = canUseBuilderDeployCredentialFallbackForRequest();
+  const privateKey = canUseEnv
     ? (readDeployCredentialEnv("BUILDER_PRIVATE_KEY") ?? null)
     : null;
-  const publicKey = canUseBuilderDeployCredentialFallbackForRequest()
+  const publicKey = canUseEnv
     ? (readDeployCredentialEnv("BUILDER_PUBLIC_KEY") ?? null)
     : null;
-  const userId = canUseBuilderDeployCredentialFallbackForRequest()
+  const userId = canUseEnv
     ? (readDeployCredentialEnv("BUILDER_USER_ID") ?? null)
     : null;
-  const orgName = canUseBuilderDeployCredentialFallbackForRequest()
+  const orgName = canUseEnv
     ? (readDeployCredentialEnv("BUILDER_ORG_NAME") ?? null)
     : null;
-  const orgKind = canUseBuilderDeployCredentialFallbackForRequest()
+  const orgKind = canUseEnv
     ? (readDeployCredentialEnv("BUILDER_ORG_KIND") ?? null)
     : null;
-  const subscription = canUseBuilderDeployCredentialFallbackForRequest()
+  const subscription = canUseEnv
     ? (readDeployCredentialEnv("BUILDER_SUBSCRIPTION") ?? null)
     : null;
-  const subscriptionLevel = canUseBuilderDeployCredentialFallbackForRequest()
+  const subscriptionLevel = canUseEnv
     ? (readDeployCredentialEnv("BUILDER_SUBSCRIPTION_LEVEL") ?? null)
     : null;
-  const subscriptionName = canUseBuilderDeployCredentialFallbackForRequest()
+  const subscriptionName = canUseEnv
     ? (readDeployCredentialEnv("BUILDER_SUBSCRIPTION_NAME") ?? null)
     : null;
-  const isEnterprise = canUseBuilderDeployCredentialFallbackForRequest()
+  const isEnterprise = canUseEnv
     ? readOptionalBuilderBoolean(
         readDeployCredentialEnv("BUILDER_IS_ENTERPRISE"),
       )
     : null;
-  const isFreeAccount = canUseBuilderDeployCredentialFallbackForRequest()
+  const isFreeAccount = canUseEnv
     ? readOptionalBuilderBoolean(
         readDeployCredentialEnv("BUILDER_IS_FREE_ACCOUNT"),
       )
     : null;
+  return {
+    privateKey,
+    publicKey,
+    userId,
+    orgName,
+    orgKind,
+    subscription,
+    subscriptionLevel,
+    subscriptionName,
+    isEnterprise,
+    isFreeAccount,
+    source: canUseEnv && privateKey ? "env" : null,
+    lookupFailed,
+  };
+}
+
+/**
+ * Resolve the Builder assistant credential bundle from one complete scope.
+ * Kept to its original return shape (no `source`/`lookupFailed`) for existing
+ * callers; use `resolveBuilderCredentialsDetailed()` for those fields.
+ */
+export async function resolveBuilderCredentials(): Promise<{
+  privateKey: string | null;
+  publicKey: string | null;
+  userId: string | null;
+  orgName: string | null;
+  orgKind: string | null;
+  subscription: string | null;
+  subscriptionLevel: string | null;
+  subscriptionName: string | null;
+  isEnterprise: boolean | null;
+  isFreeAccount: boolean | null;
+}> {
+  const {
+    privateKey,
+    publicKey,
+    userId,
+    orgName,
+    orgKind,
+    subscription,
+    subscriptionLevel,
+    subscriptionName,
+    isEnterprise,
+    isFreeAccount,
+  } = await resolveBuilderCredentialsDetailed();
   return {
     privateKey,
     publicKey,
@@ -620,6 +746,13 @@ export async function resolveBuilderCredentials(): Promise<{
 }
 
 const BUILDER_AUTH_FAILURE_SETTING_PREFIX = "builder-auth-failure:";
+/**
+ * Stale markers expire so a rejected model or a transient gateway failure
+ * cannot pin a signed-in user to "Builder not connected" forever. Only a
+ * successful gateway call clears the marker early, and that call never happens
+ * while the marker is what makes the connection look broken.
+ */
+export const BUILDER_AUTH_FAILURE_TTL_MS = 15 * 60 * 1000;
 
 export interface BuilderCredentialAuthFailure {
   fingerprint: string;
@@ -660,9 +793,17 @@ export async function getBuilderCredentialAuthFailure(
   );
   if (!fingerprint) return null;
   try {
-    const { getSetting } = await import("../settings/store.js");
-    const row = await getSetting(builderAuthFailureSettingKey(fingerprint));
+    const settings = await import("../settings/store.js");
+    const settingKey = builderAuthFailureSettingKey(fingerprint);
+    const row = await settings.getSetting(settingKey);
     if (!row) return null;
+    const at = typeof row.at === "number" ? row.at : Date.now();
+    if (Date.now() - at > BUILDER_AUTH_FAILURE_TTL_MS) {
+      if (typeof settings.deleteSetting === "function") {
+        await settings.deleteSetting(settingKey).catch(() => {});
+      }
+      return null;
+    }
     return {
       fingerprint,
       message:
@@ -671,7 +812,7 @@ export async function getBuilderCredentialAuthFailure(
           : "Builder rejected the connected credentials. Reconnect Builder.io.",
       status: typeof row.status === "number" ? row.status : undefined,
       code: typeof row.code === "string" ? row.code : undefined,
-      at: typeof row.at === "number" ? row.at : Date.now(),
+      at,
       ownerEmail:
         typeof row.ownerEmail === "string" ? row.ownerEmail : undefined,
       orgId: typeof row.orgId === "string" ? row.orgId : undefined,

package/src/server/index.ts

@@ -472,11 +472,14 @@ export {
   resolveHasBuilderPrivateKey,
   resolveHasCompleteBuilderConnection,
   resolveBuilderCredentials,
+  resolveBuilderCredentialsDetailed,
+  resolveBuilderCredentialSource,
   resolveBuilderCredential,
   readDeployCredentialEnv,
   writeBuilderCredentials,
   deleteBuilderCredentials,
   resolveSecret,
+  type BuilderCredentialsDetailed,
 } from "./credential-provider.js";
 export {
   builderDesignSystemUrl,

package/src/server/prompts/framework-core-compact.ts

@@ -2,7 +2,7 @@
  * Compact framework core instructions (FRAMEWORK_CORE_COMPACT).
  * Used in lazy-context mode (lazyContext: true — the default).
  *
- * Shares rules 8–10, 14–15 with the full variant via shared-rules.ts.
+ * Shares rules 8–9, 12–13 with the full variant via shared-rules.ts.
  * The compact version omits:
  *   - Verbose "Extended Capabilities" section (agent uses get-framework-context)
  *   - Detailed "Parallel Tool Calls" prose (replaced with one-liner)
@@ -17,7 +17,6 @@ import {
 import {
   sharedRule8,
   SHARED_RULE_9,
-  SHARED_RULE_10,
   SHARED_RULE_14,
   SHARED_RULE_15,
   type PromptExamples,
@@ -71,18 +70,16 @@ Bring a senior engineer's judgment, arrived at through attention not premature c
 
 1. **Data lives in SQL** — ${dataRule}
 2. **Context awareness** — The user's current screen state is in \`<current-screen>\`, current URL in \`<current-url>\`. Use both to understand what the user is looking at. To change URL state, use \`set-search-params\` or \`set-url-path\`.
-3. **Navigate the UI** — Use the \`navigate\` tool to switch views, open items, or focus elements.
+3. **Navigate the UI** — On "show me", "go to", "open", or similar, use \`navigate\` first, then fetch/display data.
 4. **Application state** — Ephemeral UI state lives in \`application_state\`. Use \`readAppState\`/\`writeAppState\`.
 5. **Screen refresh is automatic** — The framework auto-refreshes after mutating tool calls. Only call \`refresh-screen\` when you mutated data via a path the framework can't detect.
 6. **Memory** — Use \`save-memory\` proactively when you learn preferences, corrections, or project context.
 7. **Security** — ${securityRule}
 ${sharedRule8(examples, options)}
 ${SHARED_RULE_9}
-${SHARED_RULE_10}
-**Native widgets** — For table/chart/graph/report requests, prefer actions labeled \`Native chat widget\`; use \`render-data-widget\` for compact real data and let chat render it instead of markdown tables.
-11. **Verify before you claim done** — After a mutating action (create/update/delete/send/publish), confirm it actually succeeded from the tool result or the refreshed \`<current-screen>\` before reporting it done. Never report a change as complete on intent alone; if the result is ambiguous, check rather than assume.
-12. **Find tools when unsure** — Use \`tool-search\` to find the exact action/tool for a capability. It searches the live registry, including connected MCP server tools.
-13. **Relative dates use runtime context** — The \`<runtime-context>\` block gives the authoritative current date/time. Resolve "today", "yesterday", "last week", and similar phrases to explicit calendar dates before querying data or creating artifacts.
+**Native widgets** — For table/chart/graph/report requests, prefer actions labeled \`Native chat widget\`; use \`render-data-widget\` for already-summarized data (≤50 rows) instead of markdown tables. Above that, give the total plus the top rows — never retype a full result set as widget arguments.
+10. **Find tools when unsure** — Use \`tool-search\` to find the exact action/tool for a capability. It searches the live registry, including connected MCP server tools.
+11. **Relative dates use runtime context** — The \`<runtime-context>\` block gives the authoritative current date/time. Resolve "today", "yesterday", "last week", and similar phrases to explicit calendar dates before querying data or creating artifacts.
 ${SHARED_RULE_14}
 ${SHARED_RULE_15}
 
@@ -92,13 +89,9 @@ Use the \`resources\` tool for persistent notes and context files: \`action: "li
 Resources have three levels: workspace defaults inherited from Dispatch, shared organization/app overrides, and personal overrides. Use \`resources\` with \`action: "effective"\` before editing when you need to explain or inspect which level is active for a path.
 Workspace resources are user-facing by default. If you need temporary working files, write them as agent scratch (\`visibility: "agent_scratch"\`); scratch is hidden from the Workspace view by default and expires. Use \`visibility: "workspace"\` only when the user explicitly asked to save/manage that file, or for durable AGENTS.md, LEARNINGS.md, memory, skills, jobs, or custom agents.
 
-### Navigation Rule
-
-When the user says "show me", "go to", "open", etc., ALWAYS use \`navigate\` first.
-
 ### Extended Capabilities
 
-You also have tools for: inline embeds, chat history search, agent teams/sub-agents, recurring jobs, A2A cross-app calls, structured memory, live embedded browser sessions (\`list-browser-sessions\`, \`view-browser-session\`, \`run-browser-session-action\`, \`send-browser-session-command\`), and browser automation (\`activate-browser\` for Builder-provisioned Chrome; local development may also include \`set-browser-control\`). Call \`get-framework-context\` to read detailed instructions for any of these when needed — each capability's full doc lives there.
+You also have tools for inline embeds, chat history search (\`chat-history\`), recurring jobs (\`manage-jobs\`), structured memory (\`save-memory\`/\`delete-memory\`), and browser automation (\`activate-browser\` in production, \`set-browser-control\` locally). Call \`get-framework-context\` with the matching key — it lists its own topics — for full instructions when needed.
 
 **Agent teams:** default to doing the work yourself. Delegate ONE sub-agent (\`agent-teams\` action "spawn") for self-contained heavy work; fan out to several only for genuinely independent units; never parallelize tightly-coupled work; cap fan-out around 3. Treat "background agent", "sub-agent", "parallel", "batch", "kick off", "run the rest", and "queued items" as delegation intent when the user is asking you to start or continue independent work items. After \`spawn\`, say the task started/running, not completed; use \`status\`/\`read-result\` before claiming the delegated work is done. Give each sub-agent a self-contained brief (objective, the specific context/IDs it needs, output format, boundaries) — it can't see this thread — then read all results and synthesize one integrated answer. Full details: \`get-framework-context\` key \`agent-teams\`.