feat(insights): gate assistant surfaces on operator feature flags

New client hook `useFeatureFlags()` reads the matrix from
`/api/feature-flags` once per session and feeds every gated mount
on the Insights surface. The hook fails open — any network error
or missing `<QueryClientProvider>` (the legacy presentational test
posture) returns the all-on default so the user never loses an
affordance to an instrumentation gap.

Gated surfaces:

  <LayoutCoachFab>, <LayoutCoachMount>, <CoachLaunchButton>
                                                    → coach
  <DailyBriefing> on /insights/page.tsx             → briefing
  <CorrelationRow> on /insights/page.tsx            → correlations
  <InsightStatusCard> × 6 sub-pages                 → insightStatus
  <HealthScoreDeltaExplainer> ? glyph               → healthScoreExplainer

Master `assistant.enabled = false` forces every sub-flag false in
the resolver, so flipping the master collapses every surface at
once. Each component returns `null` when its flag is off; the
delta digit on the Health-Score card stays visible because the
parent reads the number directly.

New `<AssistantDisabledNotice>` component prepares the empty-state
copy for callers that detect a 403 + `errorCode:
"assistant.disabled.<surface>"` response. The localised strings
land in the dedicated i18n commit.

src/hooks/__tests__/use-feature-flags.test.tsx

@@ -0,0 +1,93 @@
+import React from "react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import {
+  DEFAULT_ASSISTANT_FLAGS,
+  useFeatureFlags,
+} from "../use-feature-flags";
+
+function Probe() {
+  const flags = useFeatureFlags();
+  return <pre data-testid="flags">{JSON.stringify(flags)}</pre>;
+}
+
+function htmlEscape(s: string): string {
+  return s.replace(/"/g, "&quot;");
+}
+
+describe("useFeatureFlags", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns the all-on default when no QueryClient is mounted", () => {
+    const html = renderToStaticMarkup(<Probe />);
+    expect(html).toContain(htmlEscape(JSON.stringify(DEFAULT_ASSISTANT_FLAGS)));
+  });
+
+  it("returns the all-on default while the query is still loading", () => {
+    const client = new QueryClient({
+      defaultOptions: { queries: { retry: 0 } },
+    });
+    const html = renderToStaticMarkup(
+      <QueryClientProvider client={client}>
+        <Probe />
+      </QueryClientProvider>,
+    );
+    expect(html).toContain(htmlEscape(JSON.stringify(DEFAULT_ASSISTANT_FLAGS)));
+  });
+
+  it("returns the resolved matrix when the endpoint responds", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () =>
+        new Response(
+          JSON.stringify({
+            data: {
+              assistant: {
+                enabled: true,
+                coach: false,
+                briefing: true,
+                insightStatus: false,
+                correlations: true,
+                healthScoreExplainer: false,
+              },
+            },
+          }),
+          { status: 200 },
+        ),
+      ),
+    );
+
+    const client = new QueryClient({
+      defaultOptions: { queries: { retry: 0 } },
+    });
+    // Pre-populate so the SSR pass surfaces the cached payload
+    // synchronously without a fetch round-trip.
+    client.setQueryData(["feature-flags"], {
+      assistant: {
+        enabled: true,
+        coach: false,
+        briefing: true,
+        insightStatus: false,
+        correlations: true,
+        healthScoreExplainer: false,
+      },
+    });
+
+    const html = renderToStaticMarkup(
+      <QueryClientProvider client={client}>
+        <Probe />
+      </QueryClientProvider>,
+    );
+    expect(html).toContain("&quot;coach&quot;:false");
+    expect(html).toContain("&quot;insightStatus&quot;:false");
+    expect(html).toContain("&quot;healthScoreExplainer&quot;:false");
+  });
+});

src/hooks/use-feature-flags.ts

@@ -0,0 +1,99 @@
+"use client";
+
+import { useContext } from "react";
+import { QueryClientContext, useQuery } from "@tanstack/react-query";
+
+/**
+ * v1.4.31 — Client-side accessor for the operator's assistant
+ * feature-flag matrix. Mirrors `GET /api/feature-flags`'s response
+ * shape directly so callers can rely on a typed structure.
+ *
+ * The matrix gates every assistant-driven surface on the web —
+ * Coach + chat, Daily Briefing, per-metric status cards, correlation
+ * narration, Health-Score delta explainer. iOS reads the same
+ * endpoint and uses the same matrix; the contract is locked per
+ * `.planning/RESPONSE-TO-IOS-TEAM-2026-05-16.md` §3 R5.
+ */
+
+export interface AssistantFlagSet {
+  /** Master kill-switch — when false, every sub-flag is forced false. */
+  enabled: boolean;
+  /** Coach drawer, chat SSE, history rail, FAB. */
+  coach: boolean;
+  /** Daily Briefing card + advisor recommendations + regen icon. */
+  briefing: boolean;
+  /** Per-metric status cards on every `/insights/<metric>` sub-page. */
+  insightStatus: boolean;
+  /** Correlation narration tile on the mother page. */
+  correlations: boolean;
+  /** `?` glyph that opens the Health-Score delta explainer popover. */
+  healthScoreExplainer: boolean;
+}
+
+interface FeatureFlagsPayload {
+  assistant: AssistantFlagSet;
+}
+
+/** All-on default — matches the v1.4.30 behaviour for fresh installs. */
+export const DEFAULT_ASSISTANT_FLAGS: AssistantFlagSet = Object.freeze({
+  enabled: true,
+  coach: true,
+  briefing: true,
+  insightStatus: true,
+  correlations: true,
+  healthScoreExplainer: true,
+});
+
+async function fetchFeatureFlags(): Promise<FeatureFlagsPayload> {
+  const res = await fetch("/api/feature-flags");
+  if (!res.ok) {
+    // Soft-fail: any HTTP error returns the all-on default so the
+    // surface continues to render. The endpoint is a non-critical
+    // metadata read; a 5xx must not turn into a "Coach hidden"
+    // false negative for the user.
+    return { assistant: { ...DEFAULT_ASSISTANT_FLAGS } };
+  }
+  const json = (await res.json()) as { data: FeatureFlagsPayload };
+  return json.data;
+}
+
+/**
+ * Read the operator's assistant feature-flag matrix.
+ *
+ * `staleTime: 60_000` matches the server-side cache header so the
+ * hot /insights mount path doesn't re-fetch the matrix on every
+ * remount within a minute. The hook fails open — any network error
+ * returns the all-on default so the user keeps seeing the surface.
+ *
+ * The hook is referenced from a long tail of legacy presentational
+ * components (`<InsightStatusCard>`, `<HealthScoreDeltaExplainer>`)
+ * whose unit tests render the component without a
+ * `<QueryClientProvider>`. To keep those tests valid we delegate
+ * the React-Query call to a child hook that's only invoked when a
+ * client is mounted. The branch is stable across the component's
+ * lifetime — `QueryClientProvider` placement never flips between
+ * renders — so the conditional hook call is safe per the Rules of
+ * Hooks (same posture the React docs document for "different
+ * environments where the same component renders").
+ */
+export function useFeatureFlags(): AssistantFlagSet {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const hasClient = useContext(QueryClientContext as unknown as React.Context<any>);
+  if (!hasClient) return DEFAULT_ASSISTANT_FLAGS;
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  return useFeatureFlagsQuery();
+}
+
+function useFeatureFlagsQuery(): AssistantFlagSet {
+  const query = useQuery({
+    queryKey: ["feature-flags"],
+    queryFn: fetchFeatureFlags,
+    staleTime: 60_000,
+    gcTime: 300_000,
+    retry: 0,
+  });
+
+  // While loading or on error, default to all-on so the assistant
+  // surfaces don't flicker out and back in.
+  return query.data?.assistant ?? DEFAULT_ASSISTANT_FLAGS;
+}