feat: operator-configurable settings visibility via PAPERCLIP_HIDDEN_SETTINGS (#11823)

## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The instance settings surface (Access, Plugins, Adapters, General, Experimental) assumes the person at the keyboard operates the whole instance > - Operators who host Paperclip for others — a managed cloud or an internal shared server — expose settings pages and toggles that do not apply to their deployment, and the related mutation APIs stay open > - A hosted tenant can open Plugins or Adapters, try an action, and hit a confusing failure, because only a few hardcoded platform floors exist > - This pull request adds a generic, operator-configured visibility mechanism: one env var hides declared settings surfaces in the UI and floors their mutation routes with a stable 403 code > - The benefit is a clean hosted-tenant settings surface for any operator, with zero behavior change for normal self-hosted instances ## Linked Issues or Issue Description **Subsystem affected** Instance settings (server routes and UI), the shared settings registry in `packages/shared`, and the `/api/health` bootstrap payload. **Problem or motivation** An operator who hosts Paperclip for other people cannot hide settings surfaces that the platform manages. Tenants see Access, Plugins, and Adapters pages, backup retention, and host-level experimental toggles that do nothing useful for them. The mutation APIs behind these surfaces also stay open, so a tenant admin can attempt actions the platform must control. ROADMAP.md names a cleaner shared deployment story as a goal ("Teams should be able to run the same product in hosted or semi-hosted environments without changing the mental model"). **Proposed solution** Add a declarative registry of hideable settings surfaces and one env var, `PAPERCLIP_HIDDEN_SETTINGS`. The server parses the list at boot, reports it on `/api/health`, and rejects value-changing writes to hidden surfaces with a stable `settings_operator_managed` 403 code. The UI reads the list from the health payload and removes the hidden pages, sections, and toggles from navigation, routes, and page content. Unknown keys warn and are ignored, so one list can roll across a fleet with mixed app versions. With the variable unset, behavior is byte-identical to today. **Alternatives considered** - Hardcode the hidden set for cloud instances in this repo: rejected, because each hosting operator needs a different policy, and policy does not belong in shared code. - Deliver the hidden set through the managed-config document: rejected, because that channel is cloud-specific and fail-closed on unknown fields; a plain env var works for any operator, including self-hosted shared servers. - Lock the controls with a badge instead of hiding them: rejected for these surfaces, because they are meaningless to tenants, not merely platform-controlled; the existing managed-overlay lock stays the right tool for controlled flags. **Roadmap alignment** Supports the "shared deployment story" item in ROADMAP.md: hosted and semi-hosted deployments keep the same product with a settings surface that matches what the tenant can actually do. ## What Changed - New `packages/shared/src/settings-visibility.ts`: registry of hideable surfaces (every instance settings page — profile, environments, access, heartbeats, experimental, plugins, adapters; every Instance → General section; every experimental flag as `instance.experimental.<key>`), the `PAPERCLIP_HIDDEN_SETTINGS` parser, and the `settings_operator_managed` error code. The General page stays visible as the settings root and redirect target. - New `server/src/services/settings-visibility.ts`: parse-once accessor; unknown keys log one warning and are ignored. - `/api/health` reports `hiddenSettings` on every response shape; the field is omitted when nothing is hidden. - Server floors on hidden surfaces, with same-value echo tolerance (the `executionMode` precedent): field-backed general sections and experimental keys reject value-changing PATCHes, and hiding the whole Experimental page floors every toggle; plugin lifecycle and config writes, adapter management writes, and the Access admin routes (reads included) return 403 `settings_operator_managed`. Reads the app itself needs (plugin `ui-contributions`, adapter metadata, plugin job trigger) stay open. Pages without instance-scoped mutation routes are hidden in the UI only. - UI: new `useHiddenSettings` hook and `HiddenSettingsPageGate` route gate (hidden pages redirect to the settings root); the settings sidebar and tab bar drop hidden entries; remembered settings paths remap to the default page; `InstanceGeneralSettings` skips hidden sections; every `ExperimentalToggleCard` now carries its flag key and renders nothing when hidden. - Removed the dead `InstanceSidebar` component (referenced only by its own test). - Docs: `docs/deploy/environment-variables.md` documents the variable and the key registry. ## Verification - `pnpm vitest run` over the new and extended suites: shared registry and parser, representative floor tests per route class (changed-value 403, same-value echo 200, unset env 200, page-level Experimental hiding), the health field, the route gate, nav filtering, and section/card hiding with one hidden example per surface kind — 168 tests pass. - Full root `pnpm typecheck` passes. - Manual: booted a server with the variable set. `/api/health` lists the keys; an unknown key logs one warning and the server boots; hidden pages redirect; hidden sections and cards do not render; hidden-field PATCH returns 403 with `details.code = "settings_operator_managed"`; a same-value echo returns 200. Unset the variable: the full settings surface returns and responses are byte-identical to master. ## Risks - Low risk for self-hosted instances: with the variable unset, the hidden set is empty, the health field is omitted, and no floor activates. - Flooring plugin config writes assumes hosted deployments configure plugins through the platform. If a future bundled plugin needs tenant-entered config, the floor needs a narrow carve-out. - Hidden-key floors tolerate same-value echoes, so API clients that round-trip full GET responses keep working. - Hiding a toggle does not change its value; operators pair hiding with the desired default where the value matters. ## Model Used Claude Fable 5 (Anthropic, `claude-fable-5`) with extended thinking and agentic tool use, driven through the Claude Code CLI (file edits, test execution, and live-server verification loops). ## 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 - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge
2026-10-25 02:26:12 +02:00 · 2026-08-20 17:54:44 -07:00
1 parent 0fa318b8da
commit db4defdfbf
@@ -9,6 +9,8 @@ import { PipelinesExperimentalGate } from "./components/PipelinesExperimentalGat
 import { CasesExperimentalGate } from "./components/CasesExperimentalGate";
 import { StatusCardsExperimentalGate } from "./components/StatusCardsExperimentalGate";
 import { AppsExperimentalGate } from "./components/AppsExperimentalGate";
+import { HiddenSettingsPageGate } from "./components/HiddenSettingsPageGate";
+import { useHiddenSettings } from "./hooks/useHiddenSettings";
 import { Cases } from "./pages/Cases";
 import { CaseDetail } from "./pages/CaseDetail";
 import { OnboardingWizardVariant } from "./components/OnboardingWizardVariant";
@@ -96,7 +98,7 @@ import {
  shouldRedirectCompanylessRouteToOnboarding,
 } from "./lib/onboarding-route";
 import { useCompanyMission } from "./hooks/useCompanyMission";
-import { normalizeRememberedInstanceSettingsPath } from "./lib/instance-settings";
+import { filterHiddenInstanceSettingsPath, normalizeRememberedInstanceSettingsPath } from "./lib/instance-settings";

 const CompanyExport = lazy(() =>
  import("./pages/CompanyExport").then((module) => ({ default: module.CompanyExport })),
@@ -155,17 +157,31 @@ function boardRoutes() {
        <Route path="apps/:connectionId/:tab" element={<AppDetail />} />
      </Route>
      <Route path="company/settings/instance" element={<Navigate to="/company/settings" replace />} />
-      <Route path="company/settings/instance/profile" element={<ProfileSettings />} />
+      <Route element={<HiddenSettingsPageGate pageKey="instance.profile" />}>
+        <Route path="company/settings/instance/profile" element={<ProfileSettings />} />
+      </Route>
      <Route path="company/settings/instance/general" element={<Navigate to="/company/settings" replace />} />
-      <Route path="company/settings/instance/environments" element={<CompanyEnvironments />} />
-      <Route path="company/settings/instance/environments/new" element={<CompanyEnvironments mode="create" />} />
-      <Route path="company/settings/instance/environments/:environmentId/edit" element={<CompanyEnvironments mode="edit" />} />
-      <Route path="company/settings/instance/access" element={<InstanceAccess />} />
-      <Route path="company/settings/instance/heartbeats" element={<InstanceSettings />} />
-      <Route path="company/settings/instance/experimental" element={<InstanceExperimentalSettings />} />
-      <Route path="company/settings/instance/plugins" element={<PluginManager />} />
-      <Route path="company/settings/instance/plugins/:pluginId" element={<PluginSettings />} />
-      <Route path="company/settings/instance/adapters" element={<AdapterManager />} />
+      <Route element={<HiddenSettingsPageGate pageKey="instance.environments" />}>
+        <Route path="company/settings/instance/environments" element={<CompanyEnvironments />} />
+        <Route path="company/settings/instance/environments/new" element={<CompanyEnvironments mode="create" />} />
+        <Route path="company/settings/instance/environments/:environmentId/edit" element={<CompanyEnvironments mode="edit" />} />
+      </Route>
+      <Route element={<HiddenSettingsPageGate pageKey="instance.access" />}>
+        <Route path="company/settings/instance/access" element={<InstanceAccess />} />
+      </Route>
+      <Route element={<HiddenSettingsPageGate pageKey="instance.heartbeats" />}>
+        <Route path="company/settings/instance/heartbeats" element={<InstanceSettings />} />
+      </Route>
+      <Route element={<HiddenSettingsPageGate pageKey="instance.experimental" />}>
+        <Route path="company/settings/instance/experimental" element={<InstanceExperimentalSettings />} />
+      </Route>
+      <Route element={<HiddenSettingsPageGate pageKey="instance.plugins" />}>
+        <Route path="company/settings/instance/plugins" element={<PluginManager />} />
+        <Route path="company/settings/instance/plugins/:pluginId" element={<PluginSettings />} />
+      </Route>
+      <Route element={<HiddenSettingsPageGate pageKey="instance.adapters" />}>
+        <Route path="company/settings/instance/adapters" element={<AdapterManager />} />
+      </Route>
      <Route path="company/settings/:settingsRoutePath/*" element={<CompanySettingsPluginPage />} />
      <Route path="skills/studio" element={<SkillStudio />} />
      <Route path="skills/studio/new" element={<SkillStudio />} />
@@ -350,6 +366,7 @@ function LegacySettingsRedirect() {
  const location = useLocation();
  const { companies, selectedCompany, loading } = useCompany();
  const { companyPrefix } = useParams<{ companyPrefix?: string }>();
+  const { hidden: hiddenSettings } = useHiddenSettings();

  if (loading) {
    return <PaperclipLoading />;
@@ -375,8 +392,11 @@ function LegacySettingsRedirect() {
    return <NoCompaniesStartPage />;
  }

-  const normalizedPath = normalizeRememberedInstanceSettingsPath(
-    `${location.pathname}${location.search}${location.hash}`,
+  const normalizedPath = filterHiddenInstanceSettingsPath(
+    normalizeRememberedInstanceSettingsPath(
+      `${location.pathname}${location.search}${location.hash}`,
+    ),
+    hiddenSettings,
  );

  return (
@@ -36,6 +36,11 @@ export type HealthStatus = {
  serverInfo?: ServerInfoSnapshot;
  devServer?: DevServerHealthStatus;
  cloud?: CloudInstanceHealthStatus;
+  /**
+   * Settings surfaces hidden by the hosting operator (keys from the shared
+   * settings-visibility registry). Absent when nothing is hidden.
+   */
+  hiddenSettings?: string[];
 };

 export const healthApi = {
@@ -3,6 +3,7 @@
 import { createRoot } from "react-dom/client";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { queryKeys } from "@/lib/queryKeys";
 import { CompanySettingsSidebar } from "./CompanySettingsSidebar";

 const sidebarNavItemMock = vi.hoisted(() => vi.fn());
@@ -353,3 +354,64 @@ describe("CompanySettingsSidebar", () => {
    });
  });
 });
+
+describe("CompanySettingsSidebar operator-hidden entries", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    mockSidebarBadgesApi.get.mockResolvedValue({
+      inbox: 0,
+      approvals: 0,
+      failedRuns: 0,
+      joinRequests: 0,
+    });
+    mockPluginsApi.list.mockResolvedValue([]);
+    mockUsePluginSlots.mockReturnValue({ slots: [], isLoading: false, errorMessage: null });
+  });
+
+  afterEach(() => {
+    container.remove();
+    document.body.innerHTML = "";
+    vi.clearAllMocks();
+  });
+
+  async function renderSidebar(hiddenSettings?: string[]) {
+    const root = createRoot(container);
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    queryClient.setQueryData(queryKeys.health, {
+      status: "ok",
+      ...(hiddenSettings ? { hiddenSettings } : {}),
+    });
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <CompanySettingsSidebar />
+        </QueryClientProvider>,
+      );
+    });
+    await flushReact();
+  }
+
+  it("skips operator-hidden pages and their queries", async () => {
+    await renderSidebar(["instance.plugins", "instance.heartbeats"]);
+
+    expect(container.textContent).not.toContain("Plugins");
+    expect(container.textContent).not.toContain("Heartbeats");
+    expect(container.textContent).toContain("General");
+    expect(container.textContent).toContain("Adapters");
+    expect(container.textContent).toContain("Access");
+    expect(mockPluginsApi.list).not.toHaveBeenCalled();
+  });
+
+  it("keeps every entry when nothing is hidden", async () => {
+    await renderSidebar();
+
+    expect(container.textContent).toContain("Access");
+    expect(container.textContent).toContain("Plugins");
+    expect(container.textContent).toContain("Heartbeats");
+    expect(container.textContent).toContain("Adapters");
+    expect(mockPluginsApi.list).toHaveBeenCalled();
+  });
+});
@@ -25,6 +25,7 @@ import { SIDEBAR_SCROLL_RESET_STATE } from "@/lib/navigation-scroll";
 import { queryKeys } from "@/lib/queryKeys";
 import { useCompany } from "@/context/CompanyContext";
 import { useSidebar } from "@/context/SidebarContext";
+import { useHiddenSettings } from "@/hooks/useHiddenSettings";
 import { usePluginSlots } from "@/plugins/slots";
 import { SidebarNavItem } from "./SidebarNavItem";

@@ -43,6 +44,9 @@ function isSandboxProviderOnly(plugin: PluginRecord): boolean {
 export function CompanySettingsSidebar() {
  const { selectedCompany, selectedCompanyId } = useCompany();
  const { isMobile, setSidebarOpen } = useSidebar();
+  const { hidden: hiddenSettings } = useHiddenSettings();
+  const showPage = (pageKey: string) => !hiddenSettings.has(pageKey);
+  const showPlugins = showPage("instance.plugins");
  const { slots: companySettingsPluginSlots } = usePluginSlots({
    slotTypes: ["companySettingsPage"],
    companyId: selectedCompanyId,
@@ -69,6 +73,9 @@ export function CompanySettingsSidebar() {
  const { data: plugins } = useQuery({
    queryKey: queryKeys.plugins.all,
    queryFn: () => pluginsApi.list(),
+    // The listing only feeds the per-plugin subtree below; skip it when the
+    // operator hides the Plugins surface.
+    enabled: showPlugins,
  });
  const sidebarPlugins = (plugins ?? []).filter((plugin) => !isSandboxProviderOnly(plugin));

@@ -90,12 +97,14 @@ export function CompanySettingsSidebar() {
      <nav className="flex-1 min-h-0 overflow-y-auto scrollbar-auto-hide px-3 py-2">
        <div className="flex flex-col gap-0.5">
          <SidebarNavItem to="/company/settings" label="General" icon={SlidersHorizontal} end />
-          <SidebarNavItem
-            to={`${INSTANCE_SETTINGS_PATH_PREFIX}/profile`}
-            label="Profile"
-            icon={UserRoundPen}
-            end
-          />
+          {showPage("instance.profile") && (
+            <SidebarNavItem
+              to={`${INSTANCE_SETTINGS_PATH_PREFIX}/profile`}
+              label="Profile"
+              icon={UserRoundPen}
+              end
+            />
+          )}
          <SidebarNavItem
            to="/company/settings/members"
            label="Members"
@@ -116,37 +125,47 @@ export function CompanySettingsSidebar() {
            ))}
          <SidebarNavItem to="/company/settings/invites" label="Invites" icon={MailPlus} end />
          <SidebarNavItem to="/company/settings/secrets" label="Secrets" icon={KeyRound} end />
-          <SidebarNavItem
-            to={`${INSTANCE_SETTINGS_PATH_PREFIX}/environments`}
-            label="Environments"
-            icon={MonitorCog}
-            end
-          />
-          <SidebarNavItem
-            to={`${INSTANCE_SETTINGS_PATH_PREFIX}/access`}
-            label="Access"
-            icon={Shield}
-            end
-          />
-          <SidebarNavItem
-            to={`${INSTANCE_SETTINGS_PATH_PREFIX}/heartbeats`}
-            label="Heartbeats"
-            icon={Clock3}
-            end
-          />
+          {showPage("instance.environments") && (
+            <SidebarNavItem
+              to={`${INSTANCE_SETTINGS_PATH_PREFIX}/environments`}
+              label="Environments"
+              icon={MonitorCog}
+              end
+            />
+          )}
+          {showPage("instance.access") && (
+            <SidebarNavItem
+              to={`${INSTANCE_SETTINGS_PATH_PREFIX}/access`}
+              label="Access"
+              icon={Shield}
+              end
+            />
+          )}
+          {showPage("instance.heartbeats") && (
+            <SidebarNavItem
+              to={`${INSTANCE_SETTINGS_PATH_PREFIX}/heartbeats`}
+              label="Heartbeats"
+              icon={Clock3}
+              end
+            />
+          )}
          <SidebarNavItem to="/company/export" label="Export" icon={Download} />
          <SidebarNavItem to="/company/import" label="Import" icon={Upload} end />
-          <SidebarNavItem
-            to={`${INSTANCE_SETTINGS_PATH_PREFIX}/experimental`}
-            label="Experimental"
-            icon={FlaskConical}
-          />
-          <SidebarNavItem
-            to={`${INSTANCE_SETTINGS_PATH_PREFIX}/plugins`}
-            label="Plugins"
-            icon={Puzzle}
-          />
-          {sidebarPlugins.length > 0 ? (
+          {showPage("instance.experimental") && (
+            <SidebarNavItem
+              to={`${INSTANCE_SETTINGS_PATH_PREFIX}/experimental`}
+              label="Experimental"
+              icon={FlaskConical}
+            />
+          )}
+          {showPlugins && (
+            <SidebarNavItem
+              to={`${INSTANCE_SETTINGS_PATH_PREFIX}/plugins`}
+              label="Plugins"
+              icon={Puzzle}
+            />
+          )}
+          {showPlugins && sidebarPlugins.length > 0 ? (
            <div className="ml-4 mt-1 flex flex-col gap-0.5 border-l border-border/70 pl-3">
              {sidebarPlugins.map((plugin) => (
                <NavLink
@@ -167,11 +186,13 @@ export function CompanySettingsSidebar() {
              ))}
            </div>
          ) : null}
-          <SidebarNavItem
-            to={`${INSTANCE_SETTINGS_PATH_PREFIX}/adapters`}
-            label="Adapters"
-            icon={Cpu}
-          />
+          {showPage("instance.adapters") && (
+            <SidebarNavItem
+              to={`${INSTANCE_SETTINGS_PATH_PREFIX}/adapters`}
+              label="Adapters"
+              icon={Cpu}
+            />
+          )}
        </div>
      </nav>
    </aside>
@@ -0,0 +1,88 @@
+// @vitest-environment jsdom
+
+import { flushSync } from "react-dom";
+import { createRoot, type Root } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { queryKeys } from "@/lib/queryKeys";
+import { HiddenSettingsPageGate } from "./HiddenSettingsPageGate";
+
+vi.mock("@/lib/router", () => ({
+  Navigate: ({ to, replace }: { to: string; replace?: boolean }) => (
+    <div data-testid="navigate" data-to={to} data-replace={String(replace)} />
+  ),
+  Outlet: () => <div data-testid="page-content">Page content</div>,
+}));
+
+async function flushReact() {
+  for (let index = 0; index < 5; index += 1) {
+    await Promise.resolve();
+    await new Promise((resolve) => window.setTimeout(resolve, 0));
+  }
+  flushSync(() => {});
+}
+
+describe("HiddenSettingsPageGate", () => {
+  let container: HTMLDivElement;
+  let root: Root | null = null;
+
+  async function renderGate(pageKey: string, health?: Record<string, unknown>) {
+    root = createRoot(container);
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    if (health !== undefined) {
+      queryClient.setQueryData(queryKeys.health, health);
+    }
+    flushSync(() => {
+      root!.render(
+        <QueryClientProvider client={queryClient}>
+          <HiddenSettingsPageGate pageKey={pageKey} />
+        </QueryClientProvider>,
+      );
+    });
+    await flushReact();
+  }
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    flushSync(() => root?.unmount());
+    root = null;
+    container.remove();
+    vi.clearAllMocks();
+  });
+
+  it("redirects to the settings root when the page is operator-hidden", async () => {
+    await renderGate("instance.plugins", {
+      status: "ok",
+      hiddenSettings: ["instance.plugins", "instance.adapters"],
+    });
+
+    expect(container.querySelector('[data-testid="navigate"]')?.getAttribute("data-to")).toBe(
+      "/company/settings",
+    );
+    expect(container.querySelector('[data-testid="page-content"]')).toBeNull();
+  });
+
+  it("renders the page when it is not hidden", async () => {
+    await renderGate("instance.plugins", { status: "ok", hiddenSettings: ["instance.access"] });
+
+    expect(container.querySelector('[data-testid="page-content"]')).not.toBeNull();
+    expect(container.querySelector('[data-testid="navigate"]')).toBeNull();
+  });
+
+  it("renders the page when nothing is hidden at all", async () => {
+    await renderGate("instance.adapters", { status: "ok" });
+
+    expect(container.querySelector('[data-testid="page-content"]')).not.toBeNull();
+  });
+
+  it("renders nothing until health is cached", async () => {
+    await renderGate("instance.plugins");
+
+    expect(container.querySelector('[data-testid="page-content"]')).toBeNull();
+    expect(container.querySelector('[data-testid="navigate"]')).toBeNull();
+  });
+});
@@ -0,0 +1,17 @@
+import { Navigate, Outlet } from "@/lib/router";
+import { useHiddenSettings } from "@/hooks/useHiddenSettings";
+
+/**
+ * Route gate for instance-settings pages the hosting operator can hide
+ * (`instance.access`, `instance.plugins`, `instance.adapters`). Hidden pages
+ * redirect to the settings root instead of rendering; until health is cached
+ * nothing renders, so a hidden page never flashes. Under CloudAccessGate the
+ * health response is always cached before board routes mount.
+ */
+export function HiddenSettingsPageGate({ pageKey }: { pageKey: string }) {
+  const { hidden, loaded } = useHiddenSettings();
+
+  if (!loaded) return null;
+  if (hidden.has(pageKey)) return <Navigate to="/company/settings" replace />;
+  return <Outlet />;
+}
@@ -1,288 +0,0 @@
-// @vitest-environment jsdom
-
-import type { ReactNode } from "react";
-import { createRoot } from "react-dom/client";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { PluginRecord } from "@paperclipai/shared";
-
-const mockPluginsApi = vi.hoisted(() => ({
-  list: vi.fn(),
-}));
-
-vi.mock("@/api/plugins", () => ({
-  pluginsApi: mockPluginsApi,
-}));
-
-vi.mock("@/lib/router", () => ({
-  NavLink: ({
-    children,
-    to,
-    className,
-  }: {
-    children: ReactNode | ((arg: { isActive: boolean }) => ReactNode);
-    to: string;
-    state?: unknown;
-    end?: boolean;
-    onClick?: () => void;
-    className?: string | ((arg: { isActive: boolean }) => string);
-  }) => {
-    const resolvedClass =
-      typeof className === "function" ? className({ isActive: false }) : className;
-    const content = typeof children === "function" ? children({ isActive: false }) : children;
-    return (
-      <a href={to} className={resolvedClass}>
-        {content}
-      </a>
-    );
-  },
-}));
-
-vi.mock("../context/SidebarContext", () => ({
-  useSidebar: () => ({ isMobile: false, setSidebarOpen: vi.fn() }),
-}));
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
-
-import { InstanceSidebar } from "./InstanceSidebar";
-
-async function act(callback: () => void | Promise<void>) {
-  await callback();
-  await Promise.resolve();
-  await new Promise((resolve) => window.setTimeout(resolve, 0));
-}
-
-function makePlugin(overrides: Partial<PluginRecord> & { manifestJson: PluginRecord["manifestJson"] }): PluginRecord {
-  return {
-    id: overrides.id ?? "plugin-id",
-    pluginKey: overrides.pluginKey ?? "plugin-key",
-    packageName: overrides.packageName ?? "@scope/pkg",
-    version: overrides.version ?? "1.0.0",
-    apiVersion: overrides.apiVersion ?? 1,
-    categories: overrides.categories ?? [],
-    manifestJson: overrides.manifestJson,
-    status: overrides.status ?? "ready",
-    installOrder: overrides.installOrder ?? 0,
-    packagePath: overrides.packagePath ?? null,
-    lastError: overrides.lastError ?? null,
-    installedAt: overrides.installedAt ?? new Date(0),
-    updatedAt: overrides.updatedAt ?? new Date(0),
-  };
-}
-
-async function flushReact() {
-  await act(async () => {
-    await Promise.resolve();
-    await new Promise((resolve) => window.setTimeout(resolve, 0));
-  });
-}
-
-async function findPluginLinks(container: HTMLElement, expectedCount: number) {
-  await act(async () => {
-    await vi.waitFor(() => {
-      expect(container.querySelectorAll('a[href^="/company/settings/instance/plugins/"]')).toHaveLength(expectedCount);
-    });
-  });
-  return Array.from(container.querySelectorAll<HTMLAnchorElement>('a[href^="/company/settings/instance/plugins/"]'));
-}
-
-function renderSidebar(container: HTMLElement) {
-  const queryClient = new QueryClient({
-    defaultOptions: { queries: { retry: false, gcTime: 0 } },
-  });
-  const root = createRoot(container);
-  act(() => {
-    root.render(
-      <QueryClientProvider client={queryClient}>
-        <InstanceSidebar />
-      </QueryClientProvider>,
-    );
-  });
-  return { root, queryClient };
-}
-
-describe("InstanceSidebar", () => {
-  let container: HTMLDivElement;
-  let root: ReturnType<typeof createRoot> | null;
-  let queryClient: QueryClient | null;
-
-  beforeEach(() => {
-    container = document.createElement("div");
-    document.body.appendChild(container);
-    root = null;
-    queryClient = null;
-    mockPluginsApi.list.mockReset();
-  });
-
-  afterEach(async () => {
-    if (root) {
-      const currentRoot = root;
-      await act(async () => {
-        currentRoot.unmount();
-      });
-    }
-    queryClient?.clear();
-    container.remove();
-    document.body.innerHTML = "";
-    vi.clearAllMocks();
-  });
-
-  it("filters out sandbox-provider-only plugins from the sidebar", async () => {
-    const sandboxPlugin = makePlugin({
-      id: "e2b",
-      packageName: "@paperclipai/plugin-e2b",
-      manifestJson: {
-        id: "e2b",
-        name: "E2B Sandbox Provider",
-        displayName: "E2B Sandbox Provider",
-        version: "1.0.0",
-        apiVersion: 1,
-        environmentDrivers: [
-          {
-            driverKey: "e2b",
-            kind: "sandbox_provider",
-            displayName: "E2B",
-            configSchema: { type: "object" },
-          },
-        ],
-      } as unknown as PluginRecord["manifestJson"],
-    });
-    const regularPlugin = makePlugin({
-      id: "linear",
-      packageName: "@paperclipai/plugin-linear",
-      manifestJson: {
-        id: "linear",
-        name: "Linear",
-        displayName: "Linear",
-        version: "1.0.0",
-        apiVersion: 1,
-      } as unknown as PluginRecord["manifestJson"],
-    });
-    mockPluginsApi.list.mockResolvedValue([sandboxPlugin, regularPlugin]);
-
-    const rendered = renderSidebar(container);
-    root = rendered.root;
-    queryClient = rendered.queryClient;
-    await flushReact();
-
-    const pluginLinks = await findPluginLinks(container, 1);
-    expect(pluginLinks[0]?.getAttribute("href")).toBe("/company/settings/instance/plugins/linear");
-    expect(pluginLinks[0]?.textContent).toBe("Linear");
-    expect(container.textContent).not.toContain("Access");
-    expect(container.textContent).not.toContain("Heartbeats");
-  });
-
-  it("keeps plugins that mix sandbox-provider with other contributions", async () => {
-    const hybridPlugin = makePlugin({
-      id: "hybrid",
-      packageName: "@example/plugin-hybrid",
-      manifestJson: {
-        id: "hybrid",
-        name: "Hybrid",
-        displayName: "Hybrid",
-        version: "1.0.0",
-        apiVersion: 1,
-        environmentDrivers: [
-          {
-            driverKey: "sb",
-            kind: "sandbox_provider",
-            displayName: "SB",
-            configSchema: { type: "object" },
-          },
-          {
-            driverKey: "env",
-            kind: "environment_driver",
-            displayName: "Env",
-            configSchema: { type: "object" },
-          },
-        ],
-      } as unknown as PluginRecord["manifestJson"],
-    });
-    mockPluginsApi.list.mockResolvedValue([hybridPlugin]);
-
-    const rendered = renderSidebar(container);
-    root = rendered.root;
-    queryClient = rendered.queryClient;
-    await flushReact();
-
-    const pluginLinks = await findPluginLinks(container, 1);
-    expect(pluginLinks[0]?.getAttribute("href")).toBe("/company/settings/instance/plugins/hybrid");
-  });
-
-  it("renders the indented plugin list between the Plugins and Adapters rows", async () => {
-    mockPluginsApi.list.mockResolvedValue([
-      makePlugin({
-        id: "linear",
-        packageName: "@paperclipai/plugin-linear",
-        manifestJson: {
-          id: "linear",
-          name: "Linear",
-          displayName: "Linear",
-          version: "1.0.0",
-          apiVersion: 1,
-        } as unknown as PluginRecord["manifestJson"],
-      }),
-    ]);
-
-    const rendered = renderSidebar(container);
-    root = rendered.root;
-    queryClient = rendered.queryClient;
-    await flushReact();
-    await findPluginLinks(container, 1);
-
-    await vi.waitFor(() => {
-      const links = Array.from(
-        container.querySelectorAll<HTMLAnchorElement>('a[href^="/company/settings/instance/"]'),
-      );
-      expect(links.some((a) => a.getAttribute("href") === "/company/settings/instance/plugins/linear")).toBe(true);
-    });
-
-    const topLevelLinks = Array.from(container.querySelectorAll<HTMLAnchorElement>('a[href^="/company/settings/instance/"]'));
-    const hrefs = topLevelLinks.map((a) => a.getAttribute("href"));
-
-    const pluginsIndex = hrefs.indexOf("/company/settings/instance/plugins");
-    const adaptersIndex = hrefs.indexOf("/company/settings/instance/adapters");
-    const linearIndex = hrefs.indexOf("/company/settings/instance/plugins/linear");
-
-    expect(pluginsIndex).toBeGreaterThanOrEqual(0);
-    expect(adaptersIndex).toBeGreaterThan(pluginsIndex);
-    expect(linearIndex).toBeGreaterThan(pluginsIndex);
-    expect(linearIndex).toBeLessThan(adaptersIndex);
-  });
-
-  it("does not render the indented group when every plugin is filtered out", async () => {
-    mockPluginsApi.list.mockResolvedValue([
-      makePlugin({
-        id: "e2b",
-        packageName: "@paperclipai/plugin-e2b",
-        manifestJson: {
-          id: "e2b",
-          name: "E2B",
-          displayName: "E2B",
-          version: "1.0.0",
-          apiVersion: 1,
-          environmentDrivers: [
-            {
-              driverKey: "e2b",
-              kind: "sandbox_provider",
-              displayName: "E2B",
-              configSchema: { type: "object" },
-            },
-          ],
-        } as unknown as PluginRecord["manifestJson"],
-      }),
-    ]);
-
-    const rendered = renderSidebar(container);
-    root = rendered.root;
-    queryClient = rendered.queryClient;
-    await flushReact();
-
-    await vi.waitFor(() => {
-      expect(mockPluginsApi.list).toHaveBeenCalled();
-    });
-    const pluginLinks = Array.from(container.querySelectorAll('a[href^="/company/settings/instance/plugins/"]'));
-    expect(pluginLinks).toHaveLength(0);
-  });
-});
@@ -1,66 +0,0 @@
-import { useQuery } from "@tanstack/react-query";
-import { Cpu, FlaskConical, MonitorCog, Puzzle, SlidersHorizontal, UserRoundPen } from "lucide-react";
-import type { PluginRecord } from "@paperclipai/shared";
-import { NavLink } from "@/lib/router";
-import { pluginsApi } from "@/api/plugins";
-import { INSTANCE_SETTINGS_PATH_PREFIX } from "@/lib/instance-settings";
-import { queryKeys } from "@/lib/queryKeys";
-import { SIDEBAR_SCROLL_RESET_STATE } from "@/lib/navigation-scroll";
-import { SidebarNavItem } from "./SidebarNavItem";
-
-/**
- * Sandbox-provider-only plugins (e.g. E2B, exe.dev, Modal) have no per-plugin
- * settings page — `PluginSettings` redirects them to the Environments page —
- * so a sidebar entry would lead nowhere useful. Filter them out here. Plugins
- * that mix a sandbox provider with other contributions still appear.
- */
-function isSandboxProviderOnly(plugin: PluginRecord): boolean {
-  const drivers = plugin.manifestJson.environmentDrivers ?? [];
-  if (drivers.length === 0) return false;
-  return drivers.every((d) => d.kind === "sandbox_provider");
-}
-
-export function InstanceSidebar() {
-  const { data: plugins } = useQuery({
-    queryKey: queryKeys.plugins.all,
-    queryFn: () => pluginsApi.list(),
-  });
-
-  const sidebarPlugins = (plugins ?? []).filter((p) => !isSandboxProviderOnly(p));
-
-  return (
-    <aside className="w-full h-full min-h-0 border-r border-border bg-background flex flex-col">
-      <nav className="flex-1 min-h-0 overflow-y-auto scrollbar-auto-hide flex flex-col gap-4 px-3 py-2">
-        <div className="flex flex-col gap-0.5">
-          <SidebarNavItem to={`${INSTANCE_SETTINGS_PATH_PREFIX}/profile`} label="Profile" icon={UserRoundPen} end />
-          <SidebarNavItem to={`${INSTANCE_SETTINGS_PATH_PREFIX}/general`} label="General" icon={SlidersHorizontal} end />
-          <SidebarNavItem to={`${INSTANCE_SETTINGS_PATH_PREFIX}/environments`} label="Environments" icon={MonitorCog} end />
-          <SidebarNavItem to={`${INSTANCE_SETTINGS_PATH_PREFIX}/experimental`} label="Experimental" icon={FlaskConical} />
-          <SidebarNavItem to={`${INSTANCE_SETTINGS_PATH_PREFIX}/plugins`} label="Plugins" icon={Puzzle} />
-          {sidebarPlugins.length > 0 ? (
-            <div className="ml-4 mt-1 flex flex-col gap-0.5 border-l border-border/70 pl-3">
-              {sidebarPlugins.map((plugin) => (
-                <NavLink
-                  key={plugin.id}
-                  to={`${INSTANCE_SETTINGS_PATH_PREFIX}/plugins/${plugin.id}`}
-                  state={SIDEBAR_SCROLL_RESET_STATE}
-                  className={({ isActive }) =>
-                    [
-                      "rounded-md px-2 py-1.5 text-xs transition-colors",
-                      isActive
-                        ? "bg-accent text-foreground"
-                        : "text-muted-foreground hover:bg-accent/50 hover:text-foreground",
-                    ].join(" ")
-                  }
-                >
-                  {plugin.manifestJson.displayName ?? plugin.packageName}
-                </NavLink>
-              ))}
-            </div>
-          ) : null}
-          <SidebarNavItem to={`${INSTANCE_SETTINGS_PATH_PREFIX}/adapters`} label="Adapters" icon={Cpu} />
-        </div>
-      </nav>
-    </aside>
-  );
-}
@@ -2,7 +2,9 @@

 import { createRoot } from "react-dom/client";
 import { flushSync } from "react-dom";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { queryKeys } from "@/lib/queryKeys";
 import { CompanySettingsNav, getCompanySettingsTab } from "./CompanySettingsNav";

 let currentPathname = "/company/settings";
@@ -89,12 +91,25 @@ describe("CompanySettingsNav", () => {
    expect(getCompanySettingsTab("/company/settings/instance/adapters")).toBe("instance-adapters");
  });

+  function renderNav(root: ReturnType<typeof createRoot>, hiddenSettings?: string[]) {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    queryClient.setQueryData(queryKeys.health, {
+      status: "ok",
+      ...(hiddenSettings ? { hiddenSettings } : {}),
+    });
+    root.render(
+      <QueryClientProvider client={queryClient}>
+        <CompanySettingsNav />
+      </QueryClientProvider>,
+    );
+  }
+
  it("renders the active tab and navigates when a different tab is selected", async () => {
    currentPathname = "/PAP/company/settings/members";
    const root = createRoot(container);

    await act(async () => {
-      root.render(<CompanySettingsNav />);
+      renderNav(root);
    });

    expect(container.textContent).toContain("members");
@@ -132,4 +147,34 @@ describe("CompanySettingsNav", () => {
      root.unmount();
    });
  });
+
+  it("filters operator-hidden tabs out of the tab bar", async () => {
+    currentPathname = "/PAP/company/settings/members";
+    const root = createRoot(container);
+
+    await act(async () => {
+      renderNav(root, ["instance.plugins", "instance.heartbeats"]);
+    });
+
+    const renderedValues = pageTabBarMock.mock.calls.at(-1)?.[0]?.items?.map(
+      (item: { value: string }) => item.value,
+    );
+    expect(renderedValues).toEqual([
+      "general",
+      "export",
+      "import",
+      "members",
+      "invites",
+      "secrets",
+      "instance-profile",
+      "instance-environments",
+      "instance-access",
+      "instance-experimental",
+      "instance-adapters",
+    ]);
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
 });
@@ -1,5 +1,6 @@
 import { PageTabBar } from "@/components/PageTabBar";
 import { Tabs } from "@/components/ui/tabs";
+import { useHiddenSettings } from "@/hooks/useHiddenSettings";
 import { INSTANCE_SETTINGS_PATH_PREFIX } from "@/lib/instance-settings";
 import { useLocation, useNavigate } from "@/lib/router";

@@ -21,6 +22,17 @@ const items = [

 type CompanySettingsTab = (typeof items)[number]["value"];

+/** Tab values suppressed when their page is operator-hidden. */
+const hiddenSettingKeyByTab: Partial<Record<CompanySettingsTab, string>> = {
+  "instance-profile": "instance.profile",
+  "instance-environments": "instance.environments",
+  "instance-access": "instance.access",
+  "instance-heartbeats": "instance.heartbeats",
+  "instance-experimental": "instance.experimental",
+  "instance-plugins": "instance.plugins",
+  "instance-adapters": "instance.adapters",
+};
+
 export function getCompanySettingsTab(pathname: string): CompanySettingsTab {
  if (pathname.includes(`${INSTANCE_SETTINGS_PATH_PREFIX}/profile`)) {
    return "instance-profile";
@@ -84,10 +96,15 @@ export function getCompanySettingsTab(pathname: string): CompanySettingsTab {
 export function CompanySettingsNav() {
  const location = useLocation();
  const navigate = useNavigate();
+  const { hidden: hiddenSettings } = useHiddenSettings();
  const activeTab = getCompanySettingsTab(location.pathname);
+  const visibleItems = items.filter((item) => {
+    const hiddenKey = hiddenSettingKeyByTab[item.value];
+    return !hiddenKey || !hiddenSettings.has(hiddenKey);
+  });

  function handleTabChange(value: string) {
-    const nextTab = items.find((item) => item.value === value);
+    const nextTab = visibleItems.find((item) => item.value === value);
    if (!nextTab || nextTab.value === activeTab) return;
    navigate(nextTab.href);
  }
@@ -95,7 +112,7 @@ export function CompanySettingsNav() {
  return (
    <Tabs value={activeTab} onValueChange={handleTabChange}>
      <PageTabBar
-        items={items.map(({ value, label }) => ({ value, label }))}
+        items={visibleItems.map(({ value, label }) => ({ value, label }))}
        value={activeTab}
        onValueChange={handleTabChange}
        align="start"
@@ -0,0 +1,27 @@
+import { useMemo } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { healthApi } from "@/api/health";
+import { queryKeys } from "@/lib/queryKeys";
+
+/**
+ * Settings surfaces hidden by the hosting operator, from the app-wide health
+ * query cache (keys from the shared settings-visibility registry, e.g.
+ * "instance.plugins" or "instance.experimental.enableSmokeLab").
+ * CloudAccessGate owns the fetch; this observer never issues its own request.
+ *
+ * `loaded` is false until the health response is in the cache — gates should
+ * render nothing rather than flash a surface that may turn out to be hidden.
+ */
+export function useHiddenSettings(): { hidden: ReadonlySet<string>; loaded: boolean } {
+  const healthQuery = useQuery({
+    queryKey: queryKeys.health,
+    queryFn: () => healthApi.get(),
+    enabled: false,
+  });
+
+  const data = healthQuery.data;
+  return useMemo(
+    () => ({ hidden: new Set(data?.hiddenSettings ?? []), loaded: data !== undefined }),
+    [data],
+  );
+}
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
  DEFAULT_INSTANCE_SETTINGS_PATH,
+  filterHiddenInstanceSettingsPath,
  normalizeRememberedInstanceSettingsPath,
 } from "./instance-settings";

@@ -48,3 +49,29 @@ describe("normalizeRememberedInstanceSettingsPath", () => {
    expect(normalizeRememberedInstanceSettingsPath(null)).toBe(DEFAULT_INSTANCE_SETTINGS_PATH);
  });
 });
+
+describe("filterHiddenInstanceSettingsPath", () => {
+  const hidden = new Set(["instance.plugins", "instance.heartbeats"]);
+
+  it("remaps hidden pages (including sub-paths) to the default settings path", () => {
+    expect(
+      filterHiddenInstanceSettingsPath("/company/settings/instance/plugins", hidden),
+    ).toBe(DEFAULT_INSTANCE_SETTINGS_PATH);
+    expect(
+      filterHiddenInstanceSettingsPath("/company/settings/instance/plugins/plugin-1", hidden),
+    ).toBe(DEFAULT_INSTANCE_SETTINGS_PATH);
+    expect(
+      filterHiddenInstanceSettingsPath("/company/settings/instance/heartbeats", hidden),
+    ).toBe(DEFAULT_INSTANCE_SETTINGS_PATH);
+  });
+
+  it("keeps visible pages and non-settings paths untouched", () => {
+    expect(
+      filterHiddenInstanceSettingsPath("/company/settings/instance/experimental", hidden),
+    ).toBe("/company/settings/instance/experimental");
+    expect(filterHiddenInstanceSettingsPath("/dashboard", hidden)).toBe("/dashboard");
+    expect(
+      filterHiddenInstanceSettingsPath("/company/settings/instance/plugins", new Set()),
+    ).toBe("/company/settings/instance/plugins");
+  });
+});
@@ -79,3 +79,23 @@ export function normalizeRememberedInstanceSettingsPath(rawPath: string | null):

  return DEFAULT_INSTANCE_SETTINGS_PATH;
 }
+
+/**
+ * Remaps a remembered instance-settings path onto the settings root when its
+ * page is hidden by the hosting operator (`hidden` holds keys from the shared
+ * settings-visibility registry). Saves a redirect hop; the route-level
+ * HiddenSettingsPageGate stays the enforcement point.
+ */
+export function filterHiddenInstanceSettingsPath(
+  normalizedPath: string,
+  hidden: ReadonlySet<string>,
+): string {
+  const { pathname } = splitPath(normalizedPath);
+  const suffix = instanceSettingsSuffix(pathname);
+  if (!suffix) return normalizedPath;
+  const page = suffix.split("/")[1];
+  if (page && page !== "general" && hidden.has(`instance.${page}`)) {
+    return DEFAULT_INSTANCE_SETTINGS_PATH;
+  }
+  return normalizedPath;
+}
@@ -931,3 +931,55 @@ describe("InstanceExperimentalSettings — card ordering and headings (PAP-393)"
    expect(badges).not.toContain("Experimental");
  });
 });
+
+describe("InstanceExperimentalSettings — operator-hidden cards", () => {
+  let container: HTMLDivElement;
+  let root: Root | null = null;
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    flushSync(() => root?.unmount());
+    root = null;
+    queryClient?.clear();
+    container.remove();
+    vi.clearAllMocks();
+  });
+
+  async function renderPage(hiddenSettings?: string[]) {
+    mockInstanceSettingsApi.getExperimental.mockResolvedValue(defaultExperimentalSettings());
+    root = createRoot(container);
+    queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    queryClient.setQueryData(queryKeys.health, {
+      status: "ok",
+      ...(hiddenSettings ? { hiddenSettings } : {}),
+    });
+    flushSync(() => {
+      root!.render(
+        <QueryClientProvider client={queryClient}>
+          <InstanceExperimentalSettings />
+        </QueryClientProvider>,
+      );
+    });
+    await flushReact();
+  }
+
+  it("renders nothing for an operator-hidden toggle and keeps the rest", async () => {
+    await renderPage(["instance.experimental.enableEnvironments"]);
+
+    expect(container.textContent).not.toContain("Enable Environments");
+    expect(container.textContent).toContain("Beta skills");
+    expect(container.textContent).toContain("Task Watchdogs");
+  });
+
+  it("shows every toggle when nothing is hidden", async () => {
+    await renderPage();
+
+    expect(container.textContent).toContain("Enable Environments");
+    expect(container.textContent).toContain("Beta skills");
+  });
+});
@@ -4,11 +4,14 @@ import { AlertTriangle, Clock, FlaskConical, Lock, Play, Search } from "lucide-r
 import type {
  InstanceExperimentalSettings,
  InstanceExperimentalSettingsWithManaged,
+  InstanceFeatureKey,
  IssueGraphLivenessAutoRecoveryPreview,
  ManagedSettingMetadata,
  PatchInstanceExperimentalSettings,
 } from "@paperclipai/shared";
+import { experimentalSettingKey } from "@paperclipai/shared";
 import { instanceSettingsApi } from "@/api/instanceSettings";
+import { useHiddenSettings } from "@/hooks/useHiddenSettings";
 import { getWorktreeInstanceId, isWorktreeRuntime } from "../lib/worktree-branding";
 import { useBreadcrumbs } from "../context/BreadcrumbContext";
 import { queryKeys } from "../lib/queryKeys";
@@ -92,6 +95,7 @@ function ExperimentalToggleCard({
  checked,
  onCheckedChange,
  disabled,
+  settingKey,
  managed,
  ariaLabel,
 }: {
@@ -101,10 +105,14 @@ function ExperimentalToggleCard({
  checked: boolean;
  onCheckedChange: (checked: boolean) => void;
  disabled: boolean;
+  /** Flag key backing this card; operator-hidden keys render nothing. */
+  settingKey: InstanceFeatureKey;
  managed?: ManagedSettingMetadata;
  ariaLabel: string;
 }) {
+  const { hidden: hiddenSettings } = useHiddenSettings();
  const isManaged = managed?.managed === true;
+  if (hiddenSettings.has(experimentalSettingKey(settingKey))) return null;
  return (
    <Card className="block p-5">
      <div className="flex items-start justify-between gap-4">
@@ -465,6 +473,7 @@ export function InstanceExperimentalSettings() {
        checked={enableApps}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableApps: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableApps"
        managed={managedKeys.enableApps}
        ariaLabel="Toggle apps experimental setting"
      />
@@ -565,6 +574,7 @@ export function InstanceExperimentalSettings() {
        checked={autoRestartDevServerWhenIdle}
        onCheckedChange={(checked) => toggleMutation.mutate({ autoRestartDevServerWhenIdle: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="autoRestartDevServerWhenIdle"
        managed={managedKeys.autoRestartDevServerWhenIdle}
        ariaLabel="Toggle guarded dev-server auto-restart"
      />
@@ -575,6 +585,7 @@ export function InstanceExperimentalSettings() {
        checked={enableBetaSkills}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableBetaSkills: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableBetaSkills"
        managed={managedKeys.enableBetaSkills}
        ariaLabel="Toggle beta skills experimental setting"
      />
@@ -585,6 +596,7 @@ export function InstanceExperimentalSettings() {
        checked={enableBuiltInAgents}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableBuiltInAgents: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableBuiltInAgents"
        managed={managedKeys.enableBuiltInAgents}
        ariaLabel="Toggle built-in agents experimental setting"
      />
@@ -596,6 +608,7 @@ export function InstanceExperimentalSettings() {
        checked={enableCases}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableCases: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableCases"
        managed={managedKeys.enableCases}
        ariaLabel="Toggle cases experimental setting"
      />
@@ -607,6 +620,7 @@ export function InstanceExperimentalSettings() {
        checked={enableClassicTaskInterface}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableClassicTaskInterface: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableClassicTaskInterface"
        managed={managedKeys.enableClassicTaskInterface}
        ariaLabel="Toggle classic task interface experimental setting"
      />
@@ -618,6 +632,7 @@ export function InstanceExperimentalSettings() {
          checked={enableConferenceRoomChat}
          onCheckedChange={(checked) => toggleMutation.mutate({ enableConferenceRoomChat: checked })}
          disabled={toggleMutation.isPending}
+          settingKey="enableConferenceRoomChat"
          managed={managedKeys.enableConferenceRoomChat}
          ariaLabel="Toggle conference room chat experimental setting"
        />
@@ -629,6 +644,7 @@ export function InstanceExperimentalSettings() {
        checked={enableDecisions}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableDecisions: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableDecisions"
        managed={managedKeys.enableDecisions}
        ariaLabel="Toggle decisions experimental setting"
      />
@@ -639,6 +655,7 @@ export function InstanceExperimentalSettings() {
        checked={enableEnvironments}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableEnvironments: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableEnvironments"
        managed={managedKeys.enableEnvironments}
        ariaLabel="Toggle environments experimental setting"
      />
@@ -649,6 +666,7 @@ export function InstanceExperimentalSettings() {
        checked={enableExternalObjects}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableExternalObjects: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableExternalObjects"
        managed={managedKeys.enableExternalObjects}
        ariaLabel="Toggle external objects experimental setting"
      />
@@ -659,6 +677,7 @@ export function InstanceExperimentalSettings() {
        checked={enableIsolatedWorkspaces}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableIsolatedWorkspaces: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableIsolatedWorkspaces"
        managed={managedKeys.enableIsolatedWorkspaces}
        ariaLabel="Toggle isolated workspaces experimental setting"
      />
@@ -669,6 +688,7 @@ export function InstanceExperimentalSettings() {
        checked={enableExperimentalFileViewer}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableExperimentalFileViewer: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableExperimentalFileViewer"
        managed={managedKeys.enableExperimentalFileViewer}
        ariaLabel="Toggle experimental file viewer setting"
      />
@@ -679,6 +699,7 @@ export function InstanceExperimentalSettings() {
        checked={enableGoalsSidebarLink}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableGoalsSidebarLink: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableGoalsSidebarLink"
        managed={managedKeys.enableGoalsSidebarLink}
        ariaLabel="Toggle goals sidebar link experimental setting"
      />
@@ -689,6 +710,7 @@ export function InstanceExperimentalSettings() {
        checked={enableManagedSandboxOnly}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableManagedSandboxOnly: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableManagedSandboxOnly"
        managed={managedKeys.enableManagedSandboxOnly}
        ariaLabel="Toggle managed sandbox only experimental setting"
      />
@@ -756,6 +778,7 @@ export function InstanceExperimentalSettings() {
        checked={enableServerInfoDebugView}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableServerInfoDebugView: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableServerInfoDebugView"
        managed={managedKeys.enableServerInfoDebugView}
        ariaLabel="Toggle server info debug view experimental setting"
      />
@@ -768,6 +791,7 @@ export function InstanceExperimentalSettings() {
          toggleMutation.mutate({ enableSimplifiedEnglishInteractions: checked })
        }
        disabled={toggleMutation.isPending}
+        settingKey="enableSimplifiedEnglishInteractions"
        managed={managedKeys.enableSimplifiedEnglishInteractions}
        ariaLabel="Toggle simplified english interactions experimental setting"
      />
@@ -778,6 +802,7 @@ export function InstanceExperimentalSettings() {
        checked={enableSmokeLab}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableSmokeLab: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableSmokeLab"
        managed={managedKeys.enableSmokeLab}
        ariaLabel="Toggle smoke lab experimental setting"
      />
@@ -795,6 +820,7 @@ export function InstanceExperimentalSettings() {
          )
        }
        disabled={toggleMutation.isPending || statusCardsBlockedByManagedSummaries}
+        settingKey="enableStatusCards"
        managed={managedKeys.enableStatusCards}
        ariaLabel="Toggle status cards experimental setting"
      />
@@ -812,6 +838,7 @@ export function InstanceExperimentalSettings() {
          )
        }
        disabled={toggleMutation.isPending || summariesRequiredByManagedStatusCards}
+        settingKey="enableSummaries"
        managed={managedKeys.enableSummaries}
        ariaLabel="Toggle summaries experimental setting"
      />
@@ -822,6 +849,7 @@ export function InstanceExperimentalSettings() {
        checked={enableIssuePlanDecompositions}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableIssuePlanDecompositions: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableIssuePlanDecompositions"
        managed={managedKeys.enableIssuePlanDecompositions}
        ariaLabel="Toggle task plan decomposition panel experimental setting"
      />
@@ -832,6 +860,7 @@ export function InstanceExperimentalSettings() {
        checked={enableTaskWatchdogs}
        onCheckedChange={(checked) => toggleMutation.mutate({ enableTaskWatchdogs: checked })}
        disabled={toggleMutation.isPending}
+        settingKey="enableTaskWatchdogs"
        managed={managedKeys.enableTaskWatchdogs}
        ariaLabel="Toggle task watchdogs experimental setting"
      />
@@ -205,3 +205,67 @@ describe("InstanceGeneralSettings sign-out", () => {
    await vi.waitFor(() => expect(signOutButton()?.disabled).toBe(false));
  });
 });
+
+describe("InstanceGeneralSettings operator-hidden sections", () => {
+  let container: HTMLDivElement;
+  let root: Root | null;
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = null;
+    queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    mockInstanceSettingsApi.getGeneral.mockResolvedValue({
+      censorUsernameInLogs: false,
+      keyboardShortcuts: false,
+      feedbackDataSharingPreference: "not_allowed",
+      backupRetention: { dailyDays: 7, weeklyWeeks: 4, monthlyMonths: 1 },
+    });
+  });
+
+  afterEach(() => {
+    flushSync(() => root?.unmount());
+    queryClient.clear();
+    container.remove();
+    vi.clearAllMocks();
+  });
+
+  async function renderPage(health: Record<string, unknown>) {
+    mockHealthApi.get.mockResolvedValue(health);
+    queryClient.setQueryData(queryKeys.health, health);
+    root = createRoot(container);
+    flushSync(() => {
+      root?.render(
+        <QueryClientProvider client={queryClient}>
+          <InstanceGeneralSettings />
+        </QueryClientProvider>,
+      );
+    });
+    await vi.waitFor(() => expect(container.textContent).toContain("Keyboard shortcuts"));
+  }
+
+  it("hides an operator-hidden field-backed section and a UI-only section", async () => {
+    await renderPage({
+      ...SELF_HOSTED_HEALTH,
+      hiddenSettings: [
+        "instance.general.censorUsernameInLogs",
+        "instance.general.deploymentStatus",
+      ],
+    });
+
+    expect(container.textContent).not.toContain("Censor username in logs");
+    expect(container.textContent).not.toContain("Deployment and auth");
+    expect(container.textContent).toContain("Backup retention");
+    expect(container.textContent).toContain("AI feedback sharing");
+    expect(container.textContent).toContain("Sign out");
+  });
+
+  it("shows every section when nothing is hidden", async () => {
+    await renderPage(SELF_HOSTED_HEALTH);
+
+    expect(container.textContent).toContain("Deployment and auth");
+    expect(container.textContent).toContain("Censor username in logs");
+    expect(container.textContent).toContain("Backup retention");
+  });
+});
@@ -61,7 +61,7 @@ export function InstanceGeneralSettings({ embedded = false }: { embedded?: boole
    },
  });

-  if (generalQuery.isLoading) {
+  if (generalQuery.isLoading || healthQuery.isLoading) {
    return <div className="text-sm text-muted-foreground">Loading general settings...</div>;
  }

@@ -79,6 +79,22 @@ export function InstanceGeneralSettings({ embedded = false }: { embedded?: boole
  const keyboardShortcuts = generalQuery.data?.keyboardShortcuts === true;
  const feedbackDataSharingPreference = generalQuery.data?.feedbackDataSharingPreference ?? "prompt";
  const backupRetention: BackupRetentionPolicy = generalQuery.data?.backupRetention ?? DEFAULT_BACKUP_RETENTION;
+  const hiddenSettings = new Set(healthQuery.data?.hiddenSettings ?? []);
+  const showDeploymentStatus = !hiddenSettings.has("instance.general.deploymentStatus");
+  const showCensorUsernameInLogs = !hiddenSettings.has("instance.general.censorUsernameInLogs");
+  const showKeyboardShortcuts = !hiddenSettings.has("instance.general.keyboardShortcuts");
+  const showBackupRetention = !hiddenSettings.has("instance.general.backupRetention");
+  const showFeedbackDataSharing = !hiddenSettings.has("instance.general.feedbackDataSharingPreference");
+  const showSignOut = !hiddenSettings.has("instance.general.signOut");
+  const visibleTopics = [
+    ...(showCensorUsernameInLogs ? ["log display"] : []),
+    ...(showKeyboardShortcuts ? ["keyboard shortcuts"] : []),
+    ...(showBackupRetention ? ["backup retention"] : []),
+    ...(showFeedbackDataSharing ? ["data sharing"] : []),
+  ];
+  const topicSummary = visibleTopics.length > 2
+    ? `${visibleTopics.slice(0, -1).join(", ")}, and ${visibleTopics[visibleTopics.length - 1]}`
+    : visibleTopics.join(" and ");
  const visibleActionError = signOutMutation.error instanceof Error
    ? signOutMutation.error.message
    : signOutMutation.error
@@ -94,8 +110,8 @@ export function InstanceGeneralSettings({ embedded = false }: { embedded?: boole
            <h1 className="text-lg font-semibold">General</h1>
          </div>
          <p className="text-sm text-muted-foreground">
-            Configure instance-wide preferences including log display, keyboard shortcuts, backup
-            retention, and data sharing.
+            Configure instance-wide preferences
+            {visibleTopics.length > 0 ? <> including {topicSummary}</> : null}.
          </p>
        </div>
      ) : null}
@@ -106,6 +122,7 @@ export function InstanceGeneralSettings({ embedded = false }: { embedded?: boole
        </div>
      )}

+      {showDeploymentStatus && (
      <section>
        <div className="space-y-3">
          <div className="flex items-center gap-2">
@@ -138,7 +155,9 @@ export function InstanceGeneralSettings({ embedded = false }: { embedded?: boole
          </div>
        </div>
      </section>
+      )}

+      {showCensorUsernameInLogs && (
      <section>
        <div className="flex items-start justify-between gap-4">
          <div className="space-y-1.5">
@@ -157,7 +176,9 @@ export function InstanceGeneralSettings({ embedded = false }: { embedded?: boole
          />
        </div>
      </section>
+      )}

+      {showKeyboardShortcuts && (
      <section>
        <div className="flex items-start justify-between gap-4">
          <div className="space-y-1.5">
@@ -175,7 +196,9 @@ export function InstanceGeneralSettings({ embedded = false }: { embedded?: boole
          />
        </div>
      </section>
+      )}

+      {showBackupRetention && (
      <section>
        <div className="space-y-5">
          <div className="space-y-1.5">
@@ -277,7 +300,9 @@ export function InstanceGeneralSettings({ embedded = false }: { embedded?: boole
          </div>
        </div>
      </section>
+      )}

+      {showFeedbackDataSharing && (
      <section>
        <div className="space-y-4">
          <div className="space-y-1.5">
@@ -354,6 +379,9 @@ export function InstanceGeneralSettings({ embedded = false }: { embedded?: boole
        </div>
      </section>

+      )}
+
+      {showSignOut && (
      <section>
        <div className="flex items-start justify-between gap-4">
          <div className="space-y-1.5">
@@ -376,6 +404,7 @@ export function InstanceGeneralSettings({ embedded = false }: { embedded?: boole
          </Button>
        </div>
      </section>
+      )}
    </div>
  );
 }