feat(connections): gate the built-in Google Workspace connector behind an experimental toggle (#19247)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The Apps catalog lets operators connect external tools, including
Google services.
> - Paperclip has a built-in Google Workspace connector, but Google has
not yet verified Paperclip's Google app.
> - The built-in connector also hides the Composio and Arcade Google
apps, because native Google definitions claim those app names.
> - Users therefore see an unverified connector and cannot find the
working aggregator Google apps.
> - This pull request puts the built-in connector behind a default-off
experimental setting. When the setting is off, the aggregator Google
apps appear.
> - The benefit is that users get working Google connectors now, and the
team can still test the built-in connector on demand.

## Linked Issues or Issue Description

**Problem**
Google has not verified Paperclip's Google app yet. The Apps page still
offers the built-in Google Workspace connector. The built-in Google
definitions also suppress the Composio and Arcade Google apps (Gmail,
Google Calendar, Google Drive, Docs, Sheets, Slides, Chat), so users
cannot find them.

**Proposed solution**
Add the `enableGoogleWorkspaceConnector` experimental setting. The
default is off. When it is off, hide and block the built-in connector,
and show the aggregator Google apps. When it is on, keep the current
behavior.

**Alternatives considered**
Delete the built-in connector until verification is complete. We
rejected this option because the team must continue to test the
connector.

**Additional context**
Composio documents Gmail (63 tools), Google Calendar (50 tools), and
Google Drive toolkits that use Composio-managed OAuth. These toolkits do
not need Paperclip's Google app verification.

## What Changed

- Added the default-off `enableGoogleWorkspaceConnector` experimental
setting to the shared types, validator, feature catalog, server
defaults, and the managed-key list for Paperclip Cloud staging.
- Added `experimentalFeatureKey: "enableGoogleWorkspaceConnector"` to
the `google-workspace` app definition. The existing generic connector
gate then hides the connector in the gallery and blocks its setup,
discovery, execution, and agent suggestions when the setting is off.
- Added a "Google Workspace connector (Paperclip)" toggle card to
**Settings → Experimental**.
- Apps page (`Browse.tsx`): when the setting is off, built-in Google
rows without saved accounts no longer claim aggregator app identities.
The Composio and Arcade Google apps then show as aggregator rows. The
legacy Google slug filter now applies only to native rows, so the
Composio `gmail` row is not dropped.
- Saved per-service Google connections (Gmail, Drive, and others) are
not gated. They stay visible and usable.
- Updated `doc/connections/GOOGLE-WORKSPACE.md`.
- Tests: added tests for the hidden and visible Apps page states, the
settings toggle, and the definition gate. Existing built-in Google
Workspace tests now enable the setting.

## Verification

- `cd packages/shared && npx vitest run` passes (1055 tests).
- `cd server && npx vitest run
src/__tests__/connection-management.integration.test.ts
src/__tests__/tool-access-service.test.ts
src/__tests__/tool-gateway-service.test.ts
src/services/gmail-tool-governance.test.ts
src/services/google-chat-tool-policy.test.ts
src/__tests__/instance-settings-service.test.ts
src/__tests__/health.test.ts
src/__tests__/instance-settings-managed-overlay.test.ts` passes (864
tests).
- `cd ui && npx vitest run src/pages/apps
src/pages/InstanceExperimentalSettings.test.tsx
src/features/connections` passes.
- `tsc --noEmit` passes for `packages/shared`, `server`, and `ui`. The
`ui` run shows errors only in the untouched
`storybook/support/feature-map` files.
- `pnpm check:token-gates` passes.
- Manual check: open **Apps** with the setting off. Search for "Gmail".
The Composio Gmail row appears, and the built-in Google Workspace card
does not. Turn on the setting in **Settings → Experimental**. The
built-in card appears again.

## Risks

- Existing built-in `google-workspace` connections stop running while
the setting is off, because the generic gate blocks execution. This is
intentional, so that the unverified Google app is not used. Turn on the
setting on instances that must keep these connections.
- Saved per-service Google connections are not affected.
- When the setting is on, the behavior does not change.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (Anthropic), model ID `claude-opus-5-5`, running in
Claude Code with tool use (shell, file edits, web fetch).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

packages/shared/src/app-definitions/google-workspace.json

@@ -1,4 +1,5 @@
 {
+  "experimentalFeatureKey": "enableGoogleWorkspaceConnector",
   "schemaVersion": 1,
   "slug": "google-workspace",
   "name": "Google Workspace",

packages/shared/src/connector-availability.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import { getConnectableAppDefinition } from "./app-definitions.js";
 import { isConnectorFeatureEnabled } from "./connector-availability.js";
 import { appDefinitionSchema } from "./validators/app-definition.js";
+import { instanceExperimentalSettingsSchema } from "./validators/instance.js";
 
 describe("connector availability", () => {
   const ordinary = getConnectableAppDefinition("notion")!;
@@ -24,4 +25,15 @@ describe("connector availability", () => {
     expect(isConnectorFeatureEnabled(notebook, {})).toBe(false);
     expect(isConnectorFeatureEnabled(notebook, { enablePaperclipNotebook: true })).toBe(true);
   });
+
+  it("gates only the built-in Google Workspace connector, default off, while verification is pending", () => {
+    const workspace = getConnectableAppDefinition("google-workspace")!;
+    expect(workspace.experimentalFeatureKey).toBe("enableGoogleWorkspaceConnector");
+    expect(isConnectorFeatureEnabled(workspace, instanceExperimentalSettingsSchema.parse({}))).toBe(false);
+    expect(isConnectorFeatureEnabled(workspace, { enableGoogleWorkspaceConnector: true })).toBe(true);
+    // Saved per-service Google connections keep working; only the unified entry is gated.
+    for (const slug of ["gmail", "google-drive", "google-calendar", "google-docs", "google-sheets"]) {
+      expect(getConnectableAppDefinition(slug)?.experimentalFeatureKey).toBeUndefined();
+    }
+  });
 });

packages/shared/src/feature-catalog.ts

@@ -175,6 +175,13 @@ export const INSTANCE_FEATURE_CATALOG: Record<InstanceFeatureKey, FeatureCatalog
     cloudDefault: false,
     selfHostedDefault: false,
   },
+  enableGoogleWorkspaceConnector: {
+    title: "Google Workspace connector (Paperclip)",
+    description: "Show and allow the built-in Google Workspace connector while its Google app verification is pending. When off, Google apps are offered through Composio and Arcade instead.",
+    tier: "managed",
+    cloudDefault: false,
+    selfHostedDefault: false,
+  },
   enableMcpAggregators: {
     title: "MCP aggregators (compatibility)",
     description: "Deprecated compatibility key. MCP aggregators are always enabled; stored and managed values are ignored.",

packages/shared/src/types/instance.ts

@@ -87,6 +87,8 @@ export interface InstanceExperimentalSettings {
   /** Show experimental memory connection setup. Existing connections remain usable. */
   enableMemoryConnectors: boolean;
   enablePaperclipNotebook: boolean;
+  /** Show and allow the built-in Google Workspace connector while its Google verification is pending. */
+  enableGoogleWorkspaceConnector: boolean;
   enableCases: boolean;
   enableAgentChat: boolean;
   /** Reorganized left nav, Inbox-as-Tasks-views, and the chat agent rail + task cards. */

packages/shared/src/validators/instance.ts

@@ -62,6 +62,7 @@ export const instanceExperimentalSettingsSchema = z.object({
   enableMcpAggregators: z.boolean().default(true),
   enableMemoryConnectors: z.boolean().default(false),
   enablePaperclipNotebook: z.boolean().default(false),
+  enableGoogleWorkspaceConnector: z.boolean().default(false),
   enableCases: z.boolean().default(false),
   enableAgentChat: z.boolean().default(false),
   enableCombinedInboxTasks: z.boolean().default(false),