@agent-native/core 0.169.1 → 0.170.0

package/corpus/templates/forms/server/lib/public-form-ssr.ts

@@ -5,6 +5,7 @@ import {
   AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT,
   AGENT_NATIVE_SOCIAL_IMAGE_TYPE,
   AGENT_NATIVE_SOCIAL_IMAGE_WIDTH,
+  SSR_QUERY_CACHE_KEY_HEADER,
   withAgentNativeSocialImageCacheBuster,
 } from "@agent-native/core/shared";
 import { eq } from "drizzle-orm";
@@ -321,6 +322,7 @@ export async function renderPublicForm(event: H3Event) {
     // short-fresh/long-SWR policy as React Router SSR. Keep all cache headers
     // here; relying on provider config would make templates perform differently.
     Object.assign(headers, resolveSsrCacheHeaders());
+    headers[SSR_QUERY_CACHE_KEY_HEADER] = "query";
   }
   return new Response(getMethod(event) === "HEAD" ? null : html, {
     status,
@@ -472,7 +474,15 @@ function renderFormPage(
 
   function revalidateFormVersion() {
     fetch(PUBLIC_FORM_API, { cache: "no-store" })
-      .then(function(response) { return response.ok ? response.json() : null; })
+      .then(function(response) {
+        if (response.status === 404) {
+          var currentUrl = new URL(window.location.href);
+          currentUrl.searchParams.set("v", String(Date.now()));
+          window.location.replace(currentUrl.toString());
+          return null;
+        }
+        return response.ok ? response.json() : null;
+      })
       .then(function(latest) {
         if (!latest || typeof latest.updatedAt !== "string" || !latest.updatedAt || latest.updatedAt === FORM_VERSION) return;
         var currentUrl = new URL(window.location.href);

package/corpus/templates/forms/vitest.config.ts

@@ -22,6 +22,7 @@ export default mergeConfig(
         "**/node_modules/**",
         "**/.git/**",
         "**/dist/**",
+        "**/.react-router/**",
         "shared/types.public-settings.spec.ts",
         "server/lib/submission-validation.spec.ts",
       ],

package/corpus/templates/macros/.agents/skills/secrets/SKILL.md

@@ -19,10 +19,17 @@ data, and generated extension/app content may mention credential **names** such
 as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
 signing secrets, OAuth refresh tokens, or private Builder/customer data.
 
-Secret values are supplied at runtime through deployment configuration, the
-encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
-`${keys.NAME}` substitution. Examples must use obvious placeholders such as
-`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+Provider secret values are supplied at runtime through the encrypted
+`app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Deployment configuration is reserved for
+deploy-level secrets and non-provider configuration. Examples must use obvious
+placeholders such as `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not
+real-looking copied values.
+
+Provider credentials and provider account identifiers are workspace data. Use
+standard workspace connections and org/workspace vault scopes; never put them
+in `.env` or deployment environment variables, and never add a provider-specific
+action or startup bootstrap just to write a credential for one organization.
 
 ## Credential Modeling Preflight
 

package/corpus/templates/macros/app/routes.ts

@@ -1,3 +1,5 @@
 import type { RouteConfig } from "@react-router/dev/routes";
 import { flatRoutes } from "@react-router/fs-routes";
-export default flatRoutes() satisfies RouteConfig;
+export default flatRoutes({
+  ignoredRouteFiles: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
+}) satisfies RouteConfig;

package/corpus/templates/macros/vitest.config.ts

@@ -14,7 +14,12 @@ export default mergeConfig(
     },
     test: {
       include: ["**/*.{test,spec}.?(c|m)[jt]s?(x)"],
-      exclude: ["**/node_modules/**", "**/.git/**", "**/dist/**"],
+      exclude: [
+        "**/node_modules/**",
+        "**/.git/**",
+        "**/dist/**",
+        "**/.react-router/**",
+      ],
     },
   }),
 );

package/corpus/templates/mail/.agents/skills/secrets/SKILL.md

@@ -19,10 +19,17 @@ data, and generated extension/app content may mention credential **names** such
 as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
 signing secrets, OAuth refresh tokens, or private Builder/customer data.
 
-Secret values are supplied at runtime through deployment configuration, the
-encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
-`${keys.NAME}` substitution. Examples must use obvious placeholders such as
-`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+Provider secret values are supplied at runtime through the encrypted
+`app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Deployment configuration is reserved for
+deploy-level secrets and non-provider configuration. Examples must use obvious
+placeholders such as `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not
+real-looking copied values.
+
+Provider credentials and provider account identifiers are workspace data. Use
+standard workspace connections and org/workspace vault scopes; never put them
+in `.env` or deployment environment variables, and never add a provider-specific
+action or startup bootstrap just to write a credential for one organization.
 
 ## Credential Modeling Preflight
 

package/corpus/templates/mail/actions/manage-gmail-filters.ts

@@ -1,4 +1,4 @@
-import { defineAction } from "@agent-native/core";
+import { ActionContractError, defineAction } from "@agent-native/core";
 import { writeAppState } from "@agent-native/core/application-state";
 import { z } from "zod";
 
@@ -499,7 +499,15 @@ function accountLabel(account: ConnectedAccount) {
 async function allAccounts(): Promise<ConnectedAccount[]> {
   const accounts = await getAccessTokens();
   if (accounts.length === 0) {
-    throw new Error("No Google account connected. Connect Gmail first.");
+    // A plain Error has no statusCode, so action-routes.ts can't tell this
+    // deterministic, caller-correctable precondition apart from a real server
+    // fault — it collapses to a 500 and the specific message never reaches
+    // the UI. ActionContractError carries an explicit sub-500 statusCode the
+    // route treats as user-facing and echoes as-is.
+    throw new ActionContractError(
+      "No Google account connected. Connect Gmail first.",
+      { errorCode: "GOOGLE_ACCOUNT_NOT_CONNECTED", statusCode: 400 },
+    );
   }
   return accounts;
 }

package/corpus/templates/mail/app/components/GoogleConnectBanner.tsx

@@ -4,6 +4,7 @@ import {
   oauthRedirectUri,
 } from "@agent-native/core/client/host";
 import { useT } from "@agent-native/core/client/i18n";
+import { startWorkspaceProviderOAuth } from "@agent-native/core/client/integrations";
 import {
   IconMail,
   IconX,
@@ -25,6 +26,7 @@ import {
   useGoogleAddAccountUrl,
   useDisconnectGoogle,
 } from "@/hooks/use-google-auth";
+import { shouldOfferGoogleOAuthSetup } from "@/lib/google-oauth-setup";
 
 interface EnvKeyStatus {
   key: string;
@@ -76,6 +78,15 @@ const ADD_ACCOUNT_POLL_ABORT_MS = Math.max(
   ADD_ACCOUNT_POLL_INTERVAL_MS * 4,
 );
 
+function startManagedGoogleOAuth(): void {
+  const returnPath = `${window.location.pathname}${window.location.search}`;
+  startWorkspaceProviderOAuth("gmail", {
+    appId: "mail",
+    returnPath,
+    scope: "user",
+  });
+}
+
 function newDesktopOAuthVerifier(): string | null {
   const cryptoApi = globalThis.crypto;
   const randomUuid = cryptoApi?.randomUUID;
@@ -125,6 +136,8 @@ export function GoogleConnectBanner({
 
   const accounts = googleStatus.data?.accounts ?? [];
   const hasAccounts = accounts.length > 0;
+  const googleConfigured = googleStatus.data?.configured === true;
+  const canOfferOAuthSetup = useMemo(() => shouldOfferGoogleOAuthSetup(), []);
 
   const isBuilderFrame = useMemo(() => isInBuilderFrame(), []);
   const useDesktopAuth = useMemo(
@@ -336,13 +349,15 @@ export function GoogleConnectBanner({
   useEffect(() => {
     if (authUrl.error) {
       setWantAuthUrl(false);
-      setShowWizard(true);
-      fetchStatus();
+      if (canOfferOAuthSetup) {
+        setShowWizard(true);
+        fetchStatus();
+      }
       setAuthError(
         (authUrl.error as any)?.message || t("mail.error.failedToConnect"),
       );
     }
-  }, [authUrl.error, fetchStatus]);
+  }, [authUrl.error, canOfferOAuthSetup, fetchStatus]);
 
   const allConfigured =
     envStatus.length > 0 && envStatus.every((k) => k.configured);
@@ -419,20 +434,22 @@ export function GoogleConnectBanner({
   }, [wantAddAccount, addAccountUrl.data, isBuilderFrame]);
 
   function handleConnect() {
+    if (!googleConfigured && !canOfferOAuthSetup) return;
     setDesktopAuthIssue(null);
     if (useDesktopAuth) {
       signInViaDesktopBrowser();
       return;
     }
-    setWantAuthUrl(true);
+    startManagedGoogleOAuth();
   }
 
   function handleAddAccount() {
+    if (!googleConfigured && !canOfferOAuthSetup) return;
     if (useDesktopAuth) {
       signInViaDesktopBrowser(true);
       return;
     }
-    setWantAddAccount(true);
+    startManagedGoogleOAuth();
   }
 
   async function handleJsonUpload(file: File) {
@@ -489,6 +506,15 @@ export function GoogleConnectBanner({
   }
 
   if (dismissed) return null;
+  if (!googleStatus.data && !canOfferOAuthSetup && !googleStatus.isError)
+    return null;
+  if (
+    !googleConfigured &&
+    !canOfferOAuthSetup &&
+    !hasAccounts &&
+    !googleStatus.isError
+  )
+    return null;
 
   // Full-page hero for setup / reconnection
   if (variant === "hero") {
@@ -503,22 +529,34 @@ export function GoogleConnectBanner({
         <p className="mt-2 max-w-sm text-sm text-muted-foreground leading-relaxed">
           {t("mail.googleConnect.heroDescription")}
         </p>
-        <Button
-          size="sm"
-          className="mt-8 gap-2 px-5 h-9 text-sm font-medium bg-white text-black hover:bg-white/90"
-          onClick={() => {
-            setAuthError(null);
-            handleConnect();
-          }}
-          disabled={authUrl.isLoading || authUrl.isFetching}
-        >
-          <GoogleIcon className="h-4 w-4" />
-          {authUrl.isLoading
-            ? t("mail.accounts.connecting")
-            : allConfigured
-              ? t("mail.accounts.signInWithGoogle")
-              : t("mail.accounts.connectGoogle")}
-        </Button>
+        {googleStatus.isError ? (
+          <Button
+            size="sm"
+            variant="outline"
+            className="mt-8 gap-2 px-5 h-9 text-sm font-medium"
+            onClick={() => void googleStatus.refetch()}
+            disabled={googleStatus.isFetching}
+          >
+            {t("mail.error.tryAgain")}
+          </Button>
+        ) : googleConfigured || canOfferOAuthSetup ? (
+          <Button
+            size="sm"
+            className="mt-8 gap-2 px-5 h-9 text-sm font-medium bg-primary text-primary-foreground hover:bg-primary/90"
+            onClick={() => {
+              setAuthError(null);
+              handleConnect();
+            }}
+            disabled={authUrl.isLoading || authUrl.isFetching}
+          >
+            <GoogleIcon className="h-4 w-4" />
+            {authUrl.isLoading
+              ? t("mail.accounts.connecting")
+              : allConfigured
+                ? t("mail.accounts.signInWithGoogle")
+                : t("mail.accounts.connectGoogle")}
+          </Button>
+        ) : null}
 
         <GoogleAuthIssuePanel
           issue={desktopAuthIssue}
@@ -531,7 +569,7 @@ export function GoogleConnectBanner({
           <p className="mt-3 text-xs text-red-400">{authError}</p>
         )}
 
-        {showWizard && !allConfigured && (
+        {showWizard && !allConfigured && canOfferOAuthSetup && (
           <div className="mt-10 w-full max-w-lg text-start">
             <p className="text-xs text-muted-foreground mb-3">
               {t("mail.googleConnect.setupIntro")}
@@ -711,21 +749,25 @@ export function GoogleConnectBanner({
                 className="group flex items-center gap-1.5 text-xs text-foreground/60"
               >
                 <span className="truncate">{account.email}</span>
-                <button
-                  onClick={() => disconnectGoogle.mutate(account.email)}
-                  className="opacity-0 group-hover:opacity-100 transition-opacity text-foreground/30 hover:text-foreground/60"
-                >
-                  <IconX className="h-3 w-3" />
-                </button>
+                {!account.shared && (
+                  <button
+                    onClick={() => disconnectGoogle.mutate(account.email)}
+                    className="opacity-0 group-hover:opacity-100 transition-opacity text-foreground/30 hover:text-foreground/60"
+                  >
+                    <IconX className="h-3 w-3" />
+                  </button>
+                )}
               </div>
             ))}
-            <button
-              onClick={handleAddAccount}
-              disabled={addAccountUrl.isLoading || addAccountUrl.isFetching}
-              className="text-xs text-foreground/40 hover:text-foreground/60 transition-colors whitespace-nowrap"
-            >
-              + {t("mail.accounts.addAccount")}
-            </button>
+            {(googleConfigured || canOfferOAuthSetup) && (
+              <button
+                onClick={handleAddAccount}
+                disabled={addAccountUrl.isLoading || addAccountUrl.isFetching}
+                className="text-xs text-foreground/40 hover:text-foreground/60 transition-colors whitespace-nowrap"
+              >
+                + {t("mail.accounts.addAccount")}
+              </button>
+            )}
           </div>
           <Button
             variant="ghost"
@@ -742,6 +784,17 @@ export function GoogleConnectBanner({
           onDismiss={() => setDesktopAuthIssue(null)}
           className="mx-4 mb-3"
         />
+        {googleStatus.isError && (
+          <Button
+            variant="ghost"
+            size="sm"
+            className="mx-4 mb-2"
+            onClick={() => void googleStatus.refetch()}
+            disabled={googleStatus.isFetching}
+          >
+            {t("mail.error.tryAgain")}
+          </Button>
+        )}
       </div>
     );
   }
@@ -763,7 +816,17 @@ export function GoogleConnectBanner({
         </div>
 
         <div className="flex items-center gap-1.5 shrink-0">
-          {showWizard && !allConfigured ? (
+          {googleStatus.isError ? (
+            <Button
+              size="sm"
+              variant="outline"
+              className="gap-1.5 text-xs h-7 font-medium"
+              onClick={() => void googleStatus.refetch()}
+              disabled={googleStatus.isFetching}
+            >
+              {t("mail.error.tryAgain")}
+            </Button>
+          ) : showWizard && !allConfigured && canOfferOAuthSetup ? (
             <Button
               size="sm"
               variant="outline"
@@ -817,7 +880,7 @@ export function GoogleConnectBanner({
       />
 
       {/* Inline setup wizard */}
-      {showWizard && !allConfigured && (
+      {showWizard && !allConfigured && canOfferOAuthSetup && (
         <div className="px-4 pb-4 pt-1 max-w-2xl">
           <p className="text-xs text-muted-foreground mb-3">
             {t("mail.googleConnect.setupIntro")}

package/corpus/templates/mail/app/components/email/IntegrationsSidebar.tsx

@@ -187,15 +187,18 @@ export function IntegrationsSidebar({
   email,
   displayName,
   recentEmails,
+  recentEmailsError,
   threadId,
   focusedEmailId,
 }: {
   email: string;
   displayName: string;
   recentEmails: { id: string; subject: string }[];
+  recentEmailsError?: boolean;
   threadId?: string;
   focusedEmailId?: string;
 }) {
+  const t = useT();
   const statuses = useAllIntegrations();
   const anyConnected =
     statuses.apollo || statuses.hubspot || statuses.gong || statuses.pylon;
@@ -226,7 +229,16 @@ export function IntegrationsSidebar({
       )}
 
       {/* Recent emails */}
-      {recentEmails.length > 0 && (
+      {recentEmailsError ? (
+        <div
+          className="mx-4 border-t border-border/30 px-0 py-3"
+          aria-live="polite"
+        >
+          <p className="text-[11px] text-muted-foreground/70">
+            {t("mail.error.loadTitle")}
+          </p>
+        </div>
+      ) : recentEmails.length > 0 ? (
         <>
           <div className="h-px bg-border/30 mx-4" />
           <div className="px-4 py-3">
@@ -245,7 +257,7 @@ export function IntegrationsSidebar({
             ))}
           </div>
         </>
-      )}
+      ) : null}
 
       {/* Tool extension-point slot — user-installed widgets render here */}
       <ExtensionSlot

package/corpus/templates/mail/app/components/layout/AppLayout.tsx

@@ -7,6 +7,7 @@ import { appApiPath } from "@agent-native/core/client/api-path";
 import { DevDatabaseLink } from "@agent-native/core/client/db-admin";
 import { usePerAppChatOpen } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
+import { startWorkspaceProviderOAuth } from "@agent-native/core/client/integrations";
 import { openCommandMenu } from "@agent-native/core/client/navigation";
 import { InvitationBanner, OrgSwitcher } from "@agent-native/core/client/org";
 import { FeedbackButton } from "@agent-native/core/client/ui";
@@ -82,6 +83,7 @@ import {
 } from "@/hooks/use-keyboard-shortcuts";
 import { useIsMobile } from "@/hooks/use-mobile";
 import { runUndo } from "@/hooks/use-undo";
+import { shouldOfferGoogleOAuthSetup } from "@/lib/google-oauth-setup";
 import {
   OTHER_INBOX_TAB_ID,
   OTHER_INBOX_TAB_PARAM,
@@ -91,6 +93,7 @@ import {
 } from "@/lib/inbox-tabs";
 import { isMcpEmbedSurface } from "@/lib/mcp-embed";
 import { cn } from "@/lib/utils";
+import { isKnownMailView } from "@/routes/$view";
 
 import { CommandPalette } from "./CommandPalette";
 import { useHeaderTitle, useHeaderActions } from "./HeaderActions";
@@ -328,6 +331,11 @@ function AppLayoutInner({ children }: AppLayoutProps) {
   const googleStatus = useGoogleAuthStatus();
   const accounts = googleStatus.data?.accounts ?? [];
   const hasAccounts = accounts.length > 0;
+  const googleConfigured = googleStatus.data?.configured === true;
+  const canOfferGoogleOAuthSetup = useMemo(
+    () => shouldOfferGoogleOAuthSetup(),
+    [],
+  );
   const googleStatusReady = !googleStatus.isLoading && !googleStatus.isError;
   const [accountPopoverOpen, setAccountPopoverOpen] = useState(false);
   // Account filter: which accounts' emails to show. Empty set = all accounts.
@@ -1063,18 +1071,18 @@ function AppLayoutInner({ children }: AppLayoutProps) {
   const localCountsForKind = (kind: CountKind) =>
     kind === "total" ? labelThreadCounts.total : labelThreadCounts.unread;
 
-  // Take the larger of the server-reported count and the count we compute
-  // locally from loaded inbox emails. Either side can be stale (Gmail label
-  // totals can lag; loaded emails may be a partial window).
+  // Prefer the complete server count when Gmail provides one. Falling back to
+  // loaded rows is useful for local/demo mail, but merging the two with
+  // Math.max makes badges grow as more pages happen to be loaded.
   const getInboxCount = (kind: CountKind) => {
     const inboxLabel = resolveLabelForCount("inbox");
     const countField = countFieldForKind(kind);
     const localCounts = localCountsForKind(kind);
-    const serverCount = useServerLabelCounts
-      ? (inboxLabel?.[countField] ?? 0)
-      : 0;
+    const serverCount = inboxLabel?.[countField];
     const localCount = localCounts["__inboxTotal"] ?? 0;
-    return Math.max(serverCount, localCount);
+    return typeof serverCount === "number" && useServerLabelCounts
+      ? serverCount
+      : localCount;
   };
 
   const getOtherCount = (kind: CountKind) => {
@@ -1096,12 +1104,11 @@ function AppLayoutInner({ children }: AppLayoutProps) {
     const localCounts = localCountsForKind(kind);
     const localCount =
       localCounts[viewId] ?? (label ? (localCounts[label.id] ?? 0) : 0);
-    const serverCount =
-      useServerLabelCounts && viewId !== "note-to-self"
-        ? (label?.[countField] ?? 0)
-        : 0;
     if (inboxPartitionTabIds.has(viewId)) return localCount;
-    return Math.max(serverCount, localCount);
+    const serverCount = label?.[countField];
+    return typeof serverCount === "number" && useServerLabelCounts
+      ? serverCount
+      : localCount;
   };
   const getTopBarCount = (viewId: string) => getTabCount(viewId, "total");
   const getUnreadCount = (viewId: string) => getTabCount(viewId, "unread");
@@ -1494,6 +1501,7 @@ function AppLayoutInner({ children }: AppLayoutProps) {
               >
                 <AccountPopover
                   accounts={accounts}
+                  canAddAccount={googleConfigured || canOfferGoogleOAuthSetup}
                   activeAccounts={activeAccounts}
                   onToggleAccount={(email) => {
                     setActiveAccounts((prev) => {
@@ -1899,13 +1907,17 @@ function AppLayoutInner({ children }: AppLayoutProps) {
             </div>
           )}
 
-          {/* Show full-page takeover when no accounts connected (except on settings page) */}
+          {/* Show full-page takeover when no accounts connected (except on
+              settings page, or on an unknown route — an unmatched path must
+              still reach the routed NotFound content, not this gate). */}
           {!googleStatus.isLoading &&
           !googleStatus.isError &&
           !hasAccounts &&
           !hasLocalMailboxData &&
           view !== "settings" &&
-          view !== "draft-queue" ? (
+          view !== "draft-queue" &&
+          isKnownMailView(view) &&
+          (googleConfigured || canOfferGoogleOAuthSetup) ? (
             <GoogleConnectBanner variant="hero" />
           ) : (
             <main className="agent-native-app-main flex flex-1 overflow-hidden">
@@ -2561,11 +2573,18 @@ function TabSettingsPopover({
 
 function AccountPopover({
   accounts,
+  canAddAccount,
   activeAccounts,
   onToggleAccount,
   onRemoveAccount,
 }: {
-  accounts: Array<{ email: string; displayName?: string; photoUrl?: string }>;
+  accounts: Array<{
+    email: string;
+    displayName?: string;
+    photoUrl?: string;
+    shared?: boolean;
+  }>;
+  canAddAccount: boolean;
   activeAccounts: Set<string>;
   onToggleAccount: (email: string) => void;
   onRemoveAccount: (email: string) => void;
@@ -2668,32 +2687,43 @@ function AccountPopover({
                     </span>
                   )}
               </span>
-              <button
-                onClick={() => {
-                  onRemoveAccount(account.email);
-                  disconnectGoogle.mutate(account.email);
-                }}
-                className="opacity-0 group-hover:opacity-100 text-[11px] text-muted-foreground hover:text-red-400 transition-all"
-              >
-                {t("mail.accounts.remove")}
-              </button>
+              {!account.shared && (
+                <button
+                  onClick={() => {
+                    onRemoveAccount(account.email);
+                    disconnectGoogle.mutate(account.email);
+                  }}
+                  className="opacity-0 group-hover:opacity-100 text-[11px] text-muted-foreground hover:text-destructive transition-all"
+                >
+                  {t("mail.accounts.remove")}
+                </button>
+              )}
             </div>
           );
         })}
       </div>
 
-      <div className="border-t border-border/30 px-3 py-2">
-        <button
-          onClick={() => setWantAuthUrl(true)}
-          disabled={authUrl.isLoading || authUrl.isFetching}
-          className="flex items-center gap-2 w-full text-[13px] text-muted-foreground hover:text-foreground transition-colors py-1"
-        >
-          <IconPlus className="h-3.5 w-3.5" />
-          {authUrl.isFetching
-            ? t("mail.accounts.connecting")
-            : t("mail.accounts.addAccount")}
-        </button>
-      </div>
+      {canAddAccount ? (
+        <div className="border-t border-border/30 px-3 py-2">
+          <button
+            onClick={() => {
+              const returnPath = `${window.location.pathname}${window.location.search}`;
+              startWorkspaceProviderOAuth("gmail", {
+                appId: "mail",
+                returnPath,
+                scope: "user",
+              });
+            }}
+            disabled={authUrl.isLoading || authUrl.isFetching}
+            className="flex items-center gap-2 w-full text-[13px] text-muted-foreground hover:text-foreground transition-colors py-1"
+          >
+            <IconPlus className="h-3.5 w-3.5" />
+            {authUrl.isFetching
+              ? t("mail.accounts.connecting")
+              : t("mail.accounts.addAccount")}
+          </button>
+        </div>
+      ) : null}
     </>
   );
 }

package/corpus/templates/mail/app/hooks/use-google-auth.ts

@@ -8,9 +8,11 @@ export interface GoogleAuthAccount {
   displayName?: string;
   expiresAt?: string;
   photoUrl?: string;
+  shared?: boolean;
 }
 
 export interface GoogleAuthStatus {
+  configured?: boolean;
   connected: boolean;
   accounts: GoogleAuthAccount[];
 }

package/corpus/templates/mail/app/lib/google-oauth-setup.ts

@@ -0,0 +1,17 @@
+function localHostname(hostname: string): boolean {
+  return (
+    hostname === "localhost" ||
+    hostname === "127.0.0.1" ||
+    hostname === "::1" ||
+    hostname.endsWith(".localhost") ||
+    hostname.endsWith(".local")
+  );
+}
+
+export function shouldOfferGoogleOAuthSetup(): boolean {
+  const env = (import.meta.env ?? {}) as Record<string, unknown>;
+  if (env.DEV === true) return true;
+  if (env.VITE_ENABLE_GOOGLE_OAUTH_SETUP === "true") return true;
+  if (typeof window === "undefined") return false;
+  return localHostname(window.location.hostname.toLowerCase());
+}