@agent-native/core 0.169.1 → 0.170.0

package/corpus/templates/mail/app/pages/InboxPage.tsx

@@ -50,14 +50,78 @@ function ContactPanel({
       emails.find((e) => e.id === emailId || (e.threadId || e.id) === emailId),
     [emails, emailId],
   );
-  // Always use inbox emails for "recent from contact" — shares React Query cache,
-  // no extra fetch. The `emails` prop may be a different view (sent, starred, etc.)
-  const { data: inboxEmails = [] } = useEmails("inbox");
-
   const displayEmail = contactEmail || email?.from.email;
   const displayName = contactEmail
     ? contactEmail
     : email?.from.name || email?.from.email;
+  const normalizedDisplayEmail = displayEmail?.trim().toLowerCase() ?? "";
+  // Use all mail so contact activity survives sent/archive/inbox navigation.
+  // Search at the provider boundary so the contact panel does not page through
+  // the entire mailbox. The bounded follow-up fetches cover sparse histories.
+  const {
+    data: allEmails = [],
+    isError: allEmailsError,
+    hasNextPage,
+    fetchNextPage,
+    isFetchingNextPage,
+    isFetchNextPageError,
+  } = useEmails("all", normalizedDisplayEmail || undefined, undefined, {
+    enabled: Boolean(normalizedDisplayEmail),
+  });
+  const contactPageFetchesRef = useRef(0);
+  const contactGenerationRef = useRef(0);
+
+  useEffect(() => {
+    contactPageFetchesRef.current = 0;
+    contactGenerationRef.current += 1;
+  }, [normalizedDisplayEmail]);
+
+  const recentFromContact = displayEmail
+    ? allEmails
+        .filter((e) => {
+          if (e.id === emailId) return false;
+          const participants = [
+            e.from,
+            ...e.to,
+            ...(e.cc ?? []),
+            ...(e.bcc ?? []),
+          ];
+          return participants.some(
+            (participant) =>
+              participant.email.trim().toLowerCase() === normalizedDisplayEmail,
+          );
+        })
+        .slice(0, 4)
+        .map((e) => ({ id: e.id, subject: e.subject }))
+    : [];
+
+  useEffect(() => {
+    const maxContactPages = 4;
+    if (
+      !normalizedDisplayEmail ||
+      recentFromContact.length >= 4 ||
+      !hasNextPage ||
+      isFetchingNextPage ||
+      isFetchNextPageError ||
+      contactPageFetchesRef.current >= maxContactPages
+    ) {
+      return;
+    }
+    const contactGeneration = contactGenerationRef.current;
+    contactPageFetchesRef.current += 1;
+    void fetchNextPage().catch(() => {
+      if (contactGenerationRef.current === contactGeneration) {
+        contactPageFetchesRef.current = maxContactPages;
+      }
+    });
+  }, [
+    fetchNextPage,
+    hasNextPage,
+    isFetchNextPageError,
+    isFetchingNextPage,
+    normalizedDisplayEmail,
+    recentFromContact.length,
+  ]);
 
   if (!displayEmail) {
     return (
@@ -69,16 +133,12 @@ function ContactPanel({
     );
   }
 
-  const recentFromContact = inboxEmails
-    .filter((e) => e.from.email === displayEmail && e.id !== emailId)
-    .slice(0, 4)
-    .map((e) => ({ id: e.id, subject: e.subject }));
-
   return (
     <IntegrationsSidebar
       email={displayEmail}
       displayName={displayName || displayEmail}
       recentEmails={recentFromContact}
+      recentEmailsError={allEmailsError}
       threadId={email?.threadId}
       focusedEmailId={email?.id ?? emailId}
     />

package/corpus/templates/mail/app/routes/$.tsx

@@ -1,3 +1,5 @@
+import { data } from "react-router";
+
 import messages from "@/i18n/en-US";
 import { NotFound } from "@/pages/NotFound";
 
@@ -5,6 +7,13 @@ export function meta() {
   return [{ title: messages.mail.routeTitles.notFound }];
 }
 
+// The splat route matches every unmatched path, so React Router's "no routes
+// matched" 404 branch never fires here and the response defaults to 200. Set
+// the status explicitly so an unknown URL is served as the 404 it actually is.
+export function loader() {
+  return data(null, { status: 404 });
+}
+
 export default function CatchAllRoute() {
   return <NotFound />;
 }

package/corpus/templates/mail/app/routes/$view.$threadId.tsx

@@ -1,11 +1,29 @@
+import { data, useParams } from "react-router";
+
+import messages from "@/i18n/en-US";
 import { InboxPage } from "@/pages/InboxPage";
+import { NotFound } from "@/pages/NotFound";
+
+import { isKnownMailView } from "./$view";
 
 const SEO_TITLE =
   "Mail - Open Source AI email client and Superhuman alternative";
 const SEO_DESCRIPTION =
   "Open Source AI email client for Gmail triage, drafting, organization, follow-ups, and inbox workflows built around shared actions.";
 
-export function meta() {
+// Same rationale as $view.tsx's loader: this route also matches unknown
+// `/:view/:threadId` paths and must not serve them as 200.
+export function loader({ params }: { params: { view?: string } }) {
+  if (!isKnownMailView(params.view)) {
+    return data(null, { status: 404 });
+  }
+  return null;
+}
+
+export function meta({ params }: { params: { view?: string } }) {
+  if (!isKnownMailView(params.view)) {
+    return [{ title: messages.mail.routeTitles.notFound }];
+  }
   return [
     { title: SEO_TITLE },
     { name: "description", content: SEO_DESCRIPTION },
@@ -18,5 +36,9 @@ export function meta() {
 }
 
 export default function ThreadRoute() {
+  const { view } = useParams<{ view: string }>();
+  if (!isKnownMailView(view)) {
+    return <NotFound />;
+  }
   return <InboxPage />;
 }

package/corpus/templates/mail/app/routes/$view.tsx

@@ -1,11 +1,53 @@
+import { data, useParams } from "react-router";
+
+import messages from "@/i18n/en-US";
 import { InboxPage } from "@/pages/InboxPage";
+import { NotFound } from "@/pages/NotFound";
 
 const SEO_TITLE =
   "Mail - Open Source AI email client and Superhuman alternative";
 const SEO_DESCRIPTION =
   "Open Source AI email client for Gmail triage, drafting, organization, follow-ups, and inbox workflows built around shared actions.";
 
-export function meta() {
+// The only `view` values the app itself ever links to (sidebar hrefs,
+// navigate.ts). This is a sibling of the $.tsx splat 404 route, and
+// react-router always scores a `:view` dynamic segment above a `*` splat at
+// the same depth — so an arbitrary single-segment URL matches here first.
+// Rejecting anything outside this list is what lets a typo'd/unknown path
+// still reach NotFound instead of silently rendering the inbox shell.
+const KNOWN_MAIL_VIEWS = new Set([
+  "inbox",
+  "unread",
+  "starred",
+  "snoozed",
+  "scheduled",
+  "sent",
+  "drafts",
+  "archive",
+  "trash",
+  "all",
+]);
+
+export function isKnownMailView(view: string | undefined): boolean {
+  return !view || KNOWN_MAIL_VIEWS.has(view);
+}
+
+// react-router always scores a `:view` dynamic segment above the `$.tsx`
+// splat at the same depth, so an unmatched single-segment path matches here
+// and would otherwise serve 200 (React Router only auto-404s when literally
+// no route matches). Reject it explicitly so the response status matches the
+// NotFound content the component renders below.
+export function loader({ params }: { params: { view?: string } }) {
+  if (!isKnownMailView(params.view)) {
+    return data(null, { status: 404 });
+  }
+  return null;
+}
+
+export function meta({ params }: { params: { view?: string } }) {
+  if (!isKnownMailView(params.view)) {
+    return [{ title: messages.mail.routeTitles.notFound }];
+  }
   return [
     { title: SEO_TITLE },
     { name: "description", content: SEO_DESCRIPTION },
@@ -18,5 +60,9 @@ export function meta() {
 }
 
 export default function ViewRoute() {
+  const { view } = useParams<{ view: string }>();
+  if (!isKnownMailView(view)) {
+    return <NotFound />;
+  }
   return <InboxPage />;
 }

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

@@ -1,4 +1,6 @@
 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/mail/changelog/2026-08-22-gmail-can-now-connect-with-the-shared-google-oauth.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-22
+---
+
+Gmail can now connect with the shared Google OAuth app in one click

package/corpus/templates/mail/changelog/2026-08-22-gmail-filters-now-shows-the-real-error.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-22
+---
+
+Gmail Filters in Settings now shows the actual reason for a failure, like needing to connect Google, instead of a generic server error.

package/corpus/templates/mail/changelog/2026-08-22-unknown-mail-urls-now-show-the-404-page.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-22
+---
+
+Visiting an unrecognized mail URL now shows the 404 page instead of silently loading the inbox.

package/corpus/templates/mail/server/handlers/google-auth.ts

@@ -7,6 +7,7 @@ import {
   getSession,
   isElectron,
   getAppUrl,
+  hasWorkspaceProviderOAuthCredentials,
   resolveOAuthRedirectUri,
   encodeOAuthState,
   decodeOAuthState,
@@ -21,6 +22,7 @@ import {
   safeReturnPath,
   setDesktopExchange,
   setDesktopExchangeError,
+  runWithRequestContext,
 } from "@agent-native/core/server";
 import { getUserSetting, putUserSetting } from "@agent-native/core/settings";
 import {
@@ -490,7 +492,12 @@ export const handleGoogleAddAccountCallback = defineEventHandler(
 export const getGoogleStatus = defineEventHandler(async (event: H3Event) => {
   try {
     const session = await getSession(event);
-    return await getAuthStatus(session?.email);
+    const status = await getAuthStatus(session?.email);
+    const configured = await runWithRequestContext(
+      { userEmail: session?.email, orgId: session?.orgId },
+      () => hasWorkspaceProviderOAuthCredentials("gmail"),
+    );
+    return { ...status, configured };
   } catch (error: any) {
     setResponseStatus(event, 500);
     return { error: error.message };
@@ -511,7 +518,9 @@ export const disconnectGoogle = defineEventHandler(async (event: H3Event) => {
       return { error: "email is required" };
     }
     const owned = await getAuthStatus(session.email);
-    const isOwned = owned.accounts.some((a) => a.email === targetEmail);
+    const isOwned = owned.accounts.some(
+      (a) => a.email === targetEmail && !a.shared,
+    );
     if (!isOwned) {
       setResponseStatus(event, 403);
       return { error: "Cannot disconnect an account you don't own" };

package/corpus/templates/mail/server/lib/google-auth.ts

@@ -6,14 +6,15 @@ import {
   setOAuthDisplayName,
 } from "@agent-native/core/oauth-tokens";
 import {
-  isOAuthConnected,
   getOAuthAccounts,
   GOOGLE_PRIMARY_PROVIDER_CREDENTIAL_KEYS,
+  getCredentialContext,
   resolveGoogleProviderCredentialCandidatesWithReader,
   resolveSecret,
   runWithRequestContext,
 } from "@agent-native/core/server";
 import { getUserSetting, putUserSetting } from "@agent-native/core/settings";
+import { resolveWorkspaceConnectionForApp } from "@agent-native/core/workspace-connections";
 import { decodeCommonHtmlEntities } from "@shared/markdown.js";
 
 import type { BulkMarkReadResult } from "./bulk-mark-read.js";
@@ -33,6 +34,7 @@ import {
   googleFetch,
   peopleGetProfile,
 } from "./google-api.js";
+import { getMailProviderApiRuntime } from "./provider-api.js";
 import { resolveGoogleSenderIdentity } from "./sender-identity.js";
 import { invalidateThreadCache } from "./thread-cache.js";
 
@@ -48,6 +50,8 @@ const SCOPES = [
   "https://www.googleapis.com/auth/calendar.events",
 ];
 
+const GMAIL_SCOPE_PREFIX = "https://www.googleapis.com/auth/gmail.";
+
 interface GoogleTokens {
   access_token: string;
   refresh_token?: string;
@@ -56,6 +60,41 @@ interface GoogleTokens {
   scope?: string;
 }
 
+function hasGmailScope(tokens: Record<string, unknown>): boolean {
+  const scope = tokens.scope;
+  if (typeof scope !== "string" || !scope.trim()) return true;
+  return scope
+    .split(/[\s,]+/)
+    .some((value) => value.startsWith(GMAIL_SCOPE_PREFIX));
+}
+
+type ManagedGmailClient = {
+  email: string;
+  accessToken: string;
+  refreshToken: string;
+};
+
+async function resolveManagedGmailClient(): Promise<ManagedGmailClient | null> {
+  if (!getCredentialContext()) return null;
+  const connection = await resolveWorkspaceConnectionForApp({
+    appId: "mail",
+    provider: "gmail",
+    requireConnected: true,
+  });
+  if (!connection.available) return null;
+  const credential = await getMailProviderApiRuntime().resolveOAuthAccessToken({
+    provider: "gmail",
+  });
+  if (!credential.accountId) {
+    throw new Error("The connected Gmail workspace account has no account id.");
+  }
+  return {
+    email: credential.accountId,
+    accessToken: credential.accessToken,
+    refreshToken: "",
+  };
+}
+
 export async function getOAuth2Credentials(owner?: string): Promise<{
   clientId: string;
   clientSecret: string;
@@ -288,8 +327,12 @@ export async function getClient(
   email: string | undefined,
 ): Promise<{ accessToken: string; email: string } | null> {
   if (!email) return null;
-  const accounts = await listOAuthAccountsByOwner("google", email);
-  if (accounts.length === 0) return null;
+  const accounts = (await listOAuthAccountsByOwner("google", email)).filter(
+    (account) => hasGmailScope(account.tokens),
+  );
+  if (accounts.length === 0) {
+    return resolveManagedGmailClient();
+  }
 
   const account = accounts.find((a) => a.accountId === email) ?? accounts[0];
 
@@ -318,7 +361,7 @@ export async function getClientForAccount(
 ): Promise<{ accessToken: string; email: string } | null> {
   const all = await listOAuthAccounts("google");
   const account = all.find((a) => a.accountId === accountId);
-  if (!account) return null;
+  if (!account || !hasGmailScope(account.tokens)) return null;
   return getClientFromAccount({
     ...account,
     owner: account.owner ?? undefined,
@@ -335,6 +378,7 @@ export async function getClientFromAccount(account: {
   owner?: string;
   tokens: Record<string, unknown>;
 }): Promise<{ accessToken: string; email: string } | null> {
+  if (!hasGmailScope(account.tokens)) return null;
   const tokens = account.tokens as unknown as GoogleTokens;
   if (!tokens) return null;
 
@@ -389,7 +433,9 @@ export async function getClientsWithErrors(
   // refreshes are writes and an explicitly scoped inventory read must not
   // refresh unrelated accounts.
   const accounts = (await listOAuthAccountsByOwner("google", forEmail)).filter(
-    (account) => !requested || requested.has(account.accountId.toLowerCase()),
+    (account) =>
+      hasGmailScope(account.tokens) &&
+      (!requested || requested.has(account.accountId.toLowerCase())),
   );
 
   const clients: Array<{
@@ -432,6 +478,23 @@ export async function getClientsWithErrors(
     }
   }
 
+  if (clients.length === 0) {
+    try {
+      const managed = await resolveManagedGmailClient();
+      if (
+        managed &&
+        (!requested || requested.has(managed.email.toLowerCase()))
+      ) {
+        clients.push(managed);
+      }
+    } catch (err: any) {
+      errors.push({
+        email: "workspace",
+        error: err?.message || "Workspace Gmail connection failed",
+      });
+    }
+  }
+
   return { clients, errors };
 }
 
@@ -440,15 +503,22 @@ export async function getClientsWithErrors(
  * checks only that specific account.
  */
 export async function isConnected(forEmail?: string): Promise<boolean> {
-  return isOAuthConnected("google", forEmail ?? "");
+  if (!forEmail) return false;
+  const accounts = await listOAuthAccountsByOwner("google", forEmail);
+  if (accounts.some((account) => hasGmailScope(account.tokens))) return true;
+  return Boolean(await resolveManagedGmailClient());
 }
 
 export async function getConnectedAccounts(
   forEmail?: string,
 ): Promise<string[]> {
   if (!forEmail) return [];
-  const accounts = await listOAuthAccountsByOwner("google", forEmail);
-  return accounts.map((a) => a.accountId);
+  const accounts = (await listOAuthAccountsByOwner("google", forEmail)).filter(
+    (account) => hasGmailScope(account.tokens),
+  );
+  if (accounts.length > 0) return accounts.map((a) => a.accountId);
+  const managed = await resolveManagedGmailClient();
+  return managed ? [managed.email] : [];
 }
 
 export interface GoogleAuthStatus {
@@ -458,6 +528,7 @@ export interface GoogleAuthStatus {
     displayName?: string;
     expiresAt?: string;
     photoUrl?: string;
+    shared?: boolean;
   }>;
 }
 
@@ -468,10 +539,15 @@ export interface GoogleAuthStatus {
 export async function getAuthStatus(
   forEmail?: string,
 ): Promise<GoogleAuthStatus> {
-  const oauthAccounts = await getOAuthAccounts("google", forEmail);
+  const oauthAccounts = (await getOAuthAccounts("google", forEmail)).filter(
+    (account) => hasGmailScope(account.tokens),
+  );
 
   if (oauthAccounts.length === 0) {
-    return { connected: false, accounts: [] };
+    const managed = await resolveManagedGmailClient();
+    return managed
+      ? { connected: true, accounts: [{ email: managed.email, shared: true }] }
+      : { connected: false, accounts: [] };
   }
 
   const accounts: Array<{
@@ -1883,7 +1959,9 @@ interface GmailMessageReference {
 async function getDefaultOwnedAccountAccessToken(
   ownerEmail: string,
 ): Promise<string> {
-  const accounts = await listOAuthAccountsByOwner("google", ownerEmail);
+  const accounts = (
+    await listOAuthAccountsByOwner("google", ownerEmail)
+  ).filter((account) => hasGmailScope(account.tokens));
   const account =
     accounts.find(
       (candidate) =>
@@ -1901,7 +1979,9 @@ async function getOwnedAccountAccessToken(
   ownerEmail: string,
   accountEmail: string,
 ): Promise<string> {
-  const accounts = await listOAuthAccountsByOwner("google", ownerEmail);
+  const accounts = (
+    await listOAuthAccountsByOwner("google", ownerEmail)
+  ).filter((account) => hasGmailScope(account.tokens));
   const account = accounts.find(
     (candidate) =>
       candidate.accountId.toLowerCase() === accountEmail.toLowerCase(),

package/corpus/templates/mail/server/onboarding.ts

@@ -3,17 +3,32 @@
  * framework-level onboarding registry. The step is picked up by the onboarding
  * panel in the agent sidebar on every request.
  *
- * Two completion methods are offered:
- *   1. Manual wizard — links back to the app root, where the existing
- *      `GoogleConnectBanner` auto-detects missing credentials and guides the
- *      user through the Google Cloud Console setup.
- *   2. Agent task — hands the task to the agent, which drives the user's
- *      browser (or falls back to verbal step-by-step instructions) and saves
- *      the resulting credentials as workspace-scoped DB keys.
+ * The connection uses the framework's managed Google OAuth client. The
+ * workspace chooses whether the resulting connection is personal or shared;
+ * no user-facing Google Cloud Console setup is required.
  */
 
+import { listOAuthAccountsByOwner } from "@agent-native/core/oauth-tokens";
 import { registerOnboardingStep } from "@agent-native/core/onboarding";
-import { readDeployCredentialEnv } from "@agent-native/core/server";
+import { hasWorkspaceProviderOAuthCredentials } from "@agent-native/core/server";
+import { resolveWorkspaceConnectionForApp } from "@agent-native/core/workspace-connections";
+
+const GMAIL_SCOPES = [
+  "https://www.googleapis.com/auth/gmail.readonly",
+  "https://www.googleapis.com/auth/gmail.send",
+  "https://www.googleapis.com/auth/gmail.modify",
+  "https://www.googleapis.com/auth/gmail.settings.basic",
+] as const;
+
+function hasRequiredScope(tokens: unknown): boolean {
+  if (!tokens || typeof tokens !== "object" || Array.isArray(tokens)) {
+    return false;
+  }
+  const scope = (tokens as { scope?: unknown }).scope;
+  if (typeof scope !== "string" || !scope.trim()) return true;
+  const granted = new Set(scope.split(/[\s,]+/).filter(Boolean));
+  return GMAIL_SCOPES.some((requiredScope) => granted.has(requiredScope));
+}
 
 registerOnboardingStep({
   id: "gmail",
@@ -21,14 +36,30 @@ registerOnboardingStep({
   required: false,
   title: "Connect Gmail",
   description: "Send, read, and organize real email.",
+  isAvailable: () => hasWorkspaceProviderOAuthCredentials("gmail"),
   methods: [
     {
-      id: "manual-wizard",
+      id: "oauth",
       kind: "link",
       primary: true,
-      label: "Connect Google OAuth (guided)",
-      description: "3-minute guided setup in Google Cloud Console.",
-      payload: { url: "/" },
+      label: "Connect Gmail for me",
+      description:
+        "One-click Google sign-in using the workspace's managed OAuth connection. Only you can use this connection.",
+      payload: {
+        url: "/_agent-native/connections/oauth/gmail/start?scope=user&appId=mail&return=/",
+        external: false,
+      },
+    },
+    {
+      id: "oauth-workspace",
+      kind: "link",
+      label: "Connect Gmail for my workspace",
+      description:
+        "Workspace admins can connect once and make this Gmail connection available to selected apps or everyone in the workspace.",
+      payload: {
+        url: "/_agent-native/connections/oauth/gmail/start?scope=organization&appId=mail&return=/",
+        external: false,
+      },
     },
     {
       id: "agent-task",
@@ -37,13 +68,30 @@ registerOnboardingStep({
       label: "Have the agent set it up for me",
       payload: {
         prompt:
-          "Help me connect Gmail. Walk me through creating Google OAuth credentials by driving my browser (use any mcp__*browser* tools available, or fall back to giving me step-by-step instructions with exact URLs and values). When client_id and client_secret are ready, help me configure GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET as deployment or local environment variables for Mail, then restart or redeploy before clicking Sign in with Google.",
+          "Help me connect Gmail through the managed Google OAuth connection. Start the one-click Gmail connection flow, explain the Google permission screen, and confirm whether I want the connection available only to me or to the workspace. Do not ask me to create Google Cloud credentials or paste keys.",
       },
     },
   ],
-  isComplete: async () =>
-    Boolean(
-      readDeployCredentialEnv("GOOGLE_CLIENT_ID") &&
-      readDeployCredentialEnv("GOOGLE_CLIENT_SECRET"),
-    ),
+  isComplete: async (context) => {
+    if (!context?.userEmail) return false;
+    try {
+      const accounts = await listOAuthAccountsByOwner(
+        "google",
+        context.userEmail,
+      );
+      if (accounts.some((account) => hasRequiredScope(account.tokens))) {
+        return true;
+      }
+      return (
+        await resolveWorkspaceConnectionForApp({
+          appId: "mail",
+          provider: "gmail",
+          requireConnected: true,
+        })
+      ).available;
+    } catch {
+      // coercion-ok: a failed lookup must leave onboarding incomplete, never completed.
+      return false;
+    }
+  },
 });

package/corpus/templates/mail/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/plan/.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/plan/app/routes/settings.tsx

@@ -23,7 +23,10 @@ export function meta() {
 
 export default function SettingsRoute() {
   const t = useT();
-  const agentSettingsTabs = useAgentSettingsTabs();
+  // /extensions redirects here and navigation.view supports "extensions"
+  // (see use-navigation-state.ts), so the settings tab must exist too —
+  // otherwise /settings/extensions silently falls back to General.
+  const agentSettingsTabs = useAgentSettingsTabs({ extensionTools: true });
   useSetPageTitle(t("settings.title"));
 
   const generalSearchEntries = useMemo<SettingsSearchEntry[]>(